文档管理器
面向人类和AI智能体的活的项目知识。代码是关于如何做以及某项声明是否为真的唯一真实来源。 AGENTS.md + docs/ 捕获内容、原因、决策和计划——但当它们与代码冲突时，绝不覆盖代码。
核心规则
- 优先使用
AGENTS.md作为枢纽。如果agents.md已存在，则使用它。如果只存在CLAUDE.md，要么扩展它以包含文档索引，要么添加AGENTS.md并建立交叉链接——不要创建三个互相竞争的枢纽。 - 每个生成/更新的文档都使用相对 Markdown 链接指回枢纽和相关文档。
- 除非有理由，否则永远不要删除持久性知识；ADR 上优先使用 Superseded by（“已被取代”）注释。
- 不要自动提交或自动推送。将 Git 操作留给用户。
- 生成的内容使用用户的语言（或仓库的主要语言）。此技能正文为英文，以保持生态系统兼容性。
- 优先考虑准确性和实用性，而非数量。先创建核心集；按需提供可选文档。
- 意图优先（项目层级）。 将 Intent 分类为：
integrate|audit|from-zero（以及可选的混合类型）。请参见第0步。纯功能/计划/同步不需要。 - 冲突时代码优先。 未通过结构验证的文档声明将被标记为 Contradicted（矛盾）/ Missing（缺失）——不要为了匹配文档而发明代码；修复或标记文档。
- 整合优先（当 Intent=integrate 时）。 成熟的文档 → 索引 + 差距 + 规范链接；不要并行重写产品愿景/需求/ADR。请参见 adopt-integrate。
- 每个主题一个权威。 每个主题只有一个规范文档；其他所有内容都链接到它。
- 采用/从零开始项目中的覆盖率矩阵。 产品表面（导航、ModuleId、包）显示为已记录/已链接/存在差距。
- 功能原子性。 一个 slug ≈ 一个 ModuleId 或有限上下文。集群 = 索引 + 子项。
- 状态分类法。 references/status-taxonomy.md。
- 沙箱选择加入 / 一流的从零开始。 当用户要求时（
test/等），输出Out: sandbox:path。沙箱枢纽应标明非唯一真实来源 + 晋升计划。 - 功能自动导航（v1.5 / v2）。 简单的“新功能 X”/“documentá X” → 技能选择 计划 vs 功能包，应用默认非写入，设置 Kind（新功能 | 尖峰 | 史诗 | 重新设计）。实现桥梁（位置/存根）仅在选择加入时执行（“implementá”、“存根”、“脚手架”）——默认为仅文档 + 一行提示。请参见 modes.md §3 和 implementation-bridge.md。
- 计划模式（v1.3+）。 新功能创意落在
docs/plans/<slug>/中，而不是伪造的实现包或完整的项目引导。当代码真实存在（不仅仅是存根）时，提升到docs/features/<slug>/。 - ArkGate 桥梁（v1.4）。 如果检测到 ArkGate（
ark.config.json、ark-check、.ark/、ark 技能）或用户刚刚完成一个门，则运行桥梁子流程：从契约丰富清单；门通过后 → 限定范围的同步 / 审计；残留违规 → 将声明标记为 Contradicted（矛盾）/ Partial（部分）——绝不重写文档以掩盖损坏的架构。无 Ark 则无操作。检测到 Ark 时，实现桥梁中的放置提示会重用 Ark 层。请参见 arkgate-bridge.md 和 modes.md §9。 - 知识仪表盘（v1.6）。 可选的计划/功能/声明的静态 HTML 视图（
scripts/generate-docs-dashboard.sh→docs/audit/generated/dashboard.html）。Markdown 是唯一真实来源；HTML 是 gitignored 的只读视图。在审计后提供一次，或在“仪表盘”请求时提供。请参见 knowledge-dashboard.md 和 modes.md §10。 - 技能强化（v1.7）。 维护者：在发布前运行
validate-skill.sh+test-skill-hardening.sh。智能体：通过 skill-discovery.md 检测安装/版本；在过时时建议重新安装（无静默自动修补）。 - v2.0 包。 完成 10 倍提升线：能力 1.4–1.7 加上 docs/adoption-matrix.md 跟踪。基础安装基线仍然为 2.0.0；多语言为 2.1.0；多仓库为 2.2.0；团队为 2.3.0；桥梁完成为 2.4.0；当前线是 2.5.0+（知识操作系统 迈向 100 倍的第一个增量——活声明 + CI 审计；不是第二个 10 倍）。
- 多语言栈检测（v2.1 切片 A / skill 2.1.0）。 在项目发现时（集成/审计/从零开始/采用），通过 skill-discovery.md 多语言栈检测（或
scripts/detect-stack.sh）从文件系统（package.json、pyproject.toml、go.mod……）检测栈。使用按栈的清单和按栈的文档布局指导——不要假设 Node/TS。在没有代码证据的情况下，绝不发明框架的 ModuleId/端点。请参见 modes.md §0.3。 - 多仓库枢纽（v2.2 切片 B）。 通过 skill-discovery.md 多仓库枢纽（或
scripts/detect-packages.sh）检测多包树（pnpm-workspace.yaml、package.jsonworkspaces、go.work、多包目录）。根枢纽是映射 + 包索引，而不是转储；多包覆盖率标记存在差距的包；仅在索引根时默认包非写入。请参见 modes.md §0.4。 - 团队治理（v2.3 切片 C）。 可选的
docs/team/，包含所有者 + 审批注释（最后批准样式）。根据 team-governance.md 创建与链接；枢纽链接团队，但不会变成 HR 维基；整合优先——添加团队绝不能重写产品愿景/需求/ADR。没有 CODEOWNERS 引擎或 BPM。请参见 modes.md §11。 - 模板遥测（v2.4 切片 D）。 选择加入的本地分类账，仅用于模板/技能 UX 差距（template-telemetry.md；
scripts/template-telemetry.sh）。默认关闭；绝不发送源代码/机密/仓库 URL；永不联网；选择加入关闭时，空气间隙环境无操作。请参见 modes.md §12。 - 活声明 + CI 结构性审计（v2.5 / 知识操作系统的第一个增量）。 审计矩阵使用活声明 v0：
anchor.path/ 可选的anchor.symbol/ 可选的anchor.hash，severity（critical|normal），判定不变。矩阵优先（audit-template.md）；过程参见 living-claims.md；连线参见 ADR-0001。真实得分仍然是建议性的（仪表盘启发式）；本地空气间隙scripts/audit-claims.sh/ 示例docs-auditCI 是门控（在关键矛盾时失败）。无 SaaS。请参见 modes.md §6 / §13。
第0步 — 检测作用域、模式和意图
作用域（必需）：
| 作用域 | 何时使用 | 输出重点 |
|---|---|---|
| project | 整个产品/“项目的文档” | 枢纽 + 项目文档（根据意图） |
| feature | 指定的功能/模块带代码（或刷新包） | docs/features/<slug>/ + 枢纽链接 |
| plan | 指定的新功能/史诗，在或没有可靠代码之前 | docs/plans/<slug>/ + 枢纽链接 |
| hybrid | 尚未有枢纽时的功能/计划 | 包或计划 + 最小枢纽 |
模式（必需）：
| 模式 | 信号 |
|---|---|
| bootstrap | 绿野，无枢纽/文档，或意图为 from-zero 在空/薄的项目上 |
| adopt | 代码存在；文档薄弱/缺失或意图为 integrate |
| audit | “审计文档”、“文档 vs 代码”、漂移、验证声明 |
| plan | “新功能”、“计划”、“史诗”、“我们要构建 X”而没有代码 |
| feature | 记录一个有（或就是）代码的功能/模块 |
| sync | 差异 / PR / 为变更更新文档；门后当 Ark 刚通过时 |
| roadmap | 规划发布 / 史诗列表刷新 |
意图（仅项目级工作必需）：
| 意图 | 用户信号（示例） | 行为 |
|---|---|---|
| integrate | “改进文档”、“整理”、“同步枢纽”、“成熟改进” | 采纳-整合（如果薄弱则全面）；如果怀疑漂移，可选预审计 |
| audit | “审计”、“文档是否说谎？”、“文档 vs 代码”、“验证路径” | 仅代码清单 + 声明矩阵（然后移交） |
| from-zero | “全新”、“从零开始”、“在 test/ 中生成文档”、“在文件夹 X 中生成完整知识库” | 完整知识库；如果给了路径，偏好沙箱；代码推断；旧文档 = 仅假设 |
推断（不要过度询问）：
- “nueva feature X” / “new feature X” / “我想要添加 X” → 功能自动导航（如果无代码则为计划，如果有代码则为功能；Kind 从措辞推断）。意图 = 不适用
- “implementá X” / “生成存根” / “scaffold X” → 如果需要，自动导航阶段 A + 实现桥梁选择加入（仅在请求存根时包含代码）
- “在
test/中生成所有文档” → Intent: from-zero | Out: sandbox:test/ - 成熟仓库 + “改进 / 整合 / 索引” → Intent: integrate
- “审计文档” / “代码 vs 文档” → Intent: audit
- 模糊项目工作且存在
docs/→ 询问一次：integrate | audit | from-zero - 指定的单一表面 → 永远不要要求用户列出非写入或选择文件夹
- “after ark-check” / “门后文档” / 门刚运行 + 文档意图 → sync 或 audit 带 ArkGate 桥梁
- “仪表盘” / “文档 HTML” / “知识报告” → 生成知识仪表盘（knowledge-dashboard.md）
- “owners” / “quién es dueño” / “team docs” / “审批注释” / “docs/team” → 团队治理（team-governance.md；modes §11）
- “模板遥测” / “选择加入遥测” / “记录模板差距” → 模板遥测仅在用户选择加入时（template-telemetry.md；modes §12）；默认关闭
- “活声明” / “真实得分” / “文档 CI” / “在矛盾时失败” → 活声明 + 本地 CI 门控（living-claims.md；modes §13）
成熟度（当相关时）：thin | mixed | mature — 请参见 modes.md。
如果推断后作用域/模式仍然模糊，询问一次。从 references/modes.md 加载过程。
在写入之前宣布：
Scope: <x> | Mode: <y> | Intent: <integrate|audit|from-zero|n/a> | Variant: <full|integrate|arkgate-bridge|n/a> | Maturity: <…|n/a> | Out: <root|sandbox:path> | Stack: <node-ts|python|go|mixed|unknown|n/a> | Monorepo: <yes|no|n/a> | ArkGate: <none|detected> | Slug: <slug|n/a>
当 integrate 时，列出非写入（当多仓库仅根索引时，包括包非写入）。当 audit 时，列出矩阵路径和主要矛盾。当 from-zero + 沙箱时，包括晋升计划。当 plan 或 feature 时，列出路径 + 默认非写入。当 ArkGate 桥梁时，列出信号和门后同步与审计丰富。当项目级时，包括来自发现的栈和多仓库标识。
推荐布局
project-root/
├── AGENTS.md
└── docs/
├── product-vision.md # bootstrap / from-zero / adopt-full
├── requirements.md
├── architecture.md
├── roadmap.md
├── team/ # v2.3 团队治理（可选）
│ ├── OWNERS.md
│ └── approval-notes.md
├── audit/ # 审计意图（可选）
│ └── claims-matrix.md # 活声明 v0 列
├── adr/ # 包 / 项目 ADR（可选）
├── plans/<slug>/ # v1.3 计划模式（代码前 / 史诗）
│ └── README.md
├── decisions/
└── features/<slug>/ # 代码支持的功能包
仅在合理时创建支持性文档（from-zero 除外，它可能创建完整的最小核心集）。
产物矩阵（概要）
| 产物 | from-zero / bootstrap | integrate (mature) | audit | plan | feature | sync |
|---|---|---|---|---|---|---|
| 枢纽 | 创建 | 扩展 / 索引 | 可选更新状态 | 链接计划 | 链接 | 如果需要 |
| 核心叙事文档 | 是 | 不重写 | 否（只读） | 否 | 否 | 如果有影响 |
| 覆盖率矩阵 | 是 | 必需 | 清单的一部分 | 可增加行 | 可增加行 | 更新 |
| 声明矩阵 | 可选预 | 如果怀疑漂移则推荐 | 必需 | 不适用 | 如果审计则限定范围 | 如果漂移 |
计划 docs/plans/ | 不适用 | 不适用 | 不适用 | 必需 | 如果存在则链接 | 如果有影响 |
| 功能包 | 关键领域 | 差距 / 条目 | 否（除非要求） | 否（直到提升） | 必需 | 如果有影响 |
团队 docs/team/ | 如果所有者已知 | 如果要求则创建/链接 | 否 | 不适用 | 不适用 | 如果有影响 |
| 并行完整树 | 沙箱允许 | 根目录禁止 | 不适用 | 不适用 | 不适用 | 不适用 |
工作流（所有模式）
- 第0步 — 作用域、模式、意图（如果是项目）、成熟度/变体、输出、slug；在相关时检测 ArkGate 信号；为项目工作检测栈和多仓库标识（skill-discovery.md 多语言 + 多仓库枢纽）。
- 先发现代码 — 栈感知的清单；如果是多仓库，包索引 + 每个包的清单；树、清单、入口点、示例测试。然后文档（如果有）。对于指定的功能，先搜索该表面。如果检测到 Ark，根据 arkgate-bridge.md 丰富清单。
- 如果存在审计或文档，且意图是 integrate/from-zero 并怀疑有漂移：运行调和（modes.md § Audit、audit-template.md）。门后 → 桥梁移交（modes.md §9）。
- 计划文件 — 创建/更新和非写入（功能/计划的默认值）。
- **
…
[为翻译而截断]