/update-docs

更新文档 (Update Documentation)

将文档与代码库同步，从单一事实来源 (Source of Truth) 文件生成。

步骤 1：识别单一事实来源 (Identify Sources of Truth)

| 来源 | 生成内容 | |------|----------| | `package.json` 脚本 | 可用命令参考 | | `.env.example` | 环境变量文档 | | `openapi.yaml` / 路由文件 | API 端点参考 | | 源码导出内容 | 公共 API 文档 | | `Dockerfile` / `docker-compose.yml` | 基础设施设置文档 |

步骤 2：生成脚本参考 (Generate Script Reference)

1. 读取 `package.json`（或 `Makefile`、`Cargo.toml`、`pyproject.toml`） 2. 提取所有脚本/命令及其说明 3. 生成参考表：

| Command | Description |
|---------|-------------|
| `npm run dev` | Start development server with hot reload |
| `npm run build` | Production build with type checking |
| `npm test` | Run test suite with coverage |

步骤 3：生成环境文档 (Generate Environment Documentation)

1. 读取 `.env.example`（或 `.env.template`、`.env.sample`） 2. 提取所有变量及其用途 3. 将其分类为必填与选填 (required vs optional) 4. 记录预期格式和有效值

| Variable | Required | Description | Example |
|----------|----------|-------------|---------|
| `DATABASE_URL` | Yes | PostgreSQL connection string | `postgres://user:pass@host:5432/db` |
| `LOG_LEVEL` | No | Logging verbosity (default: info) | `debug`, `info`, `warn`, `error` |

步骤 4：更新贡献指南 (Update Contributing Guide)

生成或更新 `docs/CONTRIBUTING.md`，包含：

• 开发环境设置（先决条件、安装步骤）
• 可用脚本及其用途
• 测试流程（如何运行、如何编写新测试）
• 代码风格强制执行（linter、formatter、pre-commit 钩子）
• PR 提交检查清单

步骤 5：更新运维手册 (Update Runbook)

生成或更新 `docs/RUNBOOK.md`，包含：

• 部署流程（分步指南）
• 健康检查端点与监控
• 常见问题及其修复
• 回滚流程
• 告警与升级路径

步骤 6：陈旧性检查 (Staleness Check)

1. 查找超过 90 天未修改的文档文件 2. 与最近的源代码更改进行交叉对比 3. 标记可能过时的文档以供手动审查

步骤 7：显示摘要 (Show Summary)

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)
──────────────────────────────

规则 (Rules)

• **单一事实来源 (Single source of truth)**：始终从代码生成，严禁手动编辑生成的部分
• **保留手动编写章节 (Preserve manual sections)**：仅更新生成的部分；保持手写的正文内容完整
• **标记生成的内容 (Mark generated content)**：在生成的部分周围使用 `<!-- AUTO-GENERATED -->` 标记
• **不要自发创建文档 (Don't create docs unprompted)**：仅在命令明确要求时才创建新的文档文件