Hookaido

概述

采用“配置优先”（config-first）工作流来实现和排查 Hookaido：编辑 Hookaidofile，验证配置，运行服务，测试入站（ingress）、拉取（pull）与执行（exec）流程，随后诊断队列健康状况及死信队列（DLQ）行为。

在本技能中，将 Hookaido v2.6.0 的模块化架构视为**增量式扩展能力**：默认保持现有工作流不变；仅当 postgres 模块、gRPC 工作者、子进程投递（deliver exec）或发布验证等功能对当前任务产生实质性助益时，才选择启用。

所有变更应保守、可逆，并在运行时操作前完成充分验证。

工作流

1. 确认目标拓扑结构：入站+拉取（HTTP 或 gRPC）、推送出站、子进程执行（subprocess exec）或内部队列，以及所用队列后端（sqlite、memory 或 postgres）。
2. 选择运行时模式，并确保 hookaido 可在工具执行位置被访问：
   • 主机二进制模式：使用 metadata.openclaw.install 中定义的安装动作。
   • 主机回退模式：运行 bash {baseDir}/scripts/install_hookaido.sh（固定版本 v2.6.0，SHA256 校验通过）。
   • 公共仓库/源码模式：当偏好基于源码安装时，通过 go install github.com/nuetzliches/hookaido/cmd/hookaido@v2.6.0 使用上游公共仓库 github.com/nuetzliches/hookaido。
   • Docker 沙箱模式：优先使用已预装 hookaido 的沙箱镜像；或通过 agents.defaults.sandbox.docker.setupCommand 在沙箱内安装。
   • 保留主机安装动作作为回退方案，并满足 metadata.openclaw.requires.bins 约束。
3. 以最小改动原则检查并更新 Hookaidofile。
4. 启动或重载前执行格式化与验证：
   • hookaido config fmt --config ./Hookaidofile
   • hookaido config validate --config ./Hookaidofile
   • 当涉及密钥引用（secret refs）或 Vault 支持的配置时，额外执行：hookaido config validate --config ./Hookaidofile --strict-secrets
5. 启动运行时并验证健康状态：
   • hookaido run --config ./Hookaidofile --db ./.data/hookaido.db
   • 若选用 queue postgres，则使用：hookaido run --config ./Hookaidofile --postgres-dsn "$HOOKAIDO_POSTGRES_DSN"
   • curl http://127.0.0.1:2019/healthz?details=1
6. 验证端到端行为：
   • 入站请求被成功接收并入队
   • 消费者路径（dequeue/ack/nack/extend）正常工作（支持 HTTP 拉取、批量 ack/nack，启用时还支持 gRPC 拉取）
7. 发生异常时，优先检查积压（backlog）与 DLQ，再进行变更操作。

任务手册

配置入站与拉取消费

1. 定义一条路由，明确指定认证方式与拉取路径（HTTP 拉取，可选启用 gRPC 拉取工作者监听器）。
2. 密钥始终存于环境变量或文件引用中，禁止内联写入。
3. 确保路由级认证与全局拉取认证逻辑一致。
4. 使用真实 webhook 负载及一次完整的 dequeue/ack 循环进行测试；若工作者吞吐量关键，应启用批量 ack/nack。

推荐以下基础配置：

ingress {
  listen :8080
}

pull_api {
  listen :9443
  grpc_listen :9943 # 可选的 gRPC 拉取工作者监听器
  auth token env:HOOKAIDO_PULL_TOKEN
}

/webhooks/github {
  auth hmac env:HOOKAIDO_INGRESS_SECRET
  pull { path /pull/github }
}

配置推送投递

1. 仅当允许外部服务直连本服务时，才启用推送投递模式。
2. 显式配置超时与重试策略。
3. 因投递语义为“至少一次”（at-least-once），需验证下游服务具备幂等性。

/webhooks/stripe {
  auth hmac env:STRIPE_SIGNING_SECRET
  deliver "https://billing.internal/stripe" {
    retry exponential max 8 base 2s cap 2m jitter 0.2
    timeout 10s
  }
}

配置子进程投递（deliver exec）

1. 当目标为本地脚本或二进制程序（而非 HTTP 服务）时，使用 exec 投递。
2. 负载通过 stdin 管道传入；元数据作为环境变量注入（如 HOOKAIDO_ROUTE、HOOKAIDO_EVENT_ID、HOOKAIDO_ATTEMPT 等）。
3. 退出码决定重试行为：0 表示成功确认（ack）；1–125 表示重试；126/127 表示立即进入 DLQ。
4. exec 模式不支持 sign 指令（编译时报错）。

/webhooks/github {
  auth hmac {
    provider github
    secret env:GITHUB_WEBHOOK_SECRET
  }
  deliver exec "/opt/hooks/deploy.sh" {
    timeout 30s
    retry exponential max 3 base 1s cap 30s jitter 0.2
    env DEPLOY_ENV production
    env NOTIFY_URL {env.SLACK_WEBHOOK_URL}
  }
}

配置提供商兼容的 HMAC 认证

1. 针对具有自定义签名格式的 webhook 提供商，使用 provider github、provider gitea、provider stripe 或 provider cituro。
2. 启用 provider 模式后，时间戳/随机数防重放保护将被禁用（因提供商不发送对应请求头）。
3. 在 provider 模式下，signature_header、timestamp_header、nonce_header 和 tolerance 均不可用（编译时报错）。

/webhooks/github {
  auth hmac {
    provider github
    secret env:GITHUB_WEBHOOK_SECRET
  }
  pull { path /pull/github }
}

/webhooks/gitea {
  auth hmac {
    provider gitea
    secret env:GITEA_WEBHOOK_SECRET
  }
  pull { path /pull/gitea }
}

/webhooks/stripe {
  auth hmac {
    provider stripe
    secret env:STRIPE_SIGNING_SECRET
  }
  pull { path /pull/stripe }
}

/webhooks/cituro {
  auth hmac {
    provider cituro
    secret env:CITURO_WEBHOOK_SECRET
  }
  pull { path /pull/cituro }
}

使用 SSE 流式传输（v2.5.3+）

1. SSE 替代轮询实现近实时 webhook 投递——请改用 GET {pull.path}/stream，而非重复调用 POST .../dequeue。
2. ACK/NACK 操作仍沿用现有 POST 接口，协议无变化。
3. 多个并发 SSE 连接构成竞争消费者关系。
4. 在路由的 pull 块中配置保活间隔（keepalive）与最大连接持续时间（max_duration）。

# 建立 SSE 流连接（持久化，服务端主动推送事件）
curl -sS -N "http://localhost:9443/pull/github/stream" 
  -H "Authorization: Bearer $HOOKAIDO_PULL_TOKEN"

# 确认已接收事件
curl -sS -X POST "http://localhost:9443/pull/github/ack" 
  -H "Authorization: Bearer $HOOKAIDO_PULL_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"lease_id":"lease_xyz"}'

配置队列后端

1. 除非任务明确要求临时开发模式或共享 Postgres 存储，否则默认使用 sqlite。
2. 将 memory 和 postgres 视为 v2 版本的**增量模块**，而非替代已有 sqlite 工作流的方案。
3. 使用 postgres 时，须记录 DSN 来源，并在启动后验证健康状态及积压接口响应。

推荐以下声明方式：

queue sqlite

queue memory

queue postgres

队列与 DLQ 运维

1. 从健康详情与积压接口入手。
2. 执行重新入队或删除操作前，务必先检查 DLQ 内容。
3. 若需批量重新入队，请说明预期影响及回滚路径。
4. 所有变更型管理调用均须提供明确的操作原因字符串（reason）。

可用接口如下：

• GET /healthz?details=1
• GET /backlog/trends
• GET /dlq
• POST /dlq/requeue
• POST /dlq/delete

启用 MCP 模式支持 AI 运维

1. 诊断类操作默认使用 --role read。
2. 仅在明确需要变更操作时启用写权限：
   • --enable-mutations --role operate --principal
3. 仅在管理员工作流中启用运行时控制能力：
   • --enable-runtime-control --role admin --pid-file
4. 所有变更调用必须包含具体、清晰的 reason 字段。

注册为 Claude Code MCP 插件

添加至 .claude/settings.json（或全局配置 ~/.claude/settings.json）：

{
  "mcpServers": {
    "hookaido": {
      "command": "hookaido",
      "args": [
        "mcp", "serve",
        "--config", "./Hookaidofile",
        "--db", "./.data/hookaido.db",
        "--role", "read"
      ]
    }
  }
}

启用操作角色（支持队列变更）时：

{
  "mcpServers": {
    "hookaido": {
      "command": "hookaido",
      "args": [
        "mcp", "serve",
        "--config", "./Hookaidofile",
        "--db", "./.data/hookaido.db",
        "--enable-mutations",
        "--role", "operate",
        "--principal", "claude"
      ]
    }
  }
}

MCP 服务端直接暴露结构化工具接口，无需解析 Shell 输出。Claude Code 启动时自动发现可用工具，并以类型安全的方式调用它们。

验证公开发布版本

1. 优先使用 Hookaido 公共仓库发布的官方发布资产。
2. 当供应链安全保障至关重要时，上线前须校验校验和、签名材料及出处证明（provenance）。
3. 默认保持验证为可选步骤，避免在非必要场景下加重既有技能流程负担。

使用命令：

• hookaido verify-release --checksums ./hookaido_v2.6.0_checksums.txt --require-provenance

验证清单

• hookaido config validate 在运行时启动/重载前返回成功。
• 当涉及密钥引用、Vault 配置或公开发布版本上线验证时，使用 hookaido config validate --strict-secrets。
• 健康检查端点可达，且报告的队列/后端状态符合预期。
• 拉取消费者可通过有效令牌完成 dequeue、ack、nack 和 extend 操作（支持 HTTP、SSE 及可选的 gRPC 传输），启用时亦支持批量 ack/nack。
• 推送模式下，重试与超时策略已显式配置。
• 子进程模式下，处理脚本具备可执行权限、能正确读取 stdin，并按规范使用退出码（0=ack，非零=重试，126/127=DLQ）。
• 若使用 queue postgres，运行时须通过 --postgres-dsn 或 HOOKAIDO_POSTGRES_DSN 启动。
• 任何 DLQ 变更操作均须限定范围、有据可依并完整记录。

安全规则

• 禁止为“让测试通过”而禁用认证机制。
• 禁止在只读诊断完成前建议直接执行变更操作。
• 视队列操作为“至少一次”语义，要求处理程序具备幂等性。
• 密钥必须存放于 env: 或 file: 引用中。

参考资料

• 参阅 references/operations.md 获取命令片段与 API 请求体模板。