dsh-vibe-math 2.3.15 → 2.4.0

package/docs/AUDIT-CHECKLIST.md

@@ -320,46 +320,110 @@ provider **直接拒绝**。于是"提示词/规格/状态表都写着这个参
 
 - 缺陷要分**类**："这一整类此前没有审计维度"比"修了 N 个 bug"更重要。
 - 假绿/假红必须单独说明：**审计本身失效**是最严重的发现。
-- 每条结论都要给出**可复核的证据**（真实日志片段、语料原文、可重跑的命令与结果）。
-
----
-
-## 6. 发布说明（Release Notes / GitHub Release）格式
-
-**中英双语、先中文后英文，只写"给用户看的信息"。** 工程过程（探针结果、断言条数、事故复盘、行号与
-内部编号）属于 `_oneoff/audit-findings-*.md` 台账与提交信息，**不进**发布说明。
-
-固定骨架（只有版本号、标题与正文随版本变，**节名不变**）：
-
-```markdown
-# dsh-vibe-math <版本> — 发布说明（中文）
-
-> 上一版：<版本>。<一句话：这一版是干什么的、是否影响行为。>
-
-## 概览
-## 变更
-## 兼容性
-## 升级
-
----
-
-# dsh-vibe-math <版本> — Release Notes (English)
-
-> Previous: <version>. <One sentence: what this release is and whether behaviour changes.>
-
-## Overview
-## Changes
-## Compatibility
-## Upgrade
-```
-
-- [ ] 两个 H1 都在；**英文那份的 H1 必须含 `English`**（发布门禁阶段 1c 会检查）；
-- [ ] 中文部分 ≥ 150 个汉字（门禁同阶段检查），英文部分不得残留未翻译段落；
-- [ ] 每条变更都回答"**对使用者有什么影响**"——不写内部编号、探针名、断言条数；
-- [ ] 「兼容性」明确回答：四套预设的字节/行为是否变化、参数与工具面是否变化；
-- [ ] 「升级」给出可直接复制的命令（`npm i dsh-vibe-math@latest`；若 profile 里把版本钉死了，
-      写出对应的 `dsh plugin --profile <name> add dsh-vibe-math@latest`）；
-- [ ] **发布前把草稿交给用户确认**（在对话里展示全文，或用提问工具）；用户同意或给出修改意见后再发布；
-- [ ] GitHub Release 的正文 = 这份文件本身（`gh release create --notes-file <该文件>`），标题中英并列。
-
----
+- 每条结论都要给出**可复核的证据**（真实日志片段、语料原文、可重跑的命令与结果）。
+
+---
+
+## 6. 发布说明（Release Notes / GitHub Release）格式
+
+**中英双语、先中文后英文，只写"给用户看的信息"。** 工程过程（探针结果、断言条数、事故复盘、行号与
+内部编号）属于 `_oneoff/audit-findings-*.md` 台账与提交信息，**不进**发布说明。
+
+固定骨架（只有版本号、标题与正文随版本变，**节名不变**）：
+
+```markdown
+# dsh-vibe-math <版本> — 发布说明（中文）
+
+> 上一版：<版本>。<一句话：这一版是干什么的、是否影响行为。>
+
+## 概览
+## 变更
+## 兼容性
+## 升级
+
+---
+
+# dsh-vibe-math <版本> — Release Notes (English)
+
+> Previous: <version>. <One sentence: what this release is and whether behaviour changes.>
+
+## Overview
+## Changes
+## Compatibility
+## Upgrade
+```
+
+- [ ] 两个 H1 都在；**英文那份的 H1 必须含 `English`**（发布门禁阶段 1c 会检查）；
+- [ ] 中文部分 ≥ 150 个汉字（门禁同阶段检查），英文部分不得残留未翻译段落；
+- [ ] 每条变更都回答"**对使用者有什么影响**"——不写内部编号、探针名、断言条数；
+- [ ] 「兼容性」明确回答：四套预设的字节/行为是否变化、参数与工具面是否变化；
+- [ ] 「升级」给出可直接复制的命令（`npm i dsh-vibe-math@latest`；若 profile 里把版本钉死了，
+      写出对应的 `dsh plugin --profile <name> add dsh-vibe-math@latest`）；
+- [ ] **发布前把草稿交给用户确认**（在对话里展示全文，或用提问工具）；用户同意或给出修改意见后再发布；
+- [ ] GitHub Release 的正文 = 这份文件本身（`gh release create --notes-file <该文件>`），标题中英并列。
+
+---
+
+## 7. 中英双语 README 与英文版架构图（2.3.16 起）
+
+- **默认语言**：`README.md` 为中文（默认、GitHub 首屏），`README.en.md` 为英文；两文顶部各有一行切换器
+  （中文版 `[English](README.en.md) | 中文`，英文版 `English | [中文](README.md)`）。不建 `README.zh.md`。
+- **结构同构**：标题层级序列、表格行数、代码块数、图片数量、本地链接集合必须一一对应；
+  唯一允许的差异是四张架构图各自指向 `-en` 版本（按序号配对校验）。
+- **文件与产物名不翻译**：真实目录/文件名（`示例图/…`、`docs/架构图.md`、`Verified/命题/`、`Logs/报告.md`）、
+  真实 JSON 键（`已解决`、`正确概率`）、真实格式锚点（`- ID/类型/状态/概率/…`、`### 解法/证明/证伪 N｜标题｜概率X｜状态Y`）、
+  会话重建标记 `【会话重建 —— <role> <id>】`、v2/v3 真实 md 字段名（`可信断言`、`上级体系`、`子方法`）**保持原样**，
+  首次出现处可加括注；除此以外的正文必须是英文（`tests/audit-readme-bilingual.test.mjs` 的 CJK 预算兜底）。
+- **架构图**：四张英文图 `示例图/框架图-v{2,3,4,5}-en.svg` 只被 `README.en.md` 引用，中文图不受影响；
+  v4/v5 用现有零依赖生成器加 `--lang=en`（`docs/generate_framework_diagram_v4.mjs`），
+  v2/v3 用独立的零依赖 Node 生成器 `docs/generate_framework_diagram_v{2,3}_en.mjs`（中文 v2/v3 海报仍由 matplotlib 脚本产出）。
+  英文图内只允许保留上述"真实字面量"的中文，`tests/audit-diagram-assets.test.mjs` 按图核 CJK 预算。
+- **历史文档必须标注适用范围**：描述旧版本布局的文档（如 v1 时期的 `docs/架构图.md`）要在开头写明它描述的是哪一版，
+  不能在被 README 当作"当前详解"引用时静默误导（`qs.csv`、`Pending_Verification/` 等 v1 名称在 v2 起已不存在）。
+
+---
+
+## 8. 宿主版本线适配与发布流程实测教训（2.4.0 起）
+
+### 8.1 一条版本线一个机制：先定"形态"，再谈"版本"
+
+DSH 的 **agent preset 交付方式**在 0.1.6 → 0.1.7 之间换过一次，且**旧机制是被彻底删除**的：
+
+| 版本线 | preset 形态 | 本文档对应做法 |
+|---|---|---|
+| ≤ 0.1.6 | 目录 `<DSH_HOME>/.agent-presets/<id>/{agent.cordis.yml,preset.yml,…}` | `installer.js` 复制（`detectPresetMechanism` 判为 `directory`） |
+| ≥ 0.1.7 | 组合行 `@deepseek-ai/dsh-agent-preset`（`agentPresets.register({id,plugins,…})`） | `cordis.patch.yml` 里的声明行（判为 `rows`，安装器跳过目录同步） |
+
+**判定必须用能力，不要用版本号**：`agentPresets` 服务在两条线上都存在但语义不同（旧线是目录扫描器、没有 `register`），
+所以判定改成读 **loader 入口树**里有没有 `@deepseek-ai/dsh-agent-preset`（或其 registry）——这在任何插件激活之前就可见，
+而"读服务"在 bundle 被单独激活（`dsh plugin add`）时可能还没就绪。**旧线上"装了但看不见"正是本版修掉的那类缺陷。**
+
+### 8.2 组合行声明的四条硬约束（都是实测出来的）
+
+1. **`dsh.bundle.patch` 必须是字符串**。数组形态只有 ≥ 0.1.7 接受；0.1.5/0.1.6 会把该值直接送进 `path.join`，
+   结果是整个 profile **起不来**（`ERR_INVALID_ARG_TYPE`）。要多个 patch 就合并成一个文件。
+2. **声明行不要命名宿主包**（如 `@deepseek-ai/dsh-agent-preset`）：旧线上该包不存在，行会 `failed to import`，
+   每次启动都报一条激活失败。改成本包自己的模块（`preset-declaration.js`），它在旧线上**什么都不注册且不报错**。
+3. **声明行不能用 `disabled: !!js` 做版本门**：patch 表达式里 **`ctx.get(...)` 会抛**（实测：常量、`typeof ctx` 正常，
+   任何服务查询都让入口永远不初始化，报 "N entries did not activate"）。要按宿主能力分流，就分到**代码里**（运行时读服务）。
+4. **声明行里的 `name` 不会被改写成文件 URL**（app-boot 只递归 group 的 config），loader 会拿**profile 目录**去解析相对路径
+   → `./vibe-math-vN.js` 必 ENOENT、整个 preset 拒绝挂载。必须用**包内子路径**（`dsh-vibe-math/vibe-math-vN/vibe-math-vN.js`）+ `exports` 放行。
+
+### 8.3 不要在宿主的"历史事件"面上存自己的状态
+
+会话日志是**只增不改**的，但**读它是严格的**：持久化层遇到不认识的 `type` 会**拒绝加载整个会话**，除非写入方标了
+`ignorable: true`——而 `Session.append` **无法**设置该字段（只有构造种子能）。所以"把插件状态写进会话日志"这条路
+会让**用户自己的会话在下次恢复时打不开**（静默：写入成功、失败发生在之后的加载）。自研状态请落在自己的文件里（v5 即如此）。
+
+### 8.4 发布流程：`npm publish` 返回 202 不是失败
+
+- `npm publish` 得到 **HTTP 202** + "Your package is being processed…" 时，registry 正在**异步处理**；此时 `npm view` /
+  `dist-tags` / 版本 manifest / tarball 都可能是 404 或旧值，**持续数分钟**。
+- 期间重发会得到 **409 `Cannot publish over previously staged version`**——这句措辞会让人误以为被扣下等 2FA 批准
+  （`npm stage list` 实测为空，并非 staged）。**正确处理：等待并轮询 packument**（`dist-tags.latest` + `/<pkg>/<ver>` + tarball HEAD），
+  **绝不在此时改版本号或内容**。
+- `dsh plugin --profile <p> add` 在 Windows 上可能**在 pnpm 完成后才崩**（`0xC0000409`，报 "pnpm failed"）：
+  **不要信退出码**，查 `package.json` 的 spec、lockfile、`node_modules` 三处是否一致，不一致就只对齐 manifest。
+
+---
+

package/docs/COMPAT-AUDIT-ROUND2.md

@@ -323,3 +323,6 @@ e2e-f1-agent-detach    CONFIRMED (drives the real AgentRegistry)
 | R3「v4 硬编码假名、无重试可能半启动」 | v4 的过滤器**只用用户传入的名字**，不硬编码网络/脚本名；该条**不成立**（v4 的真实问题是注册未纳入 `ctx.effect`） |
 | R1 仅"代码阅读推断" | 本轮**用真实 `AgentRegistry` 可执行复现**（`prove-f1-agent-detach.mjs`，exit 0） |
 | 「兼容性审计 0 处崩溃」 | 兼容性缺陷确实不是崩溃型，但 F-2 会让子代理**永远起不来**，属功能失效而非"无问题" |
+
+> **后续轮次**：DSH 0.2.0 的适配审计与四宿主实测记录见 [`COMPAT-AUDIT-ROUND3.md`](COMPAT-AUDIT-ROUND3.md)
+> （预设交付形态换代、会话事件白名单、子代理数量上限、工具名抛错、压缩语义等）。

package/docs/COMPAT-AUDIT-ROUND3.md

@@ -0,0 +1,139 @@
+# Vibe-Mathematics × DSH 0.2.0-rc.2 —— 第三轮兼容性审计（适配记录）
+
+> 本轮目标：把四套预设适配 **DSH 0.2.0**（当前版本），同时保住旧版本线；并在过程中把"版本线切换"这件事
+> 从"猜"变成"能力探测 + 四宿主实测"。结论先行：**0.2.0 的破坏性变更不是 API 签名**，而是三类：
+> ① 预设交付**形态换代**（旧的目录发现被彻底删除）；② 新增**硬性行为**（会话事件白名单、子代理数量上限、
+> 工具名抛错、压缩的"策略 vs 执行"语义）；③ 兼容性判定从 `engines` 扩展为 `peerDependencies`。
+
+---
+
+## 0. 摘要
+
+- 并行做了 4 份契约审计（组合行与声明 / `subagents`+`agents`+事件 / `tools`+`commands`+`timer` / `compaction`+`sessionProjections`+`sessions`+`subprocess`+`sandboxPolicy`），
+  每份都以**已安装的 0.2.0-rc.2 源码**（`lib/**/*.d.ts` 与实现）为证据。
+- 另外做了**四宿主实测**：把本包分别装进 `0.1.5-rc.2`、`0.1.6-alpha.2`、`0.1.7-rc.2`、`0.2.0-rc.2` 的独立 `DSH_HOME`，
+  启动后用宿主自己的 `agentPresets.list()` 读回预设清单。这是"预设到底有没有出现在选择器里"的唯一可信判据。
+- 结果：修复后四条版本线上预设**都**会出现（旧线走目录、新线走声明行），且新线上**零激活警告**。
+
+---
+
+## 1. 确证的缺陷
+
+### G-1 preset 在新宿主上完全不可见（致命，2.3.x 全线命中）
+
+DSH 0.1.7 起 agent preset **只**由组合行声明；`$DSH_HOME/.agent-presets/<id>/agent.cordis.yml` 已无人读取
+（宿主自带技能 `editing-cordis-compositions` 明写 "Nothing reads that directory any more"）。2.3.x 的安装器
+在新宿主上仍会写那个目录：**日志显示安装成功、`~/.dsh/.agent-presets/` 里文件齐全，选择器里却一个都没有。**
+修复：`cordis.patch.yml` 声明四个组合行；安装器的形态判定改为读 **loader 入口树**（见 G-10）。
+
+### G-2 组合行声明有三条硬约束（每条都实测过）
+
+| 约束 | 违反后的现象 | 证据 |
+|---|---|---|
+| `dsh.bundle.patch` 必须是**字符串** | 0.1.5/0.1.6 把该值直接送进 `path.join` → `ERR_INVALID_ARG_TYPE`，**整个 profile 起不来** | 实测：数组形态在 0.1.5-rc.2 上必然崩 |
+| 声明行不能命名**宿主包**（如 `@deepseek-ai/dsh-agent-preset`） | 旧线无此包 → 每次启动 `failed to import` 激活失败 | 实测：0.1.5/0.1.6 上该包不存在 |
+| 声明行不能用 **`!!js` 门**（表达式里调 `ctx.get`） | 入口**永不初始化**、预设静默不注册（`N entries did not activate`） | 实测 0.2.0：`!!js "false"` / `typeof ctx` 正常；`ctx.get('fs'\|'agents'\|'pluginManager'\|'agentPresets')` 全部让入口不加载 |
+
+因此本包改为：声明行的模块是**自己**的 `preset-declaration.js`（两条线上都可解析），它在运行时读 `agentPresets`
+服务——有就注册，没有就**什么都不做且不报警**。
+
+### G-3 声明行里的相对 `name` 解析不到（B3）
+
+`app-boot` 只会把 `group && Array.isArray(config)` 的条目名改写成 `file://` URL；声明行的 `config.plugins`
+不在其中，loader 便拿**profile 目录**解析 `./vibe-math-vN.js` → ENOENT → **整个 preset 拒绝挂载**。
+修复：改用包内子路径 `dsh-vibe-math/vibe-math-vN/vibe-math-vN.js` + 在 `exports` 放行。
+
+### G-4 v5 把状态写进宿主会话日志 → 用户会话不可恢复（致命，数据安全）
+
+`Session.append(type,data,…)` 构造信封时**无法**设置 `ignorable`（只有构造种子接受该字段）；而会话持久化在加载时
+要求"未知事件类型必须 `ignorable === true`"，否则抛 `SessionFormatUnsupportedError` **拒绝整个会话**。该规则在
+0.1.5-rc.2 / 0.1.7-rc.2 / 0.2.0-rc.2 上一致存在 → v5 每追加一条 `vibe5/*`，就把**用户自己的会话**变成"写入时无声、
+下次恢复时打不开"。修复：v5 只用加固 JSON（`State/<研究所>.v5state.json`），彻底不碰会话日志，并去掉
+`sessions` / `sessionProjections` 依赖；连它写进项目的镜像 Markdown 与**给模型看的工具描述**都一并改正。
+
+### G-5 工具过滤里的未注册名让整次派生失败（v4/v5）
+
+`tools.restrict()` 对不在宿主可限制集合里的名字**直接抛错**，而该调用发生在建立子代理时 → v4/v5 一次配置错误
+就让每次派生失败（v2/v3 早就有"按宿主提示剔除名字并重试"的守卫）。修复：v4/v5 采用同样的守卫，
+并把返回值改成"按宿主提示剔除后重试一次"，且**fail-closed**（绝不在过滤全被剔除时"不过滤"启动）。
+
+### G-6 宿主新增"每根代理 8 个存活 continuable 子代理"上限
+
+0.2.0 新增 `ActivationPool`（`maxActiveSubagents` 默认 8，来自 `subagent` 行的 config，未写入 `.d.ts`），
+超出时抛 `SubagentError{code:'ACTIVATION_LIMIT_REACHED'}`；v4 的 `residentCount` 无上限、v5 的临时工上限之和可达 12
+→ 撞限。修复：识别该错误码、从宿主消息里记下上限值、明确提示并把该次派生推迟到下一轮（不再让启动循环崩在半途）。
+
+### G-7 压缩：策略调用 vs 执行调用（v4/v5）
+
+`compactIfNeeded(agent,'pressure',signal)` 是**策略**调用，可能什么都不做且返回 `null`（无日志）；真正的执行调用是
+`compactNow(agent, signal)`。另外 v5 过去从**插件平面**取 compaction，而 preset 自己 `isolate` 了 compaction realm，
+取到的是宿主根实例（配置可能不同）。修复：优先 `compactNow`（特性探测，旧宿主回退到策略调用），v5 改用 agent 自身 ctx 的实例。
+
+### G-8 命令"业务失败"被当成成功
+
+宿主的 `CommandResult` 联合是 `{kind:'success',text?} | {kind:'error',text}`；四套预设的 `/vibe`、`/v4`、`/v5`
+在**所有失败路径**上都返回 `{kind:'success', text:'{"ok":false,…}'}` → UI 永远显示不出"这条命令被拒绝了"。
+修复：按 dispatch 结果自身的 `ok:false` 返回 `kind:'error'`（该联合在 0.1.5 上同样存在，故旧线安全）。
+
+### G-9 文档、镜像与工具描述与实现不符
+
+v5 的 README、`架构图.md`、`实现方案.md`、它写进用户项目的三个镜像文件头（`Institutes.md`、`Shared/TaskBoard.md`、
+`State/README.md`）以及 `vibe_v5_set` 的**工具描述**都写着"权威状态在会话日志投影里"。修复：全部改为真实位置
+（`State/<研究所>.v5state.json`），并重生成 v5 中英架构图。**这一条是提示词/交互面的事实性修复**，不是文风问题。
+
+### G-10 "旧线不读目录"必须用**能力**判定，不能用版本号
+
+`agentPresets` 服务在两条线上**都存在**但语义不同（旧线是目录扫描器、**没有** `register`）——用"服务存在"判形态
+会在 0.1.5/0.1.6 上误判为"组合行"，从而**跳过**唯一有效的目录安装。修复：判定读 **loader 入口树**里是否挂了
+`@deepseek-ai/dsh-agent-preset`（或其 registry）；这在任何插件激活之前就可见，而"读服务"在 bundle 被单独激活
+（`dsh plugin add`）时可能尚未就绪。
+
+---
+
+## 2. 四宿主实测矩阵
+
+| 宿主 | preset 形态 | 实测结果 |
+|---|---|---|
+| 0.1.5-rc.2 | 目录 | 安装器写入四个目录；声明行静默无副作用；`agentPresets.list()` 列出四个预设 ✅ |
+| 0.1.6-alpha.2 | 目录 | 同上 ✅ |
+| 0.1.7-rc.2 | 组合行 | 声明行注册四个预设（order 20–23）；安装器跳过目录（`state` 文件不再被写）✅ |
+| 0.2.0-rc.2 | 组合行 | 同上，且**零激活警告**（此前数组 patch / 宿主包名 / `!!js` 门各会产生一批失败行）✅ |
+
+---
+
+## 3. 已确证**正确**的部分（避免下次重复劳动）
+
+- `tools.register` 的形状（`name`/`description`/`parameters` + **必需的** `output:{schema,render}` + `execute`）与
+  `parameters` 用原生 JSON Schema 的写法（宿主自己的工具也这么写）；handler 返回符合 `output.schema` 的 JSON 字符串 ✓。
+- `commands.register`（`name`/`description`/`input:{hint}`/`handler`）与命令名正则 ✓。
+- `tools.restrict` 的 `{allow,deny}` 形状，以及"未注册名"错误消息仍以 `known global tools: …` 结尾 —— v2/v3 的重试正则
+  逐字符匹配，行为保持 fail-closed ✓。
+- `fs`（resolve/stat/readText/writeText/listDir）、`getPolicy()` 作为 `writeText` 第 5 参数的位置 ✓；`FsDirEntry` 字段无改名 ✓。
+- `subagents.startContinuable` / `sendMessage`（4 参数 + `{signal}`）/ `interrupt`（第二参数为 authority，自 0.1.1 起）/
+  `drainContinuableChildren` 的调用形状自 0.1.2-rc.1 起未变 ✓；`agents.get` 在 `subagent/start` 里可解析、在 `subagent/end`
+  里**必然不可解析**——v4/v5 "在 start 时捕获 Agent 引用"的写法继续正确 ✓。
+- `subprocess`（spawn/done/terminate/collected）与 `sandboxPolicy.resolve` ✓；`timer` 服务签名与 disposer 语义 ✓。
+- `sessionProjections.register/stateOf` 的形状本身 ✓（本包不再使用，原因见 G-4）。
+
+---
+
+## 4. 修复实施记录（2.4.0）
+
+见 `docs/release-notes/RELEASE-NOTES-2.4.0.md`「变更」。工程证据（逐条审计报告与探针输出）保存在仓库之外的
+工作区台账中；本文件只保留结论与判据。
+
+新增守卫：`tests/audit-preset-rows.test.mjs`（生成物与生成器逐字节一致、`dsh.bundle.patch` 必须是字符串、
+声明行不得命名宿主包、不得使用会调用服务的 `!!js` 门、每条组合必须含 `present`/`command-goal`/`isolate`/`workflow-ptc`、
+冻结的 0.1.x 组合保持原样）；`docs/AUDIT-CHECKLIST.md` 新增 §8 把上述四条硬约束写成流程。
+
+---
+
+## 5. 刻意不改（附理由）
+
+| 项 | 决定 | 理由 |
+|---|---|---|
+| v2/v3 使用全局 `setInterval`/`setTimeout` | 保留 | 预设是**文件行**，不经动态包 vm 沙箱（沙箱只包动态包宿主半）；实测可用，且 `ctx.effect` 内已正确清理。仅修掉"插件运行时没有全局定时器"这句**错误注释**。 |
+| 工具卡片呈现（`presentCall`/`presentResult`） | 不加 | 纯外观增强，与本次适配无关；未来要加需同步四套。 |
+| `subagents.listChildren` 元素类型变化（`SubagentCatalogEntry`） | 不处理 | 四套预设均未调用。 |
+| `additionalProperties:false` 的 `parameters` | 保留 | 宿主 `tools.register` 不校验 `parameters`；仅当预设改造成**动态包**时 `defineTool` 才会拒绝（届时再改）。 |
+| `followup` 回退分支 | 保留 | 该分支只在 0.1.1 及更早存在；本包声明的下限是 0.1.2-alpha.4，其中 `0.1.2-alpha.*` 是否仍带 `followup` 未实测，保留分支零成本且更稳。 |