ChongCyrus/Vibe-Mathematics

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

运行在 DeepSeek Harness 内的一组 agent preset（vibe-math-v1 / vibe-math-v2）， 用多代理协作自动求解数学问题并对结论做多代理交叉验证。两个预设共享「断点续跑、 中途人工干预、进度汇报、自然语言驱动」三大底座能力，但采用两套不同的求解架构： 💡 推荐使用 vibe-math-v2（v1 的架构级重构，更完善更优雅；v1 作为早期架构保留兼容，可能在将来版本中被遗弃、不再维护）。

• vibe-math-v1（经典流水线）：「广度探索 → 深度迭代 → 交叉验证 → 知识沉淀」闭环；
• vibe-math-v2（新架构 · 概率驱动）：qs.json 问题清单 + Propos/ 命题库 + 概率驱动调度。

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

---

🧩 架构图（v1 + v2）

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

Vibe Math V1（经典流水线）⚠️ 早期架构 · 将弃用 · 不建议新项目使用

一句话流水线：qs.csv → Brainstorm 拆方向 → 每方向一个 Solver 多轮迭代（卡死则 Derive 派生新方向）→ 输出拆成最小验证单元 → ≥3 个 Verifier 独立审查 → 辩论 → 裁决 → 通过晋升 Verified/ → Decider 回写 qs.csv；全程状态落盘 VibeMath_State/，resume 断点续跑，manual 模式在派发/裁决/晋升处挂起人工决策。

Vibe Math V2（新架构 · 概率驱动）✅ 推荐 · 当前主推架构

一句话流水线：qs.json 按优先级取问题 → Explorer 拆方向（全死路则重派生）→ 每方向一个 Solver 多轮迭代（引理进 Propos/、解法回 qs.json，概率均 <1）→ 调度器选 r（命题 / 命题+证明·证伪 / 问题+解法）派 ≥3 验证器独立审查→辩论→裁决 → 概率=1 自动收口（问题 solved、命题 1/0，优先级置 never）；全程状态落盘，resume 断点续跑，reportMode 可 file/push/both 汇报。

---

✨ 功能特色

• 多代理自动求解：主代理把问题交给调度器，调度器派发 brainstorm / solver / verifier / decider（v1）或 explorer / solver / verifier（v2）等子代理协同求解，你无需逐节点手操。
• 多代理交叉验证：每个结论交给 ≥3 个「严苛审稿人」独立审查 → 辩论（交流群）→ 裁决。
• 知识沉淀：验证通过的结论晋升进 Verified/ 可信知识库（v2 另有 Propos/ 命题库），供后续方向复用。
• 断点续跑：调度状态、任务栈、代理注册表、决策队列、验证器历史准确率等全部落盘；重启后 resume 即可恢复（v2 用进程纪元区分”同进程暂停→恢复”与”跨进程重启”）。
• 中途人工干预（并继续）：auto / manual 模式随时切换；manual 在关键节点挂起决策等你 approve/reject/override；可对任意子代理发消息 / 中断。
• 按项目隔离：每个数学问题一个独立项目文件夹，互不干扰，可随时切换。
• 多会话并行隔离：DSH 的 agent preset 是 standing mount（同一 preset 的所有会话共享一个插件实例），插件内部按根会话 id 隔离全部运行状态——两个会话可以同时各跑一个项目（如 A 会话跑项目 A、B 会话跑项目 B），各自的子代理会正确挂在自己会话名下，调度器 / 参数 / 决策队列 / 当前项目互不干扰。当前项目按会话分别持久化（VibeMath/current.<会话id>.json）。
• 子代理权限可调控：可限制子代理允许/禁止的工具、每轮外部工具调用上限，并明确告知其可读 Verified/、Propos/、Reliable/ 与进度日志。
• 可配置：vibe_math_setting.json（含注释）自定义默认参数；/vibe setup 交互式问答配置。
• 自然语言控制：主代理充当「助手 + 汇报者」，你把需求说成人话，它自己调用工具、汇报进度、配置参数。

---

🚀 安装

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

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

dsh plugin --profile <你的 profile> add dsh-vibe-math
# 或从 GitHub 直装：
dsh plugin --profile <你的 profile> add github:ChongCyrus/Vibe-Mathematics

安装时插件会自动把两个 preset 写入 ~/.dsh/.agent-presets/：vibe-math-v1/ 与 vibe-math-v2/。 之后新建会话，预设选择器里选择 Vibe Math V2（v2，推荐）或 Vibe Math（v1）即可——v2 是当前主推架构（v1 的架构级重构，更完善更优雅）；v1 作为早期架构保留兼容，可能在将来版本中被遗弃、不再维护，新项目请优先选 v2。 升级包版本后重启 DSH，未手动改过的 preset 文件会自动更新到新版本（细节见文末「v2」安装器说明）。

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

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

   C:\Users\<你>\.dsh\.agent-presets\vibe-math-v1\   ← 复制 vibe-math-v1/ 下的 agent.cordis.yml / preset.yml / vibe-math.js
   C:\Users\<你>\.dsh\.agent-presets\vibe-math-v2\   ← 复制 vibe-math-v2/ 下的 agent.cordis.yml / preset.yml / vibe-math-v2.js
   

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

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

DSH 版本适配与依赖

• 形态依赖：两个 preset 依赖 DSH 的标准 agent-preset 机制（~/.dsh/.agent-presets/<id>/ + 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 / followup / interrupt）、agents（roots）、tools（register）、commands（register）、fs（resolve/stat/readText/writeText/listDir），可选 subprocess / sandboxPolicy。这些 API 形状随 DSH 版本演进；本项目已充分测试并确认适配 dsh-v0.1.0-rc.7（package.json 的 dsh.minVersion / testedVersion 均为 0.1.0-rc.7），低于该版本的 DSH 未验证，可能无法挂载。
• 运行时自检：安装器（bundle 插件）每次启动时对上述服务与关键 API 做能力自检（DSH 不暴露版本号，故按能力而非版本检测）；不满足时打 warning 并提示升级 DSH。preset 挂载失败时先看 DSH 日志里的自检 warning。
• 升级路径：DSH 升级后无需重装本包；升级本包用 dsh plugin update dsh-vibe-math，重启 DSH 后安装器会自动把 preset 更新到新版本（见上文「安装」说明）。

---

🧭 两个预设怎么选

💡 强烈建议优先使用 vibe-math-v2（新架构）。v2 是对 v1（经典流水线）的架构级重构：v1 的流水线设计存在一些固有缺陷（CSV 数据模型表达能力有限、验证单元拆分粒度不易控制、缺少命题知识库与概率驱动的调度依据等），而 v2 用「问题清单 + 命题知识库 + 概率驱动调度 + 独立评审→辩论→裁决」解决了这些问题，更完善、更优雅，且经多次实测与迭代（8 点需求、多会话隔离、断点续跑、人工干预均验证通过，适配 dsh-v0.1.0-rc.7）。

⚠️ vibe-math-v1 是 v2 的架构级前身，仅作参考/兼容保留，可能在将来的版本中被遗弃、不再维护。 新项目、新问题请直接使用 v2。

	vibe-math-v1（经典 · 将弃用）	vibe-math-v2（新架构 · 推荐）
定位	早期流水线架构（v2 的前身，保留兼容）	当前主推架构，更完善、更优雅
核心思想	流水线：拆方向 → 逐方向求解 → 拆最小单元 → 多验证器辩论 → 晋升 Verified/	概率驱动：qs.json 问题 + Propos/ 命题库，按「正确概率 / 价值」调度求解与验证
数据	qs/qs.csv + Progress_Logs/	qs/qs.json + Propos/<分类>_Propos.json + Reliable/
角色	brainstorm / solver / derive / verifier / decider	explorer（拆方向）→ 逐方向 solver → verifier（独立审查→辩论→裁决）
收口规则	验证通过晋升 Verified/，decider 判定解决	解法/证明达概率 1 即收口（问题 solved、命题 1/0），never 永不调度
特设能力	子问题分支（Aux_Hypothesis）	命题「价值/关键性」自动晋升问题清单；reportMode file/push/both；priorityAdjust 三种优先级策略

两者都支持：断点续跑（vibe_math_resume）、人工/自动模式切换、vibe_math_* 工具集与 /vibe 命令、按项目隔离、子代理权限调控。但建议新项目一律选 v2。

---

🧠 架构与分工（v1 · 经典）⚠️ 早期架构 · 将弃用 · 不建议新项目使用

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

角色	类型	职责
主代理	LLM（会话里的那个助手）	自然语言接口 + 汇报者 + 助手。它自己不求解、不调度，只负责：把你的话翻译成 vibe_math_* 工具调用、汇报进展、问答式配置参数、执行调控命令。
调度器	插件代码（非模型）	唯一主控：读 qs.csv、派发子代理、写文件、推进状态机。所有调度靠编程，不靠代理。
Brainstorm 子代理	子代理	元认知头脑风暴：约束分解、边界测试、相似问题映射，把问题拆成多个「大相径庭」的求解方向。
Solver 子代理	子代理	每个方向一个专属求解器，同一会话内多轮迭代，产出引理（含证明）、子路线、存活概率、完整解法。
Derive 子代理	子代理	当某问题的所有方向都走进死路仍未解决时，基于历史痛点派生 1~3 个全新方向。
Verifier 子代理	子代理	每个验证单元 ≥3 个独立「严苛审稿人」，独立审查 → 辩论（交流群）→ 裁决。
Decider 子代理	子代理	Verified/ 出现新结论时，判断它是否解决了某未解决问题，回写 qs.csv 并重命名解法文件。

一句话分工：主代理负责“和人对话”，调度器负责“干活”，子代理负责“动脑”。

---

📁 目录结构

v1（经典）

<会话工作区>/VibeMath/
├─ current.json                        # 当前项目
├─ vibe_math_setting.json             # （可选，全局回退）默认参数 JSONC，含注释
└─ Projects/<项目>/
   ├─ vibe_math_setting.json          # 该项目默认参数
   ├─ qs/qs.csv                        # 问题清单：id,description,priority,status,deps
   ├─ Verified/                        # 已验证可信知识库（绝对可信）
   ├─ Pending_Verification/            # 待验证原始输出
   ├─ Under_Verification/              # 拆解后的最小验证单元
   ├─ Temp/                            # 临时工作区
   ├─ Temp_Validated/                  # 已验证、待晋升
   ├─ Progress_Logs/                   # 每问题进度 + 辩论日志 + 定期报告
   └─ VibeMath_State/                  # 调度器私有持久状态（断点恢复用）

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/                  # 调度器私有持久状态（断点恢复用）

铁律（两版通用）：调度器是唯一文件写者（子代理只返回结构化 JSON，从不写文件）。

---

⚡ 快速上手

方式 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）
vibe_math_add_proposition / vibe_math_list_propositions（v2）	添加 / 列出命题库（id/概述/布尔估计/细类型/价值·关键性）
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	查看 / 裁决人工决策
vibe_math_list_agents / vibe_math_message_agent / vibe_math_interrupt_agent	查看 / 发消息 / 中断子代理

斜杠命令（与工具等价）：/vibe start|resume|pause|abort|status|report|mode <auto|manual>|setup|save|template [global|project]|add <id> <desc>|add-proposition <id> <概述>|list-propositions|project [list|new <name>|<name>]|decisions|agents

---

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

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/。

---

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

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