pikasTech-HWLAB/docs/reference/chinese-first-documentation.md

HWLAB 中文优先文档规则

本规则固化 pikasTech/HWLAB#121 的要求，是 HWLAB 中文优先规则的唯一维护处：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 能索引中文优先规则。
• 不再维护 README.md / docs/reference/README.md 入口；AGENTS.md 作为唯一入口时，其索引和来源说明必须中文主导。
• 新增或更新长期参考时，中文解释覆盖“做什么、为什么、怎么判定、禁止什么”。
• 必要英文术语保留精确拼写，但不能让文档主体变回英文。

稳定来源

• pikasTech/HWLAB#121：issue 和长期文档中文化。
• pikasTech/HWLAB#108：Cloud Workbench 中文 UI 约束。
• documentation-governance.md：长期参考和 docs-spec 入库规则。