dsh-vibe-math 2.2.1 → 2.2.2

package/RELEASE-NOTES-2.2.2.md

@@ -0,0 +1,88 @@
+# dsh-vibe-math 2.2.2 — v5 架构图 + 完善 README 的 v5 章节 + 修复绘图时暴露的真实缺陷
+
+> 上一版：2.2.1。本版为 v5 补齐**架构图**与 **README 的 v5 章节**，
+> 并修掉一个在为 v5 画架构图时暴露出来的真实缺陷（会议与验证的互斥只做了单向）。
+> v2/v3/v4 未改。
+
+---
+
+## 1. 新增：v5 架构图
+
+| 交付物 | 说明 |
+|---|---|
+| `示例图/框架图-v5.svg` | **总览大图**（1720×1116 矢量图）。分层展示：所办 → 研究所（院士 / 常驻研究员 / 临时工）→ 框架（六项能力 + 调度器优先级）→ 状态与产物（投影单元 / 文件面），左侧一条**控制面通道**专门承载"所办 ↔ 框架"的工具面，因此控制箭头不会穿过所内成员 |
+| `docs/generate_framework_diagram_v5.mjs` | **零依赖 Node 生成器**（`node docs/generate_framework_diagram_v5.mjs` → 写出上面的 SVG）。v2/v3/v4 用 matplotlib 生成 PNG；v5 改用 Node 直接生成 SVG：本仓库的运行时就含 Node，不需要额外装 Python，且 SVG 可 diff、可评审、缩放不糊。生成器自带**布局自检**——会估算每行文字宽度并对溢出容器的行报错（本次就是靠它把两轮排版调整收敛干净的） |
+| `vibe-math-v5/架构图.md` | **全套细节图**（9 张 Mermaid，GitHub 原生渲染）：① 三层总览 ② 成员生命周期状态机 ③ 一轮唤醒的时序 ④ 共识验证状态机（含弃权/阻塞/看门狗）⑤ 会议流程（含双向互斥）⑥ 调度优先级 ⑦ 状态纯折叠 + 双后端 ⑧ 提示词构成 ⑨ 任务板 CAS+DAG；另附职权矩阵、目录结构、不变式速查表 |
+
+> 9 张 Mermaid 全部用 `mermaid-cli` 实际渲染验证通过（不是"看起来像对"）。
+
+## 2. 完善：README 的 v5 章节
+
+- **v5 章节整体重写**：新增架构图（内嵌 SVG + 一份紧凑 Mermaid 总览）、职位与职权表（含"表决权"列）、
+  求真规则、运行机制（通信/会议互斥/任务板/雇佣解雇/活性/看门狗/上下文/停止）、状态与持久化、
+  提示词构成、目录结构、工具面（按角色分组）、与 v4 的关键差异。
+- **修掉"只有三个预设"的遗留说法**：仓库简介、安装说明、手动安装清单、DSH 版本适配、
+  预设选择表、目录结构、断点续跑、已知边界——全部补齐 v5（选择表新增 v5 一列，
+  并给出"什么时候该选 v5"的判据）。
+- **目录结构新增 v5 小节**（含四条 v5 铁律：权威状态在投影里 / 只写自己的库 /
+  可信分层 / 入库三要素）。
+- **已知边界新增 v5 小节**：框架绝不指派是**设计边界**而非未实现；`≥ m` 一致 ≠ 数学上已证明；
+  反向票阻塞而非少数服从多数；回合永不结束者不会被强行释放；会议与验证严格互斥；
+  `resume` 后轮次计数重算；成员章程是入职快照（升级不改写）。
+- **移除 README 里的更新日志式内容**：原"提示词与交互语料（v2.2.0 新增，随包发布）"与
+  "📋 全面检查必查清单（随包发布）"两段带版本叙事的内容已删除。提示词正确性作为**特性**写进
+  v5 章节（不带版本号），`AUDIT-CHECKLIST.md` 与提示词语料改为「规格文档」里的一行索引。
+
+## 3. 修复：会议与验证的"互斥"只做了单向
+
+**怎么发现的**：画架构图时被迫把"会议与验证互斥"写成一句**明确的不变式**，
+再拿这句话去逐条对照代码 —— 发现 `startMeeting` 有守卫、`armNextVerify` 没有。
+
+**缺陷**：`maybeQueueVerify` **直接**调用 `armNextVerify`，绕过了 `schedulePass` 里
+"先看会议"的检查。因此成员在会议进行中回执 `propose_verify` 时，**第二个共识过程会真的并发启动**：
+
+```
+会议进行中 ──成员回执 propose_verify──▶ armNextVerify（无会议守卫）
+                                        └─▶ beginVerify + askVoters   ← 并发启动！
+```
+
+后果：两个共识过程争夺同一批成员，会议的看门狗时钟被饿死，`schedulePass` 也只在会议结束后
+才会回到验证 —— 与文档承诺的"验证进行中会议请求会暂存，验证做完再补开"**不对称**。
+
+**修复**：`armNextVerify` 在 `meeting` 非空时直接返回，提议**留在队列里**，
+会议收口后由下一次 `schedulePass` 启动（`if (meeting) {...return}` 在它之前，
+所以会议一结束就会走到它）。
+
+**测试**：新增用例 10b"会议进行中提出的验证必须排队"——先开一个会并让它保持在进行中，
+再提议验证，断言 `verify === null` 且 `verifyQueue` 含该对象；会议结束后断言它**确实启动了**
+（排队不能变成丢弃）。修复前该用例 **RED**，修复后 GREEN。`prompt-v5-integrity` 526 → **534 断言**。
+
+**灵敏度探针**：新增 `verify-preempts-a-live-meeting`（删掉那条守卫，套件必须变红）。
+**30 探针 / 0 盲点**。
+
+**文档同步**：`实现方案.md` §14.1 补上"互斥必须双向成立"的说明，并指出
+"进行中的验证/会议"的先后顺序**不可观测**（因为二者互斥），不应写成假装精确的优先级列表；
+`AUDIT-CHECKLIST.md` 新增 §3「把不变式写成文档/图，再拿它去对代码」——
+把这次发现缺陷的手法固化成流程（尤其注意**成对出现的关系**：互斥、双向、唯一、幂等，
+"只做一半"是最常见的形态）。
+
+## 4. 验收
+
+| 套件 | 结果 |
+|---|---|
+| `prompt-v5-integrity.test.mjs` | **534 断言**（+8：会议与验证互斥） |
+| `selfdrive-v5.mjs` | 75 断言 |
+| `e2e-v5-round2.test.mjs` | 53 断言 |
+| `audit-v5-sensitivity.mjs` | **30 探针 / 0 盲点** |
+| `audit-v5-integrity.mjs` | **clean**（31 条理念门禁 + 3 项交付物门禁 + 语料校验） |
+| `vibe-math-v5/架构图.md` 的 9 张 Mermaid | 全部经 `mermaid-cli` 实际渲染通过 |
+| 其余回归 | 26 个套件全绿 |
+
+## 5. 升级
+
+```
+npm i dsh-vibe-math@latest
+```
+
+无迁移。已在跑的研究所不受影响（这次改的是"何时允许启动一次验证"，
+不改变已有状态的结构，也不改写成员章程）。

package/audit-v5-sensitivity.mjs

@@ -263,6 +263,13 @@ const probes = [
     from: "        if ((now() - (lastActiveAt.get(m.id) || 0)) < idleMs) continue",
     to: "        if (false) continue",
   },
+  {
+    name: 'verify-preempts-a-live-meeting',
+    ref: 'prompt-v5-integrity.test.mjs',
+    guarantee: '㉝ a verification proposed during a meeting must QUEUE, never start concurrently (the two are mutually exclusive)',
+    from: "      if (meeting) return\n      // Only one begin may be in flight.",
+    to: "      // Only one begin may be in flight.",
+  },
 ]
 
 let probesPassed = 0

package/docs/generate_framework_diagram_v5.mjs

@@ -0,0 +1,284 @@
+// ============================================================
+// Vibe Math V5 架构图生成器（零依赖，纯 Node）
+//
+//   node docs/generate_framework_diagram_v5.mjs
+//   → 写出 示例图/框架图-v5.svg
+//
+// v2/v3/v4 用 matplotlib 脚本生成 PNG；v5 用 Node 直接生成 **SVG**：
+//   · 本仓库的运行时就包含 Node，不需要额外装 Python / matplotlib；
+//   · SVG 是纯文本，diff 友好、可评审、任意缩放不糊。
+// 需要 PNG 时用浏览器打开 SVG 另存，或用无头浏览器截图：
+//   chrome --headless=new --window-size=1720,1100 --screenshot=框架图-v5.png 框架图-v5.svg
+//
+// 版式约定（改布局时请遵守，否则会重叠）：
+//   · 每个 band 的标题在 y+27、副标题在 y+47，**内容从 y+56 开始**；
+//   · 左侧 x=40..214 是一条「控制面通道」，只有所办↔框架的连线走这里，
+//     研究所/框架两个 band 从 x=226 开始 —— 这样控制面的箭头不会穿过所内成员；
+//   · 生成时会估算文字宽度，超出容器的行会打印 WARN，便于立刻发现溢出。
+// ============================================================
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+const OUT = join(ROOT, '示例图', '框架图-v5.svg')
+
+const W = 1720, H = 1116
+const FONT = "'Microsoft YaHei','PingFang SC','Hiragino Sans GB','Noto Sans CJK SC','Source Han Sans SC',sans-serif"
+const MONO = "'Cascadia Mono','Consolas','SFMono-Regular',monospace"
+
+const C = {
+  ink: '#10202e', ink2: '#2c4557', mute: '#5d7788',
+  frame: '#0b6fb8', frameBg: '#eaf3fd',
+  house: '#b26a00', houseBg: '#fdf5e2',
+  data: '#1f7a52', dataBg: '#eef7f1',
+  gate: '#b3202c', gateBg: '#fdeef0',
+  human: '#5b4bb8', humanBg: '#f1eefc',
+  line: '#7d93a3',
+}
+
+// band geometry
+const FULL_L = 40, FULL_R = W - 40                 // 40 .. 1680
+const MAIN_L = 226, MAIN_R = FULL_R                // 研究所 / 框架（让出控制面通道）
+const IN_L = MAIN_L + 22, IN_R = MAIN_R - 22       // 226+22=248 .. 1638
+
+const warnings = []
+const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+// 粗略字宽估算：CJK/全角 1.0em，ASCII 0.56em。用来抓文字溢出（比截图更快）。
+const textWidth = (s, fs) => [...String(s)].reduce((n, ch) => n + (/[\u2e80-\u9fff\uff00-\uffef]/.test(ch) ? 1 : 0.56), 0) * fs
+const fits = (s, fs, limit, where) => {
+  const w = textWidth(s, fs)
+  if (w > limit) warnings.push(`${where}: 文字宽 ${w.toFixed(0)} > 可用 ${limit.toFixed(0)} — ${String(s).slice(0, 42)}…`)
+  return w
+}
+
+const out = []
+const push = (s) => out.push(s)
+
+// ---------- primitives ----------
+function band(x, y, w, h, title, sub, { fill, stroke, titleFill = C.ink }) {
+  push(`<rect x="${x}" y="${y}" width="${w}" height="${h}" rx="14" fill="${fill}" stroke="${stroke}" stroke-width="2"/>`)
+  fits(title, 15, w - 36, 'band title')
+  push(`<text x="${x + 18}" y="${y + 27}" font-size="15" font-weight="700" fill="${titleFill}">${esc(title)}</text>`)
+  if (sub) {
+    fits(sub, 12, w - 36, 'band sub')
+    push(`<text x="${x + 18}" y="${y + 47}" font-size="12" fill="${C.mute}">${esc(sub)}</text>`)
+  }
+}
+
+function card(x, y, w, h, lines, { fill = '#ffffff', stroke = C.frame, fs = 13, sfs = 11, titleFill = C.ink } = {}) {
+  push(`<rect x="${x}" y="${y}" width="${w}" height="${h}" rx="10" fill="${fill}" stroke="${stroke}" stroke-width="1.6"/>`)
+  const cx = x + w / 2
+  const lead = fs + 4
+  const total = (lines.length - 1) * lead
+  if (total + fs > h) warnings.push(`card@${x},${y}: ${lines.length} 行需要高 ${(total + fs).toFixed(0)} > 容器 ${h}`)
+  let ty = y + h / 2 - total / 2 + fs * 0.36
+  lines.forEach((ln, i) => {
+    const size = i === 0 ? fs : sfs
+    fits(ln, size, w - 16, `card line@${x},${y}`)
+    push(`<text x="${cx}" y="${ty.toFixed(1)}" font-size="${size}" font-weight="${i === 0 ? 700 : 400}" `
+      + `fill="${i === 0 ? titleFill : C.ink2}" text-anchor="middle">${esc(ln)}</text>`)
+    ty += lead
+  })
+}
+
+function plain(x, y, text, { size = 12, fill = C.ink2, anchor = 'start', weight = 400, mono = false, limit = null, where = 'plain', halo = false } = {}) {
+  if (limit) fits(text, size, limit, where)
+  // halo: 白色描边垫在文字下，用于压在连线上的标签，避免线从字中间穿过
+  push(`<text x="${x}" y="${y}" font-size="${size}" font-weight="${weight}" fill="${fill}" text-anchor="${anchor}"`
+    + (halo ? ' paint-order="stroke" stroke="#ffffff" stroke-width="4" stroke-linejoin="round"' : '')
+    + (mono ? ` font-family="${MONO}"` : '') + `>${esc(text)}</text>`)
+}
+
+function arrow(x1, y1, x2, y2, { color = C.line, dashed = false, both = true, width = 1.6, marker = 'both' } = {}) {
+  push(`<line x1="${x1}" y1="${y1}" x2="${x2}" y2="${y2}" stroke="${color}" stroke-width="${width}" `
+    + (dashed ? 'stroke-dasharray="7 5" ' : '')
+    + (both ? `marker-start="url(#${marker})" ` : '') + `marker-end="url(#${marker})"/>`)
+}
+
+function polyline(points, { color = C.human, width = 2, dashed = false, marker = 'bothHuman' } = {}) {
+  const d = points.map((p, i) => (i ? 'L' : 'M') + ' ' + p[0] + ' ' + p[1]).join(' ')
+  push(`<path d="${d}" fill="none" stroke="${color}" stroke-width="${width}" `
+    + (dashed ? 'stroke-dasharray="7 5" ' : '') + `marker-start="url(#${marker})" marker-end="url(#${marker})"/>`)
+}
+
+// ---------- document ----------
+push('<?xml version="1.0" encoding="UTF-8"?>')
+push(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${H}" width="${W}" height="${H}" role="img" aria-label="Vibe Math V5 研究所架构图">`)
+push(`<defs>
+  <marker id="both" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="${C.line}"/></marker>
+  <marker id="bothHuman" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="${C.human}"/></marker>
+  <marker id="bothFrame" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="${C.frame}"/></marker>
+  <marker id="bothData" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="${C.data}"/></marker>
+  <marker id="bothHouse" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="${C.house}"/></marker>
+</defs>`)
+push(`<rect width="${W}" height="${H}" fill="#ffffff"/>`)
+push(`<g font-family="${FONT}">`)
+
+// ---- 标题 ----
+plain(W / 2, 40, 'Vibe Math V5 —— 研究所体系', { size: 27, fill: C.ink, anchor: 'middle', weight: 700 })
+plain(W / 2, 67, '框架只是媒介：中继消息 · 沉淀产物 · 计数表决 · 管理上下文。它绝不指派任务 —— 组织与分派是所内院士的职责',
+  { size: 13, fill: C.mute, anchor: 'middle', limit: W - 80, where: 'subtitle' })
+
+// ---- 求真门槛 ----
+band(FULL_L, 84, FULL_R - FULL_L, 94, '求真门槛 —— 唯一让对象进入 Verified/ 的规则',
+  'm = min(quorumCap, 在册有表决权人数)　·　票是 [0,1] 概率：恰好 1 = 断言为真，恰好 0 = 断言为假，严格介于两者 = 弃权/存疑（不计入 m，计入全组平均）',
+  { fill: C.gateBg, stroke: C.gate, titleFill: C.gate })
+card(62, 140, 506, 28, ['布尔票 ≥ m 且全部为 1 或全部为 0 → 定论，写入 Verified/'], { stroke: C.gate, fs: 12 })
+card(588, 140, 506, 28, ['同时出现 1 与 0 → 阻塞：少数派无法靠别人弃权把结论推过去'], { stroke: C.gate, fs: 12 })
+card(1114, 140, 524, 28, ['未达门槛 → 留在原库 + 全组平均概率 + 完整辩论录（不强行裁决）'], { stroke: C.gate, fs: 12 })
+
+// ---- 所办 ----
+band(FULL_L, 190, FULL_R - FULL_L, 100, '所办（会话根代理 / 人）—— 研究所的对外接口',
+  '不参与研究 · 不投票 · 只汇报与转达人的指令；代持平台要求的一次性创建权',
+  { fill: C.humanBg, stroke: C.human, titleFill: C.human })
+card(62, 246, 372, 38, ['自然语言接口 + 汇报者', '「求解 XX」「进度如何」「暂停」'], { stroke: C.human, fs: 12, sfs: 10.5 })
+card(452, 246, 372, 38, ['vibe_v5_configure → start', 'message / meeting / hire / fire'], { stroke: C.human, fs: 12, sfs: 10.5 })
+card(842, 246, 330, 38, ['pause / resume / stop', 'set 调参（立即生效）'], { stroke: C.human, fs: 12, sfs: 10.5 })
+card(1190, 246, 448, 38, ['/v5 斜杠命令（与工具等价）', 'configure|start|resume|pause|status|report|members|message|meeting|hire|fire|set'],
+  { stroke: C.human, fs: 12, sfs: 9 })
+
+// ---- 研究所 ----
+band(MAIN_L, 302, MAIN_R - MAIN_L, 240, '研究所（所内自治）—— 编制、组织与分派都在成员之间完成，框架永不指派',
+  '院士 acad：领头人 / 组织与协调中心　·　常驻研究员 r-n：有表决权　·　临时工 t-n：无表决权（由雇主雇入与解雇）',
+  { fill: C.houseBg, stroke: C.house, titleFill: '#8a5200' })
+card(IN_L, 362, 300, 142, [
+  '院士 acad',
+  '领头人 · 组织与协调中心',
+  'L1 建立全所视图（overview）',
+  'L2 拆解并分派任务（assign）',
+  'L3 设定优先级（prioritize）',
+  'L4 召集并主持会议（convene）',
+  'L5 督导进度（nudge）',
+  'L6 调配临时工 · L7 对外代表',
+], { stroke: C.house, fs: 13.5, sfs: 10.5 })
+plain(IN_L + 150, 520, '四条边界：一票与他人等重 / 分派的是工作不是结论 /', { size: 10, fill: C.gate, anchor: 'middle', limit: 300, where: 'acad note' })
+plain(IN_L + 150, 536, '成员可据理反对 / 不能自我扩张编制', { size: 10, fill: C.gate, anchor: 'middle', limit: 300, where: 'acad note' })
+
+const RX = IN_L + 328, RW = 1390 - 328 - 44
+const rcw = (RW - 2 * 20) / 3
+plain(RX, 372, '常驻研究员（有表决权 · 可自主雇佣/解雇自己的临时工）', { size: 11.5, fill: '#8a5200', weight: 700, limit: RW, where: 'researcher label' })
+for (let i = 0; i < 3; i++) {
+  card(RX + i * (rcw + 20), 380, rcw, 52, [`常驻研究员 r-${i + 1}`, 'continuable 持久会话 · 自主方向 · 主动汇报'],
+    { stroke: C.house, fs: 13, sfs: 10.5 })
+}
+plain(RX, 452, '临时工（无表决权 · 为特定任务临时雇入 · 雇主或院士可解雇）', { size: 11.5, fill: '#8a5200', weight: 700, limit: RW, where: 'temp label' })
+for (let i = 0; i < 3; i++) {
+  card(RX + i * (rcw + 20), 460, rcw, 52, [`临时工 t-${i + 1}`, `由 r-${i + 1} 雇入 · 可读/可想/可发言/可写自己的库`],
+    { stroke: '#c99a4a', fs: 13, sfs: 10.5 })
+}
+plain(RX, 536, '所内组织动作（分派 · 优先级 · 督办 · 会议 · 用人）由院士发起，不是框架行为 —— 框架只负责送达',
+  { size: 10.5, fill: C.mute, limit: RW, where: 'house note' })
+
+// ---- 框架 ----
+band(MAIN_L, 566, MAIN_R - MAIN_L, 286, '框架 vibe-v5 —— 只是媒介（middleware）：中继 · 沉淀 · 计数 · 调度',
+  '每轮发「状态块 + 本轮问句」（规章在 persona 里，不进对话）；成员回一个 JSON：say / progress / record / verdict / task_* / hire / fire / reject_assign / input / vote_solved',
+  { fill: C.frameBg, stroke: C.frame, titleFill: '#084d80' })
+const chips = [
+  ['消息中继（持久邮箱）', '群聊 / 私信 / 致全体表决者', '所办通知 / 分派 / 督办 / 框架提示', '逐收件人落盘 · 先落盘再投递 · 群聊合批'],
+  ['会议 / 辩论', '议程 · 实时名册对账 · 随机发言序', '与验证互斥：任一方进行中，另一方排队', '看门狗：卡死即放弃并回到自组织'],
+  ['任务板（CAS + DAG）', '开 / 认领 / 释放 / 完成 / 重开 / 分派', '版本号比较交换 · 依赖环检测', '写范围重叠告警 · 解雇自动收回'],
+  ['m 票共识验证', '发起 → 独立初评 → 公开辩论重投', '布尔一致 + ≥ m 才定论', 'Verified/ 卡 + 辩论录 + 全组平均概率'],
+  ['上下文与活性', '阈值压缩（人设不丢）· 免轮询活动等待', '优先级调度 · 心跳永远重武装', '并发闸 maxParallel · 停滞自动开会'],
+  ['编制与雇佣', '院士/研究员可雇自己的临时工', '雇主或院士可真实解雇（释放子会话）', '代号永不复用 · 按人/全所双配额'],
+]
+const ccw = (IN_R - IN_L - 2 * 22) / 3
+chips.forEach((c, i) => {
+  card(IN_L + (i % 3) * (ccw + 22), i < 3 ? 620 : 708, ccw, 78, c, { stroke: C.frame, fs: 12.5, sfs: 10.5 })
+})
+card(IN_L, 796, IN_R - IN_L, 38, [
+  '调度器优先级：进行中的会议或验证（二者互斥，永不同时）→ 队列中的验证 → 暂存会议 → 已认领/被分派的在办任务（按 activityTimeoutMs 节流）→ 加急邮件 → 群聊摘要 → 停滞自动开会 → 兜底心跳',
+], { stroke: C.frame, fs: 11.5 })
+
+// ---- 数据面 ----
+band(FULL_L, 876, 790, 196, '状态权威源：会话日志的 host-only 投影单元（键 vibeMathV5）',
+  '副作用只是往会话日志追加事件 —— 不进模型上下文（零 token 成本），checkpoint / restore 交给 DSH',
+  { fill: C.dataBg, stroke: C.data, titleFill: '#125a3c' })
+card(62, 932, 360, 124, [
+  'applyV5Event（纯折叠，只此一份）',
+  '11 类事件：institute / member / task /',
+  'message / delivered / meeting / debate /',
+  'verdict / queue / counters / progress',
+  '未知或损坏事件 → 跳过并记入 diagnostics：',
+  '可用性优先，绝不因一条坏事件卡死全场',
+], { stroke: C.data, fs: 12, sfs: 10.5 })
+card(434, 932, 374, 124, [
+  'checkpoint / restore / resume',
+  '投影随会话日志一起 checkpoint；restore',
+  '时从快照 + 日志尾部重新折叠 → 跨进程与',
+  '同进程恢复走同一条代码路径',
+  '回退：宿主无 sessionProjections 时改用',
+  '加固 JSON：State/<institute>.v5state.json',
+], { stroke: C.data, fs: 12, sfs: 10.5 })
+
+band(852, 876, FULL_R - 852, 196, '文件面：人可读产物（投影之外的一切都只是镜像）',
+  '共识的权威在投影；文件是工作区与可读产物，手工改坏不会破坏研究所',
+  { fill: C.dataBg, stroke: C.data, titleFill: '#125a3c' })
+card(874, 932, FULL_R - 874 - 22, 124, [
+  'Members/<id>/Progress|Propos|Methods|Subproblems/',
+  '只有本人可写，人人可读（跨读被鼓励）',
+  'Shared/Chat/*.md · Shared/Meetings/<mt-id>.md · Shared/Debates/<obj>.md',
+  'Shared/TaskBoard.md · Institutes.md（编制镜像）· State/README.md（说明此处非权威）',
+  'Problems/<id>.md（原问题）· Problems/conclusion.md（结题）· Verified/<类型>/<id>.md（定论，只读）',
+], { stroke: C.data, fs: 11.5, sfs: 10.5 })
+
+// ---- 连线：控制面（左侧通道，不穿过所内成员） ----
+const CHX = 127
+polyline([[CHX, 290], [CHX, 700], [MAIN_L, 700]], { color: C.human, width: 2 })
+plain(CHX, 336, '工具面', { fill: C.human, anchor: 'middle', size: 12, weight: 700, halo: true })
+plain(CHX, 356, 'vibe_v5_*', { fill: C.human, anchor: 'middle', size: 11, halo: true })
+plain(CHX, 374, '/v5 命令', { fill: C.human, anchor: 'middle', size: 11, halo: true })
+plain(CHX, 398, '↓', { fill: C.human, anchor: 'middle', size: 13, weight: 700, halo: true })
+plain(CHX, 470, '汇报', { fill: C.human, anchor: 'middle', size: 12, weight: 700, halo: true })
+plain(CHX, 490, 'status', { fill: C.human, anchor: 'middle', size: 11, halo: true })
+plain(CHX, 508, 'report', { fill: C.human, anchor: 'middle', size: 11, halo: true })
+plain(CHX, 532, '↑', { fill: C.human, anchor: 'middle', size: 13, weight: 700, halo: true })
+plain(CHX, 600, '所办不投票', { fill: C.mute, anchor: 'middle', size: 10, limit: 170, where: 'ch note' })
+plain(CHX, 616, '不能让结论变真', { fill: C.mute, anchor: 'middle', size: 10, limit: 170, where: 'ch note' })
+plain(CHX, 644, '也不替成员', { fill: C.mute, anchor: 'middle', size: 10, limit: 170, where: 'ch note' })
+plain(CHX, 660, '思考或署名', { fill: C.mute, anchor: 'middle', size: 10, limit: 170, where: 'ch note' })
+
+// ---- 连线：研究所 ↔ 框架（提示词 / 回执） ----
+arrow(560, 542, 560, 566, { color: C.frame, marker: 'bothFrame', width: 2 })
+arrow(1400, 542, 1400, 566, { color: C.frame, marker: 'bothFrame', width: 2 })
+plain(980, 559, '↑ 每轮提示词（状态块 + 本轮问句）　　↓ 单个 JSON 回执',
+  { fill: C.frame, anchor: 'middle', size: 10.5, limit: 780, where: 'prompt label', halo: true })
+
+// ---- 连线：所内组织（虚线 = 不由框架执行） ----
+arrow(556, 400, 578, 400, { color: C.house, dashed: true, width: 1.8, marker: 'bothHouse' })
+arrow(556, 430, 578, 430, { color: C.house, dashed: true, width: 1.8, marker: 'bothHouse' })
+
+// ---- 连线：框架 ↔ 数据面 ----
+arrow(400, 852, 400, 876, { color: C.data, marker: 'bothData', width: 2 })
+plain(392, 868, 'append / fold / stateOf', { fill: C.data, anchor: 'end', size: 10.5, halo: true })
+arrow(1280, 852, 1280, 876, { color: C.data, marker: 'bothData', width: 2 })
+plain(1288, 868, '读写产物', { fill: C.data, anchor: 'start', size: 10.5, halo: true })
+
+// ---- 图例 ----
+plain(52, 1098, '图例', { size: 12, fill: C.ink, weight: 700 })
+const legend = [
+  [C.human, '所办 / 人（外部接口，不研究不投票）'],
+  [C.house, '所内成员与所内组织（虚线 = 不由框架执行）'],
+  [C.frame, '框架（中继 / 沉淀 / 计数 / 调度）'],
+  [C.data, '状态与产物'],
+  [C.gate, '求真门槛（唯一定论规则）'],
+]
+legend.forEach(([col, txt], i) => {
+  const x = 108 + i * 330
+  push(`<rect x="${x}" y="1087" width="14" height="14" rx="3" fill="#ffffff" stroke="${col}" stroke-width="2"/>`)
+  plain(x + 21, 1099, txt, { size: 11, fill: C.ink2, limit: 305, where: 'legend' })
+})
+
+push('</g>')
+push('</svg>')
+
+mkdirSync(dirname(OUT), { recursive: true })
+const svg = out.join('\n')
+writeFileSync(OUT, svg, 'utf8')
+console.log('saved ' + OUT + ' (' + svg.length + ' bytes)')
+if (warnings.length) {
+  console.error('\n布局告警（文字可能溢出容器）：')
+  for (const w of warnings) console.error('  WARN ' + w)
+  process.exit(1)
+}
+console.log('layout: no overflow warnings')

package/docs//346/236/266/346/236/204/345/233/276.md

@@ -0,0 +1,75 @@
+# Vibe Math 架构图
+
+> 框架 = **一个主代理（助手）+ 一个代码调度器 + 五类子代理** + 一套按项目隔离的持久化数据布局。
+> 下方的 Mermaid 代码块在 GitHub 上会**原生渲染**成流程图；本文件即图源，改完重新提交即可自动更新。
+
+```mermaid
+flowchart TB
+    subgraph L1["👤 交互层"]
+        U["😀 用户（自然语言）"]
+        M["🤖 主代理（助手 + 汇报者）<br/>翻译需求 · 汇报进度 · 问答配置<br/>不求解 · 不调度"]
+    end
+
+    subgraph L2["⚙️ 调度层（插件代码）"]
+        SCHED["调度器 Scheduler<br/>唯一文件写者<br/>读 qs.csv · 派发子代理 · 推进状态机"]
+    end
+
+    subgraph L3["🧠 子代理层（continuable 持久会话）"]
+        BRAIN["🧭 Brainstorm<br/>拆解多个求解方向"]
+        SOLV["✍️ Solver × N<br/>逐方向多轮迭代"]
+        DERI["🔀 Derive<br/>死路时派生新方向"]
+        VERI["🔬 Verifier × ≥3<br/>独立审查 → 辩论 → 裁决"]
+        DECI["⚖️ Decider<br/>判定是否解决"]
+    end
+
+    subgraph L4["💾 数据层 · VibeMath/Projects/&lt;项目&gt;/"]
+        QS["📋 qs.csv"]
+        PEND["📥 Pending_Verification/"]
+        UNDR["📂 Under_Verification/"]
+        TVAL["✅ Temp_Validated/"]
+        KNOW["📚 Verified/ 可信知识库"]
+        STATE["🗄️ Progress_Logs/ · VibeMath_State/"]
+    end
+
+    U -->|"求解 XX / 查进度 / 干预"| M
+    M -->|"vibe_math_* 工具"| SCHED
+
+    SCHED -->|"① 派发"| BRAIN
+    BRAIN -->|"多个大相径庭的方向"| SCHED
+    SCHED -->|"② 每方向一个"| SOLV
+    SOLV -->|"结构化结果 JSON"| SCHED
+    SOLV -.->|"迭代至卡死"| DERI
+    DERI -->|"派生 1~3 个新方向"| SCHED
+    SCHED -->|"③ 写盘"| PEND
+    SCHED -->|"④ 拆解为最小验证单元"| UNDR
+    SCHED -->|"⑤ 派发 ≥3 个"| VERI
+    VERI -->|"裁决 JSON"| SCHED
+    SCHED -->|"⑥ 通过"| TVAL
+    SCHED -->|"⑦ 晋升"| KNOW
+    SCHED -->|"⑧ 派发"| DECI
+    DECI -->|"⑨ 已解决 → 回写"| QS
+    SCHED <-->|"读取问题"| QS
+    SCHED <-->|"状态落盘 / 断点恢复"| STATE
+```
+
+## 主流程（编号对应上图）
+
+- **①** 主代理把用户需求翻译成 `vibe_math_add_problem` + `vibe_math_start`，调度器从 `qs.csv` 选问题并派发 **Brainstorm** 子代理；
+- **②** Brainstorm 返回多个「大相径庭」的求解方向，调度器为**每个方向**起一个专属 **Solver**（同一会话内多轮迭代，产出引理/子路线/存活概率/完整解法，以结构化 JSON 返回）；
+- **③** 调度器作为**唯一文件写者**，把 Solver 输出落盘到 `Pending_Verification/`；
+- **④** 调度器把待验证输出**拆解为最小验证单元**（`Under_Verification/`）；
+- **⑤** 每个单元派 **≥3 个 Verifier** 独立审查 → 辩论 → 裁决（一票否决 / 加权投票）；
+- **⑥** 裁决通过 → `Temp_Validated/` → **⑦ 晋升**进 `Verified/` 可信知识库；
+- **⑧** 派 **Decider** 判断新结论是否解决某未解决问题：**⑨** 是则回写 `qs.csv` 为 `solved` 并命名解法文件，否则留作后续方向复用的已知结论；
+- **卡死兜底**：所有方向都走进死路时，派 **Derive** 基于历史痛点派生 1~3 个全新方向，回到 ②。
+
+## 关键特性在图中对应
+
+| 特性 | 图中的对应 |
+|---|---|
+| **断点续跑** | `调度器 ⇄ VibeMath_State/` 双向边：任务栈、代理注册表、决策队列、依赖图、验证器历史准确率全部落盘，重启后 `vibe_math_resume` 恢复 |
+| **中途人工干预** | `manual` 模式下，调度器在 ① 派发 / ⑥ 裁决 / ⑦ 晋升 三个节点挂起决策，等主代理用 `vibe_math_list_decisions` / `vibe_math_decide` 处理，随时可切回 `auto` |
+| **唯一写者铁律** | 所有指向数据层的实线都从「调度器」出发；子代理只返回 JSON，从不写文件，跨目录移动走临时原子交换 |
+| **按项目隔离** | 整个数据层位于 `VibeMath/Projects/<项目>/` 下，互不干扰、可随时切换 |
+| **子代理权限调控** | 调度器派发时注入 toolFilter（允许/禁止）与每轮外部工具调用上限 |
+| **可配置** | 默认参数来自 `vibe_math_setting.json`（JSONC 含注释），`/vibe setup` 交互式配置 |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-vibe-math",
   "description": "Multi-agent mathematical problem-solving & verification frameworks for DeepSeek Harness — FOUR agent presets in one install: vibe-math-v2 (probability-driven: qs.json + Propos knowledge base + explorer→solver→review/debate verdict), vibe-math-v3 (THIRD-generation, recommended: paper-style Markdown knowledge base with Problems/Progress/Propos/Methods/Verified + planner-agent scheduling that decides the next N actions + universal theory/method invention library + agents write their own Markdown directly via a per-file write lock), and vibe-math-v4 (FOURTH-generation: persistent self-organizing resident subagents that message & meet to decide all tasks, verify only by unanimous consensus, /compact at a context threshold, and stop only when all agree the problem is solved), and vibe-math-v5 (FIFTH-generation research institute: an academician as the organizational centre who decomposes and ASSIGNS work and chairs meetings; permanent researchers who hold the vote and may hire/fire their own temp workers; temp workers with no vote; a group chat and meetings; a durable per-recipient mailbox; a compare-and-set task DAG; and a boolean m-vote consensus rule where an object enters Verified/ only when at least m voting members agree AND every one of them returns exactly 1 or exactly 0). Installing this bundle auto-installs all four presets (v1 was removed at v2.0.0).",
-  "version": "2.2.1",
+  "version": "2.2.2",
   "type": "module",
   "engines": {
     "node": "^22.19.0 || >=24.0.0"
@@ -13,37 +13,42 @@
     "./cordis.patch.yml": "./cordis.patch.yml"
   },
   "files": [
-    "installer.js",
+    "AUDIT-CHECKLIST.md",
+    "audit-v5-integrity.mjs",
+    "audit-v5-sensitivity.mjs",
     "cordis.patch.yml",
+    "e2e-v5-round2.test.mjs",
+    "installer.js",
+    "prompt-v5-integrity.test.mjs",
     "RELEASE-NOTES-2.0.22.md",
-    "AUDIT-CHECKLIST.md",
     "RELEASE-NOTES-2.1.0.md",
     "RELEASE-NOTES-2.2.0.md",
     "RELEASE-NOTES-2.2.1.md",
+    "RELEASE-NOTES-2.2.2.md",
     "selfdrive-v5.mjs",
-    "e2e-v5-round2.test.mjs",
-    "prompt-v5-integrity.test.mjs",
-    "audit-v5-sensitivity.mjs",
-    "audit-v5-integrity.mjs",
-    "prompt-corpus-v5/prompt-corpus-v5.md",
+    "示例图/框架图-v5.svg",
+    "docs/架构图.md",
+    "docs/generate_framework_diagram_v5.mjs",
     "prompt-corpus-v5/prompt-corpus-v5.json",
+    "prompt-corpus-v5/prompt-corpus-v5.md",
+    "vibe-math-v2/实现方案.md",
     "vibe-math-v2/agent.cordis.yml",
     "vibe-math-v2/preset.yml",
-    "vibe-math-v2/vibe-math-v2.js",
-    "vibe-math-v2/实现方案.md",
     "vibe-math-v2/v2的额外要求.txt",
+    "vibe-math-v2/vibe-math-v2.js",
+    "vibe-math-v3/实现方案.md",
     "vibe-math-v3/agent.cordis.yml",
     "vibe-math-v3/preset.yml",
     "vibe-math-v3/vibe-math-v3.js",
-    "vibe-math-v3/实现方案.md",
+    "vibe-math-v4/实现方案.md",
     "vibe-math-v4/agent.cordis.yml",
     "vibe-math-v4/preset.yml",
     "vibe-math-v4/vibe-math-v4.js",
-    "vibe-math-v4/实现方案.md",
+    "vibe-math-v5/架构图.md",
+    "vibe-math-v5/实现方案.md",
     "vibe-math-v5/agent.cordis.yml",
     "vibe-math-v5/preset.yml",
-    "vibe-math-v5/vibe-math-v5.js",
-    "vibe-math-v5/实现方案.md"
+    "vibe-math-v5/vibe-math-v5.js"
   ],
   "license": "MIT",
   "keywords": [
@@ -73,7 +78,7 @@
     },
     "minVersion": "0.1.2-rc.1",
     "testedVersion": "0.1.5-rc.2",
-    "compatNote": "依赖宿主提供的 subagents/agents/tools/commands/fs 服务与 @deepseek-ai/dsh-* 插件行；可选 subprocess/sandboxPolicy/compaction。persona 行同时携带 prefix 与 text 两个键，以兼容 0.1.3-alpha.2 的 schema 更名（prefix 必填）与 0.1.2 及更早的 text 键。已在 dsh-v0.1.5-rc.2（@deepseek-ai/dsh-persona 0.1.5-rc.2）上逐行校验全部预设行并通过（v2/v3/v4；v1 已于 v2.0.0 移除）。注意：DSH 0.1.2 起 subagents.startContinuable 的 agentOptions/toolFilter 需要宿主 provider 声明对应 capability（spawn/fork 进程内 provider 均支持），安装器启动时会做能力自检并在旧版宿主上告警。2026 兼容性修复：v2/v3 工具权限名表原先硬编码 web/fetch/bash（未注册名会使 tools.restrict() 抛错、子代理无法建立），现按真实注册名并加带守卫的重试；v4 真实 /compact 原先在 subagent/end 里查 agents.get()（该事件触发时子代理已移出注册表，属死代码），现改为在 subagent/start 捕获 Agent 引用；三套预设的可选服务改为惰性读取，不再在 apply() 快照；v4 的 tools/commands 注册补入 ctx.effect；安装器自检新增 subprocess/sandboxPolicy/compaction。v2.1.0 新增 v5 研究所体系：状态存于宿主 host-only 会话投影单元（键 vibeMathV5），因此自检新增 sessionProjections/sessions（均为可选；缺失时 v5 回退到加固 JSON 状态文件）。v5 不依赖任何 npm 实验包，纯 preset 内单文件实现。v2.2.1 把「全面检查必查清单」(AUDIT-CHECKLIST.md) 作为随包强制流程发布，提示词/交互正确性列为第一优先审计维度。v2.2.0 修复实测发现的提示词身份错乱：状态块改为显式接收它所描述的成员，创建成员时先落盘进编制再构造入职提示词，章程快照冻结在入职时，重建会话不再自称“刚入职”，所办调用不再被误判成某位研究员，框架反馈改为独立发送者投递，一次提示词不再重复投递同一条消息，并新增 prompt-v5-integrity 提示词完整性套件 + 可人工复核的提示词语料（随包发布）。",
+    "compatNote": "依赖宿主提供的 subagents/agents/tools/commands/fs 服务与 @deepseek-ai/dsh-* 插件行；可选 subprocess/sandboxPolicy/compaction。persona 行同时携带 prefix 与 text 两个键，以兼容 0.1.3-alpha.2 的 schema 更名（prefix 必填）与 0.1.2 及更早的 text 键。已在 dsh-v0.1.5-rc.2（@deepseek-ai/dsh-persona 0.1.5-rc.2）上逐行校验全部预设行并通过（v2/v3/v4；v1 已于 v2.0.0 移除）。注意：DSH 0.1.2 起 subagents.startContinuable 的 agentOptions/toolFilter 需要宿主 provider 声明对应 capability（spawn/fork 进程内 provider 均支持），安装器启动时会做能力自检并在旧版宿主上告警。2026 兼容性修复：v2/v3 工具权限名表原先硬编码 web/fetch/bash（未注册名会使 tools.restrict() 抛错、子代理无法建立），现按真实注册名并加带守卫的重试；v4 真实 /compact 原先在 subagent/end 里查 agents.get()（该事件触发时子代理已移出注册表，属死代码），现改为在 subagent/start 捕获 Agent 引用；三套预设的可选服务改为惰性读取，不再在 apply() 快照；v4 的 tools/commands 注册补入 ctx.effect；安装器自检新增 subprocess/sandboxPolicy/compaction。v2.1.0 新增 v5 研究所体系：状态存于宿主 host-only 会话投影单元（键 vibeMathV5），因此自检新增 sessionProjections/sessions（均为可选；缺失时 v5 回退到加固 JSON 状态文件）。v5 不依赖任何 npm 实验包，纯 preset 内单文件实现。v2.2.2 新增 v5 架构图（示例图/框架图-v5.svg + docs/generate_framework_diagram_v5.mjs 零依赖 Node 生成器 + vibe-math-v5/架构图.md 全套 Mermaid 细节图），并修复在绘制架构图时暴露的真实缺陷：会议进行中提出的验证会并发启动（会议与验证的互斥此前只做了单向），现改为排队。v2.2.1 把「全面检查必查清单」(AUDIT-CHECKLIST.md) 作为随包强制流程发布，提示词/交互正确性列为第一优先审计维度。v2.2.0 修复实测发现的提示词身份错乱：状态块改为显式接收它所描述的成员，创建成员时先落盘进编制再构造入职提示词，章程快照冻结在入职时，重建会话不再自称“刚入职”，所办调用不再被误判成某位研究员，框架反馈改为独立发送者投递，一次提示词不再重复投递同一条消息，并新增 prompt-v5-integrity 提示词完整性套件 + 可人工复核的提示词语料（随包发布）。",
     "compatibility": {
       "dshReleases": {
         "0.1.2-alpha.4": "compatible",