lionad-morotar/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

// 函数名 一句话功能描述。
//
// 输入示例:
//   - 参数名: 具体值（含类型说明）
//   - 参数名2: map[string]any{"key": "value"}
//
// 输出示例:
//   - 成功: 
//   - 失败: 
func FunctionName(param Type) (Result, error)

输入示例编写原则：

• 使用真实可运行的示例值
• 复杂结构体给出具体字段值
• 接口类型给出常见实现示例
• 如有多种调用方式，补充多个示例

输出示例编写原则：

• 必须覆盖成功和失败场景
• 失败场景给出典型错误类型
• 多返回值场景说明各返回值含义
• 如有副作用（如修改 context），需注明

5. 批量编辑

编辑顺序：

1. 从最底层（叶子节点）开始，自下而上
2. 同一层按文件分组，减少上下文切换
3. 优先处理被多个上层函数调用的公共函数
4. 保证组件的每一个 prop 都有一行注释

编辑技巧：

• 使用 Read 确认当前文件状态
• 使用 Edit 精确替换函数定义行
• 编辑后使用 Read 验证格式正确

输出格式

完成任务后，按以下格式汇报：

## 函数注释补全报告

### 调用链分析

入口函数: 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*\{