better-dsh 0.0.0 → 0.2.2-b

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

@@ -0,0 +1,350 @@
+# 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-mobile-spa-ios-input-experience-research.md

@@ -0,0 +1,160 @@
+# DSH Web UI 移动端（iOS Safari）输入体验研究 — focus 放大 / 键盘遮蔽（v2）
+
+- 日期：2026-09-03（v1 初稿；v2 同日晚修订，含 TypingMind 逆向实录与裁决更新）
+- 范围：DSH Web UI（`upstream/deepseek-harness` checkout，tag `dsh-v0.1.2-alpha.5`）在 iOS Safari 上的输入体验。**遵 user 2026-09-03 裁决：只解决 ①focus 放大、②虚拟键盘遮挡两个问题；左栏挤压会话区（原 D4）no-go** —— 那是框架级问题，改它是无底洞；侧栏弹出时内容完整即可，隐藏侧栏后自然回到会话区，挤压是暂时性的，由它去。
+- 参照物：typingmind.com（逆向实录见 §2）；上游源码逐行取证；WebKit Bugzilla 现状核查（2026-09-03）。
+- 关联：`docs/50_test-reports/v0.2.1f-plugin-shipped-ui-patches实测报告.md`（手势/mobile CSS 已发布态）、`ios-chat-app-bridge-research.md`（native 壳路线）。逆向工作产物：`work/typingmind-re/`（case: `work/typingmind-web-re`，reverse-skill offline-sample）。
+
+---
+
+## 0. 结论（TL;DR）
+
+两个目标问题全部可在 better-dsh 插件内闭环，**零上游改动**。v2 关键更新：
+
+1. **16px 论据已从"推断"升级为"实测"**：TypingMind 聊天输入框 **手机 16px / 桌面 14px**（CDP 活体测量，§2.3）—— 它不是"字体小也没事"，而是刻意在手机端维持 16px、桌面才降到 14px（Tailwind `text-base sm:text-sm`）。你看它"字也不大"是桌面印象。
+2. **行业存在两条正路**（§3.2）：A) 移动端字号地板 16px（TypingMind 现行）；B) JS 在 iOS 窄屏把 `user-scalable` 翻成 `no`（**iOS 10+ 并不禁双指缩放，只杀 focus 自动放大**；Discourse 曾用 A 后整体迁移到 B，原因是 A 的视觉膨胀）。DSH 选 A/B/A+B 是待讨论的决策点。
+3. **键盘问题存在两层事实**（§3.3）：浏览器内 Safari = 键盘 overlay 无 opt-out（WebKit 259770 仍 NEW），必须 visualViewport shim；**PWA standalone 态 = 引擎原生 resize（innerHeight/dvh 随键盘收缩）**，无需 shim —— 这就是 TypingMind 零键盘代码的原因（它的推荐移动形态是 PWA）。DSH manifest 已是 fullscreen，"推荐 PWA + 保留浏览器内 shim"可作组合策略。
+4. **动态岛假设有真实对应物但不是本症状的机制**（§4）：WebKit 300523（iOS 26.0 仅动态岛机型，键盘关闭/滚动后 viewport 上移数像素侵入安全区，26.1 beta 已修，应用侧无法绕过）—— 证明"动态岛参与 viewport 计算出错"这类 bug 存在，但其症状是**几像素上移**，不是 120% 宽度放大；放大是 font-size 机制（16/14≈1.14 起步，与观察值吻合）。
+
+---
+
+## 1. 症状与根因（v1 取证维持有效，摘要）
+
+### D1 — focus/JS 定位输入框 → 页面放大到 115–120%
+
+- viewport：`apps/web/index.html:5` = `width=device-width, initial-scale=1`，全仓无 `maximum-scale`/`user-scalable` 处理。
+- 字号：composer `.card { font-size: var(--dsh-content-font-size, 14px) }`（`InputBar.module.css:55`，`.input` 继承；contenteditable 锚点 `[data-composer-input]`）；`--dsh-content-font-size` 由 `ui-theme/src/boot-theme.ts:21` 写 body，**默认 14px**；permission/model 原生 `<select>` 13px。全仓可聚焦控件 13–14px，全部低于 iOS 16px 阈值 → focus 必放大。16/14 ≈ 1.14，与观察到的 115–120% 吻合。
+
+### D2 — 键盘弹出时页面不上推，input 被 overlay 遮住
+
+- WebKit 未实现 `interactive-widget`（[bug 259770](https://bugs.webkit.org/show_bug.cgi?id=259770)，2026-09-03 核查仍 NEW/P2/Nobody）→ iOS 浏览器内键盘 overlay layout viewport，无 opt-out。
+- DSH 布局：`html/body/#root {height:100%}`（`client/web/src/base.css:6`）+ `.frame` grid overflow hidden，composer 在文档流底部 → Safari 只做不可控 page pan，经常 pan 不到位。
+- 唯一引擎 API：`window.visualViewport`（`resize`/`scroll` + `height`/`offsetTop`/`scale`）。`100dvh` 无济于事（响应工具栏不响应键盘）。
+
+### D3 — 切会话自动 focus（D1+D2 的连锁触发器，保留在方案内待裁决）
+
+`InputBar.tsx` unlock effect：`useEffect(..., [locked, sessionId, editor])` → `editor.getRootElement()?.focus()` —— 注释原文 "Unlock (mount / session switch) returns focus to the box"。切会话/首载 hero 必触发程序化聚焦 = 无人请求的键盘 + 放大。桌面这是特性（键盘用户续打），移动端是 bug。**user 裁决聚焦两症状，D3 正是两症状在"切会话"场景的共同触发层**，修它属于两症状的修复范围，但是否要"移动端切会话后不聚焦"仍留作决策点（§6）。
+
+### ~~D4 — 左栏挤压~~（no-go，user 2026-09-03 裁决）
+
+不再处理。机制留档备查：`narrowExpanded` 仅跨 1024 断点清除；`computeColumns` sidebar 永不让步（`SIDEBAR_MIN=264`），center 吸收全部赤字。v1 里的 M4（点击 treeitem 自动收栏）随之撤销。
+
+---
+
+## 2. TypingMind 逆向实录（2026-09-03，work/typingmind-re）
+
+### 2.1 分发形态定性：无 DMG，现行 = PWA only
+
+官方 install 文档（docs.typingmind.com/install-typingmind-app）明示安装方式 = **PWA**：桌面 Chrome/Edge 地址栏安装图标、iOS Safari Add to Home Screen，"No app store, no download required"。历史上的 macOS app（changelog "MacOS app v1.15.0"，Setapp 渠道）已非现行分发。GitHub `typingmind/typingmind` 是 issue/docs 门面，应用本体闭源。**结论：web bundle（typingmind.com 的 Next.js chunks + PWA 全家桶）就是完整 app package** —— 逆向它 = 逆向完整应用。
+
+### 2.2 静态扫描（149 个 JS chunk ≈11MB + 4 个 CSS，样本 tarball 已存 case）
+
+| 检索 | 结果 |
+|---|---|
+| `visualViewport` | 仅 1 处，Floating UI 定位库内部偏移计算 —— **无键盘 shim** |
+| `maximum-scale` / `user-scalable` / viewport 改写 | **无**（JS 与 CSS 均零命中） |
+| `fontSize:"16px"` JS | 2 处 = Prism 代码高亮主题（噪音） |
+| `safe-area-inset` | **真实使用**：CSS `env(safe-area-inset-bottom/left/right)`；JS 侧 workspace bar 高度 `calc(58px + env(safe-area-inset-bottom))`（chunk 3a4r…）—— 标准全面屏适配通道 |
+| "dynamic island"/"notch" | 零真实命中（唯一 "notch" 是用户评价文案） |
+| 表单基线 | Tailwind Forms 全局：`[type=text],…,textarea,select { font-size:1rem }` = 16px（无 html 根字号覆写） |
+| PWA | manifest `display:standalone`；全套 iPhone/iPad splash；`apple-mobile-web-app-capable` |
+
+### 2.3 活体测量（CDP 双宽度，google-chrome --remote-debugging-port + Node 22 原生 WebSocket，`Emulation.setDeviceMetricsOverride`）
+
+主输入框 `<textarea id="chat-input-textbox">`，类名含 `text-base ... sm:text-sm`：
+
+| viewport | computed font-size（#chat-input-textbox） | 机制 |
+|---|---|---|
+| 390×844（手机） | **16px** | `text-base`（1rem）生效 |
+| 1280×900（桌面） | **14px** | `sm:text-sm`（≥640px 才降档） |
+
+同页实测：viewport meta 活体值 `initial-scale=1, viewport-fit=cover`；搜索框 16px；根字号 16px（未覆写）。
+
+**结论：TypingMind 对 focus 放大的对策 = 手机端输入面 16px（Tailwind 响应式降档手法）+ 不动 viewport meta + 无任何 JS 键盘/缩放处理。** 它的移动端键盘体验依赖 PWA standalone 的引擎原生行为（§3.3）。
+
+### 2.4 行业演化旁证：Discourse PR #30877
+
+Discourse 曾实现方案 A：`--font-size-ios-input: max(1em, 16px)`（其注释原话 "inputs/textareas in iOS need to be at least 16px to avoid triggering zoom on focus"），后整体替换为方案 B：iOS 上 JS 把 `user-scalable=yes` 翻成 `no`，注释原话："**In iOS Safari, setting user-scalable=no doesn't actually prevent the user from zooming in. But, it does prevent the annoying 'auto zoom' when focussing input fields with small font-sizes.**" —— 迁移动机是 A 造成输入框视觉膨胀。两条路都被大型产品实证有效。
+
+---
+
+## 3. 机制结论与充要性（v2 修正）
+
+### 3.1 放大机制的准确表述
+
+iOS Safari（默认配置）在 `initial-scale=1` 且未禁缩放时，对 computed font-size **< 16px** 的可聚焦控件（input/select/textarea/contenteditable）在 focus 时自动放大 visual viewport 至文本 ≥16px 可读级。这是充分条件级的行业共识（TypingMind 刻意工程 + Discourse 注释 + 大量社区文献），且数值与 DSH 症状吻合（14px→×1.14）。**充要性的诚实边界**：
+- 16px 在**默认 Safari 配置**下充分；非绝对必要（maximum-scale/user-scalable=no 亦阻断）。
+- 例外残存：用户系统级辅助功能（更大文本、Safari 每站 Page Zoom 设置）可抬高实际阈值或残留缩放；`<select>` 聚焦在个别 iOS 版本有独立报告（如 SO #64076385 "not prevented with 16px"，403 未能取全文，标题即反例存在性证明）。**这恰是 A+B 双保险的理由**（§6 决策点 1）。
+
+### 3.2 方案空间（放大问题）
+
+| 方案 | 手段 | 代价 | 先例 |
+|---|---|---|---|
+| **A 字号地板** | 窄屏 CSS：`[data-composer-input],[data-composer-placeholder],input,select,textarea { font-size: max(16px, var(--dsh-content-font-size,14px)) }` | 输入面视觉变大（13/14→16px）；对字号偏好用户保序 | TypingMind 现行；Discourse v1 |
+| **B 禁缩放标记** | 窄屏 JS 改写 viewport meta 追加 `maximum-scale=1, user-scalable=no` | iOS 10+ **不禁双指缩放**（Discourse 注释实证），只杀 focus 自动放大；桌面/Android 不动 | Discourse v2（现行） |
+| A+B | 地板兜字义，标记兜例外 | 叠加 | —— |
+
+B 的实现要点：只在 narrow + touch 检测下改写（避免桌面与 Android 误伤），boot script 早期执行（先于任何 focus）。
+
+### 3.3 键盘机制的两层事实（v2 关键更新）
+
+- **浏览器内 Safari**：键盘 overlay，无 opt-out（259770），必须 `visualViewport` shim（v1 M2 方案维持）：`intrusion = innerHeight − visualViewport.height`，>阈值且 `scale≈1` 时以 `--dashr-vvh` 收缩 `#root` + `scrollTo(0,0)` 抗 pan。
+- **PWA standalone（Add to Home Screen）**：dev.to 2026-07 实测文（iOS 17/18）：键盘弹出时 **`window.innerHeight`、`visualViewport.height`、`100dvh` 全部收缩**（引擎原生 resize，等价 `resizes-content`），`interactive-widget` 在 standalone 被忽略。已知 bug：**键盘关闭后 viewport 卡在小尺寸不恢复**（直到杀进程）；社区解法 = blur 后 140ms 对全高元素做 `display:none→reflow→restore` 翻转强制重测（配 backdrop-filter 遮罩隐藏闪跳）。**TypingMind 零键盘代码成立的原因 = 其推荐移动形态是 PWA standalone**。DSH 的 manifest 已是 `display:fullscreen`，具备同路线条件。
+- 策略组合（待讨论）：浏览器内 Safari 用户 → M2 shim；PWA 用户 → 引擎原生 + 可选 viewport-stuck 自愈；是否把"装成 PWA"作为官方推荐移动用法（对齐 typingmind）是产品决策点（§6 决策点 3）。
+
+---
+
+## 4. 动态岛假设验证（user 2026-09-03 提出方向）
+
+**方向部分成立 —— 动态岛确实参与了一类真实 viewport bug，但不是本症状的机制：**
+
+- [WebKit bug 300523](https://bugs.webkit.org/show_bug.cgi?id=300523)（REGRESSION, iOS 26.0，iPhone 15 Pro 实测 100% 复现，非动态岛机型 iPhone 13 Pro Max iOS 18 不复现）：键盘关闭或滚动/重渲染后，Safari **错误计算 visual viewport 高度，内容上移数像素侵入动态岛安全区**（fixed/sticky 头部漂移）。`viewport-fit=cover/contain`、`env(safe-area-inset-top)` padding、visualViewport JS 重算**均无法绕过**；Simon Fraser 确认 iOS 26.1 beta 已修。
+- 该 bug 的症状是**纵向几像素漂移**，不是横向 115–120% 放大，且只在 iOS 26.0 存在（26.1 已修）。DSH 若在 iOS 26.0 真机观察到顶栏上漂数像素，即此 bug，升级即愈，应用侧无动作空间。
+- **机制结论**：布局视口宽度由 viewport meta 决定（390pt 机型 = 390 CSS px），动态岛裁剪通过 `env(safe-area-inset-*)` 暴露、不改变布局宽度与缩放比；"focus 后重新拿 2000px 物理高度再按旧比例放大"无证据支持（按此假设放大应与焦点控件字号无关，而 TypingMind 16px 输入框在同一机型上不放大 —— 反证）。**120% 放大维持 font-size 机制定性**；动态岛类 bug 作为独立 bug class 记录在案。
+
+---
+
+## 5. 实现方案（v2，全部 better-dsh 插件增量，零上游改动；待批准后动工）
+
+配置通道沿用 `__DASHR_MOBILE__`（`web-trust.ts` boot script）扩键：`zoomGuard: 'font' | 'meta' | 'both' | 'off'`（默认待裁决）、`keyboardShim: true`、`focusGate: true`（若裁决保留 D3 修复）。
+
+- **M1 放大防护**（对应 §3.2 A/B，二选一或叠加，boot script 装 B、claimStyles 装 A）。
+- **M2 浏览器内键盘 shim**（§3.3；visualViewport → `--dashr-vvh` 收缩 `#root`；阈值 + scale guard + rAF 合帧）。
+- **M2b standalone viewport 自愈**（可选）：blur 后 display-flip 重测，防 PWA 态卡小 viewport。
+- **M3 focus gate**（D3 触发层，裁决点 2）：boot script 包 `HTMLElement.prototype.focus`，只拦窄屏 `[data-composer-input]` 的非用户发起聚焦（pointerdown 在 `[data-composer-card]`/弹层内放行）。若裁决"移动端切会话保留自动聚焦"，则 M3 撤销，症状由 M1+M2 兜底（键盘弹出但可见、不放大）。
+- ~~M4 自动收左栏~~ —— **撤销**（D4 no-go）。
+
+桌面零影响（全部 narrow-gated）；验证计划维持 v1 §5（4999 预演 + client spec + 真机 iOS 清单），真机清单新增：iOS 26.0 顶栏上漂观察项（对照 300523）、PWA standalone 态键盘 + 卡死自愈验证。
+
+---
+
+## 6. 待讨论决策点（user 明确先讨论后开发）
+
+1. **放大防护选型**：A（字号地板，视觉变大）/ B（user-scalable=no 标记，iOS 10+ 不禁双指）/ A+B 双保险。倾向建议：**B 为主 + A 只保 composer**（B 零视觉扰动且 Discourse 实证；composer 16px 同时改善手机可读性）——待你裁决。
+2. **切会话自动聚焦（D3）**：移动端是否取消？（取消 = 切会话后纯净阅读态；保留 = 现状行为，靠 M1+M2 兜底症状。）
+3. **移动端官方形态**：是否把"Add to Home Screen（PWA standalone）"作为推荐用法（键盘问题在引擎层消失，对齐 typingmind 路线）？浏览器内 Safari 用户仍由 M2 覆盖。
+4. M2b（standalone 卡死自愈）是否纳入首版。
+
+## 7. 证据索引（v2 增补）
+
+| 事实 | 位置/来源 |
+|---|---|
+| TypingMind 分发 = PWA only（无 DMG） | docs.typingmind.com/install-typingmind-app（2026-09-03） |
+| 输入框 16px@390 / 14px@1280（实测） | CDP 活体测量，脚本 `work/typingmind-re/measure.mjs`，样本 `work/typingmind-re/typingmind-web-bundle.tar.gz` |
+| Tailwind Forms 基线 1rem=16px | 其 CSS chunk（case 存档） |
+| 无键盘 shim / 无 viewport 改写 | bundle 全量 grep（case 存档） |
+| safe-area = env() 标准通道 | 其 CSS + chunk 3a4r…（case 存档） |
+| Discourse A→B 迁移及 B 不禁双指缩放 | Discourse PR #30877 diff（注释原话） |
+| standalone PWA 键盘 resize + 卡死 bug + display-flip 自愈 | dev.to/cederhook 2026-07（iOS 17/18 实测） |
+| 动态岛 viewport bug（上移数像素，26.1 修） | WebKit bug 300523 |
+| 浏览器内无 interactive-widget | WebKit bug 259770（仍 NEW/Nobody） |
+| DSH 侧全部源码锚点 | 见 v1 §6（`apps/web/index.html:5`、`InputBar.module.css:55`、`boot-theme.ts:21`、`InputBar.tsx` unlock effect、`base.css:6`、`columns.ts`、`stores.ts`） |
+
+## 8. 参考文献
+
+- [WebKit Bug 259770 – interactive-widget](https://bugs.webkit.org/show_bug.cgi?id=259770) · [WebKit Bug 300523 – Dynamic Island viewport shift](https://bugs.webkit.org/show_bug.cgi?id=300523)
+- [Discourse PR #30877 – Replace font-size-ios-input workaround](https://github.com/discourse/discourse/pull/30877)
+- [Fixing the iOS standalone-PWA keyboard bug (dev.to, 2026-07)](https://dev.to/cederhook/fixing-the-ios-standalone-pwa-keyboard-bug-that-shrinks-your-viewport-for-good-63d)
+- [Chromium: viewport resize behavior](https://developer.chrome.com/blog/viewport-resize-behavior/) · [CSS Viewport §interactive-widget](https://drafts.csswg.org/css-viewport-1/#interactive-widget-section)
+- [TIL: Avoid text-sm on inputs (guidefari)](https://guidefari.com/safari-ios-input-zoom/) · [SO #64076385 – 16px 反例存在性](https://stackoverflow.com/questions/64076385/input-zoom-on-iphone-safari-not-prevented-with-16px)
+- typingmind.com（bundle/manifest/viewport 实测）；docs.typingmind.com（install 文档）