documentation-governance

文档治理

使命

维护一套易于发现、便于审查、可验证且能随项目演进的文档体系。Markdown 和 Git 是默认的源格式和历史记录机制；VitePress 是展示层，并非唯一权威存储。

已确认的默认政策

• 治理范围：建立一致的标准，并允许在有充分理由时调整目录结构。
• 站点交付：本地预览以及离线／静态交付物。
• 代码同步：发现差异、提出更新并验证结果；语义变更需要审查。
• 文件变更：重大或破坏性变更前须获得确认。
• 自动化：仅在收到请求时手动运行。除非另行请求，不要添加 Git hooks、CI/CD、定时任务、云端发布或外部服务。
• 优先使用仓库原生工具和依赖项。未经说明需求并在变更影响较大时获得许可，不要安装软件包或更改软件包清单。

核心不变量

1. 先检查，再编辑。检查仓库根目录、现有文档、项目说明、软件包脚本、VitePress 配置，以及 Git 工作树状态（如可用）。
2. 按信息类型确立权威来源。运行时代码是当前行为的依据，但并不自动代表预期产品行为的权威来源。需求与实现之间存在冲突时，必须报告，不得擅自裁定。
3. 重大迁移前先制定计划。展示当前路径 → 提议路径、原因、受影响的引用、风险和回滚方案。删除、覆盖、批量移动、重命名大量文件或替换现有站点配置前，先征得批准。
4. 保留用户的工作。绝不覆盖无关变更。如果工作树不干净，应区分先前已有的变更与本任务所做的变更。不要重置、清理或丢弃变更。
5. 进行最小且便于审查的编辑。针对性修正足以解决问题时，避免大范围重写。保留有用的历史和内容。
6. 区分事实与推断。将不确定的说法标记为 needs-review，或列入审计报告。
7. 变更后进行验证。检查受影响的链接／资源、元数据、导航，以及站点构建（如可用）。报告未运行的检查及原因。
8. 不得静默发布。build 不等于 publish。离线打包不等于部署。除非获得明确授权，否则绝不上传或发布。
9. 即使没有 VitePress，这项技能仍须保持实用性。清点、映射、差异分析和基础验证都应能独立运行。

任务路由

选择满足请求所需的最精简工作流。执行前，先阅读 workflows/ 中对应的文件。

• 首次采用或标准设置 → workflows/onboarding.md
• 了解现有内容 → workflows/inventory.md
• 重组或迁移文件 → workflows/migration.md
• 比较代码／规范／文档或同步变更 → workflows/code-sync.md
• 设置、预览、构建或打包 VitePress → workflows/site-delivery.md
• 质量审查或定期审计 → workflows/audit.md
• 用户只要求报告 → 除非对方提出要求，否则不要修改文件。

执行流程

A. 建立上下文

• 确认仓库根目录和项目类型。
• 阅读适用的项目指导（例如 AGENTS.md、CONTRIBUTING.md 和现有文档约定）。
• 检查相关文件和软件包脚本；不要假设工具已安装。
• 记录现有 VitePress 配置和文档源目录。
• 如果 Git 可用，检查 Git 状态。不要因目录看起来干净就推断没有未跟踪文件。

B. 对请求的操作进行分类

• **只读：**清点、报告、链接扫描、偏差分析。
• **低风险且可逆：**补充缺失的索引、修正明显失效的本地链接、在约定的位置创建新的报告文件。
• **重大操作：**批量移动或重命名、删除或替换文档、更改权威性规则、重构导航、替换站点配置、安装依赖项、更改包脚本、生成大量派生内容、打包时排除或重写资源。

继续执行只读工作。请求明确要求修复时，可以进行低风险编辑。重大操作前应先询问，并给出简明计划。

C. 应用并验证

• 遵循选定的工作流和参考资料。
• 在迁移映射中记录重要的路径变更。
• 仅运行相关检查；机械性检查优先使用确定性脚本。
• 如果某项检查无法运行，应说明这一限制，不要暗示检查已成功。
• 总结已更改的文件、运行的检查及其结果、尚未解决的决策和后续操作。

文档模型

使用能够清楚表达内容的最少概念：

• **规范源：**特定声明或制品的事实来源。
• **派生内容：**由规范源生成；注明其生成器和重新生成方法。
• **辅助说明：**由人工维护的说明、依据、示例或教程。
• 状态：draft、active、needs-review、deprecated 或 archived。
• **负责人：**已知时填写角色、团队或人员；切勿虚构负责人。
• **审查触发条件：**应触发审查的代码路径、架构、功能、版本或事件。

不要求立即为每份旧文档添加 frontmatter。先为新文档或正在积极维护的文档添加，再逐步迁移旧文档。

项目配置

需要时，根据 templates/docs-governance.example.yml 创建 .governance/docs.yml。将其视为项目专属配置，而非必须遵循的全局架构。生成的清单和报告应与规范文档分开；除非有明确规则，否则不得将生成的输出作为权威来源。

工具规则

• 脚本默认应安全；在可行时使用标准库；提供帮助信息；验证失败时返回非零状态；除非脚本名称和文档明确说明会修改源文件，否则不得修改源文件。
• 清单和审计输出应保存到用户批准的报告位置；默认建议位置为 artifacts/documentation-governance/，但须先确认其不会与项目惯例冲突。
• 本地或离线文档应使用本地链接。除非离线交付物中明确声明，否则应避免远程资源或运行时获取。
• 除非已测试相关能力并说明其局限，否则不得声称支持 PDF 导出、单文件打包或完全可移植。

完成标准

只有在交付请求的结果，并在回复中说明以下内容后，任务才算完成：

1. 更改了什么（或说明仅进行了只读操作）。
2. 重要文件和决策。
3. 执行的验证及实际结果。
4. 尚未解决的冲突或风险，以及未执行的检查。
5. 相关时，如何在本地预览、构建或打包。

请参阅 README.md 了解包结构，并参阅 references/ 获取详细规则。