@comate/zulu 1.4.0-beta.2 → 1.4.0-beta.3

package/comate-engine/assets/skills/code-review/references/report-format.md

@@ -0,0 +1,41 @@
+# Review 报告输出格式
+
+用户需要在 10 秒内抓住关键问题。**简洁是第一优先级。**
+
+## 报告模板
+
+```markdown
+## Code Review 报告
+
+**X 个文件 | +Y/-Z 行 | 深度审查 | 风险：高**
+
+> 降级/分批/局部审查等特殊说明（无则省略）
+
+---
+
+### 🔴 P0 严重 (N)
+
+**1. [file.ts:42](file.ts#L42)** — 一句话描述风险和触发条件
+建议：一句话修复方向
+
+### 🟠 P1 高优 (N)
+
+**2. [file.ts:80](file.ts#L80)** — 一句话描述
+建议：一句话建议
+
+### 🟡 P2 中等 (N)
+
+### 🔵 P3 低优 (N)
+
+---
+
+**结论**：建议修复 P0/P1 后合入（或：审查通过，可直接合入）
+```
+
+## 输出规则
+
+1. 每条 finding **限 2 行**：问题描述 + 建议，各 1 句话
+2. 空级别直接省略，无问题写"审查通过"
+3. 使用可点击路径 `[src/file.ts:42](src/file.ts#L42)`
+4. 超过 10 条时：展示 P0/P1 全部 + P2/P3 各最多 3 条，末尾注明"另有 N 条，回复「展开」可查看"
+5. 来源维度不展示，用户追问时再补充

package/comate-engine/assets/skills/code-review/references/rules/Go/GO_AUTH_RULES.md

@@ -0,0 +1,29 @@
+# Go 接口鉴权规则
+
+检测对外接口的鉴权缺失与越权访问风险。
+
+---
+
+### AUTH_GO_01. 对外接口缺少鉴权 [high]
+- **检测**：HTTP handler 注册（`mux.Handle`/`router.GET` 等）但无身份校验中间件（JWT 解析/Session 验证），且非公开接口
+- **排除**：健康检查/登录注册/静态资源；全局鉴权中间件已覆盖；Webhook 回调
+
+### AUTH_GO_02. 越权访问 - 未校验资源归属 [high]
+- **检测**：handler 能从 context 获取用户身份，但操作资源时只用请求参数中的 ID，未校验资源归属
+- **排除**：管理员接口有角色校验；公共资源
+
+### AUTH_GO_03. 身份校验逻辑错误 [high]
+- **检测**：用非加密比较做 token 校验；校验变量来自请求参数而非解析后的 token；校验逻辑可被跳过
+- **排除**：使用 `hmac.Equal` 或安全比较库
+
+### AUTH_GO_04. 鉴权中间件配置遗漏 [middle]
+- **检测**：有鉴权中间件但部分路由组/路由前缀未被覆盖
+- **排除**：明确分开的公开/受保护路由组
+
+### AUTH_GO_05. 垂直越权 - 敏感操作缺少角色校验 [high]
+- **检测**：管理员级别操作（删除用户/修改权限等）未从 context 校验 role
+- **排除**：有 RBAC 中间件统一处理
+
+---
+
+**通用排除**：健康检查/登录/Webhook；全局鉴权中间件；框架内置权限管理

package/comate-engine/assets/skills/code-review/references/rules/Go/GO_CORRECTNESS_RULES.md

@@ -0,0 +1,111 @@
+# Go 正确性规则
+
+静态模式可识别的确定性错误，仅看代码结构即可判断，单次执行可触发。
+
+---
+
+## 一、空值与 nil 安全（4项）
+
+### CORRECTNESS_GO_01. 对 nil 指针进行方法调用或字段访问 [Critical]
+- **检测**：对可能为 nil 的指针直接访问字段或调用方法，无 nil 判断；接口断言未用 comma-ok 模式；map 取值后直接解引用
+- **排除**：有 nil 判断；上下文保证非 nil
+
+```go
+user := db.FindUser(id)
+name := user.Name // user 为 nil 时 panic
+
+s := i.(*MyStruct) // 断言失败时 panic，应用 s, ok := i.(*MyStruct)
+```
+
+### CORRECTNESS_GO_02. 未检查 context.WithCancel 返回的 cancel 函数 [Critical]
+- **检测**：`context.WithCancel`/`WithTimeout`/`WithDeadline` 返回的 cancel 未调用（用 `_` 丢弃，或在错误路径提前 return 前未执行）
+- **排除**：有 `defer cancel()`；cancel 在所有路径均有调用
+
+### CORRECTNESS_GO_03. 对 nil map 进行写操作 [Critical]
+- **检测**：map 类型字段或变量未通过 `make` 初始化就进行写操作，导致 `panic: assignment to entry in nil map`
+- **排除**：有 `make` 初始化；有 nil 判断后初始化
+
+### CORRECTNESS_GO_04. 切片越界访问 [Critical]
+- **检测**：访问切片索引前未校验长度；假设固定元素数量直接用索引；`parts[0]` 在可能为空切片上使用
+- **排除**：有 `len()` 检查；索引来源确认有界
+
+---
+
+## 二、类型与接口问题（3项）
+
+### CORRECTNESS_GO_05. 接口值与 nil 比较陷阱 [Critical]
+- **检测**：函数返回接口类型，但实际返回一个底层值为 nil 的具体类型指针（`return (*MyError)(nil)`），导致调用方 `if err != nil` 判断为 true
+- **排除**：直接 `return nil`
+
+```go
+func getError() error {
+    var p *MyError = nil
+    return p // 此时 err != nil 为 true！接口含有类型信息但值为 nil
+}
+// 正确：直接 return nil
+```
+
+### CORRECTNESS_GO_06. 类型断言未用 comma-ok 模式 [Critical]
+- **检测**：`v := i.(SomeType)` 未使用 `v, ok := i.(SomeType)` 形式，断言失败时 panic
+- **排除**：确认接口值类型；已有 recover
+
+```go
+// 错误写法 — 断言失败直接 panic
+s := i.(*MyStruct)
+
+// 正确写法
+s, ok := i.(*MyStruct)
+if !ok {
+    return errors.New("type assertion failed")
+}
+```
+
+### CORRECTNESS_GO_07. printf 格式化动词与参数类型不匹配 [Critical]
+- **检测**：`fmt.Printf`/`Sprintf`/`log.Printf` 格式化动词数量或类型与参数不匹配（如 `%s` 传 int，参数多于占位符）；直接 `log.Printf(err.Error())` 若含 `%` 则格式化出错
+- **排除**：`%v` 通用动词使用正确
+
+---
+
+## 三、代码静态检测（5项）
+
+### CORRECTNESS_GO_08. 不可达的死代码 [Critical]
+- **检测**：`return`/`panic` 语句之后存在永远不会执行的代码
+- **排除**：编译期可检出的场景（编译器通常已报告）
+
+### CORRECTNESS_GO_09. 布尔运算符使用错误 [Critical]
+- **检测**：布尔表达式中存在永真/永假条件（如 `x < 0 && x > 0`）；冗余条件（如 `err != nil || err == io.EOF`）
+- **排除**：防御性代码；逻辑确实正确
+
+### CORRECTNESS_GO_10. unsafe.Pointer 使用不当 [Critical]
+- **检测**：将 `unsafe.Pointer` 转换为 `uintptr` 后存储，再将 `uintptr` 转回指针（GC 可能已移动对象）
+- **排除**：原子操作中的合规用法；遵循 `unsafe.Pointer` 规则的转换
+
+### CORRECTNESS_GO_11. struct 字段 tag 格式错误 [Critical]
+- **检测**：struct tag 格式不合规，导致反射解析失败，JSON/ORM 行为异常
+- **排除**：工具已检查过格式
+
+```go
+// 错误写法 — 冒号后有空格（json: "name" 而非 json:"name"）
+type User struct {
+    Name string `json: "name"`  // 错误：冒号后有空格
+    Age  int    `json:"age,"`   // 错误：多余逗号
+}
+
+// 正确写法
+type User struct {
+    Name string `json:"name"`
+    Age  int    `json:"age"`
+}
+```
+
+### CORRECTNESS_GO_12. 测试/示例代码误用 [Critical]
+- **检测**：Example 函数的 `// Output:` 注释与实际输出不一致；测试函数名不以 `Test` 开头（如 `Testlogin`），导致测试用例永远不执行
+- **排除**：`// Unordered output:` 等合规注释形式
+
+---
+
+## 四、数值与逻辑（1项）
+
+### CORRECTNESS_GO_13. 整数溢出导致逻辑错误 [Critical]
+- **检测**：int32/int 类型做大数乘法（如金额×数量）结果溢出变负数；切片长度相加可能溢出（32位系统）
+- **排除**：已用 int64 或 math/big；值域确认不会溢出

package/comate-engine/assets/skills/code-review/references/rules/Go/GO_RESOURCE_CONCURRENCY_RULES.md

@@ -0,0 +1,190 @@
+# Go 资源并发类规则
+
+涵盖资源管理、内存泄漏、并发竞态、错误处理、性能及接口鉴权问题。
+
+---
+
+## 一、资源管理与内存泄漏
+
+### RES_GO_01. 文件/网络连接/数据库行未关闭 [high]
+- **检测**：`os.Open`/`http.Get`/`db.Query` 后未 `defer Close()`；HTTP 响应体 `resp.Body` 未关闭；`rows` 未调用 `rows.Close()`
+- **排除**：使用了自动管理资源的库；finally/defer 有关闭
+
+### RES_GO_02. goroutine 泄漏 [high]
+- **检测**：goroutine 阻塞在无消费者的 channel 发送；调用方超时/取消后 goroutine 因 channel 满/无缓冲永久阻塞；无退出条件的 `for {}` goroutine
+- **排除**：使用有缓冲 channel；有 `ctx.Done()` 退出；有 done 信号
+
+```go
+func handleRequest() {
+    ch := make(chan Result)        // 无缓冲
+    go func() { ch <- doWork() }()
+    select {
+    case r := <-ch: return r
+    case <-time.After(1 * time.Second): return // goroutine 泄漏：doWork 永久阻塞在发送
+    }
+}
+// 修复：ch := make(chan Result, 1)
+```
+
+### RES_GO_03. 全局缓存无限增长导致 OOM [high]
+- **检测**：全局 `var cache = make(map[...])` 只增不删，无 TTL/LRU/容量限制
+- **排除**：有定期清理；数量有界；使用带淘汰策略的缓存库
+
+### RES_GO_04. defer 在循环中导致资源延迟释放 [middle]
+- **检测**：循环体内 `defer f.Close()`，资源直到函数返回才释放，大批量时同时持有大量 fd
+- **排除**：循环次数极少（<5）；已提取为独立函数使 defer 生效
+
+---
+
+## 二、并发与竞态
+
+### RACE_GO_01. 全局变量并发读写无锁保护 [high]
+- **检测**：多 goroutine 并发读写同一 map/slice/结构体字段，无 `sync.Mutex`/`sync.RWMutex`/`atomic` 保护
+- **排除**：只读操作；有锁保护；使用 `sync.Map`
+
+### RACE_GO_02. 死锁导致服务挂起 [high]
+- **检测**：多 goroutine 加锁顺序不一致（A→B 和 B→A）；向无缓冲 channel 发送但无接收者；channel 操作无 select/超时
+- **排除**：固定加锁顺序；有 select+超时；有缓冲 channel
+
+### RACE_GO_03. sync.WaitGroup 使用不当 [high]
+- **检测**：`wg.Add(1)` 在 goroutine 内部调用（可能 Wait 已返回时还未 Add）；panic 路径导致 `Done()` 未调用（未用 defer）
+- **排除**：`wg.Add` 在 goroutine 启动前调用；`defer wg.Done()`
+
+```go
+// 错误写法 — Add 在 goroutine 内，可能 Wait 提前返回
+go func() {
+    wg.Add(1)      // 太晚了
+    defer wg.Done()
+    doWork()
+}()
+wg.Wait()
+
+// 正确写法
+wg.Add(1)
+go func() {
+    defer wg.Done()
+    doWork()
+}()
+wg.Wait()
+```
+
+### RACE_GO_04. 并发修改共享 slice 导致竞态 [high]
+- **检测**：多 goroutine 并发对同一 slice 执行 append 或索引赋值，无锁保护
+- **排除**：预分配 slice 且各 goroutine 操作不同索引；用 channel 收集结果
+
+---
+
+## 三、错误处理
+
+### ERR_GO_01. 忽略错误返回值 [high]
+- **检测**：函数返回 error 被 `_` 丢弃，或调用时直接忽略（`f.Write(data)` 不接收返回值）
+- **排除**：明确确认错误可忽略且有注释说明
+
+### ERR_GO_02. 错误被静默吞掉 [high]
+- **检测**：`recover()` 后不记录日志也不向上传递；接收 error 后 `_ = err`
+- **排除**：确认是预期的静默处理且有注释
+
+### ERR_GO_03. defer 中修改非命名返回值无效 [middle]
+- **检测**：在非命名返回值函数的 defer 中修改局部 `err` 变量，以为会影响返回值，实则无效
+- **排除**：使用命名返回值（`func f() (result string, err error)`）
+
+```go
+// 错误写法 — 修改的是局部变量，返回值不受影响
+func getUser() (string, error) {
+    var err error
+    defer func() {
+        if err != nil { err = fmt.Errorf("wrap: %w", err) } // 无效！
+    }()
+    return fetch()
+}
+
+// 正确写法 — 命名返回值
+func getUser() (name string, err error) {
+    defer func() {
+        if err != nil { err = fmt.Errorf("wrap: %w", err) } // 有效
+    }()
+    name, err = fetch()
+    return
+}
+```
+
+---
+
+## 四、性能
+
+### PERF_GO_01. 无限循环或轮询无 sleep 耗尽 CPU [high]
+- **检测**：`for {}` 内无 sleep/channel/ticker，CPU 空转；`for !done {}` 自旋等待
+- **排除**：有 `time.Sleep`；有 channel 等待；有 `ticker.C`
+
+### PERF_GO_02. N+1 查询 [middle]
+- **检测**：循环内对每条记录单独发起数据库查询
+- **排除**：循环次数确认极少；有 IN 批量查询
+
+---
+
+## 五、效率与正确性补充（4项）
+
+### EFF_GO_01. 可并行的串行 goroutine 等待 [middle]
+- **检测**：多个互不依赖的操作被顺序串行执行（逐个同步调用），而非启动多个 goroutine 并用 `sync.WaitGroup` 或 channel 并行等待
+- **排除**：后一个操作依赖前一个的返回值；操作间有顺序语义；并发写入同一资源
+
+```go
+// 反例 — 串行，总耗时 = tA + tB
+user, _ := fetchUser(uid)    // 同步阻塞
+config, _ := fetchConfig()   // 再同步阻塞
+
+// 正例 — 并行 goroutine
+var wg sync.WaitGroup
+var user User
+var cfg Config
+wg.Add(2)
+go func() { defer wg.Done(); user, _ = fetchUser(uid) }()
+go func() { defer wg.Done(); cfg, _ = fetchConfig() }()
+wg.Wait()
+```
+
+### EFF_GO_02. 文件/资源存在性预检查（TOCTOU） [low]
+- **检测**：操作前先调用 `os.Stat()`/`os.IsExist()` 检查存在性，再执行实际操作，形成 check-then-act 竞态
+- **排除**：业务逻辑确实需要分支且不可用错误处理替代；有文件锁保证原子性
+
+```go
+// 反例
+if _, err := os.Stat(path); err == nil {
+    data, _ = os.ReadFile(path)
+}
+
+// 正例 — 直接操作，检查错误类型
+data, err := os.ReadFile(path)
+if err != nil {
+    if errors.Is(err, os.ErrNotExist) {
+        // 文件不存在
+    } else {
+        return err
+    }
+}
+```
+
+### EFF_GO_03. 正则校验缺少锚点 [middle]
+- **检测**：用于输入校验的正则表达式缺少 `^` 和 `$` 锚点，`regexp.MatchString` 或 `re.FindString` 导致部分匹配通过本应拒绝的字符串
+- **排除**：明确需要部分匹配；已使用完整字符串匹配语义
+
+```go
+// 反例 — "123abc" 能通过纯数字校验
+matched, _ := regexp.MatchString(`\d+`, input)
+
+// 正例
+matched, _ := regexp.MatchString(`^\d+$`, input)
+```
+
+### EFF_GO_04. 错误链断裂（未使用 %w 包装） [middle]
+- **检测**：在错误处理中使用 `fmt.Errorf("msg: %v", err)` 或 `errors.New("msg")` 重新包装错误，未使用 `%w` 动词，导致 `errors.Is`/`errors.As` 无法在调用链上匹配原始错误类型
+- **排除**：有意隐藏底层错误类型（安全场景）；原始错误已在日志中记录
+
+```go
+// 反例 — %v 仅转为字符串，errors.Is() 无法匹配原始类型
+return fmt.Errorf("查询用户失败: %v", err)
+
+// 正例 — %w 保留错误链，errors.Is(err, sql.ErrNoRows) 可正常工作
+return fmt.Errorf("查询用户失败: %w", err)
+```
+