@local/dsh-plugin-arch-loop
ralph：作为 DSH 工具的可恢复全新上下文循环（构建/设计）
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:cperion/ralphi#1bbd0ee4c59038989179b6b16112657425595c17Plugin Arch Loop 以 @local/dsh-plugin-arch-loop 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
ralph — one resumable fresh-context loop for both harnesses. Two protocols
behind one argument:
kind | Goal | Round | Final audit |
|---|---|---|---|
build (default) | make a real change in a repo | one unit of work, verified and committed | independent verifier runs the project's checks against the goal |
design | find the simplest target architecture | one design investigation | independent implementability audit |
One call creates (or resumes) docs/ralph/<slug>/ inside the project repository,
runs N rounds with a fresh agent each round, then runs the audit. State is
committed with the code; STATE.json survives interruption.
No manual setup: no template copying, no files to create.
ralph({ goal: "Add cursor pagination to GET /items, tests included", rounds: 8 })
ralph({ kind: "design", goal: "Design the module structure and data types for X", rounds: 16 })
| Argument | Meaning |
|---|---|
goal | Objective. For build: what must be true when done. For design: the problem, behavior, constraints, non-goals. |
kind | build (default) or design. |
constraints | Hard constraints only: bounds, compatibility, runtime, invariants. |
paths | Existing files/directories the work or design must account for. |
rounds | Rounds to run in this call. Default 24, ceiling 64; later calls add more. |
name | Stable directory name. Reusing it resumes that run. |
project | Repository root that owns docs/ralph/. Defaults to the git root containing the workspace, else the workspace. |
Long-running: the call blocks the turn. Cancelling preserves every completed
round; call again with the same name and goal to continue.
Inside the project repository, so the record is versioned with the code and committed by the workers:
docs/ralph/<slug>/
STATE.json controller-owned resume marker (next / in-progress round)
rounds.jsonl per-round reports (controller-owned)
runs.jsonl one record per call (controller-owned)
AUDIT.json independent verification result
rounds/ per-round report files (pi port)
LOG.md append-only per-round record
kind=design additionally:
CONTRACT.md goal + constraints + paths
ARCHITECTURE.md best-known design; changes need evidence
QUESTIONS.md material open questions
experiments/ prototypes, benchmarks, re-derivations
kind=build additionally:
GOAL.md objective + constraints + paths
PLAN.md current approach, done / next
NOTES.md durable findings, commands, chosen interpretations
work/ scratch files
build: read GOAL.md, PLAN.md, NOTES.md, LOG.md, inspect the repo and
git status; pick the highest-value unit (or the smallest step that resolves the
biggest unknown); implement it; run the project's checks and fix damage; commit;
update the three files; report {action, summary, evidence, next, blocked}.
The audit is a fresh verifier that runs the checks itself and returns
{satisfied, evidence, gaps} — it does not trust the log.
design: read the four design files; write three candidate questions, rank by
materiality, pursue the most material one; choose continue, simplify,
experiment, or rederive (contract-only, independent design first); update
the files, commit, report {mode, question, evidence, decision, next}. The audit
tries to implement the contract and reports the first place it must invent
semantics.
STATE.json is written atomically before and after every round. If the harness
or the machine stops mid-call, call again with the same name, kind, and
goal:
git log --oneline -- docs/ralph/<slug>
git diff <start>.. -- docs/ralph/<slug>/
kind=build: read AUDIT.json first — satisfied=false means the goal was not
met, gaps says what is missing. kind=design: AUDIT.json material=true
means the design still has an implementability gap.
Both harnesses register the same tool name, ralph.
Installed in a DSH profile as the bundle @local/dsh-plugin-arch-loop (the
package name is historical; it now provides ralph). Install it with
plugin_manager / install_bundle pointing at this repository, then restart
DSH.
The tool can be registered at host scope (available to every agent), inside a
preset, or both. If the shipped tool-ralph row is enabled in the same preset,
disable it: the scoped built-in ralph would shadow this one.
After editing plugin.js or either patch, restart DSH: the live process imports
a module generation once.
Config in cordis.patch.yml:
| Field | Default | Meaning |
|---|---|---|
provider | spawn | Fresh subagent provider; must support structured output. |
maxRounds | 64 | Per-call ceiling. |
defaultRounds | 24 | Used when rounds is omitted. |
Extension in pi/. Install:
pi install ./pi
Each round spawns a fresh pi child with built-in tools only
(read,write,edit,bash,grep,find,ls), in the project root, inheriting the
parent model and thinking level. The child writes rounds/rNNN.json; the tool
validates it. /reload after editing.
rederive blindness (design) is procedural, not enforced.