Skip to main content

文档知识体系

Asset
ADP-KNO-FEAT-DOC-0013
Feature
docs-knowledge-system
领域
knowledge-governance
作用域
application-level
文档状态
draft
产品生命周期
active
文档 Owner
DOC
事实源
canonical-docs
工程 Owner
DOC
Development Ready
not-ready
更新
2026/10/14

FEATURE DEVELOPMENT PACKAGE

工程就绪状态

工程 Owner：DOC · 仓库：CDX / CLD / DOC / WSC

BLOCKED
development · not ready
  • 原子需求与验收
  • 设计与工程合同
  • 代码与仓库定位
  • 里程碑与工作包
  • 验证计划
  • 无阻断决策
verification · not ready
  • Development Ready 已通过
  • 验收标准已覆盖
  • 正式测试已登记
  • Fixture 与环境已定义
  • 测试规格已物化到正式测试
release · not ready
  • Verification Ready 已通过
  • 实现修订可定位
  • 发布证据已登记
  • 兼容与迁移已定义
  • Runbook 与回滚已定义
查看阻断项（3）
  • Development Ready 缺少：原子需求与验收
  • Development Ready 缺少：里程碑与工作包
  • Development Ready 缺少：验证计划
查看完整 readiness查看关联资产

功能目标​

让 Producer、Project Workspace Codex 和成员 repo owner 从同一套稳定文档理解 Plane 产品合同， 同时把项目路由、实现、运行事实和一次性 evidence 留在各自 owner 中。文档按总策划案、功能总表、 功能详细策划案三层组织，并通过任务导向的指南、标准和运行入口提供跨功能导航。

功能结论​

主题结论
Producer 入口从本站总览或功能库进入目标 Feature，再按权威链接进入 Project Workspace、实现或运行 evidence。
可见结果每个 Feature 有唯一 canonical 页面、明确成熟度、稳定合同、差距、owner 和验证入口。
系统保证Project Workspace 只保存项目身份与路由；docs repo 只保存长期文档；成员 repo 和外部系统分别保存实现与现场事实。
明确不做不在 docs repo 复制 Project Workspace 配置、成员 repo 规则、运行状态、一次性报告、阶段方案或临时环境信息。
事实源 / ownerplatform-docs 拥有文档源码与站点发布；AutoDev Platform Project Workspace 拥有 repo registry 与执行路由。
当前成熟度三层规划包、导航校验和 docs 发布已存在；引用完整性与重复事实检查仍需持续加强。

当前落地状态、已批准合同与差距​

  • 当前落地状态：plane-product-features-v1 已作为 canonical planning package； sidebar-navigation.json 驱动 sidebars.js，仓库具备导航测试、内容合同测试、Docusaurus build、 不可变 release 发布和只读发布日志。
  • 已批准合同：AutoDev Platform Project Workspace 是 control plane；platform-docs 是 knowledge/planning plane；实现与配置由 .autodev/repos.yaml 注册的成员 repo 或 non-repo surface 持有。
  • 当前差距：部分 Feature 仍是 stub，部分页面仍需补齐统一内容合同；路径引用、重复事实和 易变 evidence 扫描需要固定回归测试。
  • 后续交付：在每次实质内容维护时收敛对应 Feature，并扩展 repo-local validator；不建立 第二套项目模板、agent 配置或路由 registry。

用户与责任​

角色 / surface责任不拥有
Producer阅读、评审并批准长期产品合同实现代写、运行激活或凭据操作
Project Workspace Codex解析 canonical docs、repo registry、owner 和 review gate文档副本、运行真相或跨项目批准
platform-docs文档源码、导航、构建、发布合同和 docs review evidencePlane 业务状态、Automation execution 或成员 repo 实现
Plane工作意图、业务状态和声明的 Automation truth长期规划正文或本地 repo 路径
成员 repo / Integration owner代码、配置、测试、runbook 和 repo-local delivery policyPlatform 产品合同的第二份正文
GitLab、TeamCity、Runtime、QA当前 refs、build、deploy、health 和验收 evidencecanonical 产品策划

文档分层​

三层规划包​

  • index.md：产品范围、对象层级、跨 Feature 边界和阅读入口。
  • feature-map.md：Feature inventory、主作用域、成熟度和详细页链接。
  • features/*.md：稳定产品合同、当前落地、差距、接口、异常、验证和 owner。
  • manifest.yaml：模块与页面的机器索引。
  • _support/：仅供校验器和机器流程使用，不进入 Docusaurus 主导航。

同一产品事实只在一个 Feature 页面定义。相邻页面只记录依赖和相对链接，不复制状态机、字段或 权限规则。

稳定入口​

docs/guides/、docs/standards/ 和 docs/operations/ 只提供跨功能、低波动的任务顺序：何时使用、 开始条件、操作顺序、完成标准、停止条件和权威链接。具体状态机、schema、repo-local 命令和运行 参数必须留在 owning Feature、repo policy 或 evidence surface。

docs/operations/release-log.md 是唯一生成型入口。它只读展示本站成功 production publication facts，不是人工新闻页，也不是其它 Platform 组件的 release truth。

功能页面内容合同​

进入实质维护范围的 features/*.md 应在“功能目标”后提供“功能结论”表，至少覆盖：

  • Producer 入口；
  • 可见结果；
  • 系统保证；
  • 明确不做；
  • 事实源 / owner；
  • 当前成熟度。

正文按功能需要描述当前落地状态、已批准合同、差距、后续交付、责任、流程、规则、接口、异常和 验证。stub 必须明确未知项；文档存在不等于功能已实现、已部署或已验收。

一次性日期、测试 UUID/IP/端口、具体 MR/账号、临时 env/命令和 activation 结果不进入长期正文。 需要追溯时引用 owning Plane、Git、TeamCity、Runtime 或 QA evidence；完成后的报告与阶段方案通过 Git 历史保留，不在当前文档树继续参与检索和上下文加载。

导航与发布​

sidebar-navigation.json 是人工维护的 docsSidebar source of truth。repo-local generator 必须：

  1. 验证总策划案、功能总表、全部 Feature 页面和已登记稳定入口可达；
  2. 验证 sidebar label 与页面 frontmatter 一致；
  3. 拒绝重复 doc id、缺失页面和未登记 evidence 页面；
  4. 生成 sidebars.js，不得人工维护两份不同导航。

写入使用 fresh-base branch、MR、测试和 Producer review。Producer 合并 docs MR 到受保护 master 后，owning CI 才可发布该 merge commit；branch push、MR 创建或未合并 pipeline 都不授权 production publication。详细流程由发布流程和 发布日志持有。

使用流程​

产品讨论或已批准决策
  -> 更新唯一 canonical Feature 页面
  -> 必要时更新 feature map、manifest 或稳定入口
  -> 更新 sidebar-navigation.json
  -> 生成并验证 sidebars.js
  -> 运行合同测试和 Docusaurus build
  -> branch + MR + Producer review
  -> protected master CI 发布本站 release
  -> Project Workspace Codex 在后续任务中读取相关页面

稳定规则​

  • AGENTS.md 和 .codex/ 是 repo 执行指引，不是普通文档页或产品事实源。
  • AutoDev Platform Project Workspace 的 .autodev/repos.yaml 是 docs repo binding 与 owner routing 的唯一项目级 registry；docs repo 不维护副本。
  • docs repo 不保存 Plane Automation command、execution truth、DSH Profile/Application 配置、credential、runtime 操作或 Producer approval。
  • Project Workspace 不保存 planning docs 副本；canonical docs 不可读时必须返回 blocker。
  • 成员 repo 文档可以解释实现，但不能替代 Platform Feature contract。
  • 一次性报告、阶段方案、未登记页面和验证产物不得加入 docsSidebar 或长期正文。
  • 内容重排不得顺带改变状态机、schema、typed API、approval gate、frontmatter、URL 或导航。
  • 发布事实只来自 docs deploy workflow 最终成功的 immutable release；失败 candidate 留在 GitLab pipeline evidence。

Project Workspace Codex 行为​

Project Workspace Codex 在路由任务前读取 root 与 Project Workspace AGENTS.md、 .autodev/repos.yaml、本规划包总览、功能总表和任务相关 Feature 页面。它应记录已解析的 canonical docs repo、owner repo/surface、base branch、principal agent 和 review gate。

任一必需来源不可读、binding 不存在、owner 不明确或 repo-local policy 缺失时，返回可操作 blocker； 不得猜路径、创建文档副本、根据 issue 关键词推断 owner，或绕过 Project Workspace 直接写成员 repo。

数据与接口​

  • Project Workspace registry： /Users/wjai/AutoDev/Projects/AutoDevSystem/.autodev/repos.yaml。
  • Canonical Feature library：docs/capabilities/，结构化目录为 catalog/features.json。
  • Navigation source：catalog/features.json 与 docs frontmatter。
  • Generated navigation data：sidebar-navigation.json。
  • Generated navigation：sidebars.js。
  • Navigation generator：scripts/generate_navigation.py。
  • Catalog contracts：scripts/test_knowledge_catalog.py 与 scripts/validate_knowledge_schemas.mjs。
  • Docs deployment：.gitlab-ci.yml、scripts/deploy_static.py、scripts/serve_static.py。

异常、阻塞与停止条件​

  • canonical docs binding、目标页面或 repo policy 不可读：停止路由并报告缺失来源。
  • 同一事实在多个页面冲突：先确认 owner，再合并到唯一 canonical 页面。
  • 页面移动但 manifest、navigation 或引用未同步：构建失败，不得发布。
  • runtime evidence 被写成长期产品状态：移回 owning evidence surface 后再评审。
  • MR 缺少合同测试或 production build evidence：不得把内容视为可发布。
  • 需要 Runner、credential、生产目录权限或服务 activation：按 Project Workspace 授权交由 owning source / 外部 CI 执行；缺少事实或实际权限时记录具体阻塞。

外部 CI 与权威来源​

npm run generate:catalog
npm run register:navigation
npm run test:contracts
npm run test:deployment
npm run build

本地验证：根据项目策略禁止执行。上列命令仅由外部 CI Runner 执行。

权威入口：

待决策问题​

  1. 是否把跨文档引用完整性和易变 evidence 检测纳入所有 docs MR 的固定 CI？
  2. 长期架构决策应进入对应 Feature，还是增加只收录仍有效决策的独立索引？
Last updated on by source2728