better-dsh 0.2.2-c → 0.2.3-b

package/docs/superd/01-component-boundaries.md

@@ -0,0 +1,261 @@
+# Super D 组件边界与 UI 组合层（v0.3）
+
+> 2026-09-08 · 比蓝图细一层：组件级"复用 / 替换 / 排除 / 自研"边界，两幅 Mermaid + 包 roster
+> 草案。蓝图见 `00-blueprint.md`（v0.2，§3.5 对偶裁决）。
+> 上游包事实依据：`../60_exploration-and-research/02-dsh/dsh-web-profile-package-map.md`（220 包
+> 四层分类）与 `dsh-web-ui-slot-system-research.md`（插槽机制一手核验）；机制语言层依据：
+> `../60_exploration-and-research/02-dsh/dash-research.md` §1「"Everything is plug-in" 的语言层
+> 实现」。本文回答：DSH 现有包里哪些拿来做依赖、哪些明确不要（如 DSH Session Controller）、
+> 自研 agent adapter 补在哪、前端组合层替换 DSH UI 的哪一段。
+> 2026-09-08 v0.2 修订：BFF 定性为 routing mux（namespace 分流）；ui-sidebar 移入 superD 自有
+> shell；selector 位置与品牌 MVP 策略落位；DSH 认证链速查见 §2 要点（全文：蓝图 §3.6）。
+> 2026-09-08 v0.3 修订：selector 移位侧栏底部（`sidebar.footer.action` list 槽 occupant，
+> Settings 上方），superd-sidebar copy 撤回，ui-sidebar 回归中性底座（蓝图 §3.7 v0.4 / 决策 #24）。
+
+---
+
+## 1. 前后端对偶总则
+
+- 后端 **Agent Adapter**（数据面）：把 runtime 的字段/事件映射到 superD 标准字段（DSH
+  SessionEvent 词汇）。统一 `RuntimeProvider` 接口，一个 runtime 一个包。
+- 前端 **Agent UI Adapter**（呈现面，机制 = 插槽组合）：把标准字段渲染成该 runtime 的 UI
+  形态。一个 runtime 一个包，从 agent-ui-dsh 蓝本 copy 起步。
+- 两者都是 cordis 插件；**同一 selector 驱动、同组启停**——一个 runtime 落地为一对包：
+  `@pgmi-builds/agent-adapter-x` + `@pgmi-builds/agent-ui-x`。
+- **切换 = 组合重算**：selector 变更 → 插件行集合（空间数据）一次变更 → 时间维机制（受影响
+  fiber 的 unload → reload 重放）落地 → 插槽树重渲染。这是 "everything is plug-in" 的机制内
+  行为（epoch 签名驱动），不是 hack；语言层同构案例见 dash-research §1(5) 的 provider 切换。
+- **互斥不变量**：同一时刻仅一个 composition 激活。conversation.* 槽带同 key 双注册会撞、
+  list 槽会叠渲染）——互斥由 host 侧 Composition Registry 保证（按 selector 算出互斥插件行集）。
+- **DSH 面 = 全透传 + routing mux**：superD 自有 namespace（`machines.*` / `superd.*`）本地应答，
+  其余按 active adapter 转发；DSH 三面（session/workspace/settings）逐帧透传、零翻译（蓝图 §3.6）。
+
+---
+
+## 2. Host 侧组件边界
+
+```mermaid
+flowchart LR
+    subgraph UP["复用 · 上游原样（exact-pin）"]
+        COR["cordis 核心 + loader/include/group/timer/hmr<br/>（插件系统基座）"]
+        CARRY["载体：host-webserver · host-frontend-static<br/>client-modules（wire ①②：静态资产 + boot graph）"]
+        WIREH["wire：client-connection · api-gateway · typert-*<br/>（wire ③④：/api unary + WS mux，哑传输）"]
+    end
+
+    subgraph SD["自研 · superD host 核心"]
+        BOOT["superd 主插件（CLI 自举 · bundle 组装）"]
+        REG["Provider Registry<br/>RuntimeProvider 统一接口"]
+        BFF["superD Routing Mux / BFF<br/>machines.* / superd.* 本地应答 · 其余透传 active adapter"]
+        MM["Machine Manager<br/>local/remote 清单 · 连接池 · 探测"]
+        PAIR["Session Pairing（配对表 ~/.superd/pairings.json）"]
+        SELH["Selector + Composition Registry<br/>runtime 选择态 · 插件行集合重算"]
+        AUTH["AuthChain（空壳中间件链）"]
+    end
+
+    subgraph AD["自研 · Agent Adapter ×6（@pgmi-builds/agent-adapter-*）"]
+        A1["dsh（wire 透传 3080）"]
+        A2["omp（omp-web 桥接改造）"]
+        A3["pi（与 omp 同系共用源码）"]
+        A4["claude-code（SDK）"]
+        A5["codex（SDK）"]
+        A6["hermes（协议桥/源码 import）"]
+    end
+
+    CONSU["自研 · Consumers：TG messaging channel（M2+，orchestra 搬运）"]
+
+    subgraph X["排除 · 不进依赖树"]
+        X1["DSH BFF：api-session / api-workspace / api-settings-controller"]
+        X2["DSH 数据面：session / persistence / projection / query / title / telemetry…"]
+        X3["DSH agent 运行时：agent / agent-loop / llm-* / tools / tool-* / sandbox / fs / subprocess…"]
+        X4["DSH 编排原语：subagent / goal / workflow / schedule / agent-team…"]
+    end
+
+    REMOTE["远端 machine（superD-to-superD：DEV3…）"]
+    RT["上游 runtime 进程（dsh:3080 / omp / claude-code / codex / pi / hermes）"]
+
+    BOOT --> COR & CARRY & WIREH
+    BOOT --> REG & MM & PAIR & SELH & AUTH
+    BFF --> REG
+    SELH --> REG
+    MM --> REMOTE
+    REG --> A1 & A2 & A3 & A4 & A5 & A6
+    A1 & A2 & A3 & A4 & A5 & A6 --> RT
+    REMOTE -.->|"remote superD 起 adapter 桥本地 runtime"| RT
+    CONSU --> PAIR
+    BFF -.->|"替代其 RPC 面（不进树）"| X1
+```
+
+要点：
+
+- **载体层原样**：webserver / frontend-static / client-modules / connection / gateway 保持上游
+  依赖——wire 面 100% 兼容、升级跟随 upstream，锁版策略对冲无稳定性承诺的风险（蓝图 §2/§5）。
+- **替换层 = thin routing mux，不是全量重实现**：DSH 三个 BFF controller（**含 DSH Session
+  Controller**）不进依赖树；superD 侧按 RPC namespace 分流——自有面本地应答，其余透传 active
+  adapter（DSH 面逐帧零翻译，UI 与上游锁死同版 ⇒ 契约逐字节一致）。
+- **DSH 认证链速查**：machine token 一次性 mint `dsh-auth-*` cookie（HMAC 签名、持久 secret ⇒
+  cookie 跨上游重启有效，默认 30 天）→ adapter 服务端 cookie jar 附带转发；loopback Host 天然过
+  信任栅栏。源码锚点与 mint 流程见蓝图 §3.6。
+- **排除层**：DSH 的会话数据面、agent 运行时、编排原语整体不引入。superD 不跑 agent、不存原始
+  会话（唯一持久状态是 pairing 表）。这些包不是"被 patch 掉"，而是**根本不出现在 bundle 里**。
+- **远端**：v1 仅 superD-to-superD；CLI 型 runtime 必须由远端 superD 本地桥接（蓝图决策 #17）。
+
+---
+
+## 3. 浏览器侧组件边界（Agent UI Adapter 替换带）
+
+```mermaid
+flowchart TD
+    subgraph BASE["中性底座 · 上游原样（所有 composition 共享，exact-pin）"]
+        RUN["cordis-client-runner（浏览器 Cordis：fiber/registry/reflect/events）"]
+        CMOD["client-modules / client-locale / client-store / client-hmr"]
+        SLO["ui-slots（SlotCore · SlotMap 契约声明合并）"]
+        REN["ui-renderer（唯一 React 绑定 · renderSlot('root')）"]
+        LAY["ui-layout（root 布局树 · sidebar/会话区 区域槽）"]
+        SID["ui-sidebar（sidebar 壳，原样复用）<br/>含 sidebar.footer.action list 槽（selector 落位）"]
+        THM["ui-theme"]
+        SET["ui-settings（settings 页壳）"]
+        WS["ui-workspace（workspace 壳 · 数据由 superD BFF 聚合供给）"]
+        RPC["client-connection / api-remotes（RPC 桩 · 远程能力本地代理）"]
+    end
+
+    subgraph COMP["自研 · Agent UI Adapter ×6（@pgmi-builds/agent-ui-* · 同一时刻仅一个激活）"]
+        U1["agent-ui-dsh<br/>（蓝本：copy DSH 会话面全套）"]
+        U2["agent-ui-omp"]
+        U3["agent-ui-pi"]
+        U4["agent-ui-claude-code"]
+        U5["agent-ui-codex"]
+        U6["agent-ui-hermes"]
+    end
+
+    subgraph OWN["自研 · superD 自有 UI（occupant / 自有槽，不动底座）"]
+        SELUI["Runtime Selector（Agents 按钮）<br/>sidebar.footer.action occupant · Settings 上方"]
+        MSET["Machines 设置页（multi-machine 配置）"]
+        BRD["brand：MVP 不动（沿用上游品牌）"]
+        TAB["（后续）superD 专属全页 Tab + 专属插槽"]
+    end
+
+    subgraph CUT["被 composition 替换 · 不进 bundle（槽声明权随 copy 转移）"]
+        C1["ui-chat / ui-conversation / ui-session / ui-trajectory"]
+        C2["ui-model-selection / ui-agent-preset / ui-permission-presets / ui-settings-models"]
+        C3["ui-tool / ui-attachment / ui-input-trigger / ui-reference / ui-message-feedback / ui-approval / ui-user-questions"]
+        C4["ui-plan / ui-goal / ui-subagent / ui-workflow-run / ui-jobs / ui-deliverables / ui-skill / ui-commands"]
+    end
+
+    RPC --> RUN
+    RUN --> SLO
+    REN --> LAY
+    LAY --> SID
+    LAY --> SET
+    LAY --> WS
+    LAY -->|"会话区槽带（conversation.* / tool.call.* / composer.*）同一时刻仅一个激活"| U1 & U2 & U3 & U4 & U5 & U6
+    U1 -.->|"copy 蓝本（锁版 diff 基线）"| C1 & C2 & C3 & C4
+    SID --> SELUI
+    SET --> MSET
+    SID --> BRD
+    LAY -.-> TAB
+    SELUI -.->|"切换：整组换装 + 重渲染"| COMP
+```
+
+要点：
+
+- **中性底座 = 上游原样依赖**：插槽机制（ui-slots）、渲染器（ui-renderer）、布局树（ui-layout）、
+  主题、settings 页壳、sidebar 壳、wire 桩。换 runtime 不动这一层——对应 DSH 前端"框架中立
+  内核 + 可替换渲染后端"的既有分层。
+- **替换不是 patch，是不进 bundle**：CUT 组的 DSH 包（ui-chat / ui-conversation / ui-session /
+  …）直接不进依赖树；composition 包 copy 了它们的源码，**槽声明权（SlotMap 契约合并 + 槽
+  注册）随 copy 转移**给 composition。底座的 layout 只认槽带，不认包。
+- **superD 自有 UI 全部走 occupant**：selector（Agents 按钮）= `sidebar.footer.action` list 槽
+  occupant（Settings 上方；owner 只给 `wide` 标志，rail 态渲染单图标，样式对齐 Settings 行）；
+  Machines 挂 settings 页；brand MVP 不动；未来全页 Tab 走 ui-layout 声明新区域槽或自有路由
+  槽——中性底座零 copy 例外（v0.4：superd-sidebar 计划撤回）。
+- **数据来源不变**：composition 消费的仍是 api-remotes RPC 桩暴露的标准面（session/workspace/
+  settings），服务端由 superD BFF + adapter 供给。前后端各自的"对偶替换带"互不越界。
+
+---
+
+## 4. 包 roster 草案（三档处置，M1 定稿——对齐蓝图开放问题 #6）
+
+### ① 中性底座：原样依赖（exact-pin）
+
+| 组 | 包 | 备注 |
+|---|---|---|
+| Cordis 框架 | `cordis`、`plugin-loader`、`plugin-include`、`plugin-group`、`plugin-timer`、`plugin-hmr`、`cosmokit`、`schemastery` | 插件系统基座，全量需要 |
+| 载体（host） | `host-webserver`、`host-frontend-static`、`client-modules` | wire ①②（静态资产 + boot graph） |
+| wire 双端 | `client-connection`、`api-gateway`、`api-remotes`、`typert-protocol/-registry/-loader`、`cordis-host-runner`、`cordis-client-runner` | wire ③④ + 浏览器 Cordis，哑传输/哑运行时 |
+| 前端基建 | `client-locale`、`client-store`、`client-hmr` | observable/locale/热更基建 |
+| UI 壳 | `ui-slots`、`ui-renderer`、`ui-layout`、`ui-sidebar`、`ui-theme`、`ui-settings`（页壳）、`ui-cordis`（调试面板） | 组合机制与布局骨架，所有 composition 共享（v0.4：sidebar 回归） |
+| UI 壳（复核位） | `ui-workspace` | 壳可复用；数据面改由 superD BFF 聚合（machine/runtime 分组），M1 复核是否需 patch |
+
+> v0.4 修订：~~ui-sidebar 移出中性底座~~ **撤回**——selector 移位侧栏底部 footer 区，落位现成
+> list 槽 `sidebar.footer.action`（occupant 注册，渲染于 Settings **上方**堆叠；与 Settings 同行
+> 不可行：owner 的 `footArea` 是 column 布局，occupant 改不了 owner）。ui-sidebar 回归中性底座
+> 原样依赖，copy 例外清零（蓝图 §3.7 v0.4 / 决策 #24）。
+
+### ② composition 蓝本：不直接依赖，copy 进 agent-ui-dsh 后派生 per-runtime 包
+
+| 组 | DSH 源包（蓝本） | 说明 |
+|---|---|---|
+| 会话核心 | `ui-chat`、`ui-conversation`、`ui-session`、`ui-trajectory` | conversation.* 槽带的 owner，整组 copy |
+| 模型/预设 | `ui-model-selection`、`ui-agent-preset`、`ui-permission-presets`、`ui-settings-models` | 模型列表/预设是 runtime 特有词汇 |
+| 会话附属 | `ui-tool`、`ui-attachment`、`ui-input-trigger`、`ui-reference`、`ui-message-feedback`、`ui-approval`、`ui-user-questions` | 审批/提问面各 runtime 形态不一；缺字段 = 隐藏（降级容错是设计内行为） |
+| DSH 深度面 | `ui-plan`、`ui-goal`、`ui-subagent`、`ui-workflow-run`、`ui-jobs`、`ui-deliverables`、`ui-skill`、`ui-commands` | DSH 特有编排/深度面；其他 runtime 按字段在场裁剪或整块不实现 |
+
+派生纪律：`agent-ui-omp/-pi/-claude-code/-codex/-hermes` 一律从 **agent-ui-dsh**（而非上游原包）
+fork 起步——蓝本已经过一次"去 DSH 宿主耦合"的整理，派生成本更低。
+
+### ③ 排除：不进依赖树
+
+| 组 | 包 | 理由 |
+|---|---|---|
+| DSH BFF | `api-session-controller`、`api-workspace-controller`、`api-settings-controller` | 替换层：RPC 面由 superD BFF + Provider Registry 接管 |
+| DSH 数据面 | `session`、`session-persistence(-jsonl/sqlite)`、`session-projection(-cache)`、`session-query(-sqlite)`、`session-title*`、`session-stats`、`session-telemetry*`、`session-log-*`、`session-checkpoint-policy`、`session-reference` | superD 不存原始会话；唯一持久状态 = pairing 表 |
+| DSH agent 运行时 | `agent`、`agent-loop`、`agent-presets`、`agent-default-model`、`agent-instructions`、`llm-*`、`tools`、`tool-*`、`shell*`、`bash-*`、`pwsh-*`、`sandbox*`、`fs*`、`subprocess*`、`code-runtime*`、`compaction*`、`spill*`、`credentials*`、`system-prompt`、`persona`、`mcp-client` | superD 不跑 agent、不含模型调用链（蓝图 §1） |
+| DSH 编排原语 | `subagent*`、`goal*`、`workflow*`、`schedule`、`jobs*`、`experimental-agent-team`、`plan-mode` | 上游 runtime 自带编排；superD 只桥接 |
+| 宿主杂项 | `plugin-inventory*`、`directory-picker-*`（暂缓）、`brand-official`（brand 槽由自有 occupant 替换）、`settings-plugins`/`settings-plugin-inventory`（superD v1 无插件管理面） | 按需再议；directory-picker 与 machine 语义耦合，M1 裁决 |
+| 候补复核 | `dsh-settings`、`settings-file`、`storage*` | superD 自身设置面（machines/selector/TG bindings）的底座：复用或自研轻量 JSON，M1 定 |
+
+---
+
+## 5. 切换机制（两档实现）
+
+**v1 简化档（M1 先用）**：
+
+```
+UI selector 切 runtime（settings CAS 写入）
+→ host Composition Registry 重算互斥插件行集（disable 旧组 · enable 新组）
+→ boot graph 随之变更（该组 client 模块表换装）
+→ 前端整页 reload：client runner 按新组合重新拉模块、逐个 apply
+→ SlotRegistry 重算 → renderSlot('root') 整树重渲染
+```
+
+成本最低，正确性靠"组合是声明式数据"保证——页面刷新只是最粗粒度的 reload。
+
+**v2 热切换档（M2+ 增强）**：client-hmr 式 fiber 级换装，不整页刷新——旧行组 fiber unload
+（LIFO 撤销槽注册）、新行组 reload 重放，React 树保持挂载、仅会话区槽带重渲染。
+
+**机制依据**：插件行集合是运行时数据（空间维被数据化）；enable/disable 触发受影响 fiber 的
+epoch 变化 → unload → reload 重放（时间维机制化）；插槽注册随 disposer 撤销、重放时重登记。
+与 dash-research §1(5) 的 provider 切换案例完全同构，只是粒度从"单服务槽"换成"一组插件行"。
+
+---
+
+## 6. 维护策略（对偶架构的收益兑现）
+
+- **各 composition 独立演进**：Codex 字段更新 → 只改 agent-ui-codex + codex adapter，回归测试
+  只测这一对包；DSH Web UI 更新 → diff 锁定版本 → 选择性抄进 agent-ui-dsh，不跟则维持现状。
+- **copy 纪律**：每个 composition 包记录其蓝本基线（上游精确版本号）；跟进 = `diff 基线..新版`
+  → 人工挑选 → 更新基线记录。vendor verify/restore（蓝图 §5）防误改上游本体。
+- **弃大全包的理由存档**：全量字段/全模板路线在 5+ 个更新步伐不一的上游之间同步一个全量表，
+  复杂度按 O(runtime × 字段) 增长且任何一次上游 breaking 都波及全部用户；组合层把复杂度切回
+  O(runtime) 的独立通道——这正是用 Cordis 组合机制（换 provider = 换插件行）换来的维护性。
+
+---
+
+## 来源
+
+- 蓝图：`00-blueprint.md` v0.4（§2 分界点、§3.5 对偶裁决、§3.6 透传与认证链、§3.7 selector 位置 v0.4、决策 #18–#24）
+- DSH 包事实：`../60_exploration-and-research/02-dsh/dsh-web-profile-package-map.md`（220 包四层
+  分类、类型双轨）、`dsh-web-ui-slot-system-research.md`（SlotCore/双半插件/RPC 边界）
+- 机制语言层：`../60_exploration-and-research/02-dsh/dash-research.md` §1「"Everything is
+  plug-in" 的语言层实现」(3)(5)（名字耦合与 epoch、provider 切换生命周期）
+- 官方文档蒸馏：dsh-dev-skill `skill/chapters/ch18`（slots/webServer/settings 契约）

package/docs/superd/02-dsh-embed-modes.md

@@ -0,0 +1,151 @@
+# DSH 运行时呈现层嵌入模式研究（iframe / 反代透传）
+
+> 2026-09-08 · 起因：DSH runtime 的呈现层能否绕开"自有 composition"，直接复用上游 Web UI？
+> 两个候选：①iframe 直嵌 3080 页面；②DSH adapter 假装 browser 向 3080 发请求、把 traffic
+> 透传给 3090 前端。方法：上游源码一手核验（checkout `dsh-v0.1.2-alpha.5`，
+> `~/workspaces/dashr/upstream/deepseek-harness`）。
+> 结论先行：**两者都可行**；②其实就是蓝图 v0.2 已裁决的"DSH adapter wire 透传"形态的自然延伸，
+> 真正的新选择是"前端也用上游的"——最干净的落法是 **iframe（或 iframe-over-反代）作为一个
+> lite composition**，与终态集成 composition 并存，不冲突。
+
+---
+
+## 1. 四个变体速览
+
+| 变体 | 前端是什么 | 代理代码 | 远程 machine | HTTPS 混合内容 | 集成度 | 定位 |
+|---|---|---|---|---|---|---|
+| **A 直连 iframe** | 上游真 UI（iframe src=3080） | 零 | ✗（浏览器须直达 3080） | 有风险 | 零 | 本地 DSH 的零代码捷径 |
+| **B 反代 + iframe** | 上游真 UI（iframe src=镜像） | HTTP+WS 透明反代 | ✓（经 superD-to-superD） | ✓（镜像走 HTTPS） | 低（画布级） | **推荐的 M1 lite 形态** |
+| **B′ 反代全页（无 iframe）** | 上游真 UI（整页） | 同 B | ✓ | ✓ | 零（无壳共存） | ✗ 主线；仅"远程访问网关"产品形态 |
+| **C 集成 composition** | 自有 UI（agent-ui-dsh） | RPC 透传（蓝图既有） | ✓ | ✓ | 高（统一壳） | 蓝图 v0.2 终态 |
+
+判定：B′ 把代理代码和零集成两头的成本都占了却无收益——**整页 app 无法与我们的壳共挂**
+（同一页面装两套 client 模块表 = 同 id 硬错，上游设计即禁止；DSH UI 是整页 root 槽应用，
+没有"挂在 div 里"的形态），且页面内没有我们的 selector。B′ 唯一合理用途是"superD 作为
+DSH 远程访问网关"（独立产品卖点），不是统一入口的主线。
+
+---
+
+## 2. 上游事实核查（六条，均已一手核验）
+
+1. **无 frame-busting 头**：`packages/host/`、`packages/boot/` 全量 grep 无
+   `X-Frame-Options` / `Content-Security-Policy` / `frame-ancestors` → **DSH 页面可被 iframe**。
+2. **token 只存在于 DSH 进程内存**：`client/connection/src/browser-auth.ts` —— launch token
+   为进程内随机数（`PROCESS_LAUNCH_TOKENS` WeakMap，L52–60），**无 env 覆盖、不落盘**；启动时
+   由 `authenticatedUrl()` 拼成 `/?token=…` 随 URL 打印（`bundle/web-app/src/index.ts:287` 调用）。
+   → 获取路径只有一条：**读 DSH 进程的 stdout/journal/日志**。
+3. **token → cookie 交换**：`GET /?token=…`（Host authority 必须在）→ `303` + 签名 cookie
+   `dsh-auth-<authority>`，**24h 有效**（`authorizeIndex`，L236+）；token 本身**随 DSH 进程存活**，
+   cookie 过期可用同一 token 重铸。401 响应体带指纹
+   `dsh web authentication required; reopen the URL printed by dsh web.`（蓝图开放问题 #4 已记）。
+4. **`/api` 信任栅栏按 Host 绑定，且"不是 auth 层"**（`api-request-trust.ts` 文件头注释）：
+   loopback / 部署 LAN IP / 声明的 `trustedHosts` 过栅栏。→ 反代向上游发 `Host: 127.0.0.1:3080`
+   即过；iframe 内页面对 3080 的调用是 same-origin（Host=loopback）也过。
+5. **客户端 API base = `window.location.origin`**（`client/connection/src/client/rpc.ts:109–110`，
+   缺省回退内部 base）→ **经反代时客户端自动打向代理 origin**，无需改上游客户端。
+6. **资产/模块 URL 是 root-相对路径**（boot graph 里 `/plugins/??pkg/client.js&rev=…` 形态）→
+   反代**必须挂在 origin 根**（独立端口或子域）；挂路径前缀（`3090/_dsh/`）会打断这些引用，
+   除非连 boot graph JSON 一起做路径重写（可行但增加脆弱面）。
+
+---
+
+## 3. 变体 A：直连 iframe（本地零代码）
+
+机制：superD 壳的会话区渲染 `<iframe src="http://127.0.0.1:3080/?token=…">`。iframe 文档的
+origin 就是 3080，其自身的一切 `/api`+WS 调用都是 same-origin、Host=loopback → 栅栏直过；
+token URL 首开后 303 换 cookie，此后 iframe 内自持会话。
+
+- **前提 1（✓ 已核验）**：上游不设 frame 头。
+- **前提 2（✓ 已核验）**：栅栏按 Host，iframe 内 same-origin 调用天然合法。
+- **前提 3（工程项）**：token 注入——adapter 从 DSH stdout/journal 抓 URL（本地机器可做）。
+
+局限：远程 machine 的 3080 浏览器不可达（superD-to-superD 才可达）；superD 壳若走 HTTPS
+（Caddy），iframe 载入 plain HTTP 属混合内容，浏览器会拦；跨域 iframe 完全密封（壳不能
+reach-in 折叠其自带 chrome）。
+
+## 4. 变体 B：透明反代 + iframe（推荐 lite 形态）
+
+"DSH adapter 假装成 browser"的准确工程含义：**adapter 以 browser 的口音说 HTTP/WS**（正确的
+Host 头、持 cookie、做 WS upgrade），**不是**跑一个真的 headless browser（重且脆，不需要）。
+实现就是标准反向代理：
+
+```mermaid
+flowchart LR
+    BR["用户浏览器：superD 壳（3090）"] -->|"会话区 iframe src = 镜像 origin"| IF["iframe：真 DSH UI"]
+    IF -->|"same-origin /api + WS<br/>（rpc.ts 按 location.origin 打）"| MIR["superD DSH 镜像<br/>（透明反代，origin 根挂载）"]
+    MIR -->|"Host: 127.0.0.1:3080<br/>+ 代理持有 dsh-auth cookie"| DSH["目标机 DSH（3080）"]
+    BR -->|"列表/设置/新建会话等 BFF RPC（method 级）"| BFF["superD BFF + DSH adapter"]
+    BFF -->|"同上，另一条腿"| DSH
+```
+
+实现要点：
+
+- **origin 根挂载**（事实 6）：镜像监听独立端口/子域（本地如 3091+ 自动分配；远程经 Caddy
+  路由到 remote superD 的镜像），纯透传、零重写。
+- **认证归代理**：adapter 用抓到的 token 在镜像侧完成一次 `/?token=` 交换、持有并续期 cookie；
+  **浏览器全程不见 DSH token**——对下游只有 superD 自己的认证面（authChain）。
+- **WS 1:1 桥**：每个下游 WS upgrade 对应一条独立上游 WS（不做扇出 hub，M1 单用户足够）；
+  streaming 响应禁缓冲。
+- **401 自愈**：镜像收到指纹 401 → 重读目标机 DSH 日志取新 token → 重交换（DSH 重启 token
+  轮换的自动恢复）。
+- **可选 same-origin 增强**：若镜像与壳同 origin（路径前缀 + boot graph 路径重写），壳可
+  reach-in 折叠 iframe 内 DSH 自带 sidebar（双 chrome 问题）；这是 nice-to-have，不作前提。
+
+## 5. 与 v0.2 组合层架构的统一（关键：不二选一）
+
+iframe **本身就是一种合法 composition**：`agent-ui-dsh-lite` 包往会话区槽 register 一个 iframe
+组件（URL 由 adapter 供给：machine URL + token），selector 切换 = 换 composition——v0.2 的
+机制原样适用，一行不用改。分工随之清晰：
+
+- **会话画布**：lite 形态下 = 真 DSH UI（iframe）；终态 = agent-ui-dsh（copy 版）。
+- **会话列表 / workspace / settings / TG consumer**：永远走 superD BFF 的 method 级 RPC
+  （TG 本来就需要 method 级访问，adapter 的数据面两形态共用）——**统一入口不丢**：列表、
+  选择器、机器管理都是我们的，iframe 只接管画布。
+- **双 chrome**（iframe 内 DSH 自带 sidebar 叠在我们的壳里）：M1 接受；缓解路径 = 同源
+  reach-in 或移动断点折叠。
+- **红利**：镜像是 wire 层的"参考实现 + 永远新鲜的对照"——集成 composition 的字段映射
+  可随时对着真实流量校准；上游 UI 更新零成本跟进（lite 形态下根本不维护 UI）。
+
+## 6. token 获取与生命周期（两形态共用）
+
+| 事实 | 值 | 出处 |
+|---|---|---|
+| token 存储 | 仅进程内存（WeakMap），无 env、无文件 | browser-auth.ts L52–60 |
+| 发放面 | 启动时随 `authenticatedUrl` 打印到 stdout | web-app/src/index.ts:287 |
+| token 寿命 | DSH 进程生命周期（重启即轮换） | WeakMap 语义 |
+| cookie 寿命 | 24h，可用同一 token 无限重铸 | authorizeIndex + DAY_MILLISECONDS |
+| 抓取实现 | 本地：journal/日志文件；远程：remote superD 读它本机的 | 蓝图本地发现三步可复用 |
+
+长期项：向上游提 service-token / machine-token 配置需求（免除日志抓取）；M1 不依赖。
+
+---
+
+## 7. 验证清单（M1 裁决 lite 形态前）
+
+1. [ ] 直连 iframe 本地 3080 实测：`?token=` 注入 → 303 → cookie 建立 → UI 全功能。
+2. [ ] HTTPS 壳（Caddy）iframe plain-HTTP 127.0.0.1 的混合内容行为（桌面 + 移动 Chrome）。
+3. [ ] 镜像反代全通：静态资产 + boot graph + `/api` unary + WS upgrade + streaming。
+4. [ ] WS 经代理的 connection generations 行为（断线重连、代理重启）。
+5. [ ] DSH 重启 token 轮换 → 401 自愈链路。
+6. [ ] 双 chrome 观感裁决（接受 / reach-in 折叠 / 移动断点）。
+7. [ ] 同源变体的 boot graph 路径重写成本评估（仅当需要 reach-in 时）。
+
+## 8. 建议
+
+- **M1**：本地 DSH 用变体 A（零代码）；远程 DSH 用变体 B（镜像反代）。`agent-ui-dsh-lite`
+  （iframe composition）先落地，`agent-ui-dsh`（集成 copy）延到 M2+。
+- **终态**：蓝图 v0.2 的集成 composition 不变；lite 作为长尾保留（"用最新原版 DSH UI"本身
+  可以是一个用户选项）。
+- **不做**：B′ 全页镜像作主线；headless browser 方案。
+
+---
+
+## 来源
+
+- 上游 checkout（`~/workspaces/dashr/upstream/deepseek-harness`，tag `dsh-v0.1.2-alpha.5`）：
+  `packages/client/connection/src/{browser-auth,api-request-trust,rpc-host}.ts`、
+  `packages/client/connection/src/client/rpc.ts`、`packages/bundle/web-app/src/index.ts`；
+  `packages/host/`+`packages/boot/` frame 头 grep（空）。
+- `00-blueprint.md` v0.2（§3 adapter 体系、§3.5 composition、开放问题 #4/#7）；
+  `01-component-boundaries.md`（呈现层替换带）。
+- 运维证据：`docs/60_exploration-and-research/`（boot graph 模块 URL 形态、token 轮换实践）。