ChongCyrus/Vibe-Mathematics

Vibe Mathematics — 多代理数学问题求解与验证框架（三架构）

npm
License: MIT
GitHub stars

运行在 DeepSeek Harness 内的一组 agent preset（vibe-math-v2 / vibe-math-v3 / vibe-math-v4），
用多代理协作自动求解数学问题并对结论做多代理交叉验证。三个预设共享「断点续跑、
中途人工干预、进度汇报、自然语言驱动」底座能力，但采用三代不同的求解架构：
💡 vibe-math-v2 与 vibe-math-v3 同级主推——两者都是成熟可用、正在维护的主推架构，根据你的实际需求自行选择（详见下方「怎么选」）；vibe-math-v4 是最新的「常驻自组织合作研究」架构（实验性）。

- vibe-math-v2（概率驱动 · JSON 数据层）✅ 主推：qs.json 问题清单 + Propos/ 命题库 + 概率驱动调度 + 代码启发式调度；
- vibe-math-v3（第三代 · 论文式 md + 规划代理 + 方法库）✅ 主推：全部知识以 Markdown 论文/研究报告式 存储与续写（Problems/ 问题清单+依赖+来源动机、Progress/ 研究日志、Propos/ 命题库、Methods/ 通用理论发明库、Verified/ 绝对可信）；调度前由规划代理自主制定接下来 N 步计划；解决过程中发明的理论/框架/工具/方法/思想由 Method Keeper 沉淀为可复用方法体系（如发明群论、泛函分析那样）。
- vibe-math-v4（第四代 · 常驻自组织合作研究）🧪 实验性：一组持久化常驻子代理互相留言 + 开会，自主决定一切任务安排（无中央调度）；各自沉淀进度/命题/方法/子问题库并互相查阅；验证仅当全体常驻一致（真 或 假）才写入 Verified/，否则留库附概率；上下文达阈值自动 /compact；仅当全体一致认为原问题已解决才停止。

安装本插件包（或手动复制预设）后，DSH 的预设选择器里会出现三个 agent preset。

🧩 架构图（v2 + v3 + v4）

静态架构图；完整流程说明见 docs/架构图.md；可编辑生成脚本：v2 / v3 / v4。

Vibe Math V2（概率驱动 · JSON 数据层）✅ 主推

Vibe Math V2 架构图

一句话流水线：qs.json 按优先级取问题 → Explorer 拆方向（全死路则重派生）→ 每方向一个 Solver 多轮迭代（引理进 Propos/、解法回 qs.json，概率均 /、Propos//、Methods//、Subproblems// 库，并可互相阅读；验证由它们自行商议发起，仅当全体常驻一致（真或假）才写入 Verified/，否则留库附概率；常驻上下文量达阈值（默认 66%）自动 /compact；仅当全体一致认为原问题已解决才停止；可随时人工干预/增开/关闭常驻，支持断点续跑。
说明：V4 去掉 v3 的中央规划器与确定性角色（explorer/solver/verifier/planner/method-keeper），把“研究者”本身作为主体。详见 vibe-math-v4/实现方案.md。
保活机制（分级保活 A+B + 死锁看门狗）：团伙空闲超 activityTimeoutMs 会收到自驱动 CHECKPOINT（建议继续解决/发消息/提议任务，而非“是否要停止”），且并行填充——A 分支一次尽量填满 maxParallel 并发预算（同一时刻唤醒多个空闲常驻，而非“只唤醒 r1、结束后再 r2”的串行），邮箱投递也并行送达多个空闲收件人；唤醒失败会自动重新武装心跳；若团队空闲且无新产物超过 stallAutoMeetingMs（默认 6 分钟），框架会自动召集一次同步会议让常驻们自行决定下一步；若某次会议/验证卡死（超过 2×activityTimeoutMs 仍无新的发言/投票），框架会自动放弃该会议/验证并回到正常自组织，避免一个坏掉的会议永久卡住整个团队；会议不抢占验证——验证进行时会议请求会暂存，验证做完再补开（保持一致共识的“求真”环节不被协调讨论打断）——框架始终只促成、从不指派任务。

✨ 功能特色

- 多代理自动求解：主代理把问题交给调度器，调度器派发 explorer / solver / verifier（v2/v3）与 planner（规划代理，v3）、method-keeper（方法整理代理，v3） 等子代理协同求解，你无需逐节点手操。
- 多代理交叉验证：每个结论交给 ≥3 个「严苛审稿人」独立审查 → 辩论（交流群）→ 裁决（v3 默认近共识裁决：同侧且均值 ≥0.85/≤0.15 取均值，避免“0.9 vs 1”被误判成 0.5）。
- 论文式 Markdown 知识库（v3）：问题清单（含问题间依赖、后生问题产生原因与计划）、研究日志、命题、方法库全部以 md 论文/研究报告式书写与续写（方向重派生时旧方向的日志自动归档保留）；只有 Verified/ 与验证器判真/假的对象绝对可信，其余 md（含方法库未验证断言）仅作经验参考。
- 通用理论发明库（v3）：解决过程中发明的理论体系/框架/工具/方法/思想（含经验性总结）经 methods_used/new_inventions 上报，由 Method Keeper 沉淀为 Methods/ 方法卡（可组成体系层级、跨项目复用），像“解决方程时发明群论”一样形成系统化方法理论体系。
- 规划代理调度（v3）：调度前调用规划代理，根据实际情况（问题依赖/存活率/可验证对象/并发预算/上次计划结果）自主选择最优调度方案，一次安排接下来 N 步各代理任务；规划失败自动回退启发式。
- 知识沉淀：验证通过的结论晋升进 Verified/ 可信知识库（v2/v3 另有 Propos/ 命题库），供后续方向复用。
- 断点续跑：调度状态、任务栈、代理注册表、决策队列、验证器历史准确率等全部落盘；重启后 resume 即可恢复（v2/v3 用进程纪元区分“同进程暂停→恢复”与“跨进程重启”；v3 的 md 本身即叙事断点）。
- 中途人工干预（并继续）：auto / manual 模式随时切换；manual 在关键节点挂起决策等你 approve/reject/override（v3 新增计划审批门与方法晋升门）；可对任意子代理发消息 / 中断。
- 按项目隔离：每个数学问题一个独立项目文件夹，互不干扰，可随时切换。
- 多会话并行隔离：DSH 的 agent preset 是 standing mount（同一 preset 的所有会话共享一个插件实例），插件内部按根会话 id 隔离全部运行状态——两个会话可以同时各跑一个项目，各自的子代理会正确挂在自己会话名下，调度器 / 参数 / 决策队列 / 当前项目互不干扰（v3 另有项目锁，同一项目同一时刻只被一个会话调度）。当前项目按会话分别持久化（VibeMath/current..json）。
- 子代理权限可调控：可限制子代理允许/禁止的工具、每轮外部工具调用上限，并明确告知其可读 Verified/、Propos/、Methods/、Reliable/ 与进度日志。
- 可配置：vibe_math_setting.json（含注释）自定义默认参数；/vibe setup 交互式问答配置。
- 自然语言控制：主代理充当「助手 + 汇报者」，你把需求说成人话，它自己调用工具、汇报进度、配置参数。

🚀 安装

两种安装方式，任选其一（也可并存）：

方式 A：作为插件包一键安装（推荐，同时装出三个预设）

dsh plugin --profile  add dsh-vibe-math
或从 GitHub 直装：
dsh plugin --profile  add github:ChongCyrus/Vibe-Mathematics

安装时插件会自动把三个 preset 写入 ~/.dsh/.agent-presets/：vibe-math-v2/、vibe-math-v3/ 与 vibe-math-v4/。
之后新建会话，预设选择器里选择 Vibe Math V3（v3，主推）、Vibe Math V2（v2，主推）或 Vibe Math V4（v4，常驻自组织）即可——v2 与 v3 同级主推，按实际需求自选（见「怎么选」）。
升级包版本后重启 DSH，未手动改过的 preset 文件会自动更新到新版本（细节见文末「v2/v3」安装器说明）。

方式 B：作为 agent preset 手动安装

1. 把本仓库对应目录的文件复制到 preset 目录：

C:\Users\\.dsh\.agent-presets\vibe-math-v2\   ← 复制 vibe-math-v2/ 下的 agent.cordis.yml / preset.yml / vibe-math-v2.js
C:\Users\\.dsh\.agent-presets\vibe-math-v3\   ← 复制 vibe-math-v3/ 下的 agent.cordis.yml / preset.yml / vibe-math-v3.jstext
C:\Users\\.dsh\.agent-presets\vibe-math-v4\   ← 复制 vibe-math-v4/ 下的 agent.cordis.yml / preset.yml / vibe-math-v4.js

2. 新建一个会话，在 preset 选择器里选 「Vibe Math V2」 / 「Vibe Math V3」 / 「Vibe Math V4」。
3. 会话启动后即可使用：工具列表里会出现 vibe_math_ 工具，输入框键入 /vibe 有自动补全。

修改 preset 文件后需重启 DSH 进程再开新会话（preset 的 standing mount 会缓存到进程退出）。

DSH 版本适配与依赖

- 形态依赖：三个 preset 依赖 DSH 的标准 agent-preset 机制（~/.dsh/.agent-presets// + preset picker）与 bundle patch 机制（cordis.patch.yml 注入安装器）。
- 宿主插件行：agent.cordis.yml 引用宿主提供的 @deepseek-ai/dsh- 插件行（persona、agent-instructions、tool-bash/pwsh、tool-fs/fs-search、tool-jobs、skill-filesystem、tool-skill、tool-goal、plan-mode、compaction、subagent/workflow、ask-user、todo、web 等，约 21 个唯一包名）。宿主缺行会导致 preset 挂载失败（会话启动时报错）。
- 宿主服务 API：预设插件消费 subagents（startContinuable / sendMessage（续做/唤醒；followup 仅为 Agent 对象方法、不是 subagents 服务方法）/ interrupt）、agents（roots）、tools（register）、commands（register）、fs（resolve/stat/readText/writeText/listDir）、可选 subprocess / sandboxPolicy。这些 API 形状随 DSH 版本演进；本项目已充分测试并确认适配 dsh-v0.1.2-rc.1（package.json 的 dsh.testedVersion；minVersion 为 0.1.2-rc.1）。注意：DSH 0.1.2 起 subagents.startContinuable 的 agentOptions / toolFilter 需要宿主 provider 声明对应 capability（spawn / fork 进程内 provider 均支持，v4 指定常驻模型/路由与工具权限依赖于此）。
- DSH STORE 兼容声明：package.json 的 dsh.compatibility.dshReleases 对每个完整 DSH 版本逐项声明 compatible / incompatible / unknown（当前 0.1.2-alpha.4、0.1.2-alpha.5、0.1.2-rc.1 均标 compatible）；engines.node 为 ^22.19.0 || >=24.0.0（与 DSH 0.1.2 相同）。
- 运行时自检（能力 + 版本双检）：安装器（bundle 插件）每次启动时：① 尽力探测 DSH 版本（读 @deepseek-ai/dsh/package.json 或 DSH_VERSION 环境变量；DSH 未通过公开 service/context 暴露版本，故为尽力而为，探测不到就跳过）。若探测到且该版本未被 dshReleases 声明为 compatible，会给出明确“DSH 版本不匹配，请使用 dsh-v0.1.2-rc.1（或 0.1.2-alpha.4/alpha.5）”提示；② 再对上述服务与关键 API 做能力自检（这是真正的挂载门槛，含 fs.resolve 返回形状检测与 subagent agentOptions/toolFilter capability 检测），不满足时打 warning。preset 挂载失败时先看 DSH 日志里的自检 warning。
- 升级路径：DSH 升级后无需重装本包；升级本包用 dsh plugin update dsh-vibe-math，重启 DSH 后安装器会自动把 preset 更新到新版本（见上文「安装」说明）。

🧭 三个预设怎么选

💡 vibe-math-v2 与 vibe-math-v3 同级主推，按你的实际需求自行选择：

- 选 vibe-math-v2（概率驱动 · JSON 数据层），如果你：
- 偏好结构化 JSON 数据（qs.json / Propos/_Propos.json / Verified/ 卡），方便程序化检索与二次加工；
- 想要成熟稳定的代码启发式调度（优先级 + 概率，行为可预期、不依赖规划代理的“临场发挥”）；
- 不需要方法库沉淀 / 论文式叙述，数据以字段为主即可。
- 选 vibe-math-v3（论文式 md + 规划代理 + 方法库），如果你：
- 偏好论文/研究报告式的自然语言知识库（问题清单含依赖与后生问题来源动机、研究日志按方向按轮续写，人类可读、可自由续写）；
- 希望调度由规划代理根据实际情况自主制定 N 步计划（更灵活，失败自动回退启发式）；
- 希望通用理论发明库——求解中发明的理论/框架/工具/方法/思想经 Method Keeper 沉淀为可复用、可体系化、跨项目扩充的方法论（像“解决方程时发明群论”）；
- 接受“只有 Verified/ 绝对可信，其余 md 为经验参考”的可信分层。

两者都成熟可用、持续维护，且都支持断点续跑、人工/自动干预、进度汇报、多会话隔离、命题晋升、近共识/加权裁决等核心能力；切换成本低（同一套 vibe_math_ 工具与 /vibe 命令、同一套参数体系）。

⚠️ vibe-math-v2 与 vibe-math-v3 是成熟主推架构；vibe-math-v4 是实验性的常驻自组织架构， 均可选择；老 vibe-math-v1 已被移除（本包仅含 v2/v3/v4）。

| | v2（概率驱动 · 主推） | v3（论文式 md · 主推） | v4（常驻自组织 · 实验） |
|---|---|---|---|
| 定位 | 主推（JSON 数据层） | 主推（第三代） | 实验性（第四代） |
| 核心思想 | 概率驱动：qs.json 问题 + Propos/ 命题库，按「正确概率 / 价值」调度 | 论文式 md 知识库 + 规划代理调度 + 通用理论发明库 | 持久化常驻子代理自组织：互相留言 + 开会决定一切任务，无中央调度 |
| 数据 | qs/qs.json + Propos/_Propos.json + Reliable/ | Problems/ + Progress/ + Propos/ + Methods/（全部 md，软规范锚点 + 自由叙述）+ Verified/ | Problems/ + 按常驻 id 归属的 Progress|Propos|Methods|Subproblems// + Shared/（会议/任务板/辩论）+ Verified/ |
| 角色 | explorer → 逐方向 solver → verifier | planner（规划代理） → explorer → 逐方向 solver → verifier → method-keeper（方法整理代理） | N 个常驻研究者（continuable），由它们互相通信/开会分工，无固定角色 |
| 调度方式 | 代码启发式（优先级 + 概率） | 规划代理产出 N 步计划（校验后执行，失败回退启发式） | 无中央调度：任务由常驻互相留言/开会（框架只做媒介，不指派） |
| 收口规则 | 解法/证明达概率 1 即收口，never 永不调度 | 同 v2（近共识裁决修复 flat 误判） | 仅当全体常驻一致（真 或 假）才写入 Verified/，否则留库附概率 |
| 停止 | 全解或卡死 | 全解/无候选 | 仅当全体常驻一致认为原问题已解决才停止 |
| 上下文 | 无 | 无 | 常驻上下文达阈值自动 /compact（可调） |
| 特设能力 | 命题「价值/关键性」自动晋升问题清单；reportMode file/push/both；priorityAdjust | 方法库沉淀循环（methods_used/new_inventions → Method Keeper）；计划审批门/方法晋升门；项目锁；后生问题「来源与动机」一等公民 | 常驻各自沉淀 + 互相阅读；全体一致验证；随时增开/关闭常驻、留言干预；断点续跑 |

三者都支持：断点续跑（vibe_math_resume / vibe_v4_resume）、人工/自动模式切换、vibe_math_ / vibe_v4_ 工具集与 /vibe /v4 命令、按项目隔离、子代理权限调控。v2 与 v3 均为同级主推——偏好结构化 JSON 数据与确定性调度选 v2，偏好论文式 md、规划代理与理论发明库选 v3；v4 是最新的「常驻自组织合作研究」实验架构。

🧠 架构与分工（v3 · 第三代）✅ 主推

框架 = 一个主代理（助手）+ 一个代码调度器 + 一个规划代理 + 六类子代理。

| 角色 | 类型 | 职责 |
|---|---|---|
| 主代理 | LLM（会话里的那个助手） | 自然语言接口 + 汇报者 + 助手。它自己不求解、不调度，只负责：把你的话翻译成 vibe_math_ 工具调用、汇报进展、问答式配置参数、执行调控命令。 |
| 调度器 | 插件代码（非模型） | 唯一主控：维护 md 知识库索引、构造状态简报、校验并执行规划代理的计划、写文件、推进状态机。硬约束（并发/幂等/已验证不再调度/写所有权）由代码强制。 |
| Planner（规划代理） 🆕 | 子代理 | 每次准备派发时，读取状态简报（问题+依赖+存活率、可验证对象、活跃代理、并发预算、可用方法、上次计划结果），自主选择最优调度方案，一次安排接下来 N 步（spawn/continue/interrupt/promote/verify/method-keep/wait）。输出 JSON 计划，由调度器校验后执行；失败自动回退启发式。 |
| Explorer 子代理 | 子代理 | 元认知头脑风暴：约束分解、边界测试、相似问题映射，把问题拆成多个「大相径庭」的求解方向（全死路则重派生）。开工前先查 Methods/ 方法库。 |
| Solver 子代理 | 子代理 | 每个方向一个专属求解器，同一会话内多轮迭代，产出引理（含证明）、子路线、存活概率、完整解法，并上报 methods_used 与 new_inventions（本轮回新发明的方法/工具/思想）。 |
| Verifier 子代理 | 子代理 | 每个验证对象 ≥3 个独立「严苛审稿人」，独立审查 → 辩论（交流群）→ 近共识裁决（同侧且均值 ≥0.85/≤0.15 取均值，否则 flat/forced）。 |
| Method Keeper（方法整理代理） 🆕 | 子代理 | 定期消化近期工作与新发明上报，提炼新方法卡、合并碎片、完善体系结构（上级体系/子方法）、维护可信断言，把求解中发明的理论/框架/工具/方法/思想沉淀进 Methods/ 通用理论发明库。 |

一句话分工：主代理负责“和人对话”，规划代理负责“定计划”，调度器负责“执行与守界”，子代理负责“动脑”，Method Keeper 负责“把发明沉淀成理论”。

📁 目录结构

v2（概率驱动 · 主推）

/VibeMath/
├─ current.json                        # 当前项目
├─ vibe_math_setting.json             # （可选，全局回退）默认参数 JSONC，含注释
└─ Projects//
├─ vibe_math_setting.json          # 该项目默认参数
├─ qs/qs.json                       # 问题清单：概述/已解决/解法列表(完整解法·正确概率)/优先级/progress
├─ Propos/_Propos.json        # 命题库：概述/布尔估计/细类型/证明·证伪列表/优先级/价值·关键性/progress
├─ Reliable/                        # 可信参考文献（只读，用户放入）
├─ Verified/                        # 定论事实索引（布尔估计=0/1 的命题）
├─ Verification_logs/               # 每轮验证的辩论记录（审计用）
├─ Progress_Logs/                   # 定期进度报告 report.json
└─ VibeMath_State/                  # 调度器私有持久状态（断点恢复用）

v3（论文式 md + 规划代理 + 方法库）✅ 主推

/VibeMath/
├─ Methods/                            # 【全局】跨项目通用理论发明库（v3，晋升自项目级）
├─ current..json               # 每会话当前项目（多会话并行互不覆盖）
├─ vibe_math_setting.json             # （可选，全局回退）默认参数 JSONC，含注释
└─ Projects//
├─ vibe_math_setting.json          # 该项目默认参数
├─ Problems/.md                 # 问题清单：每问题一个 md（软规范锚点：ID/类型/状态/优先级/依赖/被依赖/来源/计划
│                                   #   + ## 陈述 / ## 来源与动机（后生问题：产生流程/动机/回填计划）/ ## 解法候选）
├─ Progress/.md                 # 聚合研究日志索引（各方向摘要 + 引理索引 + 各轮记录）
├─ Progress//.md         # 每方向一个独立文件（代理自组织直接写，方向间无并发冲突）
├─ Propos//.md            # 命题库：每命题一个 md（陈述/证明尝试/证伪尝试，软规范锚点 + 自由叙述）
├─ Methods/.md                  # 【通用理论发明库】方法卡：理论体系/框架/工具/方法/思想（含应用记录/改进历史/体系层级）
├─ Verified/命题/.md            # 绝对可信：调度器生成的已验证命题卡（只读）
├─ Verified/问题/.md            # 绝对可信：已解决问题的完整可信解法卡（只读）
├─ Reliable/                        # 可信参考文献（只读，用户放入）
├─ Notes/                           # 自由笔记（不参与调度）
├─ Logs/Verification/               # 每轮验证的辩论记录（审计用）
├─ Logs/Plans/                      # 每次调度计划 + 执行结果（规划学习闭环）
├─ Logs/报告.md                     # 论文式人读进度报告
└─ State/                           # 调度器私有持久状态（agents/tasks/plans/verifier_accuracy/index/项目锁/进程纪元）

铁律（v2 通用）：调度器是唯一文件写者（子代理只返回结构化 JSON，从不写文件）。
v3 铁律：只有 Verified/ 与验证器判真/假的对象绝对可信；其余 md（未定论命题、研究日志、方法库未验证断言）仅作经验参考；调度器只解析软规范锚点行与条目标题行，从不解析正文散文。v3 支持代理直接写 md（自组织定位各自归属文件，如求解器写 Progress//.md、新引理写 Propos//.md、方法整理代理写 Methods/.md）；并发安全靠写锁——写任何文件前调 vibe_math_claim_write、写完 vibe_math_release_write（同一文件同一时刻只允许一个代理写），内容留在 md，轻量元数据经 vibe_math_sync_meta 上报给调度器。

⚡ 快速上手

方式 A：直接对话（推荐，最省事）

因为主代理内置了使用说明，你直接说人话即可：

帮我用 Vibe Math 证明 √2 是无理数。

主代理会自动：vibe_math_add_problem 加题 → vibe_math_start 启动 → 之后你随时问它进度。

现在进展怎么样了？

主代理会自动调用 vibe_math_status / vibe_math_report 并把结果用人话汇报给你。

方式 B：命令 / 工具（精确控制）

在对话里直接调用工具（参数为 JSON）：

| 工具 | 作用 |
|---|---|
| vibe_math_add_problem | 加题（id/description/priority/dependencies?；v3 生成 Problems/.md） |
| vibe_math_add_proposition / vibe_math_list_propositions（v2/v3） | 添加 / 列出命题库（id/概述/布尔估计/细类型/价值·关键性；v3 生成 Propos//.md） |
| vibe_math_start / vibe_math_resume | 启动 / 断点恢复调度器 |
| vibe_math_pause / vibe_math_abort | 暂停 / 终止（中断所有子代理） |
| vibe_math_status / vibe_math_report | 查看状态 / 完整进度报告 |
| vibe_math_set_mode | 切换 auto / manual |
| vibe_math_set_params | 运行时调参 |
| vibe_math_setup | 返回参数 schema（交互式配置用） |
| vibe_math_save_settings | 把当前参数存成新默认 |
| vibe_math_template | 生成默认参数模板文件 |
| vibe_math_new_project / vibe_math_set_project / vibe_math_list_projects | 项目管理 |
| vibe_math_list_decisions / decide | 查看 / 裁决人工决策（v3：node=plan 计划审批 / node=method-promote 方法晋升） |
| vibe_math_list_agents / vibe_math_message_agent / vibe_math_interrupt_agent | 查看 / 发消息 / 中断子代理 |
| vibe_math_plan（v3） | 查看待执行计划 / 上次计划，或 force:true 强制触发一次规划 |
| vibe_math_index（v3） | 从 md 知识库重建机器索引（State/index.json） |
| vibe_math_method_add / vibe_math_method_list（v3） | 手动添加 / 列出方法卡（项目 + 全局） |
| vibe_math_lock_status（v3） | 查看项目锁占用 |
| vibe_math_claim_write / vibe_math_release_write（v3） | 申请 / 释放某个 md 文件的写锁（代理直接写文件前调用；同一文件同一时刻只允许一个代理写，防并发冲突） |
| vibe_math_sync_meta（v3） | 代理把内容写进 md 后上报轻量元数据（方向状态/存活率/引理 id/方法卡 id/新发明），让调度器同步索引——内容留在 md，不进 JSON |

斜杠命令（与工具等价）：/vibe start|resume|pause|abort|status|report|mode |setup|save|template [global|project]|add  |add-proposition  |list-propositions|project [list|new |]|decisions|agents（v3 另有 methods|index|plan|lock）

🎓 教学：让主代理替你干活

1. 自然语言驱动（不用记命令）

主代理的作用就是当你的「翻译官」。你只需描述目标，它会自己选择并调用工具：

| 你说的话 | 主代理做的事 |
|---|---|
| “求解 / 证明 XXX” | add_problem + start，之后汇报 |
| “现在进度怎么样 / 有哪些代理在跑” | status / report / list_agents 并总结 |
| “暂停 / 终止求解” | pause / abort |
| “切到人工模式，我要逐步把关” | set_mode manual，之后有决策就 list_decisions 提醒你 |
| “给 q1 的某个求解方向换个思路（比如改成构造性证明）” | list_agents 找到 childId → message_agent 注入新指令 |
| “中断某个卡住的子代理” | interrupt_agent |

2. 问答式参数配置（/vibe setup）

你甚至不用记参数名。说：

帮我配置一下参数。

主代理会调用 vibe_math_setup 拿到完整参数 schema（每项含说明 / 选项 / 建议 / 当前值），
然后用 ask_user_question 逐项问你（选项自带解释与建议），你选完它用 vibe_math_set_params
应用，最后问你是否 vibe_math_save_settings 存为默认。

也可以直接跑命令：/vibe setup（看 schema）→ 跟主代理说你要改哪些 → /vibe save（存默认）。

3. 配置文件（vibe_math_setting.json）

- 生成模板：/vibe template（生成到工作区）或 /vibe template project（生成到当前项目）——
会产出一份带 // 注释、逐项中文说明的 JSON 模板，你手改后重启/resume 即生效。
- 保存当前值：/vibe save 把当前生效参数写回该文件。
- 唯一持久化来源：该文件是参数的唯一持久化层（项目级优先 → 缺失时回退全局 /VibeMath/vibe_math_setting.json → 内置默认）。
vibe_math_set_params / set_mode 会立即写回项目级文件并持久化，无需再手动 save。

🌱 新手示例流程（以“证明 √2 是无理数”为例）

Step 1 — 用一句话启动

帮我用 Vibe Math 证明：√2 是无理数。

主代理执行 vibe_math_add_problem {"id":"q1","description":"证明：√2 是无理数。","priority":0}
再执行 vibe_math_start，然后告诉你“已启动”。

Step 2 — 询问进度

进展如何？

主代理执行 vibe_math_status 并用人话汇报：当前活跃子代理数、正在验证的单元、是否有待决策等。

Step 3 — 问答式调参（可选）

我想让它用加权投票，并发数设成 6。

主代理 vibe_math_set_params {"verdictMode":"weighted-vote","maxParallelThreshold":6}，
并问你是否 vibe_math_save_settings 保存。

Step 4 — 中途干预（可选）

切到人工模式，我要在每个关键节点把关。

主代理 vibe_math_set_mode {"mode":"manual"}。之后每到一个关键节点它会 vibe_math_list_decisions
拿到决策，向你说明，等你 vibe_math_decide {"id":"...","action":"approve"}（或 reject / override）。

Step 5 — 收尾

结束了吗？结论是什么？

主代理 vibe_math_status：qs.csv 里 q1 已回写 solved，解法文件在 Verified/ 里并被命名为
q1-的解法_.csv。

v2 对应的收尾是：qs.json 中 q1.已解决 = true，其解法 正确概率 = 1，相关命题进入 Verified/。

🖼️ 实际使用示例（长截图）

截图很长，这里默认折叠：点击下方「展开」才加载整张长图，避免它占满页面、遮挡前后文字。

📸 展开查看实际使用示例长截图

实际使用示例长截图

⚙️ 参数速查表

v2（概率驱动 · 主推）默认值

| 参数 | 默认 | 说明 |
|---|---|---|
| mode | auto | auto / manual |
| maxParallelThreshold | 4 | 全局最大并发子代理轮数（新派发前须 active 1 = 自己 + 最多 N-1 个其他活跃方向摘要） |
| verifierCount | 3 | 每个验证对象的独立验证器数量 |
| debateMaxRounds | 5 | 验证辩论（交流群）最大轮数 |
| verdictMode | flat | flat = 均衡机制（不一致判 0.5）/ forced = 强制裁决（历史准确率+严谨性加权） |
| reportMode | file | file = 写报告文件 / push = 推送主代理汇报 / both |
| promoteValueThreshold | 0.7 | Propos 中「价值/关键性」≥ 该值且未决(0,1) 的命题自动加入 qs.json |
| priorityAdjust | none | none / deadend-deprioritize（全死路降优先级）/ survival-map（按存活率重算） |
| proposPriorityAdjust | none | 命题优先级动态调整：none / progress-graded（按定论接近度+证明/证伪材料量重算，越接近定论越优先验证） |
| provider / model | 空 | 子代理模型（空 = 继承根代理） |
| solverPersona / verifierPersona / explorerPersona | 空 | 注入求解器/验证器/explorer 提示词开头的人格/要求 |
| knowledgeContext | 空 | 共享知识/数据模型说明（空 = 内置完整版：对象/属性定义、概率语义、文件夹用途、输出完整性要求；非空 = 覆盖并注入所有子代理提示词） |
| solverToolAllow / solverToolDeny | [] | 求解器允许/禁止的工具 |
| verifierToolAllow / verifierToolDeny | [] | 验证器允许/禁止的工具 |
| solverAllowNetwork / verifierAllowNetwork | 空 | 网络工具开关（web_search/web/fetch）：空=继承全部；true=在已有 allow 列表时补入；false=禁止 |
| solverAllowScripts / verifierAllowScripts | 空 | 脚本工具开关（bash/pwsh）：同上 |
| solverMaxToolCalls / verifierMaxToolCalls | 0 | 每轮外部工具调用上限（0=不限） |
| reportIntervalMs | 0 | 0 = 仅事件驱动（有状态更新才写/推）；>0 = 定时自动汇报（毫秒） |
| tickIntervalMs | 2000 | 调度器心跳间隔（毫秒） |
| activityLogCap | 100 | 活动日志保留条数（report 最多显示 30 条） |
| maxExplorerRetries | 3 | explorer 拆方向失败的重派生上限 |

v3（论文式 md + 规划代理 + 方法库）默认值

在 v2 全部参数之上新增/调整：

| 参数 | 默认 | 说明 |
|---|---|---|
| verdictMode | forced | v3 先做近共识判定（全部结果同侧且均值 ≥0.85/≤0.15 取均值），否则 forced=按历史准确率+严谨性加权 / flat=均衡（0.5）。修复了 v2 flat 把"0.9 vs 1"误判成 0.5 的问题 |
| planningHorizon | 3 | 规划代理一次计划的最多动作数（"接下来 n 次"） |
| plannerEnabled | true | false = 完全走内置启发式调度（规划代理禁用） |
| plannerProvider / plannerModel | 空 | 规划代理模型路由（空 = 继承根代理） |
| plannerPersona | 空 | 注入规划代理提示词开头的人格/要求 |
| planMinIntervalMs | 30000 | 两次规划调用的最小间隔（毫秒）；系统空闲且有工作时忽略 |
| plannerMaxFails | 3 | 规划代理连续失败达此值 → 自动降级启发式 |
| methodKeepIntervalMs | 0 | Method Keeper 定时整理间隔（0 = 事件驱动） |
| methodKeepEvery | 5 | 每积累 N 个待沉淀发明/新命题触发一次整理 |
| methodAutoPromote | false | 项目级方法自动晋升全局库（false = 人工门） |
| indexAutoRebuild | true | 每次写盘后自动重建 State/index.json（false = 手动 vibe_math_index） |
| projectLockTimeoutMs | 60000 | 项目锁等待超时（同项目同一时刻只允许一个会话调度） |
| methodKeeperPersona | 空 | 注入方法整理代理提示词开头的人格/要求 |

v4（常驻自组织 · 实验）默认值

vibe_v4_set 可调（持久化到 State/settings.json）：

| 参数 | 默认 | 说明 |
|---|---|---|
| residentCount | 4 | 常驻数（可 vibe_v4_add_member 增减） |
| compactThreshold | 66 | 常驻上下文占比达此值触发软压缩（自述指令） |
| compactAfterRounds | 8 | 常驻每累计 N 轮（未压缩）触发一次软压缩 |
| meetingKeepEvery | 5 | 每积累 N 个新产物自动触发一次同步会议 |
| maxParallel | 3 | 同时唤醒的常驻上限（框架侧并发闸，非指派） |
| activityTimeoutMs | 120000 | 空闲心跳间隔（超时才触发自驱动 CHECKPOINT 唤醒，推动常驻继续推进；唤醒失败会自动重新武装心跳，保证小组永不永久停死） |
| stallAutoMeetingMs | 360000 | 停滞自动同步会议阈值（分级保活 B）：团队空闲且无新产物超过该时长时，框架自动召集一次同步会议，让常驻们自行决定下一步路线/分工（框架只促成，不指派） |
| verdictMaxRounds | 3 | 验证在独立初评后进入辩论的最大轮数 |
| provider / model | 空 | 常驻 LLM 路由（空 = 常驻继承主代理的 provider/model；此前声明未用，v1.4.1 真正接入） |
| residentPersona | 空 | 注入每个常驻提示词开头的人格/要求 |
| toolAllow / toolDeny | [] | 常驻工具权限（经 startContinuable 的 toolFilter 做作用域 tools.restrict()；空 = 继承全部工具；⚠️ 空 allow:[] 会拒绝一切工具） |

📝 断点续跑 & 人工干预（两大硬性需求）

- 断点续跑：所有状态落盘（v2：VibeMath_State/.json；v3：State/.json），每个子代理都是 DSH 的 continuable 持久会话（对话由 DSH 自动保存）。重启后新开会话 → vibe_math_resume 即可续跑。v2/v3 额外用进程纪元区分“同进程暂停→恢复”（保留存活子代理继续）与“跨进程重启”（清理陈旧任务）。v3 的 md 知识库本身就是叙事断点——代理 resume 时从研究日志/问题卡/命题卡尾部续写。
- 中途人工干预：manual 模式在关键节点挂起决策（v2：explorer/solver 派发、验证裁决；v3：计划审批门（规划代理产出计划后等你 approve/reject）、验证裁决门、方法晋升门（项目方法 → 全局库））；可随时 set_mode auto 切回自动（自动放行所有挂起决策）；可对任意子代理 message_agent / interrupt_agent。
- 进度汇报：默认事件驱动 —— 只有代理状态更新等事件发生时才会写报告（v2：Progress_Logs/report.json；v3：Progress_Logs/report.json + Logs/报告.md 论文式人读摘要；reportMode 可 file/push/both，push 通过 rootAgent.followup() 唤醒主代理主动汇报）；只有把 reportIntervalMs 设为 >0 才启动定时自动汇报（间隔毫秒）。

📚 规格文档

- v2（概率驱动）：vibe-math-v2/实现方案.md
- v3（论文式 md + 规划代理 + 方法库）：vibe-math-v3/实现方案.md
- v4（常驻自组织）：vibe-math-v4/实现方案.md

⚠️ 已知边界（有意简化）

v2：
- 安装器带版本化自动更新：每次 DSH 启动时对比包版本与 /.vibe-math-installed.json 记录——版本升级会自动替换未被手动修改的 preset 文件（哈希一致才覆盖）；你改过的文件会被保留并在日志中提示。无记录的老安装首次会一次性刷新到当前版本。想强制全量重装：删除 ~/.dsh/.agent-presets/vibe-math-v2、vibe-math-v3 与 vibe-math-v4 目录后重启 DSH。
- flat 裁决在辩论不一致时直接判 0.5（高置信分歧如 0.9 vs 1 也会被误判 0.5——v3 已用近共识规则修复）；forced 按历史准确率+置信度加权。
- never 优先级的问题/命题永不调度，且不阻塞严格终止（视为主动弃权）。
- 三个 preset 文件互相独立、可共存；同一会话同时只能选一个预设。

v3：
- 软规范而非零规范：md 知识库只强制对象头部的 4~7 行锚点（- ID/类型/状态/概率/优先级/依赖/...）与条目标题行（### 解法/证明/证伪 N｜标题｜概率X｜状态Y），供调度器可靠索引；正文完全自由论文式叙述，调度器从不解析正文。手工编辑锚点可能导致索引漂移（调度器会保留上次有效索引并告警）。
- 规划代理是增强而非必需：plannerEnabled=false 或规划代理连续失败（plannerMaxFails）时自动回退 v2 式启发式调度；planMinIntervalMs 冷却在有在途子代理时生效（系统空闲时有工作则立即规划）。
- 方法库可信分层：方法卡的 可信断言 只允许链接已进 Verified/ 的 ID；方法条目的其余内容（含未验证的策略/直觉/启发式）一律视为经验参考，不得当定理引用。
- 项目锁：同一项目同一时刻只允许一个会话调度（第二个会话启动会提示“被会话 X 占用”）；锁在暂停/终止/全部解决时自动释放。
- 近共识裁决：全部验证器结果同侧且均值 ≥0.85/≤0.15 时取均值（如 0.9 vs 1 → 0.95），否则 forced 加权 / flat 判 0.5——修复了 v2 中“数学上正确但形式有瑕疵”的结论被误判为不确定的问题。

📄 License

MIT