better-dsh 0.2.3 → 0.2.4

package/docs/plans/dashr-profile-layer-feasibility.md

@@ -1,367 +0,0 @@
-# 可行性研究：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/docs/plans/dashr-sandbox-escalation-semantics-gap.md

@@ -1,171 +0,0 @@
-# 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 拦截在执行前），不增加人工决策负担（审批通道已存在），只消除"模型连试都不敢试"的死锁。