feat(apes-sidebar): Phase 0 工程骨架 — host/client 分裂 + i18n + 不变量面

从 0 重写的 v2.0.0 DSH 侧边栏插件第一阶段： - 工程骨架：tsdown 双构建（host ESM + client CJS closure）、vitest、strict TS - host 半：namespace 插件形状（name/inject/apply，无 default），minimal apply - client 半：closure factory 注册 5 个 apes:* tab 占位 + zh/en i18n - 不变量面：assert/semver/peer guard（dsh-better-sidebar >= 0.18.0） - 依赖策略：dsh-better-sidebar=peerDependency（不打包），cordis=devDependency（仅类型） - 门禁：pnpm typecheck + build + test 全绿（14 单测通过） - AGENTS.md 工程约定 + .gitignore（排除 lib/node_modules/maxkb-integration）模板：dsh-better-sidebar。作用域锁定信息层（tasks/agents/apps/messages/profile），不含 file/terminal/browser（归 better-sidebar）、不含 team/room（归 background-agents）。
2026-09-04 17:14:22 +08:00
parent c319fb106e
commit 0e91e99f49
19 changed files with 5838 additions and 0 deletions
@@ -0,0 +1,362 @@
+# apes-sidebar 重写方案（v2）— 冲突检查通过，从零开始
+
+> 目标：重写现有 `apes-sidebar`（v0.4.0，单文件手写 JS client bundle），
+> **代码规范/工程方案学习 [DSH-better-sidebar v0.18.0](https://github.com/omdsh-dev/DSH-better-sidebar)**，
+> **需求功能/交互能力学习 [tutti-os/tutti](https://github.com/tutti-os/tutti)**。
+>
+> 分析基线：DSH-better-sidebar `v0.18.0`（浅克隆 /tmp/DSH-better-sidebar）· Tutti（本地 /Users/figmarlite/Desktop/…/APES/tutti）
+> 生成时间：2026-09-03 · 用途：重构开工前对齐，供评审与拆单。
+
+## 0. 冲突检查结论（2026-09-03）
+
+**目标自洽，不冲突，无需推翻重规划。** 两个参考源互补：
+- better-sidebar v0.18.0 = 「怎么建」（工程规范/构建/测试/i18n/token/服务契约）
+- tutti-os/tutti = 「做什么」（面板模型/角标/agent 可编程驱动）
+
+三处主动调整（借"从零开始"授权做干净化）：
+1. **Tab id 换前缀**：旧 `wb:*` → 新 `apes:*`（apes:tasks / apes:agents / apes:apps / apes:messages / apes:profile），不留 `wb` 历史包袱。
+2. **定位收敛**：只做 **tasks/agents/apps/messages/profile** 五面板信息层；files/terminal/browser/editor 由 better-sidebar 宿主提供，**不重复造轮子**（复用 `openTab/openFile` + 宿主内置 tab 即可）。
+3. **放弃团队房间**：tutti 的 rooms/team 依赖 `dsh-background-agents` 0.7.x，与 DSH 基座 loader id 冲突会崩（历史教训），v2 不做。
+
+唯一硬约束：peer 钉 `@deepseek-ai/cordis ^4.0.2` + `dsh-better-sidebar ^0.18.0`（better-sidebar 发 npm `next` dist-tag，随 DSH rc.x 漂移；升级前必须跑挂载冒烟）。
+
+---
+
+## 1. 现状诊断（旧版 v0.4.0 的痛点）
+
+### 1.1 现状结构
+
+```
+figmar/apes-sidebar (v0.4.0)
+├── package.json       # peer: cordis ^4.0.1 / better-sidebar ^0.16.0 / react 18
+├── cordis.patch.yml   # insert apes-sidebar（双挂载守卫）
+├── lib/index.js       # host 最小入口（~1KB，只打日志）
+└── lib/client.js      # 45KB 单文件，window.__ModuleLoader__.load 手写 bundle
+                       # 纯 JS + React.createElement，无 JSX/TS/构建/测试
+```
+
+注册 4 个 Tab（全部基于 better-sidebar `ctx.betterSidebar.registerTab`）：
+
+| Tab id | 作用 | 参照 |
+|---|---|---|
+| `wb:tasks` | 工作区+时间分组会话列表、搜索、运行中徽标、运行中任务区 | WorkBuddy |
+| `wb:agents` | 子代理/后台 agent 列表、状态、一键跳转 | Tutti multi-agent |
+| `wb:apps` | 应用中心（Design/PPT/Video 网格） | Tutti App Center |
+| `wb:profile` | Provider/模型信息 + 设置/帮助入口 | WorkBuddy 底部 |
+
+配置：better-sidebar 设置页 `pluginSettings['apes-sidebar']`（`enableTasks`/`enableAgents`/`enableApps`/`enableProfile`/`displayName`/`showTime`/`showUngrouped`/`appsList`）。
+
+### 1.2 主要痛点
+
+1. **单文件 45KB 手写 JS bundle**：无类型、无模块拆分、无构建产物管理；
+   CSS 以字符串内联注入（`APPS_CSS` 拼接），每次改样式要手工编辑字符串。
+2. **零测试**：无 spec，无 CI 挂载冒烟——任何 API 漂移（如 DSH rc 升级）静默崩。
+3. **i18n 手写**：本地 zh/en 两字典，不跟随宿主 `ctx.locale`，第三方语言直接缺。
+4. **皮肤脆弱**：CSS 硬编码 `#fff` 渐变等（`card-icon` 用 `#3370ff→#7c3aed`），不消费
+   `--dsw-alias-*` token 链，深色/浅色/品牌换肤会破。
+5. **状态模型简单**：轮询/快照读取 sessions/workspaces，无订阅模型、无 memo、无懒加载。
+6. **无 host 能力**：只有日志入口。需要 host 路由（读会话日志、子代理拓扑、job 回放）
+   时只能绕 DSH 网关或放弃。
+7. **版本基线落后**：peer 只到 better-sidebar ^0.16.0；而 better-sidebar v0.18.0
+   已毕业正式版、只支持 DSH 0.1.2-rc.1+（协议、RPC 方言、client store 均大变）。
+
+---
+
+## 2. 参考源 A：DSH-better-sidebar v0.18.0 工程规范（「怎么建」）
+
+### 2.1 包结构（published npm package）
+
+- `name: dsh-better-sidebar` / `version: 0.18.0` / `type: module` / `pnpm@11.8.0`
+- `main: lib/index.js`；exports 子路径：`.` / `./invariant` / `./client` / `./client/service` / `./client/api` / `./src/*` / `./package.json`
+- `dsh.bundle.patch: ./cordis.patch.yml`（bundle 激活的**硬性资格**）
+- `dsh.client.inject`: `[locale, ui-slots, ui-conversation, modules]`，`platform: web`
+- `dsh.plugin.json`：市场 manifest 形态（id/version/main/engines.dsh/contributes/client.main）
+- `files`: lib + src + cordis.patch.yml + scripts + README
+
+### 2.2 构建与质量
+
+- `build`: `tsc -p tsconfig.build.json && tsdown`（类型声明 + JS 产物）
+- `typecheck` / `test`（vitest） / `lint:ts`（oxlint） / `playwright`（e2e）
+- **懒加载 chunk**：重依赖（xterm/CodeMirror/mermaid）独立 bundle `lib/client-<name>.js`，
+  经 `/sidebar/bundle` 按需下发、`globalThis.__dshChunks__` 物化（`src/client/chunk-loader.ts`）；
+  核心 bundle 禁止静态 import chunks。
+- **CI 挂载冒烟**（`plugin-mount` job）：`pnpm pack` → scratch profile 真实安装 →
+  `dsh web`（keyless）→ Playwright 断言 `[data-dsh-better-sidebar]` 挂载、无 pageerror、
+  + 菜单逐 tab 打开、editor chunk 强制加载。本地：`pnpm build && pnpm pack && pnpm test:mount`。
+
+### 2.3 仓库硬约束（AGENTS.md）
+
+- 禁止修改 DSH 源码（零写入 `~/.dsh/source/current`）；改动必须 PR（`feat/*`/`fix/*`）。
+- 挂载只走 `cordis.patch.yml` + profile；**不反向侵入 DSH**。
+- 市场约束：`dependencies/peerDependencies/optionalDependencies` **一律不得出现 `cordis`**；
+  `scripts` 不得含 `preinstall/install/postinstall/prepare`（`tests/market-manifest.spec.ts` 守护）。
+- 缺能力时用 DSH 现成只读/公开 API 或插件自有路由（如 jobs.output 事件回放），不改 DSH。
+
+### 2.4 架构：host half + client half
+
+**host half（Node 侧，`src/index.ts` ~1300 行）**
+- 导出 `export const name = 'dsh-better-sidebar'`、`inject = ['webServer','sessions','webRuntime','tools']`、`export function apply(ctx)`。
+- 插件自有路由全走同源 fence：`/sidebar/api/*`（JSON：fs.tree/search/read/write、git.*、session.cwd、
+  changes.ops…）、`/sidebar/file`（媒体）、`/sidebar/html`（预览）、`/sidebar/bundle`（懒加载）、
+  `/sidebar/ws/*`（终端 WebSocket upgrade）。
+- **信任围栏** `trust-fence.ts`：与 /api 网关同源（Host-header loopback / webRuntime trustedHosts），
+  逐请求读取；**路径安全** `path-security.ts`：会话 cwd 内解析、workspaceFence 守卫、写路径原子写（tmp+rename）。
+- 会话隔离：所有请求带 sessionId，权威 cwd 来自 session store（header → client cwd → persistence → process.cwd 四级回退）。
+- PTY 管理：`pty-manager.ts` + `agent-pty.ts`（agent 终端注册表、resize gate、按会话配额）。
+- 工具注册：`registerTools`（agent 可调用）、`agent-opens.ts`（agent 主动开 tab 的 registry + open tool）。
+
+**client half（浏览器侧，`src/client/index.tsx` ~446 行）**
+- `inject = ['slots','sessions','locale','modules','connection']`
+- `attachLocale(ctx.locale)` + `ctx.effect` 注册词典（zh/en 为主，第三语言走 better-locale 可选覆盖）。
+- `createSidebarStore()` 单例 per activation → `ctx.provide('betterSidebar', service)`。
+- `ctx.effect(() => registerBuiltins(ctx, service))`：内置 7 tab + 6 viewer **自己吃自己的狗粮**。
+- 挂载：`document.body` 追加 host div → `createRoot` 渲染 `RenderBoundary > Sidebar`；
+  bodyObserver 防宿主移除；几何自检防页面 transform 漂移（degraded viewport sync）。
+- 拦截层：turn-tail 拦截、open-path 拦截（`remote.session.openWorkspacePath` 遮蔽）、外链拦截
+  （urlTarget 认领，默认 browser tab）、**IME 守卫**（composition 键防第三方 UI 抢键）。
+- 设置面：`ctx.slots.inject('settings.section', …)` 声明「Side card」设置分区。
+
+### 2.5 服务契约（消费插件 API，也是 apes-sidebar 重写后要面向的基座）
+
+`ctx.betterSidebar`（client-only）：
+
+```ts
+registerTab(descriptor: TabDescriptor): () => void   // 返回 disposer，HMR-safe
+registerFileViewer(descriptor: FileViewerDescriptor): () => void
+getTabs() / getFileViewers() / getTab(id)
+isTabEnabled(id) / isViewerEnabled(id)
+matchFileViewer(path, head?)
+openTab(seed: OpenTabSeed, scope?) / closeTab(tabId, scope?)
+openFile(scope, path, title?)
+updateTab / activateTab
+subscribe(listener) / getSnapshot() / subscribeState(listener)
+```
+
+`TabDescriptor` 关键字段（v0.18.0 全量）：
+
+```ts
+interface TabDescriptor {
+  id: string
+  title: string | (() => string)
+  icon?: ReactNode | ((size: number) => ReactNode)
+  order?: number                 // + 菜单排序，默认 100
+  hidden?: boolean
+  available?: (ctx, scope, state) => boolean   // + 菜单禁用谓词
+  single?: boolean               // 单实例（dedupeKey: () => id 语法糖）
+  dedupeKey?: (tab) => string | undefined
+  createTab?: (state) => { tab, patch? } | null  // 自定义 mint tab id
+  urlTarget?: (url: URL) => boolean            // 外链认领
+  settings?: SidebarSettingsDeclaration        // toggles / pluginToggles / render
+  badge?: (ctx, scope, state) => string | number | null | undefined  // Tab 角标
+  onOpen? / onActivate? / onClose?              // 生命周期（仅 service 路径触发）
+  component: (props: TabComponentProps) => ReactNode
+}
+```
+
+声明式设置：`'switch' | 'text' | 'number' | 'select'`；select 支持 `multi` 与图标选项卡。
+`TabComponentProps = { ctx, store, scope, tab, visible, expanded?, revealed?, onToggleDir?/onOpenFile?/… }`。
+
+**接入规范（外部插件视角）**：
+- peerDependencies: `@deepseek-ai/cordis` + `dsh-better-sidebar`（optional）；
+  type-only import 触发 `declare module '@deepseek-ai/cordis'` 类型合并；
+- 纯浏览器插件走 `import type {} from 'dsh-better-sidebar/client/service'`（零 Node 依赖图）；
+- client half `inject: ['betterSidebar', …]`，`ctx.effect(() => ctx.betterSidebar.registerTab(...))`；
+- 宿主 half 无此服务——需要读状态走 better-sidebar 自己的 HTTP/WS 路由。
+
+### 2.6 i18n / 皮肤 / 无障碍规范
+
+- i18n：词典注册到 DSH `ctx.locale`（LOCALE_NS）；新增 zh key 必须同步 ja（否则 ja 回退 en）；
+  渲染 MarkdownText 必须经 `markdownTextProps()`（labels 嵌套契约）。
+- 皮肤：**视觉值只消费 `--dsw-alias-*` / `--dsw-font-*` / `--ds-*` 令牌**，无硬编码颜色；
+  硬编码 hex 只能做 token 链末端 fallback（`color:var(--x,#fff)`），并有 `tests/theme.spec.ts` 守护。
+- a11y：role=tablist/tab/separator、aria-selected/valuenow、focus-visible ring、IME guard。
+
+---
+
+## 3. 参考源 B：Tutti 侧边栏能力（「做什么」）
+
+### 3.1 面板模型（packages/agent/gui/workbench/tool-sidebar/model.ts）
+
+```ts
+export const agentToolPanelIds = ['files','terminal','browser','tasks','apps','messages','side'] as const
+```
+
+- 每面板有 label、可开多实例（resourceId 区分，如 browser tab 带 agent session id）。
+- 每面板默认/最小/最大宽度（files 最大不限、side 默认 440 最大 600、其余默认 720/最小 420）。
+- `mainContentMinWidth = 280`：主内容区最小宽度保护。
+
+### 3.2 行为层（AgentToolSidebar.tsx + useAgentToolSidebarController）
+
+- **多标签**：TabBar（role=tablist），每个 tab = panel + resourceId；关闭/激活/拖拽。
+- **可编程 handle**（AgentToolSidebarHandle，agent/宿主可驱动）：
+  `addPanel / ensurePanel / openPanel / closeTab / close / collapseForContainerConstraint`
+- **容器约束自动折叠**：`shouldAutoCollapseAgentToolSidebar({containerWidth, mainContentMinWidth, sidebarWidth})`
+  → 窗口变窄时 `collapseForContainerConstraint()`（不关 tab，只收起到 Dock）。
+- **宽度记忆 + 动画**：`onLayoutWidthChange`、resize handle（键盘可操作 role=separator）、
+  width transition 260ms。
+- **懒挂载渲染**：`contentReadyTabIds` + `renderLoading`（未就绪 tab 显示 loading，就绪才挂）。
+- **空态 Picker**：`isEmptySidebar` → AgentToolSidebarPicker（从 + 菜单选面板）。
+- **展开态**：expand 按钮让活动面板撑满（expanded panel 概念）。
+
+### 3.3 信息架构与角标（StandaloneAgentToolSidebar.tsx）
+
+- `panels` 条件组装：`side` 面板仅在有 side conversation identity 时出现（`canAdd: false`）。
+- `quickActionPanels`: 有自动化 browser 时把 browser 提到 quick action；常驻 tasks/apps/messages。
+- `reminders`（角标计数）：
+  - `browser: automationBrowserCount`（运行中 automation browser tab 数）
+  - `messages: messageCenterWorkingCount`（工作会话中 working agent 消费者计数，订阅 sessionEngine）
+- 对应旧版 apes-sidebar 的 badge 概念：tasks 徽标 = 运行中会话数；agents 徽标 = 运行子代理数。
+
+### 3.4 各面板承载（渲染层职责划分）
+
+| 面板 | 承载 | apes-sidebar 对应/借鉴 |
+|---|---|---|
+| files | 文件树/编辑器 | （better-sidebar 已有 editor）不重复 |
+| terminal | 终端 | （better-sidebar 已有）不重复 |
+| browser | 内嵌浏览器 | （better-sidebar 已有）不重复 |
+| tasks | Issue Manager/任务编排 | **apes:wb:tasks 升级对象**：会话/任务拓扑 |
+| apps | App Center | **apes:wb:apps 对齐对象**：应用网格+调起 |
+| messages | 消息中心（审批/通知/后台工作汇总） | **apes 可新增 wb:messages** |
+| side | Side Conversation（子会话并排） | 子代理会话展示可借鉴 |
+
+Tutti 其余值得迁移的交互：控制中心（一个视图看所有 agent 对话+待审批+运行任务）、
+goal→tasks 自动拆分、@ 深度引用、task 分配给人/agent。
+
+### 3.5 进程/事件模型
+
+- 会话与活动数据经 `sessionEngine`/activity 服务订阅（`subscribe + getSnapshot` 模式，
+  即 React 19 `useSyncExternalStore` 形状）——ape-sidebar 应把「轮询」升级为订阅 + memo。
+- 子代理/后台工作 → `subagent-live-route` / jobs 回放（better-sidebar 已实现：
+  `jobs-routes.ts` 从会话事件日志回放 job 输出、`subagent-live-route.ts` 批量子代理状态）。
+
+---
+
+## 4. apes-sidebar v2 目标架构
+
+### 4.1 定位
+
+> **apes-sidebar v2 = 构建在 better-sidebar v0.18.0 之上的「工作空间指挥层」**，
+> 不重复 files/terminal/browser/editor（better-sidebar 已有），聚焦 Tutti 风格
+> **任务 / Agent / 消息 / 应用**四类信息面板 + host 侧路由与 agent 可编程驱动。
+
+仍是一个 **client-half 注册型插件**（注册到 `ctx.betterSidebar`），但工程规范全面对齐 better-sidebar。
+
+### 4.2 目标仓库布局
+
+```
+apes-sidebar/
+├── package.json               # peer: @deepseek-ai/cordis ^4.0.2 / dsh-better-sidebar ^0.18.0 / react ^18
+├── cordis.patch.yml           # insert apes-sidebar（双挂载守卫，抄 v0.18.0 写法）
+├── tsconfig.json / tsconfig.build.json
+├── tsdown.config.ts           # 多产物：lib/index.js + lib/client.js + lib/client-<chunk>.js
+├── vitest.config.ts / playwright.config.ts
+├── scripts/e2e-mount.sh       # scratch profile 真实挂载冒烟
+├── AGENTS.md                  # 仓库硬约束（参照 better-sidebar）
+├── src/
+│   ├── index.ts               # host half：路由 + 工具（若需要）
+│   ├── context-types.ts       # declare module '@deepseek-ai/cordis' 类型合并
+│   ├── client/
+│   │   ├── index.tsx          # apply()：attachLocale → 注册词典 → registerTabs
+│   │   ├── locales.ts         # zh/en（跟随 ctx.locale）
+│   │   ├── api.ts             # 插件自有路由 client
+│   │   ├── tabs/
+│   │   │   ├── TasksTab.tsx     # 会话/任务导航（保留 wb:tasks id 兼容持久化）
+│   │   │   ├── AgentsTab.tsx    # Agent/子代理拓扑（wb:agents）
+│   │   │   ├── AppsTab.tsx      # 应用中心（wb:apps）
+│   │   │   ├── MessagesTab.tsx  # （新）消息中心/审批汇总
+│   │   │   └── ProfileTab.tsx   # 底部用户区（wb:profile）
+│   │   └── builtins.ts         # 统一注册（吃自己的狗粮）
+│   └── (host routes 需要时) sidechat-routes.ts / subagent-routes.ts
+└── tests/
+    ├── tabs.spec.tsx / theme.spec.ts / market-manifest.spec.ts
+    └── e2e/mount.e2e.ts
+```
+
+### 4.3 关键工程决策
+
+1. **TS + tsdown 双产物**：lib/index.js（host）、lib/client.js（client 入口）、
+   chunks 按需（若引入 mermaid/图表等重依赖）；`files` 白名单发布。
+2. **client inject 精简**：只声明实际 require 的宿主包
+   （`@deepseek-ai/dsh-client-ui-primitives` + 服务注入 betterSidebar/sessions/workspaces/locale 经 cordis inject，不塞 dsh.client.inject）。
+3. **host half 保持最小**：纯展示可无 host；需要会话日志回放/子代理状态时新增
+   better-sidebar 风格的自有路由（同源 fence + 会话隔离），不碰 DSH 源码。
+4. **Tab id 向后兼容**：`wb:tasks` / `wb:agents` / `wb:apps` / `wb:profile` 保持不变
+   （避免破坏已持久化 pluginToggles / 用户布局）；样式 data 属性带 `apes-sidebar-` 前缀。
+5. **配置迁移到声明式 settings**：沿用 `pluginToggles`（switch/select）机制，
+   在 better-sidebar 设置页渲染；新增 `displayName` select（apes-sidebar/feyOS/自定义）。
+6. **i18n 对齐**：词典注册 `ctx.locale`（zh/en）；新增 key 同步第三方语言或做 en 回退。
+7. **皮肤对齐**：全部视觉消费 `--dsw-alias-*`/`--ds-*` token，硬编码 hex 仅作链尾 fallback。
+8. **badge/reminders 对齐 Tutti**：TasksTab 徽标 = 运行中会话/任务数；AgentsTab 徽标 =
+   运行子代理数（订阅 sessionEngine 而非轮询）。若可经 host 路由读 agent consumer counts，
+   则消息中心徽标 = working count（对应 Tutti messageCenterWorkingCount）。
+9. **懒挂载**：未激活 tab 不渲染内容；首次打开再挂（contentReady + loading），
+   与 better-sidebar TabContent 行为一致。
+10. **测试门禁**：至少 tabs 注册/开关/渲染 smoke + 挂载 e2e + 皮肤 token 守护 +
+    market manifest 守护（cordis 不得出现在 dependencies）。
+
+---
+
+## 5. 功能清单（Tutti → apes-sidebar 映射）
+
+| # | 能力 | Tutti 参照 | apes-sidebar v2 落地 | 优先级 |
+|---|---|---|---|---|
+| F1 | 会话/任务导航（工作区+时间分组、搜索、运行徽标） | Tasks | `wb:tasks` 升级：订阅式 + 运行中任务区 + 拓扑 | P0 |
+| F2 | Agent 总览（子代理/后台 agent、状态、跳转） | multi-agent | `wb:agents` 升级：订阅式、subagent lineage | P0 |
+| F3 | 应用中心（已装应用网格 + 调起） | App Center | `wb:apps`：appsList 可配置、viewId 调起多级降级 | P0 |
+| F4 | 消息中心/审批/工作汇总（角标） | messages + messageCenterWorkingCount | `wb:messages`（新） | P1 |
+| F5 | 任务自动拆分（goal→tasks） | Tutti goal 编排 | 规划：输入目标→子任务草稿→一键建会话（DSH 能力内简化版） | P2 |
+| F6 | 显示名/开关/子设置 | — | 声明式 settings（pluginToggles） | P0 |
+| F7 | agent 可编程开 tab | AgentToolSidebarHandle | host route + better-sidebar openTab/openFile 组合 | P1 |
+| F8 | 自动折叠/宽度记忆 | shouldAutoCollapseAgentToolSidebar | 交 better-sidebar 容器（若支持）或本地监听 | P2 |
+| F9 | Profile 用户区 | — | `wb:profile`：模型/provider/连接状态 | P0 |
+| F10 | 深色/浅色/换肤 | skin tokens | 全 token 化 | P0 |
+
+---
+
+## 6. 分阶段实施
+
+### Phase 0：工程骨架（0.5d）
+- 建仓、tsconfig/tsdown/vitest/playwright、package.json（peer 钉 cordis ^4.0.2 + better-sidebar ^0.18.0）
+- cordis.patch.yml（v0.18.0 守卫写法）、AGENTS.md、最小 host+client 空注册冒烟
+- 通过 `pnpm test:mount` 在 scratch profile 验证挂载
+
+### Phase 1：4 Tab 平移 + 质量化（1-1.5d）
+- 把旧 client.js 的 4 视图用 TSX 重写，行为不变（保留 wb:* id）
+- i18n → ctx.locale、皮肤 → token、样式 → CSS modules
+- 配置 → pluginToggles 声明式
+- 单测：注册数/开关/渲染/badge
+
+### Phase 2：Tutti 能力增强（2-3d）
+- `wb:tasks`：订阅式 sessionEngine 快照 + 运行中任务区（子代理拓扑优先排序）
+- `wb:agents`：subagent lineage + 状态订阅
+- 新增 `wb:messages`（若 host 有 working count 数据源）
+- agent 可编程开 tab（F7）最小实现
+
+### Phase 3：打磨与发布（1d）
+- 皮肤 token 全检、a11y、IME guard、错误边界
+- e2e 挂载冒烟入 CI、Gitea 发布 + npm 发版脚本
+
+---
+
+## 7. 验证清单（每个 Phase 完成时）
+
+```bash
+pnpm typecheck
+pnpm test            # vitest 单测
+pnpm lint:ts
+pnpm build && pnpm pack
+pnpm test:mount      # scratch profile 真实挂载（需 dsh + playwright chromium）
+# 真机：dsh plugin --profile desktop add file:<tarball>  → 硬刷新 → + 菜单见新 tab
+```
+
+---
+
+## 8. 风险与注意
+
+- **DSH rc 漂移**：better-sidebar 是 0.1.2-rc.1 线，DSH 官方 rc.x 发 next dist-tag；
+  重写期间锁定 devDeps peer，升级前跑 `pnpm peers check`。
+- **不要装 dsh-background-agents 0.7.x**：与 DSH 基座 loader 条目 id 冲突 → 启动崩溃
+  （历史教训），团队房间类能力暂缓。
+- **apps 调起无公开一键 API**：维持多级防御（uiConversation.activateView → slots.set → 提示）。
+- **client 纯模块表**：运行时只能 require react/react-dom/primitives 等宿主提供模块；
+  其余依赖必须内联或走懒加载 chunk，否则构建纯度门会拦。