super-dsh 0.1.12 → 0.3.0

package/node_modules/better-dsh/docs/10_plans/dashr-profile-layer-feasibility.md

@@ -0,0 +1,367 @@
+# 可行性研究：DASHR 从 Agent Preset 层上升到 Profile 层
+
+> 日期：2026-08-16 · 类型：纯可行性研究（不干预开发、不改 v0.5 蓝图）
+> 触发：用户提出——Dash 有 Profile（`dsh --profile`）与 Agent Preset 两层，
+> 现蓝图把 DASHR 做成"与内建 PTC 编码模式同级的第五 preset"，能否再拔高
+> 一层，到 Profile 层面去做？
+> 方法：直读 `deepseek-harness @47f9438` 的 boot / bundle / preset 三层源码 +
+> 活体 profile 目录（`~/.dsh/profiles/`）+ DASHR 两包实测，逐条取证。
+> v1.1（2026-08-16 补）：新增 §9 决策附录（四模式核实/隔离实测/Web UI 复用）、
+> §10 形态收敛（直接做成 Profile）+ TUI 可行性（三条思路源码取证 + 生态实证）。
+> 一句话结论：**可行，且机制已内置——Profile 层的可分发原子是 bundle
+> （声明 `dsh.bundle.patch` 的包）；"上升到 Profile 层"精确等价于"把
+> DASHR 从 plugin+preset 变成 bundle（甚至一个 headless 式的独立运行时
+> profile）"。内建先例就是 headless。**
+
+---
+
+## 0. 结论摘要（TL;DR）
+
+1. **用户"两层"直觉需修正为四层 + 一个正交层**（§1）。Profile 与 Agent
+   Preset **不是上下级**，而是两个不同阶段的层：Profile 是 boot 层（决定
+   挂哪些 bundle/插件），Agent Preset 是 session 层（决定模型看到哪些
+   工具/提示）。真正的"Profile 层的可分发插件"原语是 **bundle**。
+2. **"上升到 Profile 层" = 成为 bundle**。精确语义是：DASHR 的 runtime
+   半边（`rlmRuntime` 服务 + presentation + 生命周期）从 preset 的
+   per-session scope 移到 **boot 层 / host realm**；模型面半边（工具 +
+   提示）仍是 preset，但借 bundle 覆盖 `agent-presets.default` 变成
+   **默认 preset**（甚至像 headless 那样干脆不需要 preset 名册）。
+3. **最硬的实证支点**：DASHR 现在两个包 `dsh: null`（非 bundle），装包后
+   preset 连注册都要靠手动 `--patch` overlay（`dashr-presentation/README`
+   L48-73 实证）。升 bundle 后这一步由 bundle 自己的 `cordis.patch.yml`
+   在 boot 时自动完成——一次 `dsh plugin add` 全落。
+4. **内建先例 = headless**：`headless` bundle 就是"编码模式做成运行时"的
+   官方示范——boot 层直接挂 `code-runtime` worker-thread，无 preset 名册，
+   `tools.mode` 走 `DSH_TOOLS_MODE`。DASHR 的"Profile 层"完全可以照抄这
+   条，做一个 `dashr` profile：boot 挂 `rlmRuntime`，运行时即 RLM 模式。
+5. **代价**：boot 层耦合面变宽（依赖 `agent-presets`/`session`/`sandbox`
+   等行 id 稳定），与 v0.5 §7.6"运行时零上游依赖"决策存在**真实张力**，
+   需重新权衡（§6）。
+
+---
+
+## 1. 源码证实的真实分层（修正"两层"直觉）
+
+活体 `~/.dsh/profiles/web/package.json` + `packages/boot/app-boot/src/profile.ts`
++ `packages/preset/agent-presets/` 三处对读，实际是**四层 + 一个正交层**：
+
+```
+boot 阶段（决定"装了什么运行时"）           session 阶段（决定"模型看到什么"）
+┌─ Profile  ~/.dsh/profiles/<name>/         ┌─ Agent Preset（正交，非下级）
+│    package.json: dsh.profile.bundles[]       agent.cordis.yml 列表 = 面向模型的
+│    cordis.patch.yml（用户层）                 工具行 + 提示行 + scoped 服务
+│  └─ Bundle  npm 包，声明 dsh.bundle.patch      发现：roots 扫描（system shipped
+│      cordis.patch.yml = insert 行 + 覆盖行        + ~/.dsh/.agent-presets/）
+│    └─ Plugin  单个 Cordis entry（id+name+config） 选择：default + 会话头 + 事件，锁
+```
+
+**证据**：
+- Profile 本体：`profile.ts` L36-96（`Profile`/`ProfileLayer`/`bundles`）；
+  `PROFILE_TEMPLATES` L114-117（`web`/`headless` 自动初始化）；
+  `DEFAULT_PROFILE_BUNDLES = ['@deepseek-ai/dsh-base']` L125。
+- Bundle 声明：`profile.ts` L42-45（`dsh.bundle.patch`）；L371-397
+  （`loadProfile` 解析 bundle patch，缺 `dsh.bundle` 则 fail-loud L392-394）。
+- 装配：空根 `[]` + bundle 层按序 + profile 层 + home 层 + overlay
+  （`apps/cli/src/profile-boot.ts` `composeProfile`）。
+- Preset 发现：`discovery.ts` `COMPOSITION_FILE='agent.cordis.yml'` L26、
+  `USER_PRESET_DIR='.agent-presets'` L41、`discoverPresets` 按 roots 优先级
+  L177-186；`preset.ts` `Config{default,roots,includeUserRoot}` L51-62。
+
+---
+
+## 2. 各层"能做什么 / 不能做什么"（层级决定能力）
+
+| 层 | 挂载时机 | realm | 能贡献 | 不能贡献 |
+|---|---|---|---|---|
+| **Bundle** | boot（进程启动） | root/host | **任何行**：llm、session、sandbox、subagent、system-prompt、`agent-presets` 本身、以及新 runtime 服务 | — |
+| **Agent Preset** | session（每会话挂） | scoped（per-session） | 工具行、system-prompt 段、`isolate` realm 的 scoped 服务 | **root realm 服务被拒**（`mount.ts` 头注 + `leakedServices`：泄露到 root realm 的行直接拒载） |
+
+**推论（本研究的核心）**：
+- runtime 服务（`rlmRuntime`、kernel 生命周期、sandbox 套壳、subagent 桥）
+  **天生是 bundle 的事**——它们要在 boot 时进 host realm、按 Session/Agent
+  键控，而不是挤进 preset 的 per-session scope。
+- 模型面（`run_cell` transport、py-sdk、工具 schema 抑制）**天生是 preset
+  的事**——它们本来就是 per-session 组合。
+- DASHR 现状把**两者都塞进 preset**，正是 §7.4.1 realm 勘误（isolate 是
+  per-mount 非 per-session）与 root-realm-reject 风险的根因。分层错位，
+  不是缺能力。
+
+---
+
+## 3. DASHR 现在到底在哪一层（实测）
+
+| 项 | 实测 | 层 |
+|---|---|---|
+| `dashr/package.json` | `dsh: null`，deps 仅 schemastery + zeromq | **非 bundle** → plain dependency |
+| `dashr-presentation/package.json` | `dsh: null` | **非 bundle** → plain dependency |
+| preset 文件 | `dashr-presentation/preset/dashr/{agent.cordis.yml,preset.yml}` | session 层 |
+| preset 注册方式 | README L48-73：**手动 `--patch` overlay** 给 `agent-presets` 加 `roots` 指到 `node_modules/dashr-tool-presentation/preset`，再手动设 default | **手动的 boot overlay** |
+
+即现状 = **plugin（依赖）+ preset（会话模式），且 preset 注册是手动的
+boot overlay**。`dsh plugin add <pkg>` 对 `dsh: null` 的包只会装成
+"plain dependency, not a profile layer"（`plugin.ts` `reconcilePlugins`
+L44-47 的 warning 分支），preset 名册根本不会自动知道它。
+
+---
+
+## 4. 上升方案：两级目标
+
+### 4.1 Target 1 — DASHR 成为 bundle（Profile 层，叠加到既有 profile）
+
+最小改动：给一个包声明 bundle，其 `cordis.patch.yml` 在 boot 时完成三件事：
+
+```yaml
+# dashr 包 package.json
+"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
+
+# dashr 包 cordis.patch.yml（boot 层，root realm）
+- insert:
+    - id: rlm-runtime
+      name: 'dashr-code-runtime-ipython'      # ① runtime 服务，boot 时 host realm
+    - id: rlm-presentation
+      name: 'dashr-tool-presentation'          # ② run_cell transport + py-sdk
+
+- id: agent-presets                            # ③ 覆盖 preset 名册（web 才有此行）
+  config:
+    default: dashr
+    roots:
+      - path: <bundle-dir>/preset               # 本包自带 preset 目录
+        trust: system
+```
+
+效果：`dsh plugin add dashr-code-runtime-ipython` 一次命令 → `reconcilePlugins`
+检测到 `dsh.bundle.patch` → 自动追加进 `dsh.profile.bundles` → boot 时
+runtime + presentation 挂 host realm、preset root 注册、default 翻到 dashr。
+**手动 `--patch` 消失**。
+
+### 4.2 Target 2 — DASHR 成为独立运行时 profile（headless 式一等运行时）
+
+**没有"profile package"这种可分发原语**——profile 是用户本地目录，创建靠
+`dsh plugin --profile dashr add <pkg>`（`DEFAULT_PROFILE_BUNDLES=[dsh-base]`）。
+所以"发一个 profile"实际是**发一个 bundle + 安装器/文档**。但语义上可以做
+成 headless 的镜像：
+
+```
+dashr bundle（照抄 headless/cordis.patch.yml 的结构，~25 行）
+- id: system-prompt        → RLM persona 覆盖
+- id: tools                → 呈现 RLM cell 界面（对应 headless 的 mode: DSH_TOOLS_MODE）
+- insert: rlm-runtime + rlm-presentation + dashr-startup + dashr-runner
+```
+
+对比 headless（`packages/bundle/headless/cordis.patch.yml` 全文仅 ~25 行）：
+它 **boot 层直接挂 `code-runtime` worker-thread，无 preset 名册**，
+`dsh --profile headless "<task>"` 即"编码模式做成一等运行时"。DASHR 照此做
+`dsh --profile dashr "<task>"`，即"RLM 做成一等运行时"。这比 Target 1
+更进一步：**连 preset 名册都可有可无**（像 headless 那样 tools.mode 直给）。
+
+---
+
+## 5. 价值（为什么上升，按权重）
+
+1. **runtime 逃出 preset scope**（最大）：`rlmRuntime` 从 per-session 的
+   isolate realm 挤迫，改为 boot 层 host realm + 显式 Session/Agent 键控。
+   直接消除 §7.4.1 的 realm-per-mount 勘误与 root-realm-reject 风险。
+2. **身份对齐乃至超越**：PTC 编码模式在 web 里**仍只是五选一的 preset**
+   （`default: standard`，会话内切换）；而 DASHR 升 bundle 后拥有 boot 层，
+   是"运行时"而非"模式"——比"与 PTC 同级"更进一步，对标的是 headless。
+3. **boot 级能力组合解锁**：sandbox 套 kernel、subagent 桥 boot 化、snapshot
+   store、persona、compaction——这些现在被 preset 边界挡住的项，全部可在
+   bundle 层落地。
+4. **装包摩擦归零**：手动 `--patch` overlay（§3 实证痛点）→ 一次
+   `dsh plugin add` 自动全落。
+
+## 6. 代价与风险（诚实记录，与 v0.5 决策的张力）
+
+1. **boot 层耦合面变宽**：bundle 依赖 `agent-presets`/`session`/`sandbox`/
+   `system-prompt` 等**行 id 与 config 形状稳定**。这与 v0.5 §7.6 换键 +
+   vendored SD 换来的"运行时零上游依赖"是**相反方向**——前者买自主，后者
+   买 boot 杠杆。这是本路线最需要用户拍板的一处权衡。
+2. **`agent-presets` 行只在 `web-app` bundle**（L421-424，`default: standard`），
+   `dsh-base` 与 `headless` 都没有（实测）。→ Target 1 的"覆盖 default"只在
+   web profile 成立；headless 场景要走 Target 2（tools.mode 直给），不依赖
+   preset 名册。这是关键的平台分叉，必须写进方案。
+3. **root realm 服务 = process-global**：per-session 键控从"preset 隔离"变为
+   "自己 key"。M3-A 已交付 `Map<principal,kernel>` + lazy per-key +
+   `agent/disposed` per-key teardown，机械件已具备，语义要重述。
+4. **发行面**：bundle 需声明 `dsh.bundle.patch`，且行 id 与 dsh 实际一致
+   （pre-release 漂移面，比现在宽）。
+5. **两包形态**：bundle 的 patch 按"行名→包名"引用插件，runtime 与
+   presentation 两包需一个 bundle 包（或 meta-bundle）统一 insert；要么合并
+   成单包，要么增一个壳包。
+
+## 7. 与 v0.5 蓝图的关系
+
+- **不改 v0.5 蓝图**；本研究是**平行的"再拔高"路线**，可作为 M4 之后
+  （或独立分支）的选型输入，不排入当前 M3-B/M4 计划。
+- 与 §7.4"第五 preset"不冲突：Target 1 把 runtime 半边升到 bundle、preset
+  保留为默认 face；Target 2 把 DASHR 整个做成 headless 式运行时 profile。
+  两者都是从"五选一模式"走向"一等运行时"的同一条路上不同深度。
+
+## 8. 待决 / 待核清单（供讨论，非本文结论）
+
+| # | 问题 | 现状 |
+|---|---|---|
+| 1 | 目标选 Target 1（bundle 叠加）还是 Target 2（headless 式独立 profile）？ | 开放 |
+| 2 | bundle 内 `rlmRuntime` 用 root realm 还是 isolate realm 的正确 boot 语义 | 开放 |
+| 3 | 是否接受 boot 层耦合 dsh 行 id（与 §7.6 零依赖决策的权衡） | 开放，需拍板 |
+| 4 | 发行形态：runtime+presentation 两包 + 壳 bundle，还是合并单包 | 开放（包名 scope 仍悬置） |
+| 5 | web（Target 1）与 headless（Target 2）是否两条都要，还是先一条 | 开放 |
+
+---
+
+## 9. 决策附录（2026-08-16 补充：四模式核实 / 隔离实测 / Web UI 复用）
+
+### 9.1 四个模式核实（用户"标准/极简/PTC/Creator"四点全对）
+
+实读 `apps/cli/config/agent-presets/<id>/preset.yml`：
+
+| preset id | 显示名 | order | 说明 |
+|---|---|---|---|
+| `standard` | 标准模式 | 1 | 全功能编码 Agent |
+| `code` | PTC 模式 | 2 | Code Mode SDK 呈现工具 |
+| `minimal` | 极简模式 | 3 | bash + str_replace_editor 双工具 |
+| `cordis` | 创造模式 | 4 | = 你说的 "Creator"；用于创作自定义 preset |
+
+加第 5 preset `dashr`（RLM 模式）到名册 = 正确路径，与现开发一致。
+
+### 9.2 web 是默认 profile、无 TUI 入口
+
+- `web` 是 hardcoded alias（`args.ts` 原文："`web` is a hardcoded alias for
+  `--profile web`"）；无参数默认起 web。
+- `PROFILE_TEMPLATES` 只有 `web`/`headless`；帮助文本里的 `tui` 只是"自定义
+  profile 名"举例，非出厂模板。
+- 结论：交互面 = Web UI（web profile）+ headless 一次性；无 TUI。
+
+### 9.3 Web UI = `dsh-web-app` bundle，自包含、原样复用
+
+`web-app/cordis.patch.yml` 内 UI 相关行：`web-startup` / `webserver` /
+`web-runtime`（`dsh-web-app` 本体）、`api-gateway`（`dsh-host-apiproxy`）、
+`api-remotes`、`ui-theme` / `ui-layout` / `ui-sidebar` / `ui-settings-*` /
+`ui-conversation` …。→ 复用 = 把 `@deepseek-ai/dsh-web-app` 写进
+`dsh.profile.bundles`，**不 fork 源码**。
+
+### 9.4 profile 之间不隔离（影响"独立 dashr profile"决策）
+
+- session 按 **workspace（cwd）** 隔离：`~/.dsh/sessions/<转义cwd>/session-<uuid>/`；
+  session 头记 `agentPreset`，不记 profile。
+- `settings.yaml` / credentials **全局**（`~/.dsh/` 下，跨 profile 共享）。
+- 含义：独立 `dashr` profile 得到"默认 = RLM + 干净名册"，但**得不到数据
+  隔离**；若只要"在 Web UI 里加一个 RLM 模式"，最简做法是直接扩展现有 web
+  profile（`dsh plugin --profile web add <dashr-bundle>`），连新 profile 都
+  不用建。
+
+### 9.5 现状 ≈ Target 1（升 bundle 是"装法正式化"，非重构）
+
+| | 现状（开发中） | 升 bundle（Target 1） |
+|---|---|---|
+| 包声明 | 两包 `dsh: null`（普通依赖） | 声明 `dsh.bundle.patch` |
+| preset 注册 | 手动 `--patch` overlay | bundle 的 `cordis.patch.yml` boot 自动 |
+| Web UI | 复用 `dsh-web-app` | 同左（不变） |
+| 安装 | `dsh plugin add` 只装普通依赖 | 同命令，自动进 bundles + 挂 runtime + 注册 preset + 设 default |
+
+---
+
+## 10. 形态收敛：直接做成 Profile（bundle）+ TUI 作为 surface bundle
+
+### 10.1 "直接做成 Profile" 的确认（POFA = Profile 解读）
+
+用户新判断：Profile 也好、preset 也好，如今都按 bundle 发布，DASHR 既然
+实质是运行时，就直接做成 Profile 层。**成立，且与 §4 收敛一致**：
+
+- 可分发原语只有 bundle；"Profile 层"与"preset 层"的差别不在发布形态，
+  而在**挂载阶段与 realm**（§2）。
+- DASHR 的 runtime 半边（`rlmRuntime`/presentation/生命周期）本就该在 boot
+  层；模型面半边（`run_cell`/py-sdk）仍是 preset、设为默认。
+- 所以"直接做成 Profile"= 把 DASHR 声明成 bundle + 复用 web-app，其余照旧
+  （§4.1 Target 1）。不是新路线，是把现开发正式化。
+
+### 10.2 "同一包既借 Web UI 又用 TUI"——架构上天然成立，且已被生态证实
+
+dsh 把"交互面"抽象为 **surface bundle**：`dsh-web-app`（Web）、
+`dsh-headless`（一次性）。TUI 只是**第三个 surface bundle**，与 runtime
+bundle 正交：
+
+```
+dsh-base（核心）+ DASHR runtime bundle（kernel+presentation，surface 无关）
+  ├─ + dsh-web-app  → dashr-web（借 Web UI）
+  └─ + dsh-tui      → dashr-tui（用 TUI）
+```
+
+所以"一个包"= DASHR runtime bundle 一个，同时喂给两个 surface，不需要 fork
+任何东西。
+
+**关键实证（web 检索 2026-08-16）**：生态里已有现成 TUI，且正是
+"out-of-tree dsh plugin bundle"或"over the one DSH HTTP contract"：
+
+- [openguardrails/dsh-tui](https://github.com/openguardrails/dsh-tui) —
+  Claude Code-style TUI，明确是 **out-of-tree dsh plugin bundle**
+- [MashedPotato817/dsh-tui](https://github.com/MashedPotato817/dsh-tui) —
+  Claude Code-style 对话 + Vim modal + HUD，**走 DSH 单一 HTTP 契约**（即
+  复用 web-app 暴露的 `api-gateway`/`api-proxy` RPC，不是 fork Web UI）
+- npm [`@dsh-tui/dsh-tui`](https://www.npmjs.com/package/@dsh-tui/dsh-tui)
+- [lhjnano/orcatui](https://github.com/lhjnano/orcatui) — 终端多 agent 编排器
+  （N agent side-by-side，各自 PTY/worktree）——正是你要的 tmux 式 manager 形态
+
+这直接回答"要不要抄 Web UI 源码"：**TUI 甚至不碰 web-app 源码，它是跑在
+同一条 host RPC 上的另一个 client**。思路 #1（参考开源）因此不是"再多参考
+一个 repo"，而是**几乎可以直接踩在现成项目上**。
+
+### 10.3 三条 TUI 思路的源码级可行性
+
+| 思路 | 实测依据 | 工作量 | 风险 |
+|---|---|---|---|
+| 1 参考开源 dsh-tui | 已存在，out-of-tree bundle + DSH HTTP 契约 | **低**（复用/参考） | 协议随 dsh 0.1.x 漂移；社区项目成熟度待核 |
+| 2 复用 PA TUI | `@earendil-works/pi-tui` 自研轻量 ANSI（仅 chalk/get-east-asian-width/marked/mime-types 5 依赖），组件系统齐全（box/input/editor/select-list/markdown/image/loader…）+ `modes/`（`interactive-mode`、`agents-view-mode`=多 agent 视图、`daemon`+`agent-connection`） | **中偏高**（组件可抄，渲染循环/数据源要重接 dsh agent loop + session 事件） | pi-tui 耦合 PA 的 session/daemon 模型；双上游维护 |
+| 3 自建 TUI | dsh **无 TUI 源码**（`packages/terminal` 是 shell/PTY 后端组 `terminal`/`terminal-bash`/`tool-terminal`，非 UI；无 ink/blessed 依赖）——用户猜测正确 | **高**（全量） | — |
+
+结论：TUI 应作为**独立 surface bundle + 独立里程碑**，与 runtime bundle 解耦；
+Web UI（复用 web-app）先跑通，TUI 从思路 #1 起步（参考现成 dsh-tui），
+思路 #2 仅在需要 PA 式"agents-view 多 agent 视图"时再评估移植 pi-tui 组件层。
+
+---
+
+## 11. 决策结论（暂缓，留后路）
+
+2026-08-16 用户定调：**暂不决定**，资料落盘存档即可。
+
+1. **暂不深整合 TUI**：官方现处 0.x 早期，bundle 走 Web UI 路径（与 DeepSeek
+   Web Chat 一脉相承，更 future-proof）；官方后续（0.7/0.8 附近）可能自出
+   TUI。现在 Web UI 已够用，且没有"必须用 TUI 才能完成"的工作。
+2. **留后路原则**：GUI 主攻大方向 + CLI/TUI/headless 必须留入口（LLM 本身
+   TUI-native / 命令行-native / headless-native，GUI 再成熟也要留尾巴）。
+   官方已有 headless 入口，正合此逻辑。
+3. **观望两条趋势**（观察项，非任务）：
+   - 整体是否"GUI 进发、同时留 TUI 尾巴"；
+   - 官方 TUI 是否落地（0.7/0.8）。
+4. **再评估触发条件**：官方出 TUI / 官方 bundle 形态定型 / 出现必须 TUI 的
+   工作。
+
+对 §8 待决清单的处置：**不关闭、保持开放**，但排期上不主动推进——Target 1
+vs 2、TUI 路线选择全部挂起，等官方信号。
+
+---
+
+## 附：证据索引
+
+| 结论 | 出处（clone 内实读） |
+|---|---|
+| Profile = `dsh.profile.bundles` + 用户 patch | `packages/boot/app-boot/src/profile.ts` L36-96 |
+| Bundle = 声明 `dsh.bundle.patch`；缺则 fail-loud | `profile.ts` L42-45, L371-397 |
+| `dsh plugin add` 按 `dsh.bundle.patch` 有无 reconcile | `apps/cli/src/plugin.ts` L22-25, L39-75 |
+| 空根 + bundle 层按序装配 | `apps/cli/src/profile-boot.ts` `composeProfile` |
+| Preset = `agent.cordis.yml` 目录，roots 扫描 + 优先级 | `packages/preset/agent-presets/src/discovery.ts` |
+| Preset `default` + `roots` 配置 | `preset.ts` L51-62 |
+| Preset 拒 root realm 服务 | `mount.ts` 头注 + `leakedServices` |
+| 会话选择 + 锁定 | `session.ts`；agent-presets README L148 |
+| `agent-presets` 行只在 web-app，`default: standard` | `packages/bundle/web-app/cordis.patch.yml` L421-424 |
+| headless = boot 挂 code-runtime、无 preset 名册 | `packages/bundle/headless/cordis.patch.yml` 全文 |
+| DASHR 两包 `dsh: null`（非 bundle） | `dashr/dashr/package.json`、`dashr-presentation/package.json` |
+| DASHR preset 注册靠手动 `--patch` | `dashr-presentation/README.md` L48-73 |
+| 四预设显示名（标准/PTC/极简/创造） | `apps/cli/config/agent-presets/<id>/preset.yml` |
+| `web` = 无参数默认别名 | `apps/cli/src/args.ts` L13, L66-70 |
+| Web UI 行全在 web-app bundle（自包含） | `packages/bundle/web-app/cordis.patch.yml` L99-198 |
+| session 按 workspace(cwd) 隔离、非 profile | `~/.dsh/sessions/<转义cwd>/session-<uuid>/`（活体） |
+| settings/credentials 全局共享 | `~/.dsh/settings.yaml`（活体） |
+| PA TUI = `pi-tui` 自研轻量 ANSI（5 依赖）+ `modes/` | `prime-agent/packages/tui/`；`packages/coding-agent/src/modes/` |
+| dsh 无 TUI 源码（terminal = PTY 后端组） | `packages/terminal/`（组目录：terminal/terminal-bash/tool-terminal） |
+| 生态已有 dsh-tui（out-of-tree bundle / DSH HTTP） | web 检索：openguardrails、MashedPotato817、@dsh-tui、orcatui |

package/node_modules/better-dsh/docs/10_plans/dashr-sandbox-escalation-semantics-gap.md

@@ -0,0 +1,171 @@
+# DSH 沙箱-审批语义缺口：模型先验抑制升级尝试
+
+> 日期：2026-09-01
+> 范围：upstream DSH 运行时权限语义（`@deepseek-ai/dsh-sandbox` / `dsh-sandbox-policy` / `dsh-permission-presets` / `dsh-user-approval`，全部结论来自安装包源码核实 + 本机实测）
+> 性质：源码证据链 + 语义缺口分析 + 设计提案
+> 关联：`docs/plans/dashr-security-sandbox-analysis.md`（2026-08-17，kernel 沙箱边界穿透）；同 session 的 workspace-write 沙箱实测（bwrap `--unshare-pid`，宿主 PID 不可见）
+
+## 0. 结论先行（TL;DR）
+
+**问题**：workspace-write 模式下，模型上下文主动声明 "Current DSH file policy: workspace-write…"（一个只描述限制、不描述出口的句子），却没有告知"受限操作可按调用**单次升级**（`allowed-once`）"。这给大模型注入了一个先验——"整个运行时是沙箱化的、不可绕过的"。后果是模型倾向于**自我设限**：面对 out-of-box 命令时直接报告"受限运行时干不了"，**根本不会去尝试**，因此**永远看不到** denial 返回里附带的升级提示。Denial message 是"后话"——它只对**先尝试过**的模型可见；先验一旦抑制了尝试，升级路径对整个运行时就是永不可见的死信息。
+
+**提议**：沙箱限制**对用户可见**（UI badge + 审批弹窗），但对模型采取"**后知**"披露（model-late disclosure）——不预先声明"你被沙箱化/不可变"，让模型先尝试、撞 denial、再从 denial + escalation hint 中学习"可单次升级"。形成「尝试 → 拒绝 → 可升级」的完整闭环，而不是「告知 → 自我设限 → 死锁」。
+
+**事实支撑**（§2 证据链）：DSH 自身就是"双 knob"模型（sandbox/mode × approval/policy，解耦设计，源码原话 "independent … knobs"）；升级语义字面为 `allowed-once`（单次、按调用、执行前审批）；且三个模式的上下文语句**存在不对称**——read-only 模式反而含有反自我审查指令，workspace-write 没有。
+
+---
+
+## 1. 背景与动机
+
+- Agent 运行时（DeepSeek Harness）的工具执行经 bwrap 沙箱：`--ro-bind / / --unshare-pid --tmpfs /tmp --bind <workspace>`。根文件系统只读、独立 PID namespace、/tmp 为私有 tmpfs、网络 namespace 共享（实测，2026-09-01）。
+- 沙箱之外存在一条**单次热升级**通道：工具调用可带 `sandbox_permissions` 重试，经用户审批后该次调用以更宽模式执行（`allowed-once`），下一条调用回到原有效模式。
+- 这条通道**语义上无法从"我被沙箱化"推导出来**：Sandbox（capability 层）与 Approval（decision 层）是正交维度；一个只被告知"你被沙箱化"的模型，不会自行推导出"ask for approval 可以解开沙箱"。
+- 本文记录该语义缺口，并提出"用户可见、模型后知"的披露策略。
+
+## 2. 源码事实核对（证据链）
+
+全部结论可在安装包源码中复现：`<dsh>/node_modules/@deepseek-ai/dsh-{sandbox,sandbox-policy,permission-presets,user-approval}/lib/`。
+
+### 2.1 双 knob 模型（`dsh-permission-presets`）
+
+设计文档原话：*"User-facing permission presets over the **independent** sandbox-mode and approval-policy knobs."*
+
+- **knob 1 — sandbox/mode**：`read-only | workspace-write | danger-full-access`
+- **knob 2 — approval/policy**：`ask | never`（仅两个值）
+
+preset 只是两 knob 的捆绑，默认表：
+
+| preset | sandbox | approval |
+|---|---|---|
+| `workspace-write` | workspace-write | **ask** |
+| `danger-full-access` | danger-full-access | **never** |
+
+推论：官方把 unboxed 与 never 绑定，等于承认"ask 的触发源是 denial"——unboxed 模式没有 denial 事件，ask 就成了惰性 knob。用户设想的 "unboxed ask"（unboxed + ask）不是内置 preset，但 `presets` 表可配置、任意组合允许（不匹配任何表项时投影报 `custom`）。
+
+### 2.2 单次升级机制（`dsh-sandbox/lib/types/escalation.d.ts` + `lib/index.js`）
+
+- 升级**在执行前**解决：`approveEscalation` — *"resolve a sandbox-escalation request BEFORE anything executes"*，有序 fail-closed：严格加宽校验 → 审批通道 → 结果映射。
+- 审批结果枚举字面：**`'allowed-once' | 'rejected' | 'cancelled' | 'unavailable'`**。
+- 粒度**恰好这一次调用**：*"Returns the granted mode to stamp onto exactly this call"*；`SandboxPolicy` 注释 *"an approved escalated retry is a new call with a wider policy"*。→ 不是"逃出沙箱"，是**调用级换挡**。
+- 严格加宽阶梯（执行期校验，非 schema 静态值）：
+
+```js
+WIDER_MODES = { "read-only": ["workspace-write","danger-full-access"],
+                "workspace-write": ["danger-full-access"] }
+```
+
+- 非加宽请求**永不弹审批**（*"a non-widening request never prompts a human"*，直接拒）。
+- 无审批通道 / 无 agent → fail closed，绝不静默放行。
+- `sandbox_permissions` 与 `justification` 必须成对（理由缺失 = malformed ask）。
+
+### 2.3 三个模式的模型上下文语句（`dsh-sandbox-policy/lib/index.js` `renderPolicyContext`）——**不对称在这里**
+
+| 模式 | 模型看到的上下文 | 是否提及升级 |
+|---|---|---|
+| `read-only` | "…**Do not refuse a required modification from this policy alone: try an available tool normally and follow any denial and escalation guidance it returns.**" | **是**（反自我审查指令 + 升级预告） |
+| `workspace-write` | "Current DSH file policy: workspace-write. …may modify files under the session workspace: … Some platform temporary areas may also be writable." | **否** |
+| `danger-full-access` | "The DSH file sandbox does not restrict file modifications by available operations." | 不适用（已是顶） |
+
+**最常用的 workspace-write 模式没有任何升级提示，而最该防自我设限的 read-only 反而有。** 这正是语义缺口的具体落点。
+
+### 2.4 denial + escalation hint：反应式教学（`dsh-sandbox/lib/index.js`）
+
+- denial 标记：`[sandbox: file access denied under workspace-write mode]`
+- 同轮升级提示：`[sandbox: escalation available — retry this exact command once with sandbox_permissions (the narrowest wider mode that suffices) + justification; the approval prompt asks the user]`
+
+设计意图（源码注释）：nudge *"lives at the decision point so the sanctioned retry does not depend on the model recalling the tool description"*。→ 设计者已知"模型会忘"，把提示放在 denial 处。但**它依赖模型先触发 denial**。
+
+### 2.5 审批通道（`dsh-user-approval`）
+
+- `APPROVAL_POLICIES = ["ask","never"]`。
+- `ask` 语句：*"Operations that require approval may ask through the configured answerers; without an available answerer, the request fails closed."* —— 未枚举"什么需要审批"。
+- `never` 语句（反向教学）：*"…do not request sandbox escalation (do not set `sandbox_permissions`)."*
+- 审批请求当前**唯一喂入方是升级路径**；不存在"unboxed 下某工具类仍强制审批"的 gate（无硬编码 hook）。→ 想让 unboxed+ask 非惰性，需要给 `request()` 加第二个喂入方。
+
+### 2.6 schema 层补充（实测）
+
+工具 schema **始终**广播升级词汇（`ESCALATION_TARGETS = ["workspace-write","danger-full-access"]`，受限即广播）。设计注释：防止 session *"stranded … with no lever"*。→ 升级的**词汇**模型永远拿得到；缺口只在**上下文先验**，不在 schema。修 prompt 即可，不用动 schema。
+
+## 3. 语义缺口的形式化表述
+
+```
+先验注入（"workspace-write 限制"）→ 模型自我设限（"受限运行时，干不了"）
+  → 不尝试 out-of-box 操作 → denial 永不触发
+  → escalation hint 永不可见 → 升级通道对模型是死信息
+  → 自我设限成为自我实现的预言
+```
+
+- Denial message 是**后话**：它只奖励"先尝试"的模型；不尝试的模型永远到不了决策点。
+- 触发尝试的常见前提恰恰是**用户主动要求探索边界**（如"你给我探测一下沙箱边界"），日常任务注意力被任务本身拽住，不会自发地元思考能力边界。
+- 与 `danger-full-access`（unboxed + never）形成**巨大反差**：一边是"受限且不告知出口"，另一边是"全开放且不询问"。中间态（workspace-write + ask 可单次升级）的语义价值因此被埋没。
+
+## 4. 设计提案：用户可见、模型后知（model-late disclosure）
+
+### 4.1 核心主张
+
+> 沙箱限制应该**对用户可见**（UI badge、审批弹窗、`/permission` 视图），但**不必在 prompt 里预先声明给模型**——尤其不要用"你被沙箱化、不可改"的表述注入先验。让模型自然去做 out-of-box 尝试（命令行、tool call），然后在 denial 返回值里给它语义提醒（现有 escalation hint 已具备），告诉它可以单次升级。这才是完整闭环。
+
+- 对用户：策略透明（弹窗携带 `justification` 原文 + 审计记录，通道已存在）。
+- 对模型：**不预设失败**，尝试 → denial → hint → escalate（可选）→ 用户批准 → 该调用执行。
+- 安全面不扩大：denial 拦截在沙箱层，**命令根本没执行**（"nothing has run"）；尝试失败只是多一轮调用，不构成越权。
+
+### 4.2 具体落地选项（按侵入度排序）
+
+1. **最小改动（推荐先做）**：改写 `renderPolicyContext` 的 workspace-write 语句，对齐 read-only 的句式——不宣称限制不可变，改为中性 + 出口预告：
+   - 例如："Current DSH file policy: workspace-write (restricted writes; some platform temporary areas may also be writable). Do not refuse a required operation from this policy alone: try the tool normally and follow any denial and escalation guidance it returns."
+2. **严格后知（用户主张）**：workspace-write 下完全不向模型声明沙箱状态（策略仅对用户 UI 可见），升级教学完全依赖 denial + hint。副作用：模型可能对常规受限操作（如工作区外写配置）多打几轮 denial——代价小，且正是教学素材。可做成配置开关（如 `discloseSandboxToModel: false`）。
+3. **unboxed ask 前置条件**：若要提供 unboxed+ask preset，必须先实现强制审批 hook（§2.5 所述 `request()` 的第二个喂入方），否则 ask knob 是装饰性的。
+
+### 4.3 披露对称性原则（通用准则）
+
+无论披露什么，**约束与出口必须成对披露**：告诉模型存在约束，就同时告诉它缓解阀（read-only 语句已示范；`never` 语句是反向示范）；不告诉它约束，就由 denial 在决策点教学。禁止"只披露约束、不披露出口"——那是把模型锁进自我实现的预言里。
+
+### 4.4 零侵入实现路径（插件侧，机制已核实 2026-09-01）
+
+> 结论：中性披露**不需要侵入 upstream 源码**。System Prompt 按两个独立集合组装——sections（主 prompt 区）与 contexts（"Current runtime context" 快照区）；两区都支持插件注册，且有组装期改写钩子。
+
+**机制核实**（`dsh-system-prompt` + `dsh-agent-loop` 源码）：
+- `ctx.systemPrompt.section()` / `context()` 均为公开 API，任意 order 可注册；contexts 按 order 排序渲染进 `"Current runtime context. This snapshot supersedes…"` 快照（`sandbox:policy`=110，`approval:policy`=115，`subagent:delegation`=120）。
+- `assemble()` 尾部有 `system-prompt/assemble` waterfall（"the returned waterfall value is authoritative"）——插件可整体改写 assembly，含 contexts 文本。
+- DASHR 已注册 `dashr:control-prompt`（section，order 100）与 `dashr:tool-catalog`（150）——注入通道现成。
+
+**三条路径**（按与政策段落的贴合度排序）：
+1. **A. 插件注册 context（order 116）**：`ctx.systemPrompt.context({ name: 'dashr:escalation-guidance', order: 116, text: … })`。渲染进**同一个** runtime-context 快照，紧贴 `approval:policy`（115）之后——模型视为运行时事实的一部分；零上游改动、声明式、无冲突。
+2. **B. assemble waterfall 原位改写**：注册 `system-prompt/assemble` listener，把 `assembly.contexts` 中 `sandbox:policy` 的 text 替换为中性 + 出口预告版。模型看到的是政策段落**本体**被改写，等同原位 patch；代价是 waterfall 语义（last non-undefined wins）需与其他 listener 协调。
+3. **C. 现有 section 追加一句**：在 `dashr:control-prompt` 加一句。可用，但落在主 prompt 区，与 `sandbox:policy`（快照区）**物理分离**——正是"都在 System Prompt 但隔了一段距离"的情形；且 order 100 先于快照区渲染，属次优位。
+
+推荐：**A 为主，B 为可选强化**。两者都不改 upstream 一行代码。
+
+**最终决策（2026-09-01，并入升级批次）**——选项 A 的落地规格：
+
+- **注入文本（精简：只披露能力，不劝导行为）**：
+  `Restricted operations may be retried once with sandbox_permissions for single-call escalation, pending user approval.`
+  （语义即"受限操作可带 sandbox_permissions 单次升级（需用户审批）"；**不做**"不要仅凭策略拒绝、先尝试"之类的行为劝导——尝试与否由模型自行决定，运行时只负责让杠杆可知。注入文本用英文，与上游 runtime-context 快照的英文语句同文风。）
+- **注入条件（模式判断，仅 workspace-write）**：`text: (ctx) => 有效模式 === 'workspace-write' ? TEXT : ''`（空文本被渲染器过滤，等同 pass）：
+  - `read-only`：pass —— 上游该模式语句已自带反自我审查 + 升级指引（§2.3），无需重复；
+  - `danger-full-access`：pass —— unboxed，无升级目标可言。
+- **机制**：§4.4-A（`ctx.systemPrompt.context({ name: 'dashr:escalation-guidance', order: 116 })`），声明式、零上游改动。
+- **批次**：作为一次升级批次中的一项变更，与其余待改项一次性采集实施（§6）。
+
+## 5. 权衡与反方观点
+
+| 维度 | 后知披露的代价 | 缓解 |
+|---|---|---|
+| 尝试轮次 | 模型可能对常规受限操作多尝试几次才收敛 | denial 是廉价信号；read-only 语句已验证"尝试→指引"模式可用 |
+| 用户困惑 | 用户可能看到模型频繁撞 denial | 弹窗/审计已把决策权交还用户；UI badge 表明当前策略 |
+| 与"尽量减少 out-of-box 危险动作"的设计哲学 | 后知披露确实会鼓励更多 out-of-box 尝试 | 但尝试被 denial 拦截，**不执行**；真正执行仍需用户审批，风险决策点不变 |
+| 模型上下文长度 | 移除先验可省一行；增加出口预告也只是一行 | 净变化为零量级 |
+
+反方观点（诚实记录）：部分设计者会主张"先验设限"正是安全冗余——模型宁可少做也不越权。但该冗余的代价是把**合法且已有人工审批兜底**的升级通道变成死信息，属于可用性损失换来的虚假安全。审批弹窗（ask）本身就是人工决策点，真正的安全边界在用户那里，不在模型的自我设限里。
+
+## 6. 落地建议清单
+
+- [ ] **插件侧实现（无需上游改动）**：DASHR 注册 `dashr:escalation-guidance` context（order 116，§4.4-A），按 §4.4 最终决策的文本与模式条件实施——仅 workspace-write 注入精简版单次升级披露（read-only / danger-full-access pass）。若改走 upstream PR 路线，再落 `renderPolicyContext`（§4.2-1）。
+- [ ] （可选）新增配置项 `discloseSandboxToModel`，默认保留当前披露、可选严格后知（§4.2-2）。
+- [ ] 若做 unboxed ask preset：为 `ctx.approval.request()` 增加与沙箱无关的强制审批喂入方（按工具类/高危类），并配套文档说明 ask 只在有触发源时有意义（§4.2-3）。
+- [ ] 文档化披露对称性原则（§4.3）为权限语义设计不变量。
+- [ ] 将"双 knob 解耦（sandbox = enforcement，approval = decision，可组合不可推导）"写入项目约定（CONTEXT.md 或 ADR）。
+
+## 7. 结论
+
+语义缺口真实存在且可定位到具体代码行（`dsh-sandbox-policy/lib/index.js` 的 `renderPolicyContext`）；修复方向明确——**用户可见、模型后知**：策略对用户透明，对模型不注入"不可变"先验，让 denial + escalation hint 在决策点完成升级教学。该改动不扩大攻击面（denial 拦截在执行前），不增加人工决策负担（审批通道已存在），只消除"模型连试都不敢试"的死锁。