better-dsh 0.2.2-c → 0.2.3-c

package/docs/60_exploration-and-research/dsh-web-profile-package-map.md

@@ -1,186 +0,0 @@
-# DSH Web Profile 包分类测绘
-
-> 记录：2026-08-31 · 一手核验：`~/.dsh/profiles/node_modules/@deepseek-ai/`（220 包，dsh-alpha
-> 4.x 全量）+ `~/workspaces/dsh-alpha/packages/` 源码（client 各包 src import 逐文件 grep）。
-> 范围：Web Profile（含 headless-only 包一并列出，但标注为"非 Web"）。
-
----
-
-## 1. 一句话结论
-
-**DSH Web 的依赖不是一条干净的"核心 → 中间层 → UI"三层管道，而是"双轨"：**
-
-- **运行时数据**走干净的管道：`核心(service) → 中间层(api-controller RPC) → UI`。
-- **类型**却是**双轨旁路**：UI 层**跳过中间层，直接 import 底层核心的类型**
-  （`dsh-session/types`、`dsh-llm`、`dsh-agent`、`dsh-scope`）。
-
-**量化证据**：40 个 `dsh-client-ui-*` 包里，**17 个直接 import 底层核心**（session/llm/agent/scope），
-共约 70 个文件；其中 `ui-conversation`、`ui-chat` 各 14 个文件。这是"UI 直接 import 底层"的铁证。
-
----
-
-## 2. 数据流验证（你问的核心问题）
-
-### 2.1 UI 直接 import 底层核心（跳过中间层）
-
-```
-ui-conversation:    14 文件
-ui-chat:            14 文件
-ui-workspace:        5 文件
-ui-workflow-run:     3 文件
-ui-trajectory:       3 文件
-ui-subagent:         3 文件
-ui-input-trigger:    3 文件
-ui-message-feedback: 2 文件
-ui-goal:             2 文件
-ui-commands:         2 文件
-+ 7 个包各 1 文件（session / skill / plan / model-selection / deliverables / approval / user-questions）
-```
-
-具体例子（`ui-session/src/client/index.ts`）：
-
-```ts
-import type { SessionId } from '@deepseek-ai/dsh-session/types'   // 直接 import 底层
-import type {} from '@deepseek-ai/dsh-api-session-controller/client'  // 同时 import 中间层
-```
-
-### 2.2 判定
-
-**是，UI 层既走中间层（拿运行时数据），又跳过中间层（拿类型）。** 两条轨：
-
-| 轨 | 路径 | 内容 |
-|---|---|---|
-| 数据轨 | 核心 service → api-controller → RPC → UI | 运行时数据（会话列表、transcript、模型） |
-| 类型轨 | 核心 types → UI **直接 import** | `SessionId`/`SessionEvent`/`ContentBlock` 等形状 |
-
-**这正是"UI 类型耦合在底层、不在中间层"的机制层证据**——你之前问"alias dsh-session 能不能
-只服务前端 100 行"，答案是**不能**，因为前端 17 个包、约 70 个文件直接 import 了 dsh-session/
-dsh-llm 的类型，alias 必须覆盖这些。
-
----
-
-## 3. 四层分类清单（220 包）
-
-### ① Cordis 框架底层（15）
-
-| 组 | 包 |
-|---|---|
-| 框架核心 | `cordis` |
-| 框架插件 | `cordis-plugin-loader` `cordis-plugin-include` `cordis-plugin-group` `cordis-plugin-timer` `cordis-plugin-hmr` |
-| 框架配套 | `cosmokit` `schemastery` `node-addon-landlock-run` |
-| 共享基础 | `dsh-invariants` `dsh-brand` `dsh-timeout` `dsh-atomic-write` `dsh-util-crypto` `dsh-util-workspace-path` |
-
-### ② DSH 核心底层（约 140，含 headless）
-
-| 组 | 包 |
-|---|---|
-| 入口/自举 | `dsh` `dsh-base` `dsh-app-boot` `dsh-home-paths` `dsh-launch-environment` |
-| host 基建 | `dsh-host-webserver` `dsh-host-frontend-static` `dsh-host-directory-picker`(+auto/browse/native) `dsh-host-plugin-inventory` |
-| **Session（17）** | `dsh-session` `dsh-session-persistence` `dsh-session-persistence-jsonl` `dsh-session-projection` `dsh-session-projection-cache` `dsh-session-query` `dsh-session-query-sqlite` `dsh-session-title` `dsh-session-title-first-prompt-llm` `dsh-session-title-llm` `dsh-session-log-deepseek` `dsh-session-log-export` `dsh-session-stats` `dsh-session-telemetry` `dsh-session-telemetry-otel` `dsh-session-checkpoint-policy` `dsh-session-reference` |
-| **LLM（5）** | `dsh-llm` `dsh-llm-deepseek` `dsh-llm-pi-ai` `dsh-llm-retry` `dsh-deepseek-llm-api-extensions` |
-| **Agent（7）** | `dsh-agent` `dsh-agent-loop` `dsh-agent-presets` `dsh-agent-default-model` `dsh-agent-instructions` `dsh-agent-tool-presentation` `dsh-agent-spine-demo` |
-| scope/workspace | `dsh-scope` `dsh-workspace` |
-| **Tools（20）** | `dsh-tools` `dsh-tool-{ask-user,bash,bash-persistent,call-timeout-policy,cordis,fs,fs-search,goal,jobs,pwsh,pwsh-persistent,ralph,skill,str-replace-editor,subagent,subagent-control,subagent-report,todo,web,workflow}` |
-| 命令/技能 | `dsh-commands` `dsh-command-{compact,feedback,goal}` `dsh-skill` `dsh-skill-{badge,filesystem}` |
-| 子代理/子进程 | `dsh-subagent` `dsh-subagent-{fork-in-process,in-process-driver,spawn-in-process}` `dsh-subprocess` `dsh-subprocess-local` |
-| shell/sandbox/fs | `dsh-shell` `dsh-shell-env` `dsh-bash-{local,sandbox}` `dsh-pwsh-{local,sandbox}` `dsh-sandbox` `dsh-sandbox-{local,policy,windows-acl}` `dsh-fs` `dsh-fs-{local,observation-policy,sandbox}` `dsh-win32-process` |
-| code-runtime | `dsh-code-runtime` `dsh-code-runtime-worker-thread` |
-| 存储/spill/压缩 | `dsh-storage` `dsh-storage-{domain,json}` `dsh-spill` `dsh-spill-{local,policy}` `dsh-compaction` `dsh-compaction-{basic,tool-result-pruner}` |
-| jobs/attachment/credential | `dsh-jobs` `dsh-jobs-local` `dsh-attachment` `dsh-attachment-local` `dsh-credentials` `dsh-credentials-local` |
-| 权限/审批 | `dsh-permission-presets` `dsh-authorization` `dsh-user-approval` `dsh-user-questions` |
-| 消息/引用 | `dsh-message-feedback` `dsh-file-reference` `dsh-file-reference-local` |
-| goal/plan/persona/system | `dsh-goal` `dsh-goal-round-driver` `dsh-plan-mode` `dsh-persona` `dsh-system-prompt` `dsh-schedule` `dsh-time-context` `dsh-tmux-context` |
-| hooks | `dsh-hook-protocol` `dsh-hooks-claude-code` `dsh-hooks-codex` |
-| MCP/杂项 | `dsh-mcp-client` `dsh-token-meter` `dsh-output-retention` `dsh-native-command` `dsh-repeat-tool-reminder` `dsh-settings` `dsh-settings-file` `dsh-workflow` `dsh-workflow-worker-thread` `dsh-plugin-package-inventory-deepseek` |
-| *headless-only* | `dsh-headless` `dsh-cmdline` `dsh-terminal` `dsh-terminal-bash` |
-
-### ③ DSH 中间层（API/RPC 转接，约 16）
-
-| 组 | 包 |
-|---|---|
-| API BFF | `dsh-api-gateway` `dsh-api-remotes` `dsh-api-session-controller` `dsh-api-settings-controller` `dsh-api-workspace-controller` |
-| RPC 机制 | `dsh-typert-protocol` `dsh-typert-registry` `dsh-typert-loader` |
-| RPC 传输 | `dsh-client-connection` |
-| 双半 runner | `dsh-cordis-host-runner` `dsh-cordis-client-runner` |
-| ACP | `dsh-acp` `dsh-acp-app` |
-| SDK | `dsh-sdk-app` `dsh-sdk-jsonrpc-server` `dsh-sdk-minimal` `dsh-sdk-protocol` |
-
-### ④ DSH UI 层（约 50）
-
-| 组 | 包 |
-|---|---|
-| **UI 组件（40）** | `dsh-client-ui-{agent-preset,approval,attachment,brand-official,chat,commands,conversation,cordis,deliverables,directory-picker-browse,directory-picker-native,goal,input-trigger,jobs,layout,message-feedback,model-selection,permission-presets,plan,reference,renderer,session,settings,settings-general,settings-models,settings-plugin-inventory,settings-plugins,sidebar,skill,subagent,theme,tool,trajectory,user-questions,workflow-run,workspace}`（40 个） |
-| client 基建 | `dsh-client-modules` `dsh-client-locale` `dsh-client-hmr` `dsh-client-store` |
-| web 组装 | `dsh-web` `dsh-web-app` `dsh-web-frontend` |
-| web 工具 | `dsh-web-fetch-http` `dsh-web-search-deepseek` `dsh-webhook` `dsh-webhook-github` |
-
----
-
-## 4. Mermaid 分层图
-
-```mermaid
-flowchart TD
-  subgraph L1["① Cordis 框架底层"]
-    cordis["cordis"]
-    cp["cordis-plugin-loader / include / group / timer / hmr"]
-    base["cosmokit · schemastery · node-addon-landlock-run"]
-    shared["dsh-invariants · dsh-brand · dsh-timeout · dsh-atomic-write · dsh-util-*"]
-  end
-
-  subgraph L2["② DSH 核心底层"]
-    boot["dsh · dsh-base · dsh-app-boot · dsh-home-paths"]
-    host["dsh-host-webserver · host-frontend-static · host-directory-picker · host-plugin-inventory"]
-    session["dsh-session · session-persistence · session-projection · session-query · session-title · session-log · session-stats · session-telemetry"]
-    llm["dsh-llm · llm-deepseek · llm-pi-ai · llm-retry · deepseek-llm-api-extensions"]
-    agent["dsh-agent · agent-loop · agent-presets · agent-default-model · agent-instructions"]
-    scope["dsh-scope · dsh-workspace"]
-    tools["dsh-tools · dsh-tool-*（20）· dsh-command-* · dsh-skill-* · dsh-subagent-*"]
-    runtime["dsh-subprocess · shell · bash · pwsh · sandbox · fs · code-runtime · storage · spill · compaction · jobs · attachment · credentials"]
-    policy["dsh-permission-presets · authorization · user-approval · hook-protocol · mcp-client"]
-  end
-
-  subgraph L3["③ DSH 中间层（API/RPC 转接）"]
-    api["dsh-api-gateway · api-remotes · api-session-controller · api-settings-controller · api-workspace-controller"]
-    rpc["dsh-typert-protocol · typert-registry · typert-loader · client-connection"]
-    runner["dsh-cordis-host-runner · cordis-client-runner"]
-    ext["dsh-acp · acp-app · dsh-sdk-app · sdk-jsonrpc-server · sdk-protocol"]
-  end
-
-  subgraph L4["④ DSH UI 层"]
-    renderer["dsh-client-ui-renderer（SlotRegistry + React mount）"]
-    shell["dsh-client-ui-layout · sidebar · theme"]
-    chat["dsh-client-ui-chat · session · conversation · trajectory · message-feedback"]
-    model["dsh-client-ui-model-selection · agent-preset · permission-presets"]
-    ws["dsh-client-ui-workspace · goal · plan · jobs · workflow-run · deliverables"]
-    misc["dsh-client-ui-* 其余（approval · attachment · commands · reference · skill · subagent · tool · user-questions · input-trigger · settings-* · directory-picker-* · cordis · brand-official）"]
-    infra["dsh-client-modules · client-locale · client-hmr · client-store"]
-    web["dsh-web · dsh-web-app · dsh-web-frontend"]
-  end
-
-  L2 -->|"运行时数据（service → RPC）"| L3
-  L3 -->|"运行时数据（RPC → 浏览器）"| L4
-  L2 -.->|"类型直连：SessionId / SessionEvent / ContentBlock（跳过中间层，17 个 UI 包约 70 文件）"| L4
-  L1 --> L2
-```
-
----
-
-## 5. 关键发现汇总
-
-1. **不是干净三层管道**：数据走 `核心→中间层→UI`，但**类型走 `核心→UI` 旁路**。
-2. **类型耦合在底层，不在中间层**：`dsh-client-ui-session` 直接 `import { SessionId } from
-   'dsh-session/types'`，`ui-chat`/`ui-conversation` 各 14 文件直接 import dsh-session/dsh-llm。
-3. **对桥接层的意义**：要斩断 dsh-session，代价不在 api-controller（中间层），而在 UI 层那
-   ~70 个文件的类型 import——这才是真正的耦合点。
-4. **中间层（api-controller）是运行时数据的分发器**，不是类型隔离层；类型隔离在 UI 层直接
-    import 底层时就破了。
-
----
-
-## 来源
-
-- `~/.dsh/profiles/node_modules/@deepseek-ai/`：220 包清单（`ls`）+ 各包 `package.json` 的
-  `description`/`peerDependencies`/`dependencies`。
-- `~/workspaces/dsh-alpha/packages/client/`：`ui-*/src` 逐文件 grep `import ... from
-  '@deepseek-ai/dsh-(session|llm|agent|scope)'` 与 `'@deepseek-ai/dsh-api-*-controller/client'`。
-- 关联：`dsh-web-ui-slot-system-research.md`（UI 插槽机制）、`cordis-research.md`（Cordis 服务端）。

package/docs/60_exploration-and-research/dsh-web-ui-slot-system-research.md

@@ -1,310 +0,0 @@
-# dsh Web UI 前端插件系统研究
-
-> 记录：2026-08-31 · 一手核验：`~/workspaces/dsh-alpha/packages/client/` 源码 +
-> `packages/extensions/cordis-client-runner/` + vendored `@deepseek-ai/*` 4.x 编译产物
-> （`~/.dsh/profiles/node_modules/@deepseek-ai/`，220 包）。
-> 本文是 `cordis-research.md`（Cordis 服务端侧）与 `web-frontend-composability-research.md`
-> （Web 生态通用对照）的**dsh 实测侧**：回答"dsh 的 Web UI 到底是怎么把插件穿透到前端、又
-> 怎么在 React 上渲染出来的"。
-
----
-
-## 1. 一句话结论
-
-**dsh 的 Web UI 不是"React 组件库"，而是把 Cordis 原封不动地搬进了浏览器：每个
-`dsh-client-ui-*` 包是"双半插件"（服务端空 `apply()` + 浏览器端真 `apply(ctx)`），组合靠一套
-框架无关的**插槽注册表（SlotRegistry）**——一个靠 TypeScript `declare module` 声明合并出来的
-类型化 `SlotMap` 定义所有插槽契约，React 只是挂在注册表上的**一个可替换渲染后端**，状态用
-框架无关的 observable 喂给 `useSyncExternalStore`。**
-
-判定：这与服务端 Cordis 是**同一哲学的两个投影**——服务端用 `inject`/`provide` 组合 *服务*，
-前端用 `register`/`renderSlot` 组合 *组件*；两者都是"声明式 + 控制反转 + 免重启装卸"。
-
----
-
-## 2. 双半插件（dual-half）：一个包，两个编译目标
-
-每个 `dsh-client-ui-*` 插件有两个入口文件，编译成两个目标：
-
-**host 半**（服务端，空函数——只为让 Cordis Loader 有东西可加载）：
-
-```ts
-// packages/client/ui-sidebar/src/index.ts
-/** Host loader entry for the browser-only sidebar plugin. */
-/** Provides no host-side behavior. */
-export function apply(): void {}
-```
-
-**browser 半**（浏览器里真正干活）：
-
-```ts
-// packages/client/ui-sidebar/src/client/index.ts
-export const inject = ['slots', 'layout', 'uiWorkspace', 'locale']
-
-export function apply(ctx: ClientContext): void {
-  const workspaceNavigation = ctx.get('uiWorkspace')
-  ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'ui-sidebar: dictionaries')
-  const injectProps = (): SidebarRootInjected => ({
-    startSession: (workspaceId) => workspaceNavigation.startSession(workspaceId),
-    toggleSidebar: () => ctx.layout.toggleSidebar(),
-  })
-  ctx.effect(
-    () => ctx.slots.register({ name: 'sidebar', children: {...}, inject: injectProps }, SidebarRoot),
-    'ui-sidebar: slot registration',
-  )
-}
-```
-
-关键点：`client/index.ts` 的 `apply(ctx)` 里有 `inject` 数组（`['slots', 'layout', ...]`）和
-`ctx.effect(...)`——**和服务端 Cordis 插件完全一样的写法**。它跑在浏览器里，是因为下面第 8 节
-的 `dsh-cordis-client-runner` 在浏览器里又起了一套 Cordis。
-
-判定：服务端"组合服务"和前端"组合 UI"用的是**同一套心智模型**，只是换了个宿主（Node 进程 →
-浏览器页面）。
-
----
-
-## 3. 组合 = Slot：框架无关的类型化插槽注册表
-
-前端的组合**不是** React 的 props 钻孔，也不是 React Context，而是一个**纯插槽注册表**
-（`SlotCore`，无 cordis、无 React）：
-
-```ts
-// packages/client/ui-slots/src/index.ts
-export interface SlotMap {}          // 空接口，靠各插件 declare module 合并
-export interface LocaleNamespaceMap {}
-export type SlotKind = 'single' | 'list' | 'keyed' | 'chain'
-export type SlotScope = 'root' | 'session-maybe' | 'session'
-```
-
-每个插件通过 **TypeScript 声明合并** 往 `SlotMap` 上"合并"进自己的插槽名，于是**类型层面就知道
-每个插槽的契约**：
-
-```ts
-// packages/client/ui-sidebar/src/client/contract/slots.ts
-declare module '@deepseek-ai/dsh-client-ui-slots' {
-  interface SlotMap {
-    'sidebar.brand.mark': ...
-    'sidebar.brand.name': ...
-    'sidebar.workspaces': ...
-    'sidebar.settings': ...
-    'sidebar.footer.action': ...
-  }
-}
-```
-
-这与服务端 Cordis 的 `declare module '@deepseek-ai/cordis' { interface Context { slots: ... } }`
-是**同一个机制**（`ui-renderer` 就是用它把 `ctx.slots`、`ctx.uiRenderer` 合并进 cordis Context）。
-
-组合是**一棵树**：owner 注册时声明 `children`（子槽），occupant 填充别人的槽：
-
-```
-root（内置，唯一的 ctx 级槽）
-  └─ layout 区域（ui-layout 拥有，声明 'sidebar' 等区域槽）
-       └─ sidebar 壳（ui-sidebar 注册）
-            ├─ sidebar.workspaces  ← ui-workspace 填充
-            ├─ sidebar.settings    ← ui-settings 填充
-            ├─ sidebar.brand.mark  ← ui-brand 填充
-            └─ sidebar.footer.action（list 槽，多插件追加）
-```
-
-判定：**"谁声明槽"和"谁填槽"是两个正交的插件集**，靠 `SlotMap` 的类型合并保证编译期契约匹配
-——这是它比"字符串 key + `any` props"的普通插件系统（如 VS Code views）高明的地方。
-
----
-
-## 4. 插槽的两个轴：基数（kind）与作用域（scope）
-
-```ts
-type SlotKind = 'single' | 'list' | 'keyed' | 'chain'   // 单占位 / 有序列表 / 按 key 分发 / 选择器路由链
-type SlotScope = 'root' | 'session-maybe' | 'session'   // 全局 / 可选当前会话 / 严格绑定会话
-```
-
-- **kind** 决定一个槽能容纳几个 occupant、怎么分发（`single` 一个、`list` 按顺序叠加、`keyed`
-  按 key 分发、`chain` 用选择器决定路由）。
-- **scope** 决定 occupant 是否/如何拿到当前 Session（`session` 槽会被注入 `sessionId` +
-  `SessionProvider` 座，`session-maybe` 在无会话时收到 `undefined`，`root` 不接触会话）。
-
-判定：基数轴覆盖了 UI 扩展点的四种真实形态；作用域轴把"会话数据怎么流进 UI"做成了类型级约束
-（`PropsRuntime` 按 scope 收窄），而不是靠运行时约定。
-
----
-
-## 5. React 渲染：整个 App = 一个 `root` 槽
-
-这是最反直觉的一步——**整个 React 树只有一个入口**：
-
-```tsx
-// packages/client/ui-renderer/src/client/app.tsx
-export function buildRenderApp(deps): () => ReactNode {
-  const { ctx } = deps
-  return () => ctx.slots.renderSlot('root', {})   // ← 整个 app 就这一句
-}
-```
-
-```ts
-// packages/client/ui-renderer/src/client/index.ts
-export function apply(ctx: Context): void {
-  const slots = new SlotRegistry(ctx)
-  slots.install(createSlotRenderer())          // ← 把 React 渲染器装进插槽注册表
-  ctx.reflect.provide('uiRenderer', {
-    mount: (container) => {
-      const root = mountApp(container, buildRenderApp({ ctx }))  // createRoot / hydrateRoot
-      return () => root.unmount()
-    },
-  })
-}
-```
-
-`SlotRegistry` 是 cordis 侧对 `SlotCore` 的包装；`createSlotRenderer()` 是**唯一一个 React 绑定**。
-React 挂载后只渲染 `renderSlot('root')`，渲染器递归展开插槽树、找到每个槽的 occupant 渲染出来。
-
-还有一段 boot 水合细节（`mountApp`）：如果容器里已有 kernel 预渲染的 `[data-dsh-boot]` DOM，就走
-`hydrateRoot` 保活；否则 `createRoot` + `flushSync` 首帧。这是"框架无关的 boot DOM"→"React 接管"的
-交接。
-
-判定：**插槽注册表和状态都是框架中立的；React 只是"当前安装的那个渲染器"。** 理论上换一个
-渲染器（如 preact / solid）只换 `createSlotRenderer()`，插槽树和业务插件一行不用改。
-
----
-
-## 6. 每个插槽组件的 props 是"组合"出来的
-
-一个 slot 组件收到的 props 是五份的交集（`ComposedProps`）：
-
-| 份额 | 类型 | 来源 |
-|---|---|---|
-| **owner 分享** | `PropsRuntime`（`OwnerOf` + `KeyPropsOf` + scope 标准件） | 父级 `renderSlot` 调用点传的数据 |
-| **render 分享** | `PropsRenderSlots<S>` | 子插槽的 `renderSlot` 函数，**静态收窄到声明的 `children`** |
-| **store hooks** | `PropsStore` | 从 observable 源合成的 `use<Name>` 选择器 hook |
-| **locale** | `PropsLocale` | `t` 翻译函数（按命名空间收窄 key） |
-| **inject** | `InjectFace` | owner 注入的 `inject` 工厂（`hooks` 成员被转成 hook） |
-
-侧栏的 `injectProps` 就是第 5 份的实例：把 `startSession`/`toggleSidebar` 通过 `inject` 工厂塞给
-`SidebarRoot`，而 `SidebarRoot` 自己只消费 `PropsRenderSlots<'sidebar.brand.mark' | ...>` 去渲染
-它声明的 5 个子槽。
-
-判定：props 的每一份都有**编译期来源**（类型系统里能追到"谁给了什么"），不是运行时拼出来的
-黑盒。这是它能"有求必应"又"不越权"的根基——owner 只拿到自己声明的 children 的 `renderSlot`，
-occupant 只拿到 owner 声明的 `owner`/`inject` 分享。
-
----
-
-## 7. 状态 = 框架无关的 observable → useSyncExternalStore
-
-业务状态**不依赖 React**，是 `HostObservable<T>`（`getSnapshot` + `subscribe`）。React 绑定用
-`useSyncExternalStore` 把它变成 hook：
-
-```ts
-// packages/client/ui-renderer/src/client/bindings.tsx
-export function observableHook<T>(source: HostObservable<T>): SnapshotSelectorHook<T> { ... }
-export function maybeObservableHook<T>(source: HostObservable<T> | undefined) { ... }  // 缺席保持 Hook 调用顺序稳定
-export function keyedObservableHook(source: KeyedStandardSource | undefined) { ... }
-```
-
-一个 store 的 snapshot 变成组件里注入的 `use<Name>(selector)` hook（`standardHookPropName` 把源名
-`foo` 转成 `useFoo`）。`use-sync-external-store` 是为了在 React 18 里拿到并发安全的订阅。
-
-判定：**状态层是框架中立的，React 是纯渲染绑定。** 这和第 5 节同构——插槽和状态都跟框架解耦，
-所以"换渲染器"不是说说而已。
-
----
-
-## 8. 浏览器里的 Cordis + RPC 传输
-
-`dsh-cordis-client-runner`（`packages/extensions/cordis-client-runner/src/client/`）在**浏览器里再
-起一套完整 Cordis**，逐个调每个 UI 插件的 `client/index.ts` 的 `apply(ctx)`。它带齐了 cordis 的
-运行时件：`runtime.ts`、`providers.ts`、`evaluator.ts`、`guard.ts`、`timer.ts`、`slot-catalog.ts`、
-`orchestrator.ts`（页面侧的 run 编排 / 审批 / 面板手势）。
-
-浏览器 → 服务端的通信是 **WebSocket 上的 Typert RPC**：
-
-| 包 | 角色 |
-|---|---|
-| `dsh-client-connection` | 认证 RPC 传输（`ws`），生命周期管理 |
-| `dsh-api-gateway` | Typert Remote Host 分发器（`ws` + schemastery 校验） |
-| `dsh-api-remotes` | 客户端 RPC 桩（BFF 组装，会话/工作区/设置等面） |
-| `dsh-api-*-controller` | 服务端 BFF 后端（session/workspace/settings） |
-
-判定：浏览器里的 Cordis 服务通过 `inject` 拿到的是**远程能力的本地代理**（`dsh-api-remotes` 桩），
-而非直接 import 服务端实现。这条 RPC 边界就是"前端插件"和"后端服务"的分界——也是我们桥接层
-（omp-webui）要替换数据源的那条缝。
-
----
-
-## 9. 完整链路（一张图）
-
-```mermaid
-flowchart TD
-  subgraph Browser["浏览器（dsh-cordis-client-runner 再起一套 cordis）"]
-    R["ui-renderer<br/>SlotRegistry + createSlotRenderer + mount"]
-    L["ui-layout<br/>拥有 root 布局树，声明 'sidebar' 等区域槽"]
-    S["ui-sidebar<br/>注册 'sidebar' 槽 + 5 个子槽"]
-    W["ui-workspace / ui-settings<br/>填 sidebar.workspaces / sidebar.settings"]
-    C["ui-chat / ui-session / ui-conversation<br/>聊天区"]
-    T["client-connection（WS）＋ api-remotes（RPC 桩）"]
-    R -->|"ctx.slots.renderSlot('root')"| L
-    L --> S --> W
-  end
-  subgraph Host["宿主（Node cordis）"]
-    G["dsh-api-gateway（typert 分发）"]
-    A["api-session/workspace/settings controller"]
-    D["dsh-session / dsh-llm / dsh-agent（核心，供数据）"]
-    G --> A --> D
-  end
-  T -->|"WebSocket Typert RPC"| G
-```
-
----
-
-## 10. 方法论提炼：为什么这么设计
-
-把 dsh 前端这套机制抽象成三条方法论，与 Cordis 服务端一一对应：
-
-1. **组合 = 类型化的注册表，不是字符串约定。** 服务端 `declare module '@deepseek-ai/cordis'`
-   合并 `Context`；前端 `declare module '@deepseek-ai/dsh-client-ui-slots'` 合并 `SlotMap`。插槽
-   契约是编译期检查的，不是文档口头约定。
-2. **框架中立的内核 + 可替换的渲染后端。** `SlotCore`（无 cordis/React）+ observable（无 React）
-   是内核；`createSlotRenderer()` 是唯一 React 绑定。对应 Cordis 的"框架内核 + 插件树"。
-3. **双半部署。** 一个插件包编译成 host 半（空 `apply()`）+ browser 半（真逻辑），由 cordis 的
-   `cordis-client-runner` 在两端各自加载。对应 Cordis 的"同一插件在两个运行时里各有一半"。
-
-判定：这套东西的难点不在"能组合"（Web Components / MF 都能），而在**"依赖驱动的、反应式的、
-类型安全的组合"**——`web-frontend-composability-research.md` §5 说 Web 生态缺的"反应式依赖激活"，
-dsh 前端是用 **cordis 本身**补上的（浏览器里再跑一个 cordis），而不是在 DOM 层重造。
-
----
-
-## 11. 对 omp-webui 桥接层的意义
-
-这份研究直接回答了我们前几轮纠结的问题：
-
-- **"能不能只复用 UI、自己写 HTTP 服务器？"** —— 不能干净地做。UI 插件是 dual-half，它的
-  browser 半靠 `dsh-cordis-client-runner` 跑在浏览器 cordis 里、通过 `dsh-api-remotes` 的 RPC 桩
-  调服务端；UI 的"前端组件"和"后端服务"不是 REST 边界，是 Typert RPC 边界。要复用 UI 就得
-  把服务端 RPC 那半也搭起来。
-- **"我们的桥接层到底替换了哪一段？"** —— 替换的是**数据源服务**（`dsh-session-persistence`
-  → OMP 适配器、`dsh-agent-loop` → OMP provider、`dsh-agent-presets` → 单模式 roster），即第 8 节
-  RPC 链**服务端**那一侧的几个 provider。**前端插槽树、渲染器、RPC 协议一行没动。**
-- **"YAML 组合"的设想本来就存在。** 服务端是 `cordis.patch.yml`（定义加载哪些插件），前端是
-  `SlotMap` + `register`/`renderSlot`（定义 UI 怎么组合）。我们要加 UI 面板，正确做法是**注册一个
-  槽的 occupant**（`ctx.slots.register(...)`），而不是去改渲染器或重写插槽机制。
-
----
-
-## 来源
-
-- dsh-alpha 源码（`~/workspaces/dsh-alpha/packages/`）：
-  - `client/ui-sidebar/src/index.ts`（host 半空 `apply()`）、`client/ui-sidebar/src/client/index.ts`
-    （browser 半 `ctx.slots.register`）、`client/ui-sidebar/src/client/contract/slots.ts`（SlotMap 合并）
-  - `client/ui-slots/src/index.ts`（`SlotMap`/`SlotKind`/`SlotScope`/`SlotCore`）、
-    `client/ui-slots/src/renderer.ts`（框架中立契约 `SlotRendererHost`/`SlotRenderer`）
-  - `client/ui-renderer/src/client/app.tsx`（`renderSlot('root')`）、
-    `client/ui-renderer/src/client/index.ts`（`SlotRegistry` + `createSlotRenderer` + `mount`）、
-    `client/ui-renderer/src/client/bindings.tsx`（observable → `useSyncExternalStore`）
-  - `extensions/cordis-client-runner/src/client/orchestrator.ts`（浏览器 cordis 编排）
-- vendored 编译产物：`~/.dsh/profiles/node_modules/@deepseek-ai/{dsh-web-app,dsh-web-frontend,
-  dsh-cordis-client-runner,dsh-client-connection,dsh-api-gateway,dsh-api-remotes,dsh-client-ui-renderer,
-  dsh-typert-protocol}/package.json`（description + peerDependencies 取证的依赖图）
-- 关联研究：`cordis-research.md`（Cordis 服务端时空可组合性）、`web-frontend-composability-research.md`
-  （Web 生态通用对照，本文是其 dsh 实测侧）