lyon
97 lines
9.3 KiB
Markdown
97 lines
9.3 KiB
Markdown
# HWLAB 文档治理与 docs-spec 入库规则
|
||
|
||
本文是 HWLAB 仓库内固化的 `docs-spec` 规则副本和可执行摘要，也是本仓库唯一维护 `docs-spec` 使用规则的长期参考。它等价承担 `docs/reference/docs-spec.md` 的职责；不要再新增同级 `docs-spec` 规则副本，避免多处口径漂移。编辑 `AGENTS.md`、`docs/reference/*.md` 或把过程记录蒸馏为长期参考时，必须先按本文执行；如果 runner 能读取外部 `docs-spec` skill，也要以本文作为 HWLAB 本地权威落点。
|
||
|
||
`v0.2` 文档树的额外收敛规格见 [spec-v02-documentation-governance.md](spec-v02-documentation-governance.md)。该规格禁止仓库保留根 `README.md`、`docs/*.md`、`docs/*.json` 和 `docs/plan/*.md` 作为长期或过程文档入口；计划、里程碑和一次性记录必须迁入 GitHub issue。
|
||
|
||
中文优先规则只在 [chinese-first-documentation.md](chinese-first-documentation.md) 维护，用户和参谋反馈分流规则只在 [user-feedback-triage.md](user-feedback-triage.md) 维护。本文只交叉引用这些规则，不替代 [commander-collaboration.md](commander-collaboration.md) 中由 [pikasTech/HWLAB#131](https://github.com/pikasTech/HWLAB/issues/131) 固化的一手事实和真实推进边界。
|
||
|
||
## AGENTS.md 规则
|
||
|
||
- `AGENTS.md` 是 agent、指挥官和 runner 的唯一入口，用于快速定位命令、入口和长期参考文档。
|
||
- 与 `AGENTS.md` 同等作用的文档，例如 `README.md`、`docs/reference/README.md`、`CLAUDE.md`，不得作为入口或索引；`v0.2` 不保留这类二级入口，历史内容迁入 issue 或吸收到对应 reference。
|
||
- 每个命令在 `AGENTS.md` 中只保留一条主索引；参数、背景、判定标准写入链接的 reference 文档。
|
||
- `AGENTS.md` 的主标题、章节名和列表摘要必须中文优先；`Agent`、`runner`、`Cloud Workbench`、命令和路径等可保留原文，但要放在中文语境中解释。
|
||
- 每个列表项只描述一个功能点，用一句中文概括，不在顶层展开实现细节。
|
||
- `AGENTS.md` 必须直接索引中文优先、用户反馈分流、PR 工作流、`#78` 上位约束和各专项 `docs/reference/*.md`，不得再通过 README.md 二级入口跳转。
|
||
|
||
## docs/reference 长期参考规则
|
||
|
||
- `docs/reference/` 只记录长期稳定、可重复复用的入口、前置条件、约束和判定标准。
|
||
- 不写日期化日报、一次性过程记录、实测流水账、容易过时的 changelog 或临时 blocked 记录。
|
||
- 每个功能点优先对应 `docs/reference/` 下的独立 Markdown 文档；`AGENTS.md` 只链接和摘要。
|
||
- 功能需要补充说明时，先更新 reference 详细文档，再更新 `AGENTS.md` 的一句话摘要。
|
||
- 知识更新遵循：增加新稳定知识、删除过时知识、修正错误知识、合并重复知识。
|
||
- 跨文档重复时，选择一个 reference 作为唯一权威出处，其他文档交叉引用它。
|
||
- 涉及 skill 的 reference 必须说明该 skill 与 HWLAB 代码、硬件、目录和验收标准的关系；通用 CLI 用法直接引用 skill，不在仓库内复制成另一份通用手册。
|
||
|
||
## 过程文档蒸馏规则
|
||
|
||
- 过程文档是历史资料，通常带时间戳，时效性强，不能直接进入长期参考。
|
||
- 蒸馏只提取稳定结论、边界、验收标准和禁止事项。
|
||
- 计划、plan、里程碑、阶段迁移、一次性报告和旧 gate 文档全文迁入 GitHub issue；仓库内不再维护 `docs/plan/*.md`。
|
||
- 不篡改过程文档；过程记录是原始来源。
|
||
- 大文件按滑动窗口阅读，读一段就提炼稳定结论，不等全部读完才更新 reference。
|
||
- 新稳定结论覆盖旧冲突结论；旧过程只作为历史来源。
|
||
- 可以简述重要发展脉络，但不能把长期参考写成流水账。
|
||
|
||
## 中文和反馈治理
|
||
|
||
- 中文优先规则见 [chinese-first-documentation.md](chinese-first-documentation.md)；长期参考必须中文主导。
|
||
- 用户和参谋反馈分流规则见 [user-feedback-triage.md](user-feedback-triage.md)；默认按高优先级用户反馈处理并挂到 `#7`。
|
||
- 影响 M3 判定的文档必须显式对齐 `DC-DCSN-P0-2026-003` / `#78`，不得把 SOURCE、LOCAL、DRY-RUN、fixture、edge-only health 或前端状态写成 M3 DEV-LIVE。
|
||
- 影响发布、运行态、端口和 PR 流程的规则必须交叉引用对应 reference，不在多个文档里各写一套。
|
||
|
||
## 本地入库和同步机制
|
||
|
||
- 本文保留外部 `docs-spec` 的完整核心规则，使没有 skill 可见性的 runner 仍能执行 HWLAB 文档治理；它是 `#123` 要求的 repo 内权威落点。
|
||
- 每次任务涉及 `AGENTS.md`、`docs/reference/*.md` 或过程文档蒸馏时，runner 应先读取外部 `docs-spec` skill；如果外部规则与本文不同，必须在同一 PR 中同步更新本文并说明差异。
|
||
- 如果外部 skill 不可读，按本文执行，并在 PR body 中说明“使用仓库内 docs-spec 固化规则，外部 skill 不可用或未校验”。
|
||
- 本仓库覆盖外部通用 docs-spec 中的 README 入口口径：新增 reference 后只更新对应 reference 和 `AGENTS.md`，不得新增或维护 `README.md` / `docs/reference/README.md` 入口。
|
||
|
||
## HWLAB 当前应用
|
||
|
||
- `#7` 是指挥官看板和用户反馈集中入口。
|
||
- `#78` / `DC-DCSN-P0-2026-003` 是 M3 虚拟硬件可信闭环上位约束。
|
||
- `#121` 要求 issue 和长期文档中文化。
|
||
- `#122` 要求用户和参谋反馈默认高优先级并挂到 `#7`。
|
||
- `#123` 要求 docs-spec 规则固化进 HWLAB 长期参考文档，而不是只在 issue 里引用外部 skill；本文就是该规则的等价本地文档。
|
||
- `#532` 是 `v0.2` 文档治理规格和被删除根文档/过程文档的全文归档入口；当前收敛规格见 [spec-v02-documentation-governance.md](spec-v02-documentation-governance.md)。
|
||
- 当前 HWLAB 的 node/lane 工作区、运行面入口、M3 证据、Cloud Workbench 默认路由和 PR 工作流，分别由本目录的专项 reference 与受控 lane 配置维护；D601 legacy 只指旧 DEV/CD、迁移对照和事故回放路径，D601 v0.3 这类 issue/CLI 明确的 node-scoped runtime lane 不属于 legacy。
|
||
|
||
## docs-spec 原文副本
|
||
|
||
以下副本来自当前 runner 可见的 `docs-spec` skill，用于满足 `#123` 的本地固化要求。后续如果外部 skill 更新，应按“本地入库和同步机制”同步。
|
||
|
||
```markdown
|
||
---
|
||
name: docs-spec
|
||
description: 用于指导 docs 的文档规范，编辑 CLAUDE.md/AGENTS.md 或者 docs/reference/*.md 或者进行过程文档蒸馏时必须加载本 SKILL
|
||
---
|
||
|
||
- `AGENTS.md` 只作为项目级顶级索引，用于快速定位命令、入口和文档。
|
||
- 其他和 `AGENTS.md` 具有同等作用的文档（例如 CLAUDE.md )中只写入一行 `@AGENTS.md` 将其引导到 `AGENTS.md`，避免多种口径互相不一致。
|
||
- 每个命令在 `AGENTS.md` 中保留一条主索引，命令下面可以挂多个功能子列表。
|
||
- 每个子列表只描述一个功能点，并使用一句话概括，不在此处展开实现细节、参数说明或背景分析。
|
||
- docs/reference 长期参考文档
|
||
- `docs/reference/` 只记录长期稳定、可重复复用的入口、前置条件、约束和判定标准；不要写日期、一次性过程记录、实测流水账或容易过时的 changelog 式内容。
|
||
- 每个子列表应独立对应一个 `docs/reference/` 下的参考文档；如果同一命令包含多个功能，则分别链接到各自文档。
|
||
- 所有功能的详细说明统一写入 `docs/reference/` 下的独立 Markdown 文档，并在 `AGENTS.md` 中提供对应链接索引。
|
||
- 当某项功能需要补充说明时，优先更新 `docs/reference/` 的详细文档，再回到 `AGENTS.md` 维护对应子列表的一句话摘要与链接。
|
||
- 知识更新原则 - 增加新知识、删除过时知识、修改错误知识、合并重复知识
|
||
- 避免重复 - 对于同文档重复的内容应当进行合并，对于跨文档重复的内容，应当选择或者新建一个文档作为唯一权威出处，其他文档交叉引用权威出处。
|
||
- `docs/reference/` 中涉及 skill 的文档，必须突出该 skill 与当前项目代码、硬件、目录和判定标准的具体联系；通用安装、CLI 参数、子命令和完整用法直接交叉引用对应 skill 的 `SKILL.md`，不要在 reference 中重复抄写一份通用说明。
|
||
- 过程文档蒸馏
|
||
- 过程文档指的是开发过程中的过程记录，通常带有时间戳，特征是时效性明显，容易过时，代表了系统的发展和转变过程。
|
||
- 过程文档蒸馏指的是将过程文档蒸馏为长期参考文档。
|
||
- 蒸馏原则
|
||
- 从旧到新原则 - 先从旧的过程文档开始整理，然后逐渐处理新的。
|
||
- 滑动窗口 - 对于大的过程文档文件，采用滑动窗口策略，读一定长度（例如 500 行）就更新一次长期参考文档，不要全部读完再更新。
|
||
- 新的覆盖旧的 - 新的过程文档有更高的重要性，在新的和旧不一致时，应当以新的替换旧的。
|
||
- 简述发展过程 - 在长期参考文档中用简短的篇幅描述总体的发展过程 OUTLINE。
|
||
- 避免将发展过程写成流水账。
|
||
- 越早期的发展过程越简略地写。
|
||
- 重要的发展过程节点可以交叉引用过程文档。
|
||
- 不要篡改过程文档 - 过程文档是一手的历史资料，禁止对过程文档进行篡改。
|
||
```
|