better-dsh 0.2.5-b → 0.2.5-d

package/docs/specs/docs-packaging-trim/spec.md

@@ -0,0 +1,110 @@
+# 发布包瘦身：摘掉与 DSH/本插件无关的 docs（docs-packaging-trim）
+
+状态：**设计已定（user 裁决 2026-10-03：档位 F）；待落实现**
+｜ 规格路径：`docs/specs/docs-packaging-trim/spec.md`（仓库根 docs；`better-dsh/docs/` 是 `prebuild` 由 `../docs` 重建的产物，别写那里）
+
+---
+
+## 0. 动机（审计实证）
+
+`better-dsh` 的 tarball 是 **20.2 MB**，而 `lib/`（真正的代码）只有 **2.5 MB**。差额几乎全在**随包发布的 docs 副本**上：`tar czf docs` = **20.3 MB**（含 tar 开销），即 tarball 基本等于 docs。
+
+`scripts/copy-docs.mjs` 把仓库 `docs/` 拷进 `better-dsh/docs/`（`files: ["docs"]` 发布），已有 EXCLUDE 规则只挡了 `60_exploration-and-research/`、`superd/`、`dsh-sys-prompt_*.md`、`*_artifacts/`。逐目录盘点后，剩下的发布面里混着**与 DSH 和本插件都无关的东西**。
+
+### 0.1 关键澄清：`80_upstream-docs-and-skills/` 不是"纯文档"
+
+user 提问："`api-skills.json` 不是给人读的，那它存在的唯一意义就是作为技能放在 skills 目录让 harness 读取，对吧？既然是纯文档就不需要它？"
+
+**比这更弱**——该目录自己的 `src-README.md` 写明：
+
+> This stage only does the **fetching**; distillation into a skill is a separate follow-up
+
+即 `hermes-dev-skill/` 是"抓取 → 蒸馏成技能"两阶段流水线的**第一阶段**，而**第二阶段从未执行**：整个目录没有 `SKILL.md`、没有 `skill/`。所以这 77 MB 是**没有被任何东西消费的流水线输入**——既不是技能，也不是文档。`api-skills.json` 是 `https://hermes-agent.nousresearch.com/docs/api/skills.json`（59 MB），**Hermes 自己那套技能的机器可读目录**，`grep` 全仓无引用。
+
+### 0.2 归属：这是别人的框架说明书
+
+`hermes-dev-skill` 是 **NousResearch/hermes-agent** 官方文档的完整镜像（`src-README.md` 记着 sparse clone commit `4e9d3c71…` 与抓取日期 2026-09-16），它自己声明的用途是：
+
+> so agents that develop / integrate with **Hermes Agent** can work without hitting the live site
+
+——一个**别的 agent 框架**的说明书。Hermes 有自己的文档站与仓库（该 README 自己就引了）。入库溯源：commit `d13c4a3`，提交信息为 *"rig(test123): remove profiles/node_modules symlink farm"*——一个与文档无关的 rig 提交把它捎带进来。
+
+### 0.3 全树盘点（`copy-docs.mjs` 实际发布范围）
+
+| 路径 | 磁盘 | 是什么 | 判定 |
+|---|---|---|---|
+| `00_adr/` `10_plans/` `20_specs/` `specs/` | 980 K | 本仓 ADR / 计划 / 规格 | ✅ 留 |
+| `50_test-reports/` | 3.5 M | 本仓实测报告（已做 token 脱敏） | ✅ 留 |
+| `superpowers/` | 40 K | 本仓两份 spec/plan | ✅ 留 |
+| `80_.../hermes-dev-skill/` | **77 M** | 别家框架文档镜像；抓取阶段，无 `SKILL.md`，零引用 | ❌ **摘** |
+| `80_.../dsh-dev-skill/pi-and-omp/` | **2.8 M** | OMP / Pi 第三方资料；**技能正文零引用**（`grep -rn "pi-and-omp" skill/` 为空） | ❌ **摘** |
+| `80_.../dsh-dev-skill/src-scripts/` | **3.4 M** | 抓取工具 + `docs-tree.json`（3.5 M 构建清单） | ❌ **摘** |
+| `80_.../dsh-dev-skill/skill/` | 304 K | DSH 开发知识库蒸馏稿（`SKILL.md` + 22 章）——**静态文档**，与技能运行时无关 | ✅ 留（DSH 相关） |
+| `80_.../dsh-dev-skill/src/` | 4.0 M | DSH 官方文档快照——**被 `SKILL.md` 与 4 个章节明确引用** | ✅ 留 |
+| `dsh-docs/`（包根） | 4.1 M | DSH 官方文档（较新），`dsh://docs` 主面 | ✅ 留 |
+| `60_exploration-and-research/` `superd/` | — | 已在既有 EXCLUDE 内 | — |
+
+> **不要整段摘 `80_upstream-docs-and-skills/`**：`dsh-dev-skill/` 的内容是**蒸馏过的官方 DSH 文档**，按本 change 的留置规则属「与 DSH 相关」的静态文档。**与技能运行时无关**：Harness 技能发现只扫四个根（`<project>/.dsh/skills`、`<project>/.agents/skills`、`~/.dsh/skills`、`~/.agents/skills`，见 `packages/skill/skill-filesystem/src`），插件 docs 树从来不在其中。`dsh://docs` 是纯静态资源——装了插件任何人都能读，里面的目录叫不叫 skill，与 Harness 加载什么技能毫无关系。早期版本的本节曾称它是「运行时真正加载的技能、整段摘会打断一个技能」，**那是错误推断**（把「文件存在」当成了「被运行时加载」），已撤回。
+
+> **重复发布（本 change 不处理）**：`dsh-docs/`（249 文件）与 `…/dsh-dev-skill/src/docs/`（241 文件）是同一套官方 DSH 文档的**两个修订版**（后者较旧）。摘后者需同时改写 `SKILL.md` 与 4 个章节里 `../src/docs/` 的指向——那是**文档内部交叉引用**问题（静态库里出现悬空指针），不是技能问题，另开 change 评估。
+
+---
+
+## 1. 目标态（硬契约）
+
+1. **发布副本里不再出现**：`hermes-dev-skill/`、`dsh-dev-skill/pi-and-omp/`、`dsh-dev-skill/src-scripts/`。
+2. **repo 的 `docs/` 一字不动**：`copy-docs.mjs` 只改写发布副本 `better-dsh/docs/`。本仓测试报告、技能源、任何交叉引用与本地技能（如引用 `site-pages-map.txt` 的 `.agents/skills/cordis-dsh-dev`）全不受影响。
+3. **承重面完好**：`dsh-dev-skill/skill/`（含 `SKILL.md`）与其引用的 `src/docs/`、`src/site-pages-map.txt` 必须**全部保留**。
+4. **无新的悬空引用**：发布副本内不得有指向被摘路径的活引用（见 §3 的已知例外）。
+5. **不改语言/行为面**：本 change 纯打包面，不触碰任何源码或技能正文。
+
+---
+
+## 2. 改动
+
+`scripts/copy-docs.mjs` 的 `EXCLUDE` 数组增加 3 条目录规则（沿用既有的"按源路径正则匹配"形式）：
+
+```js
+/(^|\/)hermes-dev-skill($|\/)/,
+/(^|\/)dsh-dev-skill\/pi-and-omp($|\/)/,
+/(^|\/)dsh-dev-skill\/src-scripts($|\/)/,
+```
+
+不删除任何仓库文件，只改变**进包集合**。
+
+---
+
+## 3. 已知例外（明示接受，不做过度工程）
+
+`docs/80_upstream-docs-and-skills/dsh-dev-skill/src-README.md` 在正文里提到 `src-scripts/`（抓取清单的结构说明）。摘掉该目录后，**发布副本**里这份 fetch manifest 会描述一个不在包内的目录。
+
+- 影响面：仅"文档自述"的措辞不一致，无功能影响；该 manifest 的价值在于说明 `src/` 是什么。
+- 处置：**接受**。不改写正文（改写会让发布副本与 repo 副本分叉，违背 §1.2）。若日后要更干净，用发布期的占位替换，另开 change。
+
+---
+
+## 4. 验收
+
+1. **量化**：`npm pack` 出的 tarball 从 **20.2 MB → ≈ 3.7 MB**（docs 贡献 20.3 → 3.7 MB）；安装后磁盘 sizeof(`docs/`) 从 **98 MB → ≈ 15 MB**。
+2. **承重存活**：解包 tarball，`docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/SKILL.md` 与 `src/docs/`、`src/site-pages-map.txt` 均在位；被摘三目录不存在。
+3. **静态文档可读**：rig 上 `read dsh://docs/80_upstream-docs-and-skills/dsh-dev-skill/skill/SKILL.md` 能取回正文——它只是众多静态文档之一。~~会话技能目录仍列出 `dsh-dev-skill`、`skill://dsh-dev-skill` 可读~~ 该判据建立在错误模型上，撤回：技能是否被 Harness 加载取决于 user 本地 / per-workspace 安装，与本插件无关。
+4. **零新增悬空引用**：在解包后的 `docs/` 内 `grep -rn "hermes-dev-skill\|pi-and-omp\|src-scripts"` 只剩 §3 那一处已知例外。
+5. **`dsh://docs` 可读性不变**：`read dsh://docs` 列表与抽查若干路径仍正常。
+6. 实测报告落 `docs/50_test-reports/`；发布仍需 user 明确放行。
+
+---
+
+## 5. 风险
+
+| 风险 | 说明 | 处置 |
+|---|---|---|
+| 误摘承重目录 | `80_upstream-docs-and-skills/` 名字像"纯上游资料"，实则含承重技能 | §1.3 硬契约 + 验收第 2/3 条把关 |
+| 规则误伤同名目录 | EXCLUDE 是正则，若将来别处出现同名目录会被一并摘 | 规则带路径前缀锚定（`dsh-dev-skill/…`），不做裸名匹配 |
+| 与 ast-engine-deomp 同批发布 | 两者都改打包面，回归时互相遮蔽 | 验收分开做：先各自量化，再合并实测一次 |
+
+---
+
+## 6. 进展日志
+
+- **2026-10-03 设计轮**：user 发现 Hermes 材料混入并质疑归属，要求"只要跟 DSH 不相关、跟我们这个插件不相关的，全部摘掉"。完成全树审计（见 §0.3），确认：`hermes-dev-skill` 是别家框架的**未消费抓取产物**（无 `SKILL.md`）；`pi-and-omp` 被技能正文零引用；`dsh-dev-skill/skill` + `src/` 承重不可摘。user 裁决**档位 F**（只摘未引用的外来物与构建机械）。实测数字：tarball 20.3 → **3.7 MB**；磁盘 98 → **15 MB**。
+- 附带澄清（user 提问驱动）：`api-skills.json` 既非技能亦非文档，是未完成流水线的输入；"包内 gzip"被否决——npm tarball 本就是 gzip，包内再压只影响安装后磁盘，且 `dsh://docs` 读纯文本，需为**零引用**文件新增解压读路径，方向错误。

package/docs/specs/dvc/spec.md

@@ -35,12 +35,31 @@ The system SHALL implement the device write contract: `write dvc://<device>` wit
 - **THEN** the device executes and its result returns to the caller
 
 ### Requirement: ast devices
-The system SHALL provide `ast_edit` (staged structured codemod) and `ast_grep` (structured search) devices, vendored from the omp harness (MIT), backed by the published `@oh-my-pi/pi-natives` binding.
+The system SHALL provide `ast_edit` (staged structured codemod) and `ast_grep` (structured search) devices, backed by the official ast-grep engine compiled to WebAssembly plus an in-package tree-sitter grammar set (`lib/ast-assets/`), with no OMP and no native binary.
 
 #### Scenario: ast_grep search over a workspace file
 - **WHEN** the model writes `dvc://ast_grep` with a pattern and path
 - **THEN** structured matches return from the AST search
 
+### Requirement: Diagnostic fields (deliberate divergence from the native predecessor)
+The ast devices SHALL surface failure modes that the native predecessor swallowed silently (0.2.6 contract addition). `ast_grep` results SHALL carry `patternErrors?: string[]` — present (non-empty) iff at least one supplied pattern failed to compile as a single-root AST node, one entry per failing pattern formatted `pattern <index> ("<pattern text>"): <underlying message>`; multi-root patterns land here and matches from the remaining patterns still return — and `pathNotFound?: boolean` — `true` only when the resolved target path does not exist on disk, absent otherwise. `ast_edit` results SHALL carry the same `patternErrors` semantics over `ops[].pat` (a failing op contributes no edits), `overlapping?: number` — the count of edits dropped by the overlap guard, present only when greater than zero — and the same `pathNotFound` semantics (true when at least one resolved target root does not exist on disk). Patterns that fail with a hard syntax compile error SHALL still throw through as `DVC_DEVICE_ERROR`. The devices perform no workspace boundary check — the boundary is the approval/policy layer — and `ast_edit` writes whatever paths it is given. All pre-existing fields keep their names and semantics.
+
+#### Scenario: Multi-root pattern is reported, not swallowed
+- **WHEN** `ast_grep` runs a multi-root pattern (e.g. `"alpha": $V`) that fails to compile as a single-root AST node
+- **THEN** the result carries `patternErrors` with one entry naming the pattern index, the pattern text, and the underlying message, and zero matches from that pattern — instead of an indistinguishable empty result
+
+#### Scenario: Missing path is distinguishable from zero matches
+- **WHEN** the resolved target path does not exist on disk
+- **THEN** the result carries `pathNotFound: true` with `filesSearched: 0`, so "nothing there" is no longer confused with "pattern matched nothing"
+
+#### Scenario: Overlap-guard drops are counted
+- **WHEN** `ast_edit` ops produce edits that overlap an already accepted edit
+- **THEN** the first-registered op wins, the shadowed edit is dropped, and the result reports the dropped-edit count in `overlapping` instead of dropping it silently
+
+#### Scenario: Hard syntax errors still throw
+- **WHEN** a pattern fails with a hard syntax compile error (e.g. `$$$`)
+- **THEN** the device throws and the caller receives the structured `DVC_DEVICE_ERROR`, exactly as before
+
 ### Requirement: browser device
 The system SHALL provide a `browser` device (open/close/run over real browser tabs) vendored from the omp harness, using puppeteer-core against the system Chrome; when no browser can launch, the device returns a structured error.
 

package/docs/specs/remote-pty-label/spec.md

@@ -0,0 +1,126 @@
+# remote-pty-label Specification
+
+## Purpose
+
+`remote` 工具的持久化 BYO-PTY 通道从「`spawn` 命令原文即会话键」改为「`target` 选择器寻址的具名会话」。旧实现的池键就是整条 spawn 文本，于是「同一条命令」与「同一个会话」被绑死：改一个 token 就**静默**新开一个 shell（cwd/env 全丢、零提示），roster 又拿整整一条 shell 命令当会话名。本规格固定新契约——`byop:<label>` 是唯一入口、label 由调用方（模型）自选并因此成为复用入口、`spawn` 降格为该 label 首次创建时的伴生参数——并据此定义创建/复用/冲突三分支、失败面，以及裸名候选表的末位新增项。
+
+## Requirements
+
+### Requirement: 单入口寻址
+
+`target` SHALL 是 `remote` 工具的唯一分流入口。以 `byop:` 开头的 target SHALL 被解析为 PTY 选择器，冒号之后的全部内容为 label。`spawn` SHALL 仅在与 `byop:<label>` target 同时出现时合法——它不再是独立入口。
+
+#### Scenario: spawn 不能独立成调用
+
+- **WHEN** 调用只给 `spawn`（无 target，或 target 不是 `byop:` 选择器）
+- **THEN** 系统返回 `[E_PARAMS]` 并在消息内给出正确形状 `{ target: "byop:<label>", spawn: "…", cmd: "…" }`，且不创建、不触碰任何会话
+
+#### Scenario: label 字符集
+
+- **WHEN** label 不匹配 `^[A-Za-z0-9][A-Za-z0-9._-]*$`（空 label、含空白、含 `:` 等）
+- **THEN** 系统返回 `[E_BAD_LABEL]` 并在消息内给出合法形状，且不触碰会话池
+
+#### Scenario: PTY 选择器锁定 mode
+
+- **WHEN** `byop:<label>` target 与显式 `mode:"oneshot"` 同时出现
+- **THEN** 系统返回 `[E_BAD_MODE]`，而不是静默降级或静默改写 mode
+
+### Requirement: label 即复用入口，命名空间按 agent 隔离
+
+PTY 会话 SHALL 以 `` `${agentSessionKey}|p:${label}` `` 为池键。`spawn` 原文 SHALL 作为创建来源（origin）随会话保存，仅用于同 label 重复给 spawn 时的比对。label 首次创建之后，仅给 `{ target: "byop:<label>", cmd }` SHALL 复用该会话，cwd/env 存活。
+
+#### Scenario: 创建后仅凭 label 复用
+
+- **WHEN** 先调用 `{target:"byop:dev3", spawn:"bash", cmd:"cd /tmp && export MARK=live"}`，再调用 `{target:"byop:dev3", cmd:'echo "$MARK" && pwd'}`
+- **THEN** 第二次调用在**同一个** shell 内执行，输出含 `live`、cwd 为 `/tmp`，且结果带 `session: "byop:dev3"`
+
+#### Scenario: 两个 agent 的同名 label 互不可见
+
+- **WHEN** agent A 创建了 `byop:dev3`，agent B 以同一 label 且不给 spawn 调用
+- **THEN** B 得到 `[E_NO_SESSION]`，A 的会话不受任何影响
+
+### Requirement: 同 label 重复 spawn 的三分支
+
+对已存在的 label 再次给 `spawn` 时，系统 SHALL 将其与创建来源比对：相同即复用并在结果内附教学提示；不同即拒绝，且 SHALL NOT 执行任何命令。
+
+#### Scenario: 同一 spawn → 复用 + 提示
+
+- **WHEN** 对活着的 `byop:dev3` 再次传入与创建时逐字相同的 `spawn`
+- **THEN** 调用在既有会话内执行，结果的 `notice` 说明该 PTY 是持久化的、后续可省略 `spawn`（只写 label）
+
+#### Scenario: 不同 spawn → 冲突，什么都不跑
+
+- **WHEN** 对活着的 `byop:dev3` 传入与创建时不同的 `spawn`
+- **THEN** 系统返回 `[E_LABEL_CONFLICT]`，消息内含既有 spawn 原文与「丢掉 spawn 复用它 / 换一个 label 新建」两条出路，**cmd 不执行**，既有会话状态不变
+
+### Requirement: 无会话面 fail-loud 且不保留 spawn
+
+label 从未创建、或已被 idle TTL（默认 600s）回收时，不带 `spawn` 的调用 SHALL 返回 `[E_NO_SESSION]`。spawn 命令 SHALL NOT 被跨会话保留（无墓碑、无自动重建）。
+
+#### Scenario: 回收后必须重贴 spawn
+
+- **WHEN** `byop:dev3` 因 idle TTL 出池后调用 `{target:"byop:dev3", cmd:"echo hi"}`
+- **THEN** 系统返回 `[E_NO_SESSION]`，消息内给出带 `spawn` 的重建形状，并说明 spawn 未被保留
+
+### Requirement: 初始化失败不留任何东西
+
+首建命令未能初始化（`[E_SESSION_DIED]` / `[E_SESSION_START]`）时，该 PTY 会话 SHALL 出池：label 与 TTY SHALL NOT 被建立——这里从来没有过一个可用会话。**已 ready 过**的会话死亡 SHALL 留在池内（那是 reconnect 语义），不受本需求约束。
+
+#### Scenario: 失败的 spawn 之后 label 仍然自由
+
+- **WHEN** `{target:"byop:x", spawn:"…", cmd:"…"}` 的首建命令未能初始化
+- **THEN** 随后不带 spawn 的复用得到 `[E_NO_SESSION]`（而非重跑冻结的 argv 再失败一次），且带**任意** spawn 的调用 SHALL 正常新建——不得被创建来源比对拦成 `[E_LABEL_CONFLICT]`
+
+#### Scenario: 已 ready 的会话死亡仍可重连
+
+- **WHEN** 一个曾经初始化成功的 `byop:<label>` shell 死亡后被复用
+- **THEN** 该会话留在池内、按原创建命令重连并附 reconnect 提示
+### Requirement: 状态面与 roster 以 label 呈现
+
+`{target:"byop:<label>"}`（无 cmd）SHALL 只读池内状态、零拨号。roster SHALL 以 `byop:<label>` 命名会话，SHALL NOT 泄露 spawn 命令。
+
+#### Scenario: 探测不存在的 label
+
+- **WHEN** 对无会话的 `byop:<label>` 做 status 调用
+- **THEN** 返回 `session: none — no live PTY under this label`（不是 transport target 的 "dials on first exec"，也不报错）
+
+#### Scenario: roster 只给 label
+
+- **WHEN** 调用方自己以 `UNIQUESPAWNMARKER bash` 创建了 `byop:dev3`
+- **THEN** roster 包含 `live pty sessions: byop:dev3`，且文本中不出现 `UNIQUESPAWNMARKER`
+
+### Requirement: roster 的活性面按 agent session 作用域
+
+「live pty sessions」段 SHALL 只列调用方 agent session 自己的会话（池键前缀 = 调用方 sessionKey）。`ssh hosts` / `docker containers` / `incus containers` 三段名字候选 SHALL 保持全局可见。理由：名字候选是**静态公共配置**（谁都能 `ssh dev4`），活会话却是**操作环境**——复用别的 agent 留下的 shell 等于继承未知状态，而两个 agent 各开一条线的代价可忽略。BYO-PTY 天然是活的，因此自然落进这个 scope，无需另立规则。
+
+#### Scenario: 两个 agent 各自只看见自己的活会话
+
+- **WHEN** agent `a1` 建了 `byop:mine`、agent `a2` 建了 `byop:theirs`，随后各自调 `{}`
+- **THEN** `a1` 的 roster 含 `byop:mine` 且不含 `byop:theirs`（反之亦然），而两边 `ssh hosts` / `docker containers` / `incus containers` 三段内容相同
+### Requirement: 模型面不得泄露池内部键
+
+面向模型的文本（roster、status、错误消息）SHALL 只出现模型面名字（`byop:<label>`、裸 transport target），SHALL NOT 出现池键（`` `${agentSessionKey}|p:<label>` `` / `|t:<target>`）。key→名字 SHALL 是单一定义（`displayKey`），roster 与错误面共用同一条规则。
+
+#### Scenario: 初始化失败的错误消息
+
+- **WHEN** agent `sess-abc` 的 `byop:x` 初始化失败
+- **THEN** 错误消息含 `'byop:x'`，且不含 `sess-abc`、不含 `|p:`
+
+### Requirement: 裸名候选表末位新增 PTY label
+
+裸名解析顺序 SHALL 保持 ssh config 字面 host → docker → incus **一位不挪**，并在这三段之后、ssh 兜底之前追加「池内活 PTY label」候选。该候选 SHALL 仅在调用面未显式指定 `mode:"oneshot"` 时参与匹配。命中顺序即优先级：同名冲突时更靠前的来源胜出。
+
+#### Scenario: 无重名时裸 label 可达（懒复用）
+
+- **WHEN** 池内有 `byop:lab`，ssh config / docker / incus 均无 `lab`，且调用 `{target:"lab", cmd:"…"}`（未指定 mode）
+- **THEN** 调用落在该 PTY 会话上（mode 为 `pty`），结果 `session` 为 `"byop:lab"`
+
+#### Scenario: 重名时 ssh host 优先
+
+- **WHEN** ssh config 存在 `Host lab`，同时池内有 `byop:lab`
+- **THEN** 裸名 `lab` 仍解析为 ssh transport（现有优先级逐位不变）；要进 PTY 通道必须显式写 `byop:lab`
+
+#### Scenario: 显式 oneshot 不吃 PTY 候选
+
+- **WHEN** 调用显式带 `mode:"oneshot"` 且 target 为裸名
+- **THEN** 该调用不走 PTY 末位候选，裸名在 `mode:"oneshot"` 下的旧行为逐位保留