开放 API

PryFox AI 开放 API 让外部系统以项目密钥身份创建任务、查询任务与日志、实时监听任务事件、确认计划模式任务，并管理工作空间。任务以工作空间为隔离单元，同一工作空间内的多次调用共享同一智能体实例、记忆与会话历史。

基础信息

基础地址：https://pryfox.ai/openapi（开放接口为顶层命名空间 /openapi，与内部接口的 /api 前缀相互独立）
所有接口统一返回结构：{ code, message, data }
- code === 0 表示成功，非 0 为错误
- message 为结果描述
- data 为业务数据

认证方式

开放 API 使用项目访问密钥换取 JWT Token，后续请求通过 Bearer Token 调用。

1. 换取 Token

http

POST /openapi/auth/project-key
Content-Type: application/json

{
  "key": "proj_<uuid>_<random>",
  "projectUuid": "可选的项目 UUID，用于校验"
}

成功响应：

json

{
  "code": 0,
  "message": "认证成功",
  "data": {
    "token": "eyJhbG...",
    "csrfToken": "a49e9e4b88a34ce0b2d63bfb53a885ad",
    "project": { "uuid": "...", "name": "..." },
    "permissions": { "tasks": ["read", "write"] }
  }
}

响应同时通过 Set-Cookie 头下发 project_token 与 csrfToken 两个 cookie。纯后端调用（无 cookie 场景）可直接用响应体里的 token 作 Authorization: Bearer、csrfToken 作 X-CSRF-Token 头。

2. 调用接口

场景	要求
读接口（GET）	`Authorization: Bearer {token}`
写接口（POST/PUT/DELETE）	`Authorization: Bearer {token}` + `X-CSRF-Token: {csrfToken}`
SSE 流式	`Authorization: Bearer {token}`，或在 URL 中附带 `?token={token}`（EventSource 无法自定义请求头）

项目密钥权限字段 permissions.tasks 包含：

read：查询任务、日志、计划、流式、工作空间
write：创建任务、管理工作空间、确认 / 拒绝计划

确认 / 拒绝计划只需 tasks:write，无需单独的 approve 权限。

工作空间与频道

工作空间（Workspace）是开放 API 的核心隔离单元。 每个任务必须归属一个工作空间，由调用方在创建任务时传入 workspace_id（UUID）指定。

task_id：公开的任务 ID，查询 / 监听 / 确认计划均使用它
workspace_id：工作空间 UUID，由调用方持有，决定任务的运行时归属
external_user_id：Claw 运行时内部使用的用户键，等于 workspace_id——同一工作空间内的所有任务共享同一智能体实例、记忆库与连续会话历史，第二次调用同一 workspace_id 时智能体会记得第一次的对话上下文。不同工作空间之间的数据互不可见。

频道（channel） 决定任务在工作空间内发往何处。开放 API 暴露两种逻辑频道：

逻辑频道	含义	完整频道（Server 组合）	选派方式
`work-group`	工作空间群聊	`workspace:{workspace_id}`	协调员自动选派智能体
`agent:{agent_id}`	与某智能体私聊	`agent:{agent_id}:ws:{workspace_id}`	手动指派该智能体

调用方传逻辑频道，Server 用与 web UI 同款编码组合成完整频道——开放 API 任务与该工作空间在 web UI 内的同频道完全互通。不要传组合后的完整频道，也不要自带 :ws:{workspace_id} 后缀，Server 会据 workspace_id 自动追加。

工作空间是持久实体：

首次派任务时隐式创建（name 为空，前端列表回退显示 UUID 简写），也可通过工作空间管理接口显式创建并命名。
软删除后，用同一 workspace_id 再次派任务会自动恢复为 active（「删除」对第三方而言等价于「暂停」，持有的 ID 不会死锁）。
项目内所有有权限的身份均可见可干涉同一工作空间。

接口列表

创建任务

http

POST /openapi/projects/{project_id}/tasks

向项目派发一个任务。任务归属调用方指定的 workspace_id 工作空间，并经调用方同时指定的逻辑频道路由。

请求体：

字段	类型	必填	说明
`content`	string	是	任务内容
`workspace_id`	string (UUID)	是	工作空间 ID，决定任务运行时归属（同 ID 共享智能体实例/记忆/历史）
`channel`	string	是	逻辑频道：`work-group`（工作空间群聊）或 `agent:{agent_id}`（与某智能体私聊）。Server 据此 + `workspace_id` 组合完整频道。
`mode`	string	否	三态：`plan`（强制计划确认模式）/ `auto`（强制自动执行）/ 不传（按工作空间→项目级默认回退，见下）
`metadata`	object	否	自定义元数据，会随消息落库
`reply_to`	string	否	仅 `work-group` 频道有效，回复某条消息的 ID

计划模式生效优先级（mode 不传时按此回退算出本任务的 force_plan_mode）：

显式 mode='plan' → true；mode='auto' → false
工作空间默认 workspaces.settings.plan_mode_enabled（由项目成员在 web UI 工作空间管理页设置）
项目级默认 projects.settings.plan_mode_enabled（工作空间未设时回退）
兜底 false

开放 API 的工作空间管理接口不暴露 plan_mode_enabled 字段——工作空间级计划模式默认值由项目成员在 web UI 设置。第三方按需逐任务控制时，在创建任务的 mode 字段显式传 plan 或 auto 即可。

响应：

json

{
  "code": 0,
  "message": "任务已派发",
  "data": {
    "task_id": "42987a4f-e35b-43e2-bd81-c8a527bdcaba",
    "workspace_id": "8e6bc849-b634-4a85-aa68-594a301dd282",
    "status": "pending",
    "channel": "workspace:8e6bc849-b634-4a85-aa68-594a301dd282",
    "logical_channel": "work-group",
    "agent_id": null,
    "mode": "plan",
    "plan_mode_enabled": true,
    "message_db_id": "0c6e0d89-dc03-4750-bdc3-2745f8cf966e",
    "created_at": "2026-07-07T11:32:58.416Z"
  }
}

channel：组合后的完整频道（work-group → workspace:{workspace_id}；agent:{agent_id} → agent:{agent_id}:ws:{workspace_id}）。
logical_channel：调用方传入的逻辑频道（work-group / agent:{agent_id}）。
agent_id：null 表示 work-group 群聊由协调员自动选派；agent:{agent_id} 私聊时为该智能体 ID。
mode：回显调用方传入的逻辑值（plan/auto，不传时落库为 auto）。
plan_mode_enabled：本任务实际生效的计划模式布尔（显式 > 工作空间默认 > 项目级回退），调用方可据此判断是否需要后续确认计划。
若 workspace_id 对应的工作空间不存在，会自动隐式创建工作空间行；若该工作空间此前被软删，会自动恢复为 active。

列出任务

http

GET /openapi/projects/{project_id}/tasks?workspace_id={uuid}&status=running&page=1&limit=20

按工作空间 / 状态过滤并分页列出任务。支持 page/limit 分页或 before 游标分页。

查询参数：

参数	类型	说明
`workspace_id`	string (UUID)	可选，传则只列该工作空间下的任务
`status`	string	可选：`pending` / `running` / `planning` / `completed` / `failed` / `cancelled`
`page`	number	页码，默认 1（与 `before` 互斥，传 `before` 时忽略）
`limit`	number	每页数量，默认 20，最大 100
`before`	string (ISO 时间戳)	可选，游标分页，返回 `created_at < before` 的任务

响应：

json

{
  "code": 0,
  "message": "获取任务列表成功",
  "data": {
    "tasks": [
      {
        "task_id": "42987a4f-...",
        "workspace_id": "8e6bc849-...",
        "channel": "workspace:8e6bc849-...",
        "agent_id": null,
        "mode": "plan",
        "status": "completed",
        "content": "...",
        "plan_id": "492c1f7a-...",
        "started_at": "2026-07-07T03:33:01.528Z",
        "completed_at": "2026-07-07T03:33:01.575Z",
        "result_summary": "...",
        "metadata": {},
        "created_at": "2026-07-07T11:32:58.416Z",
        "updated_at": "2026-07-07T11:33:01.575Z"
      }
    ],
    "has_more": false,
    "next_before": null,
    "page": 1,
    "limit": 20
  }
}

密钥归属：列表只返回由当前密钥创建的任务。next_before 为游标，下次请求作 before 传入取更早的页；null 表示已到最早。

获取任务状态

http

GET /openapi/projects/{project_id}/tasks/{task_id}

响应：

json

{
  "code": 0,
  "message": "获取任务状态成功",
  "data": {
    "task_id": "42987a4f-e35b-43e2-bd81-c8a527bdcaba",
    "workspace_id": "8e6bc849-b634-4a85-aa68-594a301dd282",
    "status": "completed",
    "channel": "workspace:8e6bc849-b634-4a85-aa68-594a301dd282",
    "mode": "plan",
    "content": "Full lifecycle test",
    "agent_id": null,
    "plan_id": "492c1f7a-f20c-4c56-8293-c384b1530a44",
    "started_at": "2026-07-07T03:33:01.528Z",
    "completed_at": "2026-07-07T03:33:01.575Z",
    "result_summary": "...",
    "metadata": {},
    "created_at": "2026-07-07T11:32:58.416Z",
    "updated_at": "2026-07-07T11:33:01.575Z",
    "active_run": null
  }
}

状态机：pending → planning / running → completed | failed | cancelled。

active_run：尽力态字段，任务有在途执行时返回 { agent_id, tool_name, started_at, updated_at }，否则为 null。
密钥归属：仅可读由当前密钥创建的任务，否则 403「任务不属于当前密钥」。

获取频道日志

http

GET /openapi/projects/{project_id}/channels/logs?channel=work-group&workspace_id={uuid}&limit=50&before=2026-07-07T11:33:00Z

频道级日志：传逻辑频道 + workspace_id 双参数，Server 组合成完整频道后查询该工作空间下该频道的对话日志——一个频道下所有任务的事件聚合为连续对话流，无需逐 task_id 查询，与 web UI 同频道日志视图一致。

传逻辑频道（work-group 或 agent:{agent_id}），不要传组合后的完整频道，也不要自带 :ws:{workspace_id} 后缀——Server 会据 workspace_id 自动追加。

频道分派（镜像 web UI 两套日志查询模式）：

work-group：工作空间群聊，聚合该工作空间的 agent_logs（含 message/tool_call/tool_response/progress/error/llm_request/llm_response）与用户提问（work_group_messages 中 sender_type='user'）。
agent:{agent_id}：工作空间内与某智能体的私聊，聚合该智能体在该工作空间的 agent_logs 与私聊历史（agent_private_messages，含用户提问分隔条）。

查询参数：

参数	类型	必填	说明
`channel`	string	是	逻辑频道：`work-group` 或 `agent:{agent_id}`
`workspace_id`	string (UUID)	是	工作空间 ID
`limit`	number	否	最大返回条数，默认 50，最大 100
`before`	string (ISO 时间戳)	否	游标分页，返回该时间戳之前的数据

响应：

json

{
  "code": 0,
  "message": "获取频道日志成功",
  "data": {
    "channel": "workspace:8e6bc849-b634-4a85-aa68-594a301dd282",
    "logical_channel": "work-group",
    "workspace_id": "8e6bc849-b634-4a85-aa68-594a301dd282",
    "logs": [
      {
        "agent_id": null,
        "agent_name": null,
        "agent_title": null,
        "agent_avatar": null,
        "type": "message",
        "data": "帮我制定一个计划",
        "error_message": null,
        "metadata": {},
        "sender_type": "user",
        "timestamp": "2026-07-07T11:32:58.416Z"
      },
      {
        "agent_id": "8e6bc849-b634-4a85-aa68-594a301dd282",
        "agent_name": "PlanTester",
        "agent_title": "计划测试员",
        "agent_avatar": null,
        "type": "llm_response",
        "data": "...",
        "error_message": null,
        "metadata": {},
        "sender_type": null,
        "timestamp": "2026-07-07T11:32:59.000Z"
      }
    ],
    "has_more": false,
    "next_before": null
  }
}

type 可能值：message、llm_request、llm_response、tool_call、tool_response、progress、error 等。
sender_type：user 表示用户提问（对话分隔条），null 表示智能体事件。
next_before：游标，下次请求作 before 传入取更早的日志；null 表示已到最早。

实时事件流（SSE）

http

GET /openapi/projects/{project_id}/channels/stream?channel=work-group&workspace_id={uuid}&token={token}
Accept: text/event-stream

频道级 SSE：订阅一个完整频道（由 channel + workspace_id 组合），实时接收该频道下所有任务的状态变化、日志、计划待确认、完成/失败事件——一个频道多任务时所有事件推到同一连接，客户端按 data.task_id 自行区分各任务。

频道级订阅按项目成员身份放行（项目密钥已 gate 项目成员）。同一频道可能由同项目多个密钥派发任务，频道视图对所有同项目密钥可见（与 web UI 项目内全员可见对齐）。
频道级是长连接订阅，频道一直可能有新任务派发，连接保持到客户端主动断开。

查询参数：

参数	类型	必填	说明
`channel`	string	是	逻辑频道：`work-group` 或 `agent:{agent_id}`
`workspace_id`	string (UUID)	是	工作空间 ID
`token`	string	是*	Access Token。EventSource 无法自定义请求头时经 URL 传递；可用 `Authorization: Bearer` 头时无需 URL 传

SSE 事件列表：

事件	说明
`connected`	连接成功，附带该频道当前活跃任务快照（`active_tasks`：pending/running/planning）
`status_changed`	任务状态变化（连接时对每个活跃任务各发一条以同步当前状态）
`log`	新日志产生，`data.task_id` 标识所属任务，`data.type` 为日志类型
`plan_pending`	有新计划待确认，`data.task_id` 标识所属任务
`completed`	任务完成
`failed`	任务失败
`cancelled`	任务取消
`heartbeat`	每 30 秒心跳
`error`	初始化失败（鉴权/参数错误）

每个事件的 data 都含 task_id（connected/heartbeat/error 除外），客户端据此把同一频道内多任务的事件分别归集。connected 事件的 data 含 active_tasks 数组，每项为 {task_id, status, mode, plan_id, started_at}。

典型用法：跟踪单个任务进度并在完成时断开

频道级是长连接订阅。典型流程是「派任务 → 订阅该工作空间该频道 → 按 task_id 过滤只关心自己的任务 → 收到终态事件（completed/failed/cancelled）主动 close()」。EventSource 断线会自动重连，无需额外处理。

// 向工作空间 A 的 work-group 派任务后，跟踪该任务进度，完成时断开
const TASK_ID = '42987a4f-e35b-43e2-bd81-c8a527bdcaba'; // 来自 POST /tasks 响应
const PROJECT = '你的项目UUID';
const WORKSPACE = '工作空间A的UUID';
const TOKEN = 'eyJhbG...';

const url = `https://pryfox.ai/openapi/projects/${PROJECT}/channels/stream`
  + `?channel=work-group&workspace_id=${WORKSPACE}&token=${encodeURIComponent(TOKEN)}`;
const es = new EventSource(url);

es.addEventListener('connected', e => {
  const snap = JSON.parse(e.data);
  console.log('已连接，频道活跃任务:', snap.active_tasks);
});

es.addEventListener('log', e => {
  const d = JSON.parse(e.data);
  if (d.task_id !== TASK_ID) return;   // 只关心自己的任务
  console.log(`[${d.type}] ${d.data ?? ''}`);
});

es.addEventListener('status_changed', e => {
  const d = JSON.parse(e.data);
  if (d.task_id === TASK_ID) console.log('状态:', d.status);
});

// 计划模式任务：收到 plan_pending 后调 POST /plans/{plan_id}/confirm 确认
es.addEventListener('plan_pending', e => {
  const d = JSON.parse(e.data);
  if (d.task_id === TASK_ID) console.log('计划待确认:', d.plan_id);
});

// 任务进入终态时关闭连接
const closeOnTerminal = e => {
  const d = JSON.parse(e.data);
  if (d.task_id === TASK_ID) { console.log('任务结束:', d.status); es.close(); }
};
['completed', 'failed', 'cancelled'].forEach(t => es.addEventListener(t, closeOnTerminal));

列出待确认计划

http

GET /openapi/projects/{project_id}/plans/pending?channel=work-group&workspace_id={uuid}

按频道返回待确认（status = proposed）计划。传逻辑频道 + workspace_id 双参数，Server 组合完整频道后直接按 agent_plans.channel 过滤——只返回该工作空间下该频道的待确认计划。

传逻辑频道（work-group 或 agent:{agent_id}），不要传组合后的完整频道，也不要自带 :ws:{workspace_id} 后缀。
用例：?channel=work-group&workspace_id=A 取工作空间 A 群聊的待确认计划；?channel=agent:agent1&workspace_id=A 取工作空间 A 下与 agent1 私聊的待确认计划。

查询参数：

参数	类型	必填	说明
`channel`	string	是	逻辑频道：`work-group` 或 `agent:{agent_id}`
`workspace_id`	string (UUID)	是	工作空间 ID

响应：

json

{
  "code": 0,
  "message": "获取待确认计划成功",
  "data": {
    "channel": "workspace:8e6bc849-b634-4a85-aa68-594a301dd282",
    "logical_channel": "work-group",
    "workspace_id": "8e6bc849-b634-4a85-aa68-594a301dd282",
    "plans": [
      {
        "plan_id": "492c1f7a-f20c-4c56-8293-c384b1530a44",
        "agent_id": "8e6bc849-b634-4a85-aa68-594a301dd282",
        "channel": "workspace:8e6bc849-b634-4a85-aa68-594a301dd282",
        "title": "Mock Plan: Verify Open API Flow",
        "description": "...",
        "status": "proposed",
        "session_id": "1e523e38-24fe-42cd-9eb1-76fd03f18c17",
        "task_id": "42987a4f-e35b-43e2-bd81-c8a527bdcaba",
        "created_at": "2026-07-07T11:33:00.000Z",
        "items": [
          {
            "id": "...",
            "step_number": 1,
            "title": "Confirm endpoint works",
            "description": "...",
            "expected_skill": "",
            "status": "pending"
          }
        ]
      }
    ]
  }
}

每条计划的 channel 是 storeAgentPlan 写入的完整频道（workspace:{wid} 群聊 / agent:{aid}:ws:{wid} 私聊），与查询时组合的频道一致。agent_id 为生成该计划的智能体。channel 取 agent:{agent_id} 时，该智能体必须属于当前项目。

确认 / 拒绝计划

http

POST /openapi/projects/{project_id}/plans/{plan_id}/confirm

请求体：

字段	类型	必填	说明
`confirm`	boolean	是	`true` 确认执行，`false` 拒绝
`feedback`	string	拒绝时必填	拒绝原因（`confirm: false` 时必传）
`workspace_id`	string (UUID)	是	计划所属工作空间，需与计划频道（`plan.channel`）解析出的工作空间一致

json

{
  "confirm": true,
  "feedback": "",
  "workspace_id": "8e6bc849-b634-4a85-aa68-594a301dd282"
}

工作空间归属校验：workspace_id 必传，且必须与计划频道解析出的工作空间一致，否则返回 403「计划不属于当前工作空间」。
密钥归属校验：用项目密钥调用时，仅可确认由当前密钥创建的任务关联的计划。若计划关联的任务由其他密钥创建，返回 403「计划不属于当前密钥」。任务无 key_id 时放行。

响应：

json

{
  "code": 0,
  "message": "计划已确认",
  "data": {
    "plan_id": "492c1f7a-f20c-4c56-8293-c384b1530a44",
    "task_id": "42987a4f-e35b-43e2-bd81-c8a527bdcaba",
    "status": "confirmed",
    "agent_id": "8e6bc849-b634-4a85-aa68-594a301dd282",
    "channel": "workspace:8e6bc849-b634-4a85-aa68-594a301dd282",
    "workspace_id": "8e6bc849-b634-4a85-aa68-594a301dd282"
  }
}

status：confirm: true 返回 confirmed（任务转 running），confirm: false 返回 rejected（任务转 cancelled，result_summary 记拒绝原因）。会话已超时返回 410。

工作空间管理

第三方可显式创建、命名、归档、删除工作空间。所有工作空间接口需项目密钥含 tasks:read（读类）或 tasks:write（写类）。

列出工作空间

http

GET /openapi/projects/{project_id}/workspaces

返回项目下全部 active + archived 工作空间（软删的不返回），每项含任务数与是否有活跃任务。

响应：

json

{
  "code": 0,
  "message": "获取工作空间列表成功",
  "data": {
    "workspaces": [
      {
        "id": "8e6bc849-b634-4a85-aa68-594a301dd282",
        "name": "客服对话池",
        "description": "面向终端用户的咨询工作空间",
        "status": "active",
        "created_by": 12,
        "created_at": "2026-07-07T11:32:58.416Z",
        "updated_at": "2026-07-07T11:32:58.416Z",
        "task_count": 5,
        "has_active_task": false,
        "channel": "workspace:8e6bc849-b634-4a85-aa68-594a301dd282"
      }
    ]
  }
}

创建工作空间

http

POST /openapi/projects/{project_id}/workspaces

显式创建工作空间并可选命名。返回的 id 可作为后续创建任务时的 workspace_id 复用。

请求体：

字段	类型	必填	说明
`name`	string	否	工作空间名称，最长 100 字符；不传则前端列表回退显示 UUID 简写
`description`	string	否	工作空间描述

响应：

json

{
  "code": 0,
  "message": "工作空间已创建",
  "data": {
    "id": "8e6bc849-b634-4a85-aa68-594a301dd282",
    "name": "客服对话池",
    "description": "面向终端用户的咨询工作空间",
    "status": "active",
    "created_by": 12,
    "created_at": "2026-07-07T11:32:58.416Z",
    "channel": "workspace:8e6bc849-b634-4a85-aa68-594a301dd282"
  }
}

获取工作空间详情

http

GET /openapi/projects/{project_id}/workspaces/{workspace_id}

响应：

json

{
  "code": 0,
  "message": "获取工作空间详情成功",
  "data": {
    "id": "8e6bc849-b634-4a85-aa68-594a301dd282",
    "name": "客服对话池",
    "description": "面向终端用户的咨询工作空间",
    "status": "active",
    "created_by": 12,
    "created_at": "2026-07-07T11:32:58.416Z",
    "updated_at": "2026-07-07T11:32:58.416Z",
    "task_count": 5,
    "active_task_count": 0,
    "message_count": 23,
    "channel": "workspace:8e6bc849-b634-4a85-aa68-594a301dd282"
  }
}

task_count：该工作空间下全部任务数（含历史）。
active_task_count：处于 pending/running/planning 的活跃任务数。
message_count：该工作空间群聊消息数。

更新工作空间

http

PUT /openapi/projects/{project_id}/workspaces/{workspace_id}

改名、改描述、在 active ↔ archived 之间切换状态。归档可逆，不删除历史数据。至少传一个可更新字段。

请求体：

字段	类型	必填	说明
`name`	string	否	新名称，最长 100 字符；传空字符串则清空为 `null`
`description`	string	否	新描述
`status`	string	否	`active` 或 `archived`

响应：

json

{
  "code": 0,
  "message": "工作空间已更新",
  "data": {
    "id": "8e6bc849-b634-4a85-aa68-594a301dd282",
    "name": "客服对话池 v2",
    "description": "面向终端用户的咨询工作空间",
    "status": "archived",
    "created_by": 12,
    "created_at": "2026-07-07T11:32:58.416Z",
    "updated_at": "2026-07-08T09:00:00.000Z",
    "channel": "workspace:8e6bc849-b634-4a85-aa68-594a301dd282"
  }
}

工作空间级计划模式默认值（plan_mode_enabled）由项目成员在 web UI 工作空间管理页设置，开放 API 的工作空间接口不暴露此字段。第三方按需逐任务控制计划模式时，在创建任务的 mode 字段显式传 plan 或 auto 即可。

删除工作空间

http

DELETE /openapi/projects/{project_id}/workspaces/{workspace_id}

软删除工作空间（status = deleted + deleted_at），保留历史消息 / 日志 / 任务行便于审计。

带活跃任务删除：若工作空间下有活跃任务（pending / running / planning），仍允许删除（软删）。删除时程序会终止这些任务：在途的流式执行会被中止（向 Claw 发 cancel_message），任务记录被置为 cancelled（终态），task 行保留为历史记录便于审计。列表接口返回的 has_active_task 字段可用于在前端给出警告提示。

复活语义：软删后，用同一 workspace_id 再次派任务会自动恢复为 active。故对开放 API 第三方而言，「删除」实为「暂停」——持有的工作空间 ID 不会因管理端软删而死锁。

响应：

json

{
  "code": 0,
  "message": "工作空间已删除",
  "data": {
    "id": "8e6bc849-b634-4a85-aa68-594a301dd282",
    "terminated_tasks": 2
  }
}

terminated_tasks：删除时被终止的活跃任务数。该工作空间下的会话数据（群聊/私聊消息软删、日志/计划硬删）与 Claw 记忆数据会被一并清除，主频道（workspace_id IS NULL）数据不受影响。复活的工作空间是「空白」上下文，不保留旧对话。

智能体列表（内部接口）

http

GET /api/projects/{project_id}/agents?page=1&limit=20&status=active&search=Plan

工作空间内的智能体由协调员自动选派，无需在创建任务时指定 agent_id。若需了解项目下有哪些智能体及其配置，可通过此接口查询。注意此接口走 /api/ 内部前缀，非 /openapi/。

权限要求：项目密钥需包含 employees:read。

查询参数：

page：页码，默认 1
limit：每页数量，默认 20，最大 100
status：按状态筛选
search：按名称或标题模糊搜索

响应：

json

{
  "code": 0,
  "message": "获取智能体列表成功",
  "data": {
    "agents": [
      {
        "id": "8e6bc849-b634-4a85-aa68-594a301dd282",
        "name": "PlanTester",
        "title": "计划测试员",
        "avatar": null,
        "role": "member",
        "is_system": false,
        "model": { "id": "...", "name": "mock-llm" },
        "status": "idle",
        "status_text": "等待任务",
        "device": null,
        "self_reflect": false,
        "plan_mode_enabled": true,
        "stats": {},
        "skill_count": 0,
        "created_at": "2026-07-06T...",
        "updated_at": "2026-07-06T..."
      }
    ],
    "user_role": "member",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "total_pages": 1,
      "has_more": false
    }
  }
}

智能体的 plan_mode_enabled 是该智能体自身的计划模式开关（创建智能体时配置），与工作空间级计划模式默认值是两个不同概念。status 受当前用户在途任务影响（有在途任务时显示 working）。

常见错误码

HTTP 状态	说明
400	参数错误，如内容为空、workspace_id 非法、拒绝计划缺 feedback、status 取值非法
401	未认证或 Token 失效
403	无项目权限、密钥缺少对应操作权限、或任务/计划不属于当前密钥/工作空间
404	任务 / 智能体 / 计划 / 工作空间不存在
409	计划已处理不可重复确认
410	计划确认会话已超时
429	认证接口被速率限制
500	服务端内部错误

调用示例

bash

# 1. 换取 Token
TOKEN_RESP=$(curl -s -X POST https://pryfox.ai/openapi/auth/project-key \
  -H 'Content-Type: application/json' \
  -d '{"key":"proj_xxxxx_xxxxxx"}')
TOKEN=$(echo "$TOKEN_RESP" | jq -r '.data.token')
CSRF=$(echo "$TOKEN_RESP" | jq -r '.data.csrfToken')
PROJECT='你的项目UUID'
WORKSPACE='自定义工作空间UUID'   # 可先用工作空间管理接口创建，或直接派任务时隐式建

# 2. 创建工作空间（可选，便于命名管理）
curl -s -X POST "https://pryfox.ai/openapi/projects/$PROJECT/workspaces" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: $CSRF" \
  -d '{"name":"客服对话池","description":"面向终端用户的咨询工作空间"}'

# 3. 创建任务（指定工作空间 + 群聊频道 + 计划模式）
TASK_RESP=$(curl -s -X POST "https://pryfox.ai/openapi/projects/$PROJECT/tasks" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: $CSRF" \
  -d "{\"content\":\"帮我制定一个计划\",\"workspace_id\":\"$WORKSPACE\",\"channel\":\"work-group\",\"mode\":\"plan\"}")
TASK_ID=$(echo "$TASK_RESP" | jq -r '.data.task_id')

# 4. 列出该工作空间 work-group 频道的待确认计划
PENDING=$(curl -s "https://pryfox.ai/openapi/projects/$PROJECT/plans/pending?channel=work-group&workspace_id=$WORKSPACE" \
  -H "Authorization: Bearer $TOKEN")
PLAN_ID=$(echo "$PENDING" | jq -r '.data.plans[0].plan_id')

# 5. 确认计划
curl -s -X POST "https://pryfox.ai/openapi/projects/$PROJECT/plans/$PLAN_ID/confirm" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: $CSRF" \
  -d "{\"confirm\":true,\"workspace_id\":\"$WORKSPACE\"}"

# 6. 订阅该工作空间 work-group 频道实时事件流（按 task_id 跟踪，终态时断开）
#    EventSource 无法自定义请求头，token 经 URL 传递
#    在 JS 客户端用 new EventSource(...)，按 data.task_id 过滤自己的任务，
#    收到 completed/failed/cancelled 后 es.close()（频道级长连接不会自动关）

# 7. 列出该工作空间下的全部任务
curl -s "https://pryfox.ai/openapi/projects/$PROJECT/tasks?workspace_id=$WORKSPACE&limit=20" \
  -H "Authorization: Bearer $TOKEN"

# 8. 拉取该工作空间 work-group 频道的历史日志（连接前补齐已有事件）
curl -s "https://pryfox.ai/openapi/projects/$PROJECT/channels/logs?channel=work-group&workspace_id=$WORKSPACE&limit=50" \
  -H "Authorization: Bearer $TOKEN"

开放 API ​

基础信息 ​

认证方式 ​

1. 换取 Token ​

2. 调用接口 ​

工作空间与频道 ​

接口列表 ​

创建任务 ​

列出任务 ​

获取任务状态 ​

获取频道日志 ​

实时事件流（SSE） ​

典型用法：跟踪单个任务进度并在完成时断开 ​

列出待确认计划 ​

确认 / 拒绝计划 ​

工作空间管理 ​

列出工作空间 ​

创建工作空间 ​

获取工作空间详情 ​

更新工作空间 ​

删除工作空间 ​

智能体列表（内部接口） ​

常见错误码 ​

调用示例 ​

开放 API

基础信息

认证方式

1. 换取 Token

2. 调用接口

工作空间与频道

接口列表

创建任务

列出任务

获取任务状态

获取频道日志

实时事件流（SSE）

典型用法：跟踪单个任务进度并在完成时断开

列出待确认计划

确认 / 拒绝计划

工作空间管理

列出工作空间

创建工作空间

获取工作空间详情

更新工作空间

删除工作空间

智能体列表（内部接口）

常见错误码

调用示例