zhangshenao/harness9/debugging-guide

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