Skip to content

enhancement-center-design.md

Latest commit

 

History

History
1409 lines (1178 loc) · 89.4 KB

enhancement-center-design.md

File metadata and controls

1409 lines (1178 loc) · 89.4 KB
Raw

增强中心与商店设计方案

状态：开发需求清单（一次性实现基线，已完成全面审查修订） 更新：2026-08-14 说明：本文同时是后续 Codex 一次性实现的输入，不再按 P0-P5 分期交付。 基线：SunamAI 已完成 P0-P6 全量 Cordis 插件化（原 PLAN 文件已删除）； 本文是在该已完成基线上的增量设计，已有能力直接复用，不重复实现。

本文记录 Sunam 的「增强 / 商店」产品结构：增强承载已安装能力的管理，商店承载 跨生态的发现与安装；两者共同构成应用中心模型。本文同时是后续 Codex 一次性实现 的需求基线，不按阶段交付，但所有需求都建立在已完成的全量插件化架构之上。

1. 背景与目标

Sunam 当前同时依赖两套生态：以 pi 为核心的 Agent 引擎，以及以 Cordis/DSH 为代表的插件与 Agent 宿主体系。产品不能只停留在「内置功能 + 能力开关」层面， 否则与 Succinix 之外的竞品相比，缺少可生长的生态优势。

目标：

  1. 建立统一的「增强」主入口，把当前分散的能力面板、插件管理收拢为一个入口。
  2. 插件中心在现有 ctx.plugins 基础上扩展为安装与生命周期底座，负责生态插件 装卸、运行区路由；「商店」作为应用中心的发现与安装入口。
  3. 工具库复用现有 ctx.capability / ctx.tools，负责用户可见的 AI 工具管理， 并把每个工具暴露的系统能力透明化。
  4. 不设独立权限配置页；权限声明只作展示，最终权限在 Agent 执行层裁决。
  5. 本轮交付 Skill、MCP，并为 AI 自主调度工具预留标准化扩展位。
  6. 新增「商店」主入口，下设 DSH 插件 / Pi 拓展 / Skill 市场 / MCP 市场四个子 市场，统一目录、搜索、验证、安装与更新流程。

1.1 现有基线（已完成，直接复用）

以下能力来自已完成的原迁移基线（原 PLAN 文件已删除），本文不重做，只在其上扩展：

  • 25 个内置 @sunam/plugin-* 已全部落地，统一走 src/plugins/<id>/；
  • 全插件共享唯一 Cordis Context，ctx.ui、ctx.systemPrompt、ctx.capability、 ctx.tools、ctx.agent、ctx.llm、ctx.plugins 均已存在；
  • 插件管理已有启停、重载、配置、依赖图、日志、secret 脱敏、失败隔离和活跃 run 延迟重载；
  • PluginRegistration.load 已支持懒加载插件，是运行时 ESM 装载的现成入口；
  • @succinix/engine@0.6.0 已作为外部 Cordis 插件接入，提供 succinix-host 与四个 dsh 服务键。

本文提到的“插件中心”“工具库”“热更新”都指在以上能力上做增量，不新建平行的 插件系统、工具注册表或 Cordis 运行时。

需要特别区分“现有基线”和“本轮新增契约”，避免实现时误认为已有能力：

  • ctx.ui 目前只有通用 slot / id / order / priority / label / Component 注册模型，SlotEntry.Component 是必填；primary-nav / workspace-view / segment-nav:<scope> / display 都是本轮新增槽位契约，不是已存在插槽；
  • 当前 TerminalTabs 写死 ai / capability，ContainerCapsule 写死 ai / user / services / files，MobileNavigation 写死 chat / ai / capability；本轮要新增主入口渲染壳并从注册表派生，这些写死 列表不能当作“只需小改”的现状；
  • RegisteredTool 目前没有 origin / runtimeZone / systemAccess， ToolExecutionContext 没有 toolPolicy / runtimeZone，AgentRun.toolPolicy 只有 role / allowedTools / writeScope，这些都是扩展项；
  • AgentDriverId 目前是 pi | claude-code | codex，create.ts 实际只返回 PiDriver；新增 dsh 需要同步类型、配置解析与工厂分支；
  • PluginRegistryController 目前只有 register / start / stop / restart / enable / disable / updateConfig / statuses / graph / effectiveConfig / subscribe / notify，没有 install / uninstall / update / rollback；热更新不能只靠“复用”现有控制器 完成，需要先补接口。

2. 产品结构

主入口为「对话 / 电脑 / 增强 / 商店」，统一通过 primary-nav / workspace-view 注册；对话 / 电脑由现有界面迁入新契约，增强 / 商店由本轮 新增插件注册。

对话
电脑
增强
├─ 插件（插件中心：在现有 ctx.plugins 上扩展为安装与生命周期底座）
│  ├─ 来源管理：pi package / Cordis / DSH / npm / git / CDN / 本地包
│  ├─ 安装、卸载、更新、搜索、启停、配置、依赖、版本
│  ├─ 兼容性检测：导入时静态分析 / 安装时服务解析 / 运行时探测
│  └─ 运行区路由：Sunam 主区 / DSH 区 / pi 扩展区（zone 元数据）
├─ 工具（原“能力库”升维：复用 ctx.capability / ctx.tools）
│  ├─ 模块分组、工具级开关、依赖关系
│  ├─ 工具详情：来源、风险、数据影响、超时、读写执行标签
│  ├─ 系统能力指纹 systemAccess
│  └─ 全局已注册工具清单
├─ 技能（Skill：新增 @sunam/plugin-skills）
└─ MCP（MCP 接口：新增 @sunam/plugin-mcp）
商店
├─ DSH插件（GitHub `dsh-plugin` topic / dsh-plugins-store 目录）
├─ Pi拓展（pi package / ExtensionAPI 目录）
├─ Skill市场（skill / skill-pack / Sunam skill manifest）
└─ MCP市场（MCP server / registry 目录）

增强是“已装能力管理”入口：插件中心、工具库、Skill、MCP 的本地启停、配置、 依赖、工具开关都在这里。商店是“发现与安装”入口：目录浏览、搜索、详情、外部 验证状态、安装与更新触发都在这里。两者不做双轨，商店的安装请求统一交给插件 中心安装器与兼容性检测，安装完成后进入增强管理。

当前 UI 中「能力库」是电脑视图内的能力面板，插件管理在设置页 settings.plugins；按本方案收拢为「增强」下的「工具 / 插件」子视图。 「权限」不做独立页面，权限能力并入 Agent 层执行机制。

当前全局底部 status-bar（Telemetry / Notes）与聊天气泡底部的 context_injected 属于演示性 / 重复性信息，统一在第 8 章收敛到“电脑”展示层， 纳入同一交付批次，不留双轨。

2.1 主入口插槽（Primary Nav / Workspace View）

Sunam 真正面向插件开放的 UI 扩展点，不是 status-bar 这类临时通用位，而是 “对话 / 电脑 / 增强 / 商店”所在的主入口插槽，以及“电脑”内部的胶囊选择器。 目标模型对齐 VS Code 的贡献点：

  • primary-nav：插件注册一个主入口（图标、文案、order），出现在左侧主导航 / 移动端底部选择器；
  • workspace-view：插件注册该主入口对应的整页界面，Workspace 只负责按当前 主入口渲染对应视图；
  • settings-tab：沿用现有模型，负责设置页签；
  • terminal / file-manager / capability / display：负责“电脑”内部的 子视图与展示面，不再承担主入口职责。

现状没有 primary-nav：桌面端实际由 Workspace 的双栏布局承载，移动端由 MobileNavigation 写死三个 tab。因此本轮先补一个主入口渲染壳（可在 src/pages/ConfiguredPage.tsx 或新增 PrimaryNavShell 实现），再让“对话 / 电脑 / 增强 / 商店”以及第三方主入口都从 primary-nav + workspace-view 派生； MobileNavigation 同步改为渲染 primary-nav，不再维护独立 tab 清单。

例如 @sunam/plugin-ui-enhance 注册“增强”、@sunam/plugin-store 注册“商店”：

ctx.ui.register('primary-nav', {
  id: 'enhance',
  order: 30,
  labelKey: 'nav.enhance',
  iconKey: 'sparkles',
});

ctx.ui.register('workspace-view', {
  id: 'enhance',
  order: 0,
  Component: EnhanceHome,
});

ctx.ui.register('primary-nav', {
  id: 'store',
  order: 40,
  labelKey: 'nav.store',
  iconKey: 'store',
});

ctx.ui.register('workspace-view', {
  id: 'store',
  order: 0,
  Component: StoreHome,
});

未来第三方 Sunam 插件用同一契约注册新主界面；插件卸载时入口与视图一起移除。 现有 TerminalTabs 中写死的 ai / capability 两个 tab、ContainerCapsule 中写死的四个 segment，以及 MobileNavigation 中写死的三个 tab，改为从插槽 注册表派生，插件才能新增、移除和排序主入口。

契约字段要求：primary-nav 条目只提供 id / order / labelKey / iconKey，不 必填 Component；workspace-view 条目必填 Component。因此 SlotEntry 需要 扩展为 Component 可选，并新增 labelKey? / iconKey?；SunamExtensionUiSlot 与 SunamPluginManifest.uiSlots 同步支持这两个字段，否则 manifest 无法自动 生成主入口。UiSlotView 渲染前跳过无 Component 的条目；primary-nav 由 主入口渲染壳直接消费 labelKey / iconKey / order，不经过 UiSlotView。

边界：

  • 当前激活主入口只存在运行时内存，默认“对话”，不做全局持久化；刷新后回到默认 入口，当前视图对应插件被卸载或禁用时自动回退到“对话”。
  • 桌面端本轮保留现有“对话 + 电脑”双栏工作区形态；primary-nav 先接管主导航 / 移动底部栏与主视图切换，不强行改成整页模式。若后续产品决定整页切换，作为独立 UI 决策在实现前确认，不阻塞插槽契约。
  • primary-nav / workspace-view 按 id 配对；同 id 冲突复用 ctx.ui 的原子 替换语义，排序由 order 决定。
  • 内置 order 建议：对话 10、电脑 20、增强 30、商店 40；第三方默认 >= 50，避免与内置主入口抢占位置。

2.2 通用胶囊选择器（Segment Selector）

“灵动岛”是 Sunam 的通用二级选择器，不是电脑专用组件。任何主视图内部需要切换 栏目时，都在相同位置复用同一个胶囊组件：样式、自适应、动效、键盘与移动端交互 只维护一份。

  • segment-nav:<scope>：通用子页面插槽，按 scope 隔离模块，例如 segment-nav:computer 与 segment-nav:enhance；
  • 主视图注册自己的子页面，例如“增强”注册“插件 / 工具 / 技能 / MCP”：
ctx.ui.register('segment-nav:enhance', {
  id: 'plugins',
  order: 10,
  labelKey: 'enhance.plugins',
  iconKey: 'puzzle',
  Component: PluginsView,
});
  • SegmentSelector 统一渲染：读当前 scope 的 entries，输出胶囊；可见项少于 2 个时隐藏；宽度不足时收缩为 icon-only；桌面键盘、移动端滑动与 thumb 动效复用 同一实现；
  • “电脑”内的 电脑 / 终端 / 服务 / 文件、“增强”内的 插件 / 工具 / 技能 / MCP 与“商店”内的 DSH插件 / Pi拓展 / Skill市场 / MCP市场 都走这一模型，交互完全 一致；
  • 现有 ContainerCapsule 是原型实现，本轮抽成共享 SegmentSelector，放入 src/shared/ui，再经 ctx.ui 的 scope 注册表驱动，避免跨插件 static import。

segment-nav:<scope> 不设注册限制：第三方可以注册任意 scope，也可以改造其他 插件已注册的 scope 条目。官方默认条目先加载，同 scope 同 id 复用 ctx.ui 原子 替换语义，排序由 order 决定；插件应使用带自身前缀的稳定 id 避免误覆盖。

3. 插件中心职责

插件中心是生态兼容的入口，负责管理所有可装载运行时的插件来源：

  • 底座：现有 ctx.plugins + PluginRegistryController；不重建插件系统， 本轮在其上扩展安装、卸载、更新、搜索、来源与运行区能力。
  • 来源：pi package、Cordis/DSH 插件、npm、git、CDN、本地包。
  • 生命周期：安装、卸载、更新、搜索、启停、配置、依赖解析、版本管理。
  • 运行区路由：根据插件类型路由到不同运行区。

浏览器静态页面不能直接安装原始 npm 包；npm / git 来源应要求提供预构建 ESM bundle + manifest + hash/integrity；CDN 需同源或允许 CORS，本地包 / 上传文件 可转成 blob: URL 后作为 bundle 来源。

运行区：

Sunam 主区     内置 Cordis 插件与 Sunam 原生扩展（同一 Cordis Context）
DSH 区         同一 Cordis Context 下的 DSH 插件装配组 + DshDriver；
               zone 是元数据/生命周期分组，不开第二 Cordis runtime
pi 扩展区      pi package / ExtensionAPI 宿主（本轮完整实现 PiCompatHost，
               注册到 ctx.* 扩展面）

插件详情展示插件的信任等级、能力声明与兼容度，但不提供权限配置页。用户 看到的是“这个插件声明了哪些能力、来自哪里、运行在哪个区域、能不能直接跑”， 而不是手动勾选权限。

3.1 契约差异面（现有代码 → 新增面）

以下表格是 Codex 一次性实现时的“差异面”，避免把新增项误当成已有能力：

面 现有代码位置/形态 本轮新增
UI 插槽 SlotEntry（src/contracts/cordis.ts）只有 id/order/priority/label/Component SlotEntry 增加 labelKey? / iconKey?，Component 改为可选；识别 primary-nav / workspace-view / segment-nav:<scope> / display 槽位
Manifest SunamPluginManifest.uiSlots 只有 slot/id/order/label uiSlots 增加 labelKey? / iconKey?；manifest.generated.ts 同步；主入口条目可无 Component
主入口渲染 Workspace / MobileNavigation / TerminalTabs 写死 tab 新增 PrimaryNavShell（或等价壳），从 primary-nav + workspace-view 派生；MobileNavigation 改读同一注册表
二级选择器 ContainerCapsule 写死 SEGMENTS 抽成共享 SegmentSelector，按 segment-nav:<scope> 注册
插件生命周期 CordisPluginRegistryController 无安装/卸载/更新/回滚接口 新增 install / uninstall / update / rollback / listInstallRecords；PluginRegistration 增加 installRecord? / packageUrl? / integrity? / runtimeZone? / runGated? / previousVersions?
热更新 RUN_GATED_PLUGIN_IDS 是硬编码 Set；fiber.update(config, true) 只换配置 新增动态 runGated 插件标记；代码包热切换走 stop/start 替换 registration.plugin，配置热更新继续走 fiber.update；回滚保留旧 bundle/plugin 引用
工具契约 RegisteredTool 无来源/运行区/指纹；ToolExecutionContext 无策略/运行区 扩展 origin / runtimeZone / systemAccess；执行上下文增加 toolPolicy / runtimeZone
Agent 驱动 `AgentDriverId = 'pi' 'claude-code'
新增服务 现有 ctx 无 compat / display / skills / mcp / scheduler / store 新增对应插件与服务并扩展 cordis-augmentation.d.ts
版本 src/host/cordis.ts 手写 SUCCINIX_VERSION 删除手写值，构建期生成 src/shared/versions.generated.ts
样式 check-design-tokens.mjs 只扫插件 CSS 原始色值 新增 check-css-migration.mjs；升级 token 门禁并纳入 check:architecture

插件兼容性检测

第三方插件导入必须执行三层兼容性检测，并把结论作为插件详情的一部分持久化： 用户安装前即可看到“直接运行 / 需要 shim / 需要改造 / 不兼容”，不把问题留到 运行时才发现。

第一层：导入时静态检测

  • 识别入口形态：标准 Cordis apply(ctx)、DSH host 插件、ClientContext 插件、 pi package；
  • 扫描 import / exports / manifest：dsh.client 声明、exports["./client"]、 package 前缀，判断是否双 half；
  • 扫描客户端专属依赖：@deepseek-ai/dsh-client-*、 @deepseek-ai/dsh-client-runtime/client、@deepseek-ai/dsh-client-ui-* 等；
  • 扫描 Node 专属能力：node: 内置模块、child_process、process.env、 原生 addon / worker_thread，判断是否必须进入 Succinix 执行世界；
  • 输出插件形态与 surface 结论。

第二层：安装时服务解析

  • 将插件 inject 与 Sunam 服务表做差集，区分“可直接映射 / 缺失 / 需 shim”；
  • 缺失服务为硬依赖时：安装前阻止或标记不兼容；
  • 缺失服务为软依赖时：允许降级运行并在详情中提示；
  • 对 DSH API 形状做静态比对，需要时自动挂接 @sunam/compat-dsh-tools （库级 shim，不作为独立 Cordis 插件安装）。
插件依赖 Sunam 映射 结论
tools / systemPrompt ctx.tools / ctx.systemPrompt 直接兼容
fs / sandbox / terminals / sessionPersistence @succinix/engine 服务键 直接兼容
agent / llm ctx.agent / ctx.llm 直接兼容
session ctx.workspace + ctx.persistence 适配；当前没有 ctx.session 同名单服务
slots ctx.ui 直接兼容；旧 status-bar 等槽位按第 8 章映射到 display
locale ctx.i18n 直接兼容
theme 无等价服务 需 shim 或降级；本轮不新建主题服务
sessions / workspaces / remote / client-connection 无等价服务 不兼容或仅 host half

第三层：运行时探测

  • 安装后执行一次试运行：注册、注入、依赖图、启用、卸载全链路；
  • 校验插件是否真实注册工具 / 提示词 / UI 插槽，捕获启动崩溃；
  • 合并静态结论与运行时结论，回写插件详情；
  • 插件更新版本时重新检测，API 形状变化后兼容度可能变化。

检测结果分四档：

compatible            直接安装启用
compatible-with-shim  自动挂接 @sunam/compat-dsh-tools 等适配层
needs-conversion      通常是 ClientContext / UI 插件，host half 可用，browser half 需迁到 ctx.ui
incompatible          缺核心服务 / 依赖 DSH 专属运行时或原生能力，安装前阻止或隔离

检测结果至少展示：来源、入口形态、运行区、兼容度、缺失服务、能力声明、 建议处理方式。ClientContext 形态插件不得静默安装为“可用”；服务型 DSH 插件 不得因缺少浏览器 half 而被误判为完全不可用。

兼容性检测实现细节

检测结果数据模型（ctx.compat 返回并持久化到插件详情）：

type PluginCompatLevel =
  | 'compatible'
  | 'compatible-with-shim'
  | 'needs-conversion'
  | 'incompatible';

interface PluginCompatibilityReport {
  pluginId: string;
  version: string;
  checkedAt: number;
  level: PluginCompatLevel;
  entryKind: 'cordis' | 'dsh-host' | 'dsh-client' | 'pi';
  surface: 'host' | 'client' | 'dual' | 'unknown';
  services: Array<{
    key: string;
    status: 'available' | 'mapped' | 'missing' | 'shim';
    target?: string;
    required: boolean;
  }>;
  imports: Array<{
    specifier: string;
    kind: 'client-runtime' | 'host-api' | 'node' | 'native' | 'unknown';
    status: 'ok' | 'shim' | 'needs-conversion' | 'incompatible';
  }>;
  runtimeProbe?: {
    started: boolean;
    registered: { tools: number; prompts: number; uiSlots: number };
    error?: string;
  };
  suggestedAction: string;
}

静态检测规则细化

  • 入口形态：default export 是 Plugin.Object / 具名 apply → Cordis；包名或 manifest 声明 dsh → DSH；声明 dsh.client 或存在 exports["./client"] → 双 half；ClientContext 类型引用 → client 插件；
  • import 分类：@deepseek-ai/dsh-client-*、dsh-client-runtime/client、 dsh-client-ui-*、dsh-client-connection → client-runtime； @deepseek-ai/dsh-tools、dsh-system-prompt 等 → host-api，命中 shim 表； node: 前缀、child_process、fs、process → node，需 Succinix 执行世界； 原生 addon / worker_thread / .node 文件 → native，默认 incompatible；
  • 未知 import 不直接判失败，进入运行时探测，避免误杀纯工具插件。

服务解析规则细化

  • inject 中的每个 key 必须落到四档之一：可用、映射、shim、缺失；
  • 缺失且 required: true：阻止安装；缺失且可选：允许降级并展示“降级运行”；
  • DSH host 服务映射表命中后，记录 target 指向 Sunam 实际服务或 shim 包；
  • 插件同时声明 host 与 client 服务时，报告必须分开标注两个 half 的结论。

运行时探测规则细化

  • 试运行只注册、不执行模型工具，避免安装动作产生副作用；
  • 成功后统计真实注册数量，而不是只验证 apply 不抛错；
  • 失败时报告首个错误并允许回滚到未安装状态；
  • 更新版本、更换配置、切换运行区时自动重新检测。

兼容性检测 UI（遵循现有设计规范）

插件中心与兼容性检测 UI 不新建设计语言，统一复用现有标准：

维度 必须遵循
设计令牌 --color-* / --radius-* / --material-* / --elevation-* / --font-*；迁移前来自 src/app/base.css，迁移后由 Tailwind @theme 单一来源，变量名不变；插件 CSS 只允许 var(--...) / token 类，禁止硬编码色值
共享样式 src/shared/styles/controls.css / formControls.css / motion.css / menus.css / effects.css
圆角 只使用 --radius-small / --radius-medium / --radius-large；嵌套表面按“外半径减内边距”
动效 使用 --motion-fast/base/slow/exit 与 motion-* 类；reduced-motion / reduced-transparency 有兜底
控件 btn / btn-primary / btn-secondary / input-field / icon-button / list-row / scroll-region
响应式 900px 断点；移动端触控目标最小 44px，桌面可 36px
可访问性 语义化 button、aria-label / title、role="alert" / role="status"、键盘操作、focus-visible、Escape 关闭浮层
国际化 经 useI18n 提供 zh-CN / en-US / ja-JP 全量 key；不硬编码界面文案
图标 lucide-react；图标按钮必须带可翻译的 aria-label
插件边界 UI 只经 ctx.ui / ctx.sunam 注册；不跨插件 static import 内部模块
视觉验收 桌面 / 移动 Playwright 视觉回归；新增基线人工检查，差异 ≤ 0.2%
质量门禁 npm run check / check:all，遵守 .trellis/spec/frontend/ 与 docs/extension-development.md

页面结构

  • 插件列表沿用现有表格 / 列表行：插件名、版本、运行区、状态、兼容度徽标；
  • 插件详情包含：来源与入口形态、服务解析表、缺失服务、surface 结论、运行时 探测、建议处理方式；
  • 兼容度徽标颜色使用现有语义 token：--color-success / --color-accent / --color-warning / --color-danger，不新增色板；
  • 检测中 / 失败 / 空状态复用 AsyncState、role="status" 与 role="alert" 模式，不允许静默失败。

安装流程

  1. 导入或下载 bundle 后先执行静态检测，展示兼容性报告；
  2. compatible：显示安装按钮；
  3. compatible-with-shim：展示将自动挂接的 shim 列表后安装；
  4. needs-conversion：默认阻止，可展开“仅安装 host half”或取消，不允许静默 安装 browser half；选择“仅安装 host half”时，browser half 的入口与依赖 不进入 import graph，也不注册 UI，检测报告继续保留“browser half 未安装”；
  5. incompatible：阻止安装并展示缺失原因；
  6. 安装完成后执行运行时探测，结果回写插件详情并持久化。

热更新与运行态切换

现有基线：内置插件走构建期打包，配置与 fiber 热重载已支持；运行时 ESM 加载 （PLAN 的 B 方案）尚未落地。本轮实现 B 方案：

Sunam 是静态页面，没有服务端推送，因此“热更新”采用客户端拉取 + 运行时切换， 不依赖应用重新部署：

  1. 插件中心检测来源的新版本；
  2. 下载独立 ESM 插件包并校验版本 hash / integrity；
  3. 存入 Cache API / IndexedDB；
  4. 经 PluginRegistration.load 动态 import 新包；
  5. 更新 PluginRegistration 的 plugin / load / 版本 / 安装记录，走 stop + start 替换运行中的 fiber；配置热更新继续走 fiber.update(next, true)， 两者不能混用；
  6. 失败时回滚到上一版本。

内置 @sunam/plugin-* 如果打进 app bundle，只能随应用发布更新；可热更新的第三方 插件必须作为独立 bundle 加载。活跃 Agent run 期间不热切换，更新排队到 run 空闲后 应用，复用现有 E-29 run-gated 延迟重载机制。

需要补齐的控制器语义：

  • install(record)：注册插件、持久化安装记录、运行兼容性检测与试运行；
  • uninstall(id)：停止并移除 fiber、卸载 bundle 引用、清理 UI 插槽与工具、 保留或按策略清除持久化记录；
  • update(id, next)：下载新版本、校验、替换 registration.plugin 与版本、 在 run 空闲后执行 stop + start；失败保留旧 bundle 引用并回滚；
  • rollback(id)：从 previousVersions 恢复旧 bundle / plugin，重复 stop + start；
  • RUN_GATED_PLUGIN_IDS 不能继续只靠硬编码 Set：PluginRegistration 增加 runGated?: boolean，内置安全集合与第三方声明的 runGated 合并判断，更新 和启停都走同一个等待 Agent idle 的入口。

4. 工具库职责

「工具」由现有能力库升级而来。当前能力库已经有模块级与工具级双层开关， 本方案保留该交互，并复用现有 ctx.capability / ctx.tools / RegisteredTool 契约，增加来源、运行区与能力指纹展示，不重建工具注册表。

4.1 工具自动注册与同步

  • 插件导入后由桥接层自动解析工具声明：pi AgentTool / TypeBox、DSH / Cordis 工具服务、MCP 工具列表统一转换为 RegisteredTool，不需要为单个工具手写适配器；
  • 安装、启用、更新、卸载时自动同步注册表：新工具出现、变更或移除都立即反映到 工具库与 Agent 上下文；
  • 标准插件零适配；非标准 API 形态进入 shim 表或 needs-conversion，属于生态 映射而非逐工具开发；
  • 运行时动态注册：插件运行期间调用 ctx.tools.register / unregister 或能力 模块变化时，订阅者自动收到更新；
  • 活跃 run 期间的工具变更沿用 run-gated 延迟应用，避免执行中途切换工具集；
  • systemAccess 指纹由工具 / manifest 声明 + 静态映射自动汇总，不要求用户手填。

每个已注册工具至少展示：

  • 名称、描述、所属模块、来源；
  • 模块开关与工具开关；
  • 依赖工具与依赖关系；
  • 只读 / 并发安全 / 数据影响 / 超时 / 结果类型；
  • 系统能力指纹 systemAccess；
  • 是否会被注入当前 Agent 上下文；
  • 风险与数据影响说明。

工具是否最终注入 AI 上下文，仍由 Agent 层根据用户开关、运行角色与任务策略裁决。 工具库只是注册、观察与授权的入口，不是执行模型本身。

5. 系统能力指纹

在现有 RegisteredTool 元数据基础上，增加更细的系统能力指纹，用于让用户和 AI 调度器都能判断一个工具的真实影响面。

建议模型：

interface SystemAccessFingerprint {
  files?: {
    read?: boolean;
    write?: boolean;
    paths?: string[];
  };
  process?: {
    spawn?: boolean;
    exec?: boolean;
    signal?: boolean;
  };
  network?: {
    fetch?: boolean;
    allowedHosts?: string[];
  };
  storage?: {
    read?: boolean;
    write?: boolean;
    keys?: string[];
  };
  clipboard?: boolean;
  ui?: {
    askUser?: boolean;
    navigate?: boolean;
  };
}

指纹应尽量由工具声明自动汇总，而不是让用户手工填写；来源可以是工具 manifest、 插件 manifest、静态分析结果或适配器映射。指纹进入工具详情，后续也作为 AI 调度的输入。RegisteredTool 扩展字段 origin、runtimeZone、systemAccess 与 SunamPluginManifest 的能力声明同步生成，避免 UI 手填。

指纹与兼容性报告一样，展示时必须带“声明 / 静态分析，非实际行为审计”的提示； 后续若增加运行时行为探测，再按实际结果补充字段，不能用静态汇总冒充审计结论。

6. 权限机制：不设 UI，下沉 Agent 层

Sunam 不做独立的权限管理页面，权限控制放在 Agent 执行层：

  1. 插件 manifest / 工具声明只负责声明能力与风险。
  2. 每次 Run 生成 AgentRun.toolPolicy：由用户开关、工具指纹、运行角色与任务 类型共同派生。现有 AgentToolPolicy 只有 role / allowedTools / writeScope， 本轮扩展为包含 systemAccess 约束与运行区的完整策略。
  3. 工具执行时通过 ToolExecutionContext 携带角色、writeScope、取消信号与 策略、运行区，执行层再决定是否允许。
  4. Succinix 执行世界作为最终物理边界；文件、进程、网络与存储权限最终由容器 与执行世界兜底。

这个设计保留未来接入细粒度权限的可能，但不会把权限变成用户需要学习的产品 页面。

7. 双生态兼容架构

Sunam 同时兼容 pi 与 DSH/Cordis 两套生态，但只保留一个统一工具契约： RegisteredTool。

pi package ──> PiCompatHost ──┐
                             ├──> RegisteredTool ──> Agent 上下文
DSH / Cordis ─> DshToolAdapter ┘

Agent 驱动层保留 AgentDriver 抽象：

  • PiDriver：现有默认实现；
  • DshDriver：新增实现，把 DSH Agent 宿主适配到同一 UI 与事件模型；
  • 未来 CLI 桥：继续作为可选实验驱动。

关键约束：

  • 同一个 Run 只允许一个权威驱动；pi 与 DSH 不同时作为同一个 Run 的执行权威。
  • DSH 插件在同一 Cordis Context 下按 fiber 装配组运行，zone 只是管理标签 与启停作用域，不引入第二套 Cordis runtime（对齐 PLAN DM-41）。
  • pi package 本轮一次性实现完整 PiCompatHost（工具、API、生命周期三层桥接）， 不做“工具级先、宿主后”的临时态。
  • 所有工具注册最终都收敛到 RegisteredTool，工具库只看到一份清单。

驱动选择与 run 映射：

  • 沿用现有 AGENT_DRIVER 配置面：ctx.storage 的 sunam_v2_agent_driver 或构建期 VITE_AGENT_DRIVER，默认 pi；本轮把 AgentDriverId 扩展为包含 'dsh'，并同步 src/plugins/llm/driver/config.ts 的 AGENT_DRIVER_IDS / resolveAgentDriverId 与 create.ts 工厂；
  • DshDriver 懒加载，避免 DSH 运行时进入初始 bundle；同一 run 创建时只选择 一个驱动，run 中途不切换；
  • dsh 被配置但 DSH 运行区不可用时，run 创建应明确报错 / 提示启用 DSH 区， 不静默回退 pi，避免用户以为还在 pi 驱动；
  • DSH run 仍复用 WorkspaceStore、容器与 TerminalService 作为物理执行面， 但 pi session 的创建、持久化与回放只在 PiDriver 路径发生；DSH run 的 会话/检查点落库模型单独声明，不与 pi session 混用；
  • 驱动选择不新增独立权限页；可放在设置/模型配置的现有只读信息区，按 run 创建时生效。

DSH 服务装配区

“DSH 服务装配区”指的是：在 Sunam 中为 DSH 生态开辟一个运行区，把 DSH 插件族 （agent registry、agent loop、system prompt、tool runtime、LLM runtime、 sandbox policy、session store 等）装配到同一 Cordis Context 下的独立 fiber 组中，再通过 DshDriver 桥接到 Sunam 的 UI 与执行世界。它不是设置页或权限页， 也不是第二套 Cordis 运行时，而是插件中心里的一个运行区。DSH 兼容全部在 Sunam 内实现，不依赖 dsh-zeroweb 项目；该 POC 只作为浏览器装配的验证参考。

ClientContext 双 half 插件在 DSH 区只装配 host half：browser half 的入口、 依赖与 UI 不进入 import graph，兼容报告保留“browser half 未安装”结论，直到 插件被改造为 ctx.ui / ctx.display 注册形式。

按 PLAN DM-42，DSH 兼容以源码级 API 形状对齐为主，缺失服务用 @sunam/compat-dsh-tools 等适配层补齐，不复制完整 DSH 宿主。

pi 兼容宿主（PiCompatHost）

pi 插件与 Sunam 插件不是编程语言差异，而是扩展契约差异。兼容方式是在 Sunam 内 建立 pi 扩展区，通过三层桥接一次性接入：

  • PiToolBridge：pi AgentTool / TypeBox → RegisteredTool（反向桥接）， 同时保留现有 RegisteredTool → pi AgentTool 的正向适配；
  • PiApiBridge：pi ExtensionAPI → ctx.* 服务的安全子集；
  • LifecycleBridge：pi package 的安装、启用、配置、卸载映射到插件中心。

本轮一次性交付需要同时完成正向与反向桥接，并删除手写 PI_TOOL_SCHEMAS，改为 统一 schema 规范化层（zod ↔ TypeBox 自动转换，或统一 schema 表示）。实现可复用 现有 piToolAdapter、PiDriver、PiSession，不替换现有 pi Agent 通道。

8. 电脑 = 展示屏幕（Display）

8.1 定位

Sunam 的双区定位固定为：

  • 终端：用户指令输入的地方。终端、服务、文件是容器能力，容器关闭或对应 模块卸载后，这些 segment 从电脑视图移除。
  • 电脑：一个“展示屏幕”。单次对话的 agent / tool / context / telemetry / 日志等状态信息都在这里输出，形式接近 TUI / Linux 终端，而不是常驻聊天页的 仪表盘。

现状问题：status-bar 是一个通用 UI 插槽，内置 telemetry 与 notes 示例都注册到 该插槽，App 根部始终渲染它，因此底部出现常驻 Notes / Telemetry；notes 是静态 示例（当前 0 条），telemetry 在指标产生前也显示空值。context_injected 是 agent 事件，聊天列表又单独把它渲染成固定在消息流底部的气泡，与聊天页和任务列表里的 工具调用记录重复。两者都不是因为参考 DSH 才存在，而是“插件 UI 插槽 + 聊天页 事件渲染”的叠加结果。

本方案把它们统一收敛到“电脑”展示层，聊天主页面只保留对话本身。

8.2 展示层结构

电脑视图是常驻展示屏：

  • 显示流：agent run / phase / tool / context / verification / error 事件、 telemetry 指标、插件日志、系统提示；
  • 默认页面：内置 TUI 脚本，显示 Agent 操作、工具调用、context、telemetry 与 状态栏信息；
  • 展示形态：TUI 风格的行式输出（时间、来源、级别、文本），支持 follow / pause、清屏、分页、section / table 等结构化输出；
  • 插件面板：第三方可通过 ctx.ui 注册 display 插槽条目，提供终端小宠物、 贪吃蛇、图表、自定义分页等组件；
  • 降级模式：关闭 Succinix 容器后，终端 / 服务 / 文件 segment 卸载，电脑仍作为 纯日志 / 展示栏存在，不依赖 Succinix 执行世界。

8.3 脚本化屏幕（Scriptable Display）

“电脑”不仅是日志面板，还是一个可编程的“屏幕硬件”：用户可以用脚本定义显示内容、 分页与交互，Sunam 负责渲染和隔离。

  • 默认页面：内置 TUI 脚本显示 Agent 操作、工具调用、context、telemetry 与 状态栏信息；后续脚本导入器、自定义 TUI 显示与交互由插件实现；
  • 脚本来源：脚本随插件包提供，核心不单独开放用户直接写脚本；需要导入用户脚本 的开发者自行实现脚本导入器插件；
  • 渲染模型：字符网格（TUI），提供 draw / clear / page / section / table / widget、定时器、输入事件（键盘 / 点击 / 滑动）与帧刷新；Canvas / 复杂图形由插件通过 display UI 组件或自建视图实现，核心不内置 Canvas；
  • 运行模型：允许事件循环、requestAnimationFrame 帧刷新、定时器与输入事件， 类似开发板屏幕；
  • 执行边界：脚本跟随插件运行域，不做 display 层白名单限制；安全由插件信任 模型、manifest 能力声明、Agent 权限层与 Succinix / 运行区边界兜底；
  • 降级：不依赖 Succinix 容器，容器关闭后内置 TUI 与插件 TUI 仍可显示。

脚本宿主不能混进 ctx.display 的纯文本接口；@sunam/plugin-display 另外提供 ctx.display.screen（或独立 ctx.screen）注册脚本运行时，包含 draw / clear / page / section / table / widget、输入事件订阅、定时器与帧循环 生命周期。ctx.display.write 只负责事件流输出，screen 才承载可交互 TUI。

8.4 ctx.display 契约

新增 @sunam/plugin-display，提供 ctx.display 与 display UI 插槽：

type DisplayLevel = 'info' | 'agent' | 'tool' | 'success' | 'warn' | 'error' | 'raw';

interface DisplayWriteOptions {
  level?: DisplayLevel;
  source?: string;
  time?: boolean;
  tags?: string[];
}

interface DisplayEntry {
  id: string;
  level: DisplayLevel;
  source: string;
  text: string;
  time: number;
  tags: string[];
}

interface DisplayScreen {
  open(pages: ReadonlyArray<{ id: string; title: string }>): void;
  page(id: string): void;
  draw(rows: ReadonlyArray<ReadonlyArray<string>>): void;
  clear(): void;
  section(title: string): void;
  table(rows: ReadonlyArray<ReadonlyArray<string>>): void;
  widget(id: string, component: unknown): void;
  onInput(handler: (event: unknown) => void): () => void;
  onFrame(handler: (time: number) => void): () => void;
  setInterval(handler: () => void, ms: number): () => void;
}

interface DisplayService {
  write(text: string, options?: DisplayWriteOptions): void;
  clear(): void;
  page(title: string): void;
  section(title: string): void;
  table(rows: ReadonlyArray<ReadonlyArray<string>>): void;
  subscribe(listener: (entry: DisplayEntry) => void): () => void;
  snapshot(): DisplayEntry[];
  screen?: DisplayScreen;
}

约束：

  • write 只接受纯文本 / 结构化数据，不允许 HTML、任意脚本或直接 DOM 写入； ANSI 颜色子集可后续扩展，不默认放开；
  • 第三方复杂组件必须经 ctx.ui.register('display', ...) 注册，遵守现有插件 边界、manifest 能力声明与 UI 设计规范；
  • ctx.display 文本 API 用于事件流与插件输出；脚本页面本身跟随插件运行域， 不额外设置 display 层白名单，能力边界由插件信任模型与运行区兜底；
  • screen 句柄与文本 API 分离，不进入 write 事件流；实现阶段确认挂在 ctx.display 还是独立 ctx.screen，两者不重复提供；
  • 事件桥由 @sunam/plugin-display 订阅 agent 事件（含 context_injected）、 ctx.telemetry snapshot 与 runtime / capability 事件，自动写入显示流。

8.5 现有 UI 收敛规则

  • 删除 App 根部的 app-status-bar 渲染；status-bar 不再作为新插件引导插槽， telemetry 与 notes 的 status badge 以文本 / 图形方式迁移到“电脑”展示终端； 旧 status-bar 插件条目兼容检测时映射到 display，不渲染到主页面，也不判为 不可用；notes 作为示例插件保留，只移除 status-bar 挂载点，其 settings tab / capability / tool 不变；
  • 删除 ChatMessageList 的 contextInjectedEvents 渲染，useAgentV2 / serviceAdapter 不再向聊天页透传该数组；事件仍保留在 agent 事件流供任务列表 与 display 使用；
  • ctx.telemetry 服务保留，只换展示端；
  • 通用 SegmentSelector 只渲染当前 scope 的可见 segment：终端 / 服务 / 文件 / 电脑展示层；可见项少于 2 个时不渲染胶囊，不占黑色终端区域；
  • segment 的可见条件按声明类型区分：终端 / 服务 / 文件等容器 segment = 插件已装载 + capability 开关 + 容器可用；电脑展示层 = 插件已装载 + 开关， 不要求容器可用；工具 / 技能 / MCP 等非容器子视图也不要求容器可用；
  • 顶部 tab 同理：只剩一个 tab 时隐藏 tab 栏，避免单选项空占；
  • 关闭容器 / 卸载模块时，电脑展示层永远保留一个可见 segment。
  • 移动端底部选择器直接渲染全部 primary-nav 项（对话 / 电脑 / 增强 / 商店）； 浮动胶囊是主视图内的二级菜单，跟随当前主视图，不在主入口层混排。

8.6 UI 设计标准

电脑展示层不引入第二套设计语言，遵循现有规范：

  • 使用 --font-mono 渲染行式输出；背景 / 前景沿用 --xterm-bg / --xterm-fg 或 --color-surface / --color-text，不硬编码色值；
  • 级别色使用 --color-info / --color-success / --color-warning / --color-danger / --color-text-secondary；
  • 控件复用 btn / icon-button / scroll-region；插件面板组件仍受 scripts/check-design-tokens.mjs 门禁；
  • 响应式沿用 900px 断点，移动端触控目标不小于 44px；
  • 文案经 useI18n 提供 zh-CN / en-US / ja-JP，图标使用 lucide-react；
  • 降级纯日志模式与完整电脑模式共用同一组件树，不维护两套运行时。

9. 本轮交付：Skill、MCP 与商店

技能（Skill）

Skill 是可安装、可复用的“能力包”，包含提示词片段、工作流、可选工具与元数据。 现有基线中 Skill 仍是 PLAN 的研究项（DSH-06），本轮新增 @sunam/plugin-skills 与 ctx.skills：安装入口放在插件中心，激活后贡献 ctx.systemPrompt 与工具注入。

MCP

MCP 当前不存在，本轮新增 @sunam/plugin-mcp 与 ctx.mcp，同时作为“增强”子视图 与插件来源加入。每个 MCP 工具仍必须映射成 RegisteredTool，并补齐 systemAccess 指纹。MCP 服务器声明的权限不能绕过 Agent 层策略。

MCP 传输首选 HTTP / SSE；stdio 若需要，只能通过 Succinix 执行世界内的 Node 进程承载，不作为浏览器原生能力承诺。

浏览器边界：

  • HTTP / SSE 直连仍受浏览器 CORS 限制，只支持服务器允许跨域访问的 MCP 端点； 不允许 CORS 的端点不承诺直连，可经 Succinix 内 Node 代理或标记不可用；
  • 本轮不强制引入 @modelcontextprotocol/sdk；先用轻量 JSON-RPC over HTTP/SSE client 满足工具列表与调用，若后续需要 stdio / 高级协议能力再经 Succinix Node 桥引入 SDK；
  • 连接失败、服务器下线与工具列表变更都进入插件中心/工具库状态，不静默丢工具。

新增插件与服务清单

插件 服务/UI 说明
@sunam/plugin-ui-enhance 增强主入口 + 插件/工具/技能/MCP 子视图 新增
@sunam/plugin-compat-check ctx.compat 新增，插件导入三层兼容性检测
@sunam/plugin-skills ctx.skills 新增，复用 ctx.systemPrompt 与工具注入
@sunam/plugin-mcp ctx.mcp 新增，工具映射到 RegisteredTool
@sunam/plugin-scheduler ctx.scheduler 新增，元数据驱动调度基础
@sunam/plugin-pi-compat PiCompatHost 新增，复用 piToolAdapter / PiDriver / PiSession
@sunam/compat-dsh-tools DSH 兼容 shim 新增，按 PLAN DM-42 补齐 API 形状；库级 shim，不注册为独立插件
@sunam/plugin-display ctx.display + display UI 插槽 新增，电脑展示屏幕、事件桥与降级日志模式
@sunam/plugin-store ctx.store + 商店主入口 / 四个子市场 新增，目录归一化、外部验证展示、安装桥

10. 商店 = 应用中心（Store）

10.1 定位

商店是跨生态的“发现与安装”主入口；增强是“已安装能力管理”主入口。两者边界：

入口 职责
商店 目录浏览、搜索、筛选、详情、外部验证、安装 / 更新触发
增强 已装插件启停、卸载、更新、配置、依赖、工具 / Skill / MCP 管理

主入口注册：

ctx.ui.register('primary-nav', {
  id: 'store',
  order: 40,
  labelKey: 'nav.store',
  iconKey: 'store',
});

ctx.ui.register('workspace-view', {
  id: 'store',
  order: 0,
  Component: StoreHome,
});

子市场通过同一 segment-nav:store 注册，固定为四个：

  • dsh-plugins：DSH 插件市场；
  • pi-extensions：Pi 拓展市场；
  • skills：Skill 市场；
  • mcp：MCP 市场。

10.2 统一目录模型

新增 StoreEntry，所有来源归一化后进入同一个目录：

interface StoreEntry {
  id: string
  ecosystem: 'dsh' | 'pi' | 'skill' | 'mcp' | 'sunam'
  sourceKind: 'github' | 'npm' | 'registry' | 'mcp'
  sourceRef: string
  name: string
  description: string
  author: string
  license: string | null
  icon?: string
  tags: string[]
  categories: string[]
  version: string | null
  install?: {
    kind: 'bundle' | 'npm' | 'mcp'
    url?: string
    package?: string
    manifestUrl?: string
    integrity?: string
  }
  compatibility?: CompatSummary
  validation?: ValidationSummary
  installed?: InstalledRef | null
}

install 允许缺省：只有源码链接、没有预构建 bundle 的条目应显式为 install: undefined，商店只展示“源码参考 / 需构建”，不能一键安装。bundle 的 integrity 表示最终交付物（单 ESM 文件或 zip）的 digest；若目录支持拆包多文件， 则由 manifest 声明 digest 列表并逐文件校验，不能只校验目录入口。

各市场数据源：

  • DSH 插件：消费 dsh-plugins-store 的静态 catalog.json（官网 CDN / GitHub raw 多源 fallback），归一化 projectType、分类、验证状态到 StoreEntry。
  • Pi 拓展：首个版本内置可维护的静态目录，后续可加 GitHub topic / npm 元数据 同步脚本；条目必须能解析到 package 或 ESM bundle 才可安装。
  • Skill 市场：收录 skill / skill-pack 与声明 Sunam skill manifest 的插件包。
  • MCP 市场：收录 MCP server / registry 条目，安装结果映射为 MCP 客户端连接， 工具仍进入 RegisteredTool。

本轮范围边界：统一目录模型、四个子市场 UI、安装链路与 DSH 市场源完整接入是 必做项；Pi / Skill / MCP 先交付最小内置静态目录与统一骨架，外部自动同步源 （GitHub topic / npm 元数据 / MCP registry）后续逐个接入。所有市场源都只是 远程静态 feed，新增源只增加 feed adapter，不改 UI、安装层与 StoreEntry schema。

浏览器端不连接数据库；目录以版本化静态 JSON 提供，@sunam/plugin-store 负责 拉取、缓存、解析与归一化。

10.3 安装与更新

商店的“安装”按钮不执行 DSH CLI，也不依赖 dsh-plugins-store 的 dsh plugin --profile web add github:<owner>/<repo> 路径。所有安装统一走：

StoreEntry
  -> 解析安装来源（bundle / npm / MCP）
  -> 下载 + integrity 校验
  -> @sunam/plugin-compat-check 三层兼容性检测
  -> 风险确认
  -> PluginRegistryController.install / PluginRegistration.load
  -> 工具与 UI 插槽自动同步

只有源码链接、没有预构建 bundle + manifest + integrity 的 GitHub 条目，商店 只展示“源码参考 / 需构建”，不能一键安装。安装完成后，条目在商店显示“已安装 / 更新可用”，并进入增强的插件中心管理；更新继续复用热更新与回滚基线。

浏览器安装边界：

  • 静态页面不能执行 npm install；npm / git 来源必须已有预构建 ESM bundle， 安装器只下载并校验，不解析 package.json 依赖树；
  • 动态 ESM 只能通过 import() 加载：同源 HTTPS、允许 CORS 的远程 URL、 blob: / data: 可支持；跨域且不允许 CORS 的源默认阻止，避免运行时 import 失败；
  • zip 安装需先解包：manifest 声明入口文件与 digest 列表，逐文件校验后再把 入口转成 blob: URL 供 import()，不直接 import 整个 zip； 多文件 bundle 的相对 import 需重写为绝对 blob: URL 映射，否则不承诺支持； 官方目录优先要求单文件 ESM bundle；
  • 下载与目录 feed 都受浏览器 CSP connect-src 约束；目录源必须允许 CORS 或使用仓库内缓存 fallback，失败不能阻塞对话与增强。
  • 动态 ESM 还受 script-src 约束：若 CSP 不允许 blob: / data:，只能 安装白名单 HTTPS 源，否则安装按钮按不可用处理，不进入运行时失败。

10.4 验证与安全展示

DSH 插件市场可以显示 dsh-plugins-store 的验证阶梯（发现、归类、结构、沙箱、 安装、运行、冒烟、verified / expired），但外部 verified 只作为来源信号，不 代表 Sunam 本地安全背书。用户安装前仍看到：

  • 来源、作者、仓库、许可证与 stars；
  • 外部验证状态与报告链接；
  • Sunam 本地三层兼容性检测结果；
  • 插件声明的能力、依赖与运行区；
  • 明确的风险确认。

风险文案必须包含两层语义：systemAccess / 兼容性结论由声明与静态分析 生成，不代表已审计真实行为；安装第三方插件等于在当前用户浏览器/容器权限内 运行其代码，安装确认必须明确提示“本地执行第三方代码”。商店详情与插件详情 都要展示这句提示，不能只在首次安装弹窗出现。

10.5 UI 规范

  • 商店主视图与四个子市场复用 SegmentSelector、design tokens、共享样式、 900px 断点、i18n 与 a11y；
  • 支持搜索、分类、生态、验证状态、排序与标签聚合；
  • 详情页展示元数据、readme、验证、兼容性、已装状态与安装 / 更新按钮；
  • 安装 / 更新结果与增强中的插件中心双向同步，不出现“装了但看不到”的状态。

10.6 与 dsh-plugins-store 的关系

dsh-plugins-store（MIT）是可复用的参考实现：它的 GitHub topic 发现、分类词典、 验证报告状态机与静态 catalog 结构值得复用；它的 Astro 网站、DSH Web 插件和 CLI 安装端点不作为 Sunam 运行时依赖。若直接复制其代码或目录，保留原 LICENSE 与版权声明。

11. AI 调度基础

当工具元数据标准化后，可以把工具管理交给 AI Agent 自己：

  • 按任务自动注入相关工具；
  • 按风险与任务目标选择工具；
  • 按依赖关系补齐必需工具；
  • 按上下文预算裁剪工具集；
  • 对工具使用进行审计与反馈。

本轮交付实现元数据驱动的确定性调度基础（相关性注入、风险选择、依赖补齐、预算 裁剪），并预留 AI 自主调度接口。调度层落在新增 @sunam/plugin-scheduler 的 ctx.scheduler 中，接入 ctx.agent 的 run 创建流程；完整自主调度不作为独立 UI 功能，由统一调度层演进。

12. 工程基线与样式系统迁移

12.1 终端显示 Succinix 版本

用户终端（Sunam的电脑 → 终端）在 boot / 自检输出中显示 @succinix/engine 当前版本，方便后续升级后直接看到版本信息。

现状：

  • src/host/cordis.ts 硬编码 SUCCINIX_VERSION = '0.6.0'；
  • scripts/sync-succinix-assets.mjs 从 @succinix/engine/package.json 读取版本并校验 0.6.x；
  • src/plugins/terminal/userTerminalSession.ts 保留旧 SUCCINIX_BANNER （文案仍是 0.2.0），但 boot() 已不输出该横幅，目前终端看不到版本。

方案：

  1. 以 @succinix/engine/package.json 的 version 为唯一来源，由 scripts/sync-succinix-assets.mjs 在构建期生成 src/shared/versions.generated.ts（静态 TS 常量）；不再写 public/succinix/version.json，也不做运行时 fetch，避免双版本源和额外 异步路径。check:architecture 增加一致性检查：生成文件与包版本不一致时 构建失败。生成文件应入库或保证在 typecheck 前已生成（check 会先跑 typecheck 再执行 prebuild，不能只挂在 build 阶段生成）。
  2. UserTerminalSession.boot() 在现有 boot 步骤流中输出版本，例如 [ OK ] 1/2 Started WebContainer runtime — Succinix 0.6.0，不恢复 旧横幅，不改变现有 boot 视觉；终端输出保持现有英文 ANSI 风格，不引入 i18n 重写。
  3. 删除 SUCCINIX_VERSION 与 SUCCINIX_BANNER 的手写版本号，升级 @succinix/engine 后重新构建即自动同步，不需要人工改版本。
  4. 版本信息后续可复用于 Agent 终端、服务页与插件中心详情；本轮只要求 用户终端可见。
  5. sync-succinix-assets.mjs 现有 0.6.x 硬校验要改成显式支持范围（或在 升级时同步放开），否则升级 @succinix/engine 会先被该脚本拒绝，与 “升级后自动同步”冲突。

验收：启动用户终端能看到 Succinix 版本；显示值与 node_modules 中的 package.json 一致；升级引擎包后重新构建自动更新；版本不一致时构建或 架构检查失败。

12.2 Tailwind CSS 4 全量迁移

全局 CSS 迁移到 Tailwind CSS 4 最新版，现有视觉样式不变。目标是为规范、 标准、防漏、统一与未来主题系统建立工程基线，因此一次性全量迁移，不留 旧 CSS 双轨。

现状：

  • src/**/*.css 实测约 4.2k 行、115KB、494 个独有 class（不含 node_modules）；
  • src/app/base.css 承载 design tokens 与 base reset；
  • src/shared/styles/* 承载共享控件（controls / formControls / menus / motion / effects）；
  • 各插件 CSS 承载组件样式，由插件入口各自 import；main.tsx 只手动 import 全局 CSS；
  • 已有 scripts/check-design-tokens.mjs 门禁与 src/shared/lib/breakpoints.ts（MOBILE_BREAKPOINT_PX = 900）。

方案：

  1. 引入 tailwindcss + @tailwindcss/vite，Vite 配置加载插件； src/app/tailwind.css 作为 Tailwind 入口（@import "tailwindcss" + @theme），替换 main.tsx 中的旧全局 CSS import；fonts.css 并入 tailwind.css（如无法合并则列入迁移白名单，不作为旧全局 CSS 残留）； 插件 CSS 仍由插件入口 import，Tailwind Vite 统一扫描处理，不要求把插件 CSS 改成全局汇聚 import。

  2. 分四层迁移：

    • Design tokens：base.css 的 --color-* / --radius-* / --material-* / --elevation-* / --font-* / --motion-* 迁入 @theme，类名与 var() 引用保持兼容；
    • Base：* / body / button / 输入等 reset 迁到 @layer base， 先用自定义 base 保持现状，不直接启用 Tailwind Preflight 的不可控 变化；
    • Shared：controls.css / formControls.css / menus.css / motion.css / effects.css 迁到 @layer components，class 名不变；
    • Plugin：按插件逐文件迁移到 @layer components / utility 类，迁移 一个插件就删除对应 CSS 文件。

  3. 迁移顺序：tokens / base → shared → 全局 layout → 各插件（chat / workspace / sidebar / terminal / settings / capability / ...）→ 删除 main.tsx 旧 CSS import 与旧文件。

  4. 防漏与一致性：

    • 新增 scripts/check-css-migration.mjs：扫描残留旧全局 CSS、非 @layer 组件规则与硬编码颜色，纳入 npm run check:architecture； 排除 src/app/tailwind.css 与 fonts.css 等明确保留入口，避免把 Tailwind 入口本身误报为残留；
    • check-design-tokens.mjs 升级为 Tailwind token 门禁：插件只允许 var(--...) 或 Tailwind token 类，不允许硬编码色值；扫描范围从插件 CSS 扩展到全部非 token 入口 CSS（含 shared/ui 等）与新增 TSX 中的 Tailwind color utility 类，原始色值类需列入 @theme 派生清单或禁止；
    • 断点统一由 Tailwind theme 的 --breakpoint-mobile: 900px 提供， MOBILE_BREAKPOINT_PX 与 CSS 保持单一来源；注意 Tailwind 4 默认 breakpoint 变体与现有 max-width: 900px 语义不同，迁移时显式使用 max-mobile / max-[900px] 或保留等价 @media，不得只迁移一半导致 900 / 901 断点漂移；MOBILE_BREAKPOINT_PX 与 --breakpoint-mobile 应通过配置引用 / 生成脚本联动，不允许两处手写，最终由视觉回归确认；
    • DOM / className 默认不改，只迁移 CSS 实现；确需拆解复杂类时按阶段 调整并跑视觉回归；
    • 未来主题系统以 @theme 为 token 唯一来源，暗色 / 高对比主题通过 data-theme 或 CSS 变量覆盖实现，不再散落组件 CSS。

  5. 样式不变验收：

    • 每个插件迁移完成后跑现有桌面 / 移动视觉基线，diff ≤ 0.2%，新增 截图人工核对；
    • 迁移完成后 main.tsx 不再 import 旧全局 CSS；
    • npm run check / test:e2e / test:visual / test:runtime 全绿；
    • 每个插件迁移的截图 diff ≤ 0.2%；若 CSS 层叠顺序变化导致像素噪声，以 maxDiffPixels 人工核对后更新基线，不允许无人工确认地批量更新；
    • 迁移期间不并行开发新样式，先完成迁移再做暗色主题等扩展。

边界：

  • 本轮重点是“引入 Tailwind 4 并让现有样式零变化”，不是把所有 JSX 改成 utility 类；组件 CSS 以 @layer components 保留，新代码再 utility-first；
  • Tailwind 不用于 xterm / 第三方 iframe 内部样式；
  • 不引入 Tailwind UI / Flowbite 等组件库。

13. 一次性开发需求清单

本清单是给 Codex 的一次性交付基线：不按 P0-P5 分期，不留双轨 UI；所有模块在 同一交付内完成并切换，旧能力库入口直接删除。

13.1 产品需求

# 需求 验收
P-01 新增主入口“增强”，由 @sunam/plugin-ui-enhance 提供，通过 primary-nav / workspace-view 注册，与“对话 / 电脑 / 商店”同级；内含“插件 / 工具 / 技能 / MCP”四个子视图 导航可见，四个子视图均可进入
P-02 现有能力面板演进为“增强 → 工具”，旧入口删除，不再保留双轨 代码中无旧能力库入口，工具功能不回归
P-03 插件中心在 ctx.plugins 上扩展 pi package / Cordis / DSH / npm / git / CDN / 本地包来源；npm / git 要求预构建 ESM bundle，源码-only 条目不可一键安装 可安装来源至少有一条安装路径，源码-only 条目明确显示“需构建 / 仅参考”
P-04 在现有启停/重载/配置/依赖/日志之上扩展安装、卸载、更新、搜索、版本 插件生命周期操作完整可测
P-05 插件详情展示来源、运行区、依赖、信任等级与能力声明；不提供权限配置页 详情完整，无权限 UI
P-06 工具库复用 ctx.capability / ctx.tools，展示模块分组、工具开关、依赖、详情、来源、风险、数据影响、超时、读写执行标签 已注册工具均可查看
P-07 每个工具展示扩展后的 systemAccess 系统能力指纹 工具详情可见指纹
P-08 新增 @sunam/plugin-skills：Skill 可安装、激活，贡献提示词、工作流与可选工具 激活后系统提示词与工具注入生效
P-09 新增 @sunam/plugin-mcp：MCP 作为子视图与插件来源；MCP 工具进入统一工具清单 MCP 工具可注册、启停、执行
P-10 不做独立权限页；权限显示只读，执行由 Agent 层裁决 无权限配置入口，策略在 run 中生效
P-11 落地运行时 ESM（PLAN B 方案）：插件中心支持版本检测、更新与回滚；热更新不打断活跃 Agent run 更新后插件运行新版本，失败可回滚，run 不被中断
P-12 导入第三方插件时执行三层兼容性检测，输出兼容度、缺失服务与建议处理方式；结果持久化到插件详情，更新版本时重新检测 ClientContext 插件安装前提示需改造，服务型 DSH 插件可确认兼容
P-13 插件中心与兼容性检测 UI 遵循现有设计规范：design tokens、共享样式、900px 断点、i18n、可访问性与视觉回归 scripts/check-design-tokens.mjs 通过（随 npm run check:architecture 执行），桌面/移动视觉回归通过，无硬编码文案与色值
P-14 聊天主视图不再渲染全局 status-bar 与 context_injected 气泡；单次会话状态、telemetry、context、日志统一进入“电脑”展示层 App 底部无状态栏，消息流无 context 气泡，电脑展示层可看到对应事件
P-15 新增 @sunam/plugin-display：ctx.display + display UI 插槽，提供 TUI 行式输出、分页 / 面板、clear / follow / pause；关闭 Succinix 容器后仍可作为纯日志栏 关闭容器后电脑视图仍显示日志；插件可通过 ctx.display 输出并注册自定义面板
P-16 终端 / 服务 / 文件等模块卸载或关闭后，胶囊选择器与顶部 tab 自动收敛；可见项少于 2 个时不渲染选择器 / tab 栏 关闭全部容器模块后黑色终端区域不再显示胶囊，电脑展示层仍可见
P-17 新增 primary-nav / workspace-view 主入口插槽：“增强”与“商店”经该契约注册；第三方 Sunam 插件可用同一契约新增主界面 插件启用后主入口与视图同步出现，卸载后同步移除
P-18 胶囊选择器抽成通用 SegmentSelector，子页面经 segment-nav:<scope> 注册；“电脑 / 终端 / 服务 / 文件”、“增强：插件 / 工具 / 技能 / MCP”与“商店：DSH插件 / Pi拓展 / Skill市场 / MCP市场”复用同一组件与样式 三个模块的胶囊由同一组件渲染，样式、自适应与动效只维护一份
P-19 “电脑”内置 TUI 脚本默认展示 Agent 操作与状态栏信息；脚本随插件包提供，支持字符网格、分页、输入事件、定时器与帧循环，不依赖 Succinix 容器 默认 TUI 显示 Agent / telemetry 信息；插件可提供自定义 TUI 页面；容器关闭后仍可运行
P-20 子页面显示条件按 segment 声明：容器 segment = 插件已装载 + capability 开关 + 容器可用；电脑展示层 / 工具 / 技能 / MCP = 插件已装载 + 开关，不依赖容器；旧 status-bar 条目以文本 / 图形迁入展示终端 页面不写死 segment，容器关闭后展示层仍可见，非容器子视图不被误隐藏；主页面无 status-bar 侵入
P-21 新增主入口“商店”，由 @sunam/plugin-store 提供，通过 primary-nav / workspace-view 注册，与“对话 / 电脑 / 增强”同级；内含“DSH插件 / Pi拓展 / Skill市场 / MCP市场”四个子市场 导航可见，四个子市场均可进入，胶囊复用 SegmentSelector
P-22 @sunam/plugin-store 提供 ctx.store 与统一 StoreEntry 目录模型，支持多市场 feed 归一化、搜索、分类、排序、标签聚合与详情 四个市场共用同一目录视图与详情组件，DSH / Pi / Skill / MCP 条目均可浏览
P-23 DSH 插件市场消费 dsh-plugins-store 静态 catalog.json（官网 CDN / GitHub raw 多源 fallback），并归一化其项目类型、分类与验证状态 商店可加载 DSH 目录，目录失败时有备用源与错误提示
P-24 Pi 拓展、Skill 市场、MCP 市场本轮交付最小内置静态目录 + 统一目录 / 详情 / 安装骨架；外部自动同步源后续逐个接入 三个市场可浏览与搜索；内置条目可安装；后续新增源不需要改 UI / 安装层
P-25 商店安装统一走插件中心安装器：解析来源、下载 + integrity 校验、三层兼容性检测、风险确认、注册加载、工具同步；不执行 DSH CLI 商店安装与增强插件中心状态一致，无 dsh plugin add 调用
P-26 商店详情展示外部验证阶梯与 Sunam 本地兼容性检测结果；安装前必须风险确认 外部 verified 与本地兼容度分开显示，未确认不能安装
P-27 商店与增强/插件中心双向同步安装状态：已安装、更新可用、卸载后恢复“未安装” 商店按钮状态与插件中心一致，更新走热更新与回滚
P-28 用户终端 boot / 自检输出显示 @succinix/engine 当前版本，版本来自单一来源，升级自动同步 启动终端可见 Succinix 版本，显示值与 package.json 一致；升级引擎包后重新构建自动更新
P-29 全局 CSS 全量迁移到 Tailwind CSS 4，现有视觉不变；删除旧全局 CSS import，@theme 作为 design tokens 与未来主题系统单一来源 main.tsx 无旧全局 CSS import；残留 CSS / 硬编码颜色门禁通过；桌面 / 移动视觉回归全绿
P-30 设置页 settings.plugins 不再作为独立插件管理入口，迁移 / 重定向到“增强 → 插件”；设置页保留 provider / persona / about 等非插件管理页签 代码无第二套插件管理入口，从设置页进入插件管理跳转增强，不留双轨

13.2 架构需求

# 需求 验收
A-01 所有功能域继续按 Cordis 插件开发 新功能均为 @sunam/plugin-*；纯库 shim 允许 @sunam/* 并注册到插件中心，不引入平行插件系统
A-02 在现有 RegisteredTool 上扩展 origin、runtimeZone、systemAccess，仍是唯一工具契约 pi / DSH / MCP / 原生工具统一注册
A-03 建立统一 schema 规范化层，替换手写 PI_TOOL_SCHEMAS pi 工具与 Sunam 工具双向转换无需手写 schema
A-04 AgentDriver 保留，AgentDriverId 增加 'dsh'，新增 DshDriver；同步 src/plugins/llm/driver/types.ts、config.ts、create.ts；同一 Run 只有一个权威驱动，run 中途不切换 pi 与 DSH 可分别作为驱动运行；AGENT_DRIVER 存储/env 可解析 dsh；DSH run 不混用 pi session 持久化
A-05 DSH 插件运行在同一 Cordis Context 下的 fiber 装配组，zone 是元数据；不依赖 dsh-zeroweb 项目 DSH 插件生命周期与主区隔离，但不引入第二 Cordis runtime
A-06 实现 PiCompatHost（PiToolBridge、PiApiBridge、LifecycleBridge），复用现有 pi 层 pi 插件可安装并注册工具到工具库
A-07 在现有 AgentRun.toolPolicy 基础上扩展完整策略，由用户开关、工具指纹、角色、任务类型派生 每次 run 生成并执行策略
A-08 ToolExecutionContext 在现有 writeScope / signal 上增加策略与运行区 工具执行可被策略拦截
A-09 插件安装状态与版本记录持久化到 ctx.persistence / ctx.storage 刷新后插件状态与工具清单恢复
A-10 pi / DSH 运行时按运行区懒加载 初始 bundle 不会同时打包两套 Agent 运行时，只在对应驱动首次使用时加载
A-11 旧能力库模块、旧权限相关 UI、手写 schema 映射一次性删除 不留双轨与临时兼容层
A-12 第三方插件经现有 PluginRegistration.load 以独立 ESM bundle 加载，带 hash / integrity；安装记录持久化 刷新后恢复，热更新不依赖应用重新部署
A-13 新增 @sunam/plugin-compat-check 提供 ctx.compat：静态分析、服务差集、运行时探测，检测结果接入安装流程 导入/更新插件时输出四档兼容度，缺失服务可定位
A-14 兼容性检测报告持久化到 ctx.persistence / ctx.storage；插件更新、配置变更或运行区切换时自动重新检测 刷新后详情仍保留，更新后重检生效
A-15 新增 @sunam/plugin-display 提供 ctx.display；移除 App 根部 status-bar 渲染，status-bar 不再作为新插件引导插槽，telemetry / notes 迁移到 display 无 status-bar 渲染，扩展文档不再引导新插件注册 status-bar
A-16 显示 API 只接受纯文本 / 结构化输出；第三方组件经 ctx.ui.register('display', ...) 注册，遵守插件边界、manifest 能力声明、design tokens 与安全策略 插件无法通过 display 越权访问文件 / 进程 / 网络；组件注册有能力声明
A-17 agent context_injected、telemetry snapshot、run / tool 事件自动桥接到 display；聊天页与任务列表不重复渲染同一信息 单次 run 的事件在电脑展示层可见且不重复
A-18 新增主入口渲染壳；Workspace / TerminalTabs / ContainerCapsule / MobileNavigation 的主入口与 segment 从插槽注册表派生，删除写死的 ai / capability / 四个 segment / 三个移动 tab 常量 无硬编码主入口 / segment，桌面与移动端都能注册新主界面
A-19 扩展 SlotEntry 与 uiSlots：新增 labelKey? / iconKey?，Component 可选；primary-nav 按 id / order / labelKey / iconKey 渲染，workspace-view 必填 Component；manifest 同步生成，生命周期与启停 / 卸载一致 插件中心可管理新主界面插件，入口与视图随生命周期同步移除
A-20 新增通用 segment-nav:<scope> 子页面插槽与共享 SegmentSelector 组件；ContainerCapsule 写死的 SEGMENTS 改为 scope 注册表驱动，键盘 / 滑动 / 图标收缩 / 自动隐藏逻辑统一 电脑与增强的子页面均可注册、排序、卸载；无重复胶囊实现
A-21 segment-nav:<scope> 不设注册限制：第三方可注册任意 scope，也可改造其他插件的 scope 条目；同 scope 同 id 复用 ctx.ui 原子替换，排序由 order 决定 任意 scope 可注入 / 覆盖 / 排序，官方默认先加载，无专属注册锁
A-22 主入口 active 状态只存运行时内存，默认“对话”，不做全局持久化；当前视图插件卸载 / 禁用时自动回退到“对话” 刷新后回到默认入口，卸载当前视图不进入死页面
A-23 脚本化屏幕以字符网格渲染，脚本随插件包加载，跟随插件运行域，不做 display 层白名单限制；安全由插件信任模型、manifest 能力声明、Agent 权限层与运行区兜底 插件 TUI 可自由访问插件已声明能力；未声明 / 未授权能力仍受插件中心与 Agent 策略约束
A-24 插件导入后工具自动解析、自动同步注册表：安装 / 启用 / 更新 / 卸载时自动注册、替换或移除工具，标准插件无需逐工具手写适配 pi / DSH / MCP 插件安装后工具自动进入工具库，更新与卸载同步生效；无新增手写 per-tool adapter
A-25 @sunam/plugin-store 按 Cordis 插件开发，注册 primary-nav: store、workspace-view: store 与 segment-nav:store 四个子市场 商店入口 / 子市场与插件生命周期同步，无写死主入口
A-26 新增版本化 StoreEntry / feed parser，多市场目录统一 schema，解析失败有明确错误且不污染本地状态 DSH 市场完整归一化；Pi / Skill / MCP 内置目录可归一化；后续新增 feed 不污染已有缓存
A-27 商店目录以静态 JSON 拉取、缓存与 fallback，不引入服务器与数据库 离线或上游不可用时显示缓存 / 错误 / 重试，不阻塞对话与增强
A-28 商店安装路径只允许 bundle + manifest + integrity 或 npm / MCP 来源；源码-only 条目 install: undefined，不可一键安装；动态 ESM 只支持同源 / 允许 CORS / blob / data 代码中无 dsh plugin --profile web add 安装分支；不可安装条目无安装按钮
A-29 商店 UI 严格复用 SegmentSelector、design tokens、共享样式、900px 断点、i18n 与 a11y；视觉回归覆盖桌面 / 移动 scripts/check-design-tokens.mjs 对商店 UI 全绿，视觉回归通过
A-30 若复用 dsh-plugins-store 的目录结构、分类规则或验证状态机，保留 MIT LICENSE 与版权声明；不依赖其 Astro 站点 / DSH Web 插件运行时 仓库内保留上游许可说明；构建不访问 dsh.aitreez.com，运行只把它作为可替换 feed 源之一，站点不可用时走 fallback / 缓存
A-31 Succinix 版本单一来源：sync-succinix-assets.mjs 构建期生成 src/shared/versions.generated.ts，不写 / 不读 public/succinix/version.json；check:architecture 校验生成值与包版本一致；生成文件入库或保证在 typecheck 前存在 终端版本与 @succinix/engine 包版本一致，无手写版本号与运行时 fetch，一致性检查通过
A-32 Tailwind CSS 4 通过 @tailwindcss/vite 接入，@theme 承载 tokens，base / components 分层迁移；class 名与视觉保持不变 Vite 构建加载 Tailwind，主题变量与现有 CSS 变量兼容，视觉回归通过
A-33 新增 scripts/check-css-migration.mjs（排除 tailwind.css / fonts.css 等明确保留入口），check-design-tokens.mjs 升级为 Tailwind token 门禁并覆盖插件 CSS 与新增 TSX utility 类；断点由 Tailwind theme 与 MOBILE_BREAKPOINT_PX 单一来源 迁移完成后无残留旧全局 CSS 文件与硬编码色值，900px 断点两端一致
A-34 迁移后未来主题系统以 @theme 为 token 唯一来源；暗色 / 高对比主题通过 data-theme / CSS 变量覆盖，不散落组件 CSS 主题扩展不需要改组件 CSS，设计令牌门禁可追踪 token 来源
A-35 PluginRegistryController 新增 install / uninstall / update / rollback / listInstallRecords；PluginRegistration 增加安装记录、bundle 地址、integrity、运行区、runGated 与旧版本引用；代码热更新走 stop + start，配置热更新走 fiber update 插件中心可完成安装、卸载、更新、回滚全流程，活跃 run 不被打断
A-36 商店目录与动态 ESM 安装遵守浏览器边界：目录源 / bundle URL 必须允许 CORS 或同源，npm / git 只接受预构建 bundle，CSP 受限时明确报错并保留缓存 不支持安装的条目不出现可安装按钮；目录失败不影响对话与增强
A-37 兼容性报告、指纹与商店详情必须展示“声明 / 静态分析而非审计”，安装确认必须包含“本地执行第三方代码”风险说明 用户在任何安装入口都能看到风险语义，不依赖隐藏弹窗
A-38 ctx.display 纯文本事件流与 ctx.display.screen 脚本宿主分离；screen 提供 draw / clear / page / section / table / widget、输入事件、定时器与帧循环生命周期 文本 API 不解析脚本；screen 不直接暴露文件 / 进程 / 网络能力，越权由插件信任模型与 Agent 策略兜底

13.3 实施顺序（同一交付批次内）

  1. 契约与数据模型：RegisteredTool 扩展、SystemAccessFingerprint、 AgentRun.toolPolicy、SlotEntry / uiSlots 扩展、插件来源与安装记录、 PluginRegistryController 安装/更新/回滚接口、StoreEntry 目录模型。
  2. 工具 schema 规范化层：zod ↔ TypeBox 自动转换，替换手写映射。
  3. 扩展现有 pluginRegistry / ctx.plugins：安装状态、版本、依赖、运行区、 下载缓存、hash 校验、runGated 与回滚。
  4. 兼容性检测层：@sunam/plugin-compat-check 静态分析、服务差集、运行时探测。
  5. 商店目录与市场归一化：@sunam/plugin-store、StoreEntry feed parser、 DSH 目录完整接入，Pi / Skill / MCP 最小内置静态目录 + 统一骨架、缓存与 fallback；同时落实 CORS / CSP / integrity 安装边界。
  6. 兼容性检测 UI：复用 design tokens / 共享样式 / 900px 断点 / i18n / a11y。
  7. 运行区：Sunam 主区、DSH fiber 装配组、pi 扩展区（同一 Cordis Context）。
  8. 适配器：DshDriver、PiCompatHost 三层桥接、MCP 工具映射。
  9. Agent 权限执行层：toolPolicy 扩展、生成、执行拦截、Succinix 边界。
  10. 产品 UI：@sunam/plugin-ui-enhance 增强入口与 @sunam/plugin-store 商店 入口、插件中心、工具库、Skill、MCP、四个子市场。
  11. 电脑展示层与主入口插槽：primary-nav / workspace-view / segment-nav:<scope> / display 插槽、通用 SegmentSelector、脚本化 TUI 屏幕、事件桥、胶囊 / tab 从注册表派生并自动收敛、旧 status-bar 与 context_injected 气泡清理。
  12. 迁移与清理：能力库入口迁移删除，旧页面与临时代码清理。
  13. 测试与验收：单元、组件、e2e、视觉回归、架构门禁、包体与覆盖率。
  14. 终端版本显示：版本单一来源、versions.generated.ts、boot 输出、 一致性检查。
  15. Tailwind CSS 4 全量迁移：安装与 Vite 接入 → tokens / base → shared → 全局 layout → 插件逐文件迁移 → 删除旧 CSS → 视觉回归与迁移门禁。

13.4 验收门禁

  • npm run check 全绿，且不新增双轨 UI。
  • 同一个工具库可同时列出 Sunam / pi / DSH / MCP 工具。
  • 安装 pi 或 DSH 插件后，工具可在工具库管理并进入 Agent 上下文。
  • systemAccess 与 toolPolicy 在真实 run 中生效，不依赖 UI 开关兜底。
  • 旧“能力库”入口、设置页独立插件管理入口与旧 PI_TOOL_SCHEMAS 不再存在。
  • 不依赖 dsh-zeroweb 项目，DSH 兼容全部在 Sunam 内实现。
  • 插件中心可完成一次“检测更新 → 下载 → 热切换 → 回滚”全流程，不刷新页面，活跃 run 不被打断。
  • 导入或更新第三方插件时输出四档兼容度，缺失服务可定位；ClientContext 插件安装前提示需改造。
  • 商店与插件详情展示“声明 / 静态分析而非审计”和“本地执行第三方代码”风险说明； 不支持安装的源码-only / 跨域受限条目没有可安装按钮。
  • scripts/check-design-tokens.mjs 对插件中心 UI 全绿；兼容性检测 UI 通过桌面 / 移动视觉回归，新增基线人工检查。
  • 不新增平行插件系统：插件中心、工具库、热更新均复用现有 ctx.plugins / ctx.capability / ctx.tools / PluginRegistration.load。
  • 商店四个市场均可浏览、搜索、安装 / 更新；安装后的插件立即进入增强管理， 安装路径不执行 DSH CLI，不依赖 dsh.aitreez.com 站点运行时。
  • 商店 UI 与兼容性检测 UI 的 design tokens / 视觉回归检查全绿。
  • App 根部无 status-bar 渲染，聊天消息流无 context_injected 气泡。
  • 关闭容器后电脑视图仍保留展示 / 日志层；胶囊选择器与顶部 tab 在可见项少于 2 个时隐藏。
  • ctx.display 可被第三方插件调用并注册自定义显示组件，且不越过显示边界。
  • 插件可通过 primary-nav / workspace-view 注册新主界面；启用 / 卸载后入口与 视图同步出现 / 移除，TerminalTabs / ContainerCapsule 无写死主入口。
  • “电脑”、“增强”与“商店”的二级栏目由同一个 SegmentSelector 渲染；新增 scope 时无需复制胶囊样式或交互逻辑。
  • 默认 TUI 与插件 TUI 可在 Succinix 容器关闭后运行；脚本跟随插件运行域，安全 由插件信任模型与权限层兜底。
  • 旧 status-bar 条目以文本 / 图形进入电脑展示终端，主页面无 status-bar。
  • 主入口 active 状态不落库，刷新回到默认入口；卸载当前视图自动回退“对话”。
  • 用户终端启动后可见 Succinix 版本，升级 @succinix/engine 后无需手改 版本号；versions.generated.ts 与包版本一致，无运行时 version fetch。
  • main.tsx 无旧全局 CSS import；check-css-migration.mjs 通过； @theme 与 var(--...) 兼容；桌面 / 移动视觉回归差异 ≤ 0.2%。

14. 实现基线决定

为让 Codex 可直接实施，以下事项不再作为待确认：

  • “增强”是主入口；Skill 与 MCP 都是其子视图。
  • MCP 既作为子视图，也作为工具来源。
  • 权限不设 UI；manifest 只声明，AgentRun.toolPolicy 执行。
  • pi 扩展区本轮完整实现三层桥接，不做“工具级先、宿主后”的临时态。
  • DSH 兼容在 Sunam 内实现，不依赖 dsh-zeroweb；DSH 区是同一 Cordis Context 下的 fiber 装配组，不是嵌套 Cordis runtime。
  • 插件中心在 ctx.plugins 上扩展，不重建插件系统。
  • Skill / MCP / 调度层是新增插件模块：@sunam/plugin-skills、 @sunam/plugin-mcp、@sunam/plugin-scheduler。
  • npm / git 来源要求预构建 ESM bundle + manifest + hash/integrity。
  • systemAccess 默认由插件 manifest / 工具声明 + 静态映射生成，后续可加运行时探测。
  • 插件导入自带三层兼容性检测（静态分析 / 服务解析 / 运行时探测），结论写入插件 详情并随更新重跑。
  • 兼容性检测 UI 严格复用现有设计令牌、共享样式、响应式、国际化与可访问性标准， 不引入第二套设计语言。
  • 插件信任模型：来源标注 + 能力声明 + 安装确认 + 运行区隔离；签名体系不阻塞本轮。
  • “终端”是用户指令输入的地方，“电脑”是展示屏幕；单次会话状态、telemetry、 context 与日志统一进 ctx.display，不占用聊天主页面。
  • status-bar 与 context_injected 气泡从聊天主视图移除；telemetry 服务保留， 只换展示端。
  • 关闭 Succinix 容器后“电脑”仍可作为纯日志 / 展示栏，不依赖 Succinix 执行世界。
  • 胶囊选择器与顶部 tab 在可见项少于 2 个时隐藏，不占黑色终端区域。
  • 主入口采用 primary-nav + workspace-view 插槽模型，对齐 VS Code；“增强” 与“商店”通过该契约注册，“能力库”迁入“增强”后不再是独立主入口。
  • 桌面端保留现有“对话 + 电脑”双栏工作区形态，primary-nav 先接管导航与主视图 切换；整页切换模式不纳入本轮。
  • 二级栏目采用通用 segment-nav:<scope> + 共享 SegmentSelector；“电脑”与 “增强”与“商店”复用同一胶囊组件，只维护一份样式与交互。
  • “商店”是主入口，下设 DSH 插件 / Pi 拓展 / Skill 市场 / MCP 市场四个子市场； 商店负责发现与安装，增强负责已装能力管理，不重复建设安装入口。
  • 商店安装统一复用插件中心安装器、三层兼容性检测与热更新；不执行 DSH CLI， dsh-plugins-store 只作为目录 / 验证模型参考，不作为运行时依赖。
  • 商店源覆盖边界：DSH 市场源本轮完整接入；Pi / Skill / MCP 只交付最小内置静态 目录与统一骨架，外部自动同步源后续逐个接入，新增源只写 feed adapter。
  • 主入口 active 状态只存运行时内存，默认“对话”，不写数据库。
  • segment-nav:<scope> 不设注册限制；同 scope 同 id 原子替换，order 排序。
  • 子页面显示条件按 segment 声明：容器 segment 需要容器可用；电脑展示层与 非容器子视图不依赖容器，避免关闭容器后误隐藏展示层。
  • 移动端底部选择器渲染全部 primary-nav，胶囊只作为主视图内二级菜单。
  • 旧 status-bar 映射到电脑展示终端，不侵入主页面。
  • 脚本化屏幕不依赖 Succinix 容器；默认内置 TUI 脚本显示 Agent 操作与状态栏信息， 脚本随插件包提供，渲染模型为字符网格，不做 display 层白名单限制。
  • Tailwind CSS 4 全量迁移与终端版本显示纳入本批次；样式迁移先保视觉零变化， 不并行开发新主题；版本信息以 @succinix/engine 包为唯一来源，只生成静态 TS 常量，不做运行时 version fetch。
  • 商店安装遵守浏览器边界：只有 bundle + manifest + integrity 或允许 CORS / 同源的动态 ESM 可安装；风险确认必须包含“声明非审计”和“本地执行 第三方代码”语义。

15. 边界条件与回退策略

  • 主入口 active 状态只存运行时内存，默认“对话”，不做全局持久化；刷新后回到 默认入口，卸载 / 禁用当前视图插件时自动回退到“对话”。
  • segment-nav:<scope> 不设注册限制：第三方可以注册任意 scope，也可以改造其他 插件的 scope 条目；同 scope 同 id 复用 ctx.ui 原子替换，排序由 order 决定； 官方默认条目先加载，第三方通过替换 / order 调整。
  • “电脑”子页显示条件按 segment 声明：终端 / 服务 / 文件等容器 segment = 插件已装载 + 对应 capability 开关 + 容器可用；电脑展示层与工具 / 技能 / MCP 子视图不要求容器可用，避免关闭容器后误隐藏展示层。
  • 移动端底部选择器直接渲染全部 primary-nav 项（对话 / 电脑 / 增强 / 商店）； 浮动胶囊是主视图内的二级菜单，跟随当前主视图，不在主入口层混排。
  • status-bar 不再渲染到主页面；旧条目以文本 / 图形方式迁移到“电脑”展示终端， 兼容检测不判为不可用，而是映射到 display。
  • 脚本化屏幕不依赖 Succinix 容器，容器关闭后仍可作为 log / 自定义屏幕使用； 默认内置 TUI 脚本显示 Agent 操作与状态栏信息。
  • 脚本随插件包提供，跟随插件运行域，不设 display 层白名单；渲染模型固定字符 网格，Canvas 由插件自建视图实现；允许事件循环、帧刷新与输入事件。
  • 脚本安全由插件信任模型、manifest 能力声明、Agent 权限层与运行区边界兜底， 不通过 display API 重复设限。
  • 工具注册由桥接层自动解析与同步，标准 pi / DSH / MCP / Cordis 插件无需逐工具 手写适配；运行时动态注册也自动反映到工具库。
  • 商店目录以静态 JSON 多源 fallback 加载，目录不可用时保留缓存与错误态，不阻塞 对话 / 增强；外部验证状态不作为本地安全背书，安装仍走本地兼容检测与风险确认。
  • 目录源与动态 ESM 必须满足浏览器 CORS / CSP 约束：仅同源、允许 CORS 的远程 URL、blob: / data: 可安装；不允许的源标记不可安装，不静默失败。
  • 源码-only 的商店条目不可一键安装，只有 bundle + manifest + integrity 或 npm / MCP 来源可安装；更新继续复用热更新与回滚。
  • Pi / Skill / MCP 的自动同步源不在本轮范围：本轮只保证统一 StoreEntry feed 接口、四个子市场 UI 与最小内置目录；后续接 GitHub topic / npm / MCP registry 时不改 UI、安装层与 schema 主路径。
  • 不在本轮范围：复刻 dsh-plugins-store 的 Docker 沙箱验证流水线、Astro 站点、 DSH Web 插件与 CLI 安装端点；外部验证只作展示，不作为 Sunam 本地安全背书。
  • 第三方复杂 display 组件仍走 ctx.ui.register('display', ...)；与脚本屏幕通过 同一事件流 / 显示槽协作，不另建 GUI 运行时。
  • 热更新的代码包切换走 stop + start 替换 registration.plugin；配置热更新 继续走 fiber update；runGated 由内置硬编码集合与第三方插件声明合并，不 只靠硬编码列表。
  • 兼容性结论与 systemAccess 来自声明 / 静态分析，不代表已审计；安装第三方 插件即在其当前浏览器 / 容器权限内执行代码，详情与确认弹窗都要说明。

16. 参考资料

本节路径以仓库根 /Users/mac/Desktop/MyProject 为基准；官方链接用于核对上游 语义，本地 README 与契约快照用于当前版本的实现基线。

pi 生态

  • 官方仓库：https://github.com/earendil-works/pi
  • 官方 npm 页：
  • 本地包文档：
    • SunamAI/node_modules/@earendil-works/pi-agent-core/README.md（0.84.0）： Agent 状态机、prompt/continue 事件流、工具执行、AgentTool / TypeBox、 steering / follow-up、session 与 thinking budgets。
    • SunamAI/node_modules/@earendil-works/pi-ai/README.md（0.84.0）： 统一 LLM API、provider / model catalog、工具定义、流式 toolcall、上下文 序列化与跨 provider 交接。
    • SunamAI/node_modules/@earendil-works/pi-telemetry/README.md（0.84.0）： TelemetryContext / TelemetrySpan 契约、NOOP_TELEMETRY_CONTEXT 与 in-memory 参考实现。
  • 实现时若 README 未覆盖具体公开 API，以对应包 dist/*.d.ts 类型声明为准： SunamAI/node_modules/@earendil-works/pi-agent-core/dist/、 SunamAI/node_modules/@earendil-works/pi-ai/dist/。

DeepSeek Harness（DSH / Cordis）

  • 官方仓库：https://github.com/deepseek-ai/deepseek-harness
  • 官方运行入口：npx @deepseek-ai/dsh web（默认 localhost:3080）。
  • Cordis fork：
  • DSH 0.1.0-rc.6 服务契约快照（官方 d.ts + README + provenance）：
    • Succinix/docs/contracts/dsh-0.1.0-rc.6/：dsh-fs、dsh-sandbox、 dsh-terminal、dsh-session-persistence，SOURCES.md 记录 npm integrity 与 checksum。
    • dsh-zeroweb/docs/contracts/dsh-0.1.0-rc.6/：同一快照的镜像。
    • dsh-zeroweb/docs/snapshots/dsh-0.1.0-rc.6/：完整发布类型面、peer graph、 node import scan。
  • 已安装的官方 DSH 包文档（0.1.0-rc.6）：
    • dsh-zeroweb/node_modules/@deepseek-ai/dsh-agent/README.md：Agent 接口、 registry、initiator scope、agent/* 事件词汇。
    • dsh-zeroweb/node_modules/@deepseek-ai/dsh-client-web/README.md：web shell kernel、两阶段 boot、loader 装配。
    • dsh-zeroweb/node_modules/@deepseek-ai/ 下其余 @deepseek-ai/dsh-* 包均带 README，覆盖 agent loop、client UI、sandbox、session、tools、LLM、commands、 scope 等。
  • 社区移植参考（非官方，仅作为浏览器装配验证参考）：
    • dsh-zeroweb/README.md
    • dsh-zeroweb/docs/PLAN-dsh-zeroweb.md
  • DSH 插件商店参考（MIT，目录 / 验证模型可复用，不作为 Sunam 运行时依赖）：
  • 配套本地计划：
    • Succinix/docs/PLAN-dsh-native.md
    • Succinix/docs/cordis-contract.md