clearai-dsh 0.1.7 → 0.2.1

package/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 All notable changes to this project are recorded here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] — 2026-09-18
+
+**知识任务是循环的原生行为,不是另一个模式。** 本体、实体、认识论早就在,但普通研究的最短路径仍然是「检索 → 总结 → 写报告」——要建本体得用户先想起来说一句。这一版修的是**接线缺口**:把知识任务的判据做成结构的(目标还开着 + 带着登记过的假设),系统自己进知识模式;并把图从手写 SVG 换成 React Flow,给了它一个真正的全屏工作区。
+
+### Added
+
+- **知识模式(分诊)**:判据是**结构的**——目标还开着,而且它带着登记过的命题。立约(`SetGoal`)本身就是模型已经做出的承诺;普通问答从不立约,于是从不进这一档(**零成本契约**)。词面启发式猜错了没人能复核,结构判据可以。
+- **知识预检**:把「已知」自动送到模型面前——只读、有界、**词面命中不猜语义**;每条读数说得出它来自哪条事实。
+- **缺口读数**:从已有事实算出还缺什么形态,每条指得出一个能补的动作。真跑的反直觉结论:改变行为的其实是**缺口的可见性**,不是门——所以两者都留(可见性让它想做,门不让它绕过)。
+- **知识门**:结案之前、派评估者之前拦住**没有形态的核心结论**——纯散文不许升格。
+- **知识 Inspector**:点节点或边 → 定义 / 关系 / 断言 / 证据链 / 登记与修订史;「按此筛选」是详情里的**显式动作**,不猜你点它的意思。新增宿主只读路由 `/api/clearai/inspector` 与行为测试。
+- **图谱工作区**:图带可展开成全屏工作区,布局是力导向(知识图谱的原生形状);渲染交给 React Flow(`@xyflow/react` 12,vendor 行随构建走,与 `dist/` 同一条纪律)。
+- **哲学 P6**:「本体生长是循环的原生行为,不是另一个模式」——写进[循环哲学](docs/loop-philosophy.zh-CN.md)与[认识论循环](docs/epistemic-loop.zh-CN.md)(中英)。
+- **素材工具** `tools/panel-shots.mjs`:折一场真会话 → 挂**真组件** → 真 Chrome 截图(与 `tools/graph-shots.mjs` 同一条口径)——面板截图从此可复现,不用人去界面里手点。
+
+### Changed
+
+- **图 DTO 统一**:图带与工作区共用同一份投影,判据只有一处(`fold` → `view()` → `graphProjection()`);「同一份账本 ⇒ 同一张图」是投影的性质。
+- **预设描述**收敛成一句中英并排:「利用认识论循环构建可信本体。Build a trustworthy ontology through the epistemic loop.」——名册只有这两行元数据,宿主不会替我们本地化,所以只能自己写死。
+- **README 的「安装」改为「安装与使用」**:写明怎么在模式选择器里切到 `ClearAI`(默认标准模式不挂认识论循环),并把本体图 / 图带 / Inspector 的真机截图放进去。
+- 营销物料换掉全部陈旧面板截图:知乎稿与 docx、小红书 9 张卡片改用真机会话的投影(统计同步为 15 套件 1618 条断言 · 29 个意图工具 · 6808 行内核 · 50 种事件分支)。
+
+### Fixed
+
+- **命题身份在修订时被重新签发**:同一句话在 id 空间里躺着两份读数(一份「已支持」、一份「未触及」),真会话的卡实测 4 条主张显示成 6~8 行。现在主张原文不变就复用原 id,换了主张才发新 id;并补上 `hypothesis/superseded` 一直缺席的生产者。
+- **节点拖不动**(两次):受控 `nodes` 没接 `onNodesChange`;拖动键写成了对象,`[object Object]` 查不到。
+- **React Flow 是 forwardRef 对象,不是函数**——守卫把合法组件判成「没装上」;并改为同作用域注入,不再依赖运行时模块行。
+- **图带收不到 sessionId**;时间戳不再显示 1970。
+- **工作区读面有主人**:子会话结构上写不进词汇 / 事实货架。
+- 力导向布局的四个真机缺陷(评估者独立复核后逐条修掉)。
+
+## [0.2.0] — 2026-09-17
+
+**研究的产品形态是本体。** 认识论循环是本体的生产工艺,事实是它的内容单位——真值方向不变(世界 → 证据 → 事实 → 长成本体),所以**本体不裁决任何事,它只收留被裁决过的东西**。别的知识图谱靠抽取与断言堆边;这里的每一条边都要通过循环挣得。
+
+### Added
+
+- **领域本体(语言层)**:六个账本事件(`ontology/term_added / predicate_added / *_revised / *_deprecated`)折成 `state.lexicon`;概念与谓词带依据接纳、版本化修订、黏性废止(**没有删除**);语义变化必须换 id。判据只有一份(`ui/lib/domain-language.js` 纯函数),模型工具、人门动词与折法同源。
+- **七个具名动词**:`RegisterTerm / RegisterPredicate / ReviseTerm / RevisePredicate / DeprecateTerm / DeprecatePredicate / QueryKnowledge`(意图工具 22 → 29 件)。
+- **类型化断言**:假设可带 `assertions`(主词–谓词–宾语;值形态 statement/quantity/formula/code/reference + 关系宾语 instance);**提供即严校**(引用存在、形态合域、同一事实自洽,一律落账之前拒),不提供放行(旧事实显示「未结构化」,不回溯改写);升格时断言随事实定型,事实按 id 关联假设(修掉按文本匹配)。
+- **冲突只暴露,不裁决**:同一单值谓词、同一主体、不同客体 ⇒ 派生一对冲突;卡片与货架各说一遍;不进闸门、不动任何一侧;处置走既有的人门。
+- **本体格(中栏)**:图带(本体图|实体图、缩放平移、全景、点节点=按概念过滤)、断言芯片就地展开词条卡、冲突行+内联标记、过滤 N/M 行、折叠的词汇维护区(含登记抽屉与废止入口——经人门通道,判据与模型工具同一份);零成本契约:没有词条时这一格与从前逐像素相同。
+- **词汇货架** `clear/ontology/domain.md`(概念/谓词/Mermaid 图/引用统计/废止缘由/冲突),幂等渲染,`clear/ontology/` 进系统拒写清单。
+- **提示词** `clearai/domain-language`(hard;24 段定义 / 23 段在场)。
+
+### Changed
+
+- **定位**:「认识论工作台」→「基于认识论的本体研究平台」;口号「从证据,到改进」→「从证据,到本体」;中栏「事实」格更名「本体」格,事实货架更名**本体货架**(视图 id `clearai-facts` 与账本词汇不动——只有用户可见名词收敛)。
+- 术语收敛:**本体图**(原词汇图)/ **实体图**(原知识图,「知识图谱」是业界词,指整体)。
+- 事实货架 INDEX.md 头改「本体内容(已确立条目…)」。
+- **README 整体重塑**:口号「你的研究，长成一个本体」;叙事从「认识论循环工作台」转向
+  「本体发现与探索平台」——先讲你得到什么(本体),再讲凭什么可信(循环,折叠在 details 里);
+  面板截图换为本体格为主角(待截);安装与案例后移。定位/术语表/CHANGELOG 同步。
+
+### Fixed
+
+- e2e 的会话目录 slug 不认中文路径(宿主把 亨通 编码为 ~4EA8~901A):真项目(中文工作区名)此前必被误报成一排 ✗。
+- `--installed` 一次性形态:ClosePlan 之后交出回合即结束 ⇒ CloseGoal 必须同回合连续调用(已写进 e2e 记账)。
+
 ## [0.1.7] — 2026-09-16
 
 **同一件事实只有一个来源。** 一轮"按真值表逐条核对 → 按症状打补丁 → 发现自己在打补丁 →

package/README.md

@@ -7,136 +7,151 @@
 
 <p align="center"><b>English</b> · <a href="README.zh-CN.md">中文</a></p>
 
-**From answers to evidence. From evidence to improvement.**
+**Your research, grown into an ontology.**
 
-ClearAI is a **native DSH plugin** that brings the Epistemic Loop to DeepSeek Harness.
+ClearAI is an **ontology discovery and exploration platform**, built on two core concepts:
 
-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.
+- **Domain ontology** (what you get) — your project's own vocabulary, the knowledge entries established through the loop, and their graphs. At the end of a research session you hold a continuously growing knowledge structure, retrievable next round by concept.
+- **Epistemic loop** (how you get it) — a disciplined seven-stage path: frame, hypothesize, plan, observe, verify, evaluate, record. Every edge is tested by evidence and independent evaluation.
+
+> Other knowledge graphs pile up edges by extraction and assertion; here every edge has to be earned through the loop.
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/diagrams/epistemic-loop-hero-dark.png">
-  <img src="docs/diagrams/epistemic-loop-hero.png" alt="The Epistemic Loop" width="1200">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/diagrams/ontology-hero-dark.png">
+  <img src="docs/diagrams/ontology-hero.png" alt="The epistemic loop (left) growing a domain ontology (right)" width="1200">
 </picture>
 
-> Let the model explore. Let the mechanism protect the boundary of fact.
+*Left: the Epistemic Loop — seven stages. Its emerald fact dot is also the first node of the domain ontology on the right. Right: the ontology graph — dark is a concept, light is a value form, emerald an instance; the instance carries two contradictory assertions — **the two readings are tinted amber**, marking that they do not agree. The system reports the conflict; retracting or keeping is a human decision.*
 
 ---
 
-## Install
+## What you get: a domain ontology
 
-One command, and it needs nothing but Node:
+A **domain ontology** that grows as you research:
 
-```bash
-npx clearai-dsh install
-```
+- **Vocabulary** — the language your project speaks: concepts, predicates, value forms, units. Conventions themselves carry no truth value; sentences written with them do.
+- **Established entries** — knowledge that passed the loop: each with its boundary, support level, and evidence chain. Each entry states its boundary explicitly, so it can be cited safely.
+- **Ontology graph and entity graph** — what your domain looks like (structure), and what you have actually verified (the state of play).
+- **Conflict readings** — contradictory conclusions surface automatically; the system reports them, and retracting or keeping is your decision.
 
-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`.
+## How you get it: the Epistemic Loop
 
-**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.
+Most agent loops track one thing: whether the task is done. The Epistemic Loop also tracks **what makes a conclusion trustworthy**:
 
-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.
+| | Task loop | Epistemic loop |
+|---|---|---|
+| Driving question | What next? | What do we know, and on what grounds? |
+| Completion | The model declares it | The system computes it from delivered evidence |
+| Verdict | Whoever did it, says so | Separated — above a level, the doer cannot judge themselves |
+| Failure | Deleted, retried, forgotten | Kept: a refuted hypothesis is a result, not noise |
+| What accumulates | A chat transcript | **An ontology**: every edge earned through the loop |
 
-From a checkout (development, not the install path):
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/diagrams/epistemic-loop-hero-dark.png">
+  <img src="docs/diagrams/epistemic-loop-hero.png" alt="The Epistemic Loop" width="1000">
+</picture>
 
-```bash
-npm test                       # 14 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)
-```
+*Inside the ring is the instrument's read-out: the L0–L4 axis, the **pre-registered** threshold as a dashed line, and five observations with error bars — the supported one filled, the inconclusive drawn as a dashed circle, the refuted left in place with a slash through it (nothing is deleted). The emerald dot at the opening is the one reading that crossed the threshold and settled as a fact.*
 
-`dist/` is generated and never committed. See [DSH integration](docs/dsh-integration.md).
+At runtime, the seven stages compress into four beats — plan, execute, observe, reflect. State is derived from the session record with no second store; 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 a self-improving system would need. See [Positioning](docs/positioning.md) and the [OpenRSI survey](docs/research-openrsi.md).
 
-## 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**:
+## Install and use
 
-| | 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 |
+```bash
+npx clearai-dsh install
+```
 
-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**.
+Restart `dsh web` afterwards (`npx @deepseek-ai/dsh web`), then **create a session and switch to the `ClearAI` mode in the picker at the top**:
 
-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](docs/positioning.md) and the [OpenRSI survey](docs/research-openrsi.md) for where that boundary sits.
+1. Open `dsh web` and click "New session";
+2. Click the current mode name at the top (default: **Standard mode**) to open the preset list;
+3. Pick **ClearAI** — its card reads "利用认识论循环构建可信本体。Build a trustworthy ontology through the epistemic loop.";
+4. Just ask your question. Ordinary Q&A runs as usual; once you set a goal and register hypotheses, the system enters knowledge mode by itself: known facts come to you, gaps stay visible, and conclusions earn their place.
 
-## The loop, stage by stage
+<picture>
+  <img src="docs/shots/zh/jepa-ontology.png" alt="The knowledge graph in ClearAI mode" width="820">
+</picture>
 
-The Epistemic Loop has seven stages. At runtime, these stages compress into four beats—plan, execute, observe, reflect—for a simpler operating rhythm.
+*The ontology graph in ClearAI mode — this real session grew 21 concepts and 9 predicates; the same ledger always yields the same picture. (UI shown is Chinese.)*
 
-| 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 |
+If pnpm is not on PATH: `npm install -g pnpm` (do not `corepack enable` — it installs a version forwarder that may download a pnpm it cannot launch).
 
-Full version: [The Epistemic Loop](docs/epistemic-loop.md)
+From the repository:
 
-## What it looks like
+```bash
+npm test                       # 15 suites
+node tools/build-package.mjs   # assemble dist/ from source
+node tools/verify-package.mjs  # rebuild on the spot, byte-compare
+node docs/diagrams/build-hero.mjs   # redraw the product hero (needs google-chrome)
+```
 
-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.
+`dist/` is generated and never committed. See [DSH integration](docs/dsh-integration.md).
 
-**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.
+---
 
-![Propositions and facts](docs/shots/en/facts.png)
+## What it looks like
 
-**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.
+The middle column has two switchable views: **Deliverables** and **Ontology**. The right sidebar: **Worldlines** and **External Brain**.
 
-![Worldlines](docs/shots/en/worldlines.png)
+**Ontology** — this view is your knowledge home. At the top, a **graph band**: the ontology graph (what your domain looks like) and the entity graph (what you have actually verified) toggle with one click; clicking a node or edge opens the **knowledge inspector** (definition / relations / assertions / evidence chain / history), and "filter by this" is an explicit action inside the detail view. Below that, the **ontology shelf**: established entries, each with assertion chips (click to see what the term means), boundary, and support level; contradictions surface automatically. The vocabulary maintenance block sits collapsed at the bottom — it auto-expands when a language exists before any sentence does.
 
-**Deliverables** — the middle column shows what a plan declared and what actually exists on disk, and refuses to conflate the two.
+<picture>
+  <img src="docs/shots/zh/jepa-band.png" alt="The graph band: ontology graph and entity graph" width="820">
+</picture>
 
-![Deliverables](docs/shots/en/deliverables.png)
+*The band — the ontology graph and the entity graph share one deterministic projection, so the same ledger always yields the same picture (captured from a real session: 21 concepts, 9 predicates).*
 
-**External brain** — skills and memory appear as native DSH entries in one merged catalogue, with the usage of this session next to them.
+<picture>
+  <img src="docs/shots/zh/jepa-inspector.png" alt="Knowledge inspector: definition, relations, assertions, evidence chain" width="820">
+</picture>
 
-![External brain](docs/shots/en/skills.png)
+*Open any node or edge: definition, relations, assertions, evidence chain, registration and revision history, all in one place. (UI shown is Chinese.)*
 
-## Where it lands in DSH
+**Worldlines** — when two routes genuinely disagree, they run as separate branches with their own readings; the losing one stays on record, and adoption is a human press.
 
-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).
+**Deliverables** — the middle column keeps "what the plan declared" and "what actually exists on disk" apart.
 
-![ClearAI in DSH](docs/diagrams/loop-to-dsh-planes.svg)
+**External Brain** — skills and memory as DSH-native entries in one merged catalogue.
 
-## Cases
+---
 
-Three cases, written to show what the loop does on questions where the honest answer is not a clean result:
+## Cases
 
-- [AI for Science](docs/cases/ai4sci.md) — convergence order of WENO reconstructions near critical points, and what "we could not resolve it" honestly means.
-- [Mathematics](docs/cases/mathematics.md) — keeping finite numerical evidence strictly separate from proof.
-- [Physical-world process experiment](docs/cases/physical-experiment.md) — keeping the loop intact when execution leaves the computer.
+- [Physical-world process experiment](docs/cases/physical-experiment.md) — sensor thermal drift: the full chain from raising terms to a conflict surfacing
+- [AI for Science](docs/cases/ai4sci.md) — convergence order of WENO reconstructions, and what "we could not resolve it" honestly means
+- [Mathematics](docs/cases/mathematics.md) — keeping finite numerical evidence strictly separate from proof
 
-They are illustrations of the mechanism, not shipped run records.
+---
 
 ## Documentation
 
-- [Positioning](docs/positioning.md)
-- [Design principles](docs/design-principles.md)
-- [Soul map: principle → mechanism → test](docs/soul-map.md)
-- [Glossary](docs/glossary.md)
-- [Loop philosophy](docs/loop-philosophy.md) · [Verification ontology](docs/verification-loop.md)
+- [Positioning](docs/positioning.md) · [Domain ontology design](docs/domain-ontology.md)
+- [Epistemic loop](docs/epistemic-loop.md) · [Verification ontology](docs/verification-loop.md) · [Loop philosophy](docs/loop-philosophy.md)
+- [Design principles](docs/design-principles.md) · [Soul map](docs/soul-map.md) · [Glossary](docs/glossary.md)
+- [Knowledge-native loop ledger](docs/optimization/knowledge-native-loop.zh-CN.md) (this round: triage / preflight / knowledge gate / graph / inspector; zh-CN)
+- [Development plan](docs/optimization/domain-ontology-plan.md) (with real-run evidence from the Hengtong project)
 - [Known gaps](docs/known-gaps.md) · [Authority map](docs/authority-map.md) · [Release verification](docs/release-verification.md)
-- [Convergence and slimming plan](docs/optimization/plan.md) · [Full-coverage design](docs/optimization/epistemic-coverage.md) · [Execution progress](docs/optimization/progress.zh-CN.md)
+
+## Where it sits in DSH
+
+ClearAI adds the epistemic layer on DSH's **composition plane** — one host package, one agent preset, one client module, with **zero changes to the DSH engine**. Working style is unrestricted, but nothing outside the governed path can write to the authoritative ledger (pinned by tests).
 
 ## Work attribution
 
-This project is developed and maintained under the work attribution of [基点起源](https://jidianqiyuan.com/).
+This project's work attribution unit is [Jidian Qiyuan](https://jidianqiyuan.com/).
 
-## Star history
+## Star History
 
 [![Star History Chart](https://api.star-history.com/svg?repos=Clearailhc/clearai-dsh&type=Date)](https://star-history.com/#Clearailhc/clearai-dsh&Date)
 
 ## License
 
-Apache-2.0. See [LICENSE](LICENSE).
+Apache-2.0, see [LICENSE](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](docs/known-gaps.md).
+A local-first ontology discovery and exploration platform delivered as a DSH plugin. What is not yet implemented, and what has not been verified in a real browser, is written in [Known gaps](docs/known-gaps.md).

package/README.zh-CN.md

@@ -7,48 +7,34 @@
 
 <p align="center"><a href="README.md">English</a> · <b>中文</b></p>
 
-**从答案，到证据；从证据，到改进。**
+**你的研究，长成一个本体。**
 
-ClearAI 是一个**原生 DSH 插件**，把认识论循环带进 DeepSeek Harness。
+ClearAI 是一个**本体发现与探索平台**，核心由两个概念支撑：
 
-语言模型可以在几秒内给出一个看起来合理的答案。ClearAI 关心的是接下来发生的事：写下什么能检验这个想法、执行工作、记录发生了什么、评估证据、修正已有的认识——让一个结论**获得**它的状态，而不是靠断言取得。
+- **领域本体**（你得到什么）——项目自己的词汇、经循环确立的知识条目、以及它们的图。研究结束时你拿到一个持续生长的知识结构，下一轮按概念检索。
+- **认识论循环**（你怎么得到它）——七个阶段的纪律化路径：界定、假设、规划、观测、验证、评估、记录。每条边都要经过证据与独立评估的检验。
+
+> 别的知识图谱靠抽取与断言堆边；这里的每一条边都要通过循环挣得。
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/diagrams/epistemic-loop-hero-dark.zh-CN.png">
-  <img src="docs/diagrams/epistemic-loop-hero.zh-CN.png" alt="认识论循环" width="1200">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/diagrams/ontology-hero-dark.zh-CN.png">
+  <img src="docs/diagrams/ontology-hero.zh-CN.png" alt="认识论循环（左）长出领域本体（右）" width="1200">
 </picture>
 
-> 让模型负责探索，让机制守住事实边界。
+*左：认识论循环——七阶段。绿点是它落定的事实，也是右侧领域本体的第一个节点。右：本体图——深墨是概念，浅墨是值形态，emerald 是实例；实例上挂着两条互相矛盾的断言——**那两个取值染成 amber**，就是「这两条读数对不上」。系统只报出冲突，撤回或维持由人决定。*
 
 ---
 
-## 安装
-
-一条命令，除了 Node 什么都不需要：
-
-```bash
-npx clearai-dsh install
-```
-
-它会自己找到 DSH CLI（PATH 上有就用，没有就走 npx），把插件装进你的 `web` profile，再把组合读回来核一眼 —— 不用凭一句「成功」相信它。底下就是宿主自己的安装动作，所以两者等价：`dsh plugin --profile web add clearai-dsh`。
+## 你得到什么：领域本体
 
-**装完要重启 `dsh web`**（`npx @deepseek-ai/dsh web`）。插件的两半都在运行中的进程里按模块 URL 缓存，只刷新浏览器不够。然后新建会话，在预设选择器里选 **ClearAI**。
+一个**领域本体**，它在你研究的过程中生长：
 
-如果它因为 **PATH 上没有 pnpm** 而停下：DSH 管理 profile 就是靠 pnpm，所以需要一个。用 `npm install -g pnpm` 装，或用你的系统包管理器。**别用 `corepack enable` 抄近路**——它装的是一个版本**转发器**而不是 pnpm，而当前 Node 自带的那份 corepack 可能下载一个它自己启动不了的 pnpm。
+- **词汇**——你的项目用什么语言说话：概念、谓词、值形态、单位。约定本身没有对错，有对错的是用这些词写下的句子。
+- **已确立条目**——通过了循环的知识：每条带边界、支持等级、证据链。每条都写明适用边界，否则无法安全引用。
+- **本体图与实体图**——你的领域长什么样（结构），你已经验证出了什么（战况）。
+- **冲突读数**——两条互相矛盾的结论自动亮出来；系统只报出冲突，撤回或维持由你决定。
 
-从仓库开发（这是开发路径，不是安装路径）：
-
-```bash
-npm test                       # 14 份套件 —— 清单在 test/run.sh
-node tools/build-package.mjs   # 由源装配 dist/
-node tools/verify-package.mjs  # 现场重建并逐字节比对
-node tools/verify-clean-install.mjs   # 空 DSH_HOME + 真 CLI 装一遍(16 条断言)
-node docs/diagrams/build.mjs   # 重画循环主图(需 google-chrome)
-```
-
-`dist/` 是生成物，不进版本库。见 [DSH 集成](docs/dsh-integration.zh-CN.md)。
-
-## 为什么它不只是又一个 agent loop
+## 你怎么得到它：认识论循环
 
 多数 agent loop 只跟踪一件事：任务做完没有。认识论循环还跟踪**一个结论凭什么被信任**：
 
@@ -58,72 +44,101 @@ node docs/diagrams/build.mjs   # 重画循环主图(需 google-chrome)
 | 完成 | 模型宣布完成 | 系统按交付的证据算出来 |
 | 裁决 | 谁做的谁说了算 | 分离——超过一定等级，做的人不能判自己 |
 | 失败 | 删掉、重来、忘掉 | 留下：被推翻的命题是结果，不是噪声 |
+| 沉淀 | 一段聊天记录 | **一个本体**：本体中的每个关系都有来源和验证记录 |
 
-ClearAI 把这条循环做成机制，而不是劝告。状态从会话记录派生而不是存第二本账，进度与阶段是算出来的，模型手上的工具里**根本不存在**可以宣告某一步完成的字段。
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/diagrams/epistemic-loop-hero-dark.zh-CN.png">
+  <img src="docs/diagrams/epistemic-loop-hero.zh-CN.png" alt="认识论循环" width="1000">
+</picture>
 
-ClearAI **不**声称实现递归自我改进。它提供的是自我改进系统所需要的认识论底座：诚实记录改了什么、证据是什么、谁评估了它、哪些失败了。边界在哪，见 [定位](docs/positioning.zh-CN.md) 与 [OpenRSI 调研](docs/research-openrsi.md)。
+*环内是这台仪器的读数面：横轴是 L0–L4 七个等级，那条虚线是**事先登记进判据**的阈值；五个观测各带误差棒——被支持的填实、无法判定的画虚圈、被推翻的留在原位打一道斜杠（什么都不删）。开口处那颗 emerald 是唯一越过判据、落定成事实的读数。*
 
-## 循环的每一阶段
+运行时，七个阶段压缩为四拍——计划、执行、观察、反思。状态从会话记录派生，没有第二份存储；模型的工具里没有可以宣告某一步完成的字段。
 
-认识论循环有七个阶段。运行时，这七个阶段压缩成四拍——计划、执行、观察、反思——作为更简洁的工作节奏。
+ClearAI **不**声称递归自我改进。它提供的是自我改进系统所需要的认识论底座。详见[定位](docs/positioning.zh-CN.md)与[OpenRSI 调研](docs/research-openrsi.md)。
 
-| 阶段 | 模型做什么 | 机制保证什么 | 你看到什么 |
-|---|---|---|---|
-| 界定 | 明确问题、假设、范围与目标 | 调查从显式边界开始 | 范围与假设 |
-| 提出假设 | 记录候选解释或路线 | 命题与已采纳事实分开 | 假设 |
-| 规划 | 定义可执行、可提供证据的步骤和判据 | 只能通过受治理路径推进完成 | 可检查的计划 |
-| 观测 | 执行允许的工作并记录发生了什么 | 准入只判断是否可接收，不判断真假 | 观测与产物 |
-| 验证 | 用已登记的判据检验观测 | 验证始终绑定命题及其边界 | 检查与证据 |
-| 评估 | 判断支持、不确定性与冲突 | 高等级工作可要求独立评估 | 评估与依据 |
-| 记录并行动 | 保存结果，选择下一项有边界的行动 | 保留历史；未解决命题保持限定 | 事实、边界与下一步 |
+---
 
-完整版：[认识论循环](docs/epistemic-loop.zh-CN.md)
+## 安装与使用
 
-## 它长什么样
+```bash
+npx clearai-dsh install
+```
 
-插件在原生 DSH 之上贡献三个面：中栏的**产物**，以及右栏的**世界线 / 命题与事实 / 外脑**。
+装完重启 `dsh web`（`npx @deepseek-ai/dsh web`），然后**新建会话，在顶部的模式选择器里切换到 `ClearAI`**：
 
-**命题与事实**——一行一条主张：当前处境、等级、判者。已确认的结论带着边界上架；被推翻的留在原位，连同推翻它的证据。
+1. 打开 `dsh web`，点「新建会话」；
+2. 点顶部当前的模式名（默认是「标准模式」），展开预设列表；
+3. 选 **ClearAI**——卡片描述就一句:「利用认识论循环构建可信本体。Build a trustworthy ontology through the epistemic loop.」；
+4. 像平常一样提问。普通问答照常走；一旦你立了目标并登记假设，系统自动进入知识模式：预检把已知送上来，缺口如实读出来，结论过证据才准入。
 
-![命题与事实](docs/shots/zh/facts.png)
+<picture>
+  <img src="docs/shots/zh/jepa-ontology.png" alt="ClearAI 模式下的知识图谱" width="820">
+</picture>
 
-**世界线**——两条路线真的分歧时，各自独立跑、各自带读数；落选的那条留在记录里，采纳是人按的那一下。
+*ClearAI 模式下的本体图——这场真实会话长出 21 个概念、9 条谓词；同一份账本永远得到同一张图。*
 
-![世界线](docs/shots/zh/worldlines.png)
+如果 PATH 上没有 pnpm：`npm install -g pnpm`（别用 `corepack enable`——它装的是版本转发器，可能下载一个自己启动不了的 pnpm）。
 
-**产物**——中栏把「计划声明交付的」与「盘上真有的」分开摆，不许混为一谈。
+从仓库开发：
 
-![产物](docs/shots/zh/deliverables.png)
+```bash
+npm test                       # 15 份套件
+node tools/build-package.mjs   # 由源装配 dist/
+node tools/verify-package.mjs  # 现场重建并逐字节比对
+node docs/diagrams/build-hero.mjs   # 重画产品主图(需 google-chrome)
+```
 
-**外脑**——技能与记忆以 DSH 原生条目的形式出现在同一张合并目录里，旁边是本会话的用量。
+`dist/` 是生成物，不进版本库。见 [DSH 集成](docs/dsh-integration.zh-CN.md)。
 
-![外脑](docs/shots/zh/skills.png)
+---
 
-## 它落在 DSH 的哪一层
+## 它长什么样
 
-ClearAI 把认识论层加在 DSH 的**组合面**上——一个宿主包、一个 agent 预设、一个客户端模块，**DSH 引擎一行都没改**。`/goal` `/plan` `/evidence` `/worldline` `/plan-review` 是人在 `/` 菜单里的状态窗（只读，从账本现算）；todo、子代理、workflow、模型切换用 DSH 原生的——工作方式不设限，但它们写不进权威账本（权威边界由测试钉死）。
+中栏两格可切：**产物**与**本体**。右栏：**世界树**与**外脑**。
 
-![ClearAI 在 DSH 中](docs/diagrams/loop-to-dsh-planes.zh-CN.svg)
+**本体**——这一格是你的知识主场。顶部是**图带**：本体图（你的领域长什么样）与实体图（已经验证出了什么）一键切换；点节点或边打开**知识 Inspector**（定义 / 关系 / 断言 / 证据链 / 历史），「按此过滤」是详情里的显式动作。下面是**本体货架**：已确立的条目，每条带断言芯片（点开看这个词什么意思）、边界与等级；互相矛盾的自动亮出来。词汇维护区收在最底下——语言先于句子时它自动展开。
 
-## 案例
+<picture>
+  <img src="docs/shots/zh/jepa-band.png" alt="本体图带：本体图与实体图切换" width="820">
+</picture>
 
-三个案例，用来展示循环在"诚实的答案不是一个干净结果"的问题上怎么工作：
+*图带——本体图与实体图共用同一份确定性投影，同一份账本永远得到同一张图；素材来自一场真实会话（21 概念 · 9 谓词）。*
+
+<picture>
+  <img src="docs/shots/zh/jepa-inspector.png" alt="知识 Inspector：定义、关系、断言、证据链" width="820">
+</picture>
 
-- [AI for Science](docs/cases/ai4sci.zh-CN.md) —— WENO 重构在临界点附近的收敛阶，以及「分辨不出来」到底意味着什么；
-- [数学探索](docs/cases/mathematics.zh-CN.md) —— 把有限数值证据与形式证明严格分开；
-- [物理世界工艺实验](docs/cases/physical-experiment.zh-CN.md) —— 执行离开计算机之后，循环如何保持可追溯。
+*点开任一节点或边：定义、关系、断言、证据链、登记与修订史，一处读完。*
 
-它们演示的是机制本身，随库不附跑批记录。
+**世界树**——两条路线真的分歧时，各自独立跑、各自带读数；落选的那条留在记录里，采纳是人按的那一下。
+
+**产物**——中栏把「计划声明交付的」与「盘上真有的」分开摆，不许混为一谈。
+
+**外脑**——技能与记忆以 DSH 原生条目的形式出现在同一张合并目录里。
+
+---
+
+## 案例
+
+- [物理世界工艺实验](docs/cases/physical-experiment.zh-CN.md)——传感器热漂移：从立词到冲突现形的完整链路
+- [AI for Science](docs/cases/ai4sci.zh-CN.md)——WENO 重构的收敛阶，以及「分辨不出来」意味着什么
+- [数学探索](docs/cases/mathematics.zh-CN.md)——把有限数值证据与形式证明严格分开
+
+---
 
 ## 文档
 
-- [定位](docs/positioning.zh-CN.md)
-- [设计原则](docs/design-principles.zh-CN.md)
-- [灵魂映射：原则 → 机制 → 测试](docs/soul-map.zh-CN.md)
-- [术语表](docs/glossary.zh-CN.md)
-- [循环哲学](docs/loop-philosophy.zh-CN.md) · [验证本体](docs/verification-loop.zh-CN.md)
+- [定位](docs/positioning.zh-CN.md) · [领域本体设计](docs/domain-ontology.zh-CN.md)
+- [认识论循环](docs/epistemic-loop.zh-CN.md) · [验证本体](docs/verification-loop.zh-CN.md) · [循环哲学](docs/loop-philosophy.zh-CN.md)
+- [设计原则](docs/design-principles.zh-CN.md) · [灵魂映射](docs/soul-map.zh-CN.md) · [术语表](docs/glossary.zh-CN.md)
+- [知识原生循环执行账本](docs/optimization/knowledge-native-loop.zh-CN.md)（本轮：分诊 / 预检 / 知识门 / 图 / Inspector）
+- [开发计划](docs/optimization/domain-ontology-plan.zh-CN.md)（含亨通真跑读数）
 - [已知缺口](docs/known-gaps.zh-CN.md) · [权威归属](docs/authority-map.zh-CN.md) · [发布验收](docs/release-verification.zh-CN.md)
-- [收敛与瘦身计划](docs/optimization/plan.zh-CN.md) · [认识论循环全覆盖设计](docs/optimization/epistemic-coverage.zh-CN.md) · [执行进度](docs/optimization/progress.zh-CN.md)
+
+## 它落在 DSH 的哪一层
+
+ClearAI 把认识论层加在 DSH 的**组合面**上——一个宿主包、一个 agent 预设、一个客户端模块，**DSH 引擎一行都没改**。工作方式不设限，但它们写不进权威账本（权威边界由测试钉死）。
 
 ## 工作署名
 
@@ -135,8 +150,8 @@ ClearAI 把认识论层加在 DSH 的**组合面**上——一个宿主包、一
 
 ## 许可证
 
-Apache-2.0,见 [LICENSE](LICENSE)。
+Apache-2.0，见 [LICENSE](LICENSE)。
 
 ## 状态
 
-本仓库是 DSH 原生 ClearAI 插件库：一个通过 DSH 交付的本地优先认识论工作台。哪些还没实现、哪些还没在真浏览器里验过，都写在 [已知缺口](docs/known-gaps.zh-CN.md) 里。
+一个通过 DSH 交付的本地优先本体发现与探索平台。哪些还没实现、哪些还没在真浏览器里验过，都写在[已知缺口](docs/known-gaps.zh-CN.md)里。