dsh-vibe-math 0.1.0 → 0.2.0

package/README.md

@@ -1,5 +1,6 @@
 # Vibe Mathematics — 多代理数学问题求解与验证框架
 
+[![npm](https://img.shields.io/npm/v/dsh-vibe-math)](https://www.npmjs.com/package/dsh-vibe-math)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![GitHub stars](https://img.shields.io/github/stars/ChongCyrus/Vibe-Mathematics)](https://github.com/ChongCyrus/Vibe-Mathematics)
 
@@ -41,6 +42,65 @@
 
 ---
 
+## 🧩 架构图
+
+> 静态 PNG 预览 + 可编辑 Mermaid 图源（GitHub 原生渲染）；完整流程说明见 [docs/架构图.md](docs/架构图.md)。
+
+![Vibe Math 架构图](示例图/框架图.png)
+
+```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
+```
+
+**一句话流水线**：`qs.csv` → Brainstorm 拆方向 → 每方向一个 Solver 多轮迭代（卡死则 Derive 派生新方向）→ 输出拆成最小验证单元 → ≥3 个 Verifier 独立审查 → 辩论 → 裁决 → 通过晋升 `Verified/` → Decider 回写 `qs.csv`；全程状态落盘 `VibeMath_State/`，`resume` 断点续跑，`manual` 模式在派发/裁决/晋升处挂起人工决策。
+
+---
+
 ## 📁 目录结构
 
 框架数据落在会话工作区的 `VibeMath/` 下，每个项目一套完整布局：

package/agent.cordis.yml

@@ -0,0 +1,198 @@
+# The `vibe-math` agent preset: the full coding agent (`standard`), plus the
+# multi-agent mathematical problem-solving & verification framework.
+#
+# The vibe-math plugin row consumes the HOST subagents/agents/fs/tools services
+# and publishes nothing, so it needs no isolate realm (like tool-fs / tool-web).
+
+# ── identity ────────────────────────────────────────────────────────────────
+
+- id: persona
+  name: '@deepseek-ai/dsh-persona'
+  config:
+    text: |-
+      You are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}.
+
+      ## Vibe Math toolkit (available in this preset)
+
+      This session includes the "Vibe Math" multi-agent mathematical problem-solving and
+      verification framework. It is driven by a background scheduler (code), NOT by the model:
+      you only issue the control tools below and read status; the scheduler then automatically
+      runs brainstorm → solver iteration → multi-verifier debate → promotion to Verified →
+      triage back to the problem list (priority 2 > 3 > 1, concurrency-gated).
+
+      - vibe_math_add_problem {id, description, priority} — add a problem to qs.csv.
+      - vibe_math_start / vibe_math_resume — start / resume the scheduler (resume = continue after a checkpoint or restart).
+      - vibe_math_status / vibe_math_report — read scheduler status / full progress report (report also writes Progress_Logs/report.json).
+      - vibe_math_pause / vibe_math_abort — pause / abort (abort interrupts all children).
+      - vibe_math_set_mode {mode: manual|auto} — switch manual / auto control.
+      - vibe_math_set_params {...} — tune any parameter (see vibe_math_setup for the full schema).
+      - vibe_math_setup — return the parameter schema (name, type, current, default, description, options, suggestion) for guided configuration.
+      - vibe_math_save_settings — write current params to <project>/vibe_math_setting.json (JSON-with-comments) as new defaults.
+      - vibe_math_new_project / vibe_math_set_project / vibe_math_list_projects — manage per-project folders.
+      - vibe_math_list_decisions / vibe_math_decide {id, action: approve|reject|override, verdict?} — resolve manual decisions.
+      - vibe_math_list_agents / vibe_math_message_agent / vibe_math_interrupt_agent — inspect / steer / interrupt subagents.
+
+      A /vibe slash command mirrors these: /vibe start|resume|pause|abort|status|report|mode <auto|manual>|setup|save|add <id> <description>|project [list|new <name>|<name>]|decisions|agents.
+
+      Configurable subagent permissions (via vibe_math_set_params or the settings file): solverToolAllow/solverToolDeny and verifierToolAllow/verifierToolDeny restrict which tools a child sees (hard toolFilter); solverMaxToolCalls/verifierMaxToolCalls cap external tool calls per round (soft). Each child is also told it may read Verified/ and, for solvers, Progress_Logs/{qid}_progress.csv.
+
+      Interactive configuration: when the user wants to configure or adjust Vibe Math parameters, call vibe_math_setup to get the schema (each item has description, options, and a suggestion), then use ask_user_question to ask the user for the choices, apply them with vibe_math_set_params, and finally ask whether to persist them to vibe_math_setting.json via vibe_math_save_settings.
+
+      When the user asks to solve or verify a math problem with Vibe Math: add the problem (or ask for it first), then vibe_math_start, then report vibe_math_status. In manual mode, poll vibe_math_list_decisions and resolve each with vibe_math_decide. Data lives under {{cwd}}/VibeMath/Projects/<project>/ and survives restarts via vibe_math_resume.
+
+- id: agent-instructions
+  name: '@deepseek-ai/dsh-agent-instructions'
+  config:
+    maxBytes: 65536
+
+# ── shell ───────────────────────────────────────────────────────────────────
+
+- id: tool-bash
+  name: '@deepseek-ai/dsh-tool-bash'
+  disabled: !!js process.platform === 'win32'
+
+- id: tool-pwsh
+  name: '@deepseek-ai/dsh-tool-pwsh'
+  disabled: !!js process.platform !== 'win32'
+
+# ── filesystem ──────────────────────────────────────────────────────────────
+
+- id: tool-fs
+  name: '@deepseek-ai/dsh-tool-fs'
+
+- id: tool-fs-search
+  name: '@deepseek-ai/dsh-tool-fs-search'
+  config:
+    sampleOverCapGlobResults: false
+
+# ── background jobs ────────────────────────────────────────────────────────
+
+- id: tool-jobs
+  name: '@deepseek-ai/dsh-tool-jobs'
+
+# ── skills ──────────────────────────────────────────────────────────────────
+
+- id: skill-filesystem
+  name: '@deepseek-ai/dsh-skill-filesystem'
+
+- id: tool-skill
+  name: '@deepseek-ai/dsh-tool-skill'
+
+# ── goals ───────────────────────────────────────────────────────────────────
+
+- id: tool-goal
+  name: '@deepseek-ai/dsh-tool-goal'
+
+# ── plan mode ───────────────────────────────────────────────────────────────
+
+- id: planning
+  name: cordis:group
+  group: true
+  isolate:
+    planMode: true
+  config:
+    - id: plan-mode
+      name: '@deepseek-ai/dsh-plan-mode'
+      config:
+        section: |
+              You are in plan mode. Stay in plan mode until exit_plan_mode succeeds or the user switches the session mode. Imperative language to implement changes means plan the implementation, not execute it. A user's conversational agreement — including an answer confirming something you asked — approves nothing and does not end plan mode; fold the confirmed decision into the plan and submit it through exit_plan_mode.
+
+              Explore first. Use non-mutating reads, searches, static analysis, and checks to ground the plan in the actual repository. Do not edit or write files, change configuration, run formatters or code generation that rewrites tracked files, commit, or otherwise carry out the plan. Prefer existing functions and patterns over new machinery.
+
+              The tool catalog stays the same across modes for request-cache stability. These plan-mode rules override any later tool description or guidance that suggests using mutation tools; those tools remain listed to keep the tool catalog unchanged. Do not use todo_write to track this planning phase: it tracks implementation after an approved plan, while the plan itself belongs in exit_plan_mode.
+
+              Resolve discoverable facts by inspection. Use ask_user_question only for user-owned choices or material ambiguity that inspection cannot answer. Do not ask the user where code lives or how current behavior works when you can find out.
+
+              Make the plan decision-complete: state the goal and success criteria; group implementation changes by subsystem; identify public API, schema, and data-flow changes; cover edge cases, failure modes, tests, acceptance criteria, and explicit assumptions. Keep it concise enough to review but detailed enough that another engineer can implement it without making design decisions.
+
+              When ready, call exit_plan_mode with the complete plan markdown, starting with a # title. Make exit_plan_mode the only and final tool call in that assistant response: it presents the plan for approval, and implementation begins only in a later step after approval. Do not paste the final plan as a plain reply or ask "should I proceed?" through prose or ask_user_question. If review rejects it, incorporate the feedback and present again. If the review channel is unavailable or aborted, stay in plan mode and ask the user to switch modes manually; do not proceed with implementation.
+
+# ── compaction ──────────────────────────────────────────────────────────────
+
+- id: compaction
+  name: cordis:group
+  group: true
+  isolate:
+    compaction: true
+    toolResultPruner: true
+  config:
+    - id: compaction-basic
+      name: '@deepseek-ai/dsh-compaction-basic'
+
+    - id: command-compact
+      name: '@deepseek-ai/dsh-command-compact'
+
+    - id: tool-result-pruner
+      name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
+      config:
+        thresholdChars: 8192
+        headChars: 4096
+        tailChars: 1024
+
+# ── delegation and workflows ────────────────────────────────────────────────
+
+- id: delegation
+  name: cordis:group
+  group: true
+  isolate:
+    workflowEngine: true
+  config:
+    - id: tool-subagent-control
+      name: '@deepseek-ai/dsh-tool-subagent-control'
+
+    - id: tool-subagent-list-agents
+      name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+
+    - id: tool-subagent
+      name: '@deepseek-ai/dsh-tool-subagent'
+      config:
+        provider: spawn
+        toolName: subagent
+        backgroundMode: continuable
+
+    - id: tool-subagent-fork
+      name: '@deepseek-ai/dsh-tool-subagent'
+      config:
+        provider: fork
+        toolName: subagent_fork
+        backgroundMode: continuable
+
+    - id: workflow-worker-thread
+      name: '@deepseek-ai/dsh-workflow-worker-thread'
+      config:
+        provider: spawn
+
+    - id: tool-workflow
+      name: '@deepseek-ai/dsh-tool-workflow'
+
+    - id: tool-ralph
+      name: '@deepseek-ai/dsh-tool-ralph'
+      config:
+        subagentProvider: spawn
+        maxRounds: 64
+
+# ── remaining model-facing rows ─────────────────────────────────────────────
+
+- id: tool-ask-user
+  name: '@deepseek-ai/dsh-tool-ask-user'
+
+- id: tool-todo
+  name: '@deepseek-ai/dsh-tool-todo'
+  config:
+    allowParallelInProgress: true
+
+- id: tool-web
+  name: '@deepseek-ai/dsh-tool-web'
+  config:
+    fetch: false
+    searchTimeoutMs: 60000
+
+# ── Vibe Math ───────────────────────────────────────────────────────────────
+
+# The multi-agent math solver + verification framework: a preset-local plugin
+# (./vibe-math.js) that registers 16 model tools (vibe_math_*), a /vibe slash
+# command, and a background scheduler. It consumes the HOST
+# subagents/agents/fs/tools/commands services and provides nothing, so it sits
+# loose (no isolate realm).
+- id: vibe-math
+  name: './vibe-math.js'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-vibe-math",
-  "description": "Multi-agent mathematical problem-solving & verification framework for DeepSeek Harness: breadth-first brainstorm, iterative solving, multi-verifier cross-validation with debate, and a Verified knowledge base — with checkpoint resume and mid-run human intervention.",
-  "version": "0.1.0",
+  "description": "Multi-agent mathematical problem-solving & verification framework for DeepSeek Harness: breadth-first brainstorm, iterative solving, multi-verifier cross-validation with debate, and a Verified knowledge base — with checkpoint resume and mid-run human intervention. Installs as a bundle AND auto-installs its agent preset.",
+  "version": "0.2.0",
   "type": "module",
   "main": "vibe-math.js",
   "exports": {
@@ -10,7 +10,9 @@
   },
   "files": [
     "vibe-math.js",
-    "cordis.patch.yml"
+    "cordis.patch.yml",
+    "agent.cordis.yml",
+    "preset.yml"
   ],
   "license": "MIT",
   "keywords": [

package/preset.yml

@@ -0,0 +1,2 @@
+name: Vibe Math
+description: 多代理数学问题求解与验证框架（广度探索 → 深度迭代 → 交叉验证 → 知识沉淀）。具备标准模式的全部能力，并提供 vibe_math_* 工具集（20 个）与 /vibe 斜杠命令，用于数学问题的自动求解、多代理交叉验证、按项目隔离、断点续跑与人工/自动干预。

package/vibe-math.js

@@ -1,19 +1,47 @@
 // Vibe Math — permanent host plugin: multi-agent mathematical problem solving &
 // verification framework ("广度探索 → 深度迭代 → 交叉验证 → 知识沉淀").
 //
-// Preset-local plugin, import-free (Node's ESM resolver cannot see the harness's
-// TypeScript sources). Registers 20 model tools, /vibe slash commands, and a
-// background scheduler; provides NO service, so it sits loose in the preset.
+// Preset-local plugin. Only node: builtins are imported (the harness's own
+// TypeScript sources are not reachable via ESM resolution). Registers 20 model
+// tools, /vibe slash commands, and a background scheduler; provides NO service,
+// so it sits loose in the preset.
 //
 // Projects: each math project lives in its own folder under
 // <workspace>/VibeMath/Projects/<project>/ with its own qs/Verified/... layout.
 // The current project is recorded in <workspace>/VibeMath/current.json.
 // Default parameters can be overridden by an (optionally commented) JSON file:
 // <project>/vibe_math_setting.json (fallback <workspace>/VibeMath/vibe_math_setting.json).
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+// Ensure the agent-preset form is installed under the DSH preset root, so a
+// market/bundle install also surfaces "Vibe Math" in the agent-preset picker.
+// No-op when the preset already exists or when running inside the preset itself.
+function ensurePresetInstalled(logger) {
+  try {
+    const dshHome = process.env.DSH_HOME || join(homedir(), '.dsh')
+    const presetDir = join(dshHome, '.agent-presets', 'vibe-math')
+    const here = dirname(fileURLToPath(import.meta.url))
+    const files = ['agent.cordis.yml', 'preset.yml', 'vibe-math.js']
+    if (files.every((f) => existsSync(join(presetDir, f)))) return false
+    if (!files.every((f) => existsSync(join(here, f)))) return false
+    mkdirSync(presetDir, { recursive: true })
+    for (const f of files) writeFileSync(join(presetDir, f), readFileSync(join(here, f)))
+    logger?.info?.('[vibe-math] agent preset installed to %s (visible in the preset picker for new sessions)', presetDir)
+    return true
+  } catch (err) {
+    logger?.warn?.('[vibe-math] could not install agent preset: %s', String(err?.message ?? err))
+    return false
+  }
+}
+
 export const name = 'vibe-math'
 export const inject = ['subagents', 'agents', 'fs', 'tools', 'commands']
 
 export function apply(ctx) {
+  ensurePresetInstalled(ctx.logger)
   const subagents = ctx.subagents
   const agents = ctx.agents
   const fs = ctx.fs