Task Pool Agent — Agent 接入指南 v1.1

面向接入 Task Pool Agent 平台的 AI Agent(Openclaw(主力)、Claude Code、Trae 等)。 读完本文档,你应该能立刻上手操作平台,不需要用户逐步教学。


平台访问地址(先看这个)

你的部署位置用哪个 base URL
中国大陆(家用 NAS / 国内服务器 / 国内笔记本)https://task-pool-agent.pages.dev首选
海外 / 能直连 Vercel 的环境https://task-pool-agent-9dva.vercel.app
本地开发http://localhost:3000

⚠️ *.vercel.app 在中国大陆被 GFW 拦截(SNI/IP 层,改 hosts 也救不了)。 task-pool-agent.pages.dev 是 Cloudflare Pages 反向代理,把请求原样转发到 Vercel 源站, 国内可直连。所有 API 路径、鉴权方式、请求/响应格式完全一致,只换域名即可。 拿不准就用 pages.dev 这个——海外环境走它也没问题。


一、平台是什么

Task Pool Agent 是一个 OKR + 任务管理平台,数据模型分三层:

Objective(目标)
  └── Key Result(关键结果 / KR)
        └── Task(任务)
  • Objective(O):季度级战略目标,由人通过 AI 教练对话讨论后确定,Agent 不应自行创建
  • Key Result(KR):支撑 O 的可量化结果,由人通过 AI 教练拆解,Agent 不应自行创建
  • Task(任务):支撑 KR 推进的具体行动项,由 Agent 全权负责录入、跟进、更新

你的核心职责

你能做的你不能做的
✅ 创建 Task❌ 创建 / 修改 Objective
✅ 更新 Task 状态(进行中/完成/阻塞/取消)❌ 创建 / 修改 Key Result
✅ 关联 Task 到 KR❌ 修改 KR 的量化指标
✅ 查询当前所有 O / KR / Task❌ 删除已有 O 或 KR
✅ 为用户提供进度摘要

二、认证与身份持久化(必读)

平台用 API Key(Bearer Token) 做身份认证。每个 Agent 一个 key,一次生成、长期持有,对应平台里一个固定的 agent_id 和工作历史。

⚠️ 核心原则:你不应该每次 session 都来问用户要新 key。第一次拿到后,你有责任把它持久化到你自己的可恢复存储里,下次启动自己读出来。 如果你做不到这点,你就是个一次性 agent,每次都要用户重新教你身份,这不是平台问题,是你接入实现的问题。

2.1 Key 全生命周期

首次接入                  日常工作                  Key 失效(罕见)
─────────                ────────                  ─────────────
用户在 /settings/agent     你从持久化存储读 key       401 → 提示用户重新生成
生成 tpa_xxx,复制给你  →  附在 Bearer header   →   重新存进持久化存储
你存进持久化存储           调 API 做你的工作         继续

Key 是 hash 存储的:明文 tpa_xxx... 只在生成那一刻显示给用户一次,平台数据库只存 SHA-256 hash。所以一旦你弄丢明文 key,只能让用户吊销重发,平台无法找回。这是你必须存好的原因。

2.2 你的持久化存储应该放哪

按你的运行形态选最早一种符合的方案,存进去之后告知用户存在哪了(方便他后续审查 / 替换 / 吊销):

你是推荐持久化位置备注
Claude Code(CLI / web)写进项目根的 CLAUDE.md(或用户级 ~/.claude/CLAUDE.md)一个固定小节跨 session 自动加载,最佳选择
Claude Desktop + MCPMCP server 的 env.PLATFORM_API_KEY(写在 ~/claude_desktop_config.json 里)启动时由 MCP server 注入,agent 不直接接触
Openclaw / Trae / 自研 HTTP agent你的配置文件 / secret store / 环境变量 TASK_POOL_API_KEY按你框架的惯例
任何其他形态用户级配置文件 ~/.task-pool-agent/key(你自己造一个),权限 600通用兜底

Claude Code 写入 CLAUDE.md 的标准格式(其他 agent 可参考):

## Task Pool Agent 接入凭据

- 平台地址:https://task-pool-agent.pages.dev  (国内首选;本地开发用 http://localhost:3000)
- API Key:tpa_xxxxxxxxxxxxxxxxxxxxxxxx
- 我的 agent_id(首次 GET /api/agent/context 拿到后回填):<uuid>
- 我的 display_name:<填回来>
- 接入文档:web/content/agent-onboarding.md
- 自检测试:见接入文档第八节

2.3 每次 session 启动必跑的 SOP

这是你接入这个平台的"操作系统",每次新 session 你都要按这个跑,不要跳步

START:
  1. 在你的持久化位置里查 Task Pool Agent 的 API Key
     - Claude Code:grep "Task Pool Agent" CLAUDE.md
     - 其他:按 2.2 表里的位置
  2. 找到了?
       ├── 是 → 跳到 3
       └── 否 → 跳到 NEW_REGISTRATION
  3. 调 GET /api/agent/context 验证 key 还有效
     - 200 → 跳到 4
     - 401 → key 已被吊销,跳到 NEW_REGISTRATION
     - 其他错误 → 报告用户,停下
  4. 从返回里读 agent.id 和 agent.display_name,缓存到本次 session 上下文
  5. 你的身份已确认,可以开始干活。完成。

NEW_REGISTRATION:
  1. 告诉用户:
     "我没找到(或已失效)的 Task Pool Agent API Key。
      请你去 http://localhost:3000/settings/agent 生成一个,
      并把完整的 tpa_xxx... 字符串发给我。"
  2. 收到后,写进 2.2 表对应的位置(按你的 agent 形态)
  3. 调 GET /api/agent/context 验证
  4. 把 agent.id / display_name 回填进同一个位置
  5. 跳回 START 的步骤 5

关键不要做的事

  • ❌ 拿到 key 后只放在内存里就开始干活 → 下次 session 立刻丢身份
  • ❌ 每次 session 都问用户要 key → 用户会疯
  • ❌ 把 key 贴在聊天历史里当持久化 → 聊天会被清理 / 压缩 / 跨设备同步不到

2.4 身份恢复保证(你不会"丢工作")

你的 agent_id 在 agents 表里是稳定的。哪怕你换了一次 key(旧的吊销、新的生成),只要绑定的还是同一个 agent 账号:

  • 你之前创建的所有任务,agent_id 字段还指向你 → 任务看板的 agent 过滤条点你的名字,照样能看到
  • 你之前的工作历史不会丢
  • 用户不需要重新教你"哪些任务是你的",调一次 GET /api/agent/tasks?agent_id=<self>(或从 context 里筛 agent_id == self)就能找回

2.5 Header 格式(操作时只需要记这个)

Authorization: Bearer <你存好的 tpa_xxx>
Content-Type: application/json

未来版本:将支持飞书 OAuth 替代 API Key,那时 key 由 OAuth refresh token 自动滚动,你不再需要手动持久化静态 key。架构已预留兼容,切换时业务逻辑无需改动。


三、核心 API

Base URL:https://<your-platform-domain>(本地开发:http://localhost:3000

⚠️ 命名约定(必读,否则字段会被静默忽略)

请求 body 一律使用驼峰命名(camelCase),响应体里出现的下划线字段是数据库内部命名,不能照搬到请求里

类型例子说明
✅ 请求 bodyrelatedKrId, dueDate, progressNote驼峰
❌ 错误用法related_kr_id, due_date这些是响应字段,请求里写了会被忽略,导致 KR 关联失败、日期为空等
✅ 请求枚举值priority: "HIGH"status: "DONE"用文档里列出的大写枚举
❌ 错误用法priority: "P0"P0/P1/P2 是数据库内部存储值,请求里不要直接传

踩过的坑:Agent 看到响应里的 due_date / priority: "P0" 就照搬到请求 body 里,结果任务创建了但 related_kr_id/due_date 全是 NULL,关联失效。看完本节再去对照 3.2/3.3 的字段。

3.1 查询完整上下文

GET /api/agent/context

返回当前用户的所有活跃 O、每个 O 下的 KR(含量化目标/当前进度)、以及近期任务摘要。

这是你每次开始工作前必须调用的第一个接口,用来了解当前 OKR 状态,再决定操作。

返回示例:

{
  "objectives": [
    {
      "id": "uuid-o1",
      "title": "AI Agent 提效团队协作",
      "status": "ACTIVE",
      "cycle": "2026-Q2",
      "keyResults": [
        {
          "id": "uuid-kr1",
          "title": "Agent 日均处理任务数 ≥ 50 条",
          "baseline": 0,
          "target": 50,
          "current": 12,
          "unit": "条/天",
          "status": "ACTIVE",
          "recentTasks": [
            { "id": "uuid-t1", "title": "搭建 MCP Server", "status": "IN_PROGRESS" }
          ]
        }
      ]
    }
  ],
  "unassignedTasks": []
}

3.2 创建任务

POST /api/agent/tasks

请求 body必须驼峰命名,对照上面的「命名约定」):

{
  "title": "准备 kickoff PPT",
  "description": "可选的详细说明",
  "relatedKrId": "uuid-kr1",   // ⚠️ 驼峰,不是 related_kr_id;可为 null(无 KR 关联)
  "dueDate": "2026-05-15",     // ⚠️ 驼峰,不是 due_date;可选,ISO 8601
  "priority": "HIGH"           // ⚠️ 用 LOW/MEDIUM/HIGH,不是 P0/P1/P2;可选,默认 MEDIUM
}

返回示例(注意响应字段是 snake_case,仅供查看,不要照搬到下次请求):

{
  "task": {
    "id": "uuid-task1",
    "title": "准备 kickoff PPT",
    "related_kr_id": "uuid-kr1",   // ← 响应里是下划线,但请求时必须用 relatedKrId
    "due_date": "2026-05-15",       // ← 同上
    "priority": "P0",               // ← P0 是内部映射(HIGH→P0),下次请求仍传 "HIGH"
    "status": "TODO"
  }
}

3.3 更新任务状态

PATCH /api/agent/tasks/{taskId}
{
  "status": "DONE",             // TODO / IN_PROGRESS / DONE / BLOCKED / CANCELLED
  "progressNote": "PPT 已完成,共 18 页,对齐了所有 KR 指标"  // 可选
}

3.4 列出 KR(选 KR 用)

GET /api/agent/krs

返回所有 ACTIVE KR 的列表(id + title + O 标题),用于在创建任务时让用户确认关联哪个 KR。

3.5 KR 详情(深入决策用)

GET /api/agent/krs/{id}

何时调:你已经知道某个 KR 的 id(来自 3.1 context 或 3.4 列表),需要做更精细的判断时调用 — 比如:

  • 「这个 KR 现在状况怎么样,我该建什么任务推它?」
  • 「上次 check-in 是不是落后了?」
  • 「KR 怎么量化的?我建的任务是不是真的有助于推进它?」

返回结构

{
  "kr": {
    "id": "...", "title": "...", "description": "...",
    "start_value": 0, "target_value": 100, "current_value": 60, "unit": "%",
    "health_status": "ON_TRACK",
    "last_checkin_at": "2026-05-01T...",
    "objective": { "id": "...", "title": "...", "cycle_label": "2026 年度" }
  },
  "contract": {
    "quantification_logic": "...",         // 如何量化(教练沉淀的契约)
    "evidence_requirements": [...],
    "check_method": {...},
    "check_frequency": "monthly",
    "thresholds": {...},
    "locked_at": "...", "session_id": "..."
  },
  "recent_checkins": [
    { "actor_kind": "user", "health_status": "ON_TRACK", "confidence_pct": 75,
      "notes": "...", "created_at": "..." }
  ],
  "tasks": {
    "total": 12,
    "by_status": { "TODO": 3, "IN_PROGRESS": 2, "BLOCKED": 0, "DONE": 7, "CANCELLED": 0 },
    "recent": [ { "id": "...", "title": "...", "status": "...", "priority": "P0",
                  "due_date": "...", "created_at": "..." } ]
  }
}

返回 404:KR 不存在或已软删。


三补、与 ops-agent 协作(反馈 / 咨询)

平台内置了一个运维 agent(agent_key=ops-agent),它是平台自带的内部 agent,负责回答你的使用问题、收集你报告的 bug / 需求。

核心理念:你遇到错误或疑问时,不应该把问题搬运给田野(人类用户)。直接对接 ops-agent,能问就问、能报就报。田野每天早上会拉一份 digest 看汇总,比你单条骚扰他效率高得多。

3.6 报反馈(bug / 需求 / 问题)

POST /api/ops/feedback

何时调

  • 调平台 API 失败(4xx / 5xx 不是你的请求格式问题)→ 报 category=bug
  • 你觉得平台缺某个能力(如:希望有批量更新任务接口)→ 报 category=feature
  • 问题严重需要人工介入(如:数据看起来不一致)→ 报 category=bug + severity=critical

请求 body

{
  "category": "bug",                 // bug | feature | question | other(必填)
  "title": "PATCH /api/agent/tasks 返回 500",  // 1-200 字符(必填)
  "severity": "high",                 // low | medium | high | critical(可选,默认 medium)
  "body": "请求体 {...},响应 500 错误:..."   // 详细描述(可选但强烈建议带上)
}

返回 201{ feedback: { id, ... } },把 id 记一下,方便后续追问。

3.7 问咨询(怎么用、字段含义、最佳实践)

POST /api/ops/consult

何时调

  • 不确定某个 API 的字段语义(如:priority 取值范围是什么?)→ 调这个比反复猜测高效
  • 没找到合适的 KR 关联,但又不想直接打扰用户 → 问 ops-agent「这种类型的任务通常关联到哪类 KR」
  • 接到一个超出文档范围的请求(如:用户问"能不能批量删除任务")→ 调这个先看平台支持不支持

请求 body

{
  "question": "我怎么把任务标记为已完成?给我一个 PowerShell 示例。",  // 1-2000 字符(必填)
  "context": "当前 agent 是 Claude Code,运行在用户笔记本上"     // 可选,附加上下文
}

返回 200

{
  "consultation_id": "uuid",
  "answer": "调 PATCH /api/agent/tasks/{id} ... [完整回答,markdown 格式]",
  "model": "minimax/MiniMax-M2.7-highspeed",
  "latency_ms": 4200,
  "total_tokens": 1850
}

answer 通常 5~20 行,markdown 格式,包含代码示例。直接展示给用户即可。

注意:ops-agent 的知识来自这份接入文档本身。如果它回答「文档未涵盖」,说明你应该改去调 /api/ops/feedback(category=question 或 feature)把这个空缺记下来。

3.8 标准异常处理流程

你的情境该调哪个
API 返回 4xx 且你确认请求没拼错/api/ops/feedback(bug)
API 返回 5xx/api/ops/feedback(bug · high)
不知道某字段怎么传/api/ops/consult
用户要的功能你做不到/api/ops/consult 先确认 → 不支持就 /api/ops/feedback(feature)
你怀疑数据不一致(如任务消失了)/api/ops/feedback(bug · critical)

四、决策原则(你的行为准则)

何时自主行动(不需要问用户)

  • 任务描述明确、属于哪个 KR 有很高把握 → 直接创建并关联
  • 任务状态变更与用户刚说的话完全一致 → 直接更新
  • 查询操作(GET)→ 直接执行
  • 调平台 API 报错 / 字段含义不明 / 平台能力疑问 → 直接调 /api/ops/feedback/api/ops/consult(见 3.6 / 3.7),不要打扰用户

何时必须问用户

  • KR 归属不确定:任务可能关联多个 KR,或没有明显匹配的 KR

    示例:"这个任务我打算关联到 KR2「客户 demo 数 ≥ 5」,是否正确?或者你有其他 KR 想关联?"

  • 找不到合适 KR:用户说的任务与现有所有 KR 都没有明显关系

    示例:"这个任务我没有找到合适的 KR 关联,是作为临时任务(不挂 KR)录入,还是说有新的 KR 我不知道?"

  • 需要创建 O 或 KR:这超出了你的权限范围

    示例:"你说的方向听起来像是一个新的 Objective,这需要通过平台的 OKR 教练来讨论和创建。请在看板点「与 AI 讨论,创建新 Objective」入口开始。"

  • 任务优先级冲突:用户要做的事与看板上 BLOCKED 状态的依赖有关

永远不应该做的

  • 不应猜测 O / KR 的战略意图,然后自行创建
  • 不应静默地把一个 KR 下的进展数字改掉(那是 OKR 教练的工作)
  • 不应在没有依据的情况下把任务标为 DONE

五、典型工作流示例

场景 A:用户结束会议,口述任务清单

用户 → Agent:
  "刚开完会,决定了几件事:
   1. 下周一 kickoff 会,需要先准备议程
   2. 给潜在客户 A 发演示链接,这周五前完成
   3. Agent 平台的 MCP Server 开发,预计两周"

Agent 操作流程:
  1. GET /api/agent/context → 了解当前 KR
  2. 判断:
     - 议程 → KR「demo 客户数」或「Agent 接入场景」,不确定,需要问
     - 演示链接 → 高概率是 KR「demo 客户数 ≥ 5」,把握大,直接关联
     - MCP Server → 高概率是 KR「Agent 日均处理任务 ≥ 50」,直接关联
  3. 先创建把握大的 2 个任务
  4. 问用户:"kickoff 议程准备,我打算关联到 KR1「demo 客户数 ≥ 5」,这样对吗?
             还是更偏向关联 KR3「Agent 接入场景 ≥ 3 个」?"
  5. 用户确认后,创建第 3 个任务
  6. 汇报:"已录入 3 个任务,看板已更新"

场景 B:主动巡检(建议周一或周五触发)

Agent 主动:
  1. GET /api/agent/context
  2. 分析:哪些 KR 过去 7 天没有 DONE 任务 → 可能停滞
  3. 向用户报告:"KR2 「客户 demo 数」本周没有任何任务推进,
                 当前进度 2/5。需要我帮你拆出下一步行动吗?"

场景 C:任务完成后的状态同步

用户 → Agent:"kickoff 会开完了,很顺利"

Agent 操作流程:
  1. 找到标题含"kickoff"的 IN_PROGRESS 任务
  2. PATCH /api/agent/tasks/{id}  { status: "DONE", progressNote: "用户反馈会议顺利完成" }
  3. 汇报:"已将 kickoff 议程任务标为完成 ✅"

六、接入方式

平台对所有主流 Agent 同等友好,三种协议任选其一即可。下方按主力使用场景排序。

方式一:REST API(Openclaw / Trae / 自研 Agent / 通用兜底)

最通用的接入方式,Openclaw 推荐使用此方式。在 Agent 的工具/HTTP 配置中添加:

  • 设置 Authorization: Bearer <API_KEY> Header
  • Base URL:见文档开头「平台访问地址」表——国内部署用 https://task-pool-agent.pages.dev
  • 把本文档第三节「核心 API」喂给 Agent 作为工具说明

Openclaw 配置示例(按 Openclaw 实际配置格式填写,本节将在确认 Openclaw 工具规范后补充粘贴即用片段):

tools:
  - name: task_pool_agent
    type: http
    base_url: https://task-pool-agent.pages.dev   # 国内 NAS 用 pages.dev;海外可用 *.vercel.app
    auth:
      type: bearer
      token: ${TASK_POOL_API_KEY}
    docs: web/content/agent-onboarding.md   # 直接指向本文档

方式二:MCP Server(Claude Code / Claude Desktop 等 MCP 客户端)

第一步:克隆仓库后,在 mcp-server/ 目录安装依赖:

cd mcp-server && npm install

第二步:在 Claude Code 项目的 .claude/mcp.json(或 ~/claude_desktop_config.json)中添加:

{
  "task-pool": {
    "command": "node",
    "args": ["/path/to/task-pool-agent/mcp-server/index.js"],
    "env": {
      "PLATFORM_URL": "https://task-pool-agent-9dva.vercel.app",
      "PLATFORM_API_KEY": "tpa_xxx"
    }
  }
}

PLATFORM_URL 填平台地址(国内用 https://task-pool-agent.pages.dev,海外可用 *.vercel.app,本地用 http://localhost:3000),PLATFORM_API_KEY 填在「Agent 设置」页面生成的 API Key。

MCP 工具列表(Agent 可直接 tool call,无需手写 curl):

工具名作用
get_context查询完整 OKR 上下文(O → KR → Task),开工前必调
get_kr_detail获取单个 KR 详情(契约、check-in 历史、任务汇总)
list_krs列出所有活跃 KR(比 get_context 更轻量)
create_task创建任务,字段已强类型校验,不会再有 snake_case 歧义
update_task更新任务状态/进度/截止日,enum 值自动提示

优势:MCP 工具有 Zod schema 强校验,due_date vs dueDate 之类的命名歧义不会再出现 — tool call 时传错字段名会直接报错,而不是静默忽略。

方式三:CLI

# 全局安装(一次)
npm install -g task-pool-agent-cli

# 配置
export TASK_POOL_API_KEY=<your_api_key>
export TASK_POOL_BASE_URL=http://localhost:3000

# 常用命令
tpa context                        # 查看当前 OKR 上下文
tpa task create "准备 PPT" --kr uuid-kr1 --due 2026-05-15
tpa task done uuid-task1 --note "已完成"
tpa krs                            # 列出所有 KR

七、未来规划(本版本不含,架构已预留)

  • 飞书 OAuth 认证:替代 API Key,通过飞书 open_id 绑定用户身份
  • 平台运维 AI 接管:日志监控、Bug 检测、Issue 规划接口
  • KR 进度主动推送:Webhook / 飞书消息通知 Agent
  • 多用户 / 多 Agent 协作:同一组织下多个 Agent 分工协作

八、自检测试用例 — 接入后第一次跑一遍

目的:验证你的 API Key 有效、4 个核心端点可用、KR 关联生效、看板 UI 反馈正常。 前提:你已经在某个 OKR 平台用户处拿到 API Key(形如 tpa_xxx...),平台地址默认 http://localhost:3000执行约定:每一步都要报告 HTTP 状态码 + 关键返回字段。任一步失败立刻停下来报告错误,不要继续。

测试 0:环境确认

跑测试前先按**第 2.3 节「session 启动 SOP」**确认你的 Key 已经持久化好、可用。然后记下:

  • BASE_URL = http://localhost:3000(除非用户告知其他地址)
  • API_KEY = 从持久化存储读出的 tpa_xxx...

所有请求都带这两个 header:

Authorization: Bearer <API_KEY>
Content-Type: application/json

如果你这是第一次接入(CLAUDE.md / config 里还没有 Key):先跑完 2.3 节 NEW_REGISTRATION 流程,把 key + agent.id + display_name 写进持久化位置,再回来跑测试 1。

测试 1:身份认证

GET {BASE_URL}/api/agent/context

预期:HTTP 200,返回 JSON 含 objectives 数组。

校验点

  • 状态码必须 200。401 = key 错;500 = 服务器问题
  • objectives 至少 1 个,里面有 keyResults 数组
  • 记下第一个 ACTIVE Objective 的 idtitle,备用

失败处理:401 → 立即停下来报错"API Key 无效或已吊销",让用户去 /settings/agent 检查。

测试 2:列出 KR

GET {BASE_URL}/api/agent/krs

预期:HTTP 200,返回 KR 列表。

校验点

  • 至少 1 个 KR
  • 每个 KR 含 id, title, objective(带 O 标题)
  • 记下第一个 ACTIVE KRid,命名为 TEST_KR_ID,下一步用

测试 3:KR 详情

GET {BASE_URL}/api/agent/krs/{TEST_KR_ID}

预期:HTTP 200,返回 { kr, contract?, recent_checkins, tasks }

校验点

  • kr.id == TEST_KR_ID
  • tasks.by_status 是个 5 桶对象(TODO/IN_PROGRESS/BLOCKED/DONE/CANCELLED)
  • 记下当前 tasks.total 数字,命名为 BASELINE_COUNT

测试 4:创建任务(关联到 KR)

POST {BASE_URL}/api/agent/tasks
Body:
{
  "title": "[自检] Agent 接入冒烟测试 - <当前时间 HH:MM:SS>",
  "description": "由 Claude Code agent 自动创建,验证 Agent API 接入闭环",
  "relatedKrId": "{TEST_KR_ID}",
  "priority": "MEDIUM"
}

关键提醒

  • ⚠️ 字段必须是驼峰 relatedKrId不能是 related_kr_id(写错会被静默忽略,KR 关联失效)
  • ⚠️ priority 用 LOW/MEDIUM/HIGH不能用 P0/P1/P2
  • title 末尾加当前时间,避免和历史任务混淆

预期:HTTP 201,返回 { task: { id, title, related_kr_id, ... } }

校验点(必须全部满足,否则报错):

  • 状态码 201
  • task.id 是 UUID 格式
  • task.related_kr_id == TEST_KR_ID这一步是核心校验,如果是 null 说明字段名传错了
  • task.priority == "P1"(MEDIUM 在 DB 里映射为 P1)
  • task.status == "TODO"
  • 记下 task.id,命名为 TEST_TASK_ID

测试 5:验证任务挂上去了

再调一次 KR 详情,看任务是否进了那个 KR 的桶:

GET {BASE_URL}/api/agent/krs/{TEST_KR_ID}

校验点

  • tasks.total 应该 == BASELINE_COUNT + 1
  • tasks.by_status.TODO 比测试 3 多 1
  • tasks.recent 第一项的 id 应该 == TEST_TASK_ID

测试 6:状态推进 TODO → IN_PROGRESS

PATCH {BASE_URL}/api/agent/tasks/{TEST_TASK_ID}
Body:
{
  "status": "IN_PROGRESS",
  "progressNote": "已开始执行,自检中"
}

预期:HTTP 200,返回更新后的任务。

校验点

  • task.status == "IN_PROGRESS"
  • task.actual_start_at 不为 null

测试 7:状态推进 IN_PROGRESS → DONE

PATCH {BASE_URL}/api/agent/tasks/{TEST_TASK_ID}
Body:
{
  "status": "DONE",
  "progressNote": "[自检] Agent 接入完整链路验证通过"
}

预期:HTTP 200。

校验点

  • task.status == "DONE"
  • task.completed_at 不为 null

测试 8:UI 反馈预期(请用户人肉确认)

完成上述 7 个 API 测试后,告诉用户去刷新这两个页面看效果:

  1. /okr/board(OKR 看板)→ 找到 TEST_KR_ID 那个 KR 卡片底部,点开「📎 关联任务 N 条」折叠区,应该能看到刚才那个测试任务(已完成的会在「✅ 已完成」分组里)。每行任务右侧应该有靛蓝色的 agent 名字标签(你的 agent display_name)。

  2. /tasks/board(任务看板)→ 顶部应该出现 Agent 过滤条(如果之前没有任何任务挂 agent_id,这是过滤条第一次出现)。点你自己的 agent 名字,应该只剩下你刚才创建的那个测试任务。任务卡上应该能看到 📎 KR 标题 的蓝色标签。

终报模板

跑完后用类似这样的格式汇报给用户:

✅ Task Pool Agent 接入自检完成

测试 1 身份认证       : 200 ✓ (org: <org_name>, 我是 <agent_display_name>)
测试 2 列出 KR        : 200 ✓ (共 <N> 个 KR)
测试 3 KR 详情        : 200 ✓ (KR「<title>」, 当前 <total> 个任务)
测试 4 创建任务       : 201 ✓ (id: <task_id>, related_kr_id 已正确写入)
测试 5 任务挂载验证   : 200 ✓ (KR 任务总数 +1)
测试 6 状态 → IN_PROGRESS : 200 ✓
测试 7 状态 → DONE    : 200 ✓
测试 8 UI 反馈        : 请你刷新 /okr/board 和 /tasks/board 确认

测试任务 id: <TEST_TASK_ID>(如需清理,告诉我)

任一测试失败:立即停下、贴出完整请求/响应,等用户决定。


文档版本:v1.3 | 对应平台:Phase 3.2.C/D | 更新日期:2026-05-14