PRAXIST 文档治理与构建体系:一事实一所有者的 Documentation Policy 深度解读

原创2026-10-11 23:55:401,739 阅读
文章标签:人工智能AI Agent多智能体自主智能体深度研究Agent 编排Agent 工作流AI 技能机器学习MCP 服务

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 负责创建四类产物:

  1. 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 下断言渲染结果完全一致。
  2. docs/reference/skills.md:从技能 front matter 生成。render_skills_reference() 遍历 skills/*/SKILL.md,解析 YAML front matter 中的 name 与 description,输出「Skill | Invoke in Codex | Purpose」目录表,每行标注源文件路径;缺少 name 或 description 会直接抛错。
  3. site/llms.txt:紧凑的机器可读地图(compact machine-readable map)。generate_llm_exports() 按 mkdocs.yml 的导航顺序逐页提取首段文字,生成 - 标题: 摘要 形式的条目。
  4. 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 直接检索与引用。

登录后查看全文
PRAXIST