better-dsh 0.2.3 → 0.2.4

package/docs/50_test-reports/2026-09-12-url-schemes-recallable-context-design/351/252/214/350/257/201/346/212/245/345/221/212.md

@@ -0,0 +1,160 @@
+# design.md 设计符合性验证报告 — URL Schemes 服务化与 ctx:// 可回溯上下文
+
+- **被验对象**：`openspec/changes/2026-09-11-url-schemes-recallable-context/design.md`（D1–D8）
+- **对照物**：同 change 的 spec delta（`specs/url-schema/spec.md`、`specs/ctx/spec.md`、`specs/compaction-recall/spec.md`）+ 实际代码 + 4999 活体行为
+- **验证时间**：2026-09-12 06:41 ~ 07:0x（UTC+8）
+- **验证者**：agent（本会话即 4999 测试实例）
+- **结论**：**不通过（有条件）**——D1/D3 机制陈述与实现一致；D2/D4/D5/D6 存在 4 项实质偏差（其中 2 项为 spec 要求未落地：快照 `segments`、read transform 链），另有 6 项证据/文案失真。**未触发任何发布动作**（AGENTS §〇 红线未动）。
+
+---
+
+## 1. 验证环境与被验代码的身份锚定
+
+| 项 | 值 |
+|---|---|
+| 运行时 | `DSH_HOME=/home/u1/workspaces/dashr/.dsh-test`，GUI `http://127.0.0.1:4999`，会话 `session-e96cd10a-41c8-4e82-89fd-5ff4118b9d41` |
+| 插件版本 | `better-dsh@0.2.3-d` |
+| 活体实现位置 | `upstream/deepseek-harness/packages/better-dsh/better-dsh/`（profile `web` 的 bundle 成员） |
+| canonical 源 | `dashr/` |
+
+**身份锚定（关键前提）**：`diff -rq dashr/src upstream/deepseek-harness/packages/better-dsh/better-dsh/src` 与 `.../test` **均无输出** ⇒ 本轮被验的 canonical 源与 4999 实际运行的代码**逐字节相同**，「源码核验」与「第一人称实测」指向同一份实现，不存在副本漂移。
+
+## 2. 验证方法（四路独立取证）
+
+| 路径 | 手段 | 产物 |
+|---|---|---|
+| A 源码锚点 | 逐文件读取 `src/url-schemes/**`，对每条 design 陈述定位实现点 | 本报告 §4 表格 |
+| B 第一人称 live 探针 | **以本会话自己的 `read` 工具**打真实 URL（read 即被验 chassis） | §5 |
+| C 单测全量 | `npx vitest run`（canonical `dashr/`） | `.scratch/verify-url-schemes-vitest.log` |
+| D 类型/规格 | `npm run typecheck`；`openspec validate <change> --strict` | `.scratch/verify-url-schemes-tsc.log` |
+
+## 3. 一句话判定表
+
+| design 项 | 判定 | 一句话 |
+|---|---|---|
+| D1 文法（slash/bracket/colon） | ✅ 一致 | 解析器与 ctx handler 与设计同构，live 全通 |
+| D2 canonical/prepared 二元 | ⚠️ 部分 | 模型成立，但设计说 `/transcript` 已裁撤——实现与 ctx spec 都保留它 |
+| D3 label 与失败剧集 | ✅ 一致 | label = `compaction/summary` seq，嵌套链、失败排除均成立 |
+| D4 服务形态与 read chassis | ❌ 不符 | 单一注册权 ✅、capture-delegate ✅，但 **有序 transform 链是死代码**；hashline 独立化（tasks 2.3）未交付 |
+| D5 ctx handler 重塑 | ❌ 不符 | 快照缺 **`segments`（ctx spec 明文要求）**；`system_prompt` 条件性消失；未知 key 不回显子路径 |
+| D6 披露三层 | ⚠️ 部分 | 单源/门控/description 静默 ✅；但 **bare-root 即 help 对 `skill://` 是假的**；≤600 chars 预算说法不成立 |
+| D7 Phase-2 继承式 fs backend | ⚠️ 未挂载 | 代码+单测齐（fail-soft），未挂载，设计的收益（未 wrap 的原生 read/edit 可读 `ctx://`）**未兑现** |
+| D8 验证与红线 | ✅ 纪律守住 | openspec strict 过、url-schemes 8/8 文件全绿；14 挂与 tsc 13 错已独立定性为宿主 API 漂移；未 publish |
+
+## 4. 逐项取证
+
+### D1 文法 — ✅ 一致
+
+- `selector.ts:36` `SCHEME_RE` 认 `scheme://`；`:59-60` 首标记（`:` 或 `?`）切 path/selector；`:72` `SELECTOR_EXEMPT={http,https}` ⇒ `:8443` 是端口、`?x=1` 是 query（与设计「variance」一致）。
+- `:97-99` `selPart.startsWith('raw:')` ⇒ 组合式 `:raw:N-M` 解析为 `lines`，与 `:N-M` 同构（tasks 6.2 首轮抓到的 spec gap 已修）。
+- `[<label|ordinal>]` 不进 `parseUrl`，由 handler 消费（`ctx.ts:322-329` `parseSeg` 正则 `^([a-z_]+)(?:\[(.+)\])?$`）⇒ 设计「换内容 → path/brackets；换看法 → colon modifier」在实现里成立。
+- `handlers/ctx.ts:376-380` `pickEpisode`：`String(e.label) === bracket` 精确优先，miss 回落 `Number(bracket)` 0-based —— 与设计 D1/D3 逐字一致。
+
+### D2 canonical / prepared — ⚠️ 部分（设计已过时）
+
+- 成立部分：`session` 裸=快照（`ctx.ts:335-339`，`applyFace(prepared, canonical, sel, 'prepared')`），`:raw`/行窗恒作用 canonical（`applyFace` `:200-207`）；`compactions[label]` 裸=8 段 summary、`:raw`=shadowedSeqs 原文（`:355-368`）。
+- **不符**：design.md D2 写「`/original`、`/transcript`、`/events` 子路径全部裁撤」。实际：`/original` 确实裁撤（`ctx.ts:370-374` → `CTX_BAD_PATH`），但 **`/transcript` 被保留为 canonical 别名**（`ctx.ts:334` `seg0.name === 'transcript'` → `forceCanonical`），ctx spec「Bare listing」也明文要求列出 `transcript`。live 探针 `ctx://session/transcript:1-3` 正常返回 3 行（§5）。
+- 另：design.md（D1/D5/D6）**通篇未提 `thinking` / `system` 两个集合面**，而 ctx spec 有独立 ADDED Requirement「Thinking and system collections」，实现齐备（`ctx.ts:388-436`）。design.md 是 reshape 前的产物（reshape 过程见既有实测报告 §3.2.1）。
+
+### D3 label 与失败剧集 — ✅ 一致
+
+- `ctx.ts:283` `if (e.type !== 'compaction/summary') continue` ⇒ label = summary 事件 seq；失败压缩无 summary 事件 ⇒ 天然不入档（与 spec「Failed compaction is not addressable」同构）。
+- `ctx.ts:311-313` `replacesCheckpoint = prevCheckpoint !== null && d.shadowedSeqs.includes(prevCheckpoint) ? prevCheckpoint : null` ⇒ 嵌套链（信息金字塔）成立；单测 fixture 两档嵌套断言 `compacted[1].replaces_checkpoint === 21` 绿。
+
+### D4 服务形态与 read chassis — ❌ 不符
+
+成立部分：
+- 服务零工具 + 四 wrapper 在工具层：`index.ts:14-24` 只 register handler，工具注册在 `installAgentTools`（`:169-261`）。
+- capture-before-register 纪律：`native-capture.ts` + `wiring.spec` 断言 `capture:write/grep/glob/host_extra` 全部先于 `agent-register:read`，且 `NATIVE_TOOL_NAMES = ['read','write','grep','glob']`（`native-capture.ts:57`）。
+- capture-delegate 与结构化缺省错误齐备：`NATIVE_WRITE_UNAVAILABLE`（write.ts:199）、`NATIVE_GREP/GLOB_UNAVAILABLE`（grep.ts:86 / glob.ts:84）、`NATIVE_READ_UNAVAILABLE`（read.ts:154）。
+
+**不符（实质）**：
+1. **有序 transform 链未接线**。`transforms.ts` 导出的 `createUrlTransform` / `createAnchorTransform` / `ReadTransform` **在全仓（src+test）零调用点**——仅被 `general-section.ts:23`、`fs-backend.ts:26` 当 **类型** 引入 `ReadGates`。`read.ts` 仍是内联双分支结构（`:117` urlSchemes 分支 / `:130` hashline 分支 / `:147` 终端 delegate）。
+2. 由此 `transforms.ts:50` 的注释「Scheme-prefix fork — **kept in ONE place** so every stage agrees on the split」是假的：`SCHEME_URL_RE` 在 `read.ts:73` 与 `transforms.ts:50` **各定义一份**。设计 D4「chassis 内有序 transform 链」与 url-schema spec ADDED「Read chassis with ordered transforms」目前只有「单一注册权 + 终端 delegate」满足，**链本身不存在**。
+3. 设计 D4「hashline 以 transform 身份接入（chassis 缺席时 fallback 自持最小 wrapper）」= tasks 2.3，**未做**（tasks 2.3 未勾）。当前 hashline 锚点能力**无法脱离本插件独立安装**——插件缺席即无锚点。这不是回归（旧行为相同），但 spec 的这条 SHALL 未兑现。
+
+### D5 ctx handler 重塑 — ❌ 不符
+
+成立部分（live 逐字核对，§5）：
+- identity 吸收（`ctx.ts:527-531`）：`id/createdAt/cwd/agentPreset/status/origin/delegationDepth`；`ctx://model` / `ctx://cwd` 一级 key 已移除（live `CTX_UNKNOWN_KEY`）。
+- `storage` / `totals` 用 DSH 原生字段名并做零值规范化（`:503-513`）：live 实测 `user_prompts/injected_user_messages/agent_messages/block_reasoning/block_text/block_tool-call/tool_calls/tool_results/compactions` 九键齐。
+- `compacted[]` 九字段 + 每档 8 段 ×100 字预览（`:533-541`、`sectionPreviews` `:186-194`）；顶层 `syntax` 字段（`:518`）；`hints` 三条（`:542-546`）。
+
+**不符**：
+1. **快照无 `segments`**。ctx spec MODIFIED「Curated snapshot keys」明文要求 prepared 面携带「per-compaction segments plus a `live` tail segment」，design D5 亦写「per-segment 分段（按 compaction 切段 + live 热区）」。`buildSnapshot` 全函数（`:508-550`）**无任何分段字段**，live `ctx://session` 亦无（§5）。且 **无任何单测断言它**——spec 要求与测试双缺口。
+2. **`system_prompt` 卡条件性消失**：`ctx.ts:536` `system === undefined ? undefined : {...}`，`JSON.stringify` 丢弃 undefined ⇒ 无 `request/header` 的会话里该 key 整体不存在（live 实测确实缺失）。spec 说快照 SHALL carry the card；模型侧看到的是「字段不存在」而非「字段为空」。
+3. **未知 key 不回显子路径**：spec「Unknown key echoes known keys」要求列出「currently known first-level keys **and the sub-path pointer**」。实测 `ctx://bogus` / `ctx://model` 只回 `unknown key (known: session — model/cwd folded into the session info card)`（`ctx.ts:250-253`），**无子路径清单**。（另一条兜底错误 `:556-558` 才列出全部子路径，但它只对 `session/<未知段>` 触发。）
+4. **行窗在 bracket 元素路径上被忽略**：spec 说「line windows ... on **every** resolved resource」。实测 `ctx://session/user_prompts[0]:1-1` 与 `:2-2` 返回**同一个完整两项文本**；`agent_responses[0]:1-1` 同样。代码路径（`ctx.ts:452-462`、`:476-481`）在 bracket 命中后 `return bySeq.text` / `items[ordinal].text`，**不经 `applyFace`**。
+
+### D6 披露 — ⚠️ 部分
+
+成立部分：
+- 单源：`general-section.ts:44-45` 模块期 `readFileSync` walk-up 加载包根 `url-schemes-section.md`；`package.json files` 含 `url-schemes-section.md`（漏列即 boot ENOENT，0.2.3-d 教训已内建）。
+- 门控：`generalSection(gates)` 在 `urlSchemes: false` 返回 `undefined`（`general-section.ts:88`），单测断言绿。
+- 工具 description 静默：四个 wrapper 的 `description:` 字符串（read.ts:89 / write.ts:149 / grep.ts:101 / glob.ts:99）**零 `scheme://`**——spec scenario「Tool descriptions stay scheme-silent」成立（`scheme://` 只出现在源码注释里）。
+- L3：未知 label 回显有效清单（`ctx.ts:482-489` pickEpisode 列出 labels）；超尺 `:raw` 尾行 note（`:357-361`）单测覆盖。
+
+**不符**：
+1. **bare-root 即 help 对 `skill://` 是假的**。shipped section 第 3 行写着「Reading a bare root (`ctx://`, `agent://`, `dvc://`, `skill://`) lists that scheme's surface — treat it as the scheme's help.」实测：`ctx://`（9 行 roster）、`agent://`（"no agents"）、`dvc://`（4 设备表）确实枚举；**`skill://` → `Error: skill "" is unknown or no longer available`**（`skill.ts:141` `URL_SKILL_NOT_FOUND`，因为 `splitSkillPath('')` 得空名去查注册表）；`dsh://` 裸根亦报错 `unknown resource "(empty)" — expected "docs" or "config"`（`dsh://` 未在该句里点名，但同属「静态/系统资源」）。这是**上报给模型的事实性误导**，每次会话渲染，代价是白跑一次工具调用。
+2. **≤600 chars 预算不成立**。tasks 4.1 与既有实测报告 §2 都写「≤600 chars（断言绿）」。实测 shipped 文件 = **1,788 字符 / 19 行**（`wc -c` 1768 字节）；`general-section.spec.ts` 只断言**覆盖度**（6 schemes + `:raw:N-M` + read-only + transcript/thinking/system），**没有任何预算断言**。该说法应更正。
+
+### D7 Phase-2 fs backend — ⚠️ 未挂载（spike 姿态正确）
+
+- `fs-backend.ts` 实现齐：`resolve` 拦 scheme → virtual target（`targetKey` = URL）、`stat` 合成 `{type:'file',size}`、`readText` 解引用、`writeText`/`editText` 抛 `FS_VIRTUAL_READONLY`、其余 `super`；`build()` 对 `@deepseek-ai/dsh-fs-sandbox` 动态 import 失败返回 `null`（fail-soft，`:120-127`）。
+- **未挂载**：`createUrlAwareFileSystemBackend` 在 `src/` 内零引用（只在自身模块与 `fs-backend.spec.ts`），index.ts 不 import ⇒ 设计 D7 的挂载动作（home 层同 id 行重述 `fs-sandbox`）与收益（「未 wrap 的原生 read/edit 亦能读 `ctx://`」）**均未兑现**，与 tasks 5.2「未执行」一致。
+- 三个 spec delta 里**没有 fs 相关 requirement** ⇒ 该 spike 不构成 spec 欠账，属设计内可整体放弃项。
+
+### D8 验证与红线 — ✅ 纪律守住
+
+- `openspec validate 2026-09-11-url-schemes-recallable-context --strict` → **`Change ... is valid`**。
+- url-schemes 八个 spec 文件**全绿**：`http 35 / tools-delegation 29 / ctx 19 / skill 16 / fs-backend 5 / escalation-forward 5 / wiring 4 / general-section 2` = **115 用例**。
+- 全量：`Test Files 2 failed | 37 passed (39)`，`Tests 14 failed | 473 passed (487)`。**14 挂全部同一根因**：`TypeError: SessionSeq is not a function`，落在 `test/url-schemes.spec.ts`（2，`agent://` roster）与 `test/surface-devices/agent-family.spec.ts`（12，`agent://` family roster/addressing）——**宿主 session API 漂移，与被验 change 的代码路径无交集**（ctx/compaction 全部通过）。
+- `tsc --noEmit` = **13 错**（非 0），分布：`src/index.ts` ×3（`tool/ptc-dispatch*` 事件词表、`SubagentRuntime.sendMessage`）、`src/url-schemes/handlers/agent.ts:344`（`Session.snapshotEvents` 不存在）、`src/url-schemes/index.ts:282`（宿主 `SessionPersistence` 缺 `stat`/`open`，对 `agent.ts` 的 `SessionPersistenceSurface` 不匹配）、测试 ×8（`SessionSeq`/`isSeeded`/never 推断）。**全部为宿主 API 漂移族**，无一落在 `ctx.ts`/`read.ts`/`selector.ts`/`transforms.ts`/`fs-backend.ts`。注：ctx handler 用 `sessionPersistence: unknown` duck-typing，是它躲过第 3 类错误的直接原因——design D4 的「duck-typed 抗漂移」在这一点上自证有效。
+- **未 publish**：AGENTS §〇 的 a–d 四闸未启动；tasks 6.3（user 确认后归档/发布）仍待 user。
+
+## 5. 第一人称 live 探针矩阵（本会话 `read`，即被验 read chassis）
+
+| # | URL | 观测 | 判定 |
+|---|---|---|---|
+| 1 | `ctx://` | 9 行 roster（session / transcript / compactions / compactions[label\|n] / user_prompts / tool_calls / agent_responses / thinking / system） | ✅ 与 spec 覆盖一致（tasks 3.2 的「7 行」失真） |
+| 2 | `ctx://session` | 快照 JSON：`resource/syntax/session{7 字段}/storage/totals{9 键}/compacted[]/hints[3]`；**无 `segments`**；**无 `system_prompt`**（`compacted` 空因本会话 0 压缩） | ❌ F1/F7 现场复现 |
+| 3 | `ctx://session/transcript:1-3` | 3 行 transcript（`[0000008] USER` + 正文） | ⚠️ 设计说已裁撤，实际可用（F4） |
+| 4 | `ctx://session/user_prompts[0]:1-1` | 返回**两项完整文本**（非 1 行） | ❌ F3（行窗被忽略） |
+| 5 | `ctx://session/user_prompts[0]:2-2` | 与 #4 **逐字节相同** | ❌ F3 确证 |
+| 6 | `ctx://session/agent_responses[0]:1-1` | 返回完整两项文本 | ❌ F3 确证（同代码路径） |
+| 7 | `ctx://bogus` | `Error: ctx://bogus: unknown key (known: session — model/cwd folded into the session info card)` | ⚠️ F5（无子路径清单） |
+| 8 | `ctx://model` | 同上 `CTX_UNKNOWN_KEY` | ✅ 一级 key 确实移除 |
+| 9 | `skill://` | `Error: skill "" is unknown or no longer available` | ❌ F6（section 承诺的 bare-help 不存在） |
+| 10 | `dsh://` | `Error: dsh://: unknown resource "(empty)" — expected "docs" or "config"` | ⚠️ 同类（句内未点名） |
+| 11 | `agent://` | `no agents` | ✅ 枚举成立 |
+| 12 | `dvc://` | 4 设备表（`ast_edit/ast_grep/browser/lsp`） | ✅ 与 section 的 devices 列一致 |
+
+> 未能在 live 覆盖的两点，如实声明：`/original` 与 `compactions[label]` 需有效压缩档，本会话 `compactions: 0`，故 `CTX_BAD_PATH`（/original 裁撤）只由单测 `ctx.spec` 第 8 例证明；config gates 的四个分支需改 patch 行并重启实例，本轮未做（见 F10）。
+
+## 6. 发现清单（按处置优先级）
+
+| # | 级别 | 发现 | 证据 | 建议处置 |
+|---|---|---|---|---|
+| F1 | **高** | 快照缺 `segments`（per-compaction 分段 + live 热区）——ctx spec 明文要求、design D5 明文要求、无实现、无测试 | `ctx.ts:508-550` 无该字段；live #2 | 二选一：补实现（首选，spec 是契约）或在本轮明确降级并改 spec；**不可两边都不动** |
+| F2 | **高** | read「有序 transform 链」未接线，`transforms.ts` 为死代码；`SCHEME_URL_RE` 双份与「kept in ONE place」注释矛盾；tasks 2.3（hashline 独立化）未交付 | `createUrlTransform/createAnchorTransform` 全仓零调用；`read.ts:73` vs `transforms.ts:50`；tasks 2.3 未勾 | 要么落地 extract（read.ts 走 chassis），要么把 spec 的 ADDED「ordered transform chain」降级为「单一注册 + 终端 delegate」并改注释；死代码不应留在发布面 |
+| F3 | 中 | bracket 元素路径忽略 `:N-M` 行窗 | live #4/#5/#6；`ctx.ts:452-462`/`:476-481` 不过 `applyFace` | spec 的「every resolved resource」是硬话；补 `applyFace` 一行即可，或收窄 spec 措辞 |
+| F4 | 中 | design.md D2 与实现/ctx spec 冲突（`/transcript` 保留为 canonical 别名） | `ctx.ts:334`；live #3；ctx spec「Bare listing」 | 改 design.md（存档件纠偏），不要改实现 |
+| F5 | 中 | `CTX_UNKNOWN_KEY` 不回显子路径清单 | `ctx.ts:250-253`；live #7 | 把 `:556` 那份子路径清单并入 unknown-key 消息 |
+| F6 | 中 | section 的 bare-root-as-help 对 `skill://`（及 `dsh://`）失实 | live #9/#10；`skill.ts:141` | 改 `url-schemes-section.md` 一句（点名真正支持枚举的 ctx/agent/dvc），或给 skill/dsh 补 bare 枚举 |
+| F7 | 低 | `system_prompt` 卡在无 `request/header` 时整键消失 | `ctx.ts:536`；live #2 | 输出 `{chars:0, preview:''}` 之类的显式空卡，或 spec 注明条件性 |
+| F8 | 低 | 「≤600 chars」说法不成立（实际 1,788 字符 / 19 行，无预算断言） | `wc -m url-schemes-section.md` = 1788；`general-section.spec.ts` 无预算断言 | 更正 tasks 4.1 与实测报告 §2；如确实要控体积，补一条真实的预算断言 |
+| F9 | 低 | 证据链数字漂移：ctx.spec「15/15」实为 **19/19**；§3.2.1「general-section 6/6」实为 **2/2**；tasks 3.2「roster 7 行」实为 **9 行**；tasks 3.3/3.4/6.2b 仍把 `[label]/original` 当可用面（已被 §3.2.1 的 reshape 裁撤） | 本轮 vitest 逐文件计数；live #1 | 更正 tasks.md 与实测报告，避免后续 session 按错数字验收 |
+| F10 | 低 | config gates **无工具层测试**：`urlSchemes:false`/`hashline:false` 四个分支零断言，`resolveGates` 零单测（仅 `general-section` 与 `fs-backend` 各 1 处 gate 断言） | `grep -rn 'urlSchemes: *false\|hashline: *false' test/` 仅 3 命中 | tasks 1.2 承诺的「4-gate 组合注册断言」补齐；行为本身按源码静态读到是对的 |
+| F11 | 记录 | fs backend spike 未挂载、收益未兑现（spec 无对应 requirement，属可放弃项） | `createUrlAwareFileSystemBackend` src 内零引用；design D7 | 保持 spike 姿态；若本轮放弃，在 design/报告注明「不挂载」结论 |
+| F12 | 记录 | 源码注释漂移：`selector.ts:6` 与 `resolver.ts:6` 写「All five schemes / 五个 handler」而注册了六个（含 http(s)）；`index.ts:19-22` 仍写「`read` keeps its vendored hashline file branch and **captures nothing**」（capture-read 已落地） | 文件头即证 | 顺手更正，避免下一轮再被旧注释误导 |
+
+## 7. 结论
+
+1. **design.md 的机制主干成立**：D1 文法、D3 label/嵌套链、D2 的 canonical/prepared 模型、D6 的单源+门控、D8 的验证纪律，均在实际代码与活体行为上找到对应，无一处是空头设计。
+2. **但 design.md 已被 reshape 甩开**：`/transcript` 的存废、`thinking`/`system` 两面、`/original` 的重塑，设计文本停在回改之前（既有实测报告 §3.2.1 记录了 user 的 reshape 批示）。**设计文件需要一次对齐修订**，否则它作为「研究底稿 → 决策」的索引会持续误导后续 session（F4/F9）。
+3. **两项实质欠账必须处置**：F1（快照 `segments`，spec 明文）与 F2（read transform 链，spec ADDED 明文）。两者都不是文档问题，是**契约与实现的差**；要么补实现，要么改 spec——按 AGENTS §〇 的验收同类原则，**不能靠「单测绿」把 spec 要求悄悄抹掉**（F1 恰恰是「spec 有、测试无」才活到今天的）。
+4. **发布红线未触碰**：本轮无 `npm publish`、无 prod 改动、无 tag。tasks 6.3（user 确认 → 归档 → 发布）仍原样待 user 裁决。
+
+**附带产物**（可复核）：
+- `.scratch/verify-url-schemes-vitest.log` — 全量单测原始输出（含 14 例失败的完整堆栈）
+- `.scratch/verify-url-schemes-tsc.log` — tsc 13 错原始输出

package/docs/50_test-reports/2026-09-12-url-schemes-recallable-context-/345/256/236/346/265/213/345/211/247/346/234/254.md

@@ -0,0 +1,44 @@
+# URL Schemes 可回溯上下文 — 4999 实测剧本（change 2026-09-11-url-schemes-recallable-context）
+
+> 实例：`http://127.0.0.1:4999/?token=<redacted>`（systemd 单元 `dsh-4999-test`，DSH_HOME=仓库内 `.dsh-test`，构建=本 change 源码树；2026-09-12 user 指令下线 omp-web-4999-test/lan-relay 后由 4986 迁入 4999）
+> 驱动方式（0.2.3-d 先例）：user 在 GUI 打开上述 URL 开一个**新会话**，把下方「粘贴给 agent 的指令」整段贴进去；agent 完成后把它的回复贴回本 change 的实测报告。
+> **✅ 已执行（2026-09-12，agent 经 HTTP RPC 自驱，10/10 判定全过）**：被测会话 `session-eec306df`，结果与判定对照见实测报告 §3.2；本剧本存档留作复演模板。
+
+## 粘贴给 agent 的指令
+
+```text
+请按顺序执行以下第一人称实测，每步原文贴出关键输出（不要省略）：
+
+1. read ctx:// — 贴出完整 roster。
+2. read ctx://session — 贴出 JSON 的 totals 与 compacted 字段（此时 compacted 应为空清单或不存在条目）。
+3. 为了制造可压缩的历史：请连续 read 以下三个文件并各贴出一行内容摘要——
+   dashr/src/url-schemes/transforms.ts、dashr/src/url-schemes/handlers/ctx.ts、dashr/src/url-schemes/fs-backend.ts。
+4. 执行 /compact（手动压缩一次）。完成后 read ctx://session/compactions — 贴出清单；记下第一个 label（记为 L1）。
+5. read ctx://session/compactions[L1] — 贴出 8 段 summary 的前 5 行。
+6. read ctx://session/compactions[L1]:raw — 贴出前 10 行与总行数；确认包含第 3 步读过的文件名。
+7. 再正常对话 2-3 轮（例如问「transcript 格式 v1 冻结是什么意思」）后再次执行 /compact（第二次，嵌套前档）。然后 read ctx://session/compactions — 贴出新清单；确认第二个条目的 replaces_checkpoint 等于 L1 的 checkpoint_seq。
+8. read ctx://session/compactions[<第二个label>] — 贴出 8 段前 5 行。
+9. read ctx://session/compactions[L1]:raw — 关键回归：第一次压缩的原文在第二次压缩后必须仍可读；贴出前 10 行，确认包含第 3 步的文件名与 'hello world' 级别的原始内容。
+10. read ctx://session/compactions[L1]/original:1-5 — 贴出行窗结果。
+```
+
+## 判定基准（对照 mapping doc §9–§15.11）
+
+| # | 断言 |
+|---|---|
+| 1 | roster 含 `ctx://session`、`compactions`、语法提示 |
+| 2 | snapshot JSON 含 `totals`/`compacted: []`/`syntax` 字段；`session.id` 正确 |
+| 4 | manifest 出现 1 个条目，label = compaction/summary 事件 seq |
+| 5 | 8 段 summary 原文（prepared face） |
+| 6 | `:raw` = 被 shadow 的原文（含第 3 步文件内容），**不含** summary 的 `## ` 段落 |
+| 7 | 第二条目 `replaces_checkpoint` = L1 的 checkpoint_seq（嵌套链） |
+| 9 | **嵌套后 L1 原文仍可读**（log 永不删除 ⇒ 全链可寻址） |
+| 10 | `/original:1-5` 行窗作用于 canonical |
+
+已知边界（非缺陷）：`ctx://model`/`ctx://cwd` 一级 key 已按 spec 移除（信息卡并入 `ctx://session`）；未挂 fs backend spike 时原生 read 不解析 scheme（chassis 内 URL branch 承担全部 scheme 寻址）。
+
+## 环境事实
+
+- 实例：4999（systemd `dsh-4999-test`，restart = `systemctl --user restart dsh-4999-test`；日志 `.scratch/dsh-4999.log`；2026-09-12 自 4986 迁入）
+- 事故记录：4988 为 superd multi-context PoC 占用（AGENTS §二 勿杀）——首轮启动误占即 EADDRINUSE（loud fail，符合预期）后改 4986；2026-09-12 user 指令下线 omp-web-4999-test / omp-web-lan-4999-relay 后迁入 4999。
+- 构建链：canonical rsync → devDeps 手术（14 × workspace:*）→ `pnpm --filter better-dsh exec tsdown` → `tsx scripts/build-client.ts`。

package/docs/50_test-reports/2026-09-12-url-schemes-recallable-context-/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,89 @@
+# URL Schemes 可回溯上下文 — 实测报告（change 2026-09-11-url-schemes-recallable-context）
+
+> 状态：**五层验证全部完成**（单测 + 真实日志矩阵 13/13 + 三轮自驱实测 ALL PASS：10/10、13/13、9 调用 8 ok+1 预期错误）；剩余 = user 发布确认（AGENTS §〇 单次确认；npm can wait 已裁定）。详见 §3.2 / §3.2.1 / §3.2.2。
+
+## 1. 被测运行时与环境
+
+| 实例 | systemd `dsh-4999-test`，`http://127.0.0.1:4999`（token 见启动日志 `.scratch/dsh-4999.log`；2026-09-12 自 4986 迁入，见 §4） |
+|---|---|
+| 实例 | systemd `dsh-4986-test`，`http://127.0.0.1:4986`（token 见启动日志 `.scratch/dsh-4986.log`） |
+| 源码树 | `upstream/deepseek-harness`（0.1.5-rc.2 线）+ `packages/better-dsh/better-dsh`（canonical `./dashr` 的 rsync 副本 + devDeps 手术 14 × workspace:*） |
+| 构建 | `pnpm --filter better-dsh exec tsdown`（8 files, 509.80 kB）+ `tsx scripts/build-client.ts`（client 34ms） |
+| DSH_HOME | 仓库内 `.dsh-test` |
+| 健康 | shell 200；log 零错误（首次 4988 尝试撞 superd PoC 端口 EADDRINUSE loud fail 符合预期，已清理改 4986——事故记于 §4） |
+| 健康 | shell 200；token→cookie 200；log 零错误（user 复核 4999：UI 与既有功能无破坏性回归；端口史见 §4） |
+## 2. 代码交付（单测证据，全部绿）
+
+| 域 | 交付 | 测试 |
+|---|---|---|
+| 正名 | `dsh-url-schema` → **`dsh-url-schemes`**（目录/服务名/类名/测试全链；`git mv` 保历史） | tsc 13/13 = stash 基线（diff 仅路径位移）；全仓引用零残留 |
+| config gates | `Config { urlSchemes?, hashline? }`（default true，patch 行 `config:` 可达）：write/grep/glob wrapper 与 read URL branch 随 `urlSchemes` 门控；edit/undo + lsp listener 随 `hashline` 门控；read 注册条件 `(urlSchemes ‖ hashline)` | tsc/vitest 基线零新增 |
+| capture-delegate | `NATIVE_TOOL_NAMES` 增 `read`（语义名捕获，session-start 先于自注册）；`capturedRead` 终端 delegate + `NATIVE_READ_UNAVAILABLE`；branch 条件 `gates.hashline && !isScheme`（scheme 路径不落文件读） | wiring.spec 4/4（含 CTX_NO_PERSISTENCE 新断言） |
+| ctx:// 重塑 | `session` = 统计快照（prepared）‖ transcript（canonical）；identity/model/cwd 折叠；compactions 清单（label/checkpoint_seq/嵌套链/8 段预览）+ `[label|n]` 寻址（label=summary seq 精确优先、0-based 回落）+ `:raw`/行窗恒作用 canonical；`/original` 路径形；`CTX_UNKNOWN_KEY/NO_SUCH_ELEMENT/BAD_PATH/BAD_SELECTOR` 回显式错误 | `ctx.spec` **15/15**（fixture 含 2 嵌套剧集） |
+| 披露 | `url-schema:general` section（≤600 chars，`urlSchemes` gate 门控，无空承诺）+ 快照顶层 `syntax` 字段 + 超大原文行动 note | `general-section.spec` 2/2 + ctx.spec syntax 断言 |
+| fs spike（phase-2） | `createUrlAwareFileSystemBackend`：动态 import + `UrlAwareFileSystem extends SandboxedFileSystem`（resolve 拦 scheme → virtual FsTarget；stat 合成 file；readText 解引用；写系 virtual → `FS_VIRTUAL_READONLY`；其余 super）；整体 fail-soft | `fs-backend.spec` **5/5**（真 cordis Context + sandboxPolicy stub + 合法 LocalConfig 下：resolve→stat→readText 全链、只读强制、gate 关停） |
+
+全量回归：**vitest 14 failed | 458 passed (472) = 0.2.3-d 文档基线同数同族**（SessionSeq 既有 API 漂移，零新增）；tsc 13 = 基线。
+
+## 3. 真实日志矩阵验证（✅ ALL PASS，2026-09-12）
+
+驱动器 `dashr/test/url-schemes/verify-live.mts`（npx tsx；走完整 UrlResolver + selector 解析 + ctx handler 链）对真实 prod 会话 **session-788be2e1**（35,562 events、3 层嵌套压缩）执行 13 项断言，全部 PASS：
+
+- roster 列出 session 面
+- 快照：totals.compactions = 3；identity 卡正确
+- manifest labels = [109245, 221217, 338001]
+- 嵌套链：ep1→null；ep2→109246；ep3→221218
+- episode prepared = 8 段 summary（含 Primary Request / Critical Context）
+- `:raw` = 原文 span（含 ep1 CHECKPOINT；长度 > 10 × summary）
+- `/original:1-3` 行窗 = 3 行
+- 嵌套后 ep1 原文仍可达（>10000 chars）
+- transcript 含 ≥2 个 CHECKPOINT
+
+驱动过程修出 2 个真 bug：① selector undefined 归一化（applyFace 崩）；② applyFace 调用点签名错位（face flag 与 selector 参数串位）。live-log 驱动价值实证。
+
+### 3.2 in-agent 集成确认（✅ ALL PASS，2026-09-12 自驱实测收口）
+
+**验收口径**（AGENTS §〇 第 2 条：验收标准必须与改动点同类——本改动是 surface 给大模型的工具）：§3.1 live-log 驱动验证的是 `UrlResolver → selector → ctx handler` 链在真实数据上的正确性，但绕过了工具面本体——read 工具 URL branch 的注册与 gates、capture-delegate（`NATIVE_TOOL_NAMES` 先于工具自注册）、`url-schema:general` 披露段落进真实 system prompt、以及模型对 `ctx://` 语法的实际使用。本节以一次真实 agent 会话补齐全部四项。
+
+**执行方式：agent 自驱（HTTP RPC）**。0.1.5-rc.2 的 `/api` 是标准 HTTP JSON RPC（复审推翻原记「SPA 非 REST 需逆向传输层、成本高」）：token URL 换 cookie → `POST /api/<namespace>/<method>`（斜杠两段形），payload = `{args:{<首参名>:…}}`（typert 具名参数派发）；实际用 `session/create`、`session/prompt`、`commands/execute`（`agentId` + `line:'/compact'`）。每步均为真实 agent turn 内模型自调 read 工具，与 GUI 形态证据价值等价（被测路径全在 host 侧）。驱动脚本 `.scratch/url-schemes-live-driver*.sh`，过程产物 `.scratch/url-schemes-live/`。
+
+**被测会话**：`session-eec306df-e5da-4781-a9a8-b547c361ffa0`（4999 / `.dsh-test` / cwd = 仓库根）。5 个 turn、2 次嵌套 `/compact`（L1 = label 46：13 items / 16,411 tok，shadowed 8..38；L2 = label 124：23 items / 42,672 tok，shadowed 47..118——起点 47 恰为 L1 的 checkpoint seq）、**17 次工具调用（16 ok / 1 次暴露 spec gap，见下①）**，覆盖 roster → 快照 → 灌压 → 嵌套压缩 → manifest → label 下钻 → `:raw` → 行窗 → `/original:N-M` → 跨压缩旧档回归；另含 3 次模型自发的 eval-pad 组合调用（`await tool.read({path:'ctx://…'})`）。
+
+**判定基准对照（剧本 10 步）**：
+
+| # | 断言 | 结果 |
+|---|---|---|
+| 1 | roster 含 `ctx://session`、compactions、语法提示 | ✅（原生 read 返回 roster 全文） |
+| 2 | 快照 `totals`/`compacted: []`/`syntax`/`session.id` | ✅ |
+| 4 | manifest 1 条目，label = compaction/summary 事件 seq | ✅ label=46（summary 事件 seq 46） |
+| 5 | `[46]` 8 段 summary（prepared face） | ✅ 8,309 chars，8 段键齐 |
+| 6 | `:raw` = 被 shadow 原文，含第 3 步文件名 | ✅ 1,053 行 / 62,586 chars；三文件名行级命中（3/3/2 处，与 span 边界自洽） |
+| 7 | 嵌套链 `replaces_checkpoint` = L1 checkpoint_seq | ✅ 124 条目 replaces_checkpoint=47 = 46+1；L2 shadowed 起点=47 无重叠 |
+| 8 | `[124]` 8 段 summary | ✅ 12,332 chars，段标题与 L1 同构 |
+| 9 | **二次压缩后 L1 原文仍可读** | ✅ `[46]:raw` 63,893 chars 全文逐字节稳定，三文件命中行号跨压缩一字不差 |
+| 10 | `/original:1-5` 行窗作用于 canonical | ✅ 5 行，与 `:raw[:5]` 逐字相等 |
+
+**第一人称机制发现（测试 agent 自证）**：① `:raw:1-10` 组合 selector 被拒（`Error: invalid line selector…`）——**live 实测抓到的 spec gap**：§15 原始裁定第 2/3 条要求 `:raw:N-M` ≡ `:N-M` ≡ `/original:N-M`（行窗恒作用 canonical，`:raw` 前缀在行窗场景冗余但必须合法），而解析器只认整段 `raw`；`/original:N-M` 实测可用。已列发布前修复（selector 解析放行 `raw:` 前缀组合，语义零变化）。② 裸 label + `:N-M` 行窗索引 canonical 面（`:1-10 == :raw[:10]` 字节为真），绕过 prepared；③ `:raw` ≡ `/original` 全量（1053 行相等），差异仅 oversize 守卫挂点；④ 行号跨压缩稳定（shadowedSeqs 固定 ⇒ 渲染稳定）；⑤ oversize 哨兵未误触发（62,586 < 65,536）。
+
+**四项验收口径逐项闭合**：read URL branch + gates 双分支（ctx:// 走 URL、文件走 hashline 锚点格式，互不串线）✅；capture-delegate 语义捕获生效（17 次调用全部进入本插件 read chassis，原生 read 不识 ctx://）✅；披露段生效（模型首试即正确使用 label/`:raw`/`:N-M` 寻址）✅；模型实际使用 ✅。
+
+### 3.2.1 二轮回归（✅ ALL PASS，2026-09-12 晚；五点对齐 + 工具/披露段重塑后）
+
+§3.2 首轮实测抓到 `:raw:1-10` 被拒的 spec gap（§15 原始裁定第 2/3 条）后，user 批示重塑：组合 selector 放行、`/original` 子路径删除（≡ `:raw`，超尺守卫移至无窗 `:raw`）、`transcript` 保留为别名、新增 `thinking`/`system` 两个集合面、四工具 description 抹平为原生原文（read 保留 hashline 锚点条款、不再提及 scheme）、披露段改为包根 `url-schemes-section.md` 独立文件（6 schemes + 语法与 `:raw:N-M` ≡ `:N-M` + variance/只读双免责 + 一级资源覆盖 + bare-root 即 help；walk-up 加载 + `package.json files` 补录；dvc devices 实测 ids `ast_edit/ast_grep/browser/lsp`；catalog 保留为错误消息单一源）。双 sub-agent 并行实现、本人统一验收：tsc 13 基线、vitest 473 passed / 14 failed（基线同族；ctx.spec 19/19、general-section 2/2——设计核查 F9 更正原稿「6/6」为两文件合计数）、openspec validate 2/2。
+
+**二轮自驱实测**（会话 `session-1f5a930b`，驱动器 `.scratch/url-schemes-live-driver3.sh`）：13 次工具调用 **13/13 判定过**——roster 9 行含 `thinking`/`system` 无 `/original`；**`compactions[56]:raw:1-10` 与 `compactions[56]:1-10` 逐字节相同**（spec gap 修复实证）；`compactions[56]/original` → `CTX_BAD_PATH`（错误回显注明被 `:raw / :raw:N-M` 取代）；`thinking` 索引与 `[0]` 单块全文、`system` 索引与 `:raw` 9,786 chars 全过；压缩链正常（label 56，17 items / 18,706 tok）。**新披露段实证落进真实 system prompt**（`system/message` 事件含 `Internal URLs (dsh-url-schemes)` 全文，`:raw:N-M`/`ast_edit`/只读免责等 6 处命中）；`request/header` 不携带 tools schema，description 抹平由单测层证明。
+### 3.2.2 设计核查处置回归（✅ ALL PASS，2026-09-12 深夜；三轮自驱）
+
+design 验证报告（4999 实例自检，F1–F12）处置落地：**F1** 快照新增 `segments`（per-compaction 段 + `live` 尾段，spec 契约补齐）；**F3** bracket 元素路径接入 `applyFace`（行窗恒可用）；**F5** 两处 `CTX_UNKNOWN_KEY` 均带 bare-root 指针；**F7** `system_prompt` 显式空卡恒在；**F6** section bare-root 句修正（skill://、dsh:// 需首段）；**F8/F9** 文档数字修正（tasks.md/本报告）；**F10** 新增 gates.spec 5/5（resolveGates 矩阵 + read 三分支路由）；**F12** 过时注释修正；**F4/F11** design.md 对齐块 + spike 不挂载结论；**F2 user 裁定 no goal**（不做，FS 层接替）；新增 `ctx://session/injections` 集合（user 指令）。验证：ctx.spec **23/23**、gates.spec 5/5、tsc 13 基线、openspec 2/2、全量 **482 passed / 14 failed**（基线族）。
+
+**三轮自驱实测**（会话 `session-798157fc`，驱动器 `.scratch/url-schemes-live-driver4.sh`）：9 次工具调用 8 ok / 1 次预期错误——roster 10 行；快照 `segments` live 段实测在场（压缩前单 live 段 {start:0,end:22,items:23}）、`system_prompt` 空卡恒在、`injected_user_messages: 2`；`injections` 索引（2 条）/`:raw` 54,581 chars/**agent 自发 `injections:raw:1-6` 组合分页**（大注入纪律性行为自证）；`user_prompts[0]:1-1` → 单行 `[0000008] USER`（F3 实证）；`ctx://bogus` 错误带 `bare ctx:// lists the full roster` 指针（F5 实证）；压缩后 `compactions[46]:raw:1-5` 组合正常（label 46，13 items / 7,889 tok）。
+
+## 3.5 结论
+实现（P0/P1/P2 + 五点对齐重塑 + 设计核查处置）与五层验证全部完成且零回归：单测（ctx 23/23、general-section 2/2、gates 5/5、fs-backend 5/5、wiring 4/4）；真实日志矩阵 13/13（§3.1）；in-agent 第一人称实测三轮（§3.2 一轮 10/10、§3.2.1 二轮 13/13、§3.2.2 三轮 9 次调用 8 ok + 1 预期错误，均自驱）。tsc 13/13 基线；vitest 14 failed | 482 passed = 基线同族。change 状态：**代码 + 验收完成，等 user 发布确认**（AGENTS §〇 单次确认红线；npm can wait 已裁定）。fs backend spike（5.x）**维持不挂载结论**（F11；FS 层挂载 + 工具解绑为下一 change）；F2 transform 链 user 裁定 no goal（不落地，由 FS 层接替）。
+（2026-09-12 22:0x 修订：上段为三轮前的旧结论，已由上方五层验证版取代；保留一行删除记录以防引用漂移。）
+## 4. 事故与边界记录
+
+- 4988 端口为 superd multi-context PoC 占用（AGENTS §二 勿杀）——首次启动误撞即 EADDRINUSE loud fail，已清理本单元改 4986；2026-09-12 按 user 指令下线 omp-web-4999-test / omp-web-lan-4999-relay 后迁入 4999（单元 `dsh-4999-test`，日志 `.scratch/dsh-4999.log`），4986 时代完成的验证记录不受端口迁移影响。
+- 自驱驱动器调试修出 3 个 wire/脚本事实（对后续自驱有复用价值）：① `/api` endpoint 只收斜杠两段形（`session/list`），点号形 404；② typert payload 必须整信封 + 恰一个 plain-object `args` 键（漏信封报「invalid client-request」）；③ `commands/execute` wire 参数名是 `agentId`（client 代理把方法首参 `agent` 改名映射），且 jq 的 `//` 运算符把 `false` 当 falsy——`running` 布尔判断必须用 `== false` 显式比较，否则 idle 轮询永假（曾致 P1 后误判超时，实际 turn 已完成）。
+- defineTool const 泛型推断在改写 literal 下断裂 ⇒ read chassis 保留原 literal 结构、以 gates + capturedRead delegate 实现语义（transform 链抽象已建于 `transforms.ts`，extract 为后续机械步骤）。
+- 红线：**npm publish 前必须 user 单次明确确认**（AGENTS §〇）；本报告即确认前置材料。

package/docs/50_test-reports/2026-09-12-url-schemes-/345/205/255scheme/345/206/222/347/203/237/344/270/216/350/276/271/347/225/214/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,198 @@
+# dsh-url-schemes 六 scheme 冒烟与边界实测报告
+
+- 日期：2026-09-12
+- 被测对象：`dashr/src/url-schemes/` 的六类 URL scheme（`skill://`、`agent://`、`dsh://`、`ctx://`、`dvc://`、`http(s)://`）在活体 runtime 中的 `read`/`write`/`grep`/`glob` 行为。
+- 被测运行时：**本 agent 自己所在的活体实例** —— `dsh web` @ `http://127.0.0.1:4999`（`DSH_WEB_URL`），`DSH_HOME=/home/u1/workspaces/dashr/.dsh-test`，session id `session-92ef9c82-fbf8-4b71-87af-a92125e0734c`，cwd `/home/u1/workspaces/dashr`，agentPreset `standard`。
+- 方法：**第一人称实测**——全部调用由本 agent 在真实 runtime 中发出（`read`/`write`/`grep`/`glob` 工具 + `eval` pad 内 `await tool.*`），无静态推断、无人工转写返回值。`dvc://` 写路径的"是否真落地"由回读文件系统二次确认。
+- change：无（本轮为既有能力的系统冒烟，非某个 change 的验收）。
+
+---
+
+## 0. 结论
+
+> **gates 标签（2026-09-13 补）**：本报告实测于 `urlSchemes: true + hashline: true`（DASHR read 包装在场）。「六 scheme read 全可达 6/6」仅在该组合下成立；`hashline: false` 下的可达性矩阵见《2026-09-13-hashline-off下scheme可达性工具面不对称-实测报告.md》。
+
+| 判定项 | 结果 |
+|---|---|
+| 六类 scheme 在 `read` 上全部可达 | ✅ 6/6 |
+| 未登记 scheme / 已登记只读 scheme 的写拦截 | ✅ 三类错误各自精确（`URL_READ_ONLY` / `URL_WRITE_UNSUPPORTED` / `URL_UNREGISTERED_SCHEME`） |
+| `dvc://` 写是否**真实执行**（非 dry-run 空转） | ✅ `ast_edit` `dryRun:false` 改写落盘，回读确认 |
+| 选择器四形态（`:raw` / `:N-M` / `:path/` / `?q=`） | ✅ 基本全通；目录列表上的 `?q=` 不过滤（§3.3） |
+| `http(s)://` selector-exempt（端口/查询不误解析） | ✅ `:443` 与 `?x=1` 均原样进请求 |
+| 内容型 scheme 的 `grep`/`glob` 支持 | ⚠️ `grep` 经 `/dev/shm` 物化可用；`glob` 的 URL-in-`path` 分支在 `dsh://docs` 上失效（§3.4） |
+| **`dvc://` 结果的 wire 可见性** | ❌ **缺口**：`write` 渲染面只输出 `Executed dvc://<device>`，设备 payload 仅存在于结构化 `after` 字段（§3.1） |
+
+**一句话**：六类 scheme 功能面完整、错误分类精确、`dvc://` 写是真执行；唯二值得处理的是 **`dvc://` 设备结果在渲染文本里丢失**（直接影响 `ast_grep`/`lsp`/`browser` 的可用性），以及 **`glob` 在 `dsh://docs` 上的 path 分支空转**。
+
+---
+
+## 1. 被测对象与环境事实
+
+| 项 | 值 |
+|---|---|
+| 运行时 | `DSH_HOME=/home/u1/workspaces/dashr/.dsh-test`；`DSH_SESSION_ID=session-92ef9c82-fbf8-4b71-87af-a92125e0734c`；`DSH_SHELL=1` |
+| GUI 端点 | `http://127.0.0.1:4999`（监听于 `127.0.0.1`）；直连无 token 返回 **401** `dsh web authentication required; reopen the URL printed by dsh web.`（≈133 B，空 `<title>`） |
+| 方案单源 | `dashr/src/url-schemes/catalog.ts` 的 `SCHEME_CATALOGUE`（六条、`SCHEME_NAMES` 排序后 = `agent, ctx, dsh, dvc, http, https, skill`） |
+| 实现入口 | `dashr/src/url-schemes/index.ts`（挂载）、`resolver.ts`（端到端解析）、`selector.ts`（统一选择器）、`handlers/*`（六 scheme）、`tools/{read,write,grep,glob,materialize}.ts`（工具改写） |
+| 设备实现 | `vendored/devices/ast/ast-device.ts`（`ast_edit`/`ast_grep`）、`vendored/devices/browser/browser-device.ts`、`vendored/devices/lsp/lsp-device.ts` |
+| 已核 ctx 快照 | `ctx://session`：segments（live 0–34）、`system_prompt.chars = 0`、totals 与后续增长一致 |
+| 临时物化 | `grep` 对 URL 内容物化到 `/dev/shm/dashr-url-*/content.txt`；调用后目录被清理（收尾核 `/dev/shm` 为空） |
+
+---
+
+## 2. 逐 scheme 实测矩阵
+
+| Scheme | 已测形式 | 实测结果 |
+|---|---|---|
+| `skill://` | 裸根；`skill://dsh-dev-skill`；`/SKILL.md`；`/chapters/ch01-user-guide.md`；`:1-4`；`glob` 列目录 | 裸根 → `skill "" is unknown or no longer available`；`dsh-dev-skill` → 全文（= `.agents/skills/cordis-dsh-dev/SKILL.md`）；子文件可读；`:1-4` 正确截 4 行；`glob` 返回 26 个真实相对路径 |
+| `agent://` | 裸根；`agent://<原始id>`；`<原始id>/transcript`；`:1-8`；`agent://<label>`；含 `:` 的 label | 裸根 → `no agents`（无子 agent 时）/ 之后为 4 列表格；settled child 原始 id → 产出物 `pong`；live child transcript 可读并可开窗；label 可寻址；含 `:` 的 label → 选择器解析错误（§3.5） |
+| `dsh://` | 裸根；`/docs`；`/docs/subsystems`；`/docs/subsystems/slots.md?q=priority`；`/config`；`:path/` 点路径（含数组下标） | 裸根 → `expected "docs" or "config"`；目录列 JSON 数组；文件可读；`?q=priority` → 3 行命中；`/config` → 完整配置 JSON；`:path/permission.defaultPreset` → `workspace-write`；`:path/llm-deepseek.models.0.id` → `deepseek-flash` |
+| `ctx://` | 裸根；`transcript`；`system`；`thinking[0]`；`user_prompts[0]`；`tool_calls[n]`；`agent_responses[0]`；`injections:raw`；`compactions`；`:raw:N-M` | 全部可读；`[n]` 按 0 基序号或事件 seq 双寻址；越界报错带集合长度；`compactions` 无内容 → `(no compactions recorded)`；`:raw:1-3` ≡ `:1-3` |
+| `dvc://` | 裸根；设备文档（4 个）；`write` 执行（`ast_grep`/`ast_edit`/`browser`）；非法参数；尾部 `/sub` | 裸根 → 4 行设备表；设备文档 + usage 提示；写执行见 §4；非法 JSON → 带解析信息的错误；`dvc://browser/ignored-sub` → 仍返回 browser 文档（首段寻址） |
+| `http(s)://` | `read` 原始 GET；`web_fetch` 解码；`?x=1`；`:443`；loopback | `read https://example.com` → 原始 HTML（带 `[url-fetch]` 前缀）；`web_fetch` → 解码纯文本；查询与端口均原样保留；`127.0.0.1` 被拒（§3.6） |
+
+---
+
+## 3. 关键发现
+
+### 3.1 `dvc://` 设备结果在 wire 渲染面上不可见（唯一实质性缺口）
+
+`tools/write.ts` 对 `dvc://` 写构造 `WriteOutcome{ operation:'execute', after: JSON.stringify(result,null,2) }`，但 `render` 只输出：
+
+```
+const verb = … value.operation === 'execute' ? 'Executed' : …
+return [{ type: 'text', text: `${verb} ${value.path}` }]
+```
+
+→ 渲染文本恒为 `Executed dvc://ast_grep`。设备 payload 只在结构化 `after` 里。
+
+实测对照（同一次 `ast_grep` 调用）：
+
+- 直接 `write dvc://ast_grep` → 模型侧只看到 `Executed dvc://ast_grep`；
+- `eval` pad 内 `await tool.write({"file_path":"dvc://ast_grep", …})` → 完整 JSON：`totalMatches:143`、`filesWithMatches:28`、`filesSearched:162`、`limitReached:true`、`matches[]`（含 `byteStart/startLine/…`）、`parseErrors[]`。
+
+**影响**：模型直调 `ast_grep`/`lsp`/`browser` 拿不到任何结果数据（既无匹配也无报错），而这三个设备恰是输出价值最高的三个。建议 `write.ts` 的 device 分支把 payload 一并渲染进文本（或以可读摘要进文本、全量进 structure）。这是本轮唯一建议改代码的点。
+
+### 3.2 `skill://` 按 frontmatter 名寻址，而非目录名
+
+`skill://dsh-dev-skill` 命中，其解析路径为 `.agents/skills/cordis-dsh-dev/`——目录名 `cordis-dsh-dev` 反而不被接受（`skill "cordis-dsh-dev" is unknown`）。同理 `superpowers`（顶层无 `SKILL.md`）不可寻址，裸 `skill://` 亦报未知。属正确语义（skill 名 = frontmatter `name`），但"猜目录名"是最自然的错误路径，可考虑错误信息附带候选名提示。
+
+### 3.3 `?q=` 在目录列表上不过滤
+
+- `dsh://docs/subsystems/slots.md?q=priority` → 正确返回 3 行命中（含行号与上下文）；
+- `dsh://docs/subsystems?q=slots` → 返回**未过滤**的完整 98 项目录列表。
+
+即查询选择器只在"文件内容"语义下生效，目录列表（JSON 数组）上的 `?q=` 静默失效。建议改为：JSON 无匹配路径时对列表做行过滤，或明确忽略时给出提示。
+
+### 3.4 `glob` 的 URL-in-`path` 分支在 `dsh://docs` 上空转
+
+`tools/glob.ts` 头注声称 "path-backed schemes (`skill://`, `dsh://docs`) implement the handler's optional `resolvePath`"，但实测：
+
+- `glob({path:"skill://dsh-dev-skill", pattern:"ch01*.md"})` → ✅ 1 个文件（pattern 生效，any-depth 语义正确）；
+- `glob({path:"dsh://docs/subsystems", pattern:"slots.md"})` → ❌ `(no output)`。
+
+对照 `glob({pattern:"dsh://docs/subsystems"})` → ✅ 返回列表（content-backed "非空行即列表" 分支）。结论：`dsh://docs` 实际走 content-backed，`glob-in-path` 把列表 JSON 物化成 `content.txt` 后自然搜不到 `slots.md`。**头注与实现不符（注释过期）**，建议二选一：给 dsh docs 补 `resolvePath`，或订正注释。
+
+### 3.5 含 `:` 的 agent label 无法寻址
+
+`agent://Dummy child for agent:// test` → `invalid line selector ":// test" — expected N, N-M, or N-M,N2-M2`。原因是 `parseUrl` 的 path 截断在第一个 `:`，label 中的 `://` 被当成选择器。**原始 session id 始终可寻址**（本轮据此拿到 settled child 的 `pong` 产出物）。属方案语法的固有边界，值得在 `agent://` 文档里点明"label 含 `:` 时请用原始 id"。
+
+### 3.6 `http(s)://` 的两条路径与 SSRF 门
+
+- `read https://example.com` → 原始 curl 式 GET（返回完整 HTML，前缀 `[url-fetch] plain-text result of a direct HTTP GET (curl-equivalent). No JS execution or interaction`）；
+- `web_fetch https://example.com/` → 解码后的纯文本；
+- `read https://example.com:443/` 与 `?x=1` → 原样进请求（selector-exempt 生效，未误判为行选择器/点路径）；
+- `web_fetch http://127.0.0.1:4999/` → ❌ `URL hostname "127.0.0.1" resolves to a non-public IP address`（私网/回环 SSRF 门，与官方文档 Ch1 "web_fetch to literal private addresses is refused" 一致）；
+- `dvc://browser` 走设备路径**可合法访问 loopback**：`open http://127.0.0.1:4999` → `{ok:true,url:"http://127.0.0.1:4999/",title:""}`；页内求值 `document.title` → `""`、`bodyLen:133`。经 curl 侧核验，该 133 B 即 **401 认证栅栏文本**——浏览器探针到达了服务端但未携带 token（预期行为，非传输故障）。
+
+### 3.7 错误分类精确、可直接排障
+
+| 触发 | 返回 |
+|---|---|
+| `write ctx://session/transcript` | `ctx:// is a curated read-only snapshot — write to ctx://session/transcript is not supported`（`URL_READ_ONLY`） |
+| `write skill://dsh-dev-skill/SKILL.md` | `write to skill:// is not supported (read-only scheme, or its write channel is not wired yet)`（`URL_WRITE_UNSUPPORTED`） |
+| `write foo://bar` | `no handler registered for scheme "foo" (registered: agent, ctx, dsh, dvc, http, https, skill)` |
+| `read dvc://nope` | `unknown device: nope` |
+| `read ctx://session/tool_calls[999]` | `no such element (collection "tool_calls" has 40 items, 0-based; labels are event seqs)` |
+| `write dvc://ast_grep`（非 JSON） | `dvc:// write dispatch: device "ast_grep" requires a JSON args payload (Unexpected token 'h', "this is not json" is not valid JSON)` |
+| `dvc://lsp`（action 缺失 / 二进制缺失） | 先 `unknown action null — expected "diagnostics", "definition", "references", "hover", or "format"`；补 `action` 后 → `language server binary "typescript-language-server" not found … — npm install -g typescript-language-server typescript` |
+| `dvc://browser`（action 缺失） | `unknown action null — expected "open", "run", or "close"` |
+
+### 3.8 临时物化无残留
+
+`grep` 对 `dsh://docs/subsystems/slots.md` 的搜索把内容物化到 `/dev/shm/dashr-url-c2cNM0/content.txt` 后由 `finally` 清理；收尾核 `/dev/shm` 已空。符合 `tools/materialize.ts` 的设计（shm 优先、>8 MiB 回退 `os.tmpdir()`）。
+
+---
+
+## 4. `dvc://` 写路径的真执行证据（核心）
+
+### 4.1 `ast_edit`（`dryRun:false`）真实落盘
+
+目标 scratch 文件（写前）：
+
+```js
+export function greet(name) {
+  return `hello ${name}`
+}
+
+export function farewell(name) {
+  return `bye ${name}`
+}
+```
+
+调用：
+
+```json
+{"ops": [{"pat": "export function farewell($N) { $$$B }",
+          "out": "export function goodbye($N) { $$$B }"}],
+ "paths": ["/home/u1/workspaces/dashr/.scratch/dvc-scheme-test.js"],
+ "dryRun": false}
+```
+
+回读（写后）：
+
+```js
+export function greet(name) {
+  return `hello ${name}`
+}
+
+export function goodbye(name) { return `bye ${name}` }
+```
+
+→ 函数名改写 + ast-grep 单行重排均落盘，**证明这是真执行而非空转**。（该 scratch 文件在收尾时已删除。）
+
+### 4.2 `ast_grep` 结构化输出（经 eval pad 取得）
+
+```json
+{ "totalMatches": 143, "filesWithMatches": 28, "filesSearched": 162,
+  "limitReached": true,
+  "matches": [ { "path": "../../dashr/src/url-schemes/vendored/hashline/contract.js",
+                 "text": "export function isNormalizedEdit(input) { … }",
+                 "byteStart": 775, "byteEnd": 877, "startLine": 15, "startColumn": 1,
+                 "endLine": 17, "endColumn": 2 }, … ],
+  "parseErrors": [ "…: url-schemes/vendored/devices/lsp/defaults.json: GenericFailure, Invalid pattern: Multiple AST nodes are detected…" ] }
+```
+
+（`parseErrors` 出现在 `patterns` 含多节点模式时，属预期：该 pattern 在 JSON 文件上不成立。）
+
+### 4.3 `dvc://` 首段寻址
+
+`read dvc://browser/ignored-sub` → 仍返回 browser 设备文档，证实 `catalog.ts` 所述"`dvc://` 只按第一段寻址，尾部 `/sub` 被解析后丢弃"。
+
+---
+
+## 5. 遗留与建议（按优先级）
+
+1. **【建议改码】`dvc://` 设备 payload 进渲染文本**（§3.1）——否则 `ast_grep`/`lsp`/`browser` 对模型是"看得见工具、看不见结果"。当前唯一绕行 = 在 `eval` cell 内 `await tool.write(...)` 取 `after`。
+2. **【建议改码或订正注释】`glob` 的 `dsh://docs` path 分支**（§3.4）——头注声称 path-backed，实际 content-backed 空转。
+3. **【建议改码】目录列表上的 `?q=`**（§3.3）——静默失效，至少应给提示。
+4. **【文档】`skill://` 按 frontmatter 名寻址**、**`agent://` label 含 `:` 需用原始 id**（§3.2/§3.5）——两条最易踩，建议进 `agent://`/`skill://` 的模型面说明或错误信息附提示。
+5. **【无需动作】** `http(s)` 私网拒绝、`ctx://` 只读、`dvc://` 尾段丢弃、临时物化清理——均为设计内行为，已复核无异常。
+6. **【未覆盖】** 本轮未测：`dvc://lsp` 的 `definition/references/hover/format` 成功路径（缺 `typescript-language-server`，仅验到报错分支）、`http(s)` 的重定向/压缩/大响应物化、`ctx://` 分片（compaction 后多 segment）形态。留待后续按需补测。
+
+---
+
+## 附：证据来源
+
+- 全部返回值取自本 session（`session-92ef9c82…`）在 `DSH_HOME=/home/u1/workspaces/dashr/.dsh-test` 下的活体调用；`ctx://session/tool_calls[n]` 事后可回放本轮每一次调用与其结果。
+- 源码核验：`dashr/src/url-schemes/{catalog,selector,resolver,index}.ts`、`handlers/{agent,ctx,dsh,dvc,skill,http}.ts`、`tools/{read,write,grep,glob,materialize}.ts`、`vendored/devices/ast/ast-device.ts`、`vendored/devices/browser/browser-device.ts`。