/debugging-guide

name: debugging-guide
description: Use when debugging Go errors, test failures, or unexpected behavior — step-by-step diagnosis approach
trigger: debug, error, fail, crash, panic, fix, wrong

harness9 调试指南

诊断顺序

遇到问题时，按以下顺序排查：

1. 编译错误

go build ./...

常见原因：

• 未使用的 import → 删除或添加 `_` blank import
• 类型不匹配 → 检查接口实现是否完整
• 循环依赖 → 将接口定义移到使用者侧包中

2. 测试失败

# 详细输出
go test -v ./internal/engine/

# 单个测试
go test -v -run TestAgentLoop ./internal/engine/

# 带 race detector
go test -race ./...

3. 运行时 panic

查看完整 goroutine stack：

go run ./cmd/harness9 2>&1 | head -100

nil pointer panic 通常来自：

• 未初始化的 map（用 `make(map[K]V)` 初始化）
• 接口值为 nil 但调用了方法

4. Agent 行为异常

**LLM 不调用工具：** 检查工具的 `Definition()` 描述是否清晰，JSON Schema 是否正确。

**工具执行失败：** 查看 `ToolResult.IsError` 和 `Output` 字段，错误信息会回传给 LLM。

**无限循环：** 检查 `WithMaxTurns` 配置，默认 50 Turn。

常用调试技巧

打印 System Prompt

在 `internal/context/builder.go` 的 `Build()` 方法末尾临时添加：

fmt.Fprintf(os.Stderr, "=== SYSTEM PROMPT ===\n%s\n===================\n", prompt)

检查工具注册

在 `registry.Execute` 前打印可用工具列表：

for _, def := range registry.GetAvailableTools() {
    fmt.Fprintf(os.Stderr, "tool: %s\n", def.Name)
}

Provider 请求/响应

如需查看实际 API 请求，在 `internal/provider/openai.go` 中打印消息列表。

harness9 特有问题

Anthropic Provider：user/assistant 必须严格交替

症状：`400 Bad Request` 或 `invalid_request_error`

原因：Anthropic Messages API 禁止连续 assistant 消息。

修复：检查 `contextHistory` 的消息顺序，确保 system→user→assistant→user→assistant 交替。

路径沙箱拒绝访问

症状：工具返回 `路径超出工作区范围` 或类似错误

原因：路径包含 `../` 或绝对路径指向启动目录之外。

修复：Agent 应使用相对于启动目录的路径，如 `internal/engine/agent_loop.go` 而非 `/absolute/path/...`。

Skills 未加载

症状：Agent 不知道有 Skills 可用

检查： 1. `skills/` 目录是否在项目根目录（启动目录）下 2. 每个 Skill 是否在独立子目录中，且子目录内有 `SKILL.md` 文件 3. `SKILL.md` 是否包含 `name` 和 `description` frontmatter 字段 4. 启动日志中是否有 `[skills]` warn 输出

正确的目录结构示例：

skills/
├── go-coding-standards/
│   └── SKILL.md      ← 必须是这个文件名
└── debugging-guide/
    └── SKILL.md

go vet 常见 warning

| Warning | 含义 | 修复 | |---------|------|------| | `printf` 格式不匹配 | `%s` 传入了非 string 类型 | 修正格式或类型 | | `unreachable code` | return 后有代码 | 删除死代码 | | `loop variable captured` | goroutine 捕获了循环变量 | 传参而非捕获 |