智能体「嵌入网站或用作 API」对话框：改版方案

状态：2026-10-03 用户确认。分享页签按方案 2.10 保留「组织内成员」「第三方嵌入」两档（3.4）；第 8 节三条按推荐定。界面部分待并入 P2 实施清单。 上游：docs/api-key-convergence.md 2.4（「智能体」资源 Key）、2.10（智能体入口分享），属于 P2。 页面代码：对话框 aimp-platform/packages/ui/src/views/chatflows/APICodeDialog.jsx（分享页签 ShareChatbot.jsx、嵌入代码 EmbedChat.jsx）， 入口在单智能体编辑页 views/agentapps/index.jsx:357 与工作流画布 views/canvas/CanvasHeader.jsx:642；「API 管理」页 views/apikey/。

本文定 P2 的界面：智能体的「嵌入网站或用作 API」对话框改用「智能体」资源 Key，「API 管理」页新增这种资源类型，老 Key 停止新建。用户确认方案之前不改代码。

截图是本机 2026-10-03 的整页截图（1440×900）。画布与单智能体编辑页是壳外页面，没有左侧导航；「API 管理」页含左侧约 220px 导航。 团队「数据库团队」（1111），智能体 rag_test（工作流）与 code_agent（单智能体）是真实数据，两个都已发布 v1、都绑着 DefaultKey。截图里的老 Key 原文已遮盖。 示意图只画对话框或对话框里的一块，各图下写明；示意图里的资源 Key 名称与 Key 值是示例数据。

1. 现状

• 两个入口打开同一个对话框：单智能体编辑页顶栏的 </>，工作流画布顶栏的「API Endpoint」。对话框有七个页签：嵌入代码、Python 代码、JavaScript 代码、cURL 代码、异步 API、A2A 协议、分享聊天机器人。
• 页签行右侧的下拉框列出当前团队的老 Key，外加「- Add New Key -」（跳到 API 管理）。选中即调 updateChatflow 写智能体的 apikeyid（APICodeDialog.jsx:165-176），不经过保存按钮。 下拉框没有「无需授权」选项，绑定解除不了；没有「流程·编辑」权限时置灰。
• 新建智能体时服务端自动绑定本团队的 DefaultKey（server/src/services/chatflows/index.ts:435-449）。本机 41 个智能体全部绑着它，图 5 老 Key 表「用量」一栏的 41 就是这个数。
• 工作流画布上：代码页签把老 Key 原文填进 x-chatv-apikey（图 1）。嵌入代码页签提示「请从顶部右侧的下拉菜单中选择无需授权」（APICodeDialog.jsx:1337-1343），下拉框里却没有这一项，绑了 Key 的工作流拿不到嵌入代码（图 2）。 分享页签的链接带老 Key 原文，旁边是「设为公开」开关（图 3）。
• 单智能体编辑页上，2026-10-03 实测三处异常：
  1. 下拉框为空，代码示例不带 Key（图 4）。编辑页取智能体信息的 getAgentApp（server/src/services/agent-apps/index.ts:189-202）不返回 apikeyid，对话框以为没绑 Key。 照这些示例调 /prediction 会被拒，因为智能体实际绑着 DefaultKey。
  2. 嵌入代码页签生成不带 Key 的嵌入代码。portal 没有 Key 时走 /internal-prediction（chat-portal/src/chat/api.ts:32），要求 AIMP 登录态，第三方网站的访客发不出消息。这一条按代码推断，未实测。
  3. 点「分享聊天机器人」后整页白屏，页面报错 Cannot read properties of null (reading 'id')。分享页签从画布的全局状态 state.canvas.chatflow 取智能体（ShareChatbot.jsx:63-64），编辑页上这个值为空。
  【待确认】同一浏览器会话里先打开过工作流画布、再进单智能体编辑页时，分享页签可能读到上一个智能体，生成错的链接。这是代码推断，未复现。 确认办法：同一会话内先进 rag_test 画布，再从左侧导航进 code_agent 编辑页打开分享页签，由实施本方案的人在动手前复现。
• 「API 管理」页上半部分是资源 Key，现有五种类型（views/apikey/resourceTypes.js：知识应用、知识源、代码应用、代码采集点、代码系统），图 5 里看得到其中两种；下半部分是老 Key 表，带「导入」「创建 Key」。

2. 改动一览

3. 对话框

3.1 下拉框：挑 Key，也能就地关联

智能体与 Key 的关联存在 Key 上（资源 Key 的资源列表），不存在智能体上。对话框里的快捷操作与「API 管理」页改的是同一份数据、调的是同一组接口，任一处改动在另一处立即可见。 智能体上原来的 apikeyid 不显示、不修改，留到 P4 删除。

• 数据源是现有的 GET /api/v1/apikey/resources，只返回调用人自己签发的 Key。前端分两组：
  1. 「已授权 rag_test」：资源列表含本智能体的 Key。
  2. 「我的其他 Key」：不含本智能体、对外用途、未吊销、未过期的 Key。代码采集点的 Key 不列，它只能单独绑采集点；已有 20 个资源的 Key 灰掉，提示已满。
• 选中「已授权」组里的 Key：调一次 POST /api/v1/apikey/resources/:id/reveal 取明文，填进各页签的代码，不写任何数据。 同一次打开对话框，同一把 Key 只取一次明文，存在内存里供各页签共用，关掉对话框即丢弃。不能查看明文的 Key（存量无密文）灰掉，判据同 ResourceKeyCell.jsx:11-16。
• 加入：把本智能体加进「我的其他 Key」里的某一把。调现有的 PUT /api/v1/apikey/resources/:id/resources，资源列表等于原列表加本智能体。 Key 本身不变，持有它的外部系统不用改配置。加入前弹确认，列出这把 Key 现有的资源；成功后自动选中这把 Key。
• 移出：同一个接口，资源列表去掉本智能体，弹确认。一把 Key 至少要有 1 个资源，所以只授权了本智能体的 Key 不能移出，提示到「API 管理」吊销。
• 签发新 Key：在对话框上叠一层现有的「创建资源 Key」对话框，预选本智能体，名称缺省「rag_test 调用」。签发后弹现有的明文对话框（只显示一次），关闭后自动选中新 Key。 两个对话框从 views/apikey/ResourceKeys.jsx 抽成组件复用，不另写一套。
• 权限：服务端对三种写操作照常核验。签发人才能调整资源；新列表里每个资源都要有管理权限，新加的资源要可用（resource-grants.ts:357-358）。 调用人在智能体所属团队没有「流程·编辑」时，只显示「已授权」组，三个写操作的入口隐藏。签发人对 Key 里某个旧资源已失去管理权限时，加入会被拒，错误原样提示。
• 同团队其他人签发的 Key 不出现在这里，看不到明文，填不进代码。团队里有编辑权限的人在「API 管理」页列出并吊销这些 Key（方案 2.4）。
• 智能体未发布时下拉框置灰。签发和加入都要求资源可用，未发布的智能体两样都做不了。

3.2 代码页签：Key 放在 Authorization

头字段按方案 2.4 第 12 条已定的纪律：资源 Key 与 SSO 令牌都放 Authorization: Bearer，x-chatv-apikey 只留给老 Key，示例里不再出现。 现有示例末尾「把用户令牌经 Origin-Auth 或 Authorization 透传给工具」的注释只保留 Origin-Auth 一行：Authorization 已经用来放调用凭据。 Python、JavaScript、异步 API、A2A 四个页签按同样的规则改，示意图只画 cURL。

3.3 嵌入代码页签：带智能体 Key，写明后果

• 嵌入代码的 data-apikey 取下拉框选中的 Key（EmbedChat.jsx:47 已有这个属性）。portal 拿它调 /prediction，跑已发布版本。
• 提示写明后果：Key 在网页源码里，访客都能拿到；能调用智能体就能用它挂载的全部工具与技能（方案 2.10）。
• 选中的 Key 还授权了智能体以外的资源时，多一条提示，列出资源数。允许这种 Key 用于嵌入，只做提示（第 8 节第 1 条，已定）。
• 没选 Key 时不出代码，只显示「嵌入到第三方网站需要智能体 Key」，以及「签发新 Key」「加入已有 Key」两个入口（同 3.1）。

3.4 分享聊天机器人页签：组织内成员、第三方嵌入两档

按方案 2.10 的原写法，页签顶部切换两档，缺省「组织内成员」。下面的链接参数（开场问题、自动发送）与外观配置两档共用，不变。

• 组织内成员：链接不带 Key。打开的人用自己的账号登录，必须是智能体所属团队的成员，跑已发布版本。 portal 现在不带 Key 时跑草稿（/internal-prediction），要新增一个「跑已发布版本」的链接参数。参数名在 P2 实施清单里与 portal 改动一起定（第 8 节第 3 条），图里的 run=published 是示例。
• 第三方嵌入：链接带右上角下拉框选中的智能体 Key（3.1），形如 /chatV2/portal?chatflowId=…&embed=chatbot&apikey=…&teamId=…，与 embed.js 建 iframe 用的地址同一格式（chat-portal/public/embed.js:52-57）。 portal 带 Key 调 /prediction，跑已发布版本。这个链接可以直接在浏览器打开，也可以作为 iframe 地址；要弹泡、全屏或 React 写法时用「嵌入代码」页签。
• 第三方嵌入档的提示与 3.3 相同：Key 在链接里，拿到链接的人都能用它调用智能体与它挂载的工具；选中的 Key 还授权了其他资源时多一条提示。没选 Key 时不出链接，提示先选择或签发。
• 智能体未发布时两档都不生成链接，提示先发布。
• 删除「设为公开」开关（wf_chat_flow.isPublic）与 /api/v1/public-chatflows（方案 2.10）。
• 智能体 ID、团队、发布状态由对话框参数传入，不再读画布全局状态，第 1 节的白屏随之消失。

4. 「API 管理」页

「API 管理」页的改动（新增「智能体」类型、老 Key 折叠为 Legacy、资源选择器、采集点 Key 挪到「代码采集」页、资源上限可配置）见 api-keys-page/redesign.html。 本对话框 3.1 的「签发新 Key」复用那里的「创建 API Key」对话框，跳过选资源一步，资源固定为当前智能体。

5. 被否决的方案

6. 关键取舍

• 关联写在 Key 上，不写在智能体上。 代价：P3 之前智能体调工具仍以绑定的老 Key 的创建人放行，界面上改不了这个身份。以前手动改绑过其他老 Key 的智能体保持原绑定，部署前可在各环境查 wf_chat_flow.apikeyid 不是 DefaultKey 的行数。
• 「加入」扩大已有 Key 的授权范围。 一把已经交给外部系统、甚至写进网页的 Key，在对话框里点一下就多了一个能调的智能体。确认框列出这把 Key 现有的资源，并写明后果，不做额外拦截；只有签发人能操作，与在「API 管理」页「调整资源」相同。
• 组织内链接跑已发布版本。 原来不带 Key 的链接跑草稿，作者在画布上的未发布改动会立刻影响收到链接的人；改后要发布才影响。代价：未发布的智能体不能分享，本机 41 个里 28 个未发布。
• 嵌入接受 Key 进网页（方案 2.10 已定）。界面上用提示写明后果，不做额外拦截。

7. 影响面

8. 已定问题（2026-10-03 用户按推荐确认）

9. 下一步

界面部分并入 P2 实施清单，按第 7 节拆提交；「跑已发布版本」的参数名在清单里定。