clearai-dsh 0.2.8 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 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.1] — 2026-09-29
+
+**两个死结:计划置 blocked 后再也解不开,续跑窗口的阻塞码收不了兵。** 两条都不是措辞问题,是机制自己在文档承诺的出口上焊死了——0.3.0 的「连拦达阈值 ⇒ 置 blocked、停下等人」写得没错,可人按卡上说的三条出路走,一条也走不出去。
+
+### Fixed
+
+- **`block/cleared` 只清了连拦计数,没清 `plan.blocked`**:计划一旦置 blocked,`AmendPlan`(换一条能过闸的路)与 `RefinePlan`(补齐判据)把话说得再对也解不开,`plan.blocked` 会一直挂着,收件箱那条等人处置的条目成了死结。现在 `block/cleared` 同时删掉 `blocks[plan:step]` 与指向该步的 `plan.blocked`;三条出路各自**真的**能解拦——`AmendPlan`、`RefinePlan`,以及 `VoidPlanStep`(只作废被拦的那一步时才清)。阻塞守卫的文案也随之只列**可执行**的动词(去掉「让人介入后重开」,补上 `VoidPlanStep`)。
+- **续跑窗口的阻塞码用了下划线**:`clearai_loop_stalled` / `clearai_loop_abandoned` 不合宿主契约 —— `@deepseek-ai/dsh-goal` 要求 lower-kebab-case(`/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/`),`goals.block(...)` 当场拒收 ⇒ 收兵失败,窗口留在 `active` 上继续叫醒一个已经收尾的目标。现在改成 `clearai-loop-stalled` / `clearai-loop-abandoned`。测试桩 `makeHost().block` 也按同一条宿主规则抛错——桩与宿主同形,不然测的只是桩。
+- **目录被声明成物证时报「空目录」**:目录不是空文件,两件事不一样,而错的那句话会把下一步动作指错。准入现在把目录**单独判为不可作为物证**(`verified_by: 'l1'`),并如实报出目录里的**文件数与字节数**;`CreatePlan` 的 `artifacts` 契约描述与 `clearai-loop` 技能文档同步写明「目录不是物证,要声明具体文件」。
+
+### Verified
+
+- **18 套件 1886 项检查全绿**(内核 834 · 宿主 119 · 客户端 248 · 领域语言 234 · 本体 96 · 长测 41 · 对照 41 · 可读性 35 …);`verify-package` 44 通过 / 1 失败,唯一那条仍是沙箱里 `npm pack` 的 `EROFS`(只读 `~/.npm/_cacache`),与 0.3.0 记录的是同一处环境限制。
+- 续跑码那一条是**拿真宿主的契约核过**的:`node_modules/@deepseek-ai/dsh-goal/lib/index.js` 里就是那条 lower-kebab-case 正则,不是照着测试桩猜的。
+
+## [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 的宿主都是这个形状)。

package/README.md

@@ -22,8 +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.8
-# or in the app: Plugins → Add plugin → clearai-dsh@0.2.8
+dsh plugin --profile web add clearai-dsh@0.3.1
+# or in the app: Plugins → Add plugin → clearai-dsh@0.3.1
 ```
 
 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)
@@ -78,12 +78,12 @@ ClearAI does **not** claim recursive self-improvement. It provides the epistemic
 
 **Recommended — install it in the app, with the version pinned:**
 
-In the sidebar open **Plugins → Add plugin**, enter `clearai-dsh@0.2.8`, 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.)
+In the sidebar open **Plugins → Add plugin**, enter `clearai-dsh@0.3.1`, 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.8
+dsh plugin --profile web add clearai-dsh@0.3.1
 ```
 
 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.
@@ -136,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

@@ -22,8 +22,8 @@ ClearAI 是一个**本体发现与探索平台**，核心由两个概念支撑
 
 ```bash
 # 安装（npm 包，预构建——无需构建步骤，不会触发 allowBuilds 授权）
-dsh plugin --profile web add clearai-dsh@0.2.8
-# 或在应用里：侧栏「插件」→ 添加插件 → clearai-dsh@0.2.8
+dsh plugin --profile web add clearai-dsh@0.3.1
+# 或在应用里：侧栏「插件」→ 添加插件 → clearai-dsh@0.3.1
 ```
 
 重启 `dsh web`，在新建会话顶部的模式选择器里选 **ClearAI** 即可。这就是全部步骤。[完整安装说明 ↓](#安装与使用)
@@ -78,12 +78,12 @@ ClearAI **不**声称递归自我改进。它提供的是自我改进系统所
 
 **推荐——在应用里装，并把版本钉住：**
 
-侧栏打开**「插件」→ 添加插件**，填 `clearai-dsh@0.2.8`，安装。这就是 DSH 自己的插件管理器：它把你填的东西交给 pnpm，校验这个包声明了组合包、与当前宿主兼容，然后当场生效。（设置里的**插件列表**是**只读清单**；安装入口在侧栏那个「插件」页。）
+侧栏打开**「插件」→ 添加插件**，填 `clearai-dsh@0.3.1`，安装。这就是 DSH 自己的插件管理器：它把你填的东西交给 pnpm，校验这个包声明了组合包、与当前宿主兼容，然后当场生效。（设置里的**插件列表**是**只读清单**；安装入口在侧栏那个「插件」页。）
 
 **或者开终端——同一次安装：**
 
 ```bash
-dsh plugin --profile web add clearai-dsh@0.2.8
+dsh plugin --profile web add clearai-dsh@0.3.1
 ```
 
 从 npm registry 装预构建产物。本机不跑任何编译，因此不需要批准 `allowBuilds` 授权——命令返回时插件就已经可用。
@@ -137,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)