docs(zh-CN): sync Chinese docs with latest upstream changes (#304)

* docs(zh-CN): sync Chinese docs with latest upstream changes

* update

---------

Co-authored-by: neo <neo.dowithless@gmail.com>

docs/zh-CN/commands/update-docs.md

@@ -1,31 +1,86 @@
 # 更新文档
 
-从单一事实来源同步文档：
+将文档与代码库同步，从单一事实来源文件生成。
 
-1. 读取 package.json 的 scripts 部分
-   * 生成脚本参考表
-   * 包含来自注释的描述
+## 步骤 1：识别单一事实来源
 
-2. 读取 .env.example
-   * 提取所有环境变量
-   * 记录其用途和格式
+| 来源 | 生成内容 |
+|--------|-----------|
+| `package.json` 脚本 | 可用命令参考 |
+| `.env.example` | 环境变量文档 |
+| `openapi.yaml` / 路由文件 | API 端点参考 |
+| 源代码导出 | 公共 API 文档 |
+| `Dockerfile` / `docker-compose.yml` | 基础设施设置文档 |
 
-3. 生成 docs/CONTRIB.md，内容包含：
-   * 开发工作流程
-   * 可用脚本
-   * 环境设置
-   * 测试流程
+## 步骤 2：生成脚本参考
 
-4. 生成 docs/RUNBOOK.md，内容包含：
-   * 部署流程
-   * 监控和警报
-   * 常见问题及修复
-   * 回滚流程
+1. 读取 `package.json` (或 `Makefile`, `Cargo.toml`, `pyproject.toml`)
+2. 提取所有脚本/命令及其描述
+3. 生成参考表格：
 
-5. 识别过时的文档：
-   * 查找 90 天以上未修改的文档
-   * 列出以供人工审查
+```markdown
+| Command | Description |
+|---------|-------------|
+| `npm run dev` | 启动带热重载的开发服务器 |
+| `npm run build` | 执行带类型检查的生产构建 |
+| `npm test` | 运行带覆盖率测试的测试套件 |
+```
 
-6. 显示差异摘要
+## 步骤 3：生成环境文档
 
-单一事实来源：package.json 和 .env.example
+1. 读取 `.env.example` (或 `.env.template`, `.env.sample`)
+2. 提取所有变量及其用途
+3. 按必需项与可选项分类
+4. 记录预期格式和有效值
+
+```markdown
+| 变量 | 必需 | 描述 | 示例 |
+|----------|----------|-------------|---------|
+| `DATABASE_URL` | 是 | PostgreSQL 连接字符串 | `postgres://user:pass@host:5432/db` |
+| `LOG_LEVEL` | 否 | 日志详细程度（默认：info） | `debug`, `info`, `warn`, `error` |
+```
+
+## 步骤 4：更新贡献指南
+
+生成或更新 `docs/CONTRIBUTING.md`，包含：
+
+* 开发环境设置（先决条件、安装步骤）
+* 可用脚本及其用途
+* 测试流程（如何运行、如何编写新测试）
+* 代码风格强制（linter、formatter、预提交钩子）
+* PR 提交清单
+
+## 步骤 5：更新运行手册
+
+生成或更新 `docs/RUNBOOK.md`，包含：
+
+* 部署流程（逐步说明）
+* 健康检查端点和监控
+* 常见问题及其修复方法
+* 回滚流程
+* 告警和升级路径
+
+## 步骤 6：检查文档时效性
+
+1. 查找 90 天以上未修改的文档文件
+2. 与最近的源代码变更进行交叉引用
+3. 标记可能过时的文档以供人工审核
+
+## 步骤 7：显示摘要
+
+```
+Documentation Update
+──────────────────────────────
+Updated:  docs/CONTRIBUTING.md (scripts table)
+Updated:  docs/ENV.md (3 new variables)
+Flagged:  docs/DEPLOY.md (142 days stale)
+Skipped:  docs/API.md (no changes detected)
+──────────────────────────────
+```
+
+## 规则
+
+* **单一事实来源**：始终从代码生成，切勿手动编辑生成的部分
+* **保留手动编写部分**：仅更新生成的部分；保持手写内容不变
+* **标记生成的内容**：在生成的部分周围使用 `<!-- AUTO-GENERATED -->` 标记
+* **不主动创建文档**：仅在命令明确要求时才创建新的文档文件