better-dsh 0.2.4 → 0.2.5-b

package/docs/50_test-reports/2026-10-02-ctx-navigation/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,137 @@
+# ctx:// 长会话导航化实测报告（2026-10-02）
+
+- **对象**：better-dsh `ctx://` scheme 长会话导航化 —— backlog N1–N6 + findings F1/F2（自 `2026-09-28-ctx-scheme长会话utility实测报告.md` §八）
+- **被测构建**：better-dsh 0.2.4-d（+ 本次改动，未发布），harness 基座 **0.2.0-rc.2**（本轮对齐）
+- **载体**：单测夹具 + 4999 rig 第一人称活体（headless 真实 agent session，模型 = deepseek-flash）
+- **设计/规格**：`docs/superpowers/specs/2026-10-02-ctx-navigation-design.md`；live spec `docs/specs/ctx/spec.md`
+
+## 一、改动一览
+
+| 项 | 内容 |
+|---|---|
+| N1/F7/F10 | 新增 transcript line index（`buildTranscript`）；episode/manifest/快照暴露 `lines:{start,end}` + 标注 `seq=`；episode 行窗 **transcript 相对**（`compactions[l]:N-M` ≡ `transcript:N-M`），越界返回显式边界注记（不再静默空/截断） |
+| N2 | digest residence：**latest** episode prepared face = 导航块（不重吐 digest，指向 `digest resident at seq=<checkpointSeq>`）；older = 全文 digest + 指针块 |
+| N3 | landmark 名册（user turns / failures / touched paths / prior checkpoints，全为 transcript 行坐标，封顶） |
+| N4 | `fidelity=<user_turns>:<tool_calls>` 内联 manifest/快照/episode 指针块 |
+| N5/F5/F8 | `:path/` + `?q=` 在 ctx:// 落地（复用 `applySelector`），manifest 也走 `applySelector` |
+| N6/F9 | 快照 `asOf:{seq,line}` |
+| F1 | `user_prompts`/`tool_calls`/`agent_responses` 裸读给索引面（长集合封顶 20 + tail），错误不再回显空括号 |
+| F2 | `resultTextOf` 增加 flat text-block 兜底 |
+
+## 二、F2 根因更正（重要）
+
+报告 §八 曾推断「持久层对大 result 的省略存储」。实测 0.2.0-rc.2 真实 `tool/result` 事件后确认根因是**内容块形状变化**：0.2.0 的 tool-result message `content` 是**平铺** `[{type:"text",text:"…"}]`，而 `resultTextOf` 只取**嵌套** `tool-result` 块 → 对所有 result 一律产空。本次改为嵌套优先、平铺兜底，`tool_calls[<seq>]` 的 result 恢复非空。非「省略」，无需 elision 标记。
+
+## 三、验证
+
+**单测**：`ctx.spec.ts` 23→30（新增 7：N1 坐标/asOf、N1/F10 transcript 相对 + 越界注记、N2 最新/旧 episode、N3 landmark、N5 `:path/`+`?q=`、F1 索引面、F2 flat result）。全量 **648 passed / 1 skipped**（57 文件）；`tsc --noEmit` **0 错**。关键不变式测试：episode `:N-M` ≡ `transcript:N-M`（episode span ≡ transcript slice，结构上保证坐标一致）。
+
+**第一人称（headless，dsh 0.2.0-rc.2）**：真实 session 内逐面活体探测，agent 复述各步通过：
+- `ctx://session` 解析，含 `asOf:{seq:26,line:311}` 卡 + totals（`user_prompts:1` 等）；
+- `ctx://session:path/totals.tool_calls` 窄读 → 数字（`3`）；
+- `ctx://session/user_prompts` / `tool_calls` 索引面正常（含 in-progress 调用的 `(no result captured)` 行）；
+- `tool_calls[20]` result 非空（`result: hello-probe-1790893221`，F2 修复实证）。
+
+compaction 特定面（lines/fidelity/landmark/digest-residence）为代码级缺陷，单测夹具（2×compaction）覆盖；本短活体无 compaction 事件，与报告 §八「活体探测仅作证」一致。
+
+## 四、判定
+
+**通过**。N1–N6 + F1/F2 全部落地，单测全绿，0.2.0-rc.2 上第一人称活体逐面兑现。坐标不变式成立（transcript 单一坐标空间，越界显式）。prod 3080 未部署；发布走 §〇.5 门（第一人称 + user 确认），本轮不发包。
+
+## 五、独立复核（2026-10-02，本轮报告发布后的第三方复验）
+
+**缘由**：user 在报告落盘后要求独立确认 §一 声称的修复是否真在场，不复述原文。复核采用三重证据：
+
+1. **部署物同一性**：4999 rig profile 内 `better-dsh/lib/url-schemes/index.js` 与构建产物 md5 一致（`ad5b4820c4ca97520ccc196d72b3aa3f`，286,916 B）→ 活体进程加载的确实是本次改动，而非旧构建。
+2. **第一人称活体探测**：本会话即 4999 运行实例（`session-6c5f8e8e-0cd7-42a0-85da-3aec7256339f`，harness 0.2.0-rc.2），逐面实读。
+3. **回归全量**：`tsc --noEmit` **0 错**；`vitest run` **648 passed / 1 skipped**（57 文件）——与 §三 数字一致。
+
+### 5.1 逐项复核结果
+
+| 项 | 结论 | 证据（活体 / 代码） |
+|---|---|---|
+| F1 | ✅ 已修 | 裸 `user_prompts`/`tool_calls`/`agent_responses` 返回索引面（`seq=<n>` + ≤100 字预览）；长集合封顶 20 + `… +N more — use :raw / ?q= / [n\|seq]` 尾注；越界错误列集合名与条数，无空括号回显 |
+| F2 | ✅ 已修 | `resultTextOf` 嵌套优先、平铺兜底（`ctx.ts` L128–137）；活体 `tool_calls[99]` result 非空；in-progress 调用显式 `(no result captured)` |
+| F5 | ✅ 已修 | 活体 `ctx://session/tool_calls?q=bash` 行过滤生效 |
+| F7 | ✅ 已修 | 快照/manifest 内 `seq=` 与 `lines=` 双坐标并存；坐标不变式已入 spec（Requirement: Coordinate invariant） |
+| F8 | ✅ 已修 | 活体 `ctx://session:path/asOf` → `{"seq":198,"line":1431}`；`:path/totals.tool_calls` → `13`（数字，非 JSON 包裹） |
+| F9 | ✅ 已修 | 快照 `asOf:{seq,line}` 在场，且与后续窄读的前移一致（模型可自知陈旧） |
+| F10 | ✅ 已修（episode 面） | `applyEpisodeLines` 越界追加 `[ctx:// note: episode span is transcript lines s-e]`（`ctx.ts` L291–318）；单测 `N1/F10` 断言 |
+| N1 | ✅ 已修 | 上述 F7/F10 证据；transcript 行索引为单一坐标源 |
+| N2 | ✅ 已在代码 | latest episode 走 `digest resident at seq=<checkpointSeq> (transcript:<s>-<e>)` 指针块，older 出 digest + 指针块 |
+| N3 | ✅ 已在代码 | `landmarkBlock`：user turns / failures / touched paths（含次数）/ prior checkpoints，全为行坐标并封顶 |
+| N4 | ✅ 已在代码 | `fidelity=<user_turns>:<tool_calls>` 三处内联（manifest / 快照 `compacted[].fidelity` / episode 指针块） |
+| N5 / N6 | ✅ 已修 | 同 F5/F8 与 F9 |
+
+**N2–N4 的活体限度**：本会话 `compactions: 0`（快照实证），compaction 特定面无法活体触达；证据 = 代码 + 2×compaction 单测夹具，与 §三 口径一致，不构成缺口。附带观察：快照 `segments[].lines` 对 `live` 尾段为 `null`（开放区间无上界），compaction 段才带 `lines:{start,end}`——与「live 无 end」语义自洽。
+
+### 5.2 未闭合项（本轮未声称修复，复核确认仍开）
+
+- **F3 仍开**：`read` 的 `offset`/`limit` 对 `ctx://` 依旧静默忽略——活体 `read(ctx://session, limit:1)` 返回全量快照 JSON。
+- **F4 仍开**：compaction label 仍为事件 seq，后续 compaction 重划 span 时仍会漂移；未改稳定键，亦未加文档点名（`compactionId` 为既有字段）。
+- **F6 仍开**：episode `:raw` > 64 KiB 仍为 warn-don't-block（返回全文 + 注记，`ctx.ts` L528–536），无 spill-to-file / 硬护栏。
+
+### 5.3 新发现 F11：spec 宽于实现（越界注记仅 episode 面兑现）
+
+spec「Canonical and prepared content faces」写明*任何*越过 canonical 范围的 `:N-M` 都应回显显式边界注记；实测仅 **episode 面**成立：
+
+- 活体 `ctx://session/transcript:1-3` → 正常返回该行窗内容；
+- 活体 `ctx://session/transcript:9000-9010`、`:999999-999999` → **静默空串**（`applyLines` 无 extent 概念、无注记逻辑）。
+
+即 §一 表中「越界返回显式边界注记（不再静默空/截断）」仅在 episode 窗口范围内为真，spec 文字面（全资源）未兑现。建议入批 F11：把 `applyLines` 升格为带 canonical extent 入参的同款注记，或把 spec 措辞收窄到 episode 面。
+
+### 5.4 复核判定
+
+**通过，无夸大**——§一/§三 声称的 N1–N6 + F1/F2 全部经独立证据兑现；§四 的部署与发布口径亦复核无误：4999 rig 已加载修复（md5 同一），prod 3080 仍为 **0.2.4-c**，修复未发布；发布仍走 §〇.5 门（第一人称实测 ✅ + user 确认）。遗留 F3/F4/F6 + 新增 F11 按 §〇 惯例攒批，不单烧版本。
+
+## 六、F11 修复（2026-10-02，复核后同波闭合）
+
+§五.3 的 F11 属实：本波 spec 文字面宽于实现（越界注记只在 episode 面）。因本改动**尚未发布**，不适用「攒批」——同波闭合：
+
+- **修法**：ctx 侧 `applyLines` 升格为 extent-aware —— 越界窗口按 canonical 上界截断并追加 `[ctx:// note: canonical content ends at line <N>]`；`:N-` 开尾读**豁免**（刻意读到尾，非越界）；manifest 的 line 窗口也改走同一函数（原先走共享 `applySelector`，无注记）。
+- **未采纳**另一选项（把 spec 措辞收窄到仅 episode 面）：不收窄，因为「不静默截断」是 N1/F10 的原意，应全资源成立。
+- **验证**：单测新增 `F11`（越界 → 注记；`1-2` in-range 与 `1-` 开尾 → 无注记）；全量 **649 passed / 1 skipped**（57 文件）+ `tsc` 0 错；**第一人称活体**（headless，0.2.0-rc.2）读 `ctx://session/transcript:9000-9010` → 输出含 `ctx:// note`（`F11=yes`）。4999 rig 已重启加载修复（`lib/url-schemes/index.js` md5 `48771cb6…` 与构建产物同一）。
+- **仍开**：F3（read offset/limit 静默忽略）、F4（compaction label 漂移）、F6（episode `:raw` >64 KiB warn-not-block）——三者不在本波 N1–N6 范围，按 §〇 攒批。
+
+## 七、第二轮复核记录（2026-10-02）与越界注记语义定论
+
+第三方复核独立确认 F11 修复已在**运行进程**中生效（构建产物与 rig lib md5 同一 + 重启后取到新行为），并逐条活体复验：
+
+| 探测 | 结果 |
+|---|---|
+| `transcript:9000-9010` / `:999999-999999`（完全越界） | 仅注记（`canonical content ends at line <N>`），**不再静默空** ✅ |
+| `transcript:1940-2000`（部分越界） | 上界截断 **+ 尾注** ✅ |
+| `transcript:1-3`（范围内） | 正常内容，无注记 ✅ |
+| `transcript:1945-` / `compactions:1-`（开尾） | 无注记（豁免）✅ |
+| `compactions:2-`（起点越界） | 仅注记 ✅ |
+| `compactions:1-3` / `compactions:9000-9010`（manifest 新路径） | 文本+注记 / 仅注记，上界正确 ✅ |
+
+回归扫：F1/F2/F5/F7/F8/F9 全部仍绿；`tsc` 0 错、`vitest` 649 passed / 1 skipped（与 §六 一致）。
+
+### 7.1 语义定论：上界越界**保留**注记（不软化）
+
+复核提出一档可议行为：**上界越界也注记**，使 `:N-M`（M 贴/略过上界）从「纯值」变为「值 + 注记」；其测试后果即既有断言 `injections:4-5` 改为 `injections:4-`。
+
+**定论：保留现语义，不采纳「`a <= total < b` 时不注记」的软化方案。** 依据 = F10 原意本身：
+
+- F10 的病症是「越界与 span 内空行**不可区分**、上界落在何处**无从得知**」。若上界越界不注记，`:1940-2000`（1947 行）静默回 1940–1947，模型无法判断 1948–2000 是「空行」还是「不存在」——**正是 F10 要修的歧义**；软化 = 回退该修复。
+- 两种「读到尾」的正规形已豁免/覆盖：**开尾 `:N-`** 无注记（刻意读到尾）；**上界恰为 total**（`:4-4`）无注记。故越界注记只在「模型对内容长度有错误假设」时出现，而该注记正是纠正该假设的信息。
+- 代价可接受：一行元信息；远小于「误以为已读全」的风险。若未来真会话统计证明其为高频噪音，另立 finding 重议；本轮不改。
+- 规格已同步补 scenario「Over-read notes, open tail does not」（`docs/specs/ctx/spec.md`）。
+
+### 7.2 仍开（复核独立确认，非本波 N1–N6 范围）
+
+F3（`read` offset/limit 静默忽略）、F4（compaction label 漂移，无稳定键）、F6（episode `:raw` >64 KiB warn-not-block）——按 §〇 攒批。发布仍待 user 明确放行。
+
+## 八、第三轮复核：spec 措辞收窄 + 「spec > impl」模式记录
+
+第三轮复核（**无代码改动轮**，唯一 commit `6e3db37` = §七 + 一条 spec scenario）确认 §七 属实，并指出：**上轮新加的 spec scenario 措辞仍比实现宽**。
+
+- **事实**：`applyLines` 的开尾豁免带前置守卫 —— `b === Infinity ? total` 之后仍有 `if (a > total) { noted = true }`（[ctx.ts:250](/home/u1/workspaces/dashr/better-dsh/src/url-schemes/handlers/ctx.ts#L250)）。故 `compactions:1-`（起点在界内）无注记，而 `compactions:2-`（canonical 仅 1 行、**起点已越界**）返回**仅注记**。我上轮写的 THEN 是无条件句，按字面读 `:2-` 会算违例。
+- **定论：实现是对的**（起点越界时无内容可回，必须出声），错的是 spec 措辞。已改 `docs/specs/ctx/spec.md`：开尾 THEN 补限定「provided the window's start is within the extent」；新增 WHEN/THEN 覆盖「起点越界的开尾 → 仅注记」；新增 scenario「Upper bound exactly at the extent is not an over-read」（`:1-1` 恰为 total → 无注记），两个豁免均成明文。
+- **模式记录（同类再现，继 F11 之后；不计序号，避免与复核口径打架）**：spec 散文倾向把行为写得比实现的**守卫条件**宽 —— F11 属**行为缺陷**（spec 全资源 vs impl 仅 episode 面，已修码），本处属**措辞缺陷**（无条件开尾 vs 起点守卫，已改 spec）。教训：写/改 spec 的 WHEN/THEN 时逐条对照实现的 guard（`b < 1 || a > total`、`bRaw !== Infinity && b > total`、`bRaw === Infinity`），把守卫写成限定词；新增 scenario 按此自查。
+- **仍开**：F3 / F4 / F6（同 §七.2）。
+
+### 8.1 部署与发布口径（不变）
+
+本轮**无代码改动**：`git diff 44a88f5..HEAD -- better-dsh/src better-dsh/lib better-dsh/test` 为空；4999 rig 内 lib 仍 `48771cb6…`（未重建、未重启，仍是同一运行进程）。prod 3080 仍 `0.2.4-c`；修复未发布，发布待 user 明确放行。

package/docs/50_test-reports/2026-10-02-v0.2.0-rc.2/345/257/271/351/275/220/350/275/256/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,38 @@
+# v0.2.0-rc.2 对齐轮实测报告（2026-10-02）
+
+- **对象**：better-dsh 对齐 upstream dsh **0.2.0-rc.2**（npm `latest`；upstream tag `dsh-v0.2.0-rc.2`）
+- **基线**：better-dsh 0.2.4-d（当前分支 `align/v0.2.0-rc.2`，从 `align/v0.1.7-rc.1` 切出）
+- **证法**：源码级 4999 rig（`upstream/deepseek-harness` 原位重检出）+ better-dsh 全量 typecheck/test + 第一人称活体（headless 真实 session + headless-Chrome 驱动 web UI）
+
+## 一、环境迁移
+
+1. `upstream/deepseek-harness` 原位重检出 `dsh-v0.2.0-rc.2`（tags 已 fetch；本地 0.1.7-rc.1 patch 先存 `.scratch/upstream-local-patches-0.1.7-rc.1.diff`）。
+2. 三处本地 patch 在 0.2.0 下**仍全部必要**，逐条重放（均标注 `LOCAL PATCH` 注释便于下次 tag 切换）：
+   - `packages/client/tsdown.client.ts` `resolveRepositoryRoot()`（0.2.0 仍 `new URL('../..', import.meta.url)`）；
+   - `pnpm-workspace.yaml` `storeDir`/`verifyDepsBeforeRun:false`/`allowBuilds`（zeromq/ssh2/cpu-features；0.2.0 仍 strictDepBuilds）；
+   - `apps/web` react→preact 三件套（0.2.0 仍真 React，`@vitejs/plugin-react`）；`preact` devDep + 根 `unrun`/`vite` devDep。
+3. `vendor/{AGENTS,CLAUDE,README}.md` 三文件移除（0.2.0 版存 `.scratch/vendor-docs/*-0.2.0-rc.2.md`）。
+4. `pnpm install`（339 workspace 项目，21s，供应链门 1685 条目过）→ `pnpm run build`（347 client artifacts）全绿。
+
+## 二、对齐结果 — 结论：zero better-dsh 源码改动
+
+| 检查 | 结果 |
+|---|---|
+| better-dsh `npx tsc --noEmit`（farm relink 至 0.2.0-rc.2，329 包） | **0 错误** |
+| better-dsh `npx vitest run` | **641 passed / 1 skipped**（57 文件）全绿 |
+
+即用户判断成立：0.2.0 相对 0.1.7-rc.2 的 448 个 commit / 1014 个文件变更，**未触及 better-dsh 消费的 harness API 面**（消费 24 包；`dsh-tools`/`dsh-agent`/`dsh-settings`/`dsh-client-ui-settings` 等类型面兼容）。上游 0.2.0 亦**未发布 upgrade guide**（09-28 才引入该机制，仅回填 v0.1.7-rc.2）。
+
+## 三、回归门（第一人称，4999 rig，0.2.0-rc.2）
+
+0.1.7 轮的两处**静默**失败面（settings 行消失 / failover 存不进）是重点复检对象：
+
+- **boot graph**：`"id":"better-dsh"` + `plugins/??better-dsh/client.js&rev=…` 200，字节与构建产物一致（仅服务端追加 `;`+sourceMappingURL）。
+- **Settings/General 两行**（headless-Chrome 驱动真实 UI）：`Model failover`（两个 select）+ `Auto-compact threshold 90 %` 均在渲染；版本行显示 `0.2.0-rc.2`。
+- **failover save**：UI 改 `fallback2` → 落 `profiles/web/cordis.patch.yml` 用户层，无 toast 无 `settings/rejected`（写路径 = 0.1.7 崩点）。
+- **web-password 门**：默认 `admin` 登录 → 303 → authenticated index（better-dsh 0.2.4-d 的门在 0.2.0 上照常）。
+- **活体 session（headless）**：`ctx://session` → 真实 session id；`bash` → `gate-ok`；`eval` → `2`。
+
+## 四、判定
+
+**通过**。0.2.0-rc.2 对齐为纯「重检出 + patch 重放 + 重建」，better-dsh 零改动；回归门全绿。prod 3080（仍 0.1.7-rc.2 + better-dsh 0.2.4-c）本轮未动。下一步 Change B（ctx:// 导航化 N1–N6）在此已验基线上开发。

package/docs/50_test-reports/2026-10-03-better-dsh-tool-surface-repl-dvc-browser-ast-lsp-4999/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,185 @@
+# better-dsh 0.2.5-a 工具面实测报告：REPL / dvc://browser / dvc://ast_grep / dvc://ast_edit / dvc://lsp（4999 rig）
+
+> **状态**：第一人称实测完成（agent 在真实 4999 会话内自测并留证）。
+> **性质**：工具面**冒烟 + 回归**，**不是**发布验收——本轮未走 AGENTS.md §〇 的 a–d 发布闸，
+> 不涉及也不授权 `npm publish`。
+> **被测版本**：better-dsh `0.2.5-a`（package.json 与 profile 实装双侧一致）；core `@deepseek-ai/dsh` `0.2.0-rc.2`。
+> **仓库 commit**：`fb49834`（根仓与 `better-dsh/` 同 SHA）。
+> **rig**：`.test/home/compat`，端口 4999，unit `dsh-4999-test123`；本轮**未重启、未改产物、未动 prod**。
+> **时间**：2026-10-03 01:40–01:56 HKT（2026-10-02 17:40–17:56 UTC）。
+> **相关前序**：[2026-09-27-lsp-ast-reminder-4999实测报告.md](2026-09-27-lsp-ast-reminder-4999实测报告.md)（lsp/ast 提醒的发布轮）。
+
+---
+
+## 0. 方法
+
+- 全部证据取自**本会话内的真实工具调用**（第一人称），非单测、非静态检查、非进程活性。
+- `dvc://` 设备经 `write dvc://<device>` 执行，`read dvc://<device>` 仅取用法；REPL 证据取自 `eval` 单元。
+- 临时产物集中在 `.scratch/ast-probe/`；browser 设备测毕已 `close`（无孤儿 Chrome）。
+
+## 1. 结论摘要
+
+| # | 面 | 结论 | 关键证据 |
+|---|---|---|---|
+| 1 | REPL（`eval`） | ✅ 全绿 | 跨 cell 状态、完成值、工具桥、错误信封、异常存活 7/7 |
+| 2 | `dvc://browser` | ✅ 功能全绿；⚠️ 进不去带密码闸的 GUI | open/run/type+click/close + 字段白名单全通 |
+| 3 | `dvc://ast_grep` | ✅ 可用；⚠️ 相对路径基准非 workspace | 15 命中、`metaVariables`、`offset/limit` |
+| 4 | `dvc://ast_edit` | ✅ dryRun 与实写均正确 | `dryRun:true` 不落盘；`false` → `applied:true` 且盘面核实 |
+| 5 | `dvc://lsp` | ✅ gate + diagnostics + hover 全绿 | TS2322 error + TS6133 hint，坐标精确 |
+| 6 | AST 可用性提醒 | ✅ 实测出现 | `write` 结果尾行一行提醒 |
+
+净结论：**四个 dvc 设备与 REPL 主体功能无回归**；发现 2 个可用性摩擦（F1/F2）与 1 个 API 面不一致（F3），
+均非阻断，建议并入下一次批量发布（AGENTS.md §〇.5）。
+
+## 2. REPL（`eval` / dashr-repl 桥）— 全绿
+
+| 探针 | 结果 |
+|---|---|
+| 跨 cell 状态 | cell 1 设 `REPL_MARKER = "cell-1-alive"`，cell 2/4/6 读回一致 |
+| 导入持久 | cell 3 `import asyncio, json, collections`，cell 4 仍绑定 |
+| 完成值协议 | 末行裸表达式 `x`（=42）作为 completion value 返回，与 `print` 并存 |
+| 工具桥 | `await tool.bash({"command": "echo bridge-ok"})` → `bridge-ok`，exit 0 |
+| 错误信封 | 失败子调用抛 `ToolCallError`，`.toolName == "read"` |
+| 入参校验 | `tool.read({})` → `[E_BAD_SHAPE] Read request requires a non-empty "path" string.` |
+| 异常存活 | 内核在 SyntaxError、AttributeError 两次异常后仍持有全部状态 |
+| 内核 | CPython `3.11.15`（profile 内 `.venv-kernel`） |
+
+桥接口径与 wire description 一致（`await tool.<name>(args)` 单位置参数对象，`true/false/null` → `True/False/None`）。
+
+## 3. `dvc://browser`
+
+| 动作 | 结果 |
+|---|---|
+| `{"action":"open","url":"https://example.com"}` | `{ok:true, url, title:"Example Domain"}` |
+| `{"action":"run","code":"…"}`（DOM eval） | 取回 `title/links/readyState`，JSON 字符串回传 |
+| `{"action":"run","type":…,"click":…}` | 复合动作生效：`data:` 页 title 由 `t0` → `hello-dvc` |
+| `{"action":"close"}` | `{ok:true}` |
+| 未知字段 | `{"action":"open",…,"bogusField":1}` → `unknown field(s) "bogusField" for action "open" — allowed: "action", "url", "executablePath"` |
+
+**⚠️ 限制（F2）**：指向本 GUI（`http://127.0.0.1:4999`）时，`?token=` 启动 URL **不能**为新浏览器铸出会话——
+页面停在 `Enter the session password to continue. PASSWORD Unlock`，`window.__DSH_BOOT__` 不存在、
+无任何 `better-dsh` 资源请求。因此 `dvc://browser` 目前**无法**用于对本 GUI 做端到端第一人称验收，
+除非补一条 cookie 注入/免密通道。（本 rig 是密码闸实例；token 只负责首铸 cookie，而全新 Chrome 无 cookie。）
+
+**方法学附注（假阳性预防）**：首轮 DOM 探针返回 `h1count: 0`，一度疑似设备缺陷；
+核对线上原文后确认 **example.com 今日已无 `<h1>`**（仅 `<p>` + `<script>`），**设备是对的，探针是我的错**。
+记录此条以防后续把同类现象误判为插件 bug。
+
+## 4. `dvc://ast_grep`
+
+| 项 | 结果 |
+|---|---|
+| 模式 | `defineTool($$$ARGS)`，`includeMeta:true` → 命中 15 / 13 文件 / 扫 189 文件，`limitReached:true` |
+| 结构信息 | 每条含 `byteStart/byteEnd/startLine/startColumn/endLine/endColumn` + AST 级 `metaVariables` |
+| 分页 | `offset:10, limit:2` → 精确返回 2 条（分页生效） |
+| 语法错误容忍 | `defineTool({$$$})` 在 `defaults.json` 上语法不合法 → 该文件进 `parseErrors[]`，**整次搜索不失败**，其余 15 命中照常返回 |
+
+**⚠️ 相对路径基准（F1）**：`path:"better-dsh/src"` → `Path not found: No such file or directory (os error 2)`；
+改为绝对路径即通。决定性实验：**`path:"../../better-dsh/src"` 命中 15 条，与绝对路径结果一致**。
+即 ast 设备的相对路径基准 = **harness 进程 cwd（`upstream/deepseek-harness`）**，而非会话 workspace
+（`/home/u1/workspaces/dashr`）——与 `read/glob/grep` 的 workspace 基准**不一致**。
+返回值里的 `path` 也用同一基准显示（`../../better-dsh/src/bridges/index.ts`）。
+**规避**：始终传绝对路径。
+
+## 5. `dvc://ast_edit`
+
+输入（作用于 scratch 文件）：
+
+```json
+{"ops":[{"pat":"const $NAME = function ($ARG) { $$$B }","out":"function $NAME($ARG) { $$$B }"}],
+ "paths":["/home/u1/workspaces/dashr/.scratch/ast-probe/sample.ts"],"dryRun":true}
+```
+
+| 项 | 结果 |
+|---|---|
+| `dryRun:true`（默认） | 返回 `before`/`after` 与字节区间 `byteStart:74, byteEnd:128, deletedLength:54`；**`applied:false`，盘面未变** |
+| `dryRun:false` | 同区间，**`applied:true`**；盘面核实：`const legacy = function (x: number) {…}` → `function legacy(x: number) { return x * 2 }` |
+| `fileChanges`/`totalReplacements`/`filesTouched` | 1 / 1 / 1，与 `limitReached:false` 自洽 |
+
+`paths` 同样受 F1 影响（本轮用绝对路径，未复现相对路径问题）。
+
+## 6. `dvc://lsp`
+
+| 步骤 | 结果 |
+|---|---|
+| 初始 `status` | `{ok:true, gate:"unasked"}` —— per-session 闸，未询问态 |
+| `{"action":"on"}` | `{ok:true, gate:"on", message:"lsp on for this session: servers warm-start per language on first file contact; no repo artifacts are written."}` |
+| `diagnostics`（植入 2 处错） | `server:"typescript-language-server"`，自动推断 `root`；返回 **TS2322 error**（`Type 'number' is not assignable to type 'string'`，4:3）+ **TS6133 hint**（`'unusedVar' is declared but its value is never read.`，1:7）；`summary:"1 error(s), 1 hint(s)"` |
+| `hover`（3:17） | ```typescript\nfunction bad(x: number): string\n``` |
+
+坐标与 `severityName`（error/hint）均正确；服务器来源为 `typescript-language-server`。
+
+## 7. AST 可用性提醒 — 实测出现
+
+对新建 `.ts` 文件执行 `write`，结果尾部实测出现：
+
+```
+ast_edit / ast_grep available — write dvc://ast_edit (structured rewrite) or dvc://ast_grep (pattern search)
+```
+
+与前序报告的制度一致（提醒挂 `write/edit/grep` 结果尾部、per-session cap）。
+**注**：本轮未观测到 **LSP nag**（在接触代码文件前已把 gate 置 `on`，`unasked` 条件不再成立），故 nag 路径未覆盖；
+提醒的 **cap 计数**本轮亦未触及边界（未做 >5 次触发）。
+
+## 8. 发现清单
+
+| ID | 严重度 | 面 | 现象 | 建议 |
+|---|---|---|---|---|
+| **F1** | 中（摩擦） | `dvc://ast_grep`/`ast_edit` | 相对 `path` 基准 = harness 进程 cwd（`upstream/deepseek-harness`），非会话 workspace；`"better-dsh/src"` 直接 `Path not found` | 二选一：①基准改为 workspace / `exec.cwd`；②保持现状但在 device help 明写"仅收绝对路径" |
+| **F2** | 中（能力缺口） | `dvc://browser` | 无 cookie 注入通道，进不去密码闸 GUI；`?token=` 不足以对新浏览器铸会话 | 若要支撑 GUI 端到端第一人称验收，需补 cookie/免密通道 |
+| **F3** | 中（API 一致性） | `llm_completion` | **返回类型不稳定**：成功回 **裸 `str`**（`'alpha beta gamma'`），失败回 **`dict`**（`{"error":"llm_completion() output reached its maxTokens ceiling"}`）；调用方 `r["text"]` / `r.keys()` 会炸 | 统一为判别式对象（`{ok:true,text}` / `{ok:false,error}`） |
+| **F4** | 低（调优） | REPL 子调用池 | 变更类子调用实际**串行**：4×`sleep 1` = 4.78s；6×`glob` = 14.71s。源码有 `maxParallelSubCalls`（默认 10）与 `parallel\|exclusive` 分类，但观测未见并行收益 | 复核 classify 是否把常用工具过度判为 `exclusive` |
+| **F5** | 低（体验） | `llm_completion` | `maxTokens` 偏小（16）时因推理吃掉预算而**整次失败**而非截断 | 考虑截断或给出可操作的错误提示 |
+| — | 观察（正面） | harness | 连续 5 次同参调用触发**重复调用护栏**并阻止了潜在死循环 | 保留 |
+
+## 9. 未覆盖 / 遗留
+
+- `dvc://lsp` 的 `references` / `definition` / `format` / `rename` / `code_actions` / `reload` 未在本轮复测
+  （2026-09-27 报告已全绿；本轮只补 `status`/`on`/`diagnostics`/`hover`）。
+- LSP **nag 路径**与 AST 提醒 **cap 边界**未覆盖（见 §7）。
+- `dvc://ast_edit` 相对路径未复测（F1 已在 `ast_grep` 上定位）。
+- `agent` / `agent_message` / `agent_workflow` / `remote` / 各 URL scheme（`ctx://` `skill://` `dsh://`）
+  本轮未测（不属本次指定的工具面；`ctx://` 另有 2026-10-02 专项报告）。
+- 生产 3080 **未部署验证**（本轮纯 4999，未触碰 prod）。
+
+## 10. 复现命令
+
+```bash
+# REPL：在任意 4999 会话内
+#   eval: REPL_MARKER = "cell-1-alive"   →  下一 cell: print(REPL_MARKER)
+
+# ast_grep（务必绝对路径，或按 F1 用 ../../ 相对 harness 根）
+#   write dvc://ast_grep {"patterns":["defineTool($$$ARGS)"],
+#     "path":"/home/u1/workspaces/dashr/better-dsh/src","limit":5,"includeMeta":true}
+
+# ast_edit dryRun → 实写
+#   write dvc://ast_edit {"ops":[{"pat":"const $NAME = function ($ARG) { $$$B }",
+#     "out":"function $NAME($ARG) { $$$B }"}],
+#     "paths":["<abs>/sample.ts"],"dryRun":true}     # 再 dryRun:false 并 cat 盘面
+
+# lsp
+#   write dvc://lsp {"action":"status"}              # → gate:"unasked"
+#   write dvc://lsp {"action":"on"}                  # → gate:"on"
+#   write dvc://lsp {"action":"diagnostics","file":"<abs>/diag.ts"}
+#   write dvc://lsp {"action":"hover","file":"<abs>/diag.ts","line":3,"character":17}
+
+# browser
+#   write dvc://browser {"action":"open","url":"https://example.com"}
+#   write dvc://browser {"action":"run","code":"document.title"}
+#   write dvc://browser {"action":"close"}
+```
+
+## 11. 附：本轮环境事实
+
+| 项 | 值 |
+|---|---|
+| better-dsh | `0.2.5-a`（package.json ≡ profile 实装） |
+| core | `@deepseek-ai/dsh` `0.2.0-rc.2` |
+| commit | `fb49834` |
+| rig home | `.test/home/compat` |
+| 内核 | CPython `3.11.15`（`.venv-kernel`） |
+| LSP 服务器 | `typescript-language-server` |
+| browser 引擎 | Chromium（`puppeteer-core`，UA 含 `HeadlessChrome`） |
+
+> 注：`readlink /proc/<pid>/cwd` 在本沙箱内取不到 4999 进程的 cwd（进程在另一命名空间），
+> F1 的基准结论由**路径算术实验**（`better-dsh/src` 失败 vs `../../better-dsh/src` 全量命中）独立钉死，不依赖该读法。

package/docs/50_test-reports/2026-10-03-physical-import/344/270/216llm-completion-ast/347/233/270/345/257/271/350/267/257/345/276/204/344/277/256/345/244/215/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,101 @@
+# better-dsh：vendored 包改物理 import + `llm_completion` 返回形态 + ast 相对路径（2026-10-03）
+
+- **对象**：better-dsh `0.2.5-a`（本地过程版本，未发布）
+- **载体**：dev 树 + 4999 rig（`.test/home/compat`，unit `dsh-4999-test123`，core `0.2.0-rc.2`）
+- **前序**：[2026-10-03-schemastery-cosmokit源码内联实测报告](2026-10-03-schemastery-cosmokit源码内联实测报告.md)、[2026-10-03-better-dsh-tool-surface-repl-dvc-browser-ast-lsp-4999实测报告](2026-10-03-better-dsh-tool-surface-repl-dvc-browser-ast-lsp-4999实测报告.md)（后者的 F1/F3 在本轮修复）
+
+## 一、vendored 包改为"物理 import"（去掉我上一轮加的 shim）
+
+user 裁决：不要额外逻辑，**物理 import** 即可 —— 文件名就叫 `@deepseek-ai/<pkg>`，目标只是避开构建期/运行期的解析 logistics。
+
+**终态**（41 个文件 / **348 KB**）：
+
+```
+third_party/
+  schemastery/                                   @deepseek-ai/schemastery 3.18.4 (MIT)
+    lib/index.mjs  lib/index.cjs  lib/types/…
+    lib/index.d.mts                              ← 唯一自加文件（见下）
+    src/index.ts  LICENSE  README.md  package.json
+    node_modules/@deepseek-ai/cosmokit/           @deepseek-ai/cosmokit 1.8.5 (MIT)
+    node_modules/@standard-schema/spec/           1.1.0 (MIT, 仅类型)
+```
+
+`package.json` 里一个子路径映射（**删除了 `src/schemastery.ts`**）：
+
+```json
+"imports": {
+  "#schemastery": {
+    "types":   "./third_party/schemastery/lib/index.d.mts",
+    "default": "./third_party/schemastery/lib/index.mjs"
+  }
+}
+```
+
+9 个源文件统一 `import z from '#schemastery'`。
+
+**两个必须知道的机制点**（都是实测撞出来的，不是猜的）：
+
+1. **TS 拒绝把 `imports` target 指进 `node_modules` 段**。最初的镜像布局是
+   `third_party/node_modules/@deepseek-ai/schemastery/…`，`tsc` 报
+   `package.json scope … has invalid type for target of specifier '#schemastery'`；
+   读 TS 源码定位到该诊断位于 `loadModuleFromTargetImportOrExport` 的
+   `!startsWith(target, "./")` 分支后，把 target 换成不含 `node_modules` 的路径即通。
+   于是 schemastery **平铺**在 `third_party/schemastery/`，而它的依赖仍按真实安装形态
+   **嵌在它自己的 `node_modules/` 里**——这样 schemastery 内部的
+   `import '@deepseek-ai/cosmokit'` 就地解析，**vendored 代码一行都不用改**（`diff -rq`
+   与上游逐字节一致，除我们新增的 `lib/index.d.mts`）。
+2. **`lib/index.d.mts` 这一个两行文件是必需的**：本包 `"type": "module"`，TS 会把
+   `lib/types/index.d.ts` 当 CJS 声明，直接 import `lib/index.mjs` 时取不到类型；
+   `.d.mts` 是 TS 的标准 ESM 声明位。
+
+**副产品（比预期更好）**：类型面也不再引用外部 —— `lib/*.d.ts` 现在从**本地 chunk**
+（`import { t as Schema } from "./index-DZQNwO7f.js"`）取 `Schema`，`lib/` 里既无
+`#schemastery` 也无裸 `@deepseek-ai/schemastery`。即发布物**运行期 + 类型面双双自包含**。
+
+## 二、F3：`llm_completion` 返回形态统一（这是**我们自己**的工具）
+
+它是本插件自研的 one-shot / 无工具 / 无上下文的工具（`src/llm-completion.ts`），桥接上游
+`ctx.llm` 服务；不是上游工具。原实现**成功回裸 `str`、失败回 `{ error }`**，程序化调用方
+`r["text"]` / `r.keys()` 会炸。
+
+修法（三层一起改，缺一不可）：
+
+- 返回值：`{ ok: true, text }` / `{ ok: false, error }`（9 个错误点 + 1 个成功点）；
+- 工具 `output.schema`：`oneOf: [textVariant, errorVariant]`（原为 `oneOf: [string, errorVariant]`
+  —— **不改这里会直接报** `value must match exactly one oneOf branch (matched 0)`）；
+- `render`：成功时仍渲染纯文本（模型面可读），失败渲染 JSON；
+- 描述补一句"直接调用成功时只渲染文本"，消除"契约说对象、surface 是文本"的歧义（本轮第一人称
+  agent 如实报了这一点）。
+- 测试同步：`test/surface-devices/llm-completion.spec.ts` 4/4 绿。
+
+## 三、F1：ast 设备的相对路径基准改为**会话 workspace**
+
+根因：eval 工具用的是 `exec.agent.session.header.cwd`（`src/index.ts:896`），而 dvc 写入这条路
+只把 `session` 传进设备（`dispatchDvcWrite(path, content, meta.session)`），没传 cwd，
+`ast-device` 的 `ctxCwd()` 只能回落到**守护进程 cwd**（= `upstream/deepseek-harness`）。
+
+修法：把同一个 cwd 作为 transport 槽位补齐（不是 payload，避免触发设备的严格字段校验）：
+
+- `tools/write.ts`：`writeScheme(..., { session, ...exec.agent ? { cwd: exec.agent.session.header.cwd } : {} })`；
+- `handlers/dvc.ts`：`dispatchDvcWrite(path, content, session?, cwd?)` → `device.execute(args, { session, ...(cwd ? { cwd } : {}) })`。
+
+## 四、验证
+
+| 项 | 结果 |
+|---|---|
+| `tsc --noEmit`（host + client） | **0 错** |
+| `npm run build` | 通过；产物 JS 无任何裸 `@deepseek-ai/schemastery\|cosmokit`；`lib/` 无 `#schemastery` |
+| 全量单测 | **57 文件 / 649 passed, 1 skipped** |
+| rig 安装 | 两个 profile 均 **`Packages: +1`** |
+| rig 启动 | 零 `failed to import` / `did not activate` / `EPIPE`（上一轮修的 EPIPE：新 boot 段实测干净） |
+| **F1 第一人称** | `write dvc://ast_grep {"patterns":["loadPiNatives"],"path":"better-dsh/src"}` → 命中 2 文件 / 3 处，且返回 `path` 为 **workspace 相对**（`better-dsh/src/devices/ast/ast-device.ts`） |
+| **F3 第一人称** | `llm_completion({prompt:'只回答一个词：OK'})` → 程序化值为 `{ok:true,text:"OK"}`；agent 观测到的 surface 为纯文本 `OK`（render 层行为，描述已写明） |
+
+## 五、未做 / 限制
+
+- **发布**：按 AGENTS.md §〇，`npm publish` 需 user 单次明确放行，本轮未发。
+- `third_party/` **不随 tarball 发布**（`files` 不含它）：`lib/` 已经内联了运行期与类型面，
+  发布物自包含；vendored 源码只服务本仓构建。`package.json#imports` 因此在发布物里是
+  "指向未发布文件"的悬空映射 —— 发布物内没有任何代码 import 它（已实测 `lib/` 零引用）。
+- `llm_completion` 的 F5（`maxTokens` 过小时整次失败而非截断）**未动**，见汇报；改动它会变更语义。
+- F2（browser 无 cookie 注入通道）、F4（REPL 子调用未并行）未动。

package/docs/50_test-reports/2026-10-03-schemastery-cosmokit/346/272/220/347/240/201/345/206/205/350/201/224/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,63 @@
+# better-dsh：schemastery / cosmokit 源码内联实测报告（2026-10-03）
+
+- **对象**：better-dsh `0.2.5-a`（本地过程版本，未发布）——`@deepseek-ai/schemastery` 从 **optional peer** 改为 **源码内联**（`third_party/`），同批内联其运行时依赖 `@deepseek-ai/cosmokit` 与（类型only的）`@standard-schema/spec`。
+- **裁决**：user，2026-10-03 —— "这两个包直接抄进我们的源码里…这样我们就不必去看真实安装环境下它的上游到底在哪里、能不能够得着、解析路径对不对"。
+- **载体**：本机 dev 树 + 4999 rig（`.test/home/compat`，unit `dsh-4999-test123`，core dsh `0.2.0-rc.2`）。
+
+## 一、为什么要内联（与前序报告的取舍关系）
+
+[2026-10-02-schemastery依赖声明修复实测报告](2026-10-02-better-dsh-schemastery依赖声明修复实测报告.md) 记录过一次事故与一次撤回：
+
+- 事故：schemastery 曾是我们的 **`dependencies`** → pnpm 在 profile 里**实体化出第二份**并被 profile 锁文件冻在 **3.18.2** → `.volatile()`（3.18.3+）缺失 → `failover`/`compaction` 在**模块作用域**建 schema 时抛错，loader 记为 `failed to import`。
+- 撤回：当时结论是"DSH 已自带一份，ride-on-DSH 的插件不该再抄第二份"，改为 optional peer，让解析回落到 harness installation scope。
+
+**本次内联与那次撤回并不矛盾，因为失败模式不同**：
+
+| | 当年（dependencies） | 本次（third_party 源码内联） |
+|---|---|---|
+| 版本从哪来 | profile 锁文件 / 上游解析 | **本仓 `third_party/` 钉死** |
+| 会不会出现两份不同版本 | 会（宿主 3.18.4 vs profile 3.18.2） | 不会：我们只用自己这一份，且**不再声明该依赖** |
+| 解析路径依赖 | 强（walk-up / installation scope） | 无（相对路径 import，构建期内联） |
+
+即：把"解析到哪一份"这个变量彻底消掉，而不是把它交给环境的解析顺序。
+
+## 二、改动
+
+- 新增 `third_party/`（344K）：
+  - `third_party/schemastery/` = `@deepseek-ai/schemastery@3.18.4`（MIT，Copyright (c) 2021-present Shigma）原样副本；
+  - `third_party/schemastery/node_modules/@deepseek-ai/cosmokit/` = `@deepseek-ai/cosmokit@1.8.5`（同版权人）——放这一层是为了让 schemastery 自己的 `import "@deepseek-ai/cosmokit"` **就地解析**，不必改动 vendored 代码；
+  - `third_party/schemastery/node_modules/@standard-schema/spec/` = `1.1.0`（MIT，Copyright (c) 2024 Colin McDonnell），仅类型。
+  - **唯一自加文件**：`third_party/schemastery/lib/index.d.mts`（转发到包自带的 `lib/types/index.d.ts`，因为直接 import `.mjs` 不会走它的 `exports.types` 映射）。
+- `package.json` 增 `imports` 子路径映射 `#schemastery`（→ `./third_party/schemastery/lib/index.mjs`）；9 个源文件（`index` / `runtime` / `web-password` / `web-trust` / `mobile` / `compaction` / `remote` / `failover` / `url-schemes`）统一 `import z from '#schemastery'`。**（后续已改为物理 import 形态并删除 `src/schemastery.ts`：见 [2026-10-03-physical-import与llm-completion-ast相对路径修复实测报告](2026-10-03-physical-import与llm-completion-ast相对路径修复实测报告.md)）**
+- `package.json`：删除 `@deepseek-ai/schemastery` peer 声明与其 `peerDependenciesMeta` 条目（peer 59 条 → 58 条生效面）；`files` 增列 `THIRD_PARTY_NOTICES.md`。
+- 署名：`THIRD_PARTY_NOTICES.md`（包根，随 tarball 发布：清单 + MIT 全文 + 各权利人）、`third_party/README.md`（provenance、布局、升级步骤、为何内联）。
+- `.gitignore`：放行 `third_party/schemastery/node_modules/`（vendored 拷贝要入库）。
+
+## 三、验证
+
+1. **类型**：`tsc --noEmit`（host）与 `tsc -p tsconfig.client.json` 均 **0 错**。
+2. **构建**：`npm run build` 通过。产物 **JS 已内联**（`lib/schemastery-*.js` 分块，含 `createVolatile`/`isVolatile`）；运行时**无任何**裸 `@deepseek-ai/schemastery|cosmokit` 引用（仅 `.d.ts` 里保留裸类型引用——与改动前行为一致，非回归；类型面宿主本就供给该包）。
+3. **单测**：`vitest run` **57 文件 / 649 passed, 1 skipped**。
+4. **4999 rig（第一人称）**：
+   - 安装 `Packages: +1`（仍只加自己）；`deps`/`optional` 均为空，schemastery 已不在 peer 清单。
+   - **把 profile 树里的 `node_modules/@deepseek-ai/` 整个删掉**后启动：**零 `failed to import`、零 `did not activate`**；`--dump-config` 里 `dashr-failover` + `dashr-compaction-tuning` 两行在场——**正是当年挂掉的那两行**。
+   - rig 树里后来重新出现的 `@deepseek-ai/*` 来自 **profile 里的另一个插件 `corti-memory`**（其 `dependencies` 含 `@deepseek-ai/schemastery ^3.18.1`，lockfile 实证），与本插件无关：我们不再贡献该包。
+
+## 四、同批修掉的一个 crash 级 bug（本轮发现，非本次改动的目标）
+
+rig 停机日志出现：
+
+```
+dsh: fatal uncaught exception: Error: write EPIPE
+    at KernelTransport.send (…/better-dsh/lib/index.js)
+    at IpyKernelBridge.dispose
+    at DashrRuntime.teardownKernel
+```
+
+根因：round 2 新写的 `KernelTransport` 在 teardown 往**已死的 bridge stdin** 写 `shutdown`，`EPIPE` 以**异步 error 事件**到达，而没有 `error` 监听 → Node 升级为 uncaught exception（守护进程级）。修法：给 `child.stdin`/`stdout` 挂 error 监听（吞掉并把 transport 标死、结算 waiter），并把写操作收敛到 `writeLine()`：先查 `writable` 再写，失败抛普通 Error 而不是让管道错误逃逸。**实测**：重装后 boot + stop 全程日志零 `EPIPE`/`fatal uncaught`。
+
+## 五、未做 / 限制
+
+- **未发布**：按 AGENTS.md §〇，`npm publish` 需 user 单次明确放行。
+- ~~`.d.ts` 里仍以裸名引用 `@deepseek-ai/schemastery`~~ **已于同日解决**：改为物理 import 后，dts bundler 把 schemastery 类型内联进本地 declaration chunk，`lib/` 里既无 `#schemastery` 也无裸名——运行期与类型面双双自包含。
+- 升级 vendored 版本是**行为变更**（settings/config 全表面）：须跑全量单测 + 4999 第一人称后方可发版（步骤见 `third_party/README.md`）。

package/docs/50_test-reports/2026-10-03-zero-npm-runtime-deps/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,82 @@
+# better-dsh 归零 npm 运行时依赖 — 实测报告
+
+日期：2026-10-03 ｜ 规格：`docs/specs/zero-npm-runtime-deps/spec.md` ｜ 目标版本：`0.2.5-a`（本地过程版本，未发布）
+
+## 0. 一句话
+
+better-dsh 的 `dependencies` / `optionalDependencies` / `postinstall` **全部为空**（60 条 `peerDependencies` 契约保留）；真实安装器（DSH Plugin Manager 底层 pnpm）安装本插件现在只加 **1 个包**；REPL 的原生 ZMQ 依赖被换成 venv 内的 Python bridge；AST 的原生 `.node` 与 browser 的 puppeteer 由**我们自己的代码**在首次使用时自装/内联；任何一项失败只让该组件不可用。
+
+## 1. 起因（user 报告的真实现象）
+
+DSH UI Plugin Manager 安装 better-dsh 时卡住并显示：
+
+```
++ better-dsh 0.2.5-a
+Packages: +15 -71
+node_modules/zeromq install$ node ./script/install.js     ← 我们的 REPL 原生依赖（cmake 构建）
+Done in 3.7s using pnpm v11.7.0
+[WARN] GET …/@oven/bun-linux-aarch64-android/-/…-1.4.2.tgz error (UND_ERR_SOCKET). Will retry in 10 seconds.
+dsh: pnpm printed nothing for 600000ms and was terminated
+```
+
+定性：**不是构建错误，是超时**。Plugin Manager 对每条捕获输出的 pnpm 运行挂 600000 ms 静默上限（`packages/boot/plugin-manager/src/index.ts:184`），超时杀树并打印 `operations.ts:453` 那句。卡住的下载（Android/arm64 的 Bun 二进制）来自**同一 profile 里另一个插件**（`super-dsh@0.1.9 → bun@1.4.2`）：插件 profile 是一个共享 pnpm 工程，"装插件 X" = "重解整个 profile"，于是**别人的安装步骤能拖死我们的安装**。user 裁决：不再 declare 任何运行时依赖、不要 postinstall、不碰 npm/pnpm，二进制由组件自己按需自装。
+
+## 2. 改动清单
+
+| 组件 | 原依赖 | 现处置 |
+|---|---|---|
+| hashline（`diff`/`file-type`/`xxhash-wasm`） | npm 依赖 | `tsdown noExternal` 内联进 `lib/`（`file-type` 经 A/B 构建证明在改动前就已被 tree-shake，直接删） |
+| client（`use-sync-external-store`） | npm 依赖 | 早已内联进 `lib/client/index.js`，删除声明 |
+| REPL（`zeromq`） | npm 依赖 + **顶层静态 import**（缺原生模块 → **整个插件加载死**） | 声明删除；新增 `src/kernel-bridge.py`（venv 内 pyzmq/jupyter_client，stdio JSON lines）+ `src/kernel-transport.ts` |
+| browser（`puppeteer-core`） | npm 依赖 | 构建期内联（实测可拉起 Chrome）；保留 vendor 自装兜底 |
+| AST（`@oh-my-pi/pi-natives-*`） | 5 条 `optionalDependencies` | 声明删除；新增 `src/vendor.ts`，首次使用时自装到 `<packageRoot>/.vendor` |
+
+新增：`src/vendor.ts`（零依赖自装器：registry packument → sha512/shasum 校验 → 自写 tar+pax 解包 → `createRequire` 解析入口 → 递归闭包 + `os/cpu/libc` 平台过滤 → staging+rename 原子落盘）、`scripts/copy-kernel-bridge.mjs`（把 .py 拷进 `lib/`）。**全程无 `child_process`、无 npm/pnpm/npx 调用**。
+
+供给触发点：**守护进程 spin-up 自检**（原有，fire-and-forget）+ **首次使用 lazy**（`ensurePiNatives()` / `loadPuppeteer()` / venv lazy）。无 postinstall。
+
+## 3. 实测证据
+
+### 3.1 安装（真实安装器，rig profile）
+
+```
+web       Packages: +1   Done in 1.8s using pnpm v11.7.0
+headless  Packages: +1   Done in 858ms using pnpm v11.7.0
+```
+
+安装前后 profile 物理树零 `zeromq` / 零 `@oh-my-pi` / 零 `puppeteer`；插件照常加载，启动日志零错误，composed tree 含 `dashr-repl`。**这同时证明 fail-open：REPL 的原生依赖不在场，插件不再跟着死。**
+
+### 3.2 REPL（新传输层）
+
+- 直连冒烟（真实 ipykernel）：kernel_info ✅ / `print("SMOKE",6*7)` → `"SMOKE 42\n"` 流式 ✅ / 到 idle ✅ / **KERNEL_BOOTSTRAP 单元执行无错** ✅ / interrupt ✅ / dispose ✅。
+- host-request comm（新传输唯一未覆盖路径）：内核 `create_comm('dashr.host')` → iopub → Node → **control 通道** `comm_msg` 回包 → 内核 control-thread handler 解 future；cell 打印 `HOSTREPLY {'pong': True, ...}` ✅。
+- **4999 第一人称**（`dsh headless` 真实 session）：
+  - `eval` → `REPL_OK 42`；
+  - 同一 Python session 内 `await tool.bash({...})` → `HOST_OK\n`（宿主参数校验失败路径亦被触发）。
+
+### 3.3 AST（自装器）
+
+- 自装器单测：provision `@oh-my-pi/pi-natives-linux-x64@18.0.6`（2×163MB `.node`）→ **dlopen 成功**（exports `astGrep`/`astEdit`/…）→ 二次调用 reuse → `^18.0.0 -> 18.4.12`。
+- **4999 第一人称（最终产物）**：`dsh headless` 让 agent 用 `dvc://ast_grep` 搜 `loadPiNatives` → `totalMatches: 3 / filesWithMatches: 2 / filesSearched: 189`；同一时刻 `<plugin>/.vendor` 出现 **314MB** 的 `@oh-my-pi/pi-natives-linux-x64`，而 **profile 树里没有 `@oh-my-pi`** —— 证明二进制是我们自己下的。
+
+### 3.4 browser（puppeteer 内联）
+
+`lib/puppeteer-core-*.js` 导出 206 项（含 `launch`/`connect`）；用系统 Chrome 实测 `launch()` → `setContent` → `evaluate` 取回 `BUNDLED_PUPPETEER_OK`。
+
+### 3.5 构建卫生
+
+`tsc --noEmit` 0 错；`npm run build` 通过；产物除 peer 契约外无外部包引用（`zeromq` 彻底消失）；全量单测 **57 files / 649 passed, 1 skipped**。
+
+## 4. 过程中修掉的两个真 bug（都是本轮暴露、本轮修复）
+
+1. **bridge 静默死通道**：jupyter_client 反序列化后的 header `date` 是 `datetime`，`json.dumps` 抛异常且**在 pump 线程里静默打死整条通道**（现象："桥 ready 了但一条消息都没有"）。修法：`default=str` + 单条消息失败不许杀通道。
+2. **自装器锚点逃逸**：`findPackageDir(name, VENDOR_ROOT)` 会从 `.vendor` **向上走出**到 `node_modules`，破坏加载器"锚点有界"契约（单测 `ast-device.spec.ts` 抓到）。修法：vendor 走精确路径 `VENDOR_ROOT/node_modules/<name>`，且显式 `fromDir` 探测时**永不 provision**。
+   另修正 round 2 我引入的 `package.json` **重复 `puppeteer-core` 键**（已在清空依赖块时一并消除）。
+
+## 5. 未做 / 已知限制
+
+- **未发布**。按本仓红线，`npm publish` 需 user 单次明确放行。
+- 自装代码自担：版本钉死、sha512 校验、平台探测、并发去重（当前无锁：两个进程同时首用可能重复下载，后者被 rename 覆盖）、代理/离线行为。
+- AST 首次使用要下 ~314MB（上游包内含 baseline+modern 两个 CPU 变体，无法只取其一）。
+- `.vendor`/`.venv-kernel` 都在包目录内，**重装插件会重下**（与既有 venv 行为一致）。
+- 本机 rig 树里残留的旧 `@puppeteer`/`@oh-my-pi` 目录已手工清除（pnpm hoisted 树不回收无引用目录）。