review: Canary 迁移至远程插件的集成与兼容性问题 #126

背景

#113 提出 Console 插件 SDK、独立交付前端资源以及由启动配置统一管理内置模块和远程插件导航；实现见 #114。北极星实验（Canary）是需要评估的实际迁移场景：目前其前端由独立仓库维护，但通过构建脚本将源码、扩展注册、帮助文档和图片注入 Console 临时源码树，生成专用 Console 镜像。

后续 review 时，请在决定 Canary 是否迁移到远程插件模式之前，集中评估下列四类集成需求。这里记录的是待确认的兼容性和设计问题，不预设 #114 存在缺陷，也不预设必须采用某一种方案。

相关设计与现有实现

• 原提议：design: Console plugin SDK and configured navigation folders #113；实现 PR：feat(shell): load SDK plugins and YAML navigation folders #114。
• Console 插件 SDK 设计（#114 版本）。
• 可配置导航与目录设计（#114 版本）。
• 插件开发和部署指南（#114 版本）。以上文档链接固定在 design: Console plugin SDK and configured navigation folders #113 所记录的 cc29e7a，review 时还应对照 PR 最新版本。
• Canary 私有前端设计、现有构建与注入脚本、Console 适配器及 Canary 前端说明。

1. 宿主既有页面中的服务归属组件

现状与问题

Canary 当前不只注册独立页面，还通过 serviceOwners 注册 CanaryServiceOwner。Console 的模型服务列表和详情页识别 LLMCanary 类型的服务关系后，可以展示被管理／被分配关系，由 Canary 组件匹配实验并提供跳转到实验详情的链接。匹配依赖经过验证的归属信息及 UID 等字段；不可确认时不会生成不可靠的链接。没有对应扩展时，宿主可回退到通用归属展示。

#113 重点描述远程页面、路由和导航，但没有明确说明远程插件如何向宿主已有页面提供此类组件。若只迁移独立页面，模型服务页面的 Canary 专用展示可能无法延续。

Review 要点

• 确认 feat(shell): load SDK plugins and YAML navigation folders #114 最新实现是否已经支持等价的宿主扩展点；列出注册接口、数据契约和组件加载时机。
• 若不支持，讨论由宿主提供明确的服务归属扩展点、由宿主实现通用链接，或其他方案；明确责任边界。
• 明确插件缺失、加载失败、用户无权限、归属信息不可信或实验已不存在时的回退行为。
• 用模型服务列表和详情页验证管理／分配关系、正确实验链接及 fallback。

2. 帮助文档和插图的集成

现状与问题

当前构建脚本把 Canary 的中英文文档和图片复制到 Console 帮助中心，并将 canary 加入章节列表；用户可从帮助中心访问 /help/docs/canary。若不再生成专用 Console 镜像，现有构建时注入不再自动执行。#113 未明确远程插件如何扩展内置帮助中心。

Review 要点

• 决定支持插件向帮助中心贡献章节和静态资源，还是由插件提供独立帮助页，或采用其他方案；说明对统一目录的影响。
• 明确中英文内容、图片路径、导航、加载失败、版本更新和插件移除时的行为。
• 决定是否保留 /help/docs/canary 及已有链接的兼容性；如变更，给出跳转或迁移策略。
• 验证 Console 和 Canary 分别升级时，用户能访问与部署版本对应的文档。

3. 页面权限、导航和操作能力

现状与问题

Canary 有实验列表、详情、新建、价格等页面。现有适配器为新建页面声明 canary.write 和写入要求，并将 canWrite 提供给页面；价格编辑、实验创建、流量调整等操作在页面内也使用该能力控制。业务 API 仍依赖 Console 与后端的认证和授权。

#113 要求保留现有页面权限，配置化导航设计提出先过滤权限再组织目录；SDK 设计同时说明可选认证元数据本身不创建新菜单／页面策略。需要结合 #114 的实际实现确认这些机制是否覆盖 Canary 的页面和操作级行为。

Review 要点

• 逐项映射实验列表、新建、价格和详情页面的路由、菜单、读写权限，以及详情等非菜单路由。
• 明确只读用户、可写用户和无访问权限用户分别看到的菜单、可直接访问的路由、按钮和错误状态；包含直接输入 URL 的情况。
• 确认插件通过何种受支持的宿主接口获取 canWrite 等能力，以及能力加载中、配置缺失和变化时的处理。
• 验证菜单隐藏与前端控件状态之外，/api/canary 等业务 API 仍由服务端独立执行授权。
• 确定迁移前后权限与导航的对照测试，避免将 SDK 类型中的权限字段直接视为已经实现的宿主策略。

4. SDK／宿主兼容版本与多插件样式

现状与问题

#114 的指南说明 SDK 源码位于 Console 仓库，当前尚未发布到包仓库，消费方从固定的 Console 源码版本构建 SDK；插件运行时则使用宿主提供的 React、路由、Query、UI、主题和认证传输。独立构建不消除插件与宿主之间的版本兼容要求。

同一指南说明当前样式集成支持一个可选前端，任意多插件运行时 CSS 合并不在范围内。这是目前明确的范围边界，并不意味着现有单插件场景已发生样式故障。

Review 要点

• 明确 SDK 的版本号、发布／获取方式、兼容性策略，以及插件镜像应记录的 SDK 和 Console 版本。
• 定义 Console 与插件独立升级、回滚、版本不兼容的检测和用户可见错误；列出需要覆盖的兼容组合。
• 确认 Canary 单插件场景的 CSS 构建、主题、资源发布与加载方式。
• 评估多个插件同时启用时的 CSS 交付、类名或全局样式冲突、顺序和主题一致性；确定是否纳入当前范围，以及暂不支持时如何表达限制。

期望 review 产出

• 针对四项分别给出结论：已有能力及证据、需要补充的设计／实现，或明确不在本期范围。
• 确认 Console 与 Canary 仓库的职责、迁移步骤、测试计划和兼容性约束；需要后续工作的部分拆分关联 issue。
• 在结论中引用更新后的设计文档或实现，并明确哪些能力为 Canary 迁移的前置条件。