工具编辑页交互改版方案
本文覆盖两件事：工具编辑页增加「认证」区块、与凭证管理绑定；知识库 / 代码应用发布的工具（下称受管工具）的编辑页向通用工具看齐。
示意图画的是整页：工具编辑页在壳外，没有左侧导航栏（layout/AimpLayout/index.jsx:8），按 1440px 宽绘制。受管工具的数据取自本机「aimeter 代码助手」（应用 id 1789523086371597），调用地址、参数与描述按 ManagedToolFamily.CODE 的定义照抄。
通用工具与凭证的数据是示例：写方案时本机环境未启动，取不到真实记录。橙色虚线框标出的是本次改动的位置。
1. 要解决的问题
- 通用工具没有像样的认证配置。认证只有一个「SSO 认证」开关，夹在请求参数和 Hook 中间；下游的密钥只能写在请求头里，或放进全局变量再引用。全局变量是明文，还会被注入容器环境变量、替换进技能文件，智能体能直接读到。
- 受管工具的编辑页是另一套页面。没有步骤条，没有图标、Hook、校验规则；返回按钮、标题、区块样式都和通用工具不同。用户从同一张工具列表点进来，看到两种页面。
对「受管工具只有接口部分不能改，认证、Hook 等其余都一样」这个判断，读代码核对的结果是：
| 项 | 现状 | 能否与通用工具一致 |
|---|---|---|
| 校验规则 | 运行时已生效：网关先按规则校验参数再分发（McpGatewayService.java:325），保存接口也已接收 checkRules，只是页面没有入口 | 能，只改前端 |
| Hook | 不生效：应用每次发布同步工具时把 Hook 清空、SSO 置为关（ManagedToolService.java:148）；执行器 ManagedToolExecutor 不跑 Hook | 能，要改 agent-base；前置 Hook 只能改参数（地址、方法、请求头由发布流程维护） |
| 认证 | 下游就是平台自己（/api/v1/kb-tool-runtime/code/<应用 ID>/invoke），agent-base 用服务签名调用，能不能调由工具授权决定 | 不应一致：不需要、也不该让用户配；认证方式固定为「平台内调用」，控件与通用工具相同、置灰 |
| 图标 | 编辑页没有入口；发布同步不改图标；受管工具的保存接口只收标识、名称、授权与校验规则（ManagedToolService.java:195-200） | 能，前端加入口、保存接口放开图标 |
| 描述 | 按工具名称自动生成（「名称」+ 固定说明），模型靠这个前缀分辨挂在同一智能体上的多个知识库工具 | 能：允许改写，规则同工具名称（2026-10-02 确认） |
| 权限配置 | 已与通用工具共用 ShareStep | 已一致 |
2. 两类工具共用的改动
2.1 基本信息步分成四个区块
现在的基本信息步是一长串表单项。按「基本信息 / 接口定义 / 认证 / Hook」分成四个区块后，受管工具与通用工具的差别就能落到具体区块上：接口定义只读、认证固定，其余相同。工具描述从页面最底下移到「基本信息」区块。
2.2 认证区块
- 认证方式四种（2026-10-01 确认），取代原「SSO 认证」开关：
- 无须认证：调下游时不带认证信息。
- SSO Token：透传调用用户的令牌，可改写入的请求头名。智能体以服务身份运行（API Key、定时任务）时没有用户令牌，这类工具不能挂到这种智能体上，在智能体发布时拦下。原来开着「SSO 认证」开关的工具迁移到这一项，请求头名沿用
x-chatv-sso-access-token。 - 关联固定凭证：从本团队的工具凭证里选一个。下拉旁的「新建凭证」打开凭证新建抽屉（第 5 节），建好自动选中。选中后显示写入摘要（写到哪、类型、末 4 位），不显示值。
- 平台内调用：下游是平台自己的接口，用服务签名调用。只由平台发布流程设定（知识库 / 代码工具）；通用工具里显示为置灰选项，提示「仅平台发布的工具使用」。不开放的原因：服务签名代表 agent-base 本身，自建工具能选它，就能以 agent-base 的身份调平台任意内部接口。
- 脚本工具：「关联固定凭证」置灰，提示「脚本工具不支持绑定凭证，需要凭证请改用接口工具」（脚本代码能读到注入的值）。
- 请求头里出现像密钥的项（名字是
Authorization或含 key / token / secret / password，值是字面量或全局变量），行下提示「敏感值请用凭证」，不阻断保存。
| Key | Value |
|---|---|
| Content-Type | application/json |
| X-Tenant | {{$vars.tenantCode}} |
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| level | string | 否 | 告警级别 |
| from | string | 是 | 开始时间 |
| systemCode | string | 否 | 业务系统编码 |
X-API-Key · 最后更新 2026-09-28 · 只列出本团队的工具凭证图 1 通用工具 · 基本信息步（改版后）。认证区块（橙框）是新增的；其余区块的内容与现在相同，只是加了区块标题，描述上移。
图 2 认证区块的另外两种取值。「SSO Token」写入的请求头名，新建工具时缺省 x-chatv-sso-access-token（第 6 节）。
3. 受管工具页：候选方案
方案 A：与通用工具同一套页面和步骤，按需只读（2026-10-01 选定）
同一个页头、同一个三步步骤条、同一套区块和底部按钮。差别只有四处：页头下方的来源提示条；「接口定义」只读；「认证」固定为「平台内调用」；不走审核（现状）。
代价：BasicStep 要支持受管模式（接口定义只读、认证固定）；受管工具的保存请求多带图标、Hook、校验规则；agent-base 要改两处才能让 Hook 生效（发布同步不清空 Hook、执行器跑 Hook）。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| operation | string | 是 | 要做的查询：推荐先用 diagnose……（全文 10 行，默认显示前 3 行） |
| query | string | 否 | search 的关键字：类名、方法名、全限定名，或以 / 开头的 HTTP 路径…… |
| logicalId | string | 否 | call_tree、reverse_calls、detail 的起点符号 |
| 展开其余 7 个参数 | |||
图 3 方案 A：受管工具 · 基本信息步。橙框是与通用工具不同的三处；第 2 步「安全校验」、第 3 步「权限配置」与通用工具完全相同，最后一步的按钮是「保存」「取消」（不走审核）。
方案 B：保留单页，区块与样式向通用工具看齐
不加步骤条，一页从上到下：来源提示 / 基本信息 / 接口定义（只读）/ 认证（固定）/ Hook / 校验规则 / 权限配置，底部「保存」「取消」。
代价：改动比 A 小（不用拆进三步）；但两类工具仍是两种页面结构，用户在通用工具里找「安全校验」要切步骤，在受管工具里要往下翻，没有做到「尽量一致」。
方案 C：两类工具都改成单页分区（通用工具也去掉步骤条）
编辑已有工具时，分步向导要来回点「上一步 / 下一步」才能改到第三步的内容，单页加区块导航更顺手。两类工具都用单页，一致性最好。
代价：通用工具的新建流程、审核提交、助手（按步骤给提示）都要跟着改，超出这次「受管工具向通用工具看齐」的范围；可以作为以后单独的改版。
取舍
| 方案 A（推荐） | 方案 B | 方案 C | |
|---|---|---|---|
| 两类工具页面结构 | 相同 | 不同 | 相同 |
| 前端改动 | 中：BasicStep 加受管模式，删掉 ManagedToolEditor 单独的页面分支 | 小：重写 ManagedToolEditor 的布局 | 大：通用工具也要重排，新建与审核流程跟着改 |
| agent-base 改动（开放 Hook 时） | 三种方案相同：发布同步不清空 Hook；ManagedToolExecutor 执行前置 Hook（只取参数）与后置 Hook | ||
4. 方案 A 的差异清单
除下表列出的项，受管工具页与通用工具页完全相同。
| 区块 | 通用工具 | 受管工具 | 原因 |
|---|---|---|---|
| 页头 | 返回、标题、「编辑模式」标签、「助手」 | 返回、标题、「代码应用发布」/「知识应用发布」标签；无「助手」 | 助手用来生成接口定义，受管工具的接口定义不能改 |
| 来源提示条 | 无 | 来源应用名、应用启用状态、「查看应用」 | 沿用现有 ManagedKnowledgeTool 横幅 |
| 工具标识 | 可改 | 可改；kb_code_ / kb_rag_ 前缀只允许改回自己的名字 | 现有规则不变 |
| 工具名称 | 可改 | 可改，默认跟随应用名 | 现有规则不变 |
| 工具描述 | 可改 | 可改；默认按名称自动生成，改写后发布不覆盖，可「恢复为自动生成」 | 模型靠描述前缀分辨多个知识库工具，改写的人要自己写清这个库管什么 |
| 接口定义 | 可改 | 只读，参数表默认显示前 3 行 | 随应用版本同步 |
| 认证 | 无须认证 / SSO Token / 关联固定凭证（「平台内调用」置灰） | 固定为「平台内调用」，其余三项置灰 | 下游是平台自己；「平台内调用」只由发布流程设定 |
| Hook | 可改 | 可改；前置 Hook 只能改参数 | 地址、方法、请求头由发布流程维护 |
| 安全校验、权限配置 | 相同 | ||
| 最后一步按钮 | 「确定」或「提交审核」、「取消」 | 「保存」「取消」 | 受管工具不走审核（2026-10-02 确认保持现状） |
5. 对接凭据页：新建工具凭证
- 列表按用途分两组：「工具凭证」与「模型与节点凭证」（后者是现有的 flowise 凭证，不变）。工具凭证一行显示名称、类型、末 4 位、被几个工具引用、最后使用时间、到期日。
- 新建工具凭证先选类型，一期四种：API Key、Bearer 令牌、Basic 认证、OAuth2 客户端凭证（各类型的字段见
tool-credentials.md第 4 节）。「自定义令牌接口」一期不做（2026-10-01 决定）。 - 密字段保存后不回显，只能「替换」；被工具引用的凭证不能删，删除时列出引用它的工具。
- OAuth2 客户端凭证有「测试」按钮：真实换一次令牌，只显示成败与有效期。
图 4 新建工具凭证抽屉（类型：OAuth2 客户端凭证，示例数据）。从工具编辑页点「新建凭证」打开同一个抽屉，保存后回到工具页并自动选中。
6. 决定
| # | 问题 | 结论 |
|---|---|---|
| 1 | 受管工具页用哪个方案 | 方案 A（2026-10-01 确认） |
| 2 | 受管工具是否开放 Hook | 开放（2026-10-01 确认）；前置 Hook 只能改参数 |
| 3 | 工具的认证方式 | 四种：无须认证 / SSO Token / 关联固定凭证 / 平台内调用（2026-10-01 确认）；「平台内调用」只由发布流程设定 |
| 4 | 凭证一期类型 | API Key、Bearer 令牌、Basic 认证、OAuth2 客户端凭证；不做自定义令牌接口（2026-10-01 确认） |
| 5 | 受管工具的描述是否允许改写 | 允许（2026-10-02 确认）。与工具名称同一规则：默认自动生成，改写后应用发布不覆盖，可「恢复为自动生成」 |
| 6 | 受管工具是否走审核 | 不走，保持现状（2026-10-02 确认） |
| 7 | 「SSO Token」写入的请求头名，新建工具时缺省用什么 | 缺省 x-chatv-sso-access-token（与现状一致）；对接统一认证时改为 userToken（2026-10-02 确认） |
7. 影响面
| 位置 | 改动 |
|---|---|
ToolUpsert/BasicStep.jsx | 分四个区块；新增认证区块（替换 SsoAuthConfig，四种认证方式）；受管模式下接口定义只读、认证固定为「平台内调用」 |
ToolUpsert/index.jsx | 删掉受管工具单独的页面分支（:1478-1492），走同一套步骤；受管工具的保存请求带图标、Hook、校验规则 |
ToolUpsert/ManagedToolEditor.jsx | 拆掉；标识、名称的规则与提示并进 BasicStep |
ToolUpsert/GlobalVarHint.jsx | $sys.ssoAccessToken 的说明改为「建议改用认证方式：SSO Token」 |
views/credentials | 按用途分组、工具凭证类型表单、测试按钮、引用列表 |
| aimp-agent-base | 受管工具：发布同步保留 Hook 与图标；执行器跑 Hook；保存接口接收图标与 Hook。认证与凭证注入见 tool-credentials.md 第 10 节 |
| 单元测试 | ManagedKnowledgeTool.test.jsx 保留（横幅不变）；受管编辑器的用例随页面合并改写 |
| e2e | 现有用例只到工具列表与详情页，没有覆盖受管工具的编辑页；kb-app-tool-lifecycle.spec.ts 断言的横幅文案「此工具由代码应用「…」发布」、「已停用」、「查看应用」链接都保留。新增两条：受管工具改名称、图标、Hook 后保存并调用；绑定凭证的接口工具调用下游 |
8. 实施记录（2026-10-02，第一批：页面统一 + 认证方式）
代码：agent-base 认证方式与受管工具（ToolAuthMode、ToolAuthModeSupport、ManagedToolService、ManagedToolExecutor），平台前端 ToolUpsert/AuthConfig.jsx、BasicStep.jsx、index.jsx。提交与验证见 docs/tool-auth-handoff.md 开头的状态表。图 1 里的凭证下拉、「新建凭证」与第 5 节的对接凭据页属于第二批，没做。与示意图不同的地方：
- 「SSO Token」的说明改为「透传调用用户的 SSO 令牌，写进这个请求头。智能体以服务身份运行（API Key、定时任务）时没有用户令牌，下游收不到它。」图 2 里「运行开始时已换成够用的有效期」「不能设为服务身份运行」两句说的是还没实现的能力（令牌交换、发布校验），先不写。
- 认证区块标题旁写「调用下游接口时带什么认证信息」。图 1 的「凭证在发请求前由平台写入，Hook 与模型都看不到」是第二批的行为：第一批 SSO 令牌仍在前置 Hook 之前合并，Hook 读得到。
- 置灰选项的原因除了悬浮提示，还在选项下面写一行（如「「关联固定凭证」凭证管理接入后开放；「平台内调用」仅平台发布的工具使用」）：禁用的单选不好触发悬浮提示。
- 受管工具页没有右侧的工具助手面板（不只是去掉页头的「助手」按钮）。
- 权限配置步（方案没涉及，顺手修）：工具没有分享记录时，编辑页原来回显成「所有人 + 10:00–18:00」，保存一次就把工具放给所有团队、还只在白天可用。发布流程建的受管工具就没有分享记录，并入三步后人人都会走到这一步。改成与新建一样的「本团队 + 00:00–23:59」，与没有分享记录时的实际权限一致；有分享记录但没有时间段时同样回显全天。
页面上的 data-testid：tool-auth-config（认证区块）、tool-sso-header（写入请求头）、managed-interface-definition（受管工具的只读接口定义）。e2e tests/e2e/tool-edit-managed.spec.ts 按它们与可见文案断言。