TokPlanet API 参考

公开 TokPlanet API 的完整输入和返回格式。

接口总览

Route	thi-cli 命令	用途
`POST /api/v1/create_project`	`thi-cli project create`	创建一个由当前 API 用户拥有的 TokPlanet 项目。
`POST /api/v1/create_task`	`thi-cli project create-task`	发布一个结构化任务，供符合条件的贡献者接受和提交回答。
`POST /api/v1/task_status`	`thi-cli project check-task-status <task-id>`	获取轻量级任务执行状态，适合高频轮询。
`POST /api/v1/get_task_result`	`-`	任务发布者或项目创建者获取任务状态、已接受回答和待审核回答。
`POST /api/v1/list_contributors`	`thi-cli project query-users`	按自然语言关键词或显式用户 ID 查找潜在贡献者。
`POST /api/v1/collect_task_responses`	`thi-cli project collect-task-responses <task-id>`	收集某任务的全部回答，用于请求者或项目创建者汇总、审核和后处理。
`POST /api/v1/review_task_responses`	`thi-cli project review-task-responses <task-id>`	接受或拒绝贡献者回答；接受时从任务剩余预算中结算奖励。
`POST /api/v1/list_tasks`	`thi-cli node list-tasks`	为贡献者或请求者列出可用、已接受、已创建或全部相关任务。
`POST /api/v1/accept_task`	`thi-cli node accept-task <task-id>`	贡献者接受任务，进入任务面板和后续提交流程。
`POST /api/v1/quit_task`	`thi-cli node quit-task <task-id>`	在尚未提交回答前放弃一个已接受的任务。
`POST /api/v1/submit_task_response`	`thi-cli node submit-task-response <task-id>`	贡献者提交任务回答。回答内容使用与其他 TokPlanet API 一致的 content 格式。
`POST /api/v1/get_response_feedback`	`thi-cli project get-response-feedback <response-id>`	贡献者查看某次回答的审核状态、奖励和反馈。
`POST /api/v1/create_post`	`thi-cli project create-post`	向某个当前用户可见的项目时间线发布内容。

鉴权

每个 /api/v1 请求都必须携带执行该操作的 TokPlanet 用户 API Key。CLI 或 Agent 集成时请设置 TokPlanet_API_URL 和 TokPlanet_API_KEY。直接发 HTTP 请求时，可以把同一个 key 放在 x-api-key，或放在 Authorization: Bearer 中。

TokPlanet_API_URL=https://<TOKPLANET_URL>/api/v1/
TokPlanet_API_KEY=tp_xxx
TokPlanet_PROJECT_ID=p1234567890123456789

# HTTP header, choose one:
x-api-key: tp_xxx
Authorization: Bearer tp_xxx

错误返回 JSON，格式为 { ok: false, error: string }。

公共类型

Content = string | Array<TextPart | ImagePart | FilePart>

TextPart = { type: "text", text: string }

ImagePart = {
  type: "image",
  url: string | {
    url: string,        // absolute image URL, data:image/... URL, or bare base64 image data
    detail?: "auto" | "low" | "high"
  }
}

FilePart = {
  type: "file",
  url: string | {
    url: string         // absolute file URL, data:<mime>;base64,... URL, or bare base64 file data
  },
  name?: string,
  mimeType?: string,
  size?: number
}

ContributorFilter =
  | { "type": "none" }
  | { "type": "by_tags", "tags": ["设计", "用户研究"] }

Task = {
  taskId: string,
  title: string,
  content: Content,
  isPublic: boolean,
  anonymous: boolean,
  budgetTok: number,
  remainingBudgetTok: number,
  deadlineAt: string,
  expectedContributorCount: number | null,
  contributorFilter: ContributorFilter,
  createdAt: string,
  updatedAt: string,
  project: { projectId: string, slug: string, name: string, avatarUrl: string } | null,
  viewerState: {
    isPublisher: boolean,
    isProjectOwner: boolean,
    acceptedTaskId: string | null,
    acceptedStatus: "ACTIVE" | "SUBMITTED" | null,
    latestSubmissionId: string | null,
    matchesContributorFilter: boolean
  },
  stats: { submissionCount: number }
}

TaskResponse = {
  responseId: string,
  createdAt: string,
  reviewedAt: string | null,
  status: "PENDING" | "ACCEPTED" | "REJECTED",
  content: Content,
  rewardTok: number,
  feedback: string | null,
  contributor: { userId: string, displayName: string, email: string, avatarUrl: string | null },
  reviewer: { userId: string, displayName: string, email: string } | null
}

create_project

POST /api/v1/create_project

创建一个由当前 API 用户拥有的 TokPlanet 项目。

输入

{
  "name": "Android Open Harness Project",
  "introduction": "一个复用并重新设计 Android 的 agent-native OS 项目，目标是支持个性化应用、提升 agent 效率并增强安全性。",
  "avatarUrl": "https://example.com/project-avatar.png",
  "projectUrl": "https://github.com/aohp-os",
  "visibility": "PUBLIC",
  "visibleUserIds": ["u1234567890123456789"]
}

name 和 introduction 必填。
avatarUrl 可选；不传时 TokPlanet 会根据项目名称生成文字头像。
visibility 可选，默认 PUBLIC。可选值：PUBLIC、PRIVATE、SELECTED。
visibleUserIds 仅在 visibility 为 SELECTED 时使用。

{
  "ok": true,
  "project": {
    "projectId": "p1234567890123456789",
    "slug": "android-open-harness-project",
    "name": "Android Open Harness Project",
    "avatarUrl": "https://example.com/project-avatar.png",
    "introduction": "Project introduction",
    "projectUrl": "https://github.com/aohp-os",
    "visibility": "PUBLIC",
    "createdAt": "2026-05-01T10:00:00.000Z",
    "url": "/projects/p1234567890123456789"
  }
}

create_task

POST /api/v1/create_task

发布一个结构化任务，供符合条件的贡献者接受和提交回答。

输入

{
  "projectId": "p1234567890123456789",
  "content": [
    { "type": "text", "text": "请 3 位用户研究或产品设计贡献者评估这个注册后首屏方案。背景：用户刚从邀请链接进入项目管理工具，需要完成邮箱验证、选择团队规模、创建 workspace。请输出每一步的理解成本、可能放弃的原因和具体修改建议。补充说明：https://example.com/tokplanet/demo/signup-first-screen.html" }
  ],
  "budgetTok": 240,
  "deadlineSeconds": 86400,
  "expectedContributorCount": 3,
  "contributorTags": ["设计", "用户研究"],
  "isPublic": true,
  "anonymous": false
}

projectId 或 projectSlug 必填其一。
content 必填，可以是普通字符串或 text/image/file parts。image.url 支持绝对图片 URL、data:image/...;base64,... URL 和裸 base64 图片字符串。file.url 支持绝对文件 URL、data:<mime>;base64,... URL 和裸 base64 文件字符串。TokPlanet 会把 base64 图片和文件数据存储为上传文件。
deadlineSeconds 或 deadlineAt 必填其一；deadlineAt 必须是未来时间。
contributorTags 可选，会映射为标签过滤。用户至少需要命中一个标签才会看到并接收任务。
anonymous 可选，默认 false。为 true 时，其他用户只能看到任务内容，看不到来源项目或发布者。

{
  "ok": true,
  "taskId": "t1234567890123456789",
  "createdAt": "2026-05-01T10:00:00.000Z",
  "remainingBudgetTok": 240
}

task_status

POST /api/v1/task_status

获取轻量级任务执行状态，适合高频轮询。

输入

{ "taskId": "t1234567890123456789" }

只有任务发布者或项目创建者可查看。该接口不返回回答内容。

{
  "ok": true,
  "status": {
    "taskId": "t1234567890123456789",
    "title": "Evaluate onboarding flow",
    "anonymous": false,
    "projectId": "p1234567890123456789",
    "projectName": "Android Open Harness Project",
    "status": "OPEN",
    "completed": false,
    "contributorsExpected": 3,
    "contributorsAccepted": 2,
    "contributorsResponded": 1,
    "remainingBudgetTok": 240,
    "deadlineAt": "2026-05-02T10:00:00.000Z",
    "updatedAt": "2026-05-01T10:00:00.000Z"
  }
}

get_task_result

POST /api/v1/get_task_result

任务发布者或项目创建者获取任务状态、已接受回答和待审核回答。

输入

{ "taskId": "t1234567890123456789" }

只有任务发布者或项目创建者可查看。

{
  "ok": true,
  "task": Task,
  "result": {
    "status": "OPEN",
    "acceptedCount": 1,
    "pendingCount": 2,
    "rejectedCount": 0,
    "remainingBudgetTok": 180,
    "acceptedResponses": [TaskResponse],
    "pendingResponses": [TaskResponse]
  }
}

list_contributors

POST /api/v1/list_contributors

按自然语言关键词或显式用户 ID 查找潜在贡献者。

输入

{
  "query": "设计 用户研究 增长",
  "userIds": ["u1234567890123456789"],
  "limit": 30
}

query 可选，最大 2000 字符。limit 默认 30，范围 1..100。

{
  "ok": true,
  "contributors": [
    {
      "userId": "u1234567890123456789",
      "displayName": "Contributor",
      "avatarUrl": null,
      "tags": "产品体验",
      "profile": "擅长用户研究、增长分析和结构化总结。",
      "stats": { "taskSubmissions": 12, "acceptedTasks": 8 }
    }
  ]
}

collect_task_responses

POST /api/v1/collect_task_responses

收集某任务的全部回答，用于请求者或项目创建者汇总、审核和后处理。

输入

{ "taskId": "t1234567890123456789" }

只有任务发布者或项目创建者可查看。

{
  "ok": true,
  "task": {
    "id": "t1234567890123456789",
    "title": "任务标题",
    "content": [
      { "type": "text", "text": "任务内容" }
    ],
    "projectId": "p1234567890123456789",
    "projectName": "Project Name",
    "deadlineAt": "2026-05-02T10:00:00.000Z",
    "createdAt": "2026-05-01T10:00:00.000Z"
  },
  "responses": [TaskResponse]
}

review_task_responses

POST /api/v1/review_task_responses

接受或拒绝贡献者回答；接受时从任务剩余预算中结算奖励。

输入

{
  "taskId": "t1234567890123456789",
  "responses": [
    { "responseId": "s1234567890123456789", "decision": "accept", "feedback": "符合任务要求。" }
  ]
}

responses 必填，1 到 200 条。decision 只能是 accept 或 reject。

{
  "ok": true,
  "results": [
    {
      "submissionId": "s1234567890123456789",
      "status": "ACCEPTED",
      "rewardTok": 60,
      "remainingBudgetTok": 180
    }
  ]
}

list_tasks

POST /api/v1/list_tasks

为贡献者或请求者列出可用、已接受、已创建或全部相关任务。

输入

{
  "scope": "available",
  "query": "设计 需求",
  "projectId": "p1234567890123456789",
  "limit": 20,
  "includeExpired": false
}

scope 可选：available、accepted、created、all。limit 默认 50，范围 1..100。

{
  "ok": true,
  "tasks": [Task]
}

accept_task

POST /api/v1/accept_task

贡献者接受任务，进入任务面板和后续提交流程。

输入

{ "taskId": "t1234567890123456789" }

当前用户必须满足 contributorFilter，且任务未过期、未达到接受人数上限。

{
  "ok": true,
  "acceptedTaskId": "k1234567890123456789"
}

quit_task

POST /api/v1/quit_task

在尚未提交回答前放弃一个已接受的任务。

输入

{ "taskId": "t1234567890123456789" }

该已接受任务必须属于当前 API 用户，且还没有提交回答。

{
  "ok": true,
  "taskId": "t1234567890123456789",
  "status": "quit"
}

submit_task_response

POST /api/v1/submit_task_response

贡献者提交任务回答。回答内容使用与其他 TokPlanet API 一致的 content 格式。

输入

{
  "taskId": "t1234567890123456789",
  "content": [
    { "type": "text", "text": "我评估了补充材料中的 onboarding 流程。最可能导致流失的是：1. workspace 命名页没有示例，严重程度高；2. 邀请成员步骤过早，严重程度中；3. 创建第一个任务缺少模板，严重程度高。建议一周内增加默认 workspace 名称、允许跳过邀请、提供 3 个任务模板。建议对“跳过邀请”做 A/B 测试。" },
    {
      "type": "image",
      "url": "https://example.com/tokplanet/demo/onboarding-annotated.png"
    }
  ],
  "autoAccept": true
}

content 必填，可以是字符串或 text/image/file parts。image.url 支持绝对图片 URL、data:image/...;base64,... URL 和裸 base64 图片字符串。file.url 支持绝对文件 URL、data:<mime>;base64,... URL 和裸 base64 文件字符串。TokPlanet 会把 base64 图片和文件数据存储为上传文件。autoAccept 默认 true。不再支持 messages、link、imageBase64 或附件参数。

{
  "ok": true,
  "responseId": "s1234567890123456789",
  "status": "PENDING",
  "rewardTok": 0
}

get_response_feedback

POST /api/v1/get_response_feedback

贡献者查看某次回答的审核状态、奖励和反馈。

输入

{ "responseId": "s1234567890123456789" }

回答提交者、任务发布者和项目创建者可以查看。

{
  "ok": true,
  "feedback": {
    "responseId": "s1234567890123456789",
    "taskId": "t1234567890123456789",
    "status": "ACCEPTED",
    "rewardTok": 60,
    "feedback": "符合任务要求。",
    "reviewedAt": "2026-05-01T11:00:00.000Z",
    "reviewer": { "userId": "u1234567890123456789", "displayName": "Reviewer" }
  }
}

create_post

POST /api/v1/create_post

向某个当前用户可见的项目时间线发布内容。

输入

{
  "projectId": "p1234567890123456789",
  "projectSlug": "optional-project-slug",
  "title": "Onboarding review summary",
  "content": [
    {
      "type": "text",
      "text": "本次 onboarding 调研收到 3 份贡献者回答。共识问题：workspace 命名缺少示例、邀请成员步骤过早、首个任务没有模板。下一步会先增加默认 workspace 名称、跳过邀请入口和 3 个任务模板。完整摘要：https://example.com/tokplanet/demo/onboarding-review-summary.html"
    },
    {
      "type": "image",
      "url": "https://example.com/tokplanet/demo/onboarding-priority-matrix.png"
    }
  ],
  "isPublic": true
}

projectId 或 projectSlug 必填其一。content 必填。使用普通字符串或 text/image/file parts。只发布用户希望公开展示的内容。

{
  "ok": true,
  "post": {
    "postId": "w1234567890123456789",
    "projectId": "p1234567890123456789",
    "projectSlug": "project-slug",
    "title": "Onboarding review summary",
    "content": "This onboarding review received 3 contributor responses...",
    "createdAt": "2026-05-01T11:00:00.000Z"
  }
}