better-dsh 0.0.0 → 0.2.3

package/docs/v0.1.8-improved-/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,142 @@
+# DASHR v0.1.8 改进版复测报告（第一人称实测）
+
+> 复测方式：仍以 DASHR 运行时自身为被测对象（本会话，dsh Web GUI）。运行时已按上版报告调整并重启，本次对**上版全部问题逐条复测**，并重跑测试套件。
+> 复测日期：2026-08-24（同日晚，更新 commit `7ec46ac`）
+
+---
+
+## 0. 结论摘要
+
+| 结论 | 结果 |
+|---|---|
+| 上版 **P0（snapshot 失效）** | ✅ **已修复** |
+| 上版 **P1（docstring 回归）** | ✅ **已修复** |
+| 上版 P2/P3（命名漂移、masking 张力、fgm→pgmi） | ✅ **全部修复/重新设计** |
+| 测试套件 | ✅ **156/156 全绿**（上版 155/163） |
+| 遗留问题 | 🟡 README 中后段 + 根 README 仍残留旧架构文档；`compact` 引擎本部署仍未挂载 |
+
+**一句话结论**：改进版把上版报告里的**功能性问题全部清零**——内核环境自管（Python 3.11 + dill）让 snapshot 复活，delegation 工具从「桥接包装」改为「直接暴露」消除了 masking 与 dual-exposure 的张力；但**文档层还有两处 README 残留旧架构描述**需要清理。
+
+---
+
+## 1. 本次变更（commit `7ec46ac`）
+
+```
+dashr: runtime-owned kernel environment + native delegation exposure
+```
+
+1. **内核环境自管**（新增 `src/kernel-env.ts`，210 行）：运行时自己 provision 一个托管 CPython 3.11 venv（`ipykernel` + `dill`），落在**包内 `.venv-kernel`**（不再 `/tmp` 悬空 symlink）。显式解释器被校验：缺 `dill` = 响亮告警（禁用快照），缺 `ipykernel` = 硬错误。
+2. **原生 delegation 直接暴露**：masking 从 8 名收敛到**仅 2 名**（`send_message` + `report`）；`subagent`/`subagent_fork`/`list_agents`/`interrupt_agent`/`workflow`/`ralph` 直接暴露为 `tool.*` 成员；**`rlm`/`agent_list`/`rlm_workflow`/`rlm_ralph` 桥接全部删除**。
+3. **Rebrand**：`@fgm-builds/dashr` → `@pgmi-builds/dashr`；RLM 术语在 CONTEXT/ADR 去强调。
+
+---
+
+## 2. 上版问题逐条复测
+
+| 上版问题 | 严重度 | 本次实测证据 | 状态 |
+|---|---|---|---|
+| snapshot 失效（dill 缺 + Python 3.14） | 🔴 P0 | 实测内核 `Python 3.11.15` + `dill 0.4.1` + `ipykernel 7.3.0`；`.venv-kernel` 指向 uv 托管 3.11；快照测试全绿 | ✅ 修复 |
+| docstring 回归 | 🟠 P1 | 实测 `helper.__doc__ == 'First summary line.\n    Details follow.'`；`runtime.spec.ts` 绿 | ✅ 修复 |
+| `agent_message` vs `send_message` | 🟡 P2 | 实测 `tool.agent_message` → `unknown binding`；`tool.send_message` 为双向桥接；CONTEXT/ADR 已改 | ✅ 修复 |
+| flat-global vs `tool.*` | 🟡 P2 | CONTEXT.md「Binding」已改「`tool.*` member」 | ✅ 修复 |
+| `fgm` vs `pgmi` | 🟡 P2 | `package.json` name / `cordis.patch.yml` 均 `@pgmi-builds/dashr` | ✅ 修复 |
+| masking 7 vs 8 | 🟡 P2 | 重新设计为 2 名，ADR-0002 已同步 | ✅ 修复 |
+| masking 对直接面无效（结构性张力） | 🟡 P3 | 决策落地：delegation 直接暴露、`rlm` 删除，张力消除 | ✅ 修复 |
+| 桥接错误风格不一致 | 🟡 P3 | `rlm_workflow` 等已删，仅剩 `send_message`（结构化 error 值） | ✅ 消除 |
+
+---
+
+## 3. 新功能面实测（第一人称逐项）
+
+### ✅ 3.1 内核环境自管 —— 通过
+
+```
+kernel python: 3.11.15
+dill: 0.4.1
+ipykernel: 7.3.0
+```
+
+`.venv-kernel/bin/python` 现指向 `/home/u1/.local/share/uv/python/cpython-3.11-linux-x86_64-gnu/bin/python3.11`（真实存在，非悬空）。
+
+### ✅ 3.2 原生 delegation 直接暴露 —— 通过
+
+`tool.subagent` / `tool.subagent_fork` / `tool.list_agents` / `tool.interrupt_agent` / `tool.workflow` / `tool.ralph` 现在**全部直接绑定**（call-through 返回的是真实工具的参数校验错误，而非 `unknown binding`）：
+
+```
+tool.subagent        -> REJECTED (invalid arguments: missing required property "description")
+tool.list_agents     -> bound+callable（返回子代理列表）
+tool.workflow        -> REJECTED (missing required property "script")
+tool.ralph           -> REJECTED (missing required property "objective")
+```
+
+### ✅ 3.3 桥接收敛（仅 send_message + refine + compact）—— 通过
+
+```
+tool.send_message    -> bound+callable   （双向桥接）
+tool.refine          -> bound+callable
+tool.compact         -> bound+callable
+tool.rlm             -> REJECTED (unknown binding "tool.rlm")
+tool.agent_list      -> REJECTED (unknown binding)
+tool.rlm_workflow    -> REJECTED (unknown binding)
+tool.rlm_ralph       -> REJECTED (unknown binding)
+tool.agent_message   -> REJECTED (unknown binding)
+```
+
+`rlm` 家族彻底移除，递归改走 `tool.subagent` / `tool.subagent_fork` 直连。
+
+### ✅ 3.4 递归 + A2A 全链路（新形态）—— 通过
+
+```
+tool.subagent spawn → {'kind':'continuable','subagentId':'3e8f3609-...'}   （8*9）
+child 完成上报
+tool.send_message(receiver='child') 下行追问 9*9 → 上报 "81"
+tool.send_message(receiver='parent') from root → 结构化 UNAUTHORIZED（guard 仍在）
+```
+
+### ✅ 3.5 无回归项 —— 通过
+
+`tool.*` 绑定、跨 cell 持久化、`ToolCallError(.toolName)`、`asyncio.gather`、顶层 `return` → SyntaxError 均与上版一致，无回归。
+
+### ✅ 3.6 测试套件 —— 全绿
+
+```
+Test Files  18 passed (18)
+     Tests  156 passed (156)
+```
+
+上版失败的 `snapshot-revive` / `snapshot-restore` / `lifecycle` / `session-keys` / `runtime`(docstring) 全部转绿；新增 `bindings.spec.ts`（7）、`parallel.spec.ts`（2）。
+
+---
+
+## 4. 遗留问题（新发现）
+
+### 🟡 4.1 包内 `dashr/README.md` 中后段仍描述旧架构
+
+header 段已更新（`dsh-rlm-mode`→`dashr`、`RLMRuntime`→`ReplRuntime`、`ipython`→`eval`、kernel 自管），但**中后段未同步**，仍残留：
+
+- 「**`ipython`** — the only tool the model may call directly」（应为 `eval`）
+- 「FLAT top-level callables — `await name({...})`」（应为 `tool.*` member）
+- 「bridge callables `rlm`, `send_message`, `agent_list`, `rlm_workflow`, `rlm_ralph`」（已删）
+- 「Delegation and messaging (rlm, send_message, agent_list, rlm_workflow, rlm_ralph)」整段 `rlm()` API 文档（已删）
+- install 段仍指 `dsh-rlm-mode` + `rlm-mode` preset（preset 已删）
+- `dashr-kernel` group `isolate: { rlmRuntime: true }`（旧 realm 架构，现为 host-plane `dashr-repl`）
+
+### 🟡 4.2 根 `README.md` 完全未 rebrand
+
+根 `README.md` 仍是「# Dashr: RLM Plugin for `dsh`」+ `dsh-rlm-mode` npm badge + 完整 RLM 定位 + `rlm()` API 示例——本次 commit **未触碰根 README**。
+
+### 🟡 4.3 `compact` 引擎本部署未挂载
+
+`tool.compact` 返回 `{'context_tokens': 137635, 'error': 'compact() is unavailable: no ctx.compaction engine is mounted in this composition'}`——桥接存在，但本 composition 无宿主压缩引擎（与上版一致，非本 commit 引入）。
+
+### ⚪ 4.4 观察项：会话续接时工具目录未随插件升级刷新
+
+本会话（`session-5037d6a6`）跨过了插件更新 + 运行时重启，但**本会话的 system prompt（Tool Catalog）仍是旧版**——仍在声明 `rlm`/`agent_list`/`rlm_workflow`/`rlm_ralph` 可用，而实测运行时已 `unknown binding`。新开会话应得到正确目录，但「持久会话热升级插件后目录不刷新」值得留意。
+
+---
+
+## 5. 建议
+
+1. **清理 README 残留**：把 `dashr/README.md` 中后段（ipython/flat/rlm 家族/install/preset/isolate realm）+ 根 `README.md`（RLM 定位、`dsh-rlm-mode` badge、`rlm()` API）对齐 v0.1.8 实际形态（`eval`、`tool.*`、直接 delegation、`@pgmi-builds/dashr`）。
+2. **验证 compact 部署**：在目标部署形态下挂载宿主压缩引擎，复验 `compact` 与 Global Context Recency Window。
+3. **会话续接目录刷新**（可选）：考虑在插件升级/重启后让持久会话的 Tool Catalog 失效或重算，避免模型看到过期工具面。

package/docs/v0.1.8-/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,193 @@
+# DASHR v0.1.8 实测报告
+
+> 实测方式：以 DASHR agent 运行时自身（本会话，运行于 dsh Web GUI）作为被测对象，直接调用 `eval` 持久内核与 `tool.*` 绑定逐一实测，并运行仓库 `npm test` 测试套件交叉验证。
+> 实测日期：2026-08-24
+
+---
+
+## 0. 摘要（TL;DR）
+
+| 结论 | 结果 |
+|---|---|
+| 核心 REPL 能力（`eval` 持久内核、`tool.*` 绑定、masking、`rlm` 递归、A2A） | ✅ **全部实测可用** |
+| 测试套件 | ⚠️ **155/163 通过，8 个失败** |
+| 失败根因 | 🔴 **snapshot 快照/恢复功能失效**（`dill` 缺失 + 内核运行在 Python 3.14.4 而非文档要求的 3.11） |
+| 文档/命名漂移 | 🟡 若干（`agent_message` vs `send_message`、flat-global vs `tool.*`、`fgm` vs `pgmi` 等） |
+
+**一句话结论**：v0.1.8 的「eval 持久内核 + 统一 `tool.*` 桥接」这条主线功能是**成立且可用的**，递归子代理（RLM）与 A2A 通信全链路走通；但 **snapshot 快照/恢复（README 标注的 `dill` 全命名空间快照）在当前环境是坏的**，且存在多处文档与代码的命名/架构漂移。
+
+---
+
+## 1. 被测对象与版本
+
+| 项 | 值 |
+|---|---|
+| 插件包名 / 版本 | `@fgm-builds/dashr`（`dashr/package.json` `version: 0.1.8`） |
+| 工作区 git 状态 | 工作区未提交改动；`git describe` = `v0.1.6-1-gec7b844`（v0.1.7/v0.1.8 均为未提交的开发产出） |
+| 宿主运行时 | `dsh 0.1.1-rc.2`（`dsh --version`） |
+| Node | v22.22.1 |
+| 内核 Python（实测） | **3.14.4**（系统 `/usr/bin/python3`） |
+| ipykernel | 7.3.0 |
+| `dill` | ❌ **未安装**（`ModuleNotFoundError: No module named 'dill'`） |
+| 内核 venv | `.venv-kernel/bin/python` → `/tmp/dashr-py311/bin/python3.11` **悬空**（目标已删） |
+
+---
+
+## 2. v0.1.8 相对 v0.1.6 的关键变化（读代码 + 文档得出）
+
+1. **Rebrand**：`dsh-rlm-mode` → `@fgm-builds/dashr`，定位从「RLM 插件」转向「Better Dash 完整 App（distro）」（`docs/repositioning-and-rebranding.md`、`docs/distro-blueprint.md`）。
+2. **架构升级（最大改动）**：`cordis.patch.yml` 从 `[]`（空壳）改为在 **HOST 平面** 挂载 `dashr-repl`（`eval` 工具 + 持久 kernel REPL 运行时落到全局作用域层，对所有 preset 可见）。旧的 `preset/rlm-mode/agent.cordis.yml`、`preset.yml` **删除**——这是 v0.1.5「DashrDaemon 空壳」的正式落地。
+3. **传输工具改名**：`run_cell` → **`eval`**（`EVAL_NAME = 'eval'`）。
+4. **绑定形态切换**：从 v0.1.5 的「平级 top-level global」切到 **统一 `tool.*` namespace**（每工具 = `await tool.name({...})` 成员 async callable），对应 distro-blueprint §2.2 的「dual exposure / both 模式」。
+5. **Masking 名单扩充**：`MASKED_TOOL_NAMES` 含 **8 个名**（ADR-0002 只写 7 个，实际多了 `report`）：`subagent, subagent_fork, send_message, list_agents, interrupt_agent, workflow, ralph, report`。
+6. **桥接工具**（bridge tools，`BRIDGE_TOOL_SCHEMAS`）：`rlm` / `send_message` / `agent_list` / `rlm_workflow` / `rlm_ralph`。
+
+---
+
+## 3. 实测结果 — 功能面（逐项亲测）
+
+### ✅ 3.1 `eval` 持久内核 —— 通过
+
+`eval` cell 正常执行，内核为真实 IPython 持久内核，`await` / 顶层表达式 / 变量跨 cell 存续均正常。
+
+### ✅ 3.2 状态跨 cell 持久化 —— 通过
+
+Cell 1 定义 `persist_probe`，Cell 4 仍可读：`persist_probe still alive: {'made_in': 'cell-1', 'answer': 42}`。
+
+### ✅ 3.3 `tool.*` 统一绑定 —— 通过
+
+`tool.read` / `tool.bash` / `tool.grep` / `tool.glob` / `tool.write` / `tool.edit` / `tool.web_search` / `tool.skill` / `tool.memory_*` / `tool.refine` / `tool.todo_write` / `tool.get_goal` 均可用（实测调用返回正确 JSON）。
+
+### ✅ 3.4 `ToolCallError` 类型化拒绝 —— 通过
+
+真实工具调用失败（文件不存在）抛 `ToolCallError`，`.toolName` 正确携带绑定名：
+
+```
+caught ToolCallError: ToolCallError | toolName = read
+```
+
+### ✅ 3.5 `asyncio.gather` fan-out —— 通过
+
+并发 `tool.read` + `tool.bash` 同 cell 完成。
+
+### ✅ 3.6 Masking（呈现层排除，host 端拒绝）—— 通过（REPL 内）
+
+`tool.subagent` / `tool.list_agents` / `tool.interrupt_agent` / `tool.workflow` / `tool.ralph` / `tool.subagent_fork` / `tool.send_message`(上游工具名) → 全部返回 `ToolCallError: unknown binding`。
+legacy 传输名 `tool.run_cell` / `tool.run_code` / `tool.ipython` / `tool.eval`（嵌套）→ 同样 `unknown binding`（`eval` 自身不可重入）。
+
+> 关键机制：`_DashrBindingHolder.__getattr__` 对**任意**名字都返回 proxy（`getattr` 永不抛 AttributeError），真实「是否绑定」由 host 在**调用时**判定拒绝。因此 `dir(tool)` 为 0 成员、`getattr` 恒真——需要**调用**才能区分 masked 与否。
+
+### ✅ 3.7 桥接工具 —— 通过
+
+| 桥接名 | 实测 |
+|---|---|
+| `tool.rlm` | `rlm({"mode":"bogus"})` → 结构化错误值 `{'error': 'rlm() requires ...'}`（非异常） |
+| `tool.agent_list` | 返回子代理列表 |
+| `tool.send_message` | 上行/下行均走通（见 3.9/3.10） |
+| `tool.rlm_workflow` | 校验失败抛 `ToolCallError`（missing meta.name） |
+| `tool.rlm_ralph` | 实际触发一次 Ralph 循环（`status: blocked`） |
+
+### ✅ 3.8 RLM 递归子代理全链路 —— 通过
+
+```
+rlm spawn → {'kind':'continuable','subagentId':'26e2842e-...'}
+child 完成上报: "42"（6*7）
+send_message 下行追问 7*8 → child 再上报: "56"
+```
+
+spawn → child 执行 → wakeup 上报 → parent 下行追问 → 再上报，**完整闭环走通**。
+
+### ✅ 3.9 `agent_list` 状态流转 —— 通过
+
+`running → ready`（`ready` = 空闲可续聊，非终结态）。
+
+### ✅ 3.10 A2A 上行 guard —— 通过
+
+root 调 `tool.send_message(receiver='parent')` → 结构化错误：`only a live continuable child agent can report to its parent`（`authorizeReporter` 的 `UNAUTHORIZED` 路径，root 不具上行资格）。
+
+### ✅ 3.11 REPL 语义 —— 通过
+
+顶层 `return` → `SyntaxError: 'return' outside function`（parse 期即拒绝，符合原生 IPython cell 语义）。
+
+### ⚠️ 3.12 `compact` 压缩 —— 本环境不可用
+
+`tool.compact` 返回 `{'context_tokens': 88407, 'error': 'compact() is unavailable: no ctx.compaction engine is ...'}`——宿主 `ctx.compaction` 引擎未在本部署加载，压缩能力无实际效果。
+
+### 🔴 3.13 snapshot 快照/恢复 —— 失效
+
+见 §5/§6，根因是 `dill` 缺失。
+
+---
+
+## 4. 测试套件结果（`npm test` = `vitest --run`）
+
+```
+Test Files  5 failed | 13 passed (18)
+     Tests  8 failed | 155 passed (163)
+```
+
+失败分布（8 个失败，7 个集中在 snapshot）：
+
+| 文件 | 失败数 | 失败用例 |
+|---|---|---|
+| `test/snapshot-revive.spec.ts` | 4 | 全部（revive/降级/超限快照/over-cap） |
+| `test/lifecycle.spec.ts` | 1 | dispose 时写快照 |
+| `test/session-keys.spec.ts` | 1 | 每 principal 快照独立子目录 |
+| `test/snapshot-restore.spec.ts` | 1 | eval 快照路径 + 恢复纯用户态 |
+| `test/runtime.spec.ts` | 1 | **keep function docstrings intact**（非快照，单独问题） |
+
+> 注：`npm test` 进程退出码为 0（vitest 失败但外层 bash 收 0），CI 若直接依赖退出码会**漏报失败**——建议核对 vitest 的 exit-code 配置。
+
+---
+
+## 5. 根因分析
+
+### 5.1 snapshot 失效（7 个失败）—— 环境链式断裂
+
+```
+.venv-kernel/bin/python  →  /tmp/dashr-py311/bin/python3.11   （悬空，目标已删）
+        ↓ 测试 helper: existsSync(悬空 symlink)=false → 回退 'python3'
+        ↓ 内核运行在 Python 3.14.4（系统解释器）
+系统 python3.14 已装 ipykernel 7.3.0，但 ❌ 无 dill
+        ↓ snapshot/restore 依赖 dill.dump/dill.load（src/python.ts:163,242）
+        ↓ dump 失败 → manifest.json 从未写出 → 测试 ENOENT / assertion 失败
+```
+
+即：**文档承诺的「Python 3.11 内核（uv venv）+ dill」部署前提在本机已失效**，运行时静默回退到 3.14.4 且缺 dill，导致快照功能整体不可用。
+
+### 5.2 docstring 失败（1 个）—— 疑似 Python 3.14 行为变化
+
+`runtime.spec.ts`「keeps function docstrings intact」断言 `helper.__doc__` 精确等于 `'First summary line.\n    Details follow.'`，在 3.14 下不成立。与 5.1 同源（内核 Python 版本漂移），需在 3.11 下复验。
+
+---
+
+## 6. 问题清单（按严重度）
+
+### 🔴 P0 — 快照功能整体失效
+README「State Snapshot & Revival 💾 Full Namespace Snapshot (dill)」在当前环境不可用。需修复内核 Python 环境（重建 3.11 venv + `ipykernel dill`），或让运行时在缺 dill 时显式告警而非静默跳过。
+
+### 🟠 P1 — docstring 回归
+可能由 Python 3.14 引入；需在 3.11 内核下确认是否仍存在。
+
+### 🟡 P2 — 文档/命名漂移（多处）
+1. **`agent_message` vs `send_message`**：`CONTEXT.md` 术语表写 A2A 函数为 `agent_message(receiver, message, *, subagent_id)`，但 v0.1.8 实际桥接名为 **`send_message`**（`tool.send_message`）。实测 `tool.agent_message` → `unknown binding`。
+2. **flat-global vs `tool.*`**：`CONTEXT.md`「Binding = flat global」及 `V0.1.5-development-plan.md`（Q8 平级 globals）描述的是旧形态；v0.1.8 已切换为统一 `tool.*` namespace，`rlm`/`agent_list` 等**不再是裸全局**（实测 `rlm(...)` 裸调用 → `NameError`）。
+3. **`subagents-surface.ts` 头注释**仍描述「preset 的 entry-local `isolate: { replRuntime: true }` realm」旧架构；v0.1.8 已改为 HOST 平面全局挂载，注释过时。
+4. **`@fgm-builds/dashr` vs `pgmi-builds`**：最近一次 commit（`ec7b844`）把 GitHub namespace 从 fgm-builds 改成 pgmi-builds，但 `package.json` 的 `name` 仍是 `@fgm-builds/dashr`，仅 `repository.url` 是 pgmi-builds，未同步。
+5. **masking 数量**：ADR-0002 / V0.1.5 plan 写 7 个 masked 名，代码 `MASKED_TOOL_NAMES` 实际 **8 个**（多了 `report`）。
+
+### 🟡 P3 — 观察项（供决策，非必然 bug）
+1. **masking 对「直接 function-calling 面」无效**：ADR-0002 意图是「模型看不到这 7/8 个名」，但实测 masking 只作用于 REPL 内 `tool.*`；作为 dual-exposure（both 模式）副作用，`subagent`/`send_message`/`list_agents`/`interrupt_agent`/`workflow`/`ralph`/`subagent_fork` 仍出现在模型**直接可调用的工具面**。这是 both 模式与 masking 意图的结构性张力，需 maintainer 决策（是否要在直接面也收敛）。
+2. **桥接工具错误风格不一致**：`rlm()` 参数校验失败返回**结构化 error 值**，`rlm_workflow()` 校验失败抛 **ToolCallError**，两种风格并存。
+3. **README/描述措辞**：`package.json` description 写 `tool.*`，README 正文仍写 `tools.*`（复数，旧名），需统一。
+4. **`compact` 依赖宿主压缩引擎**：本部署无 `ctx.compaction` 引擎，DASHR 的「Global Context Recency Window / compact」压缩能力未在此环境生效，需在目标部署形态下复验。
+
+---
+
+## 7. 建议
+
+1. **优先修复内核环境**：重建 `.venv-kernel`（Python 3.11 + `ipykernel` + `dill`），消除悬空 symlink；否则快照功能与 7 个测试持续红灯。
+2. **为缺 dill / 版本漂移加显式护栏**：运行时启动时探测 `dill` 与 Python 版本，缺依赖时降级快照并**告警到模型/日志**，而非静默跳过。
+3. **同步文档与命名**：统一 `CONTEXT.md`（`agent_message`→`send_message`、flat-global→`tool.*`）、`subagents-surface.ts` 头注释、`package.json` `name`（fgm→pgmi）、README 的 `tools.*`→`tool.*`。
+4. **明确 masking 边界**：在 dual-exposure 下重新定义「masking 语义」——是只收敛 REPL 内 `tool.*`，还是也要在直接工具面收敛，形成 ADR。
+5. **CI 退出码**：核对 vitest 失败时是否向 CI 返回非零退出码，避免「红测试绿流水线」。

package/docs/v0.1.8b-/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,96 @@
+# DASHR v0.1.8b 实测报告（决策记录 + 待拿掉缺口清单）
+
+> 状态：决策已定，代码待落地。本文为**需求移交文档**：本会话只做实测/记录，不动代码；后续开发 agent 按 §4 一次性改。
+> 日期：2026-08-24
+
+---
+
+## 0. 结论摘要
+
+| 项 | 决策 |
+|---|---|
+| `refine`（Continual Harness） | 🔴 **移除**（本轮定） |
+| `compact`（`tool.compact` 上下文压缩 REPL 桥接） | 🔴 **移除**（上轮已定） |
+| `recency`（被动 recency 压缩引擎，后台 auto） | ✅ **保留** |
+| `send_message`（A2A 双向桥接） | ✅ 保留 |
+| `eval`（传输工具） | ✅ 保留 |
+
+DASHR 自登记的工具从 4 个（eval + send_message + refine + compact）收敛为 **2 个（eval + send_message）**——即「DASHR 独有、原生工具链没有的」两个桥接（refine/compact）全部拿掉。
+
+---
+
+## 1. 决策一：移除 `refine`（本轮，2026-08-24）
+
+`refine` 是抄 Prime Agent 的 **Continual Harness**（Prime Agent 三大支柱：RLM / Context as variable / Continual harness）。移除理由（用户定）：
+
+**1.1 定位与界限不清**
+- `refine` 功能上接近「记忆 / 技能」（memory / skill）。
+- Hermes、openclaw 这类 Persona Agent 已经在做 cross-session enhancement（harness 跨 session persist）。
+- DASHR 在 runtime 内重组 System Prompt 确实难得；但**同 session 重组后 persist 下来，下个 session 也会带着这个 harness**——这混淆了 **cross-session（跨会话）** 与 **per-session real-time（会话内实时）** 的界限。
+- 很多「当时当地有用」的配置并不该跨 session 固化；做 coding/项目的 agent，用户更倾向**每次唤醒时外围 harness 固定、可控**，需要调整再走别的机制。
+- 核心未决问题：**Dash 的定位到底是 Persona Agent（人格体、跨会话增强），还是 CLI 式（每次唤醒执行独立新任务）？** 定位不清，refine 的语义就悬空。
+
+**1.2 有效性待测**
+- real-time harness 的作用有多大未验证。
+- 它是在 runtime 内由**旁路大模型**做总结，且 persist over session——多一次推理、多一层持久状态，收益不明确。
+- Memory / Skill 已经有外围插件填补了生态位；唯一缺口只是「不能在 runtime 内实时重组」，而「实时重组」目前看偏超前、有效性存疑。
+
+**1.3 模型没空主动调它（用户补充）**
+- 大模型几乎**每一个 turn、每一个 user prompt 都有任务要做**，不会「有心思」在 runtime 里主动去调用 refine 这种自我维护动作。
+- 让模型在忙正事的同时抽空做 harness 重组，是天方夜谭；它只会专注手头任务。
+
+**可逆性**：项目有 Git 版本控制，随时可切回 v0.1.6 或更早查看源码；上游 Prime Agent 也在做相关探索，届时可再引入。故本次**暂不引入 Refine**。
+
+---
+
+## 2. 决策二：移除 `compact`（上轮已定）
+
+`compact` 是把宿主 `ctx.compaction` 引擎硬桥进 REPL 的 DASHR 独有桥接。移除理由：
+- 上下文压缩是**宿主运行时的事**，不属于 REPL（REPL 是 Agent 运行时的「外部环境」）。
+- 原生工具链根本没有 `compact` 工具（只有 CLI 命令 + 压缩引擎 service），DASHR 是「无中生有」映射进来的。
+- 实测 `tool.compact` 一调就返回 `no ctx.compaction engine is mounted`（本部署未挂引擎），映射了也没意义。
+- 程序逻辑上「既不桥接、也不屏蔽」最简洁——上游不提供，删掉即自然缺位。
+
+> 注意：移除的是 `tool.compact` 这个**模型可见的 REPL 桥接**；被动 recency 压缩引擎（`RecencyAwareCompactionEngine`，`auto: true` 后台自动压）**保留**——两者是两回事（见 §4）。
+
+---
+
+## 3. 全量「待拿掉缺口」清单
+
+| # | 缺口 | 类型 | 状态 |
+|---|---|---|---|
+| 1 | `compact` REPL 桥接（`compactCallable` + catalog + bindings） | 代码 | 🔴 待落地 |
+| 2 | `refine` REPL 桥接（`refineCallable` + catalog + bindings） | 代码 | 🔴 待落地 |
+| 3 | `refine` 连带 machinery：`refineModel` 配置、`dashr:harness` prompt 段、`src/refine.ts`、`src/harness-store.ts`（注：`compactModel`/`src/compaction-surface.ts`/`src/compaction/recency-engine.ts` 属 recency，**保留**） | 代码 | 🔴 待落地（随 1/2 一并） |
+| 4 | `dashr/README.md` 中后段仍描述旧架构（`ipython` 传输、FLAT callables、`rlm`/`agent_list`/`rlm_workflow`/`rlm_ralph`、`dsh-rlm-mode`、`rlm-mode` preset、`dashr-kernel` isolate realm） | 文档 | 🟡 待修 |
+| 5 | 根 `README.md` 完全未 rebrand（仍「RLM Plugin for dsh」+ `dsh-rlm-mode` badge + `rlm()` API） | 文档 | 🟡 待修 |
+| 6 | 持久会话热升级插件后 Tool Catalog 不刷新（system prompt 残留 `rlm`/`agent_list` 等旧名） | 运行时 | 🟡 待修（新开会话自愈，属会话续接边界） |
+
+---
+
+## 4. 落地范围（已定稿：refine 删、recency 保留）
+
+**移除 —— refine（Continual Harness）：**
+1. `BRIDGE_TOOL_SCHEMAS` 删 `refine` 条目（留 `send_message`）。
+2. 删 `refineCallable` 函数 + bindings 装配处 `refine: refineCallable`。
+3. 删 `src/refine.ts`、`src/harness-store.ts`（及其测试）。
+4. 删 `refineModel` 配置项 + `resolveRefineTarget` + `requireLlm` 相关 wiring。
+5. 删 `dashr:harness` prompt 段（refine 是唯一写入方，删后必然为空）。
+
+**移除 —— compact（仅 `tool.compact` 桥接，不动 recency）：**
+6. `BRIDGE_TOOL_SCHEMAS` 删 `compact` 条目。
+7. 删 `compactCallable` 函数 + bindings 装配处 `compact: compactCallable`。
+
+**保留：**
+- `send_message` 桥接（A2A 双向）。
+- `eval`（传输核心）。
+- **被动 recency 压缩引擎**：`src/compaction/recency-engine.ts`（`RecencyAwareCompactionEngine`，`auto: true` step 间自动压）+ `compactModel` 配置 + `src/compaction-surface.ts` + `scopedCompaction` wiring —— **全部保留**（被动压缩有用，且不占 REPL 面）。
+
+---
+
+## 5. 复测计划（落地后执行）
+
+1. 跑 `npm test`（预期原 156 用例中，refine/compact/harness 相关 spec 删除或转绿）。
+2. 实测 `tool.*` 面：`tool.refine` / `tool.compact` → `unknown binding`；`tool.send_message` / `tool.eval` 正常。
+3. 确认 `refine`/`compact` 不再出现在 Tool Catalog。
+4. 文档缺口（#4/#5）核对 README 是否对齐 v0.1.8b 实际形态。

package/docs/v0.1.8c-/345/256/236/346/265/213/346/212/245/345/221/212.md

@@ -0,0 +1,127 @@
+# DASHR v0.1.8c 实测报告（URL Schema 第一人称实测）
+
+> 状态：URL schema 已部署到运行时，但**部分生效**——本报告为实测记录 + 待修缺口清单，只做实测/记录，不动代码。
+> 日期：2026-08-26
+> 变更对象：`openspec/changes/url-schema/`（proposal + design + specs + impl-contract）
+> 发布包：`@pgmi-builds/dashr@0.1.10`（`package.json` 已升 0.1.10；本 openspec change 沿用 v0.1.8c 标签）
+
+---
+
+## 0. 结论摘要
+
+| 验收面 | 结果 | 一句话 |
+|---|---|---|
+| URL resolver + read 路由 | ✅ 生效 | `read` 能把 `scheme://` 分流到 handler |
+| `skill://` | 🔴 坏 | `ctx.skills` 注册表空，与 prompt 里的 skill 目录不同源 |
+| `agent://`（名册 / 输出 / transcript / child） | ✅ 生效 | 四形态返回真实内容；但名册字段与 spec 不符 |
+| `history://` 并入 `agent://` | ✅ 生效 | 返回「已并入」提示 |
+| `dsh://config` | ✅ 生效 | 返回 resolved settings，无 secret 泄漏 |
+| `dsh://docs` | 🔴 坏 | `docs/` 没打进发布包，`resolveDocsDir` 从安装路径向上找不到 |
+| `ctx://` 读 | 🔴 坏 | URL 分支传空 env，落到 `AGENTLESS_KEY` 空内核 |
+| `ctx://` 写 | 🔴 未接线 | `writeCtxVar` 是死代码，`defaultSchemeWrite` 直接抛不支持 |
+| `xd://` 读 + 写 | ✅ 生效 | 空占位行为与 spec 一致 |
+| selector 语法（`:N-M` / `:raw` / …） | ✅ 生效 | `dsh://config:1-3` 正确按行截断 |
+| 未注册 scheme 报错 | ✅ 生效 | 结构化报错并列出 `registered: agent, ctx, dsh, skill, xd` |
+| mask `skill` 工具（D5） | 🔴 未生效 | 只挡 REPL 的 `tool.*` 面，host 层原生 `skill` + `<available_skills>` 仍在 |
+| **`write` 普通路径（透传）** | 🔴 **回归** | **`write` 工具对工作区任意路径一律拒绝，只放行 `/tmp`；`read`/`edit`/bash 均正常** |
+
+**净结果：6 个 scheme 里 3 个半生效（agent / dsh:config / xd + selector/history），2 个半坏（skill / ctx 读），1 个彻底坏（ctx 写），1 个配套改造（dsh:docs）坏，1 个 BREAKING（mask skill）未生效；另有 1 处**非 URL 路径 `write` 的回归**（破坏「普通路径透传」spec）。**
+
+---
+
+## 1. 部署状态确认（不是 stale host）
+
+上一轮 v0.1.8c 实测结论是「stale host + BetterEdit shadow 冲突」。本轮复核**推翻该结论**：
+
+- 运行时实际加载的 DASHR 包 = `~/.dsh/profiles/web/node_modules/@pgmi-builds/dashr`，`package.json` version `0.1.10`。
+- 部署 `lib/index.js`（2026-08-26 04:22 构建，210482 字节）与工作区 `dashr/lib/index.js`（04:21）**逐字节一致**——是最新构建，非旧代码。
+- `dashr/src/url-schema/` 源码完整（resolver / selector / handlers×5 / tools×4 / vendored hashline）。
+- 5 个 handler **都已注册**（未注册 scheme 报错里列得全：`agent, ctx, dsh, skill, xd`）。
+
+所以剩余问题**不是代码没跑起来，是部署接线/打包缺口 + 一处 write 回归**。
+
+---
+
+## 2. 逐项实测记录
+
+> 以下均为本人（Dash Agent 运行时）直接调用自身 `read`/`write`/`grep`/`glob` 工具得到的第一人称结果。
+
+| scheme / 面 | 调用 | 实际返回 |
+|---|---|---|
+| skill:// 存在名 | `read skill://markitdown` | `skill "markitdown" is unknown or no longer available`（markitdown 在 `<available_skills>` 里真实存在） |
+| skill:// 不存在名 | `read skill://__nonexistent__` | 同上结构化报错 |
+| agent:// 裸 | `read agent://` | 名册表 `id / origin / depth / cwd`（4 条 session） |
+| agent://<id> | `read agent://<session-id>` | 返回该 agent 最后一条非空 assistant 输出文本 |
+| agent://<id>/transcript | `read agent://<id>/transcript` | 返回完整 transcript（role-headed） |
+| history:// | `read history://` | `history:// 已并入 agent://：…` |
+| dsh://config | `read dsh://config` | 6296 字节 resolved settings JSON；`api` 命中全为端点 URL（`api.z.ai` 等），无 key/token/secret |
+| dsh://docs | `read dsh://docs` | `dsh://docs: no docs directory found (provide docsDir to createDshHandler)` |
+| ctx:// 裸 | `read ctx://` | 空串（空命名空间） |
+| ctx://<var> | `read ctx://probe_marker` | `ctx://probe_marker: no such variable in the kernel namespace`（该变量在 eval 内核里真实存在） |
+| ctx:// 写 | `write ctx://test_var` | `write to ctx:// is not supported (read-only scheme, or its write channel is not wired yet)` |
+| xd:// 裸 | `read xd://` | `no devices mounted` |
+| xd://<device> | `read xd://lsp` | `unknown device: lsp` |
+| xd:// 写 | `write xd://lsp` | `xd:// write dispatch: no devices mounted to route the write to` |
+| 未注册 scheme | `read http://example.com/x` | `no handler registered for scheme "http" (registered: agent, ctx, dsh, skill, xd)` |
+| selector | `read dsh://config:1-3` | 按 1–3 行截断返回 |
+| grep/glob scheme | `grep skill://markitdown`、`glob skill://markitdown/**` | 均因 skill 未知而报错（路由生效，handler 上游失败） |
+| read 普通文件 | `read docs/.__editprobe.md` | 正常返回 `HASH│content` 锚点 |
+| edit 普通文件 | `edit`（先 read 后 edit） | 正常改写，锚点随内容更新 |
+| **write 普通文件** | `write /home/u1/workspaces/dashr/docs/test-ascii.md` | `cannot write "…": file access denied under workspace-write mode` |
+| **write 工作区根** | `write /home/u1/workspaces/dashr/test-root.md` | 同上被拒 |
+| **write /tmp** | `write /tmp/dashr-test.md` | 成功 `{operation: 'create'}` |
+| **bash 写工作区** | `printf … > docs/.__probe.md` | 成功（OS/bash 层不受影响） |
+
+---
+
+## 3. 失效点根因（已定位到源码）
+
+1. **`skill://`** —— `dashr/src/url-schema/handlers/skill.ts` 查 `ctx.skills.get(name)`（`@deepseek-ai/dsh-skill` 的 `SkillRegistry`），但该注册表**为空**，与注入 prompt 的 harness session skill 目录（`<available_skills>`）不是同一来源。skill handler 本身逻辑正确（错误分支、`/path` 资源寻址、路径逃逸守卫都在），只是上游 `ctx.skills` 没被喂进实际可用的 skill。
+
+2. **`dsh://docs`** —— `dashr/src/url-schema/index.ts` 的 `resolveDocsDir()` 从 `import.meta.url` 向上找 `docs/`。发布包 `@pgmi-builds/dashr` 里**没有 `docs/`**（`docs/` 在仓库根 `/home/u1/workspaces/dashr/docs`，位于包根 `dashr/` 之外，未进 npm 包）。运行时从 `~/.dsh/profiles/web/node_modules/...` 加载，向上走到 `/` 也够不着仓库里的 docs。dev 布局（`dashr/lib/index.js` 向上能到 `/home/u1/workspaces/dashr/docs`）能跑通，装进 node_modules 就断——纯打包缺口。
+
+3. **`ctx://` 读** —— `dashr/src/url-schema/tools/read.ts` 的 URL 分支调 `resolver.resolve({}, rawPath)`，传**空 env**；`handlers/ctx.ts` 随之 `queryVar(name)` 不传 `principal`，`runtime.ts:393` 落到 `AGENTLESS_KEY`（共享默认内核）——而 eval cell 跑在**会话 principal 键**的内核上。所以永远读一个没人用的空内核，真实存在的变量也报 missing。对比：文件分支正确用了 `execSessionKey(exec)`，URL 分支没传。
+
+4. **`ctx://` 写** —— `dashr/src/url-schema/tools/write.ts` 的 `defaultSchemeWrite` 对除 `xd` 外一律抛 `URL_WRITE_UNSUPPORTED`；`handlers/ctx.ts` 里已写好的 `writeCtxVar` 是**死代码**（`index.ts` 装 write 工具只传 `{ nativeWrite }`，没传 `writeScheme` 把 `ctx://` 路由到 `writeCtxVar`）。
+
+5. **mask `skill`（D5）** —— `dashr/src/index.ts:154` 的 `MASKED_TOOL_NAMES` 确实含 `'skill'`，但它只作用于 REPL 自己的 `tool.*` 绑定面（`index.ts:761`）+ Tool Catalog（`index.ts:901`），所以 eval cell 里 `tool.skill` 确实没了；但**挡不住 host 层注入的原生 `skill` 工具 + `<available_skills>` 目录**，模型从原生工具面照样能看见并调用 `skill`。验收项「工具目录不含 skill」未达成。
+
+6. **`write` 普通路径回归（新增）** —— 设计 D2 明确「不替换 write（write 保留原生，只挂 write-hook 装饰结果）」，但 v0.1.10 实际用 `tools/write.ts` 的 `createWriteTool` 以 `name: 'write'` **shadow 了原生 write**，其 `nativeWrite` 直接 `ctx.fs.resolve(...)` + `ctx.fs.writeText(...)`，**没走原生 write 工具的 write-intent 政策门**，于是对工作区路径被 sandbox 拒绝（`file access denied under workspace-write mode`），只放行 `/tmp`。对比：`read`/`edit` 走 vendored hashline 的 fs-bridge（含 `fs/write-intent` + `fs/observed` 政策门），工作区读写正常；bash 也正常。**这直接违反 spec「普通路径透传」——非 scheme 的 `write` 行为与引入 URL schema 之前不一致。**
+
+---
+
+## 4. 一处 spec 偏差（非阻断）
+
+`agent://` 名册 schema 与 spec 不符：
+
+- `specs/agent/spec.md` 要求：`id / status / kind / parent / last activity`
+- `handlers/agent.ts` 的 `renderRoster` 实际：`id / origin / depth / cwd`
+
+字段语义对不上（`origin`≠`kind`、`depth`≠`parent`、缺 `status`/`last activity`、多了 `cwd`）。
+
+---
+
+## 5. 最小修复清单
+
+| # | 缺口 | 落点 | 类型 |
+|---|---|---|---|
+| 1 | URL 分支透传会话 `principal`（复用 `execSessionKey(exec)`）给 `queryVar`/`setVar` | `tools/read.ts`、`handlers/ctx.ts`、resolver env | 代码 |
+| 2 | write 工具接上 `writeScheme`，把 `ctx://` 路由到 `writeCtxVar` | `tools/write.ts`、`index.ts` `installAgentTools` | 代码 |
+| 3 | `ctx.skills` 注册表与 harness session skill 目录同源（或 skill handler 改读 `<available_skills>` 来源） | `handlers/skill.ts`、`index.ts` 接线 | 代码 |
+| 4 | `docs/` 收进发布包（`package.json` files / 或 `docsDir` 指向随包路径） | `index.ts` `resolveDocsDir`、打包配置 | 打包 |
+| 5 | mask `skill` 到 host 注入层（非只 REPL `tool.*` 面） | host 层 / `index.ts` mask 机制 | 代码 |
+| 6 | `agent://` 名册字段对齐 spec（id/status/kind/parent/last activity） | `handlers/agent.ts` `renderRoster` | 代码/文档 |
+| 7 | **修复 `write` 普通路径回归**：native 分支走原生 write-intent 政策门（或直接委托上游原生 write），而非裸 `ctx.fs.writeText` | `tools/write.ts` `nativeWrite`、`index.ts` | 代码 |
+
+---
+
+## 6. 复测计划（修复后执行）
+
+1. `read skill://<真实 skill 名>` 返回正文；`skill://<name>/<path>` 返回内部资源；未注册名结构化报错。
+2. 原生工具面不再出现 `skill`（且 `<available_skills>` 保留为发现层）。
+3. `read dsh://docs` 返回文档清单，`dsh://docs/<doc>` 返回正文。
+4. eval 里 `x = 1` 后 `read ctx://x` 返回 `1`；`write ctx://y` 后 `read ctx://y` 返回新值。
+5. `read ctx://` 列出命名空间（含刚写的 y）。
+6. `agent://` 名册含 status/kind/parent/last activity。
+7. **`write <工作区普通路径>` 成功（回归修复）**。
+8. 回归：`read`/`write`/`grep`/`glob` 普通路径 + hashline 锚点无回归；`npm test` 全绿。