背景

当前 auto-harness 已具备 Codex NPC 运行能力，但外部系统如何以统一方式接入、触发、查询和回传结果还缺少标准 API 文档和稳定接口约定。需要建立一套可对接的标准文档与接口设计，让第三方系统、平台或内部服务都能用统一方式接入。

目标

设计并落地 auto-harness 的统一外部系统对接 API 文档和接口约定，覆盖“外部系统触发任务 -> auto-harness 分派 Codex/NPC 执行 -> 查询状态/事件 -> 获取结果/评论/提交信息”的完整链路。

工作范围

1. 梳理当前已有接口和运行路径：

   • ACP HTTP server：/healthz、/rpc、/events
   • JSON-RPC 方法：session/new、chat/sendMessage、session/listModels 等
   • CNB NPC 入口：auto-harness npc
   • runner 执行模型和结果结构

2. 设计统一对接接口规范：

   • 外部系统认证与鉴权方案，至少给出 token/header 约定和安全边界。
   • 任务创建接口：统一描述 repo、branch、issue/pr、prompt、runner、callback 等字段。
   • 状态查询接口：任务状态、runner、commit、验证结果、错误信息。
   • 事件流接口：任务开始、工具执行、代码变更、测试结果、完成/失败。
   • 结果回传接口：最终消息、文件/制品、commit SHA、PR/Issue 评论信息。
   • 错误码和重试语义。

3. 输出标准 API 文档：

   • 建议放在 docs/integration-api.md。
   • 包含接口概览、认证、数据模型、请求/响应示例、错误码、幂等和安全说明。
   • 给出至少 2 个端到端示例：Issue 触发开发任务、外部系统直接提交开发任务。

4. 如现有代码缺少必要接口，补充最小可运行实现或明确设计边界：

   • 优先复用现有 /rpc 和 /events。
   • 可新增轻量 HTTP wrapper，但不要引入大型框架。
   • 新增接口必须有测试或可执行 smoke 验证。

5. 补充测试与验证：

   • go test ./... 必须通过。
   • 如新增 HTTP 接口，提供 curl 示例或 Go 测试覆盖核心路径。
   • README 增加指向 docs/integration-api.md 的入口。

非目标

• 不实现复杂 OAuth/OIDC 全流程，只定义可扩展鉴权契约。
• 不重构整个 ACP 协议。
• 不引入数据库或长期任务存储，除非现有代码已有对应抽象可复用。

验收标准

• 新增或更新标准 API 文档，文档可被外部系统直接用于对接。
• 统一接口字段和状态模型清晰，包含请求/响应 JSON 示例。
• 如果新增代码，必须有测试或 smoke 验证。
• go test ./... 通过。
• 最终在 Issue 评论中写清：变更文件、接口设计摘要、验证结果、分支、完整 commit SHA、是否已 push。

@codex 请按 Codex NPC 工作流完成这个任务。

执行要求：

1. 先读取本 Issue 的完整详情和评论，再开始实现。
2. 基于最新 origin/main 新建独立 worktree 和分支：codex/issue-28-integration-api。
3. 优先产出标准 API 文档 docs/integration-api.md，并根据需要补充最小代码/测试。
4. 必须运行 go test ./...。
5. 完成后提交代码并 push 分支。
6. 最终评论本 Issue，写清：变更文件、接口设计摘要、验证结果、分支、完整 commit SHA、是否已 push。

@aiedulab/auto-harness(codex) 请按 Codex NPC 工作流完成这个任务。

执行要求：

1. 先读取本 Issue 的完整详情和评论，再开始实现。
2. 基于最新 origin/main 新建独立 worktree 和分支：codex/issue-28-integration-api。
3. 优先产出标准 API 文档 docs/integration-api.md，并根据需要补充最小代码/测试。
4. 必须运行 go test ./...。
5. 完成后提交代码并 push 分支。
6. 最终评论本 Issue，写清：变更文件、接口设计摘要、验证结果、分支、完整 commit SHA、是否已 push。

@aiedulab/auto-harness(codex) 请按 Codex NPC 工作流完成这个任务。

这次触发使用已修复的 NPC 角色注册和 latest 镜像。执行要求：

1. 先读取本 Issue 的完整详情和评论，再开始实现。
2. 基于最新 origin/main 新建独立 worktree 和分支：codex/issue-28-integration-api。
3. 优先产出标准 API 文档 docs/integration-api.md，并根据需要补充最小代码/测试。
4. 必须运行 go test ./...。
5. 完成后提交代码并 push 分支。
6. 最终评论本 Issue，写清：变更文件、接口设计摘要、验证结果、分支、完整 commit SHA、是否已 push。

@aiedulab/auto-harness(codex) 请按 Codex NPC 工作流完成这个任务。

这次触发使用已修复的 linux/amd64 latest 镜像。执行要求：

1. 先读取本 Issue 的完整详情和评论，再开始实现。
2. 基于最新 origin/main 新建独立 worktree 和分支：codex/issue-28-integration-api。
3. 优先产出标准 API 文档 docs/integration-api.md，并根据需要补充最小代码/测试。
4. 必须运行 go test ./...。
5. 完成后提交代码并 push 分支。
6. 最终评论本 Issue，写清：变更文件、接口设计摘要、验证结果、分支、完整 commit SHA、是否已 push。

@aiedulab/auto-harness(codex) 请按 Codex NPC 工作流完成这个任务。

这次触发使用已修复的 latest 镜像：linux/amd64 manifest 可拉取，且 CNB skills 已按单个 Codex skill 暴露。执行要求：

1. 先读取本 Issue 的完整详情和评论，再开始实现。
2. 基于最新 origin/main 新建独立 worktree 和分支：codex/issue-28-integration-api。
3. 优先产出标准 API 文档 docs/integration-api.md，并根据需要补充最小代码/测试。
4. 必须运行 go test ./...。
5. 完成后提交代码并 push 分支。
6. 最终评论本 Issue，写清：变更文件、接口设计摘要、验证结果、分支、完整 commit SHA、是否已 push。

@aiedulab/auto-harness(codex) 重新触发：已修复 NPC 注册、Codex CLI 参数、latest amd64 镜像、skills 布局，并增加 Codex 失败输出透传。请按 Issue 要求执行任务并在完成后评论结果。

@aiedulab/auto-harness(codex) 重新触发：已修复模型认证逻辑，Codex 默认使用 CNB_TOKEN_FOR_AI / CNB_TOKEN_FOR_CODEBUDDY，不再把 CNB_TOKEN 当 OpenAI key。请按 Issue 要求执行任务并评论结果。

@aiedulab/auto-harness(codex) 重新触发：已把 NPC token 显式注入 Codex 的 CODEX_API_KEY / OPENAI_API_KEY，并在配置中声明 env_key=CODEX_API_KEY。请按 Issue 要求执行任务并评论结果。

@aiedulab/auto-harness(codex) 重新触发：已移除 NPC 的固定 CODEX_CONFIG_TEMPLATE，运行时会按 CNB_API_ENDPOINT + CNB_REPO_SLUG 生成仓库 AI 网关配置。请按 Issue 要求执行任务并评论结果。

@aiedulab/auto-harness(codex) 重新触发：已隔离 NPC 运行时 CODEX_HOME=/tmp/codex-npc，避免仓库 .codex/config.toml 覆盖运行时生成的 CNB 仓库 AI 网关配置。请按 Issue 要求执行任务并评论结果。

@aiedulab/auto-harness(codex) 重新触发：已修复 CNB AI endpoint，NPC 运行时现在使用 /-/ai，并将 CODEX_HOME 放到 /workspace/.codex-npc-runtime。请按 Issue 要求执行任务并评论结果。

@aiedulab/auto-harness(codex) 重新触发：已将 CODEX_API_KEY 直接配置到 NPC pipeline 文件中，不再走 secret repo/import。请按 Issue 要求执行任务并评论结果。

@aiedulab/auto-harness(codex)

帷幄庸者，已按 Issue #28 要求完成实现并生成本地提交，但当前 CNB token 缺少 repo-code:rw 权限，push 被远端拒绝。

变更文件：

• docs/integration-api.md：新增外部系统统一对接 API 文档，覆盖接口概览、认证与鉴权、任务模型、任务创建、状态查询、事件流、结果回传、错误码、幂等/重试、安全边界，以及 2 个端到端示例（Issue 触发开发任务、外部系统直接提交开发任务）。
• README.md：在 ACP HTTP Contract 章节增加指向 docs/integration-api.md 的入口。

接口设计摘要：

• 以现有 ACP HTTP surface 为基础：GET /healthz、POST /rpc、GET /events?sid=。
• 统一任务创建映射到 session/new + chat/sendMessage，sessionId 作为 taskId/幂等键。
• 事件流复用 /events SSE，并定义 task.started、tool.executed、code.changed、verification.completed、task.completed、task.failed 等外部事件归一化语义。
• 结果回传定义最终消息、文件/制品、commit SHA、评论信息、验证结果和错误字段；callback 建议使用 HMAC 签名和按 taskId 幂等处理。
• 认证约定使用 Authorization: Bearer 或网关场景下的 X-Auto-Harness-Token，并明确 token scope 与 secret 不外传边界。

验证结果：

• /usr/local/go/bin/go test ./... 通过。

分支：codex/issue-28-integration-api
完整 commit SHA：a700936fbfa994ad5c2bfa35b2ebf5cdcb92a444
是否已 push：否。执行 git push origin HEAD 时远端返回 403：当前凭据不具备 repo-code:rw 权限。

剩余风险/下一步：需要为当前 NPC pipeline token 授予 repo-code:rw 权限，或由有权限的账号在本地 worktree /root/.config/superpowers/worktrees/auto-harness/issue-28-integration-api 推送该分支。

@aiedulab/auto-harness(codex) 重新触发：已改为提交 .codex/auth.json 文件并移除 env_key / CODEX_API_KEY 环境变量依赖；本地同镜像 smoke 已验证只靠文件认证可成功。请按 Issue 要求执行任务并评论结果。

@aiedulab/auto-harness(codex)

帷幄庸者，已按 Issue #28 要求完成外部系统统一对接 API 文档与接口规范，并生成本地提交；但推送仍被远端拒绝，原因是当前运行凭据缺少 repo-code:rw 权限。

变更文件：

• docs/integration-api.md：新增统一外部系统对接 API 文档，覆盖接口概览、认证与鉴权、Task/TaskRequest/TaskResult 数据模型、任务创建、状态查询、SSE 事件流、结果回传 callback、错误码、幂等与重试、安全边界，以及 2 个端到端示例。
• README.md：在 ACP HTTP Contract 章节增加 docs/integration-api.md 入口。

接口设计摘要：

• 复用现有 ACP HTTP surface：GET /healthz、POST /rpc、GET /events?sid=<sessionId>。
• 统一任务创建映射为 session/new + chat/sendMessage，将 sessionId 作为外部 taskId 和幂等关联键。
• 事件流复用 /events SSE，并给出 task.started、tool.executed、code.changed、verification.completed、task.completed、task.failed 的归一化映射。
• 结果回传定义最终消息、文件/制品、commit SHA、Issue/PR 评论信息、验证结果和错误结构；callback 建议使用 HMAC 签名与幂等去重。
• 鉴权约定使用 Authorization: Bearer <integration-token>，网关场景可使用 X-Auto-Harness-Token；文档明确 token scope、安全边界和 secret 不外传要求。
• 现有代码缺口已在文档中明确边界：当前没有持久化 GET /tasks/{taskId}，session/artifacts 仍是扩展点，认证强制校验建议放在网关或后续轻量 wrapper。

验证结果：

• /usr/local/go/bin/go test ./... 通过。

分支：codex/issue-28-integration-api
完整 commit SHA：1a0ca6994d1c5d66010302f95f1d555a16092d1b
是否已 push：否。执行 git push origin HEAD:codex/issue-28-integration-api 时远端返回 403：当前凭据不具备 repo-code:rw 权限。

剩余风险/下一步：需要为当前 NPC pipeline 使用的 CNB 凭据授予 repo-code:rw 权限，或由有权限账号在 worktree /root/.config/superpowers/worktrees/auto-harness/issue-28-integration-api 推送该分支。

@aiedulab/auto-harness(codex) 重新触发验证：NPC pipeline 已直接配置 Git 写入 token，并发布 latest 镜像。请按 Issue 要求执行任务，重点确认完成后能 push 分支 codex/issue-28-integration-api，最终评论写清完整 commit SHA、分支、是否已 push。

@aiedulab/auto-harness(codex)

帷幄庸者，Issue #28 已按要求完成并推送。

变更文件：

• docs/integration-api.md：新增外部系统统一对接 API 文档，覆盖接口概览、认证与安全边界、IntegrationTask/TaskStatus/TaskEvent/ResultPayload 数据模型、JSON-RPC 请求/响应示例、SSE 事件流、错误码、幂等与重试语义、CNB Issue 触发和外部系统直连两个端到端示例。
• README.md：新增“外部系统对接 API”入口，指向 docs/integration-api.md。

接口设计摘要：

• 当前最小可运行实现复用现有 GET /healthz、POST /rpc、GET /events?sid=<sessionId>，不新增大型框架或额外 HTTP wrapper。
• 任务创建使用 session/new + chat/sendMessage；状态和事件由 /events SSE 聚合；结果通过 runner 的 exitCode、resultFiles、最终消息、Git commit 和平台评论信息回传。
• 认证边界明确为外层网关或 CNB pipeline 负责，文档给出 Authorization、X-Auto-Harness-Client、X-Auto-Harness-Request-Id 约定，并说明凭据不得写入 prompt、日志或评论。
• 文档明确错误码、重试语义和写 Git 任务的幂等规则。

验证结果：

• /usr/local/go/bin/go test ./... 通过。

分支：codex/issue-28-integration-api
完整 commit SHA：6df45231919f5930d3f9597cb151469c9a42bf68
push 状态：已 push，远端 refs/heads/codex/issue-28-integration-api 当前指向同一 SHA。

剩余风险：HTTP API 当前没有内置认证中间件；面向外部系统开放时仍需由 AgentForge Gateway、反向代理或集成层承担认证、审计、限流和持久化任务状态。