Skip to content

Commit 82abdfd

Browse files
IndenScaleIndenScale
committed
Publish AtomDocs alpha
0 parents  commit 82abdfd

57 files changed

Lines changed: 15287 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
8+
permissions:
9+
contents: read
10+
11+
jobs:
12+
test:
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v4
16+
- uses: astral-sh/setup-uv@v6
17+
with:
18+
python-version: "3.14"
19+
enable-cache: true
20+
- run: uv sync --locked --all-packages
21+
- run: uv run pytest

‎.gitignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
.venv/
2+
__pycache__/
3+
.pytest_cache/
4+
*.py[cod]
5+
*.egg-info/
6+
build/
7+
dist/
8+
fixtures/**/.atomdocs/
9+
fixtures/**/output/

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Atomics Laboratory Contributors
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
<p align="center">
2+
<img src="design/identity/atomdocs-lockup-primary.svg" alt="AtomDocs" height="48">
3+
</p>
4+
5+
# AtomDocs
6+
7+
AtomDocs 是本地优先的可执行文档编译器。它把组织 Know-how 编译为可验证、可复核、可交付的版本化能力单元。
8+
9+
AtomDocs 使用一条确定性的四层编译路径：
10+
11+
1. **Ingestion**：访问、解析、切分并归一化来源，输出带来源定位的 JSON Record Sequence；
12+
2. **Data**：通过 Pydantic Model 校验 Record，形成带 Field 合同与 fingerprint 的 Instance；
13+
3. **Composition**：把 Template Block Definition Graph 经 Slot Binding 实现为 Content Block Graph；
14+
4. **Publication**：Renderer 根据 Content 与 Profile 构造 Target Document，通过资格检查后写出 Artifact。
15+
16+
Quality Gate 横跨四层；未绑定 Slot、无效引用、无效 Graph、Capability 不匹配或无效 Target Document 都会阻塞构建。
17+
18+
> 当前版本为 alpha，公共合同仍可能在正式版前调整。
19+
20+
## 仓库结构
21+
22+
```text
23+
products/atom-docs/core/ atomdocs SDK 与本地编译实现
24+
products/atom-docs/cli/ atomdocs-cli distribution
25+
plugins/markdown-renderer/ 独立 Markdown Publication Backend
26+
fixtures/compiler-project/ 最小可运行项目与测试夹具
27+
docs/ 入门和编译架构
28+
```
29+
30+
Core 与 CLI 保持独立目录、构建元数据和 wheel。Renderer 是独立 Publication Backend，不进入 Core 或 CLI。
31+
32+
## 开始使用
33+
34+
需要 Python 3.14+ 与 [uv](https://docs.astral.sh/uv/)。
35+
36+
```bash
37+
uv sync --locked --all-packages
38+
uv run atomdocs validate fixtures/compiler-project
39+
uv run atomdocs build fixtures/compiler-project
40+
```
41+
42+
构建结果写入 `fixtures/compiler-project/output/`。更多信息见[入门指南](docs/atomdocs/getting-started.md)和[编译器正向架构](docs/architecture.md)。
43+
44+
## 验证
45+
46+
```bash
47+
uv run pytest \
48+
products/atom-docs/core/tests \
49+
products/atom-docs/cli/tests \
50+
plugins/markdown-renderer/tests
51+
```
52+
53+
## License
54+
55+
[MIT](LICENSE)

‎design/identity/atom-mark-primary.svg‎

Lines changed: 14 additions & 0 deletions
Loading

‎design/identity/atomdocs-lockup-primary.svg‎

Lines changed: 22 additions & 0 deletions
Loading

‎docs/architecture.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
# AtomDocs 编译器正向架构
2+
3+
本文只定义 [[AD-ATOMDOCS|AtomDocs]] Core、CLI 与 Renderer 的本地编译架构。AtomLab 产品体系、
4+
AtomStudio 文档工程环境和 AtomPage 可执行文档运行时的职责关系以
5+
[工程认知资产入口](README.md)与 UL/PRD 为准；它们不是本架构的第五层。
6+
7+
## 产品本质
8+
9+
AtomDocs 在一个本地进程中把版本化领域数据和内容定义编译为目标格式产物。文件系统保存项目
10+
资产，Python distribution 提供领域与格式下游；系统不拥有数据库、队列、控制面或在线状态。
11+
12+
## 四层编译模型
13+
14+
```text
15+
Ingestion Source --Connector--> JSON Record Sequence
16+
Data Record --Class--> Object
17+
Composition Authoring Source + Slot Binding --realize--> Content Block Graph
18+
Publication Content + Presentation Profile --Renderer--> Target Document --> Artifact
19+
20+
Quality Gates ──────────────── check every boundary ──────────────────────────▶
21+
```
22+
23+
Quality Gate 横跨四层，不是 `Policy` 或第五个编译阶段。任一 Gate 失败时，当前构建不写出正式
24+
Artifact。
25+
26+
### Ingestion
27+
28+
Dataset 聚合本地文件或 Virtual Source。Connector 负责访问、解析、切分、Payload 映射与来源定位，
29+
统一输出带 Record ID、Class ID、Payload 和 Source 引用的 JSON Record Sequence。API、数据库、
30+
数据湖和数据仓可以按页、游标、查询或分区读取，不要求完整 dump；无法提供稳定版本的上游必须
31+
标记为 volatile。Source 在层内按需暴露 Parseable Resource，但它不是跨层合同。既有 Artifact
32+
只有经 Evidence Bundle 校验并显式声明为 Artifact Source 才能再接入。Ingestion 只验证 Record
33+
Envelope，不执行 Class 或 Field Validator。
34+
35+
### Data
36+
37+
Data 只消费 JSON Record Sequence，不读取 Dataset、Source 或 Connector。Domain Plugin 暴露
38+
Pydantic Class；Core 把 `model_fields` 描述为 Input Field，把 `@computed_field` 描述为
39+
Computed Field；Record 反序列化后形成带 Class 身份和内容 fingerprint 的 Object。Content
40+
只能通过 Typed Slot 读取声明 Field。显式类型引用投影为确定性 Object Graph，不根据字符串
41+
相等猜测关系。
42+
43+
Domain Data Contract 描述一次构建所接收的版本化静态快照。Class / Field 属于抽象定义层，
44+
Object / Property 属于运行时值层；Object 内部的无副作用确定性派生由 Computed Field 定义并
45+
形成 Computed Property。跨 Object 或跨来源的交付判断进入 pytest Policy。Core 不建模命令、
46+
对象状态迁移、生命周期或业务流程执行；文档可以描述这些概念，但 Compilation 不执行它们。
47+
48+
### Composition
49+
50+
Block Tree / Markdown 是 Template Source Adapter，不是 Content IR。Adapter 先建立 Template：
51+
Slot 定义和由 Block Definition 构成的有根 Block Graph；Wiki Link / Reverse Wiki Link 声明
52+
结构化取值，列表项与表格行在 Source 中显式存在。随后 Slot Binding 把 Object / Property 绑定到 Slot，
53+
Fixed / Parametric Definition 与显式 Generated Definition 实现为不可变 Content Block Graph。
54+
Media 是 Block kind，其本地 Resource 在本层解析并记录 fingerprint。Block 保留
55+
Definition、父节点、顺序、语义角色、Binding 与实现值，Outline 只从实际 heading Block 投影。
56+
57+
Authoring 以可追溯性为核心，用少而精的 Markdown 直接写作塑造文章流向，并显式区分原文引用、
58+
Resource 引用、结构化引用和制导生成。Material 原文通过 Material Fragment 身份与 Source
59+
locator 进入 Content，不为复述正文而先转换为 Object；结构化值沿 Property、Object、Record、
60+
Connector Run 追踪到 Source。Draft 可以从 Template 初始化；Template 通常是稳定真实 Draft 的
61+
后补抽象，保存结构、Slot、引用规则、Resource 需求与 Generation Spec，不保存项目 Binding 或
62+
Generation Result。
63+
64+
Generated Block 只接受显式 Block Tree Source 中的 heading/paragraph 叶定义；Core 使用
65+
Generation Scope 向 Generator 暴露闭合的 Slot、既有 Block、Resource 与 Diagnostic，并在
66+
验证输出合同、Evidence Binding 和可选复核后实现 Block。Source 不包含可执行的结构控制语句，
67+
也不能形成第二套 IR。
68+
69+
### Publication
70+
71+
一个 Project 可以声明多个 Presentation Profile。Profile 选择 Target Format、Renderer、输出、
72+
可选 Presentation Template、Style Binding、Semantic → Physical Style 映射、Layout 和后端参数。
73+
Core 先形成带 fingerprint 的 Target Lowering，Renderer 只消费 Content、Profile 与 Lowering，
74+
再构造内存 Target Document；Core 在 Capability、Lowering、Target Format、syntax payload 与
75+
fingerprint Gate 通过后，才原子写入 Artifact。
76+
77+
Artifact 记录 Content、Profile、Renderer、Presentation Template 与输出 fingerprint。同一 Content
78+
因此可以在一次构建中产生 Markdown 与 DOCX，而不由任何后端读取 Record 或 Template Source。
79+
成功构建还写出包含 Source、Run、Record、Object Graph、Slot、Lowering、Target、Artifact 与
80+
Diagnostic 的 Build Evidence Bundle。
81+
82+
## 分发边界
83+
84+
| Distribution | 责任 |
85+
|---|---|
86+
| `atomdocs` | Ingestion、Data、Composition、Publication 合同，编译编排与插件协议 |
87+
| `atomdocs-cli` | 只把终端调用适配到 Core 顶层公开 API |
88+
| `atomdocs-markdown-renderer` | Markdown Target Syntax Backend |
89+
| `atomdocs-docx-renderer` | WordprocessingML reference-template Backend |
90+
91+
Markdown 与 DOCX 都通过 `atomdocs.renderers` entry point 发现。Core 不包含生产格式 Renderer；CLI
92+
不依赖具体后端。
93+
94+
Publication 只负责把 Content 实现为本地 Artifact。上传、发送、上线或同步到外部渠道属于
95+
Distribution，不是 AtomDocs 编译层职责。
96+
97+
## 当前稳定变化点
98+
99+
| 变化 | 权威资产 |
100+
|---|---|
101+
| 来源访问、提取与归一化 | Dataset + Source + Connector |
102+
| 领域数据合同 | Domain Plugin Class |
103+
| 类型、Field 与固有不变量 | Domain Plugin Class |
104+
| 内容结构和实现规则 | Template Source → Template Graph |
105+
| 作者正文、引用与制导生成声明 | Draft / Template Authoring Source |
106+
| Object / Property 到 Slot 的绑定 | Project Manifest Slot Binding |
107+
| 可变业务规则 | pytest Policy + YAML |
108+
| 目标格式、Style 与 Layout | Presentation Profile + Renderer Backend |

0 commit comments

Comments
 (0)