@pzy560117/codex-harness 0.1.2 → 0.1.4

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

@@ -1,183 +0,0 @@
----
-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

@@ -1,156 +0,0 @@
----
-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

@@ -1,274 +0,0 @@
----
-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

@@ -1,72 +0,0 @@
----
-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` 重新生成 |
-| 配置缓存问题 | 检查是否存在不可序列化的任务输入 |