mirrors/pikasTech-HWLAB
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
395216122ac3919fbf3b86428164505d3d66c376
pikasTech-HWLAB/docs/reference/spec-v02-documentation-governance.md
T
Codex 395216122a fix: make hwlab cli a short web client
2026-05-30 12:31:07 +08:00

6.0 KiB
Raw Blame History

v0.2 文档治理规格

本文是 HWLAB v0.2 文档体系的长期规格。它定义哪些文档可以留在仓库、哪些过程材料必须迁入 GitHub issue、旧 D601/G14 口径如何处理，以及 docs/ 根目录不得再堆放 Markdown 或 JSON 的收敛规则。

实施和历史归档见 pikasTech/HWLAB#532。本文只记录稳定规则；被迁移文档的全文在 issue 评论中按源路径归档。

设计目标

  • AGENTS.md 是唯一顶级入口；不再维护根 README.md 或 docs/reference/README.md。
  • docs/reference/ 是长期参考唯一目录，只放规格、约束、入口、判定标准和稳定 runbook。
  • v0.2 专项长期规格必须使用 spec- 前缀，例如 spec-v02-cicd.md、spec-user-access.md。
  • 计划、里程碑、阶段推进、一次性排障、报告合同和历史验收材料不留在仓库文档树；全文迁入 GitHub issue 后删除源 Markdown。
  • docs/ 根目录不得直接放 *.md 或 *.json。机器契约放 protocol/、deploy/ 或源码相邻目录；临时报告放 /tmp、.state 或 CI artifact。
  • D601、旧 DEV gate、旧 16666/16667、M0-M5 里程碑和 simulator/patch-panel 旧规格只作为历史归档，不作为 v0.2 当前规格。

允许的文档形态

位置 允许内容 不允许内容
AGENTS.md 入口索引、一句话规则、长期参考链接 详细设计、计划全文、过程记录、二级 README 口径
docs/reference/*.md 长期规格、稳定边界、判定标准、可复用 runbook 日期化流水账、阶段计划、迁移 TODO 全文、临时 evidence、旧规格副本
GitHub issue/PR 计划全文、里程碑拆解、过程记录、一次性排障、执行证据 作为长期权威替代 docs/reference
protocol/ / deploy/ 机器可消费 schema、deploy intent、GitOps 模板 人写过程报告、临时 JSON dump
/tmp / .state / CI artifact 临时报告、运行输出、截图、trace dump 需要长期复用的规格

迁移规则

  1. 发现 README.md、docs/*.md、docs/*.json 或 docs/plan/*.md 时，先判断是否有长期价值。
  2. 有长期价值的，只把稳定结论吸收到对应 docs/reference/ 权威文档；不要整篇搬入 reference。
  3. 属于计划、里程碑、阶段迁移、报告、一次性排障或历史验收的，全文迁入 GitHub issue body/comment，再删除源文件。
  4. 属于旧规格且与当前 v0.2 spec 冲突的，直接删除；必要时在新 spec 中用一句话说明旧口径已被替代。
  5. 迁移后的 reference 必须引用相关 issue，尤其是规格尚未完全实现、仍需要 issue 承接实施步骤时。
  6. GitHub issue/PR 写入必须走 UniDesk CLI bun scripts/cli.ts gh ...，不能直接用原生 gh 或手写 GitHub API。

D601/G14 口径处理

  • 当前 HWLAB DEV/PROD 真相是 G14 k3s、G14/G14-gitops 和 hwlab-dev/hwlab-prod。
  • v0.2 真相是 origin/v0.2、v0.2-gitops、hwlab-v02 和 19666/19667，权威规格见 spec-v02-cicd.md。
  • D601 只允许作为 legacy 事故回放、迁移对照或 Windows 硬件 bridge 背景出现在长期参考中；不得作为当前 v0.2 发布、验收或权限规格。
  • 任何根文档或计划文档如果仍把 D601、旧 DEV gate、旧 main、旧 16666/16667 或 simulator/patch-panel 写成当前规格，应删除或改为引用新 spec。

本次收敛映射

被删除来源 处理
README.md 有效入口信息已由 AGENTS.md、architecture.md、dev-runtime-boundary.md 和 spec-v02-services.md 承接；全文归档到 #532。
docs/cloud-web-workbench.md 稳定前端约束由 cloud-workbench.md 承接；全文归档到 #532。
docs/dev-acceptance-matrix.md、docs/dev-gate-*、docs/dev-evidence-* 旧 DEV/D601 gate 和报告材料仅作历史归档；当前边界见 dev-runtime-boundary.md、MVP-e2e-acceptance.md 和 spec-v02-cicd.md。
docs/dev-acceptance-checklist.json 旧 M5 dry-run 机器 fixture 已退休并从源码移除；当前 v0.2 非视觉验收走 hwlab-cli client 真实 Cloud Web API。历史全文归档到 #532。
docs/m0-*、docs/m1-*、docs/m3-*、docs/m4-*、docs/m5-*、docs/operator-runbook.md 旧里程碑和 operator 阶段材料迁入 #532；当前 M3 判定见 m3-loop-rollout-runbook.md。
docs/topology-constraints.md simulator/patch-panel 旧拓扑规格与 v0.2 裁撤口径冲突；当前服务取舍见 spec-v02-services.md。
docs/schema-drift-map.md 人写摘要归档到 #532；机器 source of truth 仍是 protocol/schema-drift-map.json。
docs/plan/hwlab-v02-namespace-cicd.md 全文迁入 pikasTech/HWLAB#530 评论；长期规格见 spec-v02-cicd.md。
docs/plan/v02-multi-user-migration.md 全文迁入 pikasTech/HWLAB#531 评论；长期规格见 spec-user-access.md。
docs/plan/v02-device-pod-spec-migration.md 和旧 device-pod MVP plan 全文迁入 pikasTech/HWLAB#533 评论；长期规格见 spec-device-pod.md。

验收标准

  • AGENTS.md 索引本文，并且不再把 README.md 当入口。
  • find docs -maxdepth 1 -type f \( -name '*.md' -o -name '*.json' \) 为空。
  • docs/plan 不再包含仓库内计划 Markdown；后续计划写入 GitHub issue。
  • docs/reference/ 中不存在指向已删除根文档或 docs/plan 的相对链接。
  • D601 只以 legacy/回放/bridge 背景出现在长期参考；不会作为 v0.2 当前规格或验收路径。
  • 任何未完成规格都必须引用承接实施的 GitHub issue。
Reference in New Issue View Git Blame Copy Permalink