「API 管理」页改版方案
状态：2026-10-03 用户确认，第 6 节六条全部定（资源上限缺省 50、可配 1–200；资源选择器前端分类加载；「最近使用」放 P2 之后；按范围授权与轮换宽限期本期不做；「团队的 Key」接口排进 P2）。界面部分并入 P2 实施清单 docs/api-key-p2-call-surface.md。起因是用户 2026-10-03 提的四件事：每把 Key 的资源上限可配置；代码采集点的推送 Key 挪到「代码采集」页；老 Key 折叠为 Legacy；资源有几十上百个时，现在的页面与按类型下拉框选资源的方式都不好用。
上游：docs/api-key-convergence.md 2.4（「智能体」资源 Key、团队编辑者可列出与吊销）、docs/resource-key-multi-resource.md（一把 Key 多资源）。
智能体对话框里的快捷关联见 agent-api-dialog/redesign.html 3.1，与本文共用「创建 Key」对话框与资源选择器。
页面代码：aimp-platform/packages/ui/src/views/apikey/，代码采集 views/code/pages/CollectorList.jsx。
截图是本机 2026-10-03 的整页截图（1440×900，含左侧约 220px 导航），账号 A、团队「数据库团队」（1111），Key 与资源都是真实数据，老 Key 原文已遮盖。
示意图画的是内容区（不含左侧导航，宽约 1180px）或单个对话框、抽屉，各图下写明；橙色是示例数据。
1. 现状
- 资源 Key 区是一张表，平铺调用人名下的全部授权（
views/apikey/ResourceKeys.jsx）。账号 A 名下 64 条：对外 Key 有效 25 把、已撤销 9 把，「发布为工具」时系统生成的工具服务授权 30 条（有效 2、已撤销 28）。
已撤销与系统生成的不做区分，最上面就是一串已撤销的「Code graph tool」（图 1）。
- 工具服务授权不是 Key。知识应用、代码应用「发布为工具」时，平台在 agent-base 建受管工具，同时在同一张表
wf_resource_grant 插一条 purpose='tool' 的记录（managed-publications.ts:190-192），记的是「这个工具有权调用这个应用」。智能体经 agent-base 调这个工具时，平台按它放行（authorizeInvoke，:288 起）；调用方身份靠服务签名，所以没有 Key 原文。来源应用删除时它自动撤销（:263）：本机撤销的 28 条里，21 条对应的代码应用在知识库里都是「已删除」。在本页点「撤销」会连带下线工具（integration-access/index.ts:15-16 → managed-publications.ts:125-129）。它出现在本页，只因为列表接口返回调用人名下的全部记录（resource-grants.ts:198-202）。
- 存量用法是一把 Key 一个资源：25 把有效对外 Key 全部只绑一个资源，16 把绑知识源，大部分是 CP3 验收脚本签的。表格按这种用法长成：「资源 / 操作」列逐个列出资源的类型、ID、动作与「API 调试」，一把 Key 绑 20 个资源时这一格就有 20 段。
- 「创建资源 Key」对话框是「用途」单选加每种类型一个下拉多选框（图 2）。下拉框打开时把这一类可签发的资源全部拉回（
resourceOptions.js 的 allPages），只能按名称搜索，不能按团队、状态筛，选中的资源以标签堆在框里。
数据库团队现有智能体 41 个（已发布 13）、知识应用 14 个、知识源 17 个、代码应用 23 个、代码系统 2 个；生产环境每类会到几十上百个，在下拉框里查找、核对都困难。P2 再加「智能体」就是第五个下拉框。
- 代码采集点的推送 Key 与其他 Key 在同一张表，创建时用「用途」单选切换（图 2）。「代码采集」页每行只有一个「签 Key」链接跳回 API 管理（图 3，
CollectorRows.jsx:57），看不到这台机器有没有 Key、是谁签的。
采集点 Key 是采集端的机器身份，一个采集点一把，请求里不带采集点 ID，平台按 Key 认出是哪个采集点（resource-grants.ts authenticateBearer）。它和「外部系统调用资源」不是一类东西。
- 一把 Key 最多 20 个资源：服务端
services/integration-access/resource-grants.ts:83 的 MAX_GRANT_RESOURCES，签发（:98）与调整资源（:342）时检查；前端 views/apikey/resourceTypes.js:51 同值。
2026-09-28 随「一把 Key 多资源」加入（平台 60e57276），设计文档没写理由。它不是存储限制，资源列表存在 TEXT 列里；它限制的是签发、调整时逐个串行核验资源的次数（:221、:357-358，每个资源读一次资源描述、查一次团队权限）。
- 老 Key 表在页面最下方，带「导入」「创建 Key」（图 4）。
- 平台设置的写接口
POST /api/v1/platform-setting/value 服务端不校验管理员，只靠菜单把入口限给管理员（server/src/routes/platform-setting/index.ts 的注释）。把上限放进平台设置之前，这个口子必须补上，否则任何登录用户都能把上限改成 1，让所有人签不出 Key。
图 1 现状：「API 管理」页顶部（整页截图）。表格前几行是已撤销的工具服务授权，没有明文 Key。
图 2 现状：「创建资源 Key」对话框（整页截图）。「用途」单选下是四个按类型的下拉多选框。
图 3 现状：「代码采集」页（整页截图），四个采集点，每行「签 Key」跳到 API 管理。
图 4 现状：页面滚到底部，资源 Key 区末尾与老 Key 表（整页截图）。
2. 改动一览
| 位置 | 改动 | 建议归属 |
|---|
| 资源 Key 列表 | 一把 Key 一行，资源只显示按类型的计数；默认只显示有效的，可切到已过期、已撤销；按名称搜索；分页（3.1） | P2 |
| Key 详情 | 右侧抽屉：Key、元信息、按类型分组的资源清单（逐个移出、添加）、轮换与撤销（3.2） | P2 |
| 资源选择器 | 一个选择器选所有类型：左侧类型、上方关键字与团队筛选、中间可勾选的表格、右侧已选清单与上限计数；创建与「添加资源」共用（3.3） | P2 |
| 创建 Key | 两步：名称与有效期 → 选资源；去掉「用途」单选（3.4） | P2 |
| 工具服务授权 | 不在 API 管理页显示。状态在应用的「发布为工具」处查看，停用就下线工具或删除应用（3.1） | P2 |
| 老 Key | 移到页面底部折叠区「Legacy API Keys」，默认收起；去掉「导入」「创建 Key」（3.1） | P2（方案第 7 节已排） |
| 采集点推送 Key | 从 API 管理移出，在「代码采集」页每行签发、查看、轮换、吊销（第 4 节） | P2 |
| 资源上限 | 改为平台设置项，管理员在 API 管理页「设置」里改；平台设置写接口补管理员校验（3.5） | P2 |
| 「团队的 Key」视图 | 列出别人签发、但授权了我有编辑权限的团队资源的 Key，只能吊销（方案 2.4 已定） | P2，需新接口（已定） |
| 「最近使用」列 | 见第 6 节第 3 条 | P2 之后（已定） |
| 轮换宽限期、按团队整体授权 | 本期不做（第 6 节第 4、5 条） | 不做 |
列表、抽屉、资源选择器建议放进 P2，不单独排期。理由：P2 加「智能体」类型后，按现在的做法就是第五个下拉框；而资源到了几十上百个时，下拉框本身就是用户提出的问题。
3. 资源 Key
3.1 页面结构
- 顶部：标题、说明、「设置」（只有管理员看得到）、「创建 Key」。
- 筛选条：「我的 Key」「团队的 Key」两段切换；状态（有效 / 已过期 / 已撤销）；按名称搜索。「我的 Key」默认只显示有效的。
- 列：名称、Key（掩码，可复制的显示复制按钮）、授权资源（按类型计数）、到期、创建时间、操作（「详情」，更多菜单里放轮换、撤销）。点行打开详情抽屉。
- 代码采集点的 Key 不在这张表里，表下一行文字指到「代码采集」页。
- 页面底部一个折叠区「Legacy API Keys」，默认收起，展开是老 Key 表（已停止新建）。
- 工具服务授权不在本页出现：列表接口
GET /api/v1/apikey/resources 只返回 purpose='external' 的记录。
平台管理 / API 管理
API Keys开放接口
API Keys设置+ 创建 Key
外部系统用 API Key 调用你授权的智能体、知识应用、知识源、代码应用和代码系统。Key 是个人凭证，只有签发人能查看明文；每把 Key 最多授权 50 个资源。
我的 Key团队的 Key有效 21已过期 3已撤销 9按名称搜索
| 名称 | Key | 授权资源 | 到期 | 创建时间 | |
|---|
| 工单系统集成 | ai••••••••k3Xq 复制 | 智能体 2知识应用 1代码应用 1 | 长期有效 | 2026-10-03 | 详情 ⋯ |
| aimeter 代码助手调用（验收） | ai••••••••d1Rws 复制 | 代码应用 1 | 长期有效 | 2026-09-26 | 详情 ⋯ |
| aimeter 交易码写入（验收） | ai••••••••NFNGw 复制 | 代码系统 1 | 长期有效 | 2026-09-26 | 详情 ⋯ |
| code-open-smoke | ai••••••••EXMi8 复制 | 代码应用 1 | 长期有效 | 2026-09-16 | 详情 ⋯ |
| delivery-push-cp3-final-delivery-1789299049 | aimp_res_…4uyM 需轮换后才能复制 | 知识源 1 | 长期有效 | 2026-09-13 | 详情 ⋯ |
| CP3-invoke-primary | aimp_res_…_Y4I 需轮换后才能复制 | 知识应用 1 | 长期有效 | 2026-09-13 | 详情 ⋯ |
代码采集点的推送 Key 在「代码管理 → 代码采集」里管理。
▸ Legacy API Keys1 把 · 已停止新建，新的外部调用请创建上方的 API Key
图 5 方案：「API 管理」页内容区（不含左侧导航）。除第一行外都是账号 A 的真实 Key，计数是本机实数；第一行是一把多资源 Key 的示例。上限 50 是已定的缺省值（3.5）。
3.2 Key 详情抽屉
- 头部：名称、状态；Key 掩码与「查看」「复制」（判据同
ResourceKeyCell.jsx:11-16）；签发人、创建时间、到期、版本号（每次调整资源加 1，现有 revision 列）。
- 「授权资源 4 / 50」：按类型分组，每个资源一行，显示名称、团队、是否可用；知识类资源保留「API 调试」入口；每行「移出」。只剩一个资源时不能移出，提示撤销整把 Key。
- 「添加资源」打开 3.3 的资源选择器，已授权的资源在选择器里显示为已选中且不可取消。
- 底部：「轮换」（新 Key 生效、旧 Key 立即失效，现行规则）、「撤销」。
- 「团队的 Key」里打开的抽屉只读，只有「撤销」，看不到明文。
工单系统集成有效
Keyai••••••••k3Xq 查看 复制
签发人你
创建2026-10-03 21:40
到期长期有效
版本3
授权资源 4 / 50+ 添加资源
智能体
rag_test数据库团队 · 已发布 v1移出
code_agent数据库团队 · 已发布 v1移出
知识应用
CP3核心知识应用 cp3-app-20260913-02数据库团队API 调试移出
代码应用
aimeter 代码助手数据库团队API 调试移出
轮换撤销
图 6 方案：Key 详情抽屉（只画抽屉）。四个资源与所属团队是本机真实数据，Key 名、时间、版本号是示例。
3.3 资源选择器
资源多时，问题在三处：找得到（筛选）、看得清（状态与团队）、核得对（已选清单）。选择器按这三处设计，「创建 Key」第二步与详情抽屉的「添加资源」共用，智能体对话框不用它（那里只关联本智能体）。
- 左侧类型：全部、智能体、知识应用、知识源、代码应用、代码系统，显示每类可选数量。
- 上方筛选：关键字（名称、ID）；团队（缺省当前团队，可切到调用人所在的其他团队）；「只看已选」。
- 中间表格：勾选框、名称、类型、团队、状态、更新时间，分页每页 50 条。表头勾选框选中本页。不可选的资源（未发布、已停用、没有管理权限）不列出，与现有
resourceOptions.js 的判据一致。
- 右侧已选清单：按类型分组，逐个移除；顶部「已选 N / 上限」，到上限后其余勾选框置灰。
- 数据：每类沿用现有的列表接口，切到这一类时才加载，不在打开时拉全部类型。关键字先在已加载的数据里过滤；一类超过几百个时再改服务端搜索（第 6 节第 2 条）。
添加资源 · 工单系统集成
全部69
智能体13
知识应用14
知识源17
代码应用23
代码系统2
搜索名称或 ID团队：数据库团队 ▾只看已选
| 名称 | 类型 | 团队 | 状态 |
|---|
| rag_test | 工作流 | 数据库团队 | 已发布 v1 |
| code_agent | 单智能体 | 数据库团队 | 已发布 v1 |
| cp3-agent-validation-single-agent-1789297393793 | 单智能体 | 数据库团队 | 已发布 |
| cp3-agent-validation-agentnode-v2-1789297410433-definition | 单智能体 | 数据库团队 | 已发布 |
| cp3-agent-validation-single-agent-1789297159904 | 单智能体 | 数据库团队 | 已发布 |
| … 共 13 个，第 1 页 |
已选 4 / 50
智能体
rag_test×
code_agent×
知识应用
CP3核心知识应用 cp3-app-…已授权
代码应用
aimeter 代码助手已授权
取消添加 2 个资源
图 7 方案：资源选择器，从详情抽屉的「添加资源」打开（只画对话框）。智能体名称、类型与数量 13 是本机已发布的真实数据；知识应用、知识源、代码应用的数字是数据库团队的资源总数，没有按「已发布」过滤，所以标橙。
3.4 创建 Key
- 第一步：名称；有效期改为预设项（长期有效、30 天、90 天、1 年、自定义），缺省仍是长期有效，与现在留空的行为一致。
- 第二步：资源选择器（3.3），至少选 1 个。
- 创建后弹现有的明文对话框，只显示一次。
「用途」单选去掉：代码采集点的 Key 改在「代码采集」页签发（第 4 节）。从智能体对话框「签发新 Key」进来时跳过第二步，资源固定为该智能体。
创建 API Key
① 名称与有效期② 选择资源
签发后明文只显示一次。Key 是个人凭证，只有你能查看明文；授权资源所属团队有编辑权限的成员可以吊销它。
取消下一步：选择资源
图 8 方案：「创建 API Key」第一步（只画对话框）。第二步就是图 7 的资源选择器，标题换成「创建 API Key · ② 选择资源」。
3.5 资源上限改为平台设置
- 存到
wf_platform_setting（通用键值表，server/src/database/entities/WfPlatformSetting.ts），键名 RESOURCE_KEY_MAX_RESOURCES。签发与调整资源时服务端读它，代替常量 MAX_GRANT_RESOURCES；没有这个键时用缺省值。
- 入口：API 管理页右上角「设置」，只有平台管理员看得到；数据与「平台设置」页同源，那里也列出这一项。
- 管理员判定沿用
utils/viewerRole.ts（环境变量名单 GATEWAY_PLATFORM_ADMINS）。POST /api/v1/platform-setting/value 在服务端加这道校验，非管理员回 403；现有的技能审核模式设置一并受保护。
- 调低上限不影响已有 Key，照常可用；资源数超过新上限的 Key 只能移出资源，不能再添加。
- 缺省值 50，可配范围 1–200（2026-10-03 用户定）。
API Key 设置
范围 1–200。调低后已有的 Key 照常可用，超出上限的只能移出资源、不能再添加。签发与调整资源时逐个核验资源，上限越高，一次签发越慢。
只有平台管理员可以修改。上次修改：<管理员账号> · 2026-10-03
取消保存
图 9 方案：管理员点「设置」后的对话框（只画对话框）。50 与范围 1–200 是已定值，修改记录是示例。
4. 代码采集点的推送 Key
采集点 Key 只服务采集端：一个采集点一把，Key 本身就是采集点的身份。它跟着采集点的生命周期走（登记、签发、配进采集端、停用），放在「代码采集」页，一行就能看清这台机器的状态。数据不动：同一张 wf_resource_grant、同一组接口，只换入口。
- 「代码采集」表加一列「推送 Key」，三种状态：
- 未签发：「签发」。弹出的对话框只有名称（缺省采集点名）与有效期；签发后显示明文，并附采集端配置要填的两项（
collector.name 与 Key）。
- 我签发的：掩码、「查看」「轮换」「吊销」。
- 别人签发的：显示签发人，只有「吊销」（方案 2.4：资源所属团队有编辑权限的成员可吊销）。
- 已停用的采集点不能签发，沿用
CollectorRows.jsx:22-23 的判据。
- 要改的三处跳转：
CollectorList.jsx:162（登记成功后的「去 API 管理签 Key」）、CollectorRows.jsx:57（每行「签 Key」）、ServiceEmptyState.jsx:44（服务列表空状态的「去签发」），都改为在「代码采集」页内签发。
- API 管理的列表与「团队的 Key」都不再显示采集点 Key；「创建 Key」去掉「用途」单选。
代码管理 / 代码采集
| 名称 | 主机提示 | 状态 | 上次心跳 | 解析器版本 | 名下服务 | 推送 Key | 操作 |
|---|
| test | — | 正常 | 从未上报 | 未知 | 尚未上报服务 | 签发 | 停用 |
| aimeter-collector | localhost | 心跳超时 | 5 天前 | 0.7.0 | 2 | ai••••4XfSE · 其他成员签发 吊销 | 停用 |
| code-collector-a1a3-smoke | localhost | 心跳超时 | 17 天前 | 0.1.0 | 尚未上报服务 | ai••••cpfKY 查看 轮换 吊销 | 停用 |
| code-collector-local-01 | 127.0.0.1 | 心跳超时 | 17 天前 | 0.1.0 | 尚未上报服务 | 签发 | 停用 |
图 10 方案：「代码采集」页内容区（不含左侧导航），虚线框是新增的「推送 Key」列。四个采集点、两把 Key 的归属与掩码都是本机真实数据（aimeter-collector 的 Key 由另一个账号签发）。
5. 候选方案与取舍
5.1 资源多时怎么选资源
| 方案 | 做法 | 代价 | 结论 |
|---|
| A | 维持按类型的下拉多选框，加第五个「智能体」 | 五个框各自加载全量；不能按团队、状态筛；已选项以标签堆在框里，几十个时核对困难 | 否决 |
| B | 统一资源选择器（3.3） | 新组件；跨类型的数量与筛选要在前端拼，类型多了以后可能要服务端聚合接口 | 推荐 |
| C | 按范围授权：Key 授权「团队 T 的全部智能体」，以后新建的自动包含 | 授权范围随资源增减自动变化，Key 泄露的影响面无法事先确定；resources 要支持通配项，运行时校验改为按团队判；与「API Key 只能调授权给它的资源」的访问原则要重新对齐 | 本期不做，见第 6 节第 4 条 |
| D | 只从资源侧授权：在智能体、知识应用页面上「授权给某把 Key」 | 一把 Key 授权了哪些资源只能逐个页面去看，没有总览 | 作为 B 的补充：智能体对话框已有（agent-api-dialog 3.1），不替代 B |
5.2 参考的产品做法
以下只写结构上的做法；没有联网核对的具体数值标【待确认】。
| 产品 | 做法 | 本方案借鉴的 | 本方案不做的 |
|---|
| GitHub fine-grained personal access token | 资源范围有「全部仓库」与「只选部分仓库」两种，选部分时用可搜索的多选；权限按类别逐项选；列表显示到期与最近使用；到期缺省值与可选档位【待确认】 | 资源与权限分开；列表只放摘要 | 「全部仓库」这类范围授权（5.1 方案 C） |
| OpenAI Platform API keys | 列表列为名称、掩码 Key、创建时间、最近使用、创建人、权限；明文只在创建时显示一次 | 列表列的取舍；「最近使用」（第 6 节第 3 条） | — |
| Stripe restricted keys | 按资源逐项给权限；轮换时可以让旧 Key 再保留一段时间，档位【待确认】 | — | 轮换宽限期（第 6 节第 5 条） |
| Cloudflare API tokens | 列表行显示权限与资源摘要；创建时最后一步是汇总确认；可从模板创建 | 列表摘要；创建前汇总（第二步的已选清单承担这个作用） | 模板 |
5.3 被否决的其他做法
| 做法 | 否决原因 |
|---|
| 限制每人只能有一把 Key | 不同外部系统要能分别吊销；一把 Key 泄露时影响面应只限于一个系统 |
| 工具服务授权留在 API 管理页（主列表或底部折叠区） | 它不是用户签发、分发的 Key，没有明文，生命周期跟着「发布为工具」走；在这里撤销等于下线工具，入口放错了地方。本机 30 条里 28 条已撤销，留着只是噪音 |
| 采集点 Key 留在 API 管理，只在「代码采集」页显示状态 | 签发要先到采集点页、再跳 API 管理、再回来配采集端，三处来回；采集点 Key 不会与其他资源混在一把 Key 里，没有放在 API 管理的理由 |
5.4 关键取舍
- 列表只显示资源计数，具体资源进抽屉。 代价：看某把 Key 授权了什么要多点一次。换来的是一把 Key 有几十个资源时列表行高不变。
- 上限可调高。 代价：签发与调整资源时串行核验，上限越高越慢；调高的同时把核验改为有限并发（每次 8 个【待实测】），并发数受 KB 服务承压能力限制。
- 工具服务授权从 API 管理页拿掉。 代价：不能再从这里撤销；要停用某个工具，到应用的「发布为工具」处下线工具，或删除应用。
6. 已定问题（2026-10-03 用户确认）
| # | 问题 | 影响 | 结论 | |
|---|
| 1 | 资源上限的缺省值与可配范围 | 缺省值决定不改设置时的行为；范围上限决定一次签发最多核验多少个资源 | 已定（2026-10-03）：缺省值 50，可配范围 1–200。每个资源的核验耗时尚未实测，P2 实施时在本机测一次（签一把多资源 Key、调整一次），据此定签发接口的超时与核验并发数 | — |
| 2 | 资源选择器的数据是前端分类加载，还是新增服务端聚合与搜索接口 | 单类几百个以内前端加载够用；更多时首屏慢、关键字搜索不准 | 已定（2026-10-03）：前端按类型写死，每类沿用现有列表接口在前端加载，不新增服务端聚合与搜索接口。 | — |
| 3 | 加「最近使用」列 | 能看出哪些 Key 早就没人用、可以清理（本机 16 把知识源 Key 大多是测试留下的）。代价：wf_resource_grant 加列；认证时写库，要节流（同一把 Key 5 分钟内只写一次） | 已定（2026-10-03）：做，放在 P2 之后单独一步。 | — |
| 4 | 按范围授权（5.1 方案 C） | 资源上百时最省事，但授权范围不可预知 | 已定（2026-10-03）：本期不做；出现「一个外部系统要调整个团队全部资源」的需求时再议 | — |
| 5 | 轮换宽限期 | 现在轮换后旧 Key 立即失效，外部系统切换期间会断 | 已定（2026-10-03）：本期不做，有需求时再议 | — |
| 6 | 「团队的 Key」需要的新接口是否排进 P2 | 方案 2.4 已定「团队编辑者可列出并吊销」，现有列表接口只返回签发人自己的 Key | 已定（2026-10-03）：排进 P2，与本页面一起交付 | — |
7. 影响面
| 对象 | 变化 |
|---|
views/apikey/index.jsx、ResourceKeys.jsx、ApiKeys.jsx | 页面结构、列表、筛选、Legacy 折叠区；删掉工具服务授权的展示分支（ResourceKeys.jsx:232）；Legacy 表去掉新建与导入 |
views/apikey/ResourceSelection.jsx、resourceOptions.js、resourceTypes.js | 由按类型下拉框改为资源选择器；新增智能体类型；上限改从设置读 |
| 新增组件 | Key 详情抽屉、资源选择器、两步创建对话框（智能体对话框复用后两者） |
views/code/pages/CollectorList.jsx、components/CollectorRows.jsx、components/ServiceEmptyState.jsx | 「推送 Key」列与就地签发；三处跳转改为页内操作 |
services/integration-access/resource-grants.ts | 上限从平台设置读；核验改为有限并发；list 只返回 purpose='external'（另一个调用方「开放接口」页的 views/kb/components/ApiKeyPicker.jsx 本来就只用对外 Key）；新增「团队的 Key」查询 |
services/platform-setting/、controllers/platform-setting/ | 白名单加 RESOURCE_KEY_MAX_RESOURCES；写入校验平台管理员 |
views/PlatformSettings | 列出新设置项 |
8. 下一步
界面部分与 agent-api-dialog 一起并入 P2 实施清单，按第 7 节拆提交；单个资源核验耗时在实施时实测（第 6 节第 1 条）。
