PRAXIST 文档治理与构建体系:一事实一所有者的 Documentation Policy 深度解读
PRAXIST 文档治理与构建体系:一事实一所有者的 Documentation Policy 深度解读
本文系统解读 PRAXIST 开源仓库中 docs/about/documentation.md 所定义的文档治理(Documentation Policy):它规定
docs/下带版本管理的 Markdown 是唯一的产品文档事实源,用「一份事实、一个所有者」的契约表解决文档重复与漂移问题,并借助scripts/build_docs_site.py、mkdocs.yml与 CI 工作流完成参考页生成、导航校验、LLM 导出与托管发布。读完本文,你将掌握 PRAXIST 文档体系的完整架构、全部所有权归属、本地构建命令与发布开关,以及背后由源码和测试锁定的自动化契约。
为什么需要文档治理:单一事实源原则
PRAXIST 的产品文档体量很大——CLI、技能(Skills)、任务项目(Task Projects)、研究循环(Research Loop)、成本模型、隐私政策等分散在不同主题下。如果每个页面都各自复述一遍「安装命令」或「CLI 参数」,很快就会出现互相矛盾、新旧并存的局面。为此,docs/about/documentation.md 开门见山地确立了一条硬性规则:
docs/下带版本管理的 Markdown 是唯一被编写(authored)的产品文档来源;- 静态站点、生成的参考页(reference pages)、搜索索引、
llms.txt与llms-full.txt全部是从这份来源派生出来的产物; - PRAXIST 不使用单独维护的 GitHub Wiki——Wiki 天然容易脱离代码仓库、失去版本管理,因此被明确排除。
这意味着所有人工写作集中在 docs/ 目录,其余输出全部可由构建脚本重新生成。任何对文档内容的修改都必须落在 docs/ 下的 Markdown 源文件上,而不是去改生成产物。
从源码侧可以进一步印证这套单向派生关系:在 pyproject.toml 中,[tool.hatch.build.targets.wheel.force-include] 把 docs、skills、templates、scripts 一并打进 wheel 包的 praxist/resources/docs 等资源目录,因此即使用户不构建站点,也能通过包资源读到这些文档源;而生成 HTML 与 LLM 导出物(site/ 目录)则从不提交进仓库。
一事实一所有者:全量所有权矩阵
文档政策的核心机制是一张「信息 → 唯一所有者 → 其他页面可做什么」的契约表。每一类信息都指定唯一的权威所有者页面;其他页面允许的行为只有「链接到所有者」,最多在解释自身行为时做必要限度的概括,严禁重复陈述完整契约。
下表完整继承自 docs/about/documentation.md,所有链接已转换为从仓库根目录出发的全局相对路径:
| 信息 | 唯一所有者 | 其他页面可以 |
|---|---|---|
| CLI 参数与默认值 | praxist.cli 解析器代码(praxist/cli/init.py) |
链接到生成的 CLI 参考页 docs/reference/cli.md |
| 技能名称与激活描述 | 各 skills/*/SKILL.md 的 front matter(如 skills/praxist-control/SKILL.md) |
链接到生成的 Skills 参考页 docs/reference/skills.md |
| 包安装、安装命令与文件系统影响 | docs/getting-started/installation.md | 链接;根落地页可展示一条权威安装命令 |
| 面向用户的首次运行/OOBE 流程 | docs/getting-started/quickstart.md | 指明路线(lane)并链接 |
| Agent 托管 OOBE 实现 | docs/agents/oobe-install.md | 链接,不复制 agent 指令 |
| 项目前置条件、研究简报与 takeover 阶段 | docs/getting-started/first-task.md | 展示一次 takeover 调用并链接 |
| 目标到技能的映射与技能安装位置 | docs/user-guide/skills.md | 点名相关技能并链接 |
| 任务 schema、优先级与科学所有权 | docs/guides/task-projects.md | 解释机制如何消费任务契约 |
| 模板/示例的区分与示例落地命令 | docs/guides/examples-and-templates.md | 识别资产并链接,不重新定义边界 |
| Rocket Booster Recovery 科学细节 | examples/rocket_booster_recovery/README.md | 解释发现与启动,不复制其协议 |
| Rocket Booster Recovery(Rust)科学细节 | examples/rocket_booster_recovery_rust/README.md | 解释发现与启动,不复制其协议 |
| 生命周期语义 | docs/guides/operators.md | 展示一条 quickstart 命令并链接 |
| 核心/插件/任务边界与产物角色 | docs/concepts/architecture.md | 概括目的并链接 |
| 配置入口与优先级 | docs/concepts/config_discipline.md | 陈述一个本地输入并链接 |
| Agent 会话与 prompt 布局心智模型 | docs/concepts/runtime-model.md | 解释特定机制的影响并链接 |
| 运行时适配器能力 | docs/guides/agent-runtimes.md | 指明所选运行时并链接 |
| API 提供商形态 | docs/guides/model-providers.md | 指明所选提供商并链接 |
| 开源模型 API 候选清单与选型标准 | docs/guides/open-source-model-apis.md | 链接,不复制候选清单 |
| 认证与凭证优先级 | docs/guides/credentials.md | 陈述前置条件并链接 |
| 研究循环序列 | docs/guides/research-loop-variant-generation-flow.md | 引用阶段,不重新定义序列 |
| 成熟度、close、incubator、peer 混配与 launch-freeze 行为 | docs/guides/research-loop-flexibility-controls.md | 仅在 Task Projects 拥有组合画像处展示任务配置 |
| Deep Innovation Gate(DIG)行为与产物 | docs/guides/deep-innovation-gate.md | 陈述 DIG 是否激活并链接 |
| Quality-Diversity(QD)分配 | docs/guides/qdig-cohort-allocator.md | 引用所选路径并链接 |
| Peer 会话记忆 | docs/guides/peer-local-structured-memory-long-context.md | 将记忆视为上下文并链接 |
| 实验准入与资源所有权 | docs/guides/central-resource-scheduler.md | 陈述所选 profile 并链接 |
| 工具目录与 frontier-tool 行为 | docs/guides/tool-servers.md | 点名工具并链接 |
| 文献来源/出处策略 | docs/guides/scientific-literature-lookup.md | 陈述查找是否启用并链接 |
| 人类可读报告触发条件与语义 | docs/guides/user-facing-reports-and-init.md | 链接到生成的报告或本指南 |
| 用量测量与公式 | docs/guides/costs.md | 链接到测量产物与本指南 |
| 无损 token 节省机制 | docs/guides/cost-optimization.md | 陈述某路径使用该策略并链接 |
| 贡献者契约 | AGENTS.md | 链接,不重新定义 |
| 软件许可证 | 根目录 LICENSE.md | 链接,不复述许可条款 |
| 用户协议 | docs/legal/user-agreement.md | 链接,不复述法律条款 |
| 产品用量隐私政策、处理目的、保留期与用户权利 | docs/legal/PRIVACY.md | 链接,不复述政策 |
| 精确的带版本产品用量同意文本 | docs/legal/product-usage-data-notice.md | CLI 加载同一包资源;其他页面识别并链接 |
| 产品用量同意命令与收集器操作 | docs/operations/product-usage.md | 链接到操作流程 |
| 产品用量实现、端点、存储与审计映射 | docs/operations/DOCUMENTATION.md | 链接,不复制实现细节 |
| 机器产品用量事件 schema | praxist/product_usage/protocol.py 与已检入的 JSON Schema | 技术与法律页面解释契约;精确校验以代码为准 |
| 托管文档 URL | praxist.cli.docs.DOCUMENTATION_URL(praxist/cli/docs.py) |
在包/站点元数据中镜像并链接 |
这张矩阵的价值在于:任何一条事实都只有一个修改入口。想改 CLI 参数说明,只能改 argparse 解析器后重新生成参考页;想改技能描述,只能改对应 SKILL.md 的 front matter。测试层面对此也有强制校验——tests/hardening/test_documentation_contracts.py 中 test_contributor_docs_cover_current_boundaries 会断言 AGENTS.md、docs/guides/contributing.md、docs/guides/operators.md 等一批必需文档存在且被 mkdocs.yml 收录。
页面类型分工:教程、指南、概念、参考与首页定位
文档政策同时给四种页面类型划定了职责,避免「每页都写成迷你手册」:
- 教程(Tutorials):按顺序串起操作动作(sequence actions);
- 指南(Guides):解释过程(explain procedures);
- 概念(Concept pages):解释心智模型(explain mental models);
- 参考(Reference pages):枚举机器契约(enumerate machine contracts);
- 根目录 README:是产品落地页(product landing page),不是第二本手册。
配套的「最小命令」规则约束了教程的写作尺度:教程里可以出现它确实需要的那一条命令,但该命令的参数、默认值与边界情形必须留在生成的参考页中;任何页面若要概括相邻契约,只能概括到足以解释自身行为的程度,并且必须链接到所有者而不是复述契约。
在 tests/unit/test_documentation_site.py 中,test_key_documentation_contracts_have_one_owner 进一步把这一原则落成了可执行断言:例如 literature_search(query, sources, max_results) 只能出现在 docs/guides/scientific-literature-lookup.md,uncached_input_tokens = input_tokens 只能出现在 docs/guides/costs.md,PRAXIST_CONTEXT_EFFICIENCY_MODE 只能出现在 docs/guides/cost-optimization.md,出现多处即测试失败。
生成产物:build_docs_site.py 与四类输出
文档政策明确指出,scripts/build_docs_site.py 负责创建四类产物:
docs/reference/cli.md:从活的 CLI 解析器(live CLI parser)生成。源码中render_cli_reference()调用praxist.cli._build_parser()(定义于 praxist/cli/init.py),遍历argparse的 subparsers,把每个命令的 usage、帮助文本、Choices与Default渲染为确定性 Markdown 表格;_stable_usage()固定 100 列宽度渲染 usage,使输出与终端宽度无关——对应的test_cli_reference_is_independent_of_terminal_width测试会分别在COLUMNS=40与COLUMNS=220下断言渲染结果完全一致。docs/reference/skills.md:从技能 front matter 生成。render_skills_reference()遍历skills/*/SKILL.md,解析 YAML front matter 中的name与description,输出「Skill | Invoke in Codex | Purpose」目录表,每行标注源文件路径;缺少name或description会直接抛错。site/llms.txt:紧凑的机器可读地图(compact machine-readable map)。generate_llm_exports()按mkdocs.yml的导航顺序逐页提取首段文字,生成- 标题: 摘要形式的条目。site/llms-full.txt:按导航顺序拼接的完整语料(complete navigation-ordered corpus),每个页面以<!-- Source: 相对路径 -->注释标记来源。
政策还规定了两条提交纪律:生成的 HTML 与 LLM 导出物不提交;生成的 Markdown 参考页要提交,这样包用户不构建站点也能阅读,但 CI 必须验证它们与代码持有的输入精确一致。这正是 --check-generated 参数存在的意义:write_generated_reference_docs(check=True) 会比较提交版与实时生成版,发现任何差异都会列出 stale 文件并报错。此外,generate_llm_exports() 会把 llms.txt/llms-full.txt 同时写入 site/ 与 site/docs/ 两个位置(测试 test_llm_exports_are_derived_from_navigation_order 用临时目录验证了两处内容完全相等)。
导航所有权:mkdocs.yml 一张清单
「导航所有权」(Navigation Ownership)是文档治理的第二条支柱:每一篇手工编写的 Markdown 页面必须且只能出现在 mkdocs.yml 的 nav 中恰好一次。这样每个页面的主要受众与信息角色都是显式的。
构建脚本的 validate_docs_sources() 会执行四类静态校验:
- 检测
nav中的重复页面路径; - 检测
nav指向但磁盘上不存在的目标; - 检测
docs/下存在但未被nav认领的源页面; - 检测损坏的本地链接:解析每个 Markdown 链接目标,跳过锚点(
#...)与绝对 URL,解析后若目标位于docs/之外(outside docs)或文件不存在,一律报错。
对应测试 test_navigation_owns_every_source_page_once_and_links_resolve 断言:nav 中的页面集合与 docs/ 下递归发现的全部 .md 文件集合完全相等且无重复。而 mkdocs.yml 本身还开启了 strict: true,让 MkDocs 在严格模式下构建——任何警告都会升级为失败,进一步收紧发布质量。
本地构建与校验命令
文档政策给出的本地构建命令如下(从仓库根目录执行):
uv sync --extra docs
uv run python scripts/build_docs_site.py
uv run python scripts/build_docs_site.py --check-generated
各步骤含义:
uv sync --extra docs:安装文档构建依赖。docs可选依赖组定义在 pyproject.toml 中:mkdocs-material>=9.7,<10与mkdocstrings[python]>=1.0,<2。test_docs_dependencies_have_one_project_owned_definition还断言docs/requirements.txt不存在——依赖只允许由 pyproject 这一处定义。- 第一次运行
build_docs_site.py:生成/刷新docs/reference/cli.md、docs/reference/skills.md,执行导航与链接校验,随后调用mkdocs build --strict生成静态站点,最后生成 LLM 导出并规范化文本产物(_normalize_generated_site会去除尾随空白,保持 git diff 可控)。 - 带
--check-generated运行:只校验、不重写、不构建。main()中该分支在validate_docs_sources()后直接返回,用于 CI 确认已提交的参考页没有过期。
政策特别强调:构建全程运行在严格模式(strict mode)下,不联系 API 提供商、不读取 API 密钥、不启动任何研究服务。也就是说,文档构建是纯离线、确定性的过程,任何人都可以在无网络凭证的环境中安全执行。
托管文档与发布流程
CI 校验与私有 GitHub Pages 发布
文档政策规定:每次 pull request 与每次 push 到 main 都会运行文档校验;成功推送到 main 后,生成的站点会发布到仓库的私有 GitHub Pages 项目。访问遵循仓库的读权限并需要 GitHub 认证;生成的 HTML 始终是派生产物,不提交到仓库。
发布开关是仓库变量 PRAXIST_PAGES_ENABLED=true,维护者还可以手动触发 docs 工作流(workflow_dispatch)。Pull request 只构建并校验完整站点,绝不发布——PR 阶段是纯验证通道。
工作流实现见 .github/workflows/docs.yml:build 任务执行 uv sync --extra docs → uv run python scripts/build_docs_site.py → uv run python scripts/build_docs_site.py --check-generated 并对 docs/reference/cli.md、docs/reference/skills.md 跑 git diff --exit-code;只有在 push 或 workflow_dispatch 且 vars.PRAXIST_PAGES_ENABLED == 'true' 时才上传 Pages artifact;deploy 任务依赖 build,声明 pages: write 与 id-token: write 权限后调用 actions/deploy-pages@v4。test_docs_workflow_builds_and_deploys_only_derived_output 与 test_documentation_urls_follow_release_contracts 分别锁定了工作流的这些关键分支与 URL 契约。
praxist docs:规范 URL 的暴露入口
托管文档的规范 URL 统一通过 praxist docs 命令暴露,定义于 praxist/cli/docs.py:模块级常量 DOCUMENTATION_URL 持有规范地址,同时支持两个覆盖/控制点:
- 环境变量
PRAXIST_DOCS_URL可覆盖默认 URL; --no-open参数只打印 URL 而不尝试打开浏览器。
cmd_docs 还会调用 _can_open_browser() 做细致的开浏览器判定:检测到 PRAXIST_DOCS_NO_OPEN、CI、SSH_CONNECTION/SSH_TTY 时直接拒绝打开;Linux 下要求存在 DISPLAY 或 WAYLAND_DISPLAY。这样在 CI 或远程会话中 praxist docs 永远只会打印 URL,不会误弹浏览器。README 也据此明确写有「No local documentation server is required.」——即不要求本地文档服务器,使用 praxist docs 即可直达托管站点(docs/index.md 的「Find a Specific Answer」区同样把 <a href="https://link.gitcode.com/i/e853c6c2ab0962d367fa0fcc67797496" target="_blank">Documentation Policy</a> 列为各契约所有者的入口)。
质量保障:测试如何守护文档契约
PRAXIST 把文档治理落实为可重复执行的自动化契约,主要分两层:
单元契约层(tests/unit/test_documentation_site.py):
test_generated_references_match_live_cli_and_skill_metadata:提交的docs/reference/cli.md与docs/reference/skills.md必须与generated_reference_docs()的实时输出逐字节一致;test_navigation_owns_every_source_page_once_and_links_resolve:导航所有权与链接完整性;test_documentation_is_english_only:所有docs/、skills/、templates/、examples/下的 Markdown 不得包含 CJK 字符,也不得存在.zh-CN本地化副本——保持单一语言事实源;test_authored_docs_do_not_duplicate_long_paragraphs:剔除法律页与生成参考页后,任何 180 字符以上的段落不得跨页面重复出现,从内容层面对抗「复述契约」;test_documentation_header_uses_the_vector_logo、test_readme_uses_the_praxist_banner、test_documentation_favicon_uses_the_standalone_vector_mark:站点 Logo、favicon 等品牌资产的存在性与 viewBox 契约。
加固契约层(tests/hardening/test_documentation_contracts.py):
test_public_top_level_python_api_has_docstrings:praxist、templates/tasks、scripts下所有公开的顶层函数/类必须带 docstring——公开 API 的文档义务由测试强制;test_public_docstrings_are_stable_contract_text:docstring 中不得出现R\d+、Round N、2024-xx-xx run这类补丁式注记,保证 docstring 是稳定的契约文本而非变更日志;test_contributor_docs_cover_current_boundaries:必需文档清单必须存在,且AGENTS.md必须包含python -m praxist.run、--task-path、praxist/plugins、Result Preservation Principle、PromptLayout V1、python scripts/build_docs_site.py等关键锚点。
小结:一套「代码级」的文档治理闭环
PRAXIST 的 Documentation Policy 本质上把文档治理变成了软件契约:docs/ 是唯一事实源,所有权矩阵是人工可读的职责划分,scripts/build_docs_site.py 是确定性生成器,mkdocs.yml 是导航所有权清单,CI 工作流与两层测试则是持续执行的守门员。对贡献者而言,改文档的正确姿势是:找到所有权矩阵里的唯一所有者 → 修改对应 Markdown 源或代码/技能 front matter → 运行 uv run python scripts/build_docs_site.py --check-generated 确认参考页未过期 → 提交。这套闭环保证了任何时刻的文档、CLI、技能与代码彼此严格一致,也让 llms.txt/llms-full.txt 成为可信的机器可读语料,供搜索引擎、Agent 与 LLM 直接检索与引用。