dsh-vibe-math 2.3.14 → 2.3.15
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +873 -0
- package/README.md +2 -0
- package/docs/AUDIT-CHECKLIST.md +43 -1
- package/docs/generate_framework_diagram_v4.mjs +7 -2
- package/docs/generate_framework_diagram_v5.mjs +7 -2
- package/docs/release-notes/RELEASE-NOTES-2.3.15.md +137 -0
- package/docs/render_framework_diagram_png.mjs +273 -0
- package/docs/test-timing.md +4 -2
- package/package.json +6 -2
package/README.en.md
ADDED
|
@@ -0,0 +1,873 @@
|
|
|
1
|
+
# Vibe Mathematics — Multi-Agent Mathematical Problem Solving and Verification Framework (Four Architectures)
|
|
2
|
+
|
|
3
|
+
English | [中文](README.md)
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/dsh-vibe-math)
|
|
6
|
+
[](https://opensource.org/licenses/MIT)
|
|
7
|
+
[](https://github.com/ChongCyrus/Vibe-Mathematics)
|
|
8
|
+
|
|
9
|
+
> A set of **agent presets** running inside **DeepSeek Harness** (`vibe-math-v2` / `vibe-math-v3` / `vibe-math-v4` / `vibe-math-v5`),
|
|
10
|
+
> which use multi-agent collaboration to automatically solve mathematical problems and perform multi-agent cross-verification of the conclusions. All four presets share the foundational capabilities of "**checkpoint resume**,
|
|
11
|
+
> **mid-run manual intervention**, **progress reporting**, and **natural-language driving**", but adopt four generations of different solving architectures:
|
|
12
|
+
> **💡 `vibe-math-v2` and `vibe-math-v3` are recommended at the same level** — both are mature, usable, actively maintained recommended architectures; choose according to your actual needs (see "How to choose" below); `vibe-math-v4` is the "resident self-organizing collaborative research" architecture, and `vibe-math-v5` is the latest "institute system" (both are experimental).
|
|
13
|
+
>
|
|
14
|
+
> - **`vibe-math-v2` (probability-driven · JSON data layer) ✅ Recommended**: `qs.json` problem list + `Propos/` proposition library + probability-driven scheduling + code heuristic scheduling;
|
|
15
|
+
> - **`vibe-math-v3` (third generation · paper-style md + planner agent + method library) ✅ Recommended**: all knowledge is stored and extended in **Markdown paper/research-report form** (`Problems/` problem list + dependencies + source motivation, `Progress/` research log, `Propos/` proposition library, `Methods/` general theory invention library, `Verified/` absolutely trustworthy); before scheduling, the **planner agent** autonomously draws up a plan for the next N steps; theories/frameworks/tools/methods/ideas invented during solving are distilled by the **Method Keeper** into a reusable method system (as in inventing group theory or functional analysis).
|
|
16
|
+
> - **`vibe-math-v4` (fourth generation · resident self-organizing collaborative research) 🧪 Experimental**: a group of **persistent resident subagents** **leave messages for one another + hold meetings**, and autonomously decide all task arrangements (no central scheduler); each accumulates its own progress/proposition/method/subproblem libraries and consults the others; verification is written to `Verified/` **only when all residents agree (true or false)**, otherwise it remains in the library with a probability attached; when the context reaches a threshold it automatically `/compact`s; it stops only when all agree that the original problem has been solved.
|
|
17
|
+
> - **`vibe-math-v5` (fifth generation · institute system) 🧪 Experimental · Latest**: upgrades the residents into an **institute** — **academicians** (leaders / the organizing and coordinating center, responsible for decomposition and **assignment**, setting priorities, chairing meetings, and supervising progress) + **resident researchers** (with voting rights, able to autonomously hire/fire their own temp workers) + **temp workers** (no voting rights); it has a **public charter**, **group chat and meetings**, a **compare-and-set task board**, and **real firing**; a boolean agreement of **≥ m votes** is required to write to `Verified/` (opposing votes block, abstentions are not counted, and if the threshold is not met it remains in the library with an average probability attached); state is stored in **host-only projection units of the session log**, at zero token cost.
|
|
18
|
+
|
|
19
|
+
After installing this plugin package (or manually copying the presets), **four** agent presets appear in DSH's preset selector.
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## 🧩 Architecture Diagrams (v2 + v3 + v4 + v5)
|
|
24
|
+
|
|
25
|
+
> Static architecture diagrams; for the complete process description see [docs/架构图.md](docs/架构图.md) (v2 in detail) and
|
|
26
|
+
> [vibe-math-v5/架构图.md](vibe-math-v5/架构图.md) (the full set of v5 detail diagrams);
|
|
27
|
+
> editable generation scripts: [v2](docs/generate_framework_diagram_v2.py) / [v3](docs/generate_framework_diagram_v3.py) (matplotlib → PNG),
|
|
28
|
+
> [v4](docs/generate_framework_diagram_v4.mjs) / [v5](docs/generate_framework_diagram_v5.mjs)
|
|
29
|
+
> (zero-dependency Node → **SVG**, `node docs/generate_framework_diagram_v4.mjs`).
|
|
30
|
+
> SVG is used from v4 onward: plain text, diff-friendly, crisp at any zoom; when PNG is needed, screenshot with a headless browser (the command is at the top of the generation script).
|
|
31
|
+
|
|
32
|
+
### Vibe Math V2 (probability-driven · JSON data layer) ✅ Recommended
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
**One-sentence pipeline**: `qs.json` takes problems by priority → Explorer splits out directions (if all are dead ends, re-derive) → one Solver per direction iterates over multiple rounds (lemmas go into `Propos/`, solutions go back to `qs.json`, all probabilities <1) → the scheduler picks r (proposition / proposition+proof·disproof / problem+solution) and dispatches ≥3 verifiers for independent review → debate → ruling → at probability=1 it automatically closes out (problem solved, proposition 1/0, priority set to `never`); state is written to disk throughout, `resume` continues from the checkpoint, and `reportMode` can report by file/push/both.
|
|
37
|
+
|
|
38
|
+
### Vibe Math V3 (paper-style md + planner agent + methods library) ✅ Recommended
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
**One-sentence pipeline**: all knowledge is stored and continued as **Markdown papers/research reports** (`Problems/` problem list including dependencies and the source motivation of follow-up problems, `Progress/` research log continued by direction and by round, `Propos/` proposition library, `Methods/` general theory invention library, `Verified/` absolutely trustworthy) → before scheduling, the scheduler builds a state brief and calls the **planner agent**; the planner agent lays out the next N steps in one go (spawn solver/verifier/explorer/method-keeper, interrupt, promote, wait), which are executed after code validation (actions exceeding the concurrency limit are queued and consumed across ticks; a planning failure automatically falls back to the v2-style heuristic) → verifiers review independently → debate → **near-consensus ruling** (if on the same side and the mean is ≥0.85/≤0.15, take the mean, fixing v2's flat misjudgment) → at probability=1 it closes out and generates a `Verified/` card → the solver's `methods_used`/`new_inventions` reports are distilled/refined into the methods library by the **Method Keeper** (which can form system hierarchies and be reused across projects).
|
|
43
|
+
|
|
44
|
+
### Vibe Math V4 (resident self-organizing collaborative research) 🧪 Experimental
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
> The SVG above is generated by a zero-dependency script: `node docs/generate_framework_diagram_v4.mjs` (pure Node, no Python/matplotlib dependency;
|
|
49
|
+
> generation estimates text width, and any line overflowing its container raises a warning and exits with code 1).
|
|
50
|
+
|
|
51
|
+
**One-sentence pipeline**: initially N **resident subagents** are created (continuable, persistent context) which first brainstorm on their own and produce initial insights/directions → after that **all task arrangements are decided autonomously by them leaving messages for each other + holding collective meetings** (the framework only provides the message bus/meetings/task board/artifact persistence, and **never assigns tasks**); each resident persists valuable artifacts into **its own** `Progress/<id>/`, `Propos/<id>/`, `Methods/<id>/`, `Subproblems/<id>/` libraries according to **degree of value / planned motivation and use / its own probability estimate**, and they **can read each other's**; verification is initiated by **their own deliberation**, and only when **all residents agree (true or false)** is it written to `Verified/`, otherwise it stays in the library with a probability attached; when a resident's context reaches a threshold (66% by default) it automatically `/compact`s; they stop **only when all of them agree that the original problem is solved**; residents can be manually intervened with/added/shut down at any time, and checkpoint resume is supported.
|
|
52
|
+
|
|
53
|
+
> Note: V4 removes v3's central planner and deterministic roles (explorer/solver/verifier/planner/method-keeper) and makes the "researcher" itself the subject. See `vibe-math-v4/实现方案.md` for details.
|
|
54
|
+
> Keep-alive mechanism (tiered keep-alive A+B + deadlock watchdog): a gang idle for longer than `activityTimeoutMs` receives a **self-driven** CHECKPOINT (suggesting it continue solving/send a message/propose a task, rather than "do you want to stop"), and it **fills in parallel** — branch A fills as much of the `maxParallel` concurrency budget as possible in one go (waking several idle residents at the same moment, rather than the serial "wake only r1, then r2 after it finishes"), and mailbox delivery also reaches several idle recipients in parallel; a failed wake automatically re-arms the heartbeat; if the team is idle and has **no new artifacts** for longer than `stallAutoMeetingMs` (6 minutes by default), the framework automatically convenes a synchronous meeting so the residents can decide the next step themselves; if a **meeting/verification hangs** (still no new speech/votes after more than 2×`activityTimeoutMs`), the framework automatically **abandons that meeting/verification** and returns to normal self-organization, so that one broken meeting does not permanently block the whole team; **meetings do not preempt verification** — meeting requests while verification is under way are held and convened afterwards (keeping the consensus-consistent "truth-seeking" step from being interrupted by coordination discussion) — the framework always only facilitates and never assigns tasks.
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
### Vibe Math V5 (institute system) 🧪 Experimental · Latest
|
|
59
|
+
|
|
60
|
+
**One-sentence positioning**: upgrade v4's "a group of residents messaging each other" into an **institute** — with three classes of staff: **academician** (leader), **resident researcher**, and **temp worker**; with the institute's **public charter**; with **group chat and meetings**; with **autonomous hiring/firing**; and where
|
|
61
|
+
**any conclusion must be given a Boolean probability of 1 or 0 unanimously by at least m voting members before it can be written to `Verified/`**.
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
> Image sources and all detail diagrams (member lifecycle, one-round sequence, consensus state machine, meeting flow, scheduling priority, state folding,
|
|
66
|
+
> prompt composition, task board, authority matrix): [`vibe-math-v5/架构图.md`](vibe-math-v5/架构图.md).
|
|
67
|
+
> The SVG above is generated by a zero-dependency script: `node docs/generate_framework_diagram_v5.mjs`.
|
|
68
|
+
|
|
69
|
+
```mermaid
|
|
70
|
+
flowchart TB
|
|
71
|
+
OFF["👤 Institute office (session root agent / human)<br/>does not research · does not vote · only reports and relays instructions"]
|
|
72
|
+
subgraph INST["🏛️ Institute (internal autonomy: roster, organization and assignment all happen among members)"]
|
|
73
|
+
ACAD["Academician acad —— leader / center of organization and coordination<br/>L1 institute-wide overview · L2 assignment · L3 priority<br/>L4 chairs meetings · L5 supervision · L6 moving people · L7 external"]
|
|
74
|
+
RES["Resident researcher r-n<br/>has voting rights · may autonomously hire/fire its own temp workers"]
|
|
75
|
+
TMP["Temp worker t-n<br/>no voting rights · hired temporarily for a specific task"]
|
|
76
|
+
end
|
|
77
|
+
subgraph FW["⚙️ Framework vibe-v5 —— only a medium (middleware), never assigns tasks"]
|
|
78
|
+
M["Message relay · meetings/debates · task board CAS+DAG<br/>m-vote consensus verification · context and liveness · roster and hiring · scheduler"]
|
|
79
|
+
end
|
|
80
|
+
PROJ["💾 host-only session log projection cell (key vibeMathV5)<br/>11 kinds of events · pure fold applyV5Event · DSH handles checkpoint/restore"]
|
|
81
|
+
FS["📁 Members/<id>/* · Shared/* · Verified/ · Problems/"]
|
|
82
|
+
RULE{{"Truth gate: Boolean unanimity and Boolean votes ≥ m = min(quorumCap, number of registered voting members)"}}
|
|
83
|
+
OFF <-->|"vibe_v5_* / /v5 commands ↔ status / report"| M
|
|
84
|
+
M <-->|"per-round prompt ↔ single JSON receipt"| ACAD
|
|
85
|
+
M <-->|"per-round prompt ↔ single JSON receipt"| RES
|
|
86
|
+
M <-->|"per-round prompt ↔ single JSON receipt"| TMP
|
|
87
|
+
ACAD -.->|"assign / supervise / chair meetings (in-institute organization, not framework behavior)"| RES
|
|
88
|
+
ACAD -.-> TMP
|
|
89
|
+
M <--> PROJ
|
|
90
|
+
M <--> FS
|
|
91
|
+
M --> RULE
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
#### Positions and Authority
|
|
95
|
+
|
|
96
|
+
| Position | Codename | Voting right | Authority |
|
|
97
|
+
|---|---|---|---|
|
|
98
|
+
| **Academician** (leader) | `acad` | ✅ one vote, **of equal weight with others** | **Center of organization and coordination**: build an institute-wide overview (`overview`), decompose the original problem into tasks and **assign** them (`assign`), set priorities (`prioritize`), convene and chair meetings (`convene`), supervise progress (`nudge`), move temp workers around, report outward. **Cannot unilaterally conclude**, and cannot expand the roster on its own. |
|
|
99
|
+
| **Resident researcher** | `r-<n>` | ✅ one vote | Digs deep in its own direction; **may autonomously hire/fire its own temp workers**; reports progress to the academician and accepts its organization and assignments (**has the right of reasoned objection**). |
|
|
100
|
+
| **Temp worker** | `t-<n>` | ❌ | Hired temporarily for a specific task: can read/think/speak/write its own output library/claim or be assigned tasks; fired by its **employer or the academician**. Codenames are never reused. |
|
|
101
|
+
| **Institute office** (main assistant) | —— | ❌ | **Does not take part in research and does not vote.** Only reports, translates the human's words into tool calls, and holds on the human's behalf the creation rights the platform requires (creating an institute / adding resident researchers). |
|
|
102
|
+
|
|
103
|
+
**Division of labor in one sentence**: **organization is the academician's responsibility, but judgment belongs to each person individually** —— what the academician assigns is **work**, not **conclusions**.
|
|
104
|
+
|
|
105
|
+
#### Truth Rules (the core of V5)
|
|
106
|
+
|
|
107
|
+
For an object to enter `Verified/` it must **simultaneously** satisfy:
|
|
108
|
+
|
|
109
|
+
1. At least **m = min(`quorumCap`, number of registered voting members)** voting members cast a **Boolean probability value**;
|
|
110
|
+
2. These votes are **all** `1` (absolutely true) or **all** `0` (absolutely false).
|
|
111
|
+
|
|
112
|
+
A vote is a numeric value in `[0,1]`: **strictly between 0 and 1 = abstention/doubt** (not counted toward m, but counted in the group's average probability).
|
|
113
|
+
**Any single opposing Boolean vote blocks a conclusion** —— the minority cannot push a conclusion through by having others abstain.
|
|
114
|
+
An object that falls short of the threshold **stays in its original library**, with the group's average probability and the complete debate record attached, and is **not forcibly ruled on**.
|
|
115
|
+
|
|
116
|
+
Voting has two stages: first [independent initial assessment] (mutually invisible), and if undecided, then [open debate] followed by a re-vote, with a round cap of `verdictMaxRounds`.
|
|
117
|
+
`quorumMode: "all-unanimous"` switches back to v4's "all-unanimous" standard.
|
|
118
|
+
|
|
119
|
+
#### Operating Mechanisms
|
|
120
|
+
|
|
121
|
+
- **Communication**: group chat (fanned out to every other member), direct message, votes cast only to members with voting rights; messages are **persisted per recipient**,
|
|
122
|
+
written to disk before delivery, and group chat is batched into digests by `chatDigestMs` / `chatDigestMax` (direct messages/meetings/votes are not batched).
|
|
123
|
+
All in-institute communication goes through the framework relay (DSH's adjacency restriction does not allow members to message each other directly), but **the signature is always the real sender**.
|
|
124
|
+
- **Meetings and verification are mutually exclusive** (in both directions): meeting requests while verification is under way are **held**; verification requested while a meeting is under way is **queued** ——
|
|
125
|
+
the two consensus processes never run at the same time, avoiding mutual starvation of the watchdog clocks. Meetings collect opinions one by one in a **random speaking order**,
|
|
126
|
+
and at closing they aggregate the votes and check whether everyone considers the problem solved.
|
|
127
|
+
- **Task board**: compare-and-set (the latest `expected_revision` must be read before a change) + dependency DAG (all dependencies must be complete before claiming;
|
|
128
|
+
cycle detection rejects bad dependencies) + write-scope overlap warnings; when an owner is fired, its tasks are automatically reclaimed.
|
|
129
|
+
- **Hiring / firing**: both academicians and resident researchers can hire **their own** temp workers, with a dual quota per member (`maxTempPerMember`) and institute-wide
|
|
130
|
+
(`maxTempTotal`); firing is **real** —— it cancels in-flight turns, releases the resident sub-session, reclaims tasks, and discards undelivered mail.
|
|
131
|
+
- **Liveness**: the main drive is a **one-shot activity wait** (`vibe_v5_wait`, no polling); the scheduler advances by priority
|
|
132
|
+
(in-progress meetings/verification → queued verification → held meetings → active tasks → urgent mail → group chat digest → auto-meeting on stall → fallback heartbeat),
|
|
133
|
+
and concurrency is gated by `maxParallel`; the task board's "nudge" is **throttled** by `activityTimeoutMs`.
|
|
134
|
+
- **Watchdog**: if a meeting/verification goes beyond 2×`activityTimeoutMs` with no new speech/new votes → abandon it and return to self-organization;
|
|
135
|
+
the heartbeat is **re-armed after every wake**, so the scheduler never freezes permanently.
|
|
136
|
+
- **Context**: upon reaching `compactThreshold` (%) or accumulating `compactAfterRounds` rounds, members are asked to condense their working state into
|
|
137
|
+
`Progress/`; **the charter lives in the persona**, remains in effect after compaction, and does not need to be restated every round.
|
|
138
|
+
- **Stopping**: the problem is concluded (**writing `Problems/conclusion.md`**) **only when all voting members consider the original problem solved**.
|
|
139
|
+
|
|
140
|
+
#### State and Persistence
|
|
141
|
+
|
|
142
|
+
Institute state lives in a **host-only projection cell of the session log** (key `vibeMathV5`): the framework's only side effect is appending 11 kinds of events to the
|
|
143
|
+
session log, from which `applyV5Event` purely folds out the state. Therefore
|
|
144
|
+
|
|
145
|
+
- **Zero token cost**: these events **do not enter the model context** and do not consume members' conversation budget;
|
|
146
|
+
- **Recovery takes the same code path**: both cross-process restarts and resume after an in-process abort are covered by DSH's checkpoint/restore;
|
|
147
|
+
- the whole class of problems caused by v4's direct writes to `State/*.json` — "corrupted silent overwrite / concurrent lost writes / stale cross-process snapshots" — is eliminated by construction.
|
|
148
|
+
|
|
149
|
+
If the host has no `sessionProjections` service, v5 automatically falls back to hardened JSON (`State/<研究所>.v5state.json`, the same fold,
|
|
150
|
+
serial writes, and a mandatory load before read), and the installer's startup self-check reports this degradation. Files outside the projection (member output libraries, group chat, meeting minutes,
|
|
151
|
+
debate records, roster mirror, task board mirror) are all **human-readable artifacts**, and breaking them by hand does not damage the institute.
|
|
152
|
+
|
|
153
|
+
#### How the Prompt Is Composed
|
|
154
|
+
|
|
155
|
+
A member's "persona" carries the **ten-section public charter** (roster and colleagues, general rules, knowledge base and progress format,
|
|
156
|
+
organization and coordination, voting rules, per-round rhythm, hiring and firing, task board, context discipline, stopping conditions), which is **frozen at onboarding** and persists with the session;
|
|
157
|
+
each round's prompt carries only a short **state block** (who I am / the round / m / the registered roster / my tasks / newly arrived messages), **this round's question**,
|
|
158
|
+
and the **receipt contract**. Every field in the receipt contract that the framework actually handles appears, trimmed by position
|
|
159
|
+
(temp workers have no `verdict`/`hire`/`fire`; non-academicians have no `assign`/`prioritize`/`nudge`/`convene_meeting`).
|
|
160
|
+
|
|
161
|
+
The framework treats "the text a member reads" as a product to be guaranteed: identity is **passed explicitly and never guessed**; a member is **written to the roster first, and only then** are its onboarding
|
|
162
|
+
prompts constructed; the charter snapshot is frozen at onboarding, and a session rebuild is framed as `【会话重建】` rather than "just onboarded"; no academician narrative appears when there is no academician;
|
|
163
|
+
message headers are labeled by **true origin** (institute office assignment ≠ academician assignment; supervision ≠ assignment); framework feedback has its own sender,
|
|
164
|
+
and **only one message is delivered per prompt**.
|
|
165
|
+
|
|
166
|
+
#### Directory Structure (Institute)
|
|
167
|
+
|
|
168
|
+
```
|
|
169
|
+
<会话工作区>/VibeMath/Projects/<项目>/Institutes/<研究所>/
|
|
170
|
+
├─ Institutes.md # roster mirror (human-readable snapshot, do not edit by hand)
|
|
171
|
+
├─ Problems/<id>.md # original problem
|
|
172
|
+
├─ Problems/conclusion.md # conclusion record
|
|
173
|
+
├─ Members/<代号>/
|
|
174
|
+
│ ├─ Progress/progress.md # research log (the main basis for restoring state after compaction)
|
|
175
|
+
│ ├─ Propos/<id>.md # proposition
|
|
176
|
+
│ ├─ Methods/<id>.md # method / theory / tool
|
|
177
|
+
│ └─ Subproblems/<id>.md # subproblem
|
|
178
|
+
├─ Shared/
|
|
179
|
+
│ ├─ Chat/<date>.md # group chat log
|
|
180
|
+
│ ├─ Meetings/<mt-id>.md # meeting minutes (including the voting section)
|
|
181
|
+
│ ├─ Debates/<object>.md # debate record (each round's votes and reasons + average probability)
|
|
182
|
+
│ ├─ TaskBoard.md # task board mirror
|
|
183
|
+
│ └─ State-of-institute.md # snapshot of members' judgment on "whether it is solved"
|
|
184
|
+
├─ Verified/<type>/<id>.md # conclusion (read-only; only this can be treated as established)
|
|
185
|
+
└─ State/README.md # explains that "the authoritative state is in the session log projection, not here"
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
#### Tool Surface
|
|
189
|
+
|
|
190
|
+
| Who | Tools |
|
|
191
|
+
|---|---|
|
|
192
|
+
| **Institute office / human** | `vibe_v5_configure` (configure first) → `vibe_v5_start` (start work); `vibe_v5_resume` / `pause` / `stop`; `vibe_v5_set` (adjust parameters, effective immediately); `vibe_v5_status` / `report` / `members`; `vibe_v5_message` / `meeting`; `vibe_v5_hire` / `fire` / `add_researcher` / `remove_researcher`; slash command `/v5` |
|
|
193
|
+
| **All members** | `vibe_v5_say` (group chat/direct message/to all voters), `vibe_v5_wait` (poll-free wait), `vibe_v5_record_progress`, `vibe_v5_record_proposition` / `_method` / `_subproblem`, `vibe_v5_read_library` (cross-read others' libraries, read-only), `vibe_v5_propose_verify`, `vibe_v5_verdict`, `vibe_v5_task_create` / `_list` / `_get` / `_update`, `vibe_v5_meeting` (propose) |
|
|
194
|
+
| **Academician** (also has the `academicianLeads` switch) | `vibe_v5_overview` (institute-wide overview), `vibe_v5_assign` (assignment, must state the reason and acceptance criteria), `vibe_v5_prioritize`, `vibe_v5_nudge` |
|
|
195
|
+
|
|
196
|
+
#### Key Differences from v4
|
|
197
|
+
|
|
198
|
+
- **There is a leader**: v4 has no central scheduling and everything emerges from discussion; v5 has an academician responsible for organization and assignment **inside the institute**
|
|
199
|
+
(**the framework still never assigns** —— the assigner is the academician, who is likewise bound by the m votes).
|
|
200
|
+
- **The truth gate changes from "all-unanimous" to "≥ m unanimous"** (switchable back to the v4 standard).
|
|
201
|
+
- **State is stored in the session log's host-only projection cell**, with DSH responsible for checkpoint/recovery (see above).
|
|
202
|
+
- **Three classes of positions + hireable temp workers**: the roster is mutable, and hiring/firing are real reversible operations.
|
|
203
|
+
- **No npm experimental package is introduced**: v5 is a single `.js` file within the preset, with zero dependencies.
|
|
204
|
+
- **Meetings and verification are strictly mutually exclusive** (queued in both directions).
|
|
205
|
+
|
|
206
|
+
See [`vibe-math-v5/实现方案.md`](vibe-math-v5/实现方案.md) (written specification) and
|
|
207
|
+
[`vibe-math-v5/架构图.md`](vibe-math-v5/架构图.md) (all detail diagrams).
|
|
208
|
+
|
|
209
|
+
---
|
|
210
|
+
|
|
211
|
+
## ✨ Features
|
|
212
|
+
|
|
213
|
+
- **Multi-agent automatic solving**: the main agent hands the problem to the scheduler, which dispatches explorer / solver / verifier (v2/v3) plus subagents such as **planner (planning agent, v3)** and **method-keeper (method organizing agent, v3)** to solve collaboratively; **you do not need to operate node by node by hand**.
|
|
214
|
+
- **Multi-agent cross-validation**: every conclusion goes to ≥3 "strict reviewers" for **independent review → debate (exchange group) → adjudication** (v3 defaults to **near-consensus adjudication**: if on the same side and the mean is ≥0.85/≤0.15, take the mean, so that "0.9 vs 1" is not misjudged as 0.5).
|
|
215
|
+
- **Paper-style Markdown knowledge base (v3)**: the problem list (including dependencies between problems, and the causes and plans of descendant problems), research log, propositions, and method library are all written and continued in md paper/research-report style (when a direction is re-derived, the logs of the old direction are automatically archived and kept); **only `Verified/` and the objects that a verifier judged true/false are absolutely trustworthy**, and all other md (including unverified assertions in the method library) serve only as empirical reference.
|
|
216
|
+
- **General theory invention library (v3)**: the theory systems/frameworks/tools/methods/ideas invented during solving (including empirical summaries) are reported via `methods_used`/`new_inventions`, and the **Method Keeper** consolidates them into `Methods/` method cards (which can form a hierarchy of systems and be reused across projects), forming a systematic method–theory system just like "inventing group theory while solving equations".
|
|
217
|
+
- **Planner-agent scheduling (v3)**: before scheduling, the planner agent is invoked to autonomously choose the optimal scheduling scheme according to the actual situation (problem dependencies / survival rate / verifiable objects / concurrency budget / results of the last plan), **arranging the tasks of each agent for the next N steps in one go**; if planning fails, it automatically falls back to heuristics.
|
|
218
|
+
- **Knowledge accumulation**: conclusions that pass verification are promoted into the `Verified/` trustworthy knowledge base (v2/v3 additionally have the `Propos/` proposition library) for reuse by later directions.
|
|
219
|
+
- **Checkpoint resume**: the scheduling state, task stack, agent registry, decision queue, verifier historical accuracy, etc. are all written to disk; after a restart, `resume` restores them (v2/v3 use a process epoch to distinguish "pause → resume within the same process" from "restart across processes"; v3's md is itself the narrative breakpoint).
|
|
220
|
+
- **Mid-run manual intervention (and continue)**: the `auto / manual` modes can be switched at any time; in manual mode, a decision is suspended at key nodes and waits for your approve/reject/override (v3 adds a **plan approval gate** and a **method promotion gate**); you can send a message to / interrupt any subagent.
|
|
221
|
+
- **Per-project isolation**: each mathematical problem is an independent project folder, with no interference between them, and you can switch at any time.
|
|
222
|
+
- **Multi-session parallel isolation**: a DSH agent preset is a standing mount (all sessions of the same preset share one plugin instance), and inside the plugin all running state is isolated by **root session id** — two sessions can each run a project at the same time, their respective subagents are correctly attached under their own session, and the scheduler / parameters / decision queue / current project do not interfere with each other (v3 additionally has a **project lock**, so the same project is scheduled by only one session at a time). The current project is persisted per session (`VibeMath/current.<session id>.json`).
|
|
223
|
+
- **Adjustable subagent permissions**: you can restrict the tools a subagent is allowed/forbidden to use and the per-round cap on external tool calls, and explicitly tell it that it may read `Verified/`, `Propos/`, `Methods/`, `Reliable/` and the progress log.
|
|
224
|
+
- **Configurable**: `vibe_math_setting.json` (with comments) for customizing default parameters; `/vibe setup` for interactive question-and-answer configuration.
|
|
225
|
+
- **Natural-language control**: the main agent acts as "assistant + reporter" — you state your needs in plain words, and it calls the tools, reports progress, and configures parameters on its own.
|
|
226
|
+
|
|
227
|
+
**Specific to v4 / v5**:
|
|
228
|
+
|
|
229
|
+
- **Persistent self-organization (v4)**: at the start, N **persistent resident subagents** are created, after which **all task arrangements are decided by those subagents themselves through leaving messages for each other + holding meetings** (the framework only provides the message bus/meetings/task board, and never assigns tasks).
|
|
230
|
+
- **Institute system (v5)**: on top of v4's self-organization, it introduces the **organizational form of a real research institute** — the **academician** (leader) is responsible for decomposition, **assignment**, prioritization, chairing meetings, and supervising progress; **resident researchers** have voting rights and can **autonomously hire/fire their own temp workers**; **temp workers** have no voting rights; all organizational actions are performed by **members of the institute**, and the framework still only acts as the medium. See the [Vibe Math V5](#vibe-math-v5-institute-system--experimental--latest) section above for details.
|
|
231
|
+
- **Adjustable quorum (v5)**: for an object to enter `Verified/`, **≥ m = min(`quorumCap`, number of enrolled voters)** voters must cast a **consistent boolean vote** (all `1` or all `0`); **an opposing vote blocks**, and **abstentions do not count as votes but do count toward the average probability**; if the threshold is not reached, the object is **kept in the library with the average probability and the complete debate record**, without forcing an adjudication.
|
|
232
|
+
- **Zero-token-cost state persistence (v5)**: the institute state is stored in a **host-only projection unit of the session log** and does not enter the model context; cross-process and same-process recovery go through the same code path.
|
|
233
|
+
- **Genuinely reversible roster (v5)**: hiring creates a resident child session; firing cancels in-flight turns, releases the child session, reclaims its tasks, and discards undelivered mail; a codename is never reused.
|
|
234
|
+
- **Human-readable mirror (v4/v5)**: the roster table, task board, meeting minutes, debate records, and closing records are all written to disk as Markdown and are readable by humans at any time; but **the authoritative state is not in these files** (in v5 it is in the projection unit), so manually corrupting them will not break the institute.
|
|
235
|
+
|
|
236
|
+
---
|
|
237
|
+
|
|
238
|
+
## 🧮 Lean formal verification (shared by the four architectures, adjustable switch)
|
|
239
|
+
|
|
240
|
+
**What it changes is not "being a bit stricter" but the object of review itself.** m agents agreeing that "this is right" is still **consensus** —
|
|
241
|
+
it cannot rule out shared misunderstanding; passing Lean is **machine checking**. The only remaining uncertainty is thus reduced to a question a single person can review effectively:
|
|
242
|
+
|
|
243
|
+
> **Are the definitions / objects / conditions / assumptions / conclusions in the Lean code fully consistent with the original text of the proposition?**
|
|
244
|
+
|
|
245
|
+
| | Original verification work | Verification work after formalization passes |
|
|
246
|
+
|---|---|---|
|
|
247
|
+
| Object of review | The proposition itself (whether the derivation is correct) | **Fidelity**: whether the Lean code ↔ the original text of the proposition are consistent |
|
|
248
|
+
| Strength of the conclusion | Consensus (may be jointly wrong) | Strict (already checked by the kernel), provided that fidelity holds |
|
|
249
|
+
| By-product | None | A reusable Lean definition / lemma library |
|
|
250
|
+
|
|
251
|
+
### Switch: `formalVerify` (same name in all four architectures, default `'off'`)
|
|
252
|
+
|
|
253
|
+
| Value | Meaning |
|
|
254
|
+
|---|---|
|
|
255
|
+
| **`'off'` (default)** | **No additional requirement whatsoever.** No Lean content appears in member prompts, no formalization state is written, and the verification flow and gates are completely unchanged (it is a **true no-op**, guarded by assertions and probes). The three tools are still registered and usable (calling them proactively works as usual); the main agent's persona **always** lists these three tools and four parameters — otherwise the switch would not be discoverable, and "off" could not be turned on |
|
|
256
|
+
| `'encourage'` | **Encouraged but not mandatory**: at verification time, first judge the **implementation difficulty** of the object, and if it can be formalized within an acceptable amount of work, do that first; once Lean passes, the focus of review shifts to **fidelity**. In ordinary work, it is also encouraged to formalize and archive commonly used / potentially reusable objects, assumptions, and new definitions along the way. **No gate** |
|
|
257
|
+
| `'require'` | **Mandatory**: a true/false conclusion must satisfy "**Lean has passed**" or "**the blocking reason has been explicitly recorded**", otherwise this adjudication **does not take effect** — it is recorded as undecided (reason `formal-required`), written into the "formalization TODO", announced in the group chat, and the object is kept in the library to be re-proposed after formalization |
|
|
258
|
+
|
|
259
|
+
> "Explicitly record the blocking reason" in `require` is exactly where **"decide not to do it based on implementation difficulty"** lands: **the decision is the agent's,
|
|
260
|
+
> but the decision must be spoken and auditable**, and silently skipping is not allowed. Related parameters also include `leanCommand` (default `lean`),
|
|
261
|
+
> `leanArgs` (used with `lake env lean`), and `leanTimeoutMs` (default 120s).
|
|
262
|
+
|
|
263
|
+
### ⚠️ A fidelity defect ≠ the proposition is false (important)
|
|
264
|
+
|
|
265
|
+
Passing Lean only guarantees that "this piece of code passed the kernel"; it **does not guarantee that it says what the proposition means to say**. So when a voter, checking item by item,
|
|
266
|
+
finds that the Lean code and the original text of the proposition are inconsistent (written too narrowly / too broadly / a different object / a missing condition):
|
|
267
|
+
|
|
268
|
+
- **Do not vote 0.** Voting 0 means "**the proposition is false**"; an incorrectly written formalization would make the framework record "the formalization does not qualify"
|
|
269
|
+
as "the proposition was disproved", and under v5's all-0 consistency rule it would even write the proposition into `Verified/` marked **false** —
|
|
270
|
+
a mechanism meant for truth-seeking would instead **fabricate a wrong negative conclusion**.
|
|
271
|
+
- The correct approach: give a value strictly between 0 and 1 (recorded as an abstention) + use the receipt
|
|
272
|
+
`formal:{decision:'defect', note:'<specific deviation>'}` to record the deviation. The framework then **revokes the "passed" state of this proof**
|
|
273
|
+
(downgraded to `attempted`; `Verified/Lean/<id>.lean` is **deleted**, and if the host cannot delete it, it is rewritten as a "withdrawn" note,
|
|
274
|
+
never leaving a withdrawn proof in the place where everyone looks for proofs; and it is written into the "formalization TODO"), and under the `require` setting
|
|
275
|
+
**this adjudication is not concluded** (the `encourage` setting has no gate, so you must not claim that the framework will force a shelving — there it relies on voters abstaining to prevent a conclusion);
|
|
276
|
+
vote again only after fixing the formalization and getting it to run through.
|
|
277
|
+
- Vote 0 only when the voter, **independently of this Lean code**, can also determine that the proposition is false (and can give independent reasons).
|
|
278
|
+
|
|
279
|
+
> **Receipt channel** (members who do not call the Lean tools can also leave a judgment; it is mandatory under the `require` setting):
|
|
280
|
+
> `"formal": {"target":"<object id>", "decision":"used|blocked|defect", "file":"Formal/<object id>.lean", "note":"difficulty judgment/blocking reason/specific deviation"}`.
|
|
281
|
+
> When `decision='blocked'`/`'defect'`, **`note` is required** (if missing, the whole entry is rejected); `used` only records the object as `attempted`;
|
|
282
|
+
> under the `off` setting this channel **is disabled** (otherwise `off` would not be a true no-op).
|
|
283
|
+
|
|
284
|
+
> Three further hard requirements injected into the prompt (contract §6): tool names are always given in **full** (`<prefix>lean_archive`, not
|
|
285
|
+
> `lean_archive` — an abbreviation is not a registered name, and an agent copying it would call a nonexistent tool); before archiving a reusable definition/lemma, **run it through first** —
|
|
286
|
+
> if it does not run through, it must not enter the library; when the **toolchain is missing** (`LEAN_NOT_FOUND` cannot resolve the executable / `NO_SUBPROCESS` the host has no
|
|
287
|
+
> subprocess service), write the code down, archive it, and state "the host has no Lean toolchain" in `note` — this counts as an explicit blocking reason,
|
|
288
|
+
> and the gate lets it through on that basis, so it will not stall just because Lean cannot be installed.
|
|
289
|
+
|
|
290
|
+
### Archive: where formalized code goes
|
|
291
|
+
|
|
292
|
+
```
|
|
293
|
+
<VibeMath root>/
|
|
294
|
+
├─ Formal/ # ★ cross-project reusable library (shared by the four architectures)
|
|
295
|
+
│ ├─ Lib/<name>.lean # reusable definitions / objects / assumptions (def / structure / notation)
|
|
296
|
+
│ ├─ Lib/Index.md # name → file → category → summary (check here before writing a new definition)
|
|
297
|
+
│ ├─ Proved/<name>.lean # established Lean propositions / lemmas (already machine-checked)
|
|
298
|
+
│ └─ Proved/Index.md
|
|
299
|
+
└─ Projects/<project>/ # (in v5, Projects/<project>/Institutes/<institute>/)
|
|
300
|
+
├─ Formal/
|
|
301
|
+
│ ├─ <object id>.lean # formalization working file for this object
|
|
302
|
+
│ ├─ Index.md # object → status → file → archived proof → run result → difficulty judgment
|
|
303
|
+
│ └─ TODO.md # the "formalization TODO" under require mode
|
|
304
|
+
└─ Verified/
|
|
305
|
+
├─ <original conclusion card>
|
|
306
|
+
└─ Lean/<object id>.lean # ★ archived proof: the formalized code corresponding to this conclusion object
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
### Tools (three per architecture, prefix following each one's naming)
|
|
310
|
+
|
|
311
|
+
| Tool | Purpose |
|
|
312
|
+
|---|---|
|
|
313
|
+
| `<prefix>_lean_run` | Execute Lean on the host `subprocess` service, returning `{ok, exitCode, ms, stdout, stderr}`. **Never throws**: missing toolchain → `LEAN_NOT_FOUND`, timeout → `LEAN_TIMEOUT`, path escape → rejected |
|
|
314
|
+
| `<prefix>_lean_archive` | `kind='def'/'lemma'` → archive to the **cross-project** `Formal/Lib` or `Formal/Proved`; `kind='proof'` → write `Formal/<target>.lean`, and if it runs through, also write **`Verified/Lean/<target>.lean`** and mark the object as Lean-passed; `kind='blocked'` → record an explicit difficulty judgment/blocking reason (**reason required**) |
|
|
315
|
+
| `<prefix>_lean_lib` | Rebuild and return the three indexes and the per-object formalization status — **check for duplicates and reuse directly before writing a new definition** |
|
|
316
|
+
|
|
317
|
+
For example, v5 is `vibe_v5_lean_run` / `vibe_v5_lean_archive` / `vibe_v5_lean_lib`, v2/v3 are `vibe_math_lean_*`, and v4 is `vibe_v4_lean_*`.
|
|
318
|
+
|
|
319
|
+
**Boundaries (intentional)**: the framework **does not bundle Lean** (it does not install a toolchain or download dependencies; when the toolchain is missing it degrades gracefully and records this faithfully);
|
|
320
|
+
the framework **does not judge fidelity** (that is what agents/humans review and vote on; the framework is only responsible for **switching** the focus of review to fidelity);
|
|
321
|
+
**Lean passing ≠ the proposition is true** — it only means "this piece of formalized code passed the kernel check".
|
|
322
|
+
|
|
323
|
+
For the complete contract (parameters, paths, state transitions, prompt semantics, gate locations, index format, test requirements), see
|
|
324
|
+
[`docs/formal-verification.md`](docs/formal-verification.md).
|
|
325
|
+
|
|
326
|
+
> **The personas of all four presets (the prompt the main agent receives) fully list the three tools and four parameters above**,
|
|
327
|
+
> and the two blocks `prefix` and `text` are identical line by line (only line 0 may differ). This layer is guarded by
|
|
328
|
+
> [`audit-persona-surface.test.mjs`](tests/audit-persona-surface.test.mjs) and
|
|
329
|
+
> [`audit-persona-sensitivity.mjs`](tests/audit-persona-sensitivity.mjs) — when this feature was added, it was precisely
|
|
330
|
+
> in the four presets that the defect "the tools were registered but the persona never listed them" was found (the same batch also found that the persona listed two
|
|
331
|
+
> tools for adding/removing resident researchers too few, and that the `/v4`/`/v5` subcommand lists were inconsistent with the implementation; see the release notes shipped with the package).
|
|
332
|
+
|
|
333
|
+
---
|
|
334
|
+
|
|
335
|
+
## 🚀 Installation
|
|
336
|
+
|
|
337
|
+
Two installation methods, choose either one (they can also coexist):
|
|
338
|
+
|
|
339
|
+
### Method A: one-click install as a plugin package (recommended, installs all four presets at once)
|
|
340
|
+
|
|
341
|
+
```sh
|
|
342
|
+
dsh plugin --profile <your profile> add dsh-vibe-math
|
|
343
|
+
# Or install directly from GitHub:
|
|
344
|
+
dsh plugin --profile <your profile> add github:ChongCyrus/Vibe-Mathematics
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
During installation the plugin automatically writes the four presets into `~/.dsh/.agent-presets/`: `vibe-math-v2/`, `vibe-math-v3/`, `vibe-math-v4/` and `vibe-math-v5/`.
|
|
348
|
+
Then start a new session and pick **Vibe Math V3** (v3, **primary recommendation**), **Vibe Math V2** (v2, **primary recommendation**), **Vibe Math V4** (v4, resident self-organization) or **Vibe Math V5** (v5, institute system) in the preset picker — v2 and v3 are equally primary recommendations, choose according to your actual needs (see "How to choose").
|
|
349
|
+
**After upgrading the package version, restart DSH; the managed files in these four preset directories will be replaced wholesale with the new version's bytes — including files you edited by hand.**
|
|
350
|
+
This is intentional: a preset that is "half old version, half new version" will fail to mount or behave strangely, and you cannot tell from the outside. **The hand edits that get replaced are not lost**:
|
|
351
|
+
the original text is first backed up to `~/.dsh/.agent-presets/.vibe-math-backup/<old version>/<preset>/`, and the file names are listed in the log (see the installer notes at the end for details).
|
|
352
|
+
**If you want to customize a preset, do not edit these managed files** — make a copy (the copy action in the preset picker, or copy the directory yourself into a new id); that copy belongs to you and package updates will not touch it.
|
|
353
|
+
|
|
354
|
+
### Method B: manual install as an agent preset
|
|
355
|
+
|
|
356
|
+
1. Copy the files from the corresponding directory of this repository into the preset directory:
|
|
357
|
+
|
|
358
|
+
```
|
|
359
|
+
C:\Users\<you>\.dsh\.agent-presets\vibe-math-v2\ ← copy agent.cordis.yml / preset.yml / vibe-math-v2.js from vibe-math-v2/
|
|
360
|
+
C:\Users\<you>\.dsh\.agent-presets\vibe-math-v3\ ← copy agent.cordis.yml / preset.yml / vibe-math-v3.js from vibe-math-v3/
|
|
361
|
+
C:\Users\<you>\.dsh\.agent-presets\vibe-math-v4\ ← copy agent.cordis.yml / preset.yml / vibe-math-v4.js from vibe-math-v4/
|
|
362
|
+
C:\Users\<you>\.dsh\.agent-presets\vibe-math-v5\ ← copy agent.cordis.yml / preset.yml / vibe-math-v5.js from vibe-math-v5/
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
2. Start a new session and select **"Vibe Math V2"** / **"Vibe Math V3"** / **"Vibe Math V4"** / **"Vibe Math V5"** in the preset picker.
|
|
366
|
+
3. Once the session starts it is ready to use: v2/v3 tools are `vibe_math_*`, v4 is `vibe_v4_*`, v5 is `vibe_v5_*`; typing `/vibe`, `/v4`, `/v5` in the input box gives autocompletion.
|
|
367
|
+
|
|
368
|
+
> After modifying preset files you must **restart the DSH process** before starting a new session (a preset's standing mount is cached until the process exits).
|
|
369
|
+
|
|
370
|
+
### DSH version adaptation and dependencies
|
|
371
|
+
|
|
372
|
+
- **Form dependencies**: the four presets depend on DSH's standard **agent-preset mechanism** (`~/.dsh/.agent-presets/<id>/` + preset picker) and **bundle patch mechanism** (`cordis.patch.yml` injects the installer).
|
|
373
|
+
- **Host plugin rows**: `agent.cordis.yml` references the `@deepseek-ai/dsh-*` plugin rows provided by the host (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, etc., about 21 unique package names). Missing rows on the host cause the preset mount to fail (an error is reported when the session starts).
|
|
374
|
+
- **Host service APIs**: the preset plugins consume `subagents` (startContinuable / **sendMessage** (continue/wake; `followup` is only a method of the `Agent` object, **not** a `subagents` service method) / interrupt / drainContinuableChildren (used by v5 for **real dismissal**)), `agents` (get/roots), `tools` (register/restrict), `commands` (register), `fs` (resolve/stat/readText/writeText/listDir), plus the **optional** `subprocess` / `sandboxPolicy` / `compaction` / `sessionProjections` / `sessions`. These API shapes evolve with DSH versions; this project **has checked and adapted to them item by item on `dsh-v0.1.5-rc.2`** (`dsh.testedVersion` in `package.json`). **Note: starting with DSH 0.1.2, `subagents.startContinuable`'s `agentOptions` / `toolFilter` require the host provider to declare the corresponding capability** (both the in-process spawn / fork providers support it; v4/v5's ability to specify member models/routes and tool permissions depends on this).
|
|
375
|
+
> **2026 compatibility fix highlights** (see `docs/COMPAT-AUDIT-ROUND2.md` for details): ① `tools.restrict()` **throws on unregistered tool names**, and the filter is applied when a subagent is created, so the permission name table must contain only names actually registered in this deployment — v2/v3 previously hard-coded `web`/`fetch`/`bash` (of which `bash` is `disabled` on Windows), which caused "when you want to tighten permissions, the subagent can never start"; ② v4's real `/compact` previously looked up `agents.get()` in `subagent/end`, but that event fires only after the subagent **has already been removed from the registry**, making it dead code; it now captures the reference in `subagent/start`; ③ optional services are now read **lazily** instead of being snapshotted in `apply()` (otherwise mount order could leave `subprocess` permanently undefined and silently skip directory creation).
|
|
376
|
+
- **DSH STORE compatibility declaration**: `dsh.compatibility.dshReleases` in `package.json` declares `compatible` / `incompatible` / `unknown` item by item for each complete DSH version (currently 8 versions from `0.1.2-alpha.4` … `0.1.5-rc.2` are declared `compatible`, with `0.1.5-rc.2` as the tested target); `engines.node` is `^22.19.0 || >=24.0.0`.
|
|
377
|
+
- **Runtime self-check (capability + version dual check)**: on every start the installer (bundle plugin): **① makes a best-effort probe of the DSH version** (reads `@deepseek-ai/dsh/package.json` or the `DSH_VERSION` environment variable; DSH does not expose its version through a public service/context, so this is best effort and is skipped if the probe fails). If a version is detected and is not declared `compatible` in `dshReleases`, a clear notice is given; **② then runs a capability self-check against host services and key APIs** (this is the real mount gate): `subagents`/`agents`/`tools`/`commands`/`fs` are **required** (missing means a warning), while `subprocess`/`sandboxPolicy`/`compaction`/`sessionProjections`/`sessions` are **optional** (missing only prompts that "functionality will silently degrade" and does not affect mounting; when `sessionProjections` is missing, v5's institute state falls back to hardened JSON), and it also includes an `fs.resolve` return-shape check and a subagent `agentOptions`/`toolFilter` capability check. If a preset fails to mount, look first at the self-check warnings in the DSH log.
|
|
378
|
+
- **Upgrade path**: after upgrading DSH there is no need to reinstall this package; to upgrade this package use `dsh plugin --profile <your profile> add dsh-vibe-math@latest` (`dsh plugin`'s `--profile` is mandatory; use `add` rather than `update`, because a profile may pin the version to an exact value, in which case `update` will not cross over), and after restarting DSH the installer updates the managed files of the four presets wholly to the new version (modified files are likewise replaced, with the original text first going to `<presetRoot>/.vibe-math-backup/`; see the "Installation" notes above).
|
|
379
|
+
|
|
380
|
+
---
|
|
381
|
+
|
|
382
|
+
## 🧭 How to choose among the four presets
|
|
383
|
+
|
|
384
|
+
> **💡 `vibe-math-v2` and `vibe-math-v3` are equally primary recommendations; choose according to your actual needs:**
|
|
385
|
+
>
|
|
386
|
+
> - **Choose `vibe-math-v2` (probability-driven · JSON data layer)** if you:
|
|
387
|
+
> - prefer **structured JSON data** (`qs.json` / `Propos/<category>_Propos.json` / `Verified/` cards), convenient for programmatic retrieval and further processing;
|
|
388
|
+
> - want **mature and stable code-heuristic scheduling** (priority + probability, predictable behavior, not dependent on the planner agent's "improvisation");
|
|
389
|
+
> - do not need method library accumulation / paper-style narration, and data being field-oriented is enough.
|
|
390
|
+
> - **Choose `vibe-math-v3` (paper-style md + planner agent + method library)** if you:
|
|
391
|
+
> - prefer a **paper/research-report-style natural-language knowledge base** (the problem list includes dependencies and the source motivation of follow-up problems, the research log is continued by direction and by round, human-readable and freely extendable);
|
|
392
|
+
> - want scheduling to be **planned autonomously by the planner agent** as an N-step plan based on the actual situation (more flexible, automatically falls back to heuristics on failure);
|
|
393
|
+
> - want a **general theory invention library** — theories/frameworks/tools/methods/ideas invented during solving are accumulated by the Method Keeper into a reusable, systematizable, cross-project-extendable methodology (like "inventing group theory while solving equations");
|
|
394
|
+
> - accept the trust layering of "only `Verified/` is absolutely trustworthy, the rest of the md is empirical reference".
|
|
395
|
+
>
|
|
396
|
+
> Both are mature and usable, continuously maintained, and both support checkpoint resume, manual/automatic intervention, progress reporting, multi-session isolation, proposition promotion, near-consensus/weighted adjudication and other core capabilities; the switching cost is low (the same set of `vibe_math_*` tools and `/vibe` commands, the same parameter system).
|
|
397
|
+
>
|
|
398
|
+
> - **Choose `vibe-math-v4` (resident self-organization)** if you want a group of **persistent resident subagents** that message each other and hold meetings, **fully self-organizing** (no leader, no central scheduling), and can accept a strict threshold of "a conclusion requires unanimity".
|
|
399
|
+
> - **Choose `vibe-math-v5` (institute system)** if you want:
|
|
400
|
+
> - **organized self-organization** — like a real research institute, with a **leader (academician)** responsible for decomposition, assignment, prioritization, chairing meetings and supervising progress, but **judgment still belongs to each individual**;
|
|
401
|
+
> - a **roster that can grow or shrink** — resident researchers + temp workers who can be **autonomously hired/dismissed** (temp workers have no voting rights, suitable for chores such as checking, trial computation and material organization);
|
|
402
|
+
> - an **adjustable consistency threshold** — `m = min(quorumCap, number of voting members)` boolean-consistent votes settle the matter (easier to converge than "unanimity", while **opposing votes still block**, so a minority will not be drowned out by abstentions);
|
|
403
|
+
> - **zero-token-cost state persistence** — the institute state is stored in a host-only projection unit of the session log and does not consume member context budget.
|
|
404
|
+
>
|
|
405
|
+
> **⚠️ `vibe-math-v2` and `vibe-math-v3` are mature primary architectures; `vibe-math-v4` and `vibe-math-v5` are experimental architectures,** all are selectable; the old `vibe-math-v1` has been removed (this package contains only v2/v3/v4/v5).
|
|
406
|
+
|
|
407
|
+
| | **v2 (probability-driven · primary)** | **v3 (paper-style md · primary)** | **v4 (resident self-organization · experimental)** | **v5 (institute system · experimental)** |
|
|
408
|
+
|---|---|---|---|---|
|
|
409
|
+
| Positioning | **Primary** (JSON data layer) | **Primary** (third generation) | **Experimental** (fourth generation) | **Experimental** (fifth generation) |
|
|
410
|
+
| Core idea | Probability-driven: `qs.json` problems + `Propos/` proposition library, scheduled by "correctness probability / value" | **Paper-style md knowledge base + planner agent scheduling + general theory invention library** | **Persistent resident subagents self-organizing**: message each other + meetings decide all tasks, no central scheduling | **Institute**: the academician organizes and assigns, members research on their own; a conclusion requires **≥ m boolean-consistent votes**; temp workers can be hired as needed |
|
|
411
|
+
| Data | `qs/qs.json` + `Propos/<category>_Propos.json` + `Reliable/` | `Problems/` + `Progress/` + `Propos/` + `Methods/` (all md, soft-spec anchors + free narration) + `Verified/` | `Problems/` + `Progress|Propos|Methods|Subproblems/<id>/` **owned by resident id** + `Shared/` (meetings/task board/debate) + `Verified/` | Same member-owned layout as v4, plus `Institutes.md` (roster mirror); **the authoritative state is in the session log projection**, and files are only mirrors and workspaces |
|
|
412
|
+
| Roles | explorer → per-direction solver → verifier | **planner (planner agent)** → explorer → per-direction solver → verifier → **method-keeper (method organization agent)** | **N resident researchers** (continuable), no fixed roles | **academician acad** (leader) + **resident researcher r-n** (with voting rights) + **temp worker t-n** (no voting rights, hireable and dismissible) + institute office (does not research and does not vote) |
|
|
413
|
+
| Scheduling | Code heuristics (priority + probability) | **The planner agent produces an N-step plan** (executed after validation, falls back to heuristics on failure) | **No central scheduling**: tasks arise from residents messaging each other / holding meetings (the framework is only a medium and does not assign) | **The framework still does not assign**; the **academician** decomposes/assigns/prioritizes/supervises, and members may object with reasons; the framework only relays, keeps the task board, holds meetings and counts |
|
|
414
|
+
| Closing rule | A solution/proof reaching probability `1` closes it; `never` is never scheduled | Same as v2 (near-consensus adjudication fixes flat misjudgment) | Writes to `Verified/` **only when all residents agree (true or false)**, otherwise leaves it in the library with a probability | Writes to `Verified/` **only when boolean votes ≥ m = min(`quorumCap`, number of voting members) and all are 1 or all are 0**; opposing votes block; abstentions do not count as votes but count toward the average; (can be switched back to the v4 criterion) |
|
|
415
|
+
| Stopping | All solved or stuck | All solved / no candidates | Stops **only when all residents unanimously agree the original problem is solved** | Same as v4: concluded **only when all voting members unanimously agree the original problem is solved** |
|
|
416
|
+
| Context | None | None | **Resident context automatically runs `/compact` on reaching the threshold** (adjustable) | Same as v4 (threshold/round count adjustable; after compaction the charter still takes effect in the persona) |
|
|
417
|
+
| Ad hoc capabilities | Automatic promotion of proposition "value/criticality" to the problem list; `reportMode file/push/both`; `priorityAdjust` | **Method library accumulation loop** (`methods_used`/`new_inventions` → Method Keeper); **plan approval gate/method promotion gate**; **project lock**; follow-up problem "source and motivation" as a first-class citizen | **Residents accumulate individually + read each other**; **unanimous verification**; **add/close residents at any time, intervene by message**; **checkpoint resume** | All v4 capabilities, plus: **real hiring/dismissal** (releases sub-sessions, reclaims tasks); **compare-and-set task board + dependency DAG**; **strict mutual exclusion between meetings and verification**; **roster mirror and conclusion records**; **zero-token-cost state** |
|
|
418
|
+
|
|
419
|
+
All four support: checkpoint resume (`vibe_math_resume` / `vibe_v4_resume` / `vibe_v5_resume`), manual intervention and pause/resume,
|
|
420
|
+
per-project isolation, subagent permission control, and natural-language driving. **v2 and v3 are both equally primary recommendations** — choose v2 if you prefer structured JSON data and deterministic scheduling,
|
|
421
|
+
choose v3 if you prefer paper-style md, the planner agent and the theory invention library; v4 is fully self-organizing resident collaborative research, and v5 is an institute system with "a leader + a roster that can grow or shrink + an adjustable threshold".
|
|
422
|
+
|
|
423
|
+
---
|
|
424
|
+
|
|
425
|
+
## 🧠 Architecture and Division of Labor (v3 · third generation) ✅ recommended
|
|
426
|
+
|
|
427
|
+
The framework = **one main agent (assistant) + one code scheduler + one planner agent + six kinds of subagents**.
|
|
428
|
+
|
|
429
|
+
| Role | Type | Responsibility |
|
|
430
|
+
|---|---|---|
|
|
431
|
+
| **Main agent** | LLM (the assistant in the session) | **Natural-language interface + reporter + assistant**. It **does not solve or schedule on its own**; it is only responsible for: translating your words into `vibe_math_*` tool calls, reporting progress, configuring parameters in Q&A form, and executing control commands. |
|
|
432
|
+
| **Scheduler** | Plugin code (not a model) | The sole master control: maintains the md knowledge base index, builds the state brief, **validates and executes the planner agent's plan**, writes files, and advances the state machine. **Hard constraints (concurrency / idempotency / already-verified is never scheduled again / write ownership) are enforced by code**. |
|
|
433
|
+
| **Planner (planner agent)** 🆕 | Subagent | Each time a dispatch is being prepared, it reads the state brief (problem + dependencies + survival rate, verifiable objects, active agents, concurrency budget, available methods, result of the last plan) and **autonomously chooses the optimal scheduling scheme, arranging the next N steps in one go** (spawn/continue/interrupt/promote/verify/method-keep/wait). It outputs a JSON plan, which the scheduler validates before executing; on failure it automatically falls back to heuristics. |
|
|
434
|
+
| **Explorer subagent** | Subagent | Metacognitive brainstorming: constraint decomposition, boundary testing, similar-problem mapping, splitting the problem into multiple "widely divergent" solution directions (if all are dead ends, re-derive). Before starting work it first checks the `Methods/` method library. |
|
|
435
|
+
| **Solver subagent** | Subagent | One dedicated solver per direction, **multiple iteration rounds within the same session**, producing lemmas (with proofs), sub-routes, survival probability, and a complete solution, and **reporting `methods_used` and `new_inventions`** (methods/tools/ideas newly invented in this round). |
|
|
436
|
+
| **Verifier subagent** | Subagent | Each verification object gets ≥3 independent "harsh reviewers": independent review → debate (chat group) → **near-consensus verdict** (if on the same side with mean ≥0.85/≤0.15, take the mean; otherwise flat/forced). |
|
|
437
|
+
| **Method Keeper (method-organizing agent)** 🆕 | Subagent | Periodically digests recent work and new-invention reports, **distills new method cards, merges fragments, improves the system structure (parent system/sub-methods), maintains trusted assertions**, and deposits the theories/frameworks/tools/methods/ideas invented during solving into the `Methods/` general theory invention library. |
|
|
438
|
+
|
|
439
|
+
> Division of labor in one sentence: **the main agent handles "talking to people", the planner agent handles "setting the plan", the scheduler handles "execution and boundary-keeping", subagents handle "thinking", and the Method Keeper handles "depositing inventions into theory".**
|
|
440
|
+
|
|
441
|
+
### Architecture and Division of Labor (v4 / v5)
|
|
442
|
+
|
|
443
|
+
| | **v4 (resident self-organization)** | **v5 (institute system)** |
|
|
444
|
+
|---|---|---|
|
|
445
|
+
| Principal | N resident subagents (continuable) | academicians + resident researchers + temp workers (all continuable subagents) |
|
|
446
|
+
| Who assigns tasks | **No one**: emerges on its own through mutual messages and meetings | **academicians** (institute members, equally bound by the voting rules); the framework still does not assign |
|
|
447
|
+
| Who judges | Each on its own; a conclusion is reached only when all agree | Each on its own; a conclusion is reached only on **≥ m voting members in boolean agreement** |
|
|
448
|
+
| Coordination mechanism | messages + meetings | messages + meetings (strictly mutually exclusive with verification) + **compare-and-set task board** |
|
|
449
|
+
| Roster | resident, can be spawned/closed | **can grow and shrink**: resident researchers are hired with the institute office's approval; temp workers are hired and fired autonomously by academicians/researchers |
|
|
450
|
+
| State | `State/*.json` written directly | **session-log host-only projection cells** (zero token cost, handled by DSH checkpoint/restore) |
|
|
451
|
+
|
|
452
|
+
For the complete v5 architecture (including member lifecycle, one-round timeline, consensus state machine, meeting flow, scheduling priority, state folding, prompt composition, task board, authority matrix), see [`vibe-math-v5/架构图.md`](vibe-math-v5/架构图.md); for the textual specification see
|
|
453
|
+
[`vibe-math-v5/实现方案.md`](vibe-math-v5/实现方案.md).
|
|
454
|
+
|
|
455
|
+
---
|
|
456
|
+
|
|
457
|
+
|
|
458
|
+
## 📁 Directory Structure
|
|
459
|
+
|
|
460
|
+
### v2 (probability-driven · recommended)
|
|
461
|
+
|
|
462
|
+
```
|
|
463
|
+
<session workspace>/VibeMath/
|
|
464
|
+
├─ current.json # current project
|
|
465
|
+
├─ vibe_math_setting.json # (optional, global fallback) default parameters JSONC, with comments
|
|
466
|
+
└─ Projects/<project>/
|
|
467
|
+
├─ vibe_math_setting.json # default parameters for this project
|
|
468
|
+
├─ qs/qs.json # problem list: overview/solved/solution list (complete solution · correctness probability)/priority/progress
|
|
469
|
+
├─ Propos/<category>_Propos.json # proposition library: overview/boolean estimate/fine type/proof·disproof list/priority/value·criticality/progress
|
|
470
|
+
├─ Reliable/ # trusted references (read-only, placed by the user)
|
|
471
|
+
├─ Verified/ # concluded-fact index (propositions with boolean estimate = 0/1)
|
|
472
|
+
├─ Verification_logs/ # debate record of each verification round (for auditing)
|
|
473
|
+
├─ Progress_Logs/ # periodic progress reports report.json
|
|
474
|
+
└─ VibeMath_State/ # scheduler-private persistent state (for checkpoint resume)
|
|
475
|
+
```
|
|
476
|
+
|
|
477
|
+
### v3 (paper-style md + planner agent + method library) ✅ recommended
|
|
478
|
+
|
|
479
|
+
```
|
|
480
|
+
<session workspace>/VibeMath/
|
|
481
|
+
├─ Methods/ # [global] cross-project general theory invention library (v3, promoted from project level)
|
|
482
|
+
├─ current.<session id>.json # current project per session (parallel sessions do not overwrite each other)
|
|
483
|
+
├─ vibe_math_setting.json # (optional, global fallback) default parameters JSONC, with comments
|
|
484
|
+
└─ Projects/<project>/
|
|
485
|
+
├─ vibe_math_setting.json # default parameters for this project
|
|
486
|
+
├─ Problems/<id>.md # problem list: one md per problem (soft-spec anchor: ID/type/status/priority/dependencies/dependents/source/plan
|
|
487
|
+
│ # + ## statement / ## source and motivation (later-born problems: generation flow/motivation/backfill plan) / ## solution candidates)
|
|
488
|
+
├─ Progress/<id>.md # aggregated research log index (per-direction summaries + lemma index + per-round records)
|
|
489
|
+
├─ Progress/<id>/<direction id>.md # one independent file per direction (written directly by self-organizing agents, no cross-direction concurrency conflict)
|
|
490
|
+
├─ Propos/<category>/<id>.md # proposition library: one md per proposition (statement/proof attempts/disproof attempts, soft-spec anchor + free narrative)
|
|
491
|
+
├─ Methods/<id>.md # [general theory invention library] method card: theoretical system/framework/tool/method/idea (with application records/improvement history/system hierarchy)
|
|
492
|
+
├─ Verified/命题/<id>.md # absolutely trusted: scheduler-generated verified proposition cards (read-only)
|
|
493
|
+
├─ Verified/问题/<id>.md # absolutely trusted: complete trusted solution cards for solved problems (read-only)
|
|
494
|
+
├─ Reliable/ # trusted references (read-only, placed by the user)
|
|
495
|
+
├─ Notes/ # free notes (not involved in scheduling)
|
|
496
|
+
├─ Logs/Verification/ # debate record of each verification round (for auditing)
|
|
497
|
+
├─ Logs/Plans/ # each scheduling plan + execution result (planner learning loop)
|
|
498
|
+
├─ Logs/报告.md # paper-style human-readable progress report
|
|
499
|
+
└─ State/ # scheduler-private persistent state (agents/tasks/plans/verifier_accuracy/index/project lock/process epoch)
|
|
500
|
+
```
|
|
501
|
+
|
|
502
|
+
**Iron rule (v2 general)**: the scheduler is the **sole file writer** (subagents only return structured JSON and never write files).
|
|
503
|
+
**v3 iron rule**: only `Verified/` and objects judged true/false by the verifier are **absolutely trusted**; all other md (unconcluded propositions, research logs, unverified assertions in the method library) serve only as experiential reference; the scheduler parses only soft-spec anchor lines and entry title lines, and never parses body prose. **v3 allows agents to write md directly** (self-organizing agents locate their own files, e.g. a solver writes `Progress/<id>/<direction id>.md`, a new lemma is written to `Propos/<category>/<id>.md`, and the method-organizing agent writes `Methods/<id>.md`); concurrency safety relies on **write locks** — before writing any file call `vibe_math_claim_write`, after writing call `vibe_math_release_write` (only one agent may write a given file at a time); the content stays in the md, and lightweight metadata is reported to the scheduler via `vibe_math_sync_meta`.
|
|
504
|
+
|
|
505
|
+
### v5 (institute system · experimental)
|
|
506
|
+
|
|
507
|
+
```
|
|
508
|
+
<session workspace>/VibeMath/Projects/<project>/Institutes/<institute>/
|
|
509
|
+
├─ Institutes.md # roster mirror (human-readable snapshot: codename/position/status/employer/direction/round/context%)
|
|
510
|
+
├─ Problems/<id>.md # original problem
|
|
511
|
+
├─ Problems/conclusion.md # conclusion record (generated when all those with voting rights agree it is solved)
|
|
512
|
+
├─ Members/<codename>/
|
|
513
|
+
│ ├─ Progress/progress.md # research log (narrative, appendable; the main basis for restoring state after compaction)
|
|
514
|
+
│ ├─ Propos/<id>.md # proposition (with proof attempts/disproof attempts)
|
|
515
|
+
│ ├─ Methods/<id>.md # method / theory / tool (with definition notation/application records/improvement history)
|
|
516
|
+
│ └─ Subproblems/<id>.md # subproblem
|
|
517
|
+
├─ Shared/
|
|
518
|
+
│ ├─ Chat/<date>.md # group chat record (including institute founding/hiring/firing/meetings/votes/conclusion announcements)
|
|
519
|
+
│ ├─ Meetings/<mt-id>.md # meeting minutes (each member's speech + vote subsection)
|
|
520
|
+
│ ├─ Debates/<object>.md # debate record (each round's votes and reasons + whole-group mean probability)
|
|
521
|
+
│ ├─ TaskBoard.md # task board mirror
|
|
522
|
+
│ └─ State-of-institute.md # snapshot of members' judgment on "whether it is solved"
|
|
523
|
+
├─ Verified/<type>/<id>.md # conclusions (read-only; only these may be treated as established)
|
|
524
|
+
└─ State/
|
|
525
|
+
├─ README.md # explains "the authoritative state is in the session-log projection, not here"
|
|
526
|
+
└─ <institute>.v5state.json # fallback authoritative source only when the host lacks sessionProjections
|
|
527
|
+
```
|
|
528
|
+
|
|
529
|
+
> Enabling Lean formal verification adds two more directories: this institute's `Formal/` (working files + index + formalization todos) and `Verified/Lean/`
|
|
530
|
+
> (**archived proofs**), plus the **cross-project** `<VibeMath root>/Formal/{Lib,Proved}/` (reusable definitions and already-proved lemmas) — see
|
|
531
|
+
> the "Lean formal verification" section above.
|
|
532
|
+
|
|
533
|
+
**v5 iron rules**: ① the authoritative state lives in the **session log's host-only projection cells** (key `vibeMathV5`); in the table above, everything except
|
|
534
|
+
`State/<institute>.v5state.json` (degraded fallback) is merely a **mirror/workspace**, and breaking it by hand-editing will not destroy the institute;
|
|
535
|
+
② members **write only their own library** (`Members/<own codename>/`), but may read anyone's library;
|
|
536
|
+
③ only `Verified/` and cards marked "verified·true/false" are **absolutely trusted**; everything else (including unverified assertions in `Methods/`) is merely experiential reference,
|
|
537
|
+
and citations must be marked "unverified"; ④ entry into the library must state all three of **degree of value / motivation-purpose plan / own probability estimate**, none may be omitted.
|
|
538
|
+
|
|
539
|
+
---
|
|
540
|
+
|
|
541
|
+
## ⚡ Quick Start
|
|
542
|
+
|
|
543
|
+
### Method A: Direct conversation (recommended, the least effort)
|
|
544
|
+
|
|
545
|
+
Because the main agent has built-in usage instructions, you **can simply speak in plain language**:
|
|
546
|
+
|
|
547
|
+
```
|
|
548
|
+
帮我用 Vibe Math 证明 √2 是无理数。
|
|
549
|
+
```
|
|
550
|
+
|
|
551
|
+
The main agent will automatically: `vibe_math_add_problem` to add the problem → `vibe_math_start` to start it → after that you can ask it for progress at any time.
|
|
552
|
+
|
|
553
|
+
```
|
|
554
|
+
现在进展怎么样了？
|
|
555
|
+
```
|
|
556
|
+
|
|
557
|
+
The main agent will automatically call `vibe_math_status` / `vibe_math_report` and report the results back to you in plain language.
|
|
558
|
+
|
|
559
|
+
### Method B: Commands / tools (precise control)
|
|
560
|
+
|
|
561
|
+
Call the tools directly in the conversation (arguments are JSON):
|
|
562
|
+
|
|
563
|
+
| Tool | Purpose |
|
|
564
|
+
|---|---|
|
|
565
|
+
| `vibe_math_add_problem` | Add a problem (id/description/priority/dependencies?; v3 generates `Problems/<id>.md`) |
|
|
566
|
+
| `vibe_math_add_proposition` / `vibe_math_list_propositions` (v2/v3) | Add / list the proposition library (id/overview/boolean estimate/fine type/value·criticality; v3 generates `Propos/<分类>/<id>.md`) |
|
|
567
|
+
| `vibe_math_start` / `vibe_math_resume` | Start / checkpoint-resume the scheduler |
|
|
568
|
+
| `vibe_math_pause` / `vibe_math_abort` | Pause / abort (interrupts all subagents) |
|
|
569
|
+
| `vibe_math_status` / `vibe_math_report` | View status / full progress report |
|
|
570
|
+
| `vibe_math_set_mode` | Switch `auto` / `manual` |
|
|
571
|
+
| `vibe_math_set_params` | Adjust parameters at runtime |
|
|
572
|
+
| `vibe_math_setup` | Return the parameter schema (for interactive configuration) |
|
|
573
|
+
| `vibe_math_save_settings` | Save the current parameters as the new defaults |
|
|
574
|
+
| `vibe_math_template` | Generate the default parameter template file |
|
|
575
|
+
| `vibe_math_new_project` / `vibe_math_set_project` / `vibe_math_list_projects` | Project management |
|
|
576
|
+
| `vibe_math_list_decisions` / `decide` | View / decide manual decisions (v3: `node=plan` plan approval / `node=method-promote` method promotion) |
|
|
577
|
+
| `vibe_math_list_agents` / `vibe_math_message_agent` / `vibe_math_interrupt_agent` | View / message / interrupt subagents |
|
|
578
|
+
| `vibe_math_plan` (v3) | View the pending plan / the last plan, or `force:true` to force one planning run |
|
|
579
|
+
| `vibe_math_index` (v3) | Rebuild the machine index from the md knowledge base (`State/index.json`) |
|
|
580
|
+
| `vibe_math_method_add` / `vibe_math_method_list` (v3) | Manually add / list method cards (project + global) |
|
|
581
|
+
| `vibe_math_lock_status` (v3) | View project lock occupancy |
|
|
582
|
+
| `vibe_math_claim_write` / `vibe_math_release_write` (v3) | Claim / release the **write lock** on an md file (call before an agent writes a file directly; only one agent may write the same file at a time, preventing concurrent conflicts) |
|
|
583
|
+
| `vibe_math_sync_meta` (v3) | After an agent writes content into md, report **lightweight metadata** (direction status/survival rate/lemma id/method card id/new invention) so the scheduler can sync the index — content stays in md, not in JSON |
|
|
584
|
+
|
|
585
|
+
Slash commands (equivalent to the tools): `/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` (v3 additionally has `methods|index|plan|lock`)
|
|
586
|
+
|
|
587
|
+
---
|
|
588
|
+
|
|
589
|
+
## 🎓 Tutorial: Let the Main Agent Do the Work for You
|
|
590
|
+
|
|
591
|
+
### 1. Natural-language driven (no need to memorize commands)
|
|
592
|
+
|
|
593
|
+
The main agent's role is to be your "translator". You only need to describe the **goal**, and it will choose and call the tools itself:
|
|
594
|
+
|
|
595
|
+
| What you say | What the main agent does |
|
|
596
|
+
|---|---|
|
|
597
|
+
| “求解 / 证明 XXX” | `add_problem` + `start`, then report |
|
|
598
|
+
| “现在进度怎么样 / 有哪些代理在跑” | `status` / `report` / `list_agents` and summarize |
|
|
599
|
+
| “暂停 / 终止求解” | `pause` / `abort` |
|
|
600
|
+
| “切到人工模式，我要逐步把关” | `set_mode manual`, then remind you with `list_decisions` whenever there is a decision |
|
|
601
|
+
| “给 q1 的某个求解方向换个思路（比如改成构造性证明）” | `list_agents` to find the childId → `message_agent` to inject new instructions |
|
|
602
|
+
| “中断某个卡住的子代理” | `interrupt_agent` |
|
|
603
|
+
|
|
604
|
+
### 2. Q&A-style parameter configuration (/vibe setup)
|
|
605
|
+
|
|
606
|
+
You do not even need to remember parameter names. Say:
|
|
607
|
+
|
|
608
|
+
```
|
|
609
|
+
帮我配置一下参数。
|
|
610
|
+
```
|
|
611
|
+
|
|
612
|
+
The main agent will call `vibe_math_setup` to get the full parameter schema (each item includes a **description / options / suggestion / current value**),
|
|
613
|
+
then use `ask_user_question` to **ask you item by item** (the options come with explanations and suggestions), apply your choices with `vibe_math_set_params`,
|
|
614
|
+
and finally ask whether to save them as defaults with `vibe_math_save_settings`.
|
|
615
|
+
|
|
616
|
+
You can also just run the command: `/vibe setup` (view the schema) → tell the main agent which ones you want to change → `/vibe save` (save as defaults).
|
|
617
|
+
|
|
618
|
+
### 3. Configuration file (vibe_math_setting.json)
|
|
619
|
+
|
|
620
|
+
- **Generate a template**: `/vibe template` (generated into the workspace) or `/vibe template project` (generated into the current project) —
|
|
621
|
+
it produces a JSON template **with `//` comments and an item-by-item Chinese description**; after you edit it by hand, restart/resume to take effect.
|
|
622
|
+
- **Save current values**: `/vibe save` writes the currently effective parameters back to that file.
|
|
623
|
+
- **The only persistent source**: that file is the **only persistence layer** for parameters (project level takes precedence → when missing, fall back to the global `<工作区>/VibeMath/vibe_math_setting.json` → built-in defaults).
|
|
624
|
+
`vibe_math_set_params` / `set_mode` **write back immediately** to the project-level file and persist, so no manual save is needed.
|
|
625
|
+
|
|
626
|
+
---
|
|
627
|
+
|
|
628
|
+
## 🌱 Beginner example walkthrough (using “prove √2 is irrational” as the example)
|
|
629
|
+
|
|
630
|
+
**Step 1 — Start with one sentence**
|
|
631
|
+
|
|
632
|
+
```
|
|
633
|
+
帮我用 Vibe Math 证明：√2 是无理数。
|
|
634
|
+
```
|
|
635
|
+
|
|
636
|
+
The main agent runs `vibe_math_add_problem {"id":"q1","description":"证明：√2 是无理数。","priority":0}`
|
|
637
|
+
then runs `vibe_math_start`, and then tells you “started”.
|
|
638
|
+
|
|
639
|
+
**Step 2 — Ask about progress**
|
|
640
|
+
|
|
641
|
+
```
|
|
642
|
+
进展如何？
|
|
643
|
+
```
|
|
644
|
+
|
|
645
|
+
The main agent runs `vibe_math_status` and reports in plain language: the number of currently active subagents, the units being verified, whether there are pending decisions, and so on.
|
|
646
|
+
|
|
647
|
+
**Step 3 — Tune parameters by conversation (optional)**
|
|
648
|
+
|
|
649
|
+
```
|
|
650
|
+
我想让它用加权投票，并发数设成 6。
|
|
651
|
+
```
|
|
652
|
+
|
|
653
|
+
The main agent `vibe_math_set_params {"verdictMode":"weighted-vote","maxParallelThreshold":6}`,
|
|
654
|
+
and asks you whether to `vibe_math_save_settings` to save them.
|
|
655
|
+
|
|
656
|
+
**Step 4 — Intervene midway (optional)**
|
|
657
|
+
|
|
658
|
+
```
|
|
659
|
+
切到人工模式，我要在每个关键节点把关。
|
|
660
|
+
```
|
|
661
|
+
|
|
662
|
+
The main agent `vibe_math_set_mode {"mode":"manual"}`. Afterwards, at every key node it runs `vibe_math_list_decisions`
|
|
663
|
+
to get the decisions, explains them to you, and waits for you to `vibe_math_decide {"id":"...","action":"approve"}` (or `reject` / `override`).
|
|
664
|
+
|
|
665
|
+
**Step 5 — Wrap up**
|
|
666
|
+
|
|
667
|
+
```
|
|
668
|
+
结束了吗？结论是什么？
|
|
669
|
+
```
|
|
670
|
+
|
|
671
|
+
The main agent `vibe_math_status`: in `qs.csv`, `q1` has been written back as `solved`, and the solution file is in `Verified/` and named
|
|
672
|
+
`q1-的解法_<唯一标识>.csv`.
|
|
673
|
+
|
|
674
|
+
> The corresponding wrap-up in v2 is: `q1.已解决 = true` in `qs.json`, its solution `正确概率 = 1`, and the related proposition enters `Verified/`.
|
|
675
|
+
|
|
676
|
+
---
|
|
677
|
+
|
|
678
|
+
## 🖼️ Real usage example (long screenshot)
|
|
679
|
+
|
|
680
|
+
> The screenshot is very long, so it is **collapsed** by default here: the full long image is loaded only after you click “Expand” below, so that it does not fill the page and block the surrounding text.
|
|
681
|
+
|
|
682
|
+
<details>
|
|
683
|
+
<summary>📸 Expand to view the real usage example long screenshot</summary>
|
|
684
|
+
|
|
685
|
+
|
|
686
|
+
|
|
687
|
+
</details>
|
|
688
|
+
|
|
689
|
+
---
|
|
690
|
+
|
|
691
|
+
## ⚙️ Parameter quick reference
|
|
692
|
+
|
|
693
|
+
### v2 (probability-driven · main recommendation) defaults
|
|
694
|
+
|
|
695
|
+
| Parameter | Default | Description |
|
|
696
|
+
|---|---|---|
|
|
697
|
+
| `mode` | `auto` | `auto` / `manual` |
|
|
698
|
+
| `maxParallelThreshold` | 4 | Global maximum number of concurrent subagent rounds (before a new dispatch, active must be < threshold) |
|
|
699
|
+
| `solverMaxRounds` | 3 | Maximum number of iteration rounds per solving direction (agent_self_iteration cap) |
|
|
700
|
+
| `directionsPerSolver` | 1 | Total number of directions visible to each solver prompt (1 = only its own direction, no mutual interference; N>1 = its own plus summaries of up to N-1 other active directions) |
|
|
701
|
+
| `verifierCount` | 3 | Number of independent verifiers per verification target |
|
|
702
|
+
| `debateMaxRounds` | 5 | Maximum number of rounds of verification debate (chat group) |
|
|
703
|
+
| `verdictMode` | `flat` | `flat` = balanced mechanism (inconsistency judged 0.5) / `forced` = forced verdict (historical accuracy + rigor weighting) |
|
|
704
|
+
| `reportMode` | `file` | `file` = write a report file / `push` = push a report to the main agent / `both` |
|
|
705
|
+
| `promoteValueThreshold` | 0.7 | A proposition in Propos with "value/criticality" ≥ this value and undecided (0,1) is automatically added to qs.json |
|
|
706
|
+
| `priorityAdjust` | `none` | `none` / `deadend-deprioritize` (deprioritize all dead ends) / `survival-map` (recompute by survival rate) |
|
|
707
|
+
| `proposPriorityAdjust` | `none` | Dynamic adjustment of proposition priority: `none` / `progress-graded` (recompute by proximity to a conclusion + amount of proof/disproof material; the closer to a conclusion, the higher the priority for verification) |
|
|
708
|
+
| `provider` / `model` | empty | Subagent model (empty = inherit the root agent) |
|
|
709
|
+
| `solverPersona` / `verifierPersona` / `explorerPersona` | empty | Persona/requirements injected at the start of the solver/verifier/explorer prompt |
|
|
710
|
+
| `knowledgeContext` | empty | Shared knowledge/data model description (empty = built-in full version: object/attribute definitions, probability semantics, folder purposes, output completeness requirements; non-empty = overrides and is injected into all subagent prompts) |
|
|
711
|
+
| `solverToolAllow` / `solverToolDeny` | `[]` | Tools allowed/denied for the solver |
|
|
712
|
+
| `verifierToolAllow` / `verifierToolDeny` | `[]` | Tools allowed/denied for the verifier |
|
|
713
|
+
| `solverAllowNetwork` / `verifierAllowNetwork` | empty | Network tool switch (web_search/web/fetch): empty = inherit everything; `true` = add to the existing allow list when one is present; `false` = deny |
|
|
714
|
+
| `solverAllowScripts` / `verifierAllowScripts` | empty | Script tool switch (bash/pwsh): same as above |
|
|
715
|
+
| `solverMaxToolCalls` / `verifierMaxToolCalls` | 0 | Maximum external tool calls per round (0 = unlimited) |
|
|
716
|
+
| `reportIntervalMs` | 0 | 0 = event-driven only (write/push only when there is a state update); >0 = timed automatic reporting (milliseconds) |
|
|
717
|
+
| `tickIntervalMs` | 2000 | Scheduler heartbeat interval (milliseconds) |
|
|
718
|
+
| `activityLogCap` | 100 | Number of activity log entries retained (the report displays at most 30) |
|
|
719
|
+
| `maxExplorerRetries` | 3 | Upper limit on re-dispatching after an explorer fails to split directions |
|
|
720
|
+
| `formalVerify` | `'off'` | **Lean formal verification switch**: `'off'` no additional requirement (default)｜`'encourage'` encouraged (during verification, decide for yourself whether to formalize based on implementation difficulty)｜`'require'` mandatory (a true/false conclusion must first have a "Lean passed" or an explicit blocking record, otherwise it is recorded as undecided and enters the formalization todo list). Any illegal value falls back to `'off'` |
|
|
721
|
+
| `leanCommand` | `'lean'` | The Lean executable to run (e.g. `'lake'`) |
|
|
722
|
+
| `leanArgs` | `[]` | Additional arguments inserted before the file name (e.g. `['env','lean']` together with `leanCommand='lake'`) |
|
|
723
|
+
| `leanTimeoutMs` | `120000` | Upper limit for a single Lean run (milliseconds) |
|
|
724
|
+
|
|
725
|
+
### v3 (paper-style md + planner agent + method library) defaults
|
|
726
|
+
|
|
727
|
+
Added/adjusted on top of all v2 parameters:
|
|
728
|
+
|
|
729
|
+
| Parameter | Default | Description |
|
|
730
|
+
|---|---|---|
|
|
731
|
+
| `verdictMode` | `forced` | v3 first makes a **near-consensus determination** (all results on the same side with a mean ≥0.85/≤0.15 takes the mean), otherwise `forced` = weighted by historical accuracy + rigor / `flat` = balanced (0.5). Fixes the v2 flat problem of misjudging "0.9 vs 1" as 0.5 |
|
|
732
|
+
| `planningHorizon` | 3 | Maximum number of actions in one plan by the planner agent ("the next n times") |
|
|
733
|
+
| `plannerEnabled` | true | false = fully use the built-in heuristic scheduling (planner agent disabled) |
|
|
734
|
+
| `plannerProvider` / `plannerModel` | empty | Planner agent model route (empty = inherit the root agent) |
|
|
735
|
+
| `plannerPersona` | empty | Persona/requirements injected at the start of the planner agent prompt |
|
|
736
|
+
| `planMinIntervalMs` | 30000 | Minimum interval between two planning calls (milliseconds); ignored when the system is idle and there is work |
|
|
737
|
+
| `plannerMaxFails` | 3 | The planner agent reaching this number of consecutive failures → automatic degradation to heuristics |
|
|
738
|
+
| `methodKeepIntervalMs` | 0 | Method Keeper periodic consolidation interval (0 = event-driven) |
|
|
739
|
+
| `methodKeepEvery` | 5 | Trigger one consolidation every N accumulated inventions/new propositions awaiting sedimentation |
|
|
740
|
+
| `methodAutoPromote` | false | Automatically promote project-level methods to the global library (false = manual gate) |
|
|
741
|
+
| `indexAutoRebuild` | true | Automatically rebuild `State/index.json` after each disk write (false = manual `vibe_math_index`) |
|
|
742
|
+
| `projectLockTimeoutMs` | 60000 | Project lock wait timeout (only one session may schedule a given project at any one time) |
|
|
743
|
+
| `methodKeeperPersona` | empty | Persona/requirements injected at the start of the method consolidation agent prompt |
|
|
744
|
+
| `formalVerify` | `'off'` | **Lean formal verification switch**: `'off'` no additional requirement (default)｜`'encourage'` encouraged (during verification, decide for yourself whether to formalize based on implementation difficulty)｜`'require'` mandatory (a true/false conclusion must first have a "Lean passed" or an explicit blocking record, otherwise it is recorded as undecided and enters the formalization todo list). Any illegal value falls back to `'off'` |
|
|
745
|
+
| `leanCommand` | `'lean'` | The Lean executable to run (e.g. `'lake'`) |
|
|
746
|
+
| `leanArgs` | `[]` | Additional arguments inserted before the file name (e.g. `['env','lean']` together with `leanCommand='lake'`) |
|
|
747
|
+
| `leanTimeoutMs` | `120000` | Upper limit for a single Lean run (milliseconds) |
|
|
748
|
+
|
|
749
|
+
### v4 (resident self-organization · experimental) defaults
|
|
750
|
+
|
|
751
|
+
Adjustable via `vibe_v4_set` (persisted to `State/settings.json`):
|
|
752
|
+
|
|
753
|
+
| Parameter | Default | Description |
|
|
754
|
+
|---|---|---|
|
|
755
|
+
| `residentCount` | 4 | Resident count (can be increased/decreased via `vibe_v4_add_member`) |
|
|
756
|
+
| `compactThreshold` | 66 | Reaching this resident context share triggers soft compaction (self-report instruction) |
|
|
757
|
+
| `compactAfterRounds` | 8 | Trigger one soft compaction every N accumulated rounds per resident (uncompacted) |
|
|
758
|
+
| `meetingKeepEvery` | 5 | Automatically trigger one sync meeting every N accumulated new artifacts |
|
|
759
|
+
| `maxParallel` | 3 | Upper limit on simultaneously awakened residents (framework-side concurrency gate, not an assignment) |
|
|
760
|
+
| `activityTimeoutMs` | 120000 | Idle heartbeat interval (only on timeout is a **self-driven** CHECKPOINT wakeup triggered, pushing residents to keep making progress; a failed wakeup automatically re-arms the heartbeat, ensuring the group never permanently stalls) |
|
|
761
|
+
| `stallAutoMeetingMs` | 360000 | **Stall auto sync meeting threshold** (tiered keep-alive B): when the team is idle with no new artifacts for longer than this duration, the framework automatically convenes a sync meeting so the residents decide the next route/division of labor themselves (the framework only facilitates, it does not assign) |
|
|
762
|
+
| `verdictMaxRounds` | 3 | Maximum number of rounds of debate after independent initial assessment in verification |
|
|
763
|
+
| `provider` / `model` | empty | **Resident LLM route** (empty = residents inherit the main agent's provider/model; previously declared but unused, actually wired up in v1.4.1) |
|
|
764
|
+
| `residentPersona` | empty | Persona/requirements injected at the start of each resident prompt |
|
|
765
|
+
| `toolAllow` / `toolDeny` | `[]` | **Resident tool permissions** (scoped `tools.restrict()` via `startContinuable`'s `toolFilter`; empty = inherit all tools; ⚠️ an empty `allow:[]` rejects all tools) |
|
|
766
|
+
| `formalVerify` | `'off'` | **Lean formal verification switch**: `'off'` no additional requirement (default)｜`'encourage'` encouraged (during verification, decide for yourself whether to formalize based on implementation difficulty)｜`'require'` mandatory (a true/false conclusion must first have a "Lean passed" or an explicit blocking record, otherwise it is recorded as undecided and enters the formalization todo list). Any illegal value falls back to `'off'` |
|
|
767
|
+
| `leanCommand` | `'lean'` | The Lean executable to run (e.g. `'lake'`) |
|
|
768
|
+
| `leanArgs` | `[]` | Additional arguments inserted before the file name (e.g. `['env','lean']` together with `leanCommand='lake'`) |
|
|
769
|
+
| `leanTimeoutMs` | `120000` | Upper limit for a single Lean run (milliseconds) |
|
|
770
|
+
|
|
771
|
+
### v5 (institute system · experimental) defaults
|
|
772
|
+
|
|
773
|
+
Adjustable via `vibe_v5_set` (persisted in the session log projection):
|
|
774
|
+
|
|
775
|
+
| Parameter | Default | Description |
|
|
776
|
+
|---|---|---|
|
|
777
|
+
| `academician` | `true` | Whether to appoint an academician (1 person) |
|
|
778
|
+
| `academicianLeads` | `true` | Whether to enable the academician's organizing/dispatching authority (turning it off degrades to v4-style pure self-organization, with only the institute office able to coordinate) |
|
|
779
|
+
| `memberMayRejectAssign` | `true` | Whether a member may **reasoned-object** to the academician's assignment (an objection does not block execution, but the reason is broadcast to the academician and the whole institute) |
|
|
780
|
+
| `researcherCount` | 3 | Number of resident researchers (at institute founding) |
|
|
781
|
+
| `quorumCap` | 3 | Upper limit of m; actually **m = min(quorumCap, number of enrolled voting members)** |
|
|
782
|
+
| `quorumMode` | `'m-unanimous'` | v5 calibration; switching to `'all-unanimous'` returns to v4's "all unanimous" |
|
|
783
|
+
| `verdictMaxRounds` | 3 | Maximum number of rounds of public debate after independent initial assessment |
|
|
784
|
+
| `maxTempPerMember` | 3 | Upper limit on temp workers **simultaneously** enrolled per academician/researcher (counted by enrollment, not cumulative — so swapping people is not restricted) |
|
|
785
|
+
| `maxTempTotal` | 12 | Upper limit on temp workers simultaneously enrolled across the whole institute |
|
|
786
|
+
| `compactThreshold` | 66 | Reaching this member context share (0–100) triggers compaction |
|
|
787
|
+
| `compactAfterRounds` | 8 | Or trigger one soft compaction every N accumulated rounds |
|
|
788
|
+
| `maxParallel` | 3 | Upper limit on simultaneously awakened members (framework-side concurrency gate) |
|
|
789
|
+
| `activityTimeoutMs` | 120000 | Idle fallback heartbeat interval (the main driver is a one-shot activity wait, not polling) |
|
|
790
|
+
| `stallAutoMeetingMs` | 360000 | Threshold for automatically convening a sync meeting on stall |
|
|
791
|
+
| `chatDigestMs` / `chatDigestMax` | 45000 / 12 | Time window and entry cap for batching group chat digests (direct messages/meetings/votes are not batched) |
|
|
792
|
+
| `meetingKeepEvery` | 5 | Automatically initiate one sync meeting every N accumulated new artifacts |
|
|
793
|
+
| `provider` / `model` | empty | Member LLM route (empty = inherit the institute office/main agent route) |
|
|
794
|
+
| `toolAllow` / `toolDeny` | `[]` | Resident staff tool permissions (⚠️ an empty `allow:[]` rejects all tools) |
|
|
795
|
+
| `tempToolAllow` / `tempToolDeny` | `[]` | Temp worker tool permissions (narrower than residents) |
|
|
796
|
+
| `staffPersona` | empty | Persona/requirements appended before each member charter |
|
|
797
|
+
| `formalVerify` | `'off'` | **Lean formal verification switch**: `'off'` no additional requirement (default)｜`'encourage'` encouraged (during verification, decide for yourself whether to formalize based on implementation difficulty)｜`'require'` mandatory (a true/false conclusion must first have a "Lean passed" or an explicit blocking record, otherwise it is recorded as undecided and enters the formalization todo list). Any illegal value falls back to `'off'` |
|
|
798
|
+
| `leanCommand` | `'lean'` | The Lean executable to run (e.g. `'lake'`) |
|
|
799
|
+
| `leanArgs` | `[]` | Additional arguments inserted before the file name (e.g. `['env','lean']` together with `leanCommand='lake'`) |
|
|
800
|
+
| `leanTimeoutMs` | `120000` | Upper limit for a single Lean run (milliseconds) |
|
|
801
|
+
|
|
802
|
+
Common controls: `vibe_v5_configure` (configure first) → `vibe_v5_start` (start work) → `vibe_v5_report` / `vibe_v5_status`; `vibe_v5_message` / `vibe_v5_meeting` / `vibe_v5_members` / `vibe_v5_hire` / `vibe_v5_fire` (temp worker) / `vibe_v5_add_researcher` / `vibe_v5_remove_researcher` (add/remove residents, institute office only) / `vibe_v5_pause` / `vibe_v5_resume` / `vibe_v5_stop`; slash command `/v5`.
|
|
803
|
+
|
|
804
|
+
---
|
|
805
|
+
|
|
806
|
+
## 📝 Checkpoint resume & manual intervention (two hard requirements)
|
|
807
|
+
|
|
808
|
+
- **Checkpoint resume**: all state is persisted to disk (v2: `VibeMath_State/*.json`; v3: `State/*.json`; **v5: the host-only projection units of the session logs**), and every subagent is a DSH **continuable persistent session** (the conversation is saved automatically by DSH). After a restart, open a new session → `vibe_math_resume` / `vibe_v4_resume` / `vibe_v5_resume` resumes the run. v2/v3 additionally use a **process epoch** to distinguish "same-process pause → resume" (keeping live subagents running) from "cross-process restart" (cleaning up stale tasks). **v3's md knowledge base is itself a narrative breakpoint** — on resume the agent continues writing from the tail of the research log / problem card / proposition card; **in v5 this role is taken by the projection units** — cross-process and same-process recovery go through the same code path, and when member sessions are rebuilt they are re-seeded by "reading back your own Progress/" (rather than making them start over).
|
|
809
|
+
- **Intervening mid-run**: `manual` mode suspends decisions at key points (v2: explorer/solver dispatch, verification verdicts; v3: the **plan approval gate** (after the planning agent produces a plan, it waits for your approve/reject), the verification verdict gate, and the **method promotion gate** (project methods → global library)); you can switch back to automatic at any time with `set_mode auto` (which automatically clears all pending decisions); you can `message_agent` / `interrupt_agent` any subagent. **v4/v5 are intervenable by nature**: leave a message for a member at any time (`vibe_v5_message`), convene a meeting, pause the whole institute, add or remove positions — members will see it on their next round.
|
|
810
|
+
- **Progress reporting**: **event-driven** by default — reports are written only when an event such as an agent status update occurs (v2: `Progress_Logs/report.json`; v3: `Progress_Logs/report.json` + `Logs/报告.md`, a paper-style human-readable summary; `reportMode` can be `file`/`push`/`both`, and `push` wakes up resident agents to report proactively via `subagents.sendMessage(root agent, resident subagent, …)` — `followup` is **not** a method of the `subagents` service, it is only a method of the `Agent` object); scheduled automatic reporting (interval in milliseconds) starts only when `reportIntervalMs` is set to >0. **v4/v5 progress reporting is "self-reporting within the institute"**: members write their progress into their own `Progress/`, and state key conclusions in the group chat (in v5 there are also readers of the mirrors `Institutes.md` / `Shared/TaskBoard.md`, the meeting minutes, the debate records, and `Problems/conclusion.md`).
|
|
811
|
+
|
|
812
|
+
---
|
|
813
|
+
|
|
814
|
+
## 📚 Specification documents
|
|
815
|
+
|
|
816
|
+
- **v2 (probability-driven)**: [`vibe-math-v2/实现方案.md`](vibe-math-v2/实现方案.md)
|
|
817
|
+
- **v3 (paper-style md + planning agent + method library)**: [`vibe-math-v3/实现方案.md`](vibe-math-v3/实现方案.md)
|
|
818
|
+
- **v4 (resident self-organization)**: [`vibe-math-v4/实现方案.md`](vibe-math-v4/实现方案.md)
|
|
819
|
+
- **v5 (institute system)**: [`vibe-math-v5/实现方案.md`](vibe-math-v5/实现方案.md) (text specification) · [`vibe-math-v5/架构图.md`](vibe-math-v5/架构图.md) (the full set of architecture diagrams)
|
|
820
|
+
- **v5 prompts and interaction corpus**: [`prompt-corpus-v5/prompt-corpus-v5.md`](prompt-corpus-v5/prompt-corpus-v5.md) (the verbatim text of every prompt the framework actually emits, so you can manually review whether identity/positions/interaction signatures are correct)
|
|
821
|
+
- **Four sets of Lean prompt corpora**: [`prompt-corpus-v2/formal-verify-v2.md`](prompt-corpus-v2/formal-verify-v2.md) · [`prompt-corpus-v3/formal-verify-v3.md`](prompt-corpus-v3/formal-verify-v3.md) · [`prompt-corpus-v4/formal-verify-v4.md`](prompt-corpus-v4/formal-verify-v4.md) (each covering off / encourage / **require** / fidelity branches / work rounds / receipt contract; the workspace is normalized to `<WS>` and the VibeMath root to `<VIBEMATH>`)
|
|
822
|
+
- **The persona source text of the four presets**: [`prompt-corpus-persona/persona-corpus.md`](prompt-corpus-persona/persona-corpus.md) (the prompts the main agent actually receives: which tools, which parameters, which slash subcommands; generated by `audit-persona-surface.test.mjs` and shipped with the package)
|
|
823
|
+
- **Lean formal verification (a contract shared by the four architectures)**: [`docs/formal-verification.md`](docs/formal-verification.md)
|
|
824
|
+
- **Test timing baseline and parallel run recipes**: [`docs/test-timing.md`](docs/test-timing.md) (`node tests/run-tests.mjs` runs all suites in parallel in ≈1.9 min; the probe scripts ≈2.6 min; every runner prints its elapsed time/speedup for choosing a strategy next time)
|
|
825
|
+
- **Static prompt-surface consistency (persona ↔ tool registry ↔ slash command hint/usage)**: [`audit-persona-surface.test.mjs`](tests/audit-persona-surface.test.mjs) (197 assertions, and generates [`prompt-corpus-persona/persona-corpus.md`](prompt-corpus-persona/persona-corpus.md) for manual review) + [`audit-persona-sensitivity.mjs`](tests/audit-persona-sensitivity.mjs) (11 sensitivity probes) — guarding "every registered tool must appear in the persona / every name in the persona must really be registered / the `prefix` and `text` blocks must match line by line / hint, usage, and the actual branch must agree in all three places"
|
|
826
|
+
- **Mandatory checklist for a full review**: [`AUDIT-CHECKLIST.md`](docs/AUDIT-CHECKLIST.md) (this repository's mandatory audit process; §1.9 specifically checks "whether the tool parameter schema can accommodate them")
|
|
827
|
+
- **Prompt/interaction invariants (all four sets together, re-checkable in one command)**: [`audit-prompt-invariants.mjs`](tests/audit-prompt-invariants.mjs) (157 assertions) — encoding, one by one, "the classes of prompt/tool-surface defects that have really occurred historically" as static invariants (abbreviated tool names, projecting a fidelity defect as 0, `defect` written only in the prompt but not implemented, a receipt contract missing `defect`, passing without a note, wrong field names, the `off` tier still being able to write state in its receipt, uncertain corpora, missing probes, **a tool's closed schema that cannot accommodate the parameters in its own documentation**, **keys that the schema declares at the parameter level but silently drops**). Adding `--self-probe` injects these defect shapes in memory and requires the corresponding invariants to **turn red** while the unmutated control run **stays green** (5/5); the script itself additionally carries six self-checks X5–X8b (the comment scanner must recognize regex literals — including regexes **after a keyword** such as `return /…/` — `//` inside strings must be preserved, stripping comments must not change line structure, and the parse-level criterion that "the four sets of source, with comments stripped, must still parse under `node --check`")
|
|
828
|
+
- **Specification ↔ code traceability (all four sets together)**: [`audit-spec-traceability.mjs`](tests/audit-spec-traceability.mjs) (94 assertions) — tools promised in `实现方案.md`/README must really be registered; the four Lean parameters must be accepted by both the documentation and the code
|
|
829
|
+
- **v5 static integrity**: [`audit-v5-integrity.mjs`](tests/audit-v5-integrity.mjs) (≈0.5 s) — functions called but never defined, reads of undeclared `params.*`, methods that do not exist on the session API, documented error codes that are never thrown, leftover development markers, plus a **parse-level self-check of the scanner** (it strips comments/strings/regexes before scanning, and the self-check guarantees that "the stripped source still parses under `node --check`" — 2.3.5 fixed exactly this blind spot where the scanner misread 30 lines); accompanied by [`audit-v5-sensitivity.mjs`](tests/audit-v5-sensitivity.mjs) (39 probes, and it passes only if they all turn red)
|
|
830
|
+
|
|
831
|
+
---
|
|
832
|
+
|
|
833
|
+
## ⚠️ Known limitations (deliberate simplifications)
|
|
834
|
+
|
|
835
|
+
**v2**:
|
|
836
|
+
- The installer has **versioned auto-update**: on every DSH start it compares the package version against the record in `<presetRoot>/.vibe-math-installed.json` — **as soon as the version changes (or on the first run of an older installation with no record) it replaces the managed files wholesale, regardless of whether they were modified**; replaced hand-edited originals are first backed up to `<presetRoot>/.vibe-math-backup/<old version>/<preset>/` and listed in the log. Within the same version it **rewrites no files at all** (restarting DSH will not rewrite the presets, nor disturb the generation index it records by mtime), and missing files are restored at any time. To force a full reinstall: delete the `~/.dsh/.agent-presets/vibe-math-v2`, `vibe-math-v3`, `vibe-math-v4` and `vibe-math-v5` directories and restart DSH.
|
|
837
|
+
- **These four directories are owned by the installer**: deleting any file in them or the whole directory only leads to it being restored on the next DSH start (which is exactly why the "force a full reinstall" above works). To get rid of them entirely, uninstall this package (`dsh plugin --profile <your profile> remove dsh-vibe-math`).
|
|
838
|
+
- A `flat` verdict directly rules `0.5` when the debate is inconsistent (high-confidence disagreement such as 0.9 vs 1 is also misjudged as 0.5 — **v3 has fixed this with the near-consensus rule**); `forced` weights by historical accuracy + confidence.
|
|
839
|
+
- Problems/propositions with `never` priority are **never scheduled**, and do not block strict termination (they count as voluntarily abstaining).
|
|
840
|
+
- The four preset files are mutually independent and can coexist; only one preset can be selected in a given session at a time.
|
|
841
|
+
|
|
842
|
+
**v3**:
|
|
843
|
+
- **Soft specification rather than zero specification**: the md knowledge base only enforces the 4–7 anchor lines at the head of an object (`- ID/类型/状态/概率/优先级/依赖/...`) and the entry title line (`### 解法/证明/证伪 N｜标题｜概率X｜状态Y`), so that the scheduler can index reliably; the body is entirely free paper-style prose, and the scheduler never parses the body. Manually editing the anchors may cause index drift (the scheduler keeps the last valid index and warns).
|
|
844
|
+
- **The planning agent is an enhancement, not a requirement**: when `plannerEnabled=false` or the planning agent fails repeatedly (`plannerMaxFails`), it automatically falls back to v2-style heuristic scheduling; the `planMinIntervalMs` cooldown takes effect while subagents are in flight (when the system is idle and there is work, it plans immediately).
|
|
845
|
+
- **Trust tiers in the method library**: a method card's `可信断言` may only link IDs that have entered `Verified/`; all other content of a method entry (including unverified strategies/intuitions/heuristics) is treated as **empirical reference** and must not be cited as a theorem.
|
|
846
|
+
- **Project lock**: only one session may schedule a given project at a time (starting a second session reports "occupied by session X"); the lock is released automatically on pause/termination/when everything is resolved.
|
|
847
|
+
- **Near-consensus verdicts**: when all verifier results fall on the same side and the mean is ≥0.85/≤0.15, the mean is taken (e.g. 0.9 vs 1 → 0.95); otherwise `forced` weighting / `flat` rules 0.5 — this fixes the problem in v2 where conclusions that were "mathematically correct but formally flawed" were misjudged as uncertain.
|
|
848
|
+
|
|
849
|
+
**v5**:
|
|
850
|
+
- **The framework never assigns tasks**: this is a hard design boundary, not a feature that has yet to be implemented. The creation and allocation of tasks belong to **institute self-governance**
|
|
851
|
+
(academicians decompose and assign, members claim on their own); the framework only provides the **coordination tools** — task board, messages, and meetings.
|
|
852
|
+
- **`≥ m` agreement ≠ mathematically proved**: the quorum only guarantees that "a consistent judgment has been reached within the institute", not that the conclusion is really correct.
|
|
853
|
+
The depth of truth-seeking rests on the members' own derivations and the paper trail in the debate records; objects that do not reach quorum are **kept in the library with their average probability attached** and are not forcibly ruled true or false.
|
|
854
|
+
- **The consistency quorum is not "majority rule"**: any single opposing boolean vote blocks a conclusion, and abstention helps neither truth nor falsehood.
|
|
855
|
+
To converge more easily, lower `quorumCap` or reduce the number of members with voting rights; for stricter behavior, switch to `quorumMode: "all-unanimous"`.
|
|
856
|
+
- **A member whose round never ends will not be forcibly released** (the same boundary as v4): the heartbeat re-arms it every time,
|
|
857
|
+
so the scheduler will not freeze permanently; when manual intervention is needed, use `vibe_v5_fire` (temp worker) or have the institute office add or remove positions.
|
|
858
|
+
- **Meetings and verification are strictly mutually exclusive**: while one is in progress, the other queues/is held. Therefore "concluding an object on the spot in a meeting" first queues,
|
|
859
|
+
and only after the meeting closes does it go through the full voting procedure.
|
|
860
|
+
- **After `resume`, the round counter restarts from 1** (in-memory state, used only for throttling and compaction hints); the authoritative progress lives in the members' own `Progress/`.
|
|
861
|
+
- **A member's charter is an onboarding snapshot**: upgrading this package will not rewrite the charters of members in an institute that is already running (they keep the version frozen at onboarding).
|
|
862
|
+
If you need a new charter, open a new institute in a new session; the projection state and file tree need no migration.
|
|
863
|
+
- **Installer behavior is the same as v2** (versioned auto-update; as soon as the version changes it replaces the managed files wholesale, backing up the originals first, and the `vibe-math-v5` directory is likewise managed).
|
|
864
|
+
- **Lean formalization requires a Lean toolchain on the host**: the framework neither bundles nor downloads one; without a toolchain the three Lean tools truthfully return
|
|
865
|
+
`LEAN_NOT_FOUND`, and formalization code can still be written down and archived, but verification cannot be executed.
|
|
866
|
+
- **The gate in `require` mode is "shelving" rather than "deadlock"**: true/false conclusions that lack formalization are recorded as undecided + entered into the formalization to-do,
|
|
867
|
+
and the institute keeps moving forward (the same trade-off as "kept in the library with average probability when quorum is not reached"), so it will not be stuck forever on one object.
|
|
868
|
+
|
|
869
|
+
---
|
|
870
|
+
|
|
871
|
+
## 📄 License
|
|
872
|
+
|
|
873
|
+
MIT
|