# HWLAB 中文优先文档规则

本规则固化 [pikasTech/HWLAB#121](https://github.com/pikasTech/HWLAB/issues/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](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 入库规则。