docs: align Chinese-first feedback and docs governance

Merge PR #149 after Code Queue rebase and validation. This lands long-term documentation governance only: Chinese-first documentation, user-feedback triage, docs-spec entry rules, #131 first-source handling, and #78 commander constraints. No PROD/deploy/service changes.
This commit is contained in:
Lyon
2026-05-23 00:18:24 +08:00
committed by GitHub
parent 7a0648088c
commit eb710860dd
6 changed files with 178 additions and 91 deletions
@@ -0,0 +1,40 @@
# HWLAB 中文优先文档规则
本规则固化 [pikasTech/HWLAB#121](https://github.com/pikasTech/HWLAB/issues/121) 的要求:HWLAB issue、PR 说明、长期参考文档和用户可见说明必须中文优先,不能由英文主导。
## 适用范围
- `AGENTS.md``docs/reference/*.md` 必须中文主导。
- GitHub issue、PR body、review 结论、runner 最终回执默认使用中文。
- 面向用户或指挥官的 UI 文案、报告摘要和验收说明默认使用中文。
- 过程记录、日报和临时调查笔记不应进入 `docs/reference/`;需要长期保留时只蒸馏稳定结论。
## 允许保留英文的情况
下列内容需要保真时可以保留英文,但应在首次出现处给出中文解释或上下文:
- 命令、脚本名、文件路径、环境变量、端口、URL、协议名、HTTP path、JSON 字段、commit、tag、digest、ID。
- 产品或组件固有名词,例如 `Cloud Workbench``runner``patch-panel``hwlab-cloud-web`
- 证据标签,例如 `SOURCE``LOCAL``DRY-RUN``DEV-LIVE``BLOCKED`
- GitHub、Kubernetes、FRP、UniDesk、k3s 等外部系统或标准术语。
## 编写规则
- 标题、段落、表格说明、验收标准和禁止事项优先用中文。
- 英文术语不要替代中文解释;例如写“PR 工作流(pull request 工作流)”,不要只写 `PR workflow`
- 面向用户的反馈必须直说影响、优先级和下一步,不用英文模板化句式。
- 文档更新时如果只做翻译,不改变语义;如果同时改变规则,必须在 PR body 中说明规则变化。
- 不把每日简报、一次性执行日志、临时 blocked 状态或 changelog 式流水账写进长期参考。
## 验收标准
- `AGENTS.md` 能索引中文优先规则。
- `docs/reference/README.md` 的索引和来源说明中文主导。
- 新增或更新长期参考时,中文解释覆盖“做什么、为什么、怎么判定、禁止什么”。
- 必要英文术语保留精确拼写,但不能让文档主体变回英文。
## 稳定来源
- [pikasTech/HWLAB#121](https://github.com/pikasTech/HWLAB/issues/121)issue 和长期文档中文化。
- [pikasTech/HWLAB#108](https://github.com/pikasTech/HWLAB/issues/108)Cloud Workbench 中文 UI 约束。
- [documentation-governance.md](documentation-governance.md):长期参考和 docs-spec 入库规则。