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*\{
```