PE Agent 集成（PowerCore 平台对接指南）¶

当前章节还未完善

本文面向需要接入 AI Power 智能体平台的业务系统开发者，说明如何通过 HTTP 与 WebSocket 完成鉴权、用户同步、任务创建、对话与流式结果消费。内容以 PE Agent 当前已对接的能力 为准；未在本文列出的平台接口，请向平台方索取正式文档。

PE Agent 仓库内另有 PowerCore 集成实现说明。开放 API 轮询模式见接口 API。

1. 对接前准备¶

向 AI Power 平台方申请：

项	说明
API 根地址	如 `https://api.example.com`，下文记为 `{BASE}`
App ID	应用标识 `app_id`
App Secret	应用密钥 `app_skey`，用于签名，勿泄露
WebSocket 路径	如 `/peagent/api/chat_ws`
Agent ID	各业务场景在平台侧预置的智能体 ID（PE Agent 使用本地库中已有 `agent_id`，不提供 Agent 创建/更新接口）

对接方需在己方系统维护「业务用户 ↔ AI Power 用户」的映射（通常用 external_user_id 关联）。

2. 通用约定¶

2.1 HTTP¶

Content-Type：application/json（文件上传除外）
成功判定：响应 JSON 中 code == 200；data 为业务载荷
例外：部分扩展接口（如 LightRAG，见 §4.4）根地址同样走 {BASE}，但响应为直接 JSON 体，无 code/data 包装
鉴权：见第 3 节，用户级接口使用 Header Authorization: Bearer {user_token}

示例响应壳：

{
  "code": 200,
  "message": "success",
  "data": { }
}

失败时 code 非 200，message 为平台错误说明；HTTP 层也可能返回 4xx/5xx。对接方应：

记录完整 URL、请求体摘要、code / message、响应体（脱敏后）
鉴权类错误：刷新 access_token 或 user_token 后重试一次
业务类错误：勿盲目重试，按业务决定是否提示用户

平台方若有错误码表，以官方文档为准；本文不枚举全部 code。

2.2 WebSocket¶

由 {BASE} 的 https → wss（http → ws）
连接 URL：wss://{host}{WS_PATH}?token={user_token}
帧为 UTF-8 文本，内容为 JSON 对象；非 JSON 文本视为异常
出站、入站消息统一形如：{"type": "事件类型", "data": { ... } }（type 为字符串，如 stream、confirm）

3. 鉴权¶

两级 Token：应用 Token（管用户）与 用户 Token（管对话与 Agent）。

sequenceDiagram
    participant App as 对接方服务
    participant AI as AI Power

    App->>AI: POST get_token<br/>X-App-Id / X-Timestamp / X-Signature
    AI-->>App: access_token
    App->>AI: POST add_user<br/>Bearer access_token
    AI-->>App: user_id / username
    App->>AI: POST user_login<br/>Bearer access_token
    AI-->>App: user_token
    App->>AI: HTTP 用户级接口 / WS ?token=user_token

3.1 获取应用 access_token¶

接口：POST {BASE}/peagent/api/get_token（路径以环境为准）

请求头（签名鉴权，无 Bearer）：

Header	说明
`X-App-Id`	应用 ID
`X-Timestamp`	Unix 秒级时间戳字符串
`X-Signature`	见下方算法

签名算法（HMAC-SHA256，hex 小写）：

raw = app_id + timestamp + app_skey
signature = HMAC_SHA256(key=app_skey, message=raw).hexdigest()

响应 data 示例：

{
  "access_token": "eyJ...",
  "expires_in": 3600
}

access_token 建议缓存复用。当前实现会把缓存过期时间设为 expires_in - 100～300 秒 的随机提前量，并在剩余不足约 30 秒时刷新；刷新失败但仍有缓存时，会降级使用缓存 token。

user_token 刷新策略相同：按用户缓存，接近过期时重新 user_login；刷新失败但有缓存时降级使用缓存 token。

3.2 注册用户 add_user¶

接口：POST {BASE}/peagent/api/add_user

请求头：Authorization: Bearer {access_token}

请求体：

{
  "external_user_id": "己方用户唯一 ID（字符串）",
  "nickname": "显示名称",
  "tel": "手机号（可选）"
}

响应 data 示例：

{
  "user_id": 12345,
  "username": "platform_username"
}

首次接入用户时调用；已存在用户可由平台幂等处理或返回已有信息（以平台行为为准）。

3.3 用户登录 user_login¶

接口：POST {BASE}/peagent/api/user_login

请求头：Authorization: Bearer {access_token}

请求体：

{
  "external_user_id": "与 add_user 一致",
  "nickname": "显示名称"
}

响应 data 示例：

{
  "user_token": "eyJ...",
  "expires_in": 3600
}

后续所有用户级 HTTP 与 WebSocket 均使用 user_token。

4. HTTP 接口一览¶

以下路径为常见命名；部署环境可能略有差异。

4.1 任务与对话控制¶

进入智能体（创建任务）¶

POST {BASE}/peagent/api/enter_agent

Header：Authorization: Bearer {user_token}

Body：

{
  "agent_id": 2157,
  "message": "首轮提示或空字符串"
}

响应 data：

{
  "task_id": 987654321
}

task_id 是对话会话的核心 ID，后续 WS 消息、重新生成、暂停等均依赖它。

重新生成¶

POST {BASE}/peagent/api/re_generate

Body：

{
  "task_id": 987654321,
  "content": "用户补充说明",
  "message_id": "要重新生成的消息 ID",
  "agent_id": 2157,
  "node_id": 100
}

Header：Authorization: Bearer {user_token}

响应 data 示例：

{
  "task_id": 987654322
}

新 task_id 产生后，须在 WebSocket 侧重绑当前会话的「当前任务」，并继续 recv。

编辑 LLM 回复后继续¶

POST {BASE}/peagent/api/modify_llm_response

Header：Authorization: Bearer {user_token}

Body：

{
  "task_id": 987654321,
  "content": "编辑后的全文",
  "message_id": "消息 ID"
}

调用后应继续通过 WebSocket 接收后续推送（同一 task_id）。

编辑后的流式输出：

先确保当前用户的 WebSocket 已连接，并且本地仍按该 task_id 分发入站消息。
调用 modify_llm_response 成功后，不需要再次 enter_agent，直接继续 recv。
编辑流主要关注两类帧：
stream：增量文本分片，用于打字机展示。
refine：编辑完成后的最终全文，用于覆盖原消息内容；收到后本轮编辑流即可结束。

refine 帧示例：

{
  "type": "refine",
  "data": {
    "task_id": 987654321,
    "message_id": "消息 ID",
    "content": "编辑后的最终全文"
  }
}

sequenceDiagram
    participant Client as 对接方
    participant HTTP as AI Power HTTP
    participant WS as AI Power WS

    Client->>WS: 已连接并绑定 task_id
    Client->>HTTP: POST modify_llm_response<br/>task_id + message_id + content
    HTTP-->>Client: code = 200
    WS-->>Client: stream（编辑过程增量）
    WS-->>Client: refine（最终全文）
    Client->>Client: 用 refine.data.content 覆盖原消息

暂停任务¶

POST {BASE}/peagent/api/pause_task

Header：Authorization: Bearer {user_token}

Body：

{
  "task_id": 987654321
}

4.2 文件¶

上传¶

POST {BASE}/peagent/api/common/upload_file

Header：Authorization: Bearer {user_token}
Body：multipart/form-data，字段名 file

响应 data 示例（字段名以环境为准，常见如下）：

{
  "saved_path": "user_upload/2025/xxx.pdf",
  "file_size": "102400"
}

saved_path：平台内文件路径，dialog 的 files 里通常用 file_name 传该值（见 5.2）
file_size：字符串或数字，表示大小

下载¶

GET {BASE}/peagent/api/common/download_file?file_name=...&task_id=...

task_id 可选；响应为文件二进制流。

替换个人文件¶

POST {BASE}/peagent/api/replace_my_file

Header：Authorization: Bearer {user_token}

Body：

{
  "filename": "sub/test.txt",
  "new_content": "替换后的全文"
}

filename 支持子目录形式（如 sub/test.txt）。成功时不返回业务载荷（以环境为准）。

读取目录¶

GET {BASE}/peagent/common/read-directory?path=...&recursive=false

Header：Authorization: Bearer {access_token}（应用级）

Query：

参数	说明
`path`	目录路径，如 `智能体入口介绍` 或 `{phone}/学习文件夹`
`recursive`	`true` / `false`，是否递归

响应 data 示例：

{
  "files": [
    {
      "file_name": "示例.txt",
      "content": "文件文本内容"
    }
  ]
}

目录不存在或无权访问时，平台可能返回非 200；对接方可按需容错处理。

4.3 用户大模型密钥¶

用户级接口，路径前缀常见为 /peagent/user-llm-keys（以环境为准）。

操作	方法	路径示例
创建	POST	`/peagent/user-llm-keys/`
列表	GET	`/peagent/user-llm-keys/?page=1&page_size=50`
更新	PUT	`/peagent/user-llm-keys/{key_id}`
删除	DELETE	`/peagent/user-llm-keys/{key_id}`

Header：Authorization: Bearer {user_token}

创建 Body 示例：

{
  "model": "gpt-4o",
  "base_url": "https://api.example.com/v1",
  "api_key": "sk-...",
  "max_tokens": 4096,
  "temperature": 0.7
}

列表响应 data 示例：

{
  "count": 1,
  "page": 1,
  "list": [
    {
      "id": 1,
      "model": "gpt-4o",
      "base_url": "https://api.example.com/v1",
      "max_tokens": 4096,
      "temperature": 0.7
    }
  ]
}

字段名以平台返回为准；api_key 等敏感字段的读写策略以平台方文档为准。

4.4 知识图谱（LightRAG）¶

根地址与其它接口相同，走 {BASE}。

GET {BASE}/lightrag/open_graphs?label=*&max_depth=3&max_nodes=1000

Header：Authorization: Bearer {user_token}

Query：

参数	默认	说明
`label`	`*`	图谱标签过滤
`max_depth`	`3`	最大深度
`max_nodes`	`1000`	最大节点数

响应：直接 JSON 体（无 code/data 包装），通常含节点、边等图谱结构；具体 schema 以平台方文档为准。

5. WebSocket 对接（核心）¶

5.1 建立连接¶

调用 user_login 取得 user_token
连接 WebSocket：

wss://{host}/peagent/api/chat_ws?token={user_token}

当前实现按会话建立 WebSocket：一次业务 session 结束、最后一条链路关闭后会关闭物理连接；仅同一用户多个 session 时间重叠时，才会在同一物理连接上挂多条逻辑链路。

连接成功后，平台可能先推送若干帧（如任务初始化、confirm 等），对接方应持续 recv 直至业务就绪。

sequenceDiagram
    participant Client as 对接方
    participant HTTP as AI Power HTTP
    participant WS as AI Power WS

    Client->>WS: 建立 WebSocket<br/>?token=user_token
    Client->>HTTP: POST enter_agent(agent_id)
    HTTP-->>Client: task_id
    Client->>Client: 绑定 task_id -> 当前会话队列
    WS-->>Client: confirm / executing 等 enter 后推送
    Client->>WS: dialog {task_id, content/files}
    WS-->>Client: stream / executing / confirm

5.2 出站：发送用户输入¶

dialog — 发送一轮对话¶

{
  "type": "dialog",
  "data": {
    "task_id": 987654321,
    "content": "用户输入文本",
    "files": []
  }
}

字段	必填	说明
`task_id`	是	`enter_agent` 返回
`content`	与 `files` 至少一项	文本内容
`files`	与 `content` 至少一项	文件引用数组，见下表

files 元素示例（由 upload_file 的 saved_path 填入 file_name）：

"files": [
  {
    "file_name": "user_upload/2025/report.pdf",
    "file_size": "102400"
  }
]

仅发附件、无文本时 content 可传空字符串 ""。

发送后继续 recv，处理平台推送的流式与状态帧。

confirm — 确认/推进流程¶

用于用户确认节点产出、交付物确认等场景：

{
  "type": "confirm",
  "data": {
    "task_id": 987654321
  }
}

5.3 入站：平台推送消息类型¶

入站帧格式：

{
  "type": "stream",
  "data": { }
}

部分场景下 executing 的 data 可能为嵌套很深的 JSON 对象（内含 dialog.dialog.agents 等），对接方按需解析；也有实现将其作为字符串再 JSON.parse。

type	含义	对接建议
stream-start	某条消息流式开始	重置本地流缓冲
stream	流式增量	`data.content` 为文本片段；可有 `data.message_id`、`data.task_id`
stream-end	流式结束	刷新缓冲，可触发落库
executing	执行态快照	含节点进度、最新消息、附件元数据等；同步场景常在此解析最终结果
executed	某节点执行完成	`data.task_generated_data` 等结构化产出
confirm	一轮结束或等待用户确认	同步对话常以收到 `confirm` 作为本轮结束标志
refine	编辑后的最终全文	编辑 LLM 回复后返回；用 `data.content` 覆盖原消息内容
clarify	需用户补充信息	上游暂停等待补充；对接方可标记 waiting 状态，用户补充后重新 enter 或续聊
rate_limit_blocked	上游限流	`data.reason` 为说明正文；本轮结束，应向用户展示原因
user_message	上游自动产生的用户侧消息	`data.content`；由平台逻辑自动写入（非真实用户输入），可按业务决定是否展示/落库
del_message	删除某条消息	`data.message_id`；本地 UI 应隐藏或移除对应消息
active_task	活动任务切换	`data.task_id` 为新任务，`data.pre_task_id` 为上一任务；多 Agent 编排时需更新本地「当前 task_id」
call_agent	调用子智能体	`data.caller` / `data.callee` 表示调用关系；子任务消息可能带不同 `task_id`

task_id 出现在：

data.task_id
或帧顶层 task_id（较少）

对接方应用字符串规范化比较（避免 int/string 混用导致路由错误）。

5.4 `executing` 数据说明（摘要）¶

executing 通常承载「当前对话全量快照」，常见用途：

流式展示：配合 stream / stream-end
同步取结果：从 dialog.dialog.agents[0].messages 中取 current_state.last_message_id 对应消息的 content
进度：data.task_progress 或 data.task_context 中的节点状态
结构化笔记：data.task_generated_data（如 show、message 字段）
附件：消息 metadata 中的文件名、大小等
展示控制：当前消息上的 display 字段（见下）

消息展示控制：`display`¶

executing 快照里，当前消息位于：

data.dialog.dialog.agents[0].messages[]   # 与 current_state.last_message_id 匹配的那条

每条 message 对象可带 display，用于控制该条助手输出是否对终端用户展示：

`display` 取值	含义
`true`	展示正文、`stream` 拼接结果等
`false`	隐藏输出：不在对话 UI 中展示该条消息内容

对接注意：display 仅约束消息正文是否展示，与确认、刷新、编辑等交互按钮无关；task_progress / task_context、节点状态、confirm 等控制类帧通常仍应正常处理，避免流程卡住。

正文控制标签：`show_content` / `show_actions`¶

助手消息 content 中可嵌入控制标签；展示前应剥离标签，仅保留对用户可见的正文：

标签	说明
`<show_content>...</show_content>`	仅展示标签内正文；标签外内容不对用户展示
`<show_right>...</show_right>`	右侧动作区文案
`<show_left>...</show_left>`	左侧动作区文案
`<show_down>...</show_down>`	下方动作区文案

对接方可将 show_right / show_left / show_down 解析为 UI 动作配置（如 { "right": "...", "left": "...", "down": "..." }）。

部分 Agent 还会在正文中使用 ```questions 代码块承载结构化问答；收到后宜关闭「下一步 / 编辑」等按钮，仅保留刷新（以业务为准）。

交互按钮：确认、刷新、编辑¶

平台不会在单独帧里下发「是否显示按钮」布尔值；对接方在收到 executing 后，从当前消息（last_message_id 对应那条）解析 role、metadata.status 等字段，自行计算是否禁用各按钮。

以下是对接方自行实现客户端时的建议算法，不是 PE Agent 前端/SSE 的实际按钮策略。PE Agent 会在 SSE 层二次计算 next / refresh / modify（见 PowerCore 集成 §7.4）。

建议读取字段（均在 messages[] 单条或 metadata 内）：

字段	说明
`role`	如 `assistant`、`system`
`metadata.status`	如 `pending`、`running`、`completed`、`confirmed`；缺省按 `'pending'`
`message_id`	调用 `re_generate` / `modify_llm_response` 时必填
`node_id`	调用 `re_generate` 时必填

确认（下一步 / Confirm）¶

默认禁用确认按钮，再按状态放开：

disable_confirm = True
disable_button = False

if message.get("role") == "system":
    disable_button = True  # 系统消息：所有交互按钮禁用（含确认、刷新、编辑）

status = (message.get("metadata") or {}).get("status") or "pending"

if status == "completed":
    disable_confirm = True
if status == "confirmed":
    disable_confirm = False  # 仅此状态允许用户点确认

规则简化为：

role == "system"：确认、刷新、编辑全部不展示。
确认按钮：仅 metadata.status == "confirmed" 时启用；其他状态（含缺省、pending、running、completed）均禁用。

刷新（重新生成）、编辑¶

刷新、编辑只看 role：role != "system" 时可展示，不按 completed / confirmed 切换。

按钮	HTTP 接口	说明
刷新	`POST .../re_generate`	Body：`task_id`、`message_id`、`agent_id`、`node_id`；响应新 `task_id` 后继续 WS `recv`
编辑	`POST .../modify_llm_response`	Body：`task_id`、`message_id`、编辑后 `content`；成功后继续 WS `recv`

消息对象片段示例：

{
  "message_id": "msg_abc123",
  "role": "assistant",
  "node_name": "某节点",
  "content": "{ ... }",
  "display": false
}

具体字段以平台返回为准；建议对接时打印首条完整 executing 做 schema 对齐。

stream 帧 data 常见字段：

字段	类型	说明
`task_id`	int	所属任务
`message_id`	string	同一条回复的分片 ID，拼接 stream 时使用
`content`	string	本帧文本增量

active_task 帧 data 示例：

{
  "task_id": 987654400,
  "pre_task_id": 987654321
}

收到后应将本地「当前执行 task_id」更新为 task_id。

call_agent 帧 data 示例：

{
  "caller": 987654321,
  "callee": 987654400
}

callee 为子任务 ID，后续带该 task_id 的 stream / executing 归属子 Agent。

user_message 帧 data 示例：

{
  "task_id": 987654321,
  "message_id": "msg_auto_001",
  "content": "确认"
}

表示上游逻辑自动写入的用户侧消息（如自动「确认」），不等于终端用户真实输入；若上一条 assistant 尚未回复，对接方可选择抑制展示。

del_message 帧 data 示例：

{
  "task_id": 987654321,
  "message_id": "msg_abc123"
}

rate_limit_blocked 帧 data 示例：

{
  "task_id": 987654321,
  "reason": "请求过于频繁，请稍后再试"
}

executed 帧：节点跑完时推送；data.task_generated_data 常为结构化结果，例如：

{
  "task_generated_data": {
    "show": "message",
    "message": "节点产出正文或 JSON 字符串",
    "内容输出": "部分 Agent 使用的业务字段名"
  }
}

字段名因 Agent 模板而异，对接时以实际 Agent 约定为准。

5.5 连接与多任务实践¶

平台侧一条 WebSocket 可服务同一用户的多个 task_id。对接方若并发多个 HTTP 请求，须自行：

按 task_id 分发入站消息到对应请求队列（勿混流）
处理 active_task / call_agent 时更新 task_id 映射
发送 dialog 时带上正确的 task_id

同一用户多路并发¶

当前实现对同一用户使用“物理 WebSocket + 逻辑链路”的模型：

user_id
  └─ 一条活跃物理 WebSocket（仅多个会话重叠时复用）
       ├─ link-A：请求 A 的队列
       ├─ link-B：请求 B 的队列
       └─ link-C：请求 C 的队列

flowchart LR
    WS[同一用户的一条活跃 WebSocket]
    R[接收线程 recv]
    M[task_id -> link_id 路由表]
    QA[link-A 队列<br/>请求 A]
    QB[link-B 队列<br/>请求 B]
    QC[link-C 队列<br/>请求 C]

    WS --> R --> M
    M -->|task_id 属于 A| QA
    M -->|task_id 属于 B| QB
    M -->|task_id 属于 C| QC

核心规则：

按用户分槽：同一 user_id 同一时刻最多挂一条活跃物理 WS；如果没有活跃链路，session 结束时会关闭该 WS。
按请求建 link：每个并发请求进入时生成一个 link_id，并创建独立队列。
先建 WS，再 enter：新任务先打开 WS/link，再 enter_agent 获取 task_id。
绑定路由：拿到 task_id 后立刻建立 task_id -> link_id 映射。
入站分发：接收线程统一读 WS 帧，根据 data.task_id（或顶层 task_id）找到 link_id，再投递到对应队列。
任务切换：
active_task：用 pre_task_id 找到原 link，将新 task_id 继续绑定到同一 link。
call_agent：用 caller 找到原 link，将 callee 绑定到同一 link。
链路结束：单个请求结束时删除该 link_id 及其 task 映射；若该用户已无其它 link，则关闭物理 WS。

注意：如果入站帧的 task_id 没有绑定到任何 link，会被视为无路由消息并丢弃。因此并发场景里，enter_agent、re_generate 返回新 task_id 后必须立即更新映射。

伪代码：

begin_session(user_id):
  ws = get_or_connect_user_ws(user_id)
  link_id = new_link_id()
  queues[link_id] = Queue()
  return ws, link_id

bind_task(task_id, link_id):
  task_to_link[str(task_id)] = link_id

on_ws_message(msg):
  if msg.type == "active_task":
    link_id = task_to_link[str(msg.data.pre_task_id)]
    bind_task(msg.data.task_id, link_id)
  elif msg.type == "call_agent":
    link_id = task_to_link[str(msg.data.caller)]
    bind_task(msg.data.callee, link_id)

  task_id = msg.data.task_id or msg.task_id
  link_id = task_to_link.get(str(task_id))
  if link_id:
    queues[link_id].put(msg)

send_dialog(task_id, link_id, content):
  bind_task(task_id, link_id)
  ws.send({ "type": "dialog", "data": { "task_id": task_id, "content": content } })

end_session(link_id):
  remove_link_and_task_routes(link_id)
  if no_open_links_for_user():
    close_ws()

5.6 超时与重连¶

平台长时间无推送时，对接方应设置空闲超时（按业务调整）。PE Agent 当前实现为首包 60s、后续空闲 300s，不是平台硬性值。
连接断开：重新 user_login（若 token 过期）→ 重连 WS → 视业务决定是否 enter_agent 新任务或续聊已有 task_id
发送失败：重连后重发最后一条 dialog/confirm（注意幂等与重复消息处理）

6. 典型对接流程¶

6.1 一次性同步对话（HTTP + WS）¶

适用于：提交任务后等待一次 Agent 运行的完整结果。

推荐顺序：先连 WebSocket，再 enter_agent。enter 之后平台往往立刻经 WS 推送若干帧（常见含 confirm），若尚未建连会丢消息。

1. user_login → user_token
2. WSS connect(?token=user_token)
3. POST enter_agent(agent_id) → task_id
4. recv 直到 type=confirm（消化 enter 后的首轮推送）
5. WS send dialog { task_id, content, files? }
6. 循环 recv：
     - stream*     → 可选展示进度
     - executing   → 累积/解析
     - stream-end  → 尝试从 executing 解析最终结果
     - confirm     → 结束
7. 关闭 WS

结束条件：收到 confirm，或 stream-end 且已从 executing 解析出业务所需 JSON/文本。

PE Agent 当前实现：先建立 WS，再 enter_agent（可将首轮 message 一并传入），随后 recv_stream；续聊走 dialog，确认走 confirm。见 streaming/raw.py 的 run_agent_stream_raw()。

6.2 流式对话（多轮）¶

适用于：聊天 UI、打字机效果。

1. user_login
2. WSS connect
3. enter_agent → task_id
4. recv（enter 后推送）→ 转发 stream/executing 到前端
5. 用户每发一句：WS dialog { task_id, content }
6. 持续 recv → 转发 stream 片段
7. 用户点击「确认」：WS confirm { task_id }
8. 需要重新生成：可先保持/重连 WS → HTTP re_generate → 新 task_id → recv

后续轮次若已有 task_id：可 WS connect → 直接 dialog/confirm（无需再次 enter）。

6.3 带附件的对话¶

1. POST upload_file → 文件引用
2. WSS connect
3. enter_agent → task_id
4. recv 至 confirm
5. WS dialog { task_id, content: "", files: [上传返回的引用] }
6. recv 至 confirm
7. WS dialog { task_id, content: "后续文本问题" }
8. 解析 executing / executed

6.4 多智能体 / 子任务¶

当主 Agent 调用子 Agent 时：

收到 call_agent：记录 callee 为新子 task_id
子任务相关的 stream / executing 可能带不同 task_id，UI 上可区分「主任务 / 子任务」
收到 active_task：将当前执行上下文切换为 data.task_id

7. 对接检查清单¶

[ ] 已申请 app_id / app_skey，并实现 get_token 签名
[ ] 用户首次使用走 add_user，之后 user_login 缓存 user_token
[ ] enter_agent 成功拿到 task_id
[ ] WS URL 使用 user_token query 参数，能稳定 recv
[ ] 能发送 dialog / confirm 并正确解析 stream / executing / confirm
[ ] 能处理 clarify / rate_limit_blocked / user_message / del_message 等扩展帧
[ ] 多请求并发时按 task_id 隔离消息
[ ] 处理 active_task / call_agent 不丢消息
[ ] HTTP 仅认 code == 200；异常有日志与重试
[ ] Token 过期刷新；WS 断线重连策略已验证

8. 常见问题¶

现象	可能原因
WS 连上但收不到业务消息	enter 前未建连，推送丢失；或 task_id 错误、未按 task 分发
消息串到别的请求	多任务共用一个 WS 但未按 `task_id` 分发
HTTP 始终失败	`code` 非 200；用了过期 `user_token`；`agent_id` 类型不符
只有 stream 没有最终结果	未等到 `confirm` 或未在 `stream-end` 后解析 `executing`
子 Agent 内容缺失	未订阅 `call_agent` 的 `callee` 对应 `task_id`
收到意外 user_message	上游自动写入的用户侧消息；可按业务抑制或落库
LightRAG 返回非标准 JSON	根地址走 `{BASE}`，响应为直接 JSON 体；勿按 `code == 200` 解析
read_directory 返回空	目录不存在、路径错误或使用了 user_token 而非 access_token

9. 附录：路径速查（示例环境）¶

能力	方法	路径
应用 Token	POST	`/peagent/api/get_token`
添加用户	POST	`/peagent/api/add_user`
用户登录	POST	`/peagent/api/user_login`
进入智能体	POST	`/peagent/api/enter_agent`
WebSocket	WSS	`/peagent/api/chat_ws?token=`
重新生成	POST	`/peagent/api/re_generate`
编辑回复	POST	`/peagent/api/modify_llm_response`
暂停任务	POST	`/peagent/api/pause_task`
上传文件	POST	`/peagent/api/common/upload_file`
下载文件	GET	`/peagent/api/common/download_file`
替换个人文件	POST	`/peagent/api/replace_my_file`
读取目录	GET	`/peagent/common/read-directory`
用户 LLM Key	POST/GET/PUT/DELETE	`/peagent/user-llm-keys/` 或 `/{id}`
知识图谱	GET	`{BASE}/lightrag/open_graphs`

本文根据已对接生产系统的调用方式整理，便于第三方快速联调；字段细节、错误码表、Agent 图结构请以 AI Power 平台方正式文档为准。

PE Agent 集成（PowerCore 平台对接指南）¶

1. 对接前准备¶

2. 通用约定¶

2.1 HTTP¶

2.2 WebSocket¶

3. 鉴权¶

3.1 获取应用 access_token¶

3.2 注册用户 add_user¶

3.3 用户登录 user_login¶

4. HTTP 接口一览¶

4.1 任务与对话控制¶

进入智能体（创建任务）¶

重新生成¶

编辑 LLM 回复后继续¶

暂停任务¶

4.2 文件¶

上传¶

下载¶

替换个人文件¶

读取目录¶

4.3 用户大模型密钥¶

4.4 知识图谱（LightRAG）¶

5. WebSocket 对接（核心）¶

5.1 建立连接¶

5.2 出站：发送用户输入¶

dialog — 发送一轮对话¶

confirm — 确认/推进流程¶

5.3 入站：平台推送消息类型¶

5.4 executing 数据说明（摘要）¶

消息展示控制：display¶

正文控制标签：show_content / show_actions¶

交互按钮：确认、刷新、编辑¶

确认（下一步 / Confirm）¶

刷新（重新生成）、编辑¶

5.5 连接与多任务实践¶

同一用户多路并发¶

5.6 超时与重连¶

6. 典型对接流程¶

6.1 一次性同步对话（HTTP + WS）¶

6.2 流式对话（多轮）¶

6.3 带附件的对话¶

6.4 多智能体 / 子任务¶

7. 对接检查清单¶

8. 常见问题¶

9. 附录：路径速查（示例环境）¶

5.4 `executing` 数据说明（摘要）¶

消息展示控制：`display`¶

正文控制标签：`show_content` / `show_actions`¶