AtomDocs

AtomDocs 是本地优先的可执行文档编译器。它把组织 Know-how 编译为可验证、可复核、可交付的版本化能力单元。

AtomDocs 使用一条确定性的四层编译路径：

1. Ingestion：访问、解析、切分并归一化来源，输出带来源定位的 JSON Record Sequence；
2. Data：通过 Pydantic Model 校验 Record，形成带 Field 合同与 fingerprint 的 Instance；
3. Composition：把 Template Block Definition Graph 经 Slot Binding 实现为 Content Block Graph；
4. Publication：Renderer 根据 Content 与 Profile 构造 Target Document，通过资格检查后写出 Artifact。

Quality Gate 横跨四层；未绑定 Slot、无效引用、无效 Graph、Capability 不匹配或无效 Target Document 都会阻塞构建。

当前版本为 alpha，公共合同仍可能在正式版前调整。

仓库结构

products/atom-docs/core/       atomdocs SDK 与本地编译实现
products/atom-docs/cli/        atomdocs-cli distribution
plugins/markdown-renderer/     独立 Markdown Publication Backend
fixtures/compiler-project/     最小可运行项目与测试夹具
docs/                           入门和编译架构

Core 与 CLI 保持独立目录、构建元数据和 wheel。Renderer 是独立 Publication Backend，不进入 Core 或 CLI。

开始使用

需要 Python 3.14+ 与 uv。

uv sync --locked --all-packages
uv run atomdocs validate fixtures/compiler-project
uv run atomdocs build fixtures/compiler-project

构建结果写入 fixtures/compiler-project/output/。更多信息见入门指南和编译器正向架构。

验证

uv run pytest \
  products/atom-docs/core/tests \
  products/atom-docs/cli/tests \
  plugins/markdown-renderer/tests

License

MIT