← 返回周目标完成情况

AI 创业平台 × ndclaw 对接：背景、已确认事项与待办

2026-10-09 整理，2026-10-10 按 ndclaw 平台团队提供的《NDClaw 服务端对接手册》（v1.0，2026-10-09，AIAE 生产环境）更新。服务周目标一「AI 助手与外部 Agent 协作技术方案」（周目标原文未入库，三项周目标见 10/16 结项待办（原文引用：../superpowers/plans/2026-10-08-创业平台10月16日结项待办.md；未收录于本包）「周目标」一条）。

第一节可以直接转发给 ndclaw 方；第二、三节是我方依据，转发时可删。

依据的优先级：手册优先，手册没写到的以代码为准。代码固定在以下提交（ndhy-app-web 组织）：agent-hub e243c5c（手册依据的也是这个提交）、agent-hub-daemon b6b1fb64（手册依据的是更新的 84d5184，两者不一致时以手册为准）、ai-hub-webui ae508af8。

一、给 ndclaw 方

1.1 背景

AI 创业平台里的 AI 助手「团团」能把用户的创业想法拆成带依赖关系的任务，每个任务都写明交付物和验收标准，但现在还没有执行方。我们要以服务身份（BTS + Userid）通过 A2A 把任务派给 ndclaw 上的专家，拿回结果后交给用户验收。

首个场景是直播电商：合作方有一套提示词形式的「AI 直播团队」，包括 1 个只负责调度的主管和 9 个员工（主播定位、主题策划、选品、排品、脚本、预告物料、播前调试、复盘、售后）。

员工和用户之间是多轮对话，我们用同一个 contextId 续接。

用户范围：只接组织账号，Userid 填 UC 的 user_id。ndclaw 目前不支持个人账号；以后涉及个人账号时改走 AI 员工（目前也不支持）。

时间：10/12～10/16 开发，10/16 交付演示。

1.2 BTS 授权申请：我方要调用的接口

# 手册 3.4 的接口组 方法与路径 用途 什么时候调 10/16
1 A2A 对话 POST /a2a/experts/{agentRef}/rpc，JSON-RPC 方法 SendStreamingMessage 发任务书和用户的每一轮回复，流式接收回答 工作间里每发一轮调一次 必需
2 A2A 对话 同一地址，方法 GetTask 流中断后补查结果，并在每轮结束时确认终态 每轮结束 1 次，中断时补查 必需
3 A2A 对话 同一地址，方法 CancelTask 用户取消正在进行的一轮 用户点取消时（很少） 必需
4 A2A 对话 GET /a2a/experts?include_market=true 导入市场专家清单（mkt- 开头的 ID 和名称） 上线前跑一次，之后按需手动重跑 必需
5 实例：申请、列表 GET /api/v1/instances 派单前检查用户有没有开通成功的实例 每个执行发首轮前 1 次 可选：用户首次调 A2A 时会自动开通实例，见 1.3 第 3 项
6 实例：申请、列表 POST /api/v1/instances 用户还没有实例时提前申请 只在第 5 项查不到实例时调；每个用户一般只调一次 可选：同上
7 A2A 对话 GET /a2a/models?agent_ref= 导入时校验专家要用的模型 ID 导入时 可选：全部用默认模型时不需要
8 专家 GET /api/v1/experts/market?category=&q=&page=&page_size= 按分类、关键词筛选市场专家，拿分类、标签、技能等完整字段 导入时 可选：第 4 项够用

明确不调的接口：

附件走我方自己的 CS。直播专家的创建和发布（POST /api/v1/experts/mine/custom、POST /api/v1/experts/mine/{mineId}/publish）由发布方在 ndclaw 界面上用自己的账号操作，不需要我方服务调用。

10/16 必需的只有第 1～4 项，全部属于「A2A 对话」接口组。

调用量（按 10/16 演示估算）：A2A 共几百次请求；如果用到实例接口，每个用户 1～2 次。都是低频调用。

1.3 已确认事项

「已确认」指手册写明或对方答复，我方还没有联调实测。

# 事项 结论 依据
1 正式环境 控制面 https://agent-hub.aiae.ndhy.com，A2A 在 /a2a 下；不需要 biz-code 头 手册 2.1、3.2.3
2 用户体系 UC 是 uc-gateway.cn.ndhy.com（product 环境），BTS 是 ucbts.cn.ndhy.com，和我方平台是同一套。只接组织账号，Userid = UC user_id 手册 2.1、3.6；林炜 10/10 确认
3 实例 每个用户一个实例，同一种引擎共用一个容器。用户首次调 A2A 时会自动替用户申请。自动开通有两个条件，满足其一即可：在白名单里；或者当天的「公共每日名额」还没用完。平台的字典配置是每天自动开通 4000 个，等于不限，所以新用户首次调用就会自动开通，不需要人工审核。如果主动调申请接口，它不是幂等的，必须先查再申请 手册 1.3、5.2、5.5、8.3 第 5 条；名额配置为林炜 10/10 确认（平台字典配置，手册和代码里读不到）
4 文件 用户发给 Agent：附件链接按 📎 文件名 | 大小（原文引用：链接；未收录于本包） 放在正文前面，Agent 自己下载。Agent 交给用户：产出的文件自动上传到 CS，以 Markdown 链接写在回复里，链接会过期 手册 7.4
5 冷启动与超时 冷启动一般 40～60 秒，A2A 预热上限 300 秒。读超时建议不低于 600 秒；流式帧之间最长隔 32～36 秒，链路网关的空闲超时要大于 40 秒 手册 1.1、8.2、9
6 多轮与模型 第二轮起带上同一个 contextId、不带 taskId；/a2a/models 可以查可用模型；metadata.model 在同一上下文里会一直沿用；A2A 固定用 openclaw 引擎 手册 8.2
7 费用 演示和试用期先由 AI Hub 承担；以后会加 service code 之类的租户字段拆分服务器账单，做法和时间未定 AgentHub 项目负责人 10/09 答复
8 联调环境 手册只覆盖正式环境，先在正式环境联调测试（依据此前沟通结论）。联调用的账号同样会在正式环境产生实例和费用 手册 2.1；此前沟通结论
9 专家可见范围 直播专家在 OpenQ 多智能体平台上已是「开放使用」状态，所以先不做按租户隔离，直接上架市场（先定，后续有需要再收紧）。注意市场专家对所有租户可见（expert_market 表不按租户隔离） 此前沟通结论；agent-hub 代码

1.4 待办与待定

待办

# 待办 说明 10/16
1 开通 A2A 与授权 向 ndclaw 方申请：在 AIAE 生产环境打开 A2A（手册 8.1 标了待确认），并给我方 BTS 应用 8158568859 开通 1.2 节所列接口的权限。这是联调的前提，要最先办 必需
2 创建并上架 9 个直播专家 由我们（创业平台开发者）或范敬萍在 ndclaw 界面上用自己的账号创建并发布到市场，都可以，谁先有空谁做。可见范围见 1.3 第 9 项 必需
3 选品、售后做成技能包 人设最多 16000 字，9 个系统提示词都放得下，但选品、售后连上知识库超长，要做成技能包挂到专家上。可以由我们做，也可以列给范敬萍配合修改 必需

待定（TBD）：下面一项要先弄清机制，才能决定要不要向 ndclaw 方提。原来的「白名单」一项已经不需要：实例每天自动开通 4000 个、无需审核，见 1.3 第 3 项。

预热池是什么

结论：预热池只缩短首次开会话的等待，不影响功能闭环，先联调、验证闭环，再按需申请。

暂不列待办

二、依据（手册与代码）

事项 结论 出处
两种接入模式 用户身份（UC MAC，对方主推）走 WebSocket 直连实例，能力最全；服务身份（BTS + Userid）只能走 A2A，不能唤醒实例、取 wsUrl，也不能操作文件、定时任务和渠道。我方需要服务端转发、存档、解析交付，并且后端拿不到用户的 mac_key，所以选服务身份 手册 0.3、3.4
A2A 协议 标准 A2A 1.0。JSON-RPC 方法名是 PascalCase：SendMessage、SendStreamingMessage、GetTask、CancelTask；地址 POST /a2a/experts/{agentRef}/rpc；另有 REST 绑定 …/rest/message:stream 等。推荐用流式，或异步提交后轮询；不推荐阻塞模式 手册 8.2；agent-hub docs/a2a/integration-guide.md
请求头 每个请求带 Authorization: BTS …（每次重新计算，nonce 随机段 6 位）、Userid、A2A-Version: 1.0。不能发任何 sdp-* 头，它们会参与验签；中间不能经过改写 Host 的代理 手册 3.3、8.3 第 2 条
寻址 mkt- 是市场专家，首次发消息时自动召唤成本人的副本；之后再用 mkt- 调用，会落到同一份副本上 手册 8.2；agent-hub app/domain/a2a_server/ensure.py:103-125
专家 由人设（personaMd，最多 16000 字）、技能（最多 10 个）、样例任务等组成；只支持 openclaw 引擎；可以自建，并发布到市场 手册 6.5
专家目录 GET /a2a/experts 只有 include_market 一个参数，返回 5 个字段，不能过滤；GET /api/v1/experts/market 支持按分类、名称筛选，返回完整字段 agent-hub router.py:28-66；手册 6.5
返回结果 正文在 artifacts[].parts[].text；status.message 成功时只是 done，失败时才是错误原因 手册 8.2
失败文案 agent {ref} not found、实例申请待人工审核…、实例预热超时（预算 300.0s）、gateway ws connect failed、connect rejected、chat.send rejected、sessions.patch rejected（模型非法）、engine error、aborted by engine、stream ended without terminal event。401 的响应体能区分是 Userid 不对还是 BTS 验签失败 手册 8.3 第 9、10 条
A2A 只收发文本 收到的消息只取文本（executor.py:183）；返回结果固定是一段 text/plain（executor.py:70-71）。所以文件都以链接形式写在正文里传递 agent-hub 代码
会话与回收 A2A 的会话键是 agent:<agentId>:a2a-<contextId>；容器连续 30 分钟没有活动就回收，会话和工作区数据不丢；同一会话要串行发送 手册 1.3、8.2、10
「ham」 10/8 分工会原文「ndc call 不是支持 ham」里的 ham 就是 Hermes（ndclaw 的可选引擎）；A2A 固定用 openclaw 手册 1.3、8.2

三、费用分析

模型 token（大头）：daemon 用 BTS 向公司 AI 网关的 /v1/key 申请密钥，申请时带 {"username": <UC 用户号>, "token_group": <ndclaw 的组>}，每个用户一把并定期轮换（agent-hub-daemon lambda/shared/ai_gateway_runtime_prep.py:86-123）。所以用量记在 ndclaw 的 token 组下，并按用户号区分。

量级估算（推断，没有实测）：每个员工的提示词带赛道知识库，加上 OpenClaw 自身的系统提示，每轮输入约 2～4 万 token；完整走一遍直播流程约 50～150 轮，合计 100～600 万 token。用 GLM、DeepSeek 这一档的模型，单个用户大约几元到几十元。

容器算力：每个用户每种引擎一个容器（openclaw 引擎是 1 vCPU、2GB），连续 30 分钟没有活动就回收；预热池里的空闲容器一直在线就一直计费。

我方自己的支出：团团本身的模型调用走我们 10 月的网关预算；附件存在我们的 CS，量很小。

AgentHub 方答复（2026-10-09，林炜转述）：「可以先用。后面会开个 service code 之类的租户字段出来，用来分割服务器账单。」拆分的范围（只拆服务器还是连模型 token 一起拆）、做法和时间都还没定。

多租户与费用归属（我方内部）：ndclaw 要开发多租户能力来区分谁调用、谁付钱，报价 3 人日、要我方下单，对方说这个月内做完；我方调用 ndclaw 引发的费用记在我方（1009 晚会，解读页（原文引用：../../knowledge/wiki/60-会议对谈/2026-10-09-服务器与模型预算及两项目分工.md；未收录于本包） 第一节第 3、4 条）。1010 会白晨说吴梦赢已批、由小杰下单（解读页（原文引用：../../knowledge/wiki/60-会议对谈/2026-10-10-团团陪跑主流程与外部Agent协作模式.md；未收录于本包） 第六节，推断即这一单）。计价口径按白晨在 1009 晚会的转述是 24 小时待命，我方只在有任务时启动，实际会低一些。

尚未核实：AI 网关是否对单个用户号设了用量上限，以及 token 组的单价。

四、对我方方案的影响

  1. 用服务身份走 A2A：放弃唤醒实例、文件等用户身份才有的能力。附件用我方 CS，以链接传递。
  2. 不需要单独处理实例开通：平台每天自动开通 4000 个，新用户首次调 A2A 时就会自动开通，所以 10/16 不做派单前的实例检查。首次调用会多一段开通加冷启动的等待，交互上用「专家准备中」承接；万一仍然收到「实例申请待人工审核」的失败，按普通失败提示用户。
  3. 转存 Agent 产出的文件（我方要做，尚未实现，也没验证）：手册 7.4 说回复里的 CS 链接会过期，所以收到后要转存到我方 CS（只转存 CS 域名的链接）。我方现有的 CsStorage 能上传和签发下载链接，「从专家给的链接下载再上传」还没写；链接的域名、有效期、下载要不要鉴权，联调时验证。
  4. 超时：读超时不低于 600 秒；我方链路网关的空闲超时要大于 40 秒。冷启动一般 40～60 秒，交互上仍然按异步处理。
  5. 只接组织账号：个人账号的用户不能派给 ndclaw 专家；以后接个人账号时走 AI 员工。
  6. 直播专家的知识库要做成技能包：选品、售后连上知识库超出人设的 16000 字上限。

技术方案的对应修改见 团团与外部 Agent 协作技术方案 3.4 节。

五、出处