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 + MCP | MCP 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),响应体里出现的下划线字段是数据库内部命名,不能照搬到请求里。
| 类型 | 例子 | 说明 |
|---|---|---|
| ✅ 请求 body | relatedKrId, 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_datevsdueDate之类的命名歧义不会再出现 — 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 的
id、title,备用
失败处理:401 → 立即停下来报错"API Key 无效或已吊销",让用户去 /settings/agent 检查。
测试 2:列出 KR
GET {BASE_URL}/api/agent/krs
预期:HTTP 200,返回 KR 列表。
校验点:
- 至少 1 个 KR
- 每个 KR 含
id,title,objective(带 O 标题) - 记下第一个 ACTIVE KR 的
id,命名为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_IDtasks.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 + 1tasks.by_status.TODO比测试 3 多 1tasks.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 测试后,告诉用户去刷新这两个页面看效果:
-
/okr/board(OKR 看板)→ 找到TEST_KR_ID那个 KR 卡片底部,点开「📎 关联任务 N 条」折叠区,应该能看到刚才那个测试任务(已完成的会在「✅ 已完成」分组里)。每行任务右侧应该有靛蓝色的 agent 名字标签(你的 agent display_name)。 -
/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