文档与代码地图
概述
doc-updater 代理（Agent）是一个文档专家，负责维护代码地图（Codemap）和文档与代码库的同步。本文整合了代理定义、代码地图更新命令和文档更新命令三个组件。
第二部分：代码地图更新（Update Codemaps）
步骤 1：扫描项目结构
- 识别项目类型（单体仓库 / Monorepo、单应用、库、微服务）
- 查找所有源代码目录（src/、lib/、app/、packages/）
- 映射入口点（main.ts、index.ts、app.py、main.go 等）
步骤 2：生成代码地图
在 docs/CODEMAPS/（或 .reports/codemaps/）中创建或更新代码地图：
| 文件 | 内容 |
|---|---|
architecture.md |
高层系统架构图、服务边界、数据流 |
backend.md |
API 路由、中间件链、Service -> Repository 映射 |
frontend.md |
页面树、组件层级、状态管理流 |
data.md |
数据库表、关系、迁移历史 |
dependencies.md |
外部服务、第三方集成、共享库 |
代码地图格式
每个代码地图应当精简 Token -- 为 AI 上下文消费优化：
# 后端架构
## 路由
POST /api/users -> UserController.create -> UserService.create -> UserRepo.insert
GET /api/users/:id -> UserController.get -> UserService.findById -> UserRepo.findById
## 关键文件
src/services/user.ts (业务逻辑, 120 行)
src/repos/user.ts (数据库访问, 80 行)
## 依赖
- PostgreSQL (主数据存储)
- Redis (会话缓存, 速率限制)
- Stripe (支付处理)
步骤 3：差异检测（Diff Detection）
- 如果存在之前的代码地图，计算差异百分比
- 如果变更 > 30%，显示差异并请求用户批准后再覆盖
- 如果变更 <= 30%，就地更新
步骤 4：添加元数据
在每个代码地图添加新鲜度头部：
<!-- Generated: 2026-02-11 | Files scanned: 142 | Token estimate: ~800 -->
步骤 5：保存分析报告
将摘要写入 .reports/codemap-diff.txt：
- 自上次扫描以来添加/删除/修改的文件
- 检测到的新依赖
- 架构变更（新路由、新服务等）
- 超过 90 天未更新的文档的过期警告
提示
- 关注高层结构，而非实现细节
- 优先使用文件路径和函数签名，而非完整代码块
- 每个代码地图保持在 1000 Token 以内，以便高效加载上下文
- 用 ASCII 图表代替冗长描述来展示数据流
- 在主要功能添加或重构会话后运行
第三部分：文档更新（Update Docs）
步骤 1：识别信息源
| 信息源 | 生成内容 |
|---|---|
package.json 脚本 |
可用命令参考 |
.env.example |
环境变量文档 |
openapi.yaml / 路由文件 |
API 端点参考 |
| 源代码导出 | 公共 API 文档 |
Dockerfile / docker-compose.yml |
基础设施设置文档 |
步骤 2：生成脚本参考
- 读取
package.json（或Makefile、Cargo.toml、pyproject.toml） - 提取所有脚本/命令及其描述
- 生成参考表：
| 命令 | 描述 |
|------|------|
| `npm run dev` | 启动开发服务器（支持热重载） |
| `npm run build` | 生产构建（含类型检查） |
| `npm test` | 运行测试套件（含覆盖率） |
步骤 3：生成环境变量文档
- 读取
.env.example（或.env.template、.env.sample） - 提取所有变量及其用途
- 分类为必需和可选
- 记录预期格式和有效值
| 变量 | 必需 | 描述 | 示例 |
|------|------|------|------|
| `DATABASE_URL` | 是 | PostgreSQL 连接字符串 | `postgres://user:pass@host:5432/db` |
| `LOG_LEVEL` | 否 | 日志详细级别（默认：info） | `debug`, `info`, `warn`, `error` |
步骤 4：更新贡献指南
生成或更新 docs/CONTRIBUTING.md，包含：
- 开发环境设置（前提条件、安装步骤）
- 可用脚本及其用途
- 测试流程（如何运行、如何编写新测试）
- 代码风格规范（Linter、Formatter、pre-commit Hook）
- PR 提交检查清单
步骤 5：更新运行手册（Runbook）
生成或更新 docs/RUNBOOK.md，包含：
- 部署流程（分步说明）
- 健康检查端点和监控
- 常见问题及解决方案
- 回滚流程
- 告警和升级路径
步骤 6：过期检查
- 查找超过 90 天未修改的文档文件
- 与最近的源代码变更交叉引用
- 标记可能过时的文档以供人工审查
规则
- 单一信息源：始终从代码生成，永远不要手动编辑生成的部分
- 保留手动部分：只更新生成的部分；保持手写内容不变
- 标记生成内容：在生成部分周围使用
<!-- AUTO-GENERATED -->标记 - 不主动创建文档：只在命令明确要求时创建新文档文件