xbot Hooks 系统设计

覆盖 17 种生命周期事件，支持 command/http/mcp_tool/callback 四种执行器，用户可通过 JSON 配置无代码扩展 agent 行为。

                    ┌─────────────────────┐
                    │    Hook Manager      │
                    │ (config load·dispatch│
                    │  match·decision agg) │
                    └─────────┬───────────┘
                              │
              ┌───────────────┼───────────────┐
              │               │               │
     ┌────────▼──────┐ ┌─────▼──────┐ ┌──────▼───────┐
     │ Matcher Engine │ │  Executors │ │ Config Layers│
     │                │ │            │ │              │
     │ tool name      │ │ command    │ │ user         │
     │ event glob     │ │ http       │ │ project      │
     │ regex          │ │ callback   │ │ local        │
     │ if-condition   │ │ mcp_tool   │ │              │
     └────────────────┘ └────────────┘ └──────────────┘

{
  "type": "command",
  "command": ".xbot/hooks/lint.sh",
  "timeout": 30,
  "async": false
}

• 事件载荷通过 stdin（JSON） 传入
• 退出码 0 = 成功，退出码 2 = 阻塞（deny）
• async: true 不阻塞 agent，适合日志/通知类 hook

{
  "type": "http",
  "url": "http://localhost:3000/api/build-trigger",
  "timeout": 10
}

• 事件载荷作为 POST body（Content-Type: application/json）
• 2xx = 成功，非 2xx = 非阻塞错误

type CallbackHook struct {
    Name string
    Fn   func(ctx context.Context, event Event) (*Result, error)
}

Logging、Timing、Approval 等内置 hook 使用此类型。

{
  "type": "mcp_tool",
  "server": "security",
  "tool": "scan_file",
  "input": { "path": "${tool_input.path}" }
}

${tool_input.path} 从事件载荷自动插值。

优先级：deny > defer > ask > allow。低优先级 deny 不可被高优先级 allow 覆盖。

三层合并：~/.xbot/hooks.json → <project>/.xbot/hooks.json → <project>/.xbot/hooks.local.json，后者覆盖前者。

{
  "enable_command_hooks": true,
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Shell",
        "hooks": [{
          "type": "command",
          "command": "PATH=\"$PATH:$(go env GOPATH)/bin\" make -C \"$XBOT_PROJECT_DIR\" lint || exit 2",
          "if": "Shell(*git commit*)",
          "timeout": 120
        }]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [{
          "type": "command",
          "command": ".xbot/hooks/context-loader.sh"
        }]
      }
    ]
  }
}

• enable_command_hooks 默认禁用 — 必须显式设为 true
• 最多 10 handler 每事件，总超时 60s
• 修改配置后需重启 CLI 生效
• 项目级 .xbot/hooks.json 可提交 git，本地 .xbot/hooks.local.json 不入版本控制

agent/agent.go
  Run() 启动 → Manager.Emit(SessionStart)
  Run() 结束 → Manager.Emit(SessionEnd)

agent/engine_run.go
  Run() 入口 → Manager.Emit(UserPromptSubmit)
  Run() 结束 → Manager.Emit(AgentStop)

agent/engine.go
  executeTool() 前 → Manager.Emit(PreToolUse)
  executeTool() 后 → Manager.Emit(PostToolUse)
  批量工具完成      → Manager.Emit(PostToolBatch)

agent/context_manager.go
  maybeCompress() 前 → Manager.Emit(PreCompact)
  maybeCompress() 后 → Manager.Emit(PostCompact)

agent/subagent.go
  创建 → Manager.Emit(SubAgentStart)
  完成 → Manager.Emit(SubAgentStop)