clearai-dsh 0.1.7 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 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).
 
+# Changelog
+
+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.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,125 @@
 
 <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
-
-One command, and it needs nothing but Node:
-
-```bash
-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`.
+## What you get: a domain ontology
 
-**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.
+A **domain ontology** that grows as you research:
 
-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.
+- **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.
 
-From a checkout (development, not the install path):
+## How you get it: the Epistemic Loop
 
-```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)
-```
-
-`dist/` is generated and never committed. See [DSH integration](docs/dsh-integration.md).
+Most agent loops track one thing: whether the task is done. The Epistemic Loop also tracks **what makes a conclusion trustworthy**:
 
-## 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 |
+| | Task loop | Epistemic loop |
 |---|---|---|
-| Driving question | What do I do next? | What do we know, and on what grounds? |
+| Driving question | What 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 |
+| 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 |
 
-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**.
+<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>
 
-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.
+*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.*
 
-## The loop, stage by stage
+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.
 
-The Epistemic Loop has seven stages. At runtime, these stages compress into four beats—plan, execute, observe, reflect—for a simpler operating rhythm.
+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).
 
-| 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](docs/epistemic-loop.md)
+## Install
 
-## What it looks like
+```bash
+npx clearai-dsh install
+```
 
-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.
+Restart `dsh web` afterwards (`npx @deepseek-ai/dsh web`), create a session, and pick the **ClearAI** preset. 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).
 
-**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.
+From the repository:
 
-![Propositions and facts](docs/shots/en/facts.png)
+```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)
+```
 
-**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.
+`dist/` is generated and never committed. See [DSH integration](docs/dsh-integration.md).
 
-![Worldlines](docs/shots/en/worldlines.png)
+---
 
-**Deliverables** — the middle column shows what a plan declared and what actually exists on disk, and refuses to conflate the two.
+## What it looks like
 
-![Deliverables](docs/shots/en/deliverables.png)
+The middle column has two switchable views: **Deliverables** and **Ontology**. The right sidebar: **Worldlines** and **External Brain**.
 
-**External brain** — skills and memory appear as native DSH entries in one merged catalogue, with the usage of this session next to them.
+**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 concept node filters the shelves below. 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.
 
-![External brain](docs/shots/en/skills.png)
+**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.
 
-## Where it lands in DSH
+**Deliverables** — the middle column keeps "what the plan declared" and "what actually exists on disk" apart.
 
-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).
+**External Brain** — skills and memory as DSH-native entries in one merged catalogue.
 
-![ClearAI in DSH](docs/diagrams/loop-to-dsh-planes.svg)
+---
 
 ## Cases
 
-Three cases, written to show what the loop does on questions where the honest answer is not a clean result:
+- [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
 
-- [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.
-
-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)
+- [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,75 @@ 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** 预设。如果 PATH 上没有 pnpm：`npm install -g pnpm`（别用 `corepack enable`——它装的是版本转发器，可能下载一个自己启动不了的 pnpm）。
 
-**命题与事实**——一行一条主张：当前处境、等级、判者。已确认的结论带着边界上架；被推翻的留在原位，连同推翻它的证据。
+从仓库开发：
 
-![命题与事实](docs/shots/zh/facts.png)
+```bash
+npm test                       # 15 份套件
+node tools/build-package.mjs   # 由源装配 dist/
+node tools/verify-package.mjs  # 现场重建并逐字节比对
+node docs/diagrams/build-hero.mjs   # 重画产品主图(需 google-chrome)
+```
 
-**世界线**——两条路线真的分歧时，各自独立跑、各自带读数；落选的那条留在记录里，采纳是人按的那一下。
+`dist/` 是生成物，不进版本库。见 [DSH 集成](docs/dsh-integration.zh-CN.md)。
 
-![世界线](docs/shots/zh/worldlines.png)
+---
 
-**产物**——中栏把「计划声明交付的」与「盘上真有的」分开摆，不许混为一谈。
+## 它长什么样
 
-![产物](docs/shots/zh/deliverables.png)
+中栏两格可切：**产物**与**本体**。右栏：**世界树**与**外脑**。
 
-**外脑**——技能与记忆以 DSH 原生条目的形式出现在同一张合并目录里，旁边是本会话的用量。
+**本体**——这一格是你的知识主场。顶部是**图带**：本体图（你的领域长什么样）与实体图（已经验证出了什么）一键切换，点概念节点按概念过滤。下面是**本体货架**：已确立的条目，每条带断言芯片（点开看这个词什么意思）、边界与等级；互相矛盾的自动亮出来。词汇维护区收在最底下——语言先于句子时它自动展开。
 
-![外脑](docs/shots/zh/skills.png)
+**世界树**——两条路线真的分歧时，各自独立跑、各自带读数；落选的那条留在记录里，采纳是人按的那一下。
 
-## 它落在 DSH 的哪一层
+**产物**——中栏把「计划声明交付的」与「盘上真有的」分开摆，不许混为一谈。
 
-ClearAI 把认识论层加在 DSH 的**组合面**上——一个宿主包、一个 agent 预设、一个客户端模块，**DSH 引擎一行都没改**。`/goal` `/plan` `/evidence` `/worldline` `/plan-review` 是人在 `/` 菜单里的状态窗（只读，从账本现算）；todo、子代理、workflow、模型切换用 DSH 原生的——工作方式不设限，但它们写不进权威账本（权威边界由测试钉死）。
+**外脑**——技能与记忆以 DSH 原生条目的形式出现在同一张合并目录里。
 
-![ClearAI 在 DSH 中](docs/diagrams/loop-to-dsh-planes.zh-CN.svg)
+---
 
 ## 案例
 
-三个案例，用来展示循环在"诚实的答案不是一个干净结果"的问题上怎么工作：
+- [物理世界工艺实验](docs/cases/physical-experiment.zh-CN.md)——传感器热漂移：从立词到冲突现形的完整链路
+- [AI for Science](docs/cases/ai4sci.zh-CN.md)——WENO 重构的收敛阶，以及「分辨不出来」意味着什么
+- [数学探索](docs/cases/mathematics.zh-CN.md)——把有限数值证据与形式证明严格分开
 
-- [AI for Science](docs/cases/ai4sci.zh-CN.md) —— WENO 重构在临界点附近的收敛阶，以及「分辨不出来」到底意味着什么；
-- [数学探索](docs/cases/mathematics.zh-CN.md) —— 把有限数值证据与形式证明严格分开；
-- [物理世界工艺实验](docs/cases/physical-experiment.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/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 +124,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)里。