read-codebase

# Read Codebase Skill 用于阅读和理解棕地（Brownfield）项目代码库，提供智能代码分析和文档补充能力。 ## 模式一（默认执行）：函数注释补全 当用户输入包含函数路径或要求补充函数注释时，执行此模式。 ### 执行步骤 #### 1. 识别目标函数 - 从用户输入中提取目标函数的文件路径和行号 - 如果没有明确行号，使用 Grep 搜索函数定义 - 读取函数签名和上下文（前后 50 行） - 如果没有明确行号，则尝试高层次洞见整个文件 #### 2. 递归扫描调用链 **广度优先遍历（BFS）策略：** ``` Level 0: 入口函数（用户指定函数、或默认整个文件、组件、模块） Level 1: 入口函数体内直接调用的所有函数 Level 2: Level 1 函数调用的所有函数 Level 3+: 继续递归直到叶子节点 ``` **扫描范围（按优先级）：** | 优先级 | 类型 | 说明 | |-------|------|------| | P0 | 项目内部函数 | 必须补充，核心业务逻辑 | | P1 | 接口方法 | 组件接口、组件 props 等 | | P2 | 工具/辅助函数 | 必须补充，提高可读性 | | P3 | 标准库函数 | 简要说明，不强制 | | P4 | 第三方库函数 | 简要说明，不强制 | **扫描技巧：** - 使用 `Grep` 查找函数定义位置 - 使用 `LSP` 的 `incomingCalls`/`outgoingCalls` 获取调用关系 - 对于接口类型，找到所有实现并分别处理 #### 3. 判断是否需要补充注释 **已有注释的检查：** - 函数定义前是否有 `//` 开头的注释块 - 注释是否包含功能描述 - 注释是否包含输入/输出示例 - 每一个组件 prop 都要有一行简短的注释，复杂 prop 酌情增加注释量 **无需补充的情况：** - 已有完整注释（描述 + 示例） - 私有函数（小写开头）且逻辑极简单（<5 行） - Getter/Setter 等样板代码 - 明显的回调函数（如 `http.HandlerFunc`） #### 4. 生成注释 **格式规范：** * TypeScript：JSDoc ```go // 函数名 一句话功能描述。 // // 输入示例: // - 参数名: 具体值（含类型说明） // - 参数名2: map[string]any{"key": "value"} // // 输出示例: // - 成功: // - 失败: func FunctionName(param Type) (Result, error) ``` **输入示例编写原则：** - 使用真实可运行的示例值 - 复杂结构体给出具体字段值 - 接口类型给出常见实现示例 - 如有多种调用方式，补充多个示例 **输出示例编写原则：** - 必须覆盖成功和失败场景 - 失败场景给出典型错误类型 - 多返回值场景说明各返回值含义 - 如有副作用（如修改 context），需注明 #### 5. 批量编辑 **编辑顺序：** 1. 从最底层（叶子节点）开始，自下而上 2. 同一层按文件分组，减少上下文切换 3. 优先处理被多个上层函数调用的公共函数 4. 保证组件的每一个 prop 都有一行注释 **编辑技巧：** - 使用 `Read` 确认当前文件状态 - 使用 `Edit` 精确替换函数定义行 - 编辑后使用 `Read` 验证格式正确 ### 输出格式 完成任务后，按以下格式汇报： ```markdown ## 函数注释补全报告 ### 调用链分析 ``` 入口函数: pkg/service/handler.go:45 HandleRequest ├── Level 1 │ ├── pkg/utils/validator.go:23 ValidateInput │ └── pkg/db/query.go:67 GetUser │ └── Level 2 │ ├── pkg/db/conn.go:12 OpenConnection │ └── pkg/cache/redis.go:34 GetCache └── Level 1 └── pkg/log/logger.go:89 Infof ``` ### 已补充注释的函数 | 文件 | 行号 | 函数名 | 层级 | |------|------|--------|------| | pkg/service/handler.go | 45 | HandleRequest | Level 0 | | pkg/utils/validator.go | 23 | ValidateInput | Level 1 | | pkg/db/query.go | 67 | GetUser | Level 1 | | pkg/db/conn.go | 12 | OpenConnection | Level 2 | | pkg/cache/redis.go | 34 | GetCache | Level 2 | ### 跳过补充的函数 | 文件 | 函数名 | 原因 | |------|--------|------| | pkg/log/logger.go | Infof | 标准库风格，已有注释 | 总计：补充 [Z 个组件，][X 个函数，][跳过 Y 个函数] ``` ## 最佳实践 ### 注释质量检查清单 - [ ] 描述以函数名开头，形成完整句子 - [ ] 输入示例包含具体值，不是类型名 - [ ] 输出示例覆盖成功和失败场景 - [ ] 复杂业务逻辑说明关键决策点 - [ ] 错误返回值说明触发条件 ### 性能优化 - 大型项目（>1000 文件）时，限制扫描深度（建议 max 3 层） - 使用并行 Grep 加速函数定位 - 缓存已分析的函数签名，避免重复读取 ### 常见陷阱 1. **循环依赖**: 调用链成环时，标记已访问函数避免无限递归 2. **接口多实现**: 接口方法需找到所有实现分别补充 3. **泛型函数**: Go 泛型函数需保留类型参数示例 4. **内联函数**: 小函数可能被编译器内联，注释价值低 ## 工具使用指南 ### 推荐工具组合 | 场景 | 工具 | 用法 | |------|------|------| | 查找函数定义 | Grep | `pattern: "func FunctionName"` | | 查找调用关系 | LSP | `operation: outgoingCalls` | | 读取函数上下文 | Read | `limit: 50, offset: line-10` | | 批量编辑 | Edit | 精确定位函数定义行 | ### Grep 模式示例 ``` # 查找函数定义 func\s+\w+\s*\(.*\)\s*\{? # 查找方法定义（带接收器） func\s*\([^)]+\)\s*\w+\s*\( # 查找接口定义 type\s+\w+\s+interface\s*\{ ```