@pzy560117/codex-harness 0.1.4 → 0.1.5

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/go-build.md

@@ -0,0 +1,183 @@
+---
+description: 逐步修复Go构建错误、go vet警告和linter问题。调用go-build-resolver代理进行最小化、精确的修复。
+---
+
+# Go 构建与修复
+
+此命令调用 **go-build-resolver** 代理，以最小的更改增量修复 Go 构建错误。
+
+## 此命令的作用
+
+1. **运行诊断**：执行 `go build`、`go vet`、`staticcheck`
+2. **解析错误**：按文件分组并按严重性排序
+3. **增量修复**：一次修复一个错误
+4. **验证每次修复**：每次更改后重新运行构建
+5. **报告摘要**：显示已修复的内容和剩余问题
+
+## 何时使用
+
+在以下情况使用 `/go-build`：
+
+* `go build ./...` 因错误而失败
+* `go vet ./...` 报告问题
+* `golangci-lint run` 显示警告
+* 模块依赖关系损坏
+* 拉取更改后导致构建失败
+
+## 运行的诊断命令
+
+```bash
+# Primary build check
+go build ./...
+
+# Static analysis
+go vet ./...
+
+# Extended linting (if available)
+staticcheck ./...
+golangci-lint run
+
+# Module issues
+go mod verify
+go mod tidy -v
+```
+
+## 示例会话
+
+````text
+# Go Build 解析
+
+## 初始诊断
+
+```bash
+$ go build ./...
+internal/service/user.go:25:15: undefined: UserRepository
+internal/handler/api.go:42:9: cannot use x (type string) as type int
+internal/handler/api.go:58:2: missing return at end of function
+
+````
+
+发现错误：3
+
+## 修复 1：未定义的标识符
+
+文件：internal/service/user.go:25
+错误：undefined: UserRepository
+原因：缺少导入
+
+```go
+// Added import
+import "project/internal/repository"
+
+// Changed
+var repo UserRepository
+// To
+var repo repository.UserRepository
+```
+
+```bash
+$ go build ./...
+# 2 errors remaining
+```
+
+## 修复 2：类型不匹配
+
+文件：internal/handler/api.go:42
+错误：cannot use x (type string) as type int
+
+```go
+// Changed
+count := params.Get("count")
+// To
+countStr := params.Get("count")
+count, _ := strconv.Atoi(countStr)
+```
+
+```bash
+$ go build ./...
+# 1 error remaining
+```
+
+## 修复 3：缺少返回
+
+文件：internal/handler/api.go:58
+错误：missing return at end of function
+
+```go
+func GetUser(id string) (*User, error) {
+    if id == "" {
+        return nil, ErrInvalidID
+    }
+    user := findUser(id)
+    // Added missing return
+    return user, nil
+}
+```
+
+```bash
+$ go build ./...
+# Build successful!
+```
+
+## 最终验证
+
+```bash
+$ go vet ./...
+# No issues
+
+$ go test ./...
+ok      project/internal/service   0.015s
+ok      project/internal/handler   0.023s
+```
+
+## 摘要
+
+| 指标 | 数量 |
+|--------|-------|
+| 已修复的构建错误 | 3 |
+| 已修复的 Vet 警告 | 0 |
+| 已修改的文件 | 2 |
+| 剩余问题 | 0 |
+
+构建状态：PASS: 成功
+
+```
+## 常见错误修复
+
+| 错误 | 典型修复 |
+|-------|-------------|
+| `undefined: X` | 添加导入或修正拼写错误 |
+| `cannot use X as Y` | 类型转换或修正赋值 |
+| `missing return` | 添加返回语句 |
+| `X does not implement Y` | 添加缺失的方法 |
+| `import cycle` | 重构包结构 |
+| `declared but not used` | 移除或使用变量 |
+| `cannot find package` | `go get` 或 `go mod tidy` |
+
+## 修复策略
+
+1. **优先处理构建错误** - 代码必须能够编译
+2. **其次处理 vet 警告** - 修复可疑结构
+3. **再次处理 lint 警告** - 风格和最佳实践
+4. **一次修复一个问题** - 验证每个更改
+5. **最小化更改** - 不要重构，只修复
+
+## 停止条件
+
+在以下情况下，代理将停止并报告：
+- 相同错误经过 3 次尝试后仍然存在
+- 修复引入了更多错误
+- 需要架构性更改
+- 缺少外部依赖
+
+## 相关命令
+
+- `/go-test` - 构建成功后运行测试
+- `/go-review` - 审查代码质量
+- `/verify` - 完整验证循环
+
+## 相关
+
+- 代理: `agents/go-build-resolver.md`
+- 技能: `skills/golang-patterns/`
+```

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/go-review.md

@@ -0,0 +1,156 @@
+---
+description: 全面的Go代码审查，涵盖惯用模式、并发安全性、错误处理和安全性。调用go-reviewer代理。
+---
+
+# Go 代码审查
+
+此命令调用 **go-reviewer** 代理进行全面的 Go 语言特定代码审查。
+
+## 此命令的作用
+
+1. **识别 Go 变更**：通过 `git diff` 查找修改过的 `.go` 文件
+2. **运行静态分析**：执行 `go vet`、`staticcheck` 和 `golangci-lint`
+3. **安全扫描**：检查 SQL 注入、命令注入、竞态条件
+4. **并发性审查**：分析 goroutine 安全性、通道使用、互斥锁模式
+5. **惯用 Go 检查**：验证代码是否遵循 Go 约定和最佳实践
+6. **生成报告**：按严重程度分类问题
+
+## 使用时机
+
+在以下情况使用 `/go-review`：
+
+* 编写或修改 Go 代码之后
+* 提交 Go 变更之前
+* 审查包含 Go 代码的拉取请求时
+* 接手新的 Go 代码库时
+* 学习惯用 Go 模式时
+
+## 审查类别
+
+### 严重（必须修复）
+
+* SQL/命令注入漏洞
+* 无同步的竞态条件
+* Goroutine 泄漏
+* 硬编码凭证
+* 不安全的指针使用
+* 关键路径中忽略的错误
+
+### 高（应该修复）
+
+* 缺少带上下文的错误包装
+* 使用 panic 而非返回错误
+* 上下文未传播
+* 无缓冲通道导致死锁
+* 接口未满足错误
+* 缺少互斥锁保护
+
+### 中（考虑修复）
+
+* 非惯用代码模式
+* 导出项缺少 godoc 注释
+* 低效的字符串拼接
+* 切片未预分配
+* 未使用表格驱动测试
+
+## 运行的自动化检查
+
+```bash
+# Static analysis
+go vet ./...
+
+# Advanced checks (if installed)
+staticcheck ./...
+golangci-lint run
+
+# Race detection
+go build -race ./...
+
+# Security vulnerabilities
+govulncheck ./...
+```
+
+## 使用示例
+
+````text
+# Go 代码审查报告
+
+## 已审查文件
+- internal/handler/user.go（已修改）
+- internal/service/auth.go（已修改）
+
+## 静态分析结果
+✓ go vet: 无问题
+✓ staticcheck: 无问题
+
+## 发现的问题
+
+[严重] 竞态条件
+文件: internal/service/auth.go:45
+问题: 共享映射访问未同步
+```go
+var cache = map[string]*Session{}  // 并发访问！
+
+func GetSession(id string) *Session {
+    return cache[id]  // 竞态条件
+}
+````
+
+修复：使用 sync.RWMutex 或 sync.Map
+
+```go
+var (
+    cache   = map[string]*Session{}
+    cacheMu sync.RWMutex
+)
+
+func GetSession(id string) *Session {
+    cacheMu.RLock()
+    defer cacheMu.RUnlock()
+    return cache[id]
+}
+```
+
+\[高] 缺少错误上下文
+文件：internal/handler/user.go:28
+问题：返回的错误缺少上下文
+
+```go
+return err  // No context
+```
+
+修复：使用上下文包装
+
+```go
+return fmt.Errorf("get user %s: %w", userID, err)
+```
+
+## 摘要
+
+* 严重：1
+* 高：1
+* 中：0
+
+建议：FAIL: 在严重问题修复前阻止合并
+
+```
+## 批准标准
+
+| 状态 | 条件 |
+|--------|-----------|
+| PASS: 批准 | 无 CRITICAL 或 HIGH 级别问题 |
+| WARNING: 警告 | 仅有 MEDIUM 级别问题 (谨慎合并) |
+| FAIL: 阻止 | 发现 CRITICAL 或 HIGH 级别问题 |
+
+## 与其他命令的集成
+
+- 首先使用 `/go-test` 确保测试通过
+- 如果出现构建错误，请使用 `/go-build`
+- 提交前使用 `/go-review`
+- 对于非 Go 语言特定问题，请使用 `/code-review`
+
+## 相关
+
+- Agent: `agents/go-reviewer.md`
+- Skills: `skills/golang-patterns/`, `skills/golang-testing/`
+```

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/go-test.md

@@ -0,0 +1,274 @@
+---
+description: 为Go强制执行TDD工作流程。首先编写表驱动测试，然后实现。使用go test -cover验证80%以上的覆盖率。
+---
+
+# Go TDD 命令
+
+此命令使用惯用的 Go 测试模式，为 Go 代码强制执行测试驱动开发方法。
+
+## 此命令的作用
+
+1. **定义类型/接口**：首先搭建函数签名
+2. **编写表驱动测试**：创建全面的测试用例（RED 阶段）
+3. **运行测试**：验证测试因正确原因而失败
+4. **实现代码**：编写最少的代码以通过测试（GREEN 阶段）
+5. **重构**：改进代码，同时保持测试通过
+6. **检查覆盖率**：确保 80% 以上的覆盖率
+
+## 何时使用
+
+在以下情况下使用 `/go-test`：
+
+* 实现新的 Go 函数时
+* 为现有代码添加测试覆盖率时
+* 修复 bug 时（先编写失败的测试）
+* 构建关键业务逻辑时
+* 学习 Go 中的 TDD 工作流程时
+
+## TDD 循环
+
+```
+RED     → 编写失败的表格驱动测试
+GREEN   → 实现最小化代码以通过测试
+REFACTOR → 改进代码，保持测试通过
+REPEAT  → 下一个测试用例
+```
+
+## 示例会话
+
+````
+用户: /go-test 我需要一个验证电子邮箱地址的函数
+
+代理:
+# TDD 会话: 电子邮件验证器
+
+## 步骤 1: 定义接口
+
+```go
+// validator/email.go
+package validator
+
+// ValidateEmail 检查给定的字符串是否为有效的电子邮件地址。
+// 如果有效则返回 nil，否则返回描述问题的错误。
+func ValidateEmail(email string) error {
+    panic("not implemented")
+}
+```
+
+## 步骤 2: 编写表驱动测试 (RED)
+
+```go
+// validator/email_test.go
+package validator
+
+import (
+    "testing"
+)
+
+func TestValidateEmail(t *testing.T) {
+    tests := []struct {
+        name    string
+        email   string
+        wantErr bool
+    }{
+        // 有效邮箱
+        {"simple email", "user@example.com", false},
+        {"with subdomain", "user@mail.example.com", false},
+        {"with plus", "user+tag@example.com", false},
+        {"with dots", "first.last@example.com", false},
+
+        // 无效邮箱
+        {"empty string", "", true},
+        {"no at sign", "userexample.com", true},
+        {"no domain", "user@", true},
+        {"no local part", "@example.com", true},
+        {"double at", "user@@example.com", true},
+        {"spaces", "user @example.com", true},
+        {"no tld", "user@example", true},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            err := ValidateEmail(tt.email)
+            if tt.wantErr && err == nil {
+                t.Errorf("ValidateEmail(%q) = nil; want error", tt.email)
+            }
+            if !tt.wantErr && err != nil {
+                t.Errorf("ValidateEmail(%q) = %v; want nil", tt.email, err)
+            }
+        })
+    }
+}
+```
+
+## 步骤 3: 运行测试 - 验证失败
+
+```bash
+$ go test ./validator/...
+
+--- FAIL: TestValidateEmail (0.00s)
+    --- FAIL: TestValidateEmail/simple_email (0.00s)
+        panic: not implemented
+
+FAIL
+```
+
+✓ 测试按预期失败 (panic)。
+
+## 步骤 4: 实现最小化代码 (GREEN)
+
+```go
+// validator/email.go
+package validator
+
+import (
+    "errors"
+    "regexp"
+)
+
+var emailRegex = regexp.MustCompile(`^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$`)
+
+var (
+    ErrEmailEmpty   = errors.New("email cannot be empty")
+    ErrEmailInvalid = errors.New("email format is invalid")
+)
+
+func ValidateEmail(email string) error {
+    if email == "" {
+        return ErrEmailEmpty
+    }
+    if !emailRegex.MatchString(email) {
+        return ErrEmailInvalid
+    }
+    return nil
+}
+```
+
+## 步骤 5: 运行测试 - 验证通过
+
+```bash
+$ go test ./validator/...
+
+PASS
+ok      project/validator    0.003s
+```
+
+✓ 所有测试通过！
+
+## 步骤 6: 检查覆盖率
+
+```bash
+$ go test -cover ./validator/...
+
+PASS
+coverage: 100.0% of statements
+ok      project/validator    0.003s
+```
+
+✓ 覆盖率: 100%
+
+## TDD 完成！
+````
+
+## 测试模式
+
+### 表驱动测试
+
+```go
+tests := []struct {
+    name     string
+    input    InputType
+    want     OutputType
+    wantErr  bool
+}{
+    {"case 1", input1, want1, false},
+    {"case 2", input2, want2, true},
+}
+
+for _, tt := range tests {
+    t.Run(tt.name, func(t *testing.T) {
+        got, err := Function(tt.input)
+        // assertions
+    })
+}
+```
+
+### 并行测试
+
+```go
+for _, tt := range tests {
+    tt := tt // Capture
+    t.Run(tt.name, func(t *testing.T) {
+        t.Parallel()
+        // test body
+    })
+}
+```
+
+### 测试辅助函数
+
+```go
+func setupTestDB(t *testing.T) *sql.DB {
+    t.Helper()
+    db := createDB()
+    t.Cleanup(func() { db.Close() })
+    return db
+}
+```
+
+## 覆盖率命令
+
+```bash
+# Basic coverage
+go test -cover ./...
+
+# Coverage profile
+go test -coverprofile=coverage.out ./...
+
+# View in browser
+go tool cover -html=coverage.out
+
+# Coverage by function
+go tool cover -func=coverage.out
+
+# With race detection
+go test -race -cover ./...
+```
+
+## 覆盖率目标
+
+| 代码类型 | 目标 |
+|-----------|--------|
+| 关键业务逻辑 | 100% |
+| 公共 API | 90%+ |
+| 通用代码 | 80%+ |
+| 生成的代码 | 排除 |
+
+## TDD 最佳实践
+
+**应该做：**
+
+* 先编写测试，再编写任何实现
+* 每次更改后运行测试
+* 使用表驱动测试以获得全面的覆盖率
+* 测试行为，而非实现细节
+* 包含边界情况（空值、nil、最大值）
+
+**不应该做：**
+
+* 在编写测试之前编写实现
+* 跳过 RED 阶段
+* 直接测试私有函数
+* 在测试中使用 `time.Sleep`
+* 忽略不稳定的测试
+
+## 相关命令
+
+* `/go-build` - 修复构建错误
+* `/go-review` - 在实现后审查代码
+* `/verify` - 运行完整的验证循环
+
+## 相关
+
+* 技能：`skills/golang-testing/`
+* 技能：`skills/tdd-workflow/`

package/package-source/docs/codex-harness-engineering/templates/package-assets/docs/ecc-zh-CN/commands/gradle-build.md

@@ -0,0 +1,72 @@
+---
+description: 修复 Android 和 KMP 项目的 Gradle 构建错误
+---
+
+# Gradle 构建修复
+
+逐步修复 Android 和 Kotlin 多平台项目的 Gradle 构建和编译错误。
+
+## 步骤 1：检测构建配置
+
+识别项目类型并运行相应的构建：
+
+| 指示符 | 构建命令 |
+|-----------|---------------|
+| `build.gradle.kts` + `composeApp/` (KMP) | `./gradlew composeApp:compileKotlinMetadata 2>&1` |
+| `build.gradle.kts` + `app/` (Android) | `./gradlew app:compileDebugKotlin 2>&1` |
+| `settings.gradle.kts` 包含模块 | `./gradlew assemble 2>&1` |
+| 配置了 Detekt | `./gradlew detekt 2>&1` |
+
+同时检查 `gradle.properties` 和 `local.properties` 以获取配置信息。
+
+## 步骤 2：解析并分组错误
+
+1. 运行构建命令并捕获输出
+2. 将 Kotlin 编译错误与 Gradle 配置错误分开
+3. 按模块和文件路径分组
+4. 排序：先处理配置错误，然后按依赖顺序处理编译错误
+
+## 步骤 3：修复循环
+
+针对每个错误：
+
+1. **读取文件** — 错误行周围的完整上下文
+2. **诊断** — 常见类别：
+   * 缺少导入或无法解析的引用
+   * 类型不匹配或不兼容的类型
+   * `build.gradle.kts` 中缺少依赖项
+   * Expect/actual 不匹配 (KMP)
+   * Compose 编译器错误
+3. **最小化修复** — 解决错误所需的最小改动
+4. **重新运行构建** — 验证修复并检查新错误
+5. **继续** — 处理下一个错误
+
+## 步骤 4：防护措施
+
+如果出现以下情况，请停止并询问用户：
+
+* 修复引入的错误比解决的错误多
+* 同一错误在 3 次尝试后仍然存在
+* 错误需要添加新的依赖项或更改模块结构
+* Gradle 同步本身失败（配置阶段错误）
+* 错误出现在生成的代码中（Room、SQLDelight、KSP）
+
+## 步骤 5：总结
+
+报告：
+
+* 已修复的错误（模块、文件、描述）
+* 剩余的错误
+* 引入的新错误（应为零）
+* 建议的后续步骤
+
+## 常见的 Gradle/KMP 修复方案
+
+| 错误 | 修复方法 |
+|-------|-----|
+| `commonMain` 中无法解析的引用 | 检查依赖项是否在 `commonMain.dependencies {}` 中 |
+| Expect 声明没有 actual 实现 | 在每个平台源码集中添加 `actual` 实现 |
+| Compose 编译器版本不匹配 | 在 `libs.versions.toml` 中统一 Kotlin 和 Compose 编译器版本 |
+| 重复类 | 使用 `./gradlew dependencies` 检查是否存在冲突的依赖项 |
+| KSP 错误 | 运行 `./gradlew kspCommonMainKotlinMetadata` 重新生成 |
+| 配置缓存问题 | 检查是否存在不可序列化的任务输入 |