clearai-dsh

English · 中文

From answers to evidence. From evidence to improvement.

ClearAI is a native DSH plugin that brings the Epistemic Loop to DeepSeek Harness.

A language model can produce a plausible answer in seconds. ClearAI is about what happens next: stating what would test the idea, running the work, recording what happened, evaluating the evidence, and revising what is believed — so that a conclusion has to earn its status instead of asserting it.

Let the model explore. Let the mechanism protect the boundary of fact.

---

Install

One command, and it needs nothing but Node:

npx clearai-dsh install

It resolves the DSH CLI (from your PATH, or through npx), installs the plugin into your web profile, and reads the composed config back so you are not taking "success" on faith. Underneath it is the host's own install, so this is the same command: dsh plugin --profile web add clearai-dsh.

Restart dsh web after that (npx @deepseek-ai/dsh web). Both halves of the plugin are cached inside the running process, so refreshing the browser is not enough. Then open a session and pick ClearAI in the preset picker.

If it stops because pnpm is not on your PATH: DSH manages a profile by driving pnpm, so it needs one. Install it with npm install -g pnpm, or your system package manager. Prefer that to corepack enable, which installs a version router rather than pnpm, and the corepack shipped with current Node can fetch a pnpm it is unable to launch.

From a checkout (development, not the install path):

npm test                       # 13 suites — the list lives in test/run.sh
node tools/build-package.mjs   # assemble dist/ from source
node tools/verify-package.mjs  # rebuild and compare byte-for-byte
node tools/verify-clean-install.mjs   # install into an empty DSH_HOME through the real CLI
node docs/diagrams/build.mjs   # regenerate the loop diagram (needs google-chrome)

dist/ is generated and never committed. See DSH integration.

Why this is not just another agent loop

Most agent loops track one thing: whether the task is done. The Epistemic Loop also tracks how a conclusion came to be trusted:

	Task loop	Epistemic Loop
Driving question	What do I do next?	What do we know, and on what grounds?
Completion	The model declares it	The system computes it from delivered evidence
Judgment	Whoever did the work	Separated — above a level, the doer cannot judge its own result
Failure	Deleted, retried, forgotten	Kept: a refuted hypothesis is a result, not noise

ClearAI implements that loop as mechanism, not advice. State is derived from the session record rather than stored twice, progress and phases are computed, and the tools the model holds contain no field in which it could declare a step complete.

ClearAI does not claim recursive self-improvement. It provides the epistemic substrate that a self-improving system would need: an honest account of what changed, what supports it, who evaluated it, and what failed. See Positioning and the OpenRSI survey for where that boundary sits.

The loop, stage by stage

The Epistemic Loop has seven stages. At runtime, these stages compress into four beats—plan, execute, observe, reflect—for a simpler operating rhythm.

Stage	What the model does	What the mechanism guarantees	What you see
Frame	Bounds the question, assumptions, scope, and outcome	The inquiry starts with an explicit frame	Scope and assumptions
Hypothesize	Records candidate explanations or routes	Propositions remain distinct from admitted facts	Hypotheses
Plan	Defines executable, evidence-bearing steps and criteria	Completion is advanced only through governed paths	Inspectable plan
Observe	Runs permitted work and records what happened	Admission checks eligibility, never truth	Observations and artifacts
Verify	Tests observations against the stated criteria	Verification remains tied to the proposition and its limits	Checks and evidence
Evaluate	Assesses support, uncertainty, and conflicts	Higher-level work can require independent evaluation	Evaluation and basis
Record and act	Preserves the result and chooses the next bounded action	History is retained; unresolved claims stay qualified	Facts, limits, and next step

Full version: The Epistemic Loop

What it looks like

The plugin contributes three surfaces on top of stock DSH: a deliverables view in the middle column, and worldlines / propositions & facts / external brain panes on the right.

Propositions and facts — every claim is one row: its current standing, its level, and who judged it. Confirmed conclusions move to the shelf with their scope; refuted ones stay, with the evidence that refuted them.

Worldlines — when two routes genuinely disagree, they run as separate branches with their own readings; the record keeps the ones that lost, and adoption is a human decision.

Deliverables — the middle column shows what a plan declared and what actually exists on disk, and refuses to conflate the two.

External brain — skills and memory appear as native DSH entries in one merged catalogue, with the usage of this session next to them.

Where it lands in DSH

ClearAI adds an epistemic layer on the DSH composition surface — one host package, one agent preset, one client module. The DSH engine is not modified. /goal /plan /evidence /worldline /plan-review are the human's read-only state windows in the / menu (computed from the ledger on the spot); todo, subagents, workflows and model switching are DSH-native — working style is unbounded, but none of it can write the authoritative ledger (the authority boundary is pinned by tests).

Cases

Three cases, written to show what the loop does on questions where the honest answer is not a clean result:

• AI for Science — convergence order of WENO reconstructions near critical points, and what "we could not resolve it" honestly means.
• Mathematics — keeping finite numerical evidence strictly separate from proof.
• Physical-world process experiment — keeping the loop intact when execution leaves the computer.

They are illustrations of the mechanism, not shipped run records.

Documentation

• Positioning
• Design principles
• Soul map: principle → mechanism → test
• Glossary
• Loop philosophy · Verification ontology
• Known gaps · Release verification
• Convergence and slimming plan · Full-coverage design · Execution progress

Work attribution

This project is developed and maintained under the work attribution of 基点起源.

Star history

License

Apache-2.0. See LICENSE.

Status

This repository is the DSH-native ClearAI plugin library: a local-first epistemic workspace delivered through DSH. What is not implemented, and what has not yet been verified in a real browser, is listed explicitly in known gaps.