代码应用编辑页交互改版方案

状态：2026-09-30 已定稿并实施（方案 B），实施记录见第 7 节 · 页面 aimp-platform/packages/ui/src/views/code/pages/CodeAppForm.jsx，发布与工具面板是知识应用、代码应用共用的 packages/ui/src/ui-component/appLifecycle/index.jsx

本文给出代码应用编辑页的三版交互方案，供选定后实施。示意图只画内容区，按 1440px 宽绘制；数据取自本机「aimeter 代码助手」（应用 id 1789523086371597）。

1. 要解决的问题

现状截图与批注（2026-09-30）。

1. 「数据新鲜度」标题口语化。页面副标题「勾一组仓库，发布成一个工具。」同样口语化。
2. 状态用实心色块显示（应用：已启用、当前版本：v2、工具：可用），外观和按钮相同。
3. 操作分在三组：应用（保存草稿、发布当前草稿、发布历史）、工具（团队下拉框、发布为工具、下线工具、查看工具）、危险操作（停用应用、删除应用）。三组之间隔着发布历史和说明文字，找一个操作要扫完整个页面。

2. 三版共用的改动

• 「数据新鲜度」改为「服务构建状态」。说明改为「工具按各服务的最新构建查询。代码更新后无需重新发布；增减服务后需要重新发布。」备选名称：「当前构建」「图谱数据版本」。
• 页面副标题改为「选择一组服务的代码图谱，发布为智能体可调用的代码查询工具。」
• 状态改为圆点加文字，不加底色和边框。绿色 #1f9d55 表示正常；橙色 #d97706 表示已停用或有未保存修改；红色 #c62828 表示异常；灰色空心圆表示未发布。发布历史里的「当前」也改为文字。
• 工具所属团队固定等于应用所属团队（docs/kb-code-team-permissions.md §2.4），改为文字「数据库团队（同应用）」，不再显示禁用的下拉框。未归属团队的存量应用仍保留下拉框。
• 表单按卡片分为四组：基本信息、服务范围、服务构建状态、调用参数。
• 停用应用、删除应用保留现有的二次确认框。

3. 候选方案

方案 A：操作集中在页头右上角

页头右侧放「保存草稿」「发布」「更多」三个按钮。「更多」菜单包含查看工具、下线工具、发布历史、停用应用、删除应用。状态行在标题下方。

代价：工具操作收在菜单里，应用首次发布为工具时入口不直观，需要在未发布为工具时把「发布为工具」临时提到页头。页面滚动后按钮离开视口，页头需要吸顶。

方案 B：右侧固定的「发布与工具」面板（推荐）

左侧是配置表单，右侧面板随页面吸顶，分三段：

1. 发布：应用状态、当前版本、草稿是否与当前版本一致、保存草稿与发布、发布历史。
2. 智能体工具：工具状态、所属团队、工具标识、查看工具与下线工具。
3. 面板底部：停用应用、删除应用。

面板在其他状态下：

1. 应用已停用：面板顶部出现提示条和「启用应用」，底部不再显示「停用应用」。发布新版本同样会恢复启用，因为 kb 发布会把应用状态置为 published。
2. 工具同步失败：写出发布记录 errorCode 对应的原因，给「重试同步」。
3. 尚未发布为工具：工具段只有「发布为工具」一个操作。

方案 C：页签加底部固定操作栏

页面分「配置 / 发布记录 / 智能体工具」三个页签。配置页签底部固定一条操作栏：左侧显示是否有未保存的修改，右侧是保存草稿、发布。停用、删除在页头「更多」菜单里。

代价：工具状态和发布记录要切换页签才能看到；发布后要切到「智能体工具」页签确认同步结果。

4. 推荐与取舍

推荐方案 B。

• 批注里的三个箭头指向同一块区域。方案 B 把状态和全部操作放进同一个面板。
• 面板吸顶，编辑长表单时「发布」始终可见。方案 A 要页头吸顶才能做到；方案 C 的操作栏只在配置页签出现。
• 2026-09-29 起，应用发布新版本后由平台在 kb 代理里同步工具。方案 B 的同步结果显示在发布按钮下方，不用切页签。

方案 B 的代价是左侧表单变窄。示意图按 1440px 内容区绘制，实际页面左侧还有约 220px 的导航栏（在 1280px 宽窗口的截图上量得）：

浏览器窗口宽度	内容区宽度（约）	面板 400px 时左栏宽度（约）
1920px	1700px	1196px
1440px	1220px	716px
1280px	1060px	556px

左栏按「内容区宽度 − 左右内边距 80px − 两栏间距 24px − 面板宽度」估算。1280px 窗口下服务范围穿梭框每侧不足 250px。实施时把面板宽度降到 360px；内容区窄于 1100px 时，面板移到表单上方、取消吸顶。

方案 A 改动量最小，但没有解决「首次发布为工具」的入口问题，所以没有选作推荐。

5. 影响面

• packages/ui/src/ui-component/appLifecycle/index.jsx：面板重写。知识应用编辑页 views/kb/pages/RagAppForm.jsx 共用这个面板，会一起改变。
• packages/ui/src/views/code/pages/CodeAppForm.jsx：页面改为两栏布局（方案 B），或改为页签（方案 C）。
• 前端单测会随按钮名称和文案调整：ui-component/appLifecycle/AppLifecycle.test.jsx、views/kb/components/AppLifecycle.test.jsx。
• e2e 用例按页面文案断言，需要同步修改：aimp-meta/tests/e2e/kb-app-tool-lifecycle.spec.ts（当前版本：v2、工具：可用 等）、kb-cp3.spec.ts（发布历史、停用应用）、code-graph-smoke.spec.ts 与 code-graph-acceptance.spec.ts（/^工具：/）。
• 服务端和 kb 接口不变。

6. 决定记录

以下三项均已确认：

1. 采用哪一版：方案 B（2026-09-30 确认）。
2. 「数据新鲜度」改名为「代码版本」（2026-09-30 确认）。这张表列的是范围内各服务的当前构建（kb 里服务的 current_build_id 指向的那次构建）：commit、构建完成时间、符号数，回答的是「工具现在查的是哪个版本的代码」。「服务构建状态」容易被理解成构建中 / 成功 / 失败，没有采用。示意图中的「服务构建状态」以此为准。
3. 知识应用编辑页同样采用方案 B（2026-09-30 确认）。

7. 实施记录（2026-09-30）

代码在 aimp-platform/packages/ui/src/ui-component/appLifecycle/：AppEditLayout.jsx 是两栏布局，index.jsx 是右侧面板；两个编辑页 CodeAppForm.jsx、RagAppForm.jsx 都改为这套布局。与示意图不同的地方：

• 面板宽 360px，不是示意图的 400px（第 4 节的取舍）。
• 按内容区宽度切换，用容器查询，不按窗口宽度：左侧导航栏可以收起。内容区窄于 1100px 时面板移到配置上方、不吸顶；这时面板本身宽于 720px，「发布」「智能体工具」两段左右并排，面板约占半屏。
• 面板吸顶以布局的滚动容器 .aimp-content 为参照。页面外层 MainCard 是 MUI Card，默认 overflow: hidden 会让吸顶失效，两个编辑页都传了 overflow: visible。面板比可视高度高时自己滚动。
• 智能体工具段不显示「工具标识」。平台发布记录里的 toolName 始终是按应用 ID 拼的契约名，用户在工具页改过标识后与实际不符；要看标识点「查看工具」。
• 有待发布的草稿时，发布按钮写成「发布为 v{下一个序号}」；草稿与当前版本一致时写「发布」。
• 工具按钮随工具状态变：未发布或已下线给「发布为工具」；可用给「查看工具」「下线工具」；异常或同步中给「重试同步」「下线工具」，下线没做完时给「重试下线」。工具可用时不再显示「发布为工具」：新版本由平台自动同步，不需要手动再发一次。
• 停用应用、确认框里的「停用」用深橙色 #b45309：主题的 warning 色是浅琥珀，白底上看不清。
• 停用、启用、删除放在面板底部的「应用操作」段，与「发布」「智能体工具」同样的标题与同尺寸边框按钮（2026-09-30 用户要求，原先的文字按钮不够醒目）。应用停用时「启用应用」也在这一段，顶部提示条只留文字。
• 「查看工具」跳到工具编辑页 /agent/tools/edit/:toolId?teamId=:teamId（2026-09-30 用户要求）。原先跳壳外的独立详情页 /agent/tools/detail/:id，与工具列表页点开的样子不一致；中途试过在应用页打开工具列表页的详情抽屉，抽屉信息有限，改为编辑页：受管工具在那里看完整配置、改名称、标识与分享，顶部来源提示有回应用的链接。编辑页在壳外，不受菜单白名单限制。工具列表页的详情抽屉顶部补上了受管工具的来源提示。
• 状态值上挂了 data-testid：app-status、current-version、draft-status、tool-status、tool-team、version-history。e2e 按它们断言，不按文案。