better-dsh 0.2.3 → 0.2.4

package/docs/60_exploration-and-research/cordis-research.md

@@ -1,350 +0,0 @@
-# Cordis 框架研究
-
-> 记录：2026-08-21 · 一手核验：vendored `@deepseek-ai/cordis` 4.x（本地 4.0.1）源码 +
-> `github.com/cordiverse/cordis`（6770★）+ `github.com/cordiverse/paper`（2532★）+
-> dsh 官方 docs（`master` @ 2026-08-19）+ dsh `vendor/README.md`。
-> 本文是 Cordis 单侧研究（与 Dash 解耦后的文档；Dash 侧见 `dash-research.md`）。
-
----
-
-## 1. 总览与时空可组合性
-
-### 一句话
-
-**Cordis 是"时空可组合性的元框架"（A Meta-Framework of Spatiotemporal Composability）**：
-一个 TypeScript 插件框架，把经典类型论的 *effect/coeffect* 对偶落成两套运行时机制——
-**可逆效应（Revertible Effects，时间维）** 与 **反应式余效应（Reactive Coeffects，空间维）**，
-使插件"插得上也拔得下、依赖变化自动激活/停用"，全程免重启进程。
-
-### 血统与时间线
-
-- 作者 **Shigma（施一凡）**，Koishi 聊天机器人框架作者（2020-01 首版）。2023 年已写
-  《可逆的插件系统》设计文（koishi.chat cookbook）——论文雏形，非学术论文。
-- **2026-08-13**：论文 + dsh 开源同日。论文 *A Programming Paradigm for Spatiotemporal
-  Composability*，DeepSeek × 北大，88 页，`github.com/cordiverse/paper`（"Draft of August
-  13, 2026"，active revision）。
-- `Cordis` = 拉丁语"心"；Koishi 的一切都从 Cordis 开始。全程先工程后理论，DeepSeek 参与
-  是 2026 年的事。
-
-### 理论支柱：effect / coeffect 对偶 → 运行时机制
-
-| 维度 | 论文概念 | 工程语义 | 解决的问题 |
-|---|---|---|---|
-| **时间维** | **Revertible Effects** | 每次上下文修改配显式逆函数，叠成撤销链；卸载时反向执行 | 插件"插得上拔不下"（状态残留、伤及运行中组件） |
-| **空间维** | **Reactive Coeffects** | 组件声明依赖 → 自动拓扑编排；依赖齐→ACTIVE，缺→INACTIVE；提供者撤走→依赖者先停；回归→自动恢复 | 补丁式依赖维护 / 循环依赖 / 手写编排代码 |
-
-并统一 effect context 与 coeffect context 为**单一 context 类型**（这即"编程范式"），再组合成
-**component（组件）**，给出**动态组合的演算**，其元理论把时空可组合性从单组件推广到整个
-交错组件系统。
-
-### 作为代码的实现（源码级取证）
-
-核心包 9 个源文件（`context/service/fiber/events/registry/reflect/logger/utils/index`，
-**实测 2693 行**）。四个构件落地时空可组合性：
-
-- **`Context`** = 运行时代理（proxy）：属性读取走服务解析器（`ctx.tools`/`ctx.llm` 由服务名
-  解析，非 import 具体实现）。`extend()`/`isolate()`/`intercept()` 创建作用域子 context。
-- **`Fiber`** = 一个插件应用的运行时。持有 `_disposables`（DisposableList）、`inject`（依赖
-  声明）、`store`（已解析实现）、`state`（FiberState）、`epoch`（依赖满足度签名）。
-  - **时间维** `Fiber.effect(execute, label)`：`execute` 立即执行，产出 disposer 被收集；
-    disposer 被调 **或** fiber 卸载时，disposers **逆注册序（LIFO）** 执行（
-    `disposables.splice(0).reverse()`）。
-  - **空间维** `inject` + `_checkImpl` + `_refresh` + `epoch`：遍历每个依赖，任一缺失 →
-    `epoch=INACTIVE` → `_unload()`（停用）；全部存在 → `epoch=':uid:uid...'` → `_reload()`
-    （激活）；**提供者 fiber uid 变化** → epoch 变化 → 依赖者先 unload 再 reload。
-- **`Service`** = 服务基类：构造函数 `super(ctx, name)` 即 `ctx.reflect.provide(...)` 注册，
-  随所属 fiber 卸载自动注销。
-- **`EventsService`** = 事件总线，五种派发模式 `emit/parallel/serial/bail/waterfall`
-  （waterfall 是 around-middleware，`next()` 委派、不调则短路）。
-
-### 生产验证与自认局限
-
-Koishi：4 年、4000+ 社区插件、作者互不相识，唯一协调机制 = 反应式余效应；切存储后端 /
-重连 IM 适配器时仅依赖变化的插件重激活。论文自认局限：仅 Koishi 一生态验证、仅 TS 单语言
-数据、无与其他替代架构的直接对比。
-
----
-
-## 2. 非特权核心（No Privileged Core）
-
-### 你的理解的校验（逐点）
-
-你的 mental model 基本正确，有两处需要精确化：
-
-> "基底 binary 可以看作一个入口"
-
-✅ 精确。`dsh` 这个 binary 是 `apps/cli` 产出的 `lib/bin.js`，官方自述为 **"a thin
-self-executing composition"**（薄的自执行组合）——它只做一件事：调 `dsh-app-boot` 的
-`boot()`。
-
-> "核心自己自举（bootstrap）为一个 plugin"
-
-⚠️ 半对。**框架基底（Context + reflect/registry/events/logger 四服务）不是 plugin，它就是
-框架本身**——不是"自举成 plugin"，而是"进程里那个被 `new Context()` 造出来的根容器"。
-真正被"自举/挂载"的是 **App 的插件树**（dsh 的 ~195 个插件），它们经 Loader 从
-`dsh-base` 的 `cordis.patch.yml` 逐行 insert 到根 context 上。
-
-> "如果你基于 Cordis 写了另一个 plugin，让它自举为一个核心也是可以的"
-
-✅ 对，且措辞可更准：你不是"写一个 plugin 当核心"，而是**写一个 Cordis App（一个插件树 +
-一个薄 bin）**，它与 Dash 地位完全平等。Dash 只是"基于 Cordis 的 App 特例"。
-
-> "Dash 第一个自举的 plugin 就成了核心"
-
-⚠️ 需要修正。**没有"第一个插件成为核心"这回事**。"no privileged core" 的准确含义是：
-**框架之外没有任何硬编码的、不可替换的模块**。看起来像"核心"的东西（`session`/
-`system-prompt`/`tools`/`agent`/`agent-loop` 这六件"脊柱"）**全是 `dsh-base` 的
-`cordis.patch.yml` 里的普通插件行**，可被上层 patch 按 id 整行替换。所谓"核心"只是
-"恰好提供了别人 inject 的基础服务的那个插件"，并非特权位。
-
-### Bootstrap 链（源码取证）
-
-```
-dsh 二进制（lib/bin.js，薄壳）
-  └─ boot(binName, configPath, ...)         # dsh-app-boot
-       ├─ new Context()                     # 根容器（框架基底，非 plugin）
-       ├─ 注册 cordis:include + cordis:group builtins
-       ├─ 安装 Loader
-       ├─ mountRootInclude(...)             # 挂载 cordis.yml 配置树
-       │    └─ 逐层叠加：bundle patch 层 → profile patch → home patch → --patch
-       │         └─ 每行 = 一个 plugin（含 dsh-base 的 agent-loop 等"核心"）
-       ├─ assertEntriesLoaded / Activated    # 全部解析/激活，否则 fail loud
-       └─ 返回根 Context
-```
-
-**关键证据**：`dsh-app-boot` 的 `boot()` 注释明言 "Create the root context, install Loader,
-... mount and await the include tree ... return the root context"。核心（框架）与 App
-（插件树）的边界就在 `new Context()` 这一行：它之上全是可 patch 的插件，它本身才是唯一的
-"内核"。
-
----
-
-## 3. 架构结构测绘
-
-### Monorepo 包结构（`cordiverse/cordis`，9 包）
-
-```
-cordis/
-└── packages/
-    ├── core/            → 发布为 `cordis`：Context/Fiber/Service/Events/Registry/Reflect/Logger
-    ├── loader/          → `@cordisjs/plugin-loader`：声明式配置加载（YAML/JSON 行 → 插件树）
-    ├── include/         → `@cordisjs/plugin-include`：配置子树挂载 + `!!js` 表达式
-    ├── hmr/             → `@cordisjs/plugin-hmr`：热模块替换（保存 → 仅重应用该插件）
-    ├── group/           → `@cordisjs/plugin-group`：插件分组（isolate realm）
-    ├── timer/           → `@cordisjs/plugin-timer`：定时服务
-    ├── create/          → 脚手架（Node 22+）
-    ├── logger-console/  → 控制台日志后端
-    └── utils/           → 共享工具
-```
-
-### 核心组件与关系
-
-```mermaid
-flowchart TD
-    C["Context<br/>运行时 proxy"] --> RF["ReflectService<br/>provide/inject 服务解析器"]
-    C --> RG["RegistryService<br/>plugin 注册 + Inject"]
-    C --> EV["EventsService<br/>emit/parallel/serial/bail/waterfall"]
-    C --> LG["LoggerService"]
-    RG -->|"ctx.plugin() → Fiber"| F["Fiber<br/>一个插件实例的运行时"]
-    RF -->|"super(ctx,name) 注册"| S["Service<br/>服务基类"]
-    S -->|"随 fiber 卸载自动注销"| F
-    F -->|"effect() 收集 disposer → 逆序撤销（时间维）"| UT["utils / DisposableList"]
-    F -->|"inject + epoch → 激活/停用（空间维）"| RF
-    L["loader<br/>import() 模块 → ctx.registry.plugin"] --> RG
-    I["include<br/>配置子树挂载"] --> L
-    H["hmr<br/>热重载"] --> F
-```
-
----
-
-## 4. 开发语言与打包编译
-
-### 4.1 进程内约束（TS-only，Node ESM）
-
-- `cordis/package.json`：`"type": "module"`、`"main": "lib/index.js"`；依赖仅
-  `@standard-schema/spec` + `cosmokit`——**零 native addon、零 WASM、零 child_process**。
-- 插件入口只有三种形状：`Function(ctx, config)` / `Constructor` / `Object{apply}`，必须求值
-  为 JS 可调用对象。
-- 插件加载：`tree.import(specifier)` → `unwrapExports()` → `ctx.registry.plugin(...)`。
-  `ModuleFormat = 'builtin'|'commonjs'|'json'|'module'|'wasm'`（仅 Node loader 格式）。
-
-### 4.2 打包编译引擎：能否换成 Bun
-
-**结论：Cordis 核心（零 native 依赖）可 trivial 编译成 Bun 单文件可执行；dsh 全量表面
-"可行但有工程成本"，不是"被卡死"。Claude Code 就是现成先例。**
-
-| 项 | Bun 支持 | 说明 |
-|---|---|---|
-| `bun build --compile` 单文件可执行 | ✅ | 内嵌 Bun 运行时，客户端无需装 Node；`--target=bun-linux-x64` 交叉编译 |
-| `node:child_process`（spawn/PTY） | ✅ | 全支持 |
-| `node:worker_threads` | ✅（小缺口） | postMessage/SharedArrayBuffer 支持；resourceLimits/execArgv 部分 |
-| `node-pty`（native addon） | ❌ | 历史性坏（oven-sh/bun#7362）；Bun 官方替代 = **Bun.Terminal**（v1.3.5 起） |
-| `node-addon-landlock-run`（N-API） | ⚠️ | N-API 可加载，但 `.node` 须**静态 require + 逐 target 预编译**才能嵌入 `--compile` |
-| tsdown（Rolldown+Oxc） | ⚠️ | 是 Rolldown+Oxc（非 esbuild）；Bun 下运行是 experimental，跑 bundler 需 Node 22+ |
-
-**Claude Code 先例（前提确认为真）**：Anthropic 自 ~v2.1.113 起把 Claude Code 以
-**Bun 编译的 standalone 原生二进制**发布（`curl`/brew/winget 装的就是它；npm 包只是下载并
-链接同一二进制的 wrapper，运行时不碰 Node）。**Anthropic 2025-12 收购了 Bun**，部分原因就是
-Claude Code 以这种方式 ship。所以"用 Bun 预编译 + 直接 ship binary"不是假设，是存在证明。
-
-**推荐落地路径**（与 Claude Code 一致）：**195 个 npm 包继续用 tsdown 在 Node CI 构建
-（不动），只在最终 app 装配 + 编译阶段用 `bun build --compile`**。硬阻塞只有两个：
-`node-pty` → 换 `Bun.Terminal`；`node-addon-landlock-run` → 逐 OS/arch 预编译并静态 require。
-
----
-
-## 5. 异构代码衔接层（Hetero-Language Bridge）
-
-### 结论：官方**已经实现**了"异构语言成为插件模块"，形式 = 进程边界 + IPC 桥
-
-你对"其实是不是 subprocess 倒无所谓，只要逻辑层自洽、实现无感"的判断是对的——Cordis 的
-"everything is plugin" 抽象**确实自洽**：从 Cordis 视角看，`PythonCodeRuntime` 就是一个
-普通 Service provider；它内部 spawn 一个 Python 子进程、用 fd3 桥接，是藏在 `ctx.codeRuntime`
-缝隙背后的实现细节，消费者无感。
-
-### 官方实现（`dsh-code-runtime-python` 的 fd3 帧协议）
-
-仓库里**真实实现**（非 stub）：`packages/code-runtime/code-runtime-python/`（`src/index.ts`
-+ `py/protocol.py` + e2e tests）。机制：
-
-- 每个 model program 跑在**全新 `python3 -I` 子进程**里；`stdio: [pipe, pipe, pipe, pipe]`
-  的第 4 项 = **fd 3**，作为 framed-JSON 通道；stdout/stderr 留给程序自己的输出。
-- **帧 = fd 3 上的 JSON-lines**（每行一个 JSON 对象）。子→宿主：`boot-ack`/`call`/`log`/
-  `done`；宿主→子：`boot`（首帧）/`run`（`boot-ack` 后）/每 `call` 一个 `reply`。
-- **宿主把每帧都当敌对输入**（`validateChildFrame` 逐字段校验 + 重建）：model 代码对 fd 3
-  有完全访问权、可伪造任意帧，所以进站的 forged 字段被丢弃、非有限 call id 不会回显。
-- **无损 JSON codec**（无 `JSON.stringify` 深度限制；迭代遍历；超安全整数走 `BigInt`；
-  字节计量），保证 `CodeJsonValue` 深度无界也能过线。
-- `py/protocol.py` 是 TS `src/protocol.ts` 的镜像：`TypedDict` 形状 + `PROTOCOL_FD = 3` +
-  `log_truncation_marker`（**字节级一致**）；`protocol-mirror.e2e.ts` 起真实 `python3` 断言
-  两侧字段名/必填性不漂移（曾因 round-12 三次字段漂移而加此守卫）。
-
-TS 侧 `src/index.ts` 把 `PythonCodeRuntime` 注册为 `ctx.codeRuntime` 的 provider——**这就是
-"Python 成为 Cordis 插件"的官方答案：TS 宿主侧插件 + 外语子进程 + fd3 JSON-lines IPC**。
-
-### 全部异构缝隙（进程边界是唯一的跨语言方式）
-
-| 缝隙 | 协议 | 边界 | 可达语言 |
-|---|---|---|---|
-| `ctx.subprocess`（subprocess-local） | stdio + 进程组 | `node:child_process`+node-pty | 任意可执行 |
-| `ctx.shell`（bash/pwsh-local） | `bash -c`/pwsh | 出进程 | 任意命令 |
-| `dsh-mcp-client` | MCP = JSON-RPC 2.0（stdio / Streamable HTTP） | 出进程/远程 | 语言无关（Python MCP SDK 成熟） |
-| `ctx.codeRuntime`（code-runtime-python） | fd3 framed-JSON-lines | Python 子进程 | Python |
-| `dsh-sandbox`/`fs-sandbox`/`bash-sandbox` | 策略包装 subprocess/fs | 出进程 | 底层缝隙可达的任意语言 |
-| `dsh-typert-*` | Typert RPC 装饰器 + endpoint registry | 进程内 TS 反射 | 仅 TS |
-
-> 注意：默认 `web` profile 只 bundle `dsh-code-runtime-worker-thread`（TS 后端）；Python 后端
-> 在仓库里但不随默认 profile 发布，需显式安装。
-
----
-
-## 6. Rust 重写
-
-### 结论：核心重写**已有人做完**；但"Rust Cordis 兼容纯 TS 插件"不是进程内可行的，"万能"的
-真相是"TS 插件变成又一种异构语言桥"
-
-- **Cordis 源码量**：核心实测 **2693 行** TS（9 文件）；上游仓库总 2590 KB（含 docs/tests）。
-- **`cordis-rs` 已经存在**（`docs.rs/cordis-rs`）：`@deepseek-ai/cordis` 4.x 的 Rust 移植，
-  证明**原生核心（作用域 DI / 生命周期拥有的效应 / Fiber 状态机 / 事件总线 / registry /
-  reflect / logger）能干净地移植到 Rust**。Rust 插件走 `plugin_sync`/`plugin_async`，无 JS 引擎。
-- **异构语言插件**：当前最佳实践 = **WASM Component Model（wasmtime + WIT/bindgen）**；
-  **Extism** 作为便捷多语言 PDK 层（Rust/Python/Go/JS/TS/C#/Zig/C/C++）。
-- **"兼容纯 TS Cordis 插件"的真相**：**进程内不现实**。现有 Cordis/dsh 插件是 Node 程序
-  （`node:child_process`/`worker_threads`/`node-pty` native addon/ESM import `cordis`/ctx proxy/
-  inject epoch/热重载）。**没有任何嵌入式 JS 引擎**能提供这套 Node 面——`deno_core`(V8) 默认
-  无 Node built-ins；QuickJS/Boa 无 Node API；Extism JS PDK（QuickJS-ng in WASM）明确无
-  事件循环/`child_process`/Worker/fs/net、sync-per-export。因此纯 TS 插件必须**在真实
-  Node/Bun 运行时里出进程跑，走 RPC 桥**——即第 5 节的同一种异构桥，恰好是"又多一种插件类型"。
-
-| 机制 | 跨语言 | 能跑现有 JS 插件？ | 先例 |
-|---|---|---|---|
-| 原生 Rust 核心（cordis-rs） | 仅 Rust | ❌ | cordis-rs（已 ship） |
-| WASM Component Model（wasmtime） | ✅（WIT 多语言） | ❌ | wasmtime 生态 |
-| Extism PDK | ✅（Rust/Py/Go/JS/C#...） | ❌（JS PDK 无 Node 面） | Extism |
-| 嵌入式 V8（deno_core）/QuickJS/Boa | 仅 JS 子集 | ⚠️ 须重实现 `cordis` + ctx proxy + inject epoch | 无先例 |
-| **出进程 Node/Bun + RPC 桥** | ✅（任意语言） | ✅（真实 Node/Bun 跑 TS 插件） | 第 5 节 fd3 / MCP |
-
-**诚实成本**：原生核心 8–15k LOC / 4–8 周达到对等；**JS 互操作是真正耗时数月的硬层**
-（要么在嵌入式引擎里重实现 Node API 面——无先例，`napi-rs` 是反方向；要么让响应式
-inject-epoch 语义跨进程边界保持一致）。所以正确的心智模型不是"Rust 版 Cordis 万能兼容 TS"，
-而是 **原生 Rust 核心 + TS 插件作为又一种异构语言类型（出进程 Node/Bun + 桥）**。
-
----
-
-## 7. 进程内框架与 Recursive Cordis
-
-### 7.1 进程内框架的含义（承接你未完成的 1.5）
-
-Cordis 是**单进程内**的框架：`Context` 是一个进程内的 proxy，服务解析、事件派发、效应撤销
-全部在内存中。这意味着**一切跨进程/跨机器的组合都必须显式引入 IPC**——Cordis 自己不提供
-"远程 context 镜像"（把一个远程进程的服务透明地当作本地 `inject` 到的服务）。
-
-### 7.2 Recursive Cordis：include 子树 vs alien-binary + IPC 融合
-
-你说的两种方案，可行性截然不同：
-
-**(a) include 子树（直接加载 Dash 插件）——原生、零 IPC、已实现。**
-Cordis Multica 作为唯一基底启动 `new Context()`，用 `cordis:include` 把 Dash 的 agent 运行时
-插件直接挂到同一根 context 下（`dsh-app-boot` 的 `mountRootInclude` + dsh 自己 per-session
-preset 机制就是同一机制）。Dash 自己的 Cordis 基座**不启动**，Dash 插件直接挂在 Multica 下。
-**这就是你说的"直接加载 Dash plugin 就行"——正确，这是默认该走的路。**
-
-**(b) alien-binary-plugin（启动一个完整 Dash）+ IPC 融合——可行但"融合"是净新增工作。**
-"写一个 plugin 去 spawn 一个完整 Dash binary"本身**trivial**：一个 inject `ctx.subprocess` 的
-插件即可。但难点在**"IPC 间的 Cordis 融合"**——把两个 Cordis context 的服务/事件在进程边界
-上桥接起来。**Cordis 没有现成的跨进程 context 桥**：dsh 的跨进程原语（`dsh-sdk-jsonrpc-server`
-/sdk-client、`dsh-acp`、`dsh-api-remotes`/api-gateway）暴露的是**一个面**（如 agent 面），不是
-**context 本身**（任意服务/事件）。所以：
-
-- "大家都是 Cordis，IPC 更容易"在**语义层**成立（共享事件/服务词汇，设计桥时有共同语言）；
-- 在**机制层**不成立：桥本身是净新增，官方未 ship。
-
-**判定**：两条路不矛盾。默认走 (a)（零 IPC、原生、已实现）；(b) 只在"必须让一个完整 Dash
-独立成进程/独立沙箱/独立升级"时才有意义，且要自建 context-bridge 协议（可复用 sdk/acp/
-typert 原语）。当前阶段 (b) 是研究级工作，不是免费午餐。
-
----
-
-## 8. 同类竞品调研
-
-真正**同时**达到时间维（运行时保证的逆函数撤销）+ 空间维（响应式依赖自动激活/停用）的，
-只有 **Cordis、其直系祖先 Koishi、经典对手 OSGi**。
-
-| 框架 | 语言 | 时间维 | 空间维 | 免重启卸载 |
-|---|---|---|---|---|
-| **Cordis** | TS | ✅ `Fiber.effect()` LIFO 撤销 | ✅ `inject`+epoch | ✅ |
-| **Koishi** | TS | ✅ `fork.dispose()` 逆序撤销 | ✅ 服务 DI | ✅ 热重载 |
-| **OSGi + DS** | Java | ✅* bundle stop + `@Deactivate` | ✅ DS `bind/unbind/reconfigure` | ✅ |
-| Effect-TS | TS | ✅ Scope/LIFO finalizers | ❌ 无响应式服务激活 | 部分 |
-| VS Code Extension Host | TS | ❌ 手动 dispose，无法原地重置 | ❌ activation 一次性 | ❌ 须宿主重载 |
-| Inversify / NestJS / Angular | TS | ❌ OnDestroy 是 shutdown 语义 | ❌ 容器图静态 | ❌ |
-| Spring（core） | Java | ❌ Spring-DM 已移除 | ❌ `@RefreshScope` 非响应式激活 | ❌ |
-| .NET（MEF/Autofac） | C# | 部分（程序集无法卸载） | 部分 recomposition | ❌ 须 AppDomain |
-| Umzug（迁移） | JS | ✅* 仅时间维（up/down） | ❌ | N/A |
-| webpack/Tapable、Rollup、esbuild | JS | N/A 构建期 | ❌ | N/A |
-
-**判定**：OSGi 是 Cordis 之前唯一同构的双支柱系统（且免重启卸载）；Cordis 的差异化不在
-"有没有"而在**严谨度 + 人体工学**——每个 ctx 变更都带运行时追踪的逆函数、逆序重放（路径无关/
-合流性），OSGi 的 `deactivate()` 可靠但依赖作者纪律。Koishi 是直系祖先。Effect-TS 只到时间维；
-VS Code 是论文要反对的反例；Nest/Angular/Inversify/Spring/MEF 是空间维或 teardown-only；
-Umzug 是相邻的时间维-only；bundler 是构建期。**Cordis 的主张在"类"上不唯一，但在托管语言里
-是形式化根基最干净、免重启实现最彻底的一个。**
-
----
-
-## 来源
-
-- `github.com/cordiverse/cordis`（TypeScript/MIT，`packages/{core,create,group,hmr,include,
-  loader,logger-console,timer,utils}`）
-- `github.com/cordiverse/paper` —— *A Programming Paradigm for Spatiotemporal Composability*
-  （Draft 2026-08-13）
-- dsh 仓库 `vendor/README.md`（vendored 清单 + 18 项本地修改 + sync 流程）、
-  `packages/boot/app-boot/README.md`（bootstrap）、
-  `.agents/notes/.../2026-07-31-code-runtime-python-fd3-protocol.md` + `py/protocol.py`（fd3）
-- Vendored 源码 `~/.dsh/profiles/node_modules/@deepseek-ai/cordis/src/*.ts`（@4.0.1，实测 2693 行）
-- Bun 官方 docs（`bun build --compile` / Node-API / Bun.Terminal）、`anthropic.com/news/
-  anthropic-acquires-bun`、Claude Code quickstart
-- `docs.rs/cordis-rs`、`arroyo.dev/blog/rust-plugin-systems`、`extism.org`、`wasmtime`、
-  `deno_core` / `rquickjs` / `Boa`、`tartanllama.xyz/posts/wasm-plugins`
-- 竞品：OSGi Core Spec 9.0、`github.com/koishijs/koishi`、Effect v3 Scope、VS Code extension
-  anatomy

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 服务端）。