clearai-dsh 0.2.7 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,61 @@
 
 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.3.0] — 2026-09-29
+
+**从一次真跑的三条症状出发,把三件事从劝告变成机制。** 一位用户在真实会话里遇到的三个问题——`CloseGoal` 运行失败且要跑很久;命题晦涩、而且**从没走过认识论循环的便宜层级**;本体建得不错、**查到的实体却没进实体图谱**——每一条都追到了代码行:宿主半用**属性式**取服务(宿主 fiber 瞬态掉线就抛,而评估者刚跑完的那两分钟评审随栈帧一起没了);实体层的节点与边**唯一**来自「整条目标被独立裁决判 support」之后的升格;`supportedLevel` 只是支持证据的最大值,跳级**零代价**。这一版不是把话说重一点,而是把这三条各自换成一道**可清点的机制**——并在两场真模型 headless 长测里验过。
+
+### Added
+
+- **实体是一等写入口**(本轮的主修):`RegisterInstance`(观测:依据与出处必填)与 `Assert`(说一句关于某个**已登记实例**的带出处的话)。**断言在登记那一刻就产边**,不再等目标裁决;投影把三个来源合起来画,同键去重、节点与边都带 `source`(`registered` / `promoted` / `asserted`),两个新来源都为空时输出与 0.2.8 **逐字节相同**。`RegisterTerm` 与它的分工写死在工具描述里:**概念是约定,实例是观测**。
+- **`ExplainLevelSkip`**:为「没走过的验证等级」留理由,`levels` 必须是卡上列出的未走过等级,`reason` 必须**点到该等级要检查的对象名**(「时间不够」过不了)。
+- **缺口三条 + 三道门**:`entities_unlanded`(逐主体差集:**断言主体在图上有边**才算落地)、`levels_skipped`、`orphan_terms`;每条缺口都带 `nextAction`。门 `requireLandedEntities` / `requireLevelReasons` / `requireCriteriaVerdict` 机制缺省关、preset 里开到生产,各自两条诚实出口(补齐 或 `abandoned`)。
+- **目标的一句话与可清点的判据**:`SetGoal` 新增 `headline`(≤120 字;省略时由 `claim` 首句现算,现算超长当场拒)、`criteria[]` / `criteria_note`;改判据文本要带一份**已落定独立裁决**的 auditKey。
+- **`clear/goals/{goalId}.md`**:本体声明里 `goal.persistence` 早就写了这个落点、此前没人写;现在内核幂等落盘(判据逐条、假设、修订留痕),卡里给压缩版 + 指针。
+- **单一叙述源 `ui/lib/knowledge-view.js`**:运行态卡、右栏面板、词汇货架读**同一份**投影(此前四处各写一遍,漂了要读者自己调和)。
+- **事件命名空间 `entity/` · `level/` · `criteria/` · `host/`**;`host/inactive` 四步闭环:宿主按 scope+detail 算**内容寻址 id** → 内核 pre-step 把没上账的落成变更 → 折法按 id **幂等** → 宿主只交出还没上账的那几条。
+- **真值表**补 4 条机制(共 71 条)与**代码→真值表**的反向检查(顶层 `events` + 4 项校验,总 29 项);工具面 **29 → 32 件**,领域动词 10 件。
+
+### Changed
+
+- **CloseGoal**:派发/结算事实**在 `await` 之前独立落账**(工具抛错、被 abort 都抹不掉);裁决按**材料** digest **同态复用**——digest 只盖目标修订号、计划步与判据、观测、原始假设、事实、非审计来源的证据与**产物摘要**,不含"上一次评审自己的回声";交付那一步同样适用,但**证据照旧落账**(步骤历史与既有的「连续两次无法判定 ⇒ 强制改法」都靠它),省掉的只是那两分钟子 run。复用仍带得出评估卡与评估者会话。
+- **裁决卡设预算**:`basis` ≤1200 字,缺口的每条写成 `{criterion, what, missing}` 三格。真跑里一次裁决的 `basis` 是五千余字、末步单次生成 81 秒。
+- **宿主读面降级不再抛**:`ui/lib/index.js` 禁属性式服务访问,取不到返回空态;`sessionCwd` 拿不到会话目录**不写盘**(删掉 `process.cwd()` 回退——"写不出去"与"写到别处"是两件事)。
+- **运行态卡**:判据**逐条**渲染(每条 80 字、最多 6 条 + "还有 N 条" + 指针)、`claim` 压缩、**删掉时钟**(分钟级时间戳让"同一状态的卡"每分钟变一次,按内容去重因此永远失效)。
+
+### Fixed
+
+- **评审只写正文卡片时,裁决被整份丢掉**(真模型长测抓到):`refs` 曾被写进 `VERDICT_SCHEMA` 的 `required`,评估者在 markdown 里写清 `verdict: support` 却因形状被 runtime 拒收 ⇒ 账上只剩「无法判定」,**目标永远结不了案**。现在 `refs` 声明但不强制,并给 `parseLooseJson` 加了**正文卡片兜底**(只认 `verdict:` 后那三个词;取不到就如实说取不到——猜一份 support 比丢掉一份 refute 坏得多)。
+- **三处「目录取不到就拿 `null` 拼路径」的崩溃**(立约前侦察 / 观测登记 / 准入)与 `WriteMemory` / `SaveSkill` 的同类问题:一律降级为如实返回,不再抛。
+- **`entities_unlanded` 的判据从"图上有节点"改成"图上有边"**:只数节点时,登记一个无关实例就能把缺口压掉,而真正该落地的主体仍只在命题上。
+
+### Verified
+
+- **18 套件 1879 项检查全绿**;真值表 29 项 / 71 条机制;`verify-package` 除沙箱内的 `npm pack` 外全过。
+- **两场真模型 headless 长测**(装出来的包、无人值守):`entity-graph` **41 通过 / 0 失败**(13 个实例、15 条断言边、3 处跳级理由)、`long-plan` **40 通过 / 0 失败**(5 步全交付、记忆 1 条、账本 5 次提交、目标 achieved,并自发用了 5 个实例 + 9 条断言)。现场(轨迹、会话日志、读数)归档在 `docs/optimization/e2e-logs/`。
+- **独立验证员**(fresh context、未参与实现)三轮复验 + 变异测试:抓出并修掉 11 处缺陷(含 3 处必崩的 `null` 路径、一处时间死区、一处可绕过的门);诊断与验证全文见 `docs/optimization/2026-09-diagnosis.zh-CN.md` 与 `2026-09-independent-verification.zh-CN.md`。
+
+## [0.2.8] — 2026-09-28
+
+**四个面板消失的那条 bug:客户端半读了一个已经不存在的字段。** 客户端拿「当前会话」用的是 `sessions.list.getSnapshot().current`;宿主的 `SessionListState` 现在只有 `{ ids, byId, phase, projectionsBySession }` —— **没有 `current`**。读到 `undefined`,`isCurrentPreset()` 就恒为 `false`,`occupy()` / `syncRail()` **一个座位都不注册**。失效形态与症状完全一致:模式在、宿主半一切正常,中栏只剩「对话 / 轨迹」、右栏只剩宿主自带的页签,**而且不报错**(0.1.7-rc.2 与 0.2.0-rc.1 的宿主都是这个形状)。
+
+### Fixed
+
+- **客户端:当前会话的取法改成宿主自己的那一套** —— 在 `byId` 里找 `retainedBy.mainView > 0` 的那一行(`dsh-client-ui-open-in-app`、`dsh-client-ui-agent-preset` 都这么写);老宿主若还留着 `current`,照旧认它。`isCurrentPreset()` 与 `sessionIdFor()` 两处共用一个 `currentSessionRow()`。
+
+### Changed
+
+- **测试桩与宿主同形**(`test/client.test.mjs`):旧桩自己造了 `current: 's1'`,于是 240 条检查全绿,而真宿主上四个面板静默消失 —— 桩和宿主不一样,测的就是桩。现在桩用宿主的真实形状(`ids / byId / phase / projectionsBySession` + `retainedBy.mainView`),这条路径从此有断言看着。
+- 版本 0.2.8。
+
+### Verified on DSH 0.2.0-rc.1
+
+- **会话格式仍是 v4**(没有 v4→v5),0.2.5 那次的消息署名改动不用再动;
+- **预设声明行照旧**:名册读到 `standard, ptc, minimal, cordis, clearai`,且 clearai **没有 broken** —— `verify-clean-install` 指向 0.2.0-rc.1 是 22 通过 / 0 失败;
+- **真会话**:`node tools/e2e-run.mjs --installed` 在 0.2.0-rc.1 上 35 通过 / 0 失败(工具、`goal/set`、`plan/created`、投影、跨机制不变量);
+- **真浏览器**(隔离 DSH_HOME + 真 Chrome + 一轮真模型):中栏 `对话 | 轨迹 | 产物 | 本体`,右栏「新标签页」里有 `世界树` 与 `技能 · 记忆`;
+- 0.2 **没有删掉**我们预设用到的官方包;客户端插座与服务名(`conversation.view`、`conversation.input.*`、`sidebarRightTabs`、`sidebarRight`、`sidebar.right.pane.tab(.title)`、`layout`)在 0.2 源码里都还在。
+
 ## [0.2.7] — 2026-09-28
 
 **装完显示「成功」,装到的却是上一版——原因不在我们,但句子在我们这边。** pnpm ≥ 11 起 `minimumReleaseAge` 默认 **1440 分钟(一天)**,而这条内置默认是**非严格**的:一天内发布的版本不会被选中,但**不报错**——它静默回退到**一天以前的最新版**。于是刚发完 `0.2.6`,三条路装到的都是 **`0.2.2`**(2026-09-18):`dsh plugin --profile web add clearai-dsh`(裸包名)、`@latest`、以及**设置 → 插件列表**里填包名。一台 Mac 上实测如此,本机也用 pnpm 12.4.1 在干净工作区复现过(裸名 → 0.2.2;`clearai-dsh@0.2.6` → 0.2.6)。

package/README.md

@@ -7,6 +7,10 @@
 
 <p align="center"><b>English</b> · <a href="README.zh-CN.md">中文</a></p>
 
+<p align="center">
+  <a href="https://trendshift.io/repositories/248415?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-248415" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/248415/weekly?language=JavaScript" alt="Clearailhc%2Fclearai-dsh | Trendshift" width="250" height="55"/></a>
+</p>
+
 **Your research, grown into an ontology.**
 
 ClearAI is an **ontology discovery and exploration platform**, built on two core concepts:
@@ -18,7 +22,8 @@ ClearAI is an **ontology discovery and exploration platform**, built on two core
 
 ```bash
 # Install (npm package, prebuilt — no build step, no allowBuilds prompt)
-dsh plugin --profile web add clearai-dsh@0.2.7
+dsh plugin --profile web add clearai-dsh@0.3.0
+# or in the app: Plugins → Add plugin → clearai-dsh@0.3.0
 ```
 
 Restart `dsh web`, then pick **ClearAI** in the preset picker at the top of a new session. That is the whole setup. [Full install notes ↓](#install-and-use)
@@ -69,22 +74,29 @@ ClearAI does **not** claim recursive self-improvement. It provides the epistemic
 
 ## Install and use
 
-**Recommended — install from npm, with the version pinned:**
+**Requirements:** DSH ≥ `0.1.7-alpha.1` — that generation introduced the composition declaration line this preset rides on. Verified against the host's `0.1.7-rc.2` and `0.2.0-rc.1`.
+
+**Recommended — install it in the app, with the version pinned:**
+
+In the sidebar open **Plugins → Add plugin**, enter `clearai-dsh@0.3.0`, and install. That is DSH's own plugin manager: it hands what you type to pnpm, checks that the package declares a bundle and is compatible with this host, and applies it live. (The Settings page **插件列表 / Plugins** is the read-only inventory — installing happens on the sidebar's Plugins page.)
+
+**Or from a terminal — the same install:**
 
 ```bash
-dsh plugin --profile web add clearai-dsh@0.2.7
+dsh plugin --profile web add clearai-dsh@0.3.0
 ```
 
 This installs the prebuilt package from the npm registry. Nothing is compiled on your machine, so there is no `allowBuilds` grant to approve — the plugin is ready the moment the command returns.
 
-> **Why the version is pinned.** pnpm ≥ 11 holds back newly published versions: `minimumReleaseAge` defaults to 1440 minutes, and because that built-in default is non-strict, a bare package name (or `@latest`) **silently falls back to the newest version older than a day**. Right after a release that is the *previous* release, so a bare name can install something a version or two old and look like it worked. Pin the version — pnpm then records the exclusion itself — or exempt the package once in your profile's `pnpm-workspace.yaml`:
+> **Why the version is pinned.** pnpm ≥ 11 holds back newly published versions: `minimumReleaseAge` defaults to 1440 minutes, and because that built-in default is non-strict, a bare package name (or `@latest`) **silently falls back to the newest version older than a day** — right after a release, the *previous* release. DSH's plugin manager forwards your spec to pnpm unchanged and does **not** compare what landed against what you asked for, so this downgrade is reported as a success. Its preview card is no help either: it reads the package with `pnpm view`, which ignores the age policy, so it can show the newest release while pnpm installs the one before it. Two ways to be exact:
 >
-> ```yaml
-> minimumReleaseAgeExclude:
->   - clearai-dsh
-> ```
-
-**No terminal needed:** open **Settings → Plugins** and enter `clearai-dsh@0.2.7` (the same reason as above: a bare name is held back); that is the host's own install path. Once the package is listed in the [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) catalog it also appears in **[dsh-market](https://github.com/dsh-market/dsh-market)**'s search, where it installs in one click — that market installs only what the catalog lists.
+> - **Pin the version**, as both commands above do — pnpm then records the exception itself.
+> - **Or exempt the package once** in the profile's `pnpm-workspace.yaml`; a bare name works from then on:
+>
+>   ```yaml
+>   minimumReleaseAgeExclude:
+>     - clearai-dsh
+>   ```
 
 **Also available — one-command installer** (it resolves the current release and pins that version for you, so it is immune to the delay):
 
@@ -94,6 +106,8 @@ npx clearai-dsh install
 
 Same install underneath; it resolves the DSH CLI from your PATH (or through npx), installs into the `web` profile, and reads the composed config back so you are not taking "success" on faith. Use this if you prefer a guided path, or `--lang zh|en` to force the installer's output language.
 
+**Community market (third-party):** [dsh-market](https://github.com/dsh-market/dsh-market) lists whatever the curated [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) catalog carries and installs a pinned version for you; ClearAI's catalog entry is in review there. It is not part of DSH, and it is not needed to install this plugin.
+
 **Install from source (for development, not the normal path):**
 
 ```bash
@@ -122,7 +136,7 @@ If pnpm is not on PATH: `npm install -g pnpm` (do not `corepack enable` — it i
 From the repository:
 
 ```bash
-npm test                       # 15 suites
+npm test                       # 18 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)

package/README.zh-CN.md

@@ -7,6 +7,10 @@
 
 <p align="center"><a href="README.md">English</a> · <b>中文</b></p>
 
+<p align="center">
+  <a href="https://trendshift.io/repositories/248415?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-248415" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/248415/weekly?language=JavaScript" alt="Clearailhc%2Fclearai-dsh | Trendshift" width="250" height="55"/></a>
+</p>
+
 **你的研究，长成一个本体。**
 
 ClearAI 是一个**本体发现与探索平台**，核心由两个概念支撑：
@@ -18,7 +22,8 @@ ClearAI 是一个**本体发现与探索平台**，核心由两个概念支撑
 
 ```bash
 # 安装（npm 包，预构建——无需构建步骤，不会触发 allowBuilds 授权）
-dsh plugin --profile web add clearai-dsh@0.2.7
+dsh plugin --profile web add clearai-dsh@0.3.0
+# 或在应用里：侧栏「插件」→ 添加插件 → clearai-dsh@0.3.0
 ```
 
 重启 `dsh web`，在新建会话顶部的模式选择器里选 **ClearAI** 即可。这就是全部步骤。[完整安装说明 ↓](#安装与使用)
@@ -69,22 +74,29 @@ ClearAI **不**声称递归自我改进。它提供的是自我改进系统所
 
 ## 安装与使用
 
-**推荐——从 npm 安装，并把版本钉住：**
+**要求：** DSH ≥ `0.1.7-alpha.1`——预设靠的是那一代引入的组合声明行。已在宿主的 `0.1.7-rc.2` 与 `0.2.0-rc.1` 上验过。
+
+**推荐——在应用里装，并把版本钉住：**
+
+侧栏打开**「插件」→ 添加插件**，填 `clearai-dsh@0.3.0`，安装。这就是 DSH 自己的插件管理器：它把你填的东西交给 pnpm，校验这个包声明了组合包、与当前宿主兼容，然后当场生效。（设置里的**插件列表**是**只读清单**；安装入口在侧栏那个「插件」页。）
+
+**或者开终端——同一次安装：**
 
 ```bash
-dsh plugin --profile web add clearai-dsh@0.2.7
+dsh plugin --profile web add clearai-dsh@0.3.0
 ```
 
 从 npm registry 装预构建产物。本机不跑任何编译，因此不需要批准 `allowBuilds` 授权——命令返回时插件就已经可用。
 
-> **为什么要钉版本。** pnpm ≥ 11 会**压住刚发布的版本**：`minimumReleaseAge` 默认 1440 分钟，而这条内置默认是**非严格**的，于是裸包名（或 `@latest`）会**静默回退到一天以前的最新版**——刚发完新版时，那就是**上一版**，装完还显示成功。钉版本（pnpm 会自己记下例外），或者在 profile 的 `pnpm-workspace.yaml` 里一次性豁免这个包：
+> **为什么要钉版本。** pnpm ≥ 11 会**压住刚发布的版本**：`minimumReleaseAge` 默认 1440 分钟，而这条内置默认是**非严格**的，于是裸包名（或 `@latest`）会**静默回退到一天以前的最新版**——刚发完新版时，那就是**上一版**。DSH 的插件管理器把你填的 spec **原样**转给 pnpm，而且**不比对**装到的是不是你要求的，所以这次降级会显示成安装成功；它的预览卡也帮不上忙：预览走 `pnpm view`，**不受**这条策略过滤，于是可能出现「预览显示最新版、装下去是上一版」。两种写确切版本的办法：
 >
-> ```yaml
-> minimumReleaseAgeExclude:
->   - clearai-dsh
-> ```
-
-**不想开终端**：打开**设置 → 插件列表**，填 `clearai-dsh@0.2.7`（原因同上：裸包名会被压住），走的是宿主自己那条安装路径。等它进了 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) 目录，也能在 **[dsh-market](https://github.com/dsh-market/dsh-market)** 里搜到并一键安装——那个市场只装目录里有的东西。
+> - **把版本钉住**（上面两条命令都是）——pnpm 会自己记下例外。
+> - **或者一次性豁免这个包**，写在 profile 的 `pnpm-workspace.yaml` 里；之后裸包名也能装：
+>
+>   ```yaml
+>   minimumReleaseAgeExclude:
+>     - clearai-dsh
+>   ```
 
 **也提供——一条命令的安装器**（它自己解析当前版本并钉住，因此不受这条延迟影响）：
 
@@ -94,6 +106,8 @@ npx clearai-dsh install
 
 底层是同一个安装；它会从 PATH（或经 npx）解析出 DSH CLI，装进 `web` profile，再把合成后的配置读回来验证，所以「成功」不是靠信。想走引导式流程就用它，`--lang zh|en` 可指定安装器输出语言。
 
+**社区市场（第三方）**：[dsh-market](https://github.com/dsh-market/dsh-market) 只列 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) 目录里的条目，并且会替你钉住版本；ClearAI 的条目正在那边评审。它不属于 DSH，也不是装本插件的必要步骤。
+
 **从源码安装（开发用，不是常规路径）：**
 
 ```bash
@@ -123,7 +137,7 @@ Git 拉的是源码而不是构建产物，所以 pnpm ≥10 会拒绝运行 `pr
 从仓库开发：
 
 ```bash
-npm test                       # 15 份套件
+npm test                       # 18 份套件
 node tools/build-package.mjs   # 由源装配 dist/
 node tools/verify-package.mjs  # 现场重建并逐字节比对
 node docs/diagrams/build-hero.mjs   # 重画产品主图(需 google-chrome)