clearai-dsh 0.2.4 → 0.2.6

package/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 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.6] — 2026-09-28
+
+**插件列表里终于写了介绍。** 宿主从 `locale/<语言>.json` 的 `meta.title` / `meta.description` 与清单顶层的 `icon` 读一个插件的显示文字和图标;**三样都缺时回退到包名 + npm 的 description + 默认图**——而那正是我们一直显示的东西:标题 `clearai-dsh`(包名)、介绍 "ClearAI: The Epistemic Loop, native to DSH."(README 的 tagline)、一个通用图标。装上它的人在一个「插件市场」式的列表里看到的,是一句没有说清装上得到什么的英文。
+
+这一版把这三样补上,并给顺带发现的两处过时改了账:`docs/dsh-integration` 里「预设怎么进名册」还写着 `0.2.4` 之前的 root 目录机制(名册换代时它没跟上);README 的安装段也没提现在这条官方路径。
+
+### Added
+
+- **`locale/en.json` + `locale/zh.json`**:标题 `ClearAI`,一句话介绍分中英两份(界面是中文时不读英文)。宿主按文件名认语言,`en.json` 是基准。
+- **`brand/icon.svg`**:插件列表的图标。与 `logo.svg` 同一套几何,只把主笔颜色**写死**——主标那支是 `currentColor`,而列表里它是以 data URL 读进来的、没有可继承的 CSS 上下文,`currentColor` 会落到黑色,暗色卡片上只剩那颗点;品牌位图虽有两版,`icon` 却只能给一个文件。取中性环色 + emerald 点,明暗两套主题都读得出。
+- **`engines.dsh: ">=0.1.7-alpha.1"`**:宿主下界写进清单,市场据此显示要求(此前只有描述里那句话)。
+- **`screenshots.json`**:给市场卡片声明 5 张截图(四张英文面板 + 一张本体图工作区)。不声明时市场从 README 自动抽取,而我们的 README 里只有 logo 与星标图。
+
+### Changed
+
+- **构建把 `locale/` 打进发行物**(装配表与 `package.json` 的 `files` / `exports` 同步):`exports` 不放行 `./locale/*.json`,宿主解析不到;不进 `files`,发出去的包里就没有。图标走已有的 `brand/` 整目录拷贝。
+- **自检门加了「可被发现」这一关**:`verify-package` 判文件在不在、标题是不是包名、`exports` / `files` / `engines.dsh` 齐不齐;`verify-clean-install` 则**调宿主自己的 `readPluginMeta`** 对装好的那个包算一遍——「插件列表里会显示什么」从此是算出来的,不是我们复述的规则。这一关是先有的诊断:同一段宿主代码在我们补之前返回的正是 `{title: "clearai-dsh", description: "ClearAI: The Epistemic Loop, native to DSH."}`。
+- **文档跟上现状**:`docs/dsh-integration` 的「预设怎么进名册」按**声明行**重写(`preset-clearai` 那一条,构建期由 `preset/agent.cordis.yml` 派生,宿主 ≥ `0.1.7-alpha.1`),并给「源 → 包」表补上 `locale/` 与 `brand/` 两行;README(中英)的安装段补上不开终端的那条路(设置 → 插件列表填包名)与市场收录后的那条。
+
+## [0.2.5] — 2026-09-28
+
+**跟上了宿主的会话格式 v4(消息来源改成生产者自有)。** 宿主 `0.1.7-rc.2` 起,`source.kind` 就是**生产者自己的身份**:共享包装 `{ kind: 'plugin', plugin }` 已退役,原生接纳在落账那一步**当场拒绝**它,报 `format v4 message requires a producer-owned source kind`。内核一直用旧包装下发运行态卡与外脑事实(合并目录 / 运行档 / 候选技能 / 世界线回灌),于是**每一轮都在落账那一步整轮失败**——卡片与事实一条都进不去。而单测当时全绿:它们直接调 fold,不经过宿主的接纳。
+
+**为什么是 `plugin:clearai` 这个值**:宿主读取已发布 V3 日志时,未知名插件正是按 `plugin:<插件名>` 抬升的。选同一个值,老会话折得出来、新会话写得进去,两侧只认一个名字;另起一个名字则要永远维护新旧两套(而且旧会话在面板上的署名会和新会话长得不一样)。
+
+### Changed
+
+- **内核署 `plugin:clearai`,不再写 `plugin` 字段**:`MESSAGE_SOURCE_KIND` 一处定义,运行态卡与无卡通知两条通道共用。
+- **折叠层同时认两种署名**:`plugin:clearai`(现在写的)与退役前的 `{ kind: 'plugin', plugin: 'clearai' }`(事件被**直接**喂进来时仍带着它:测试、旧导出、重放工具)。退回到旧形状时身份在 `plugin` 字段上,**只认 `clearai`**——别的插件冒名不进这道门。
+- 形态字段没动:`form: 'snapshot'` + `sections` 照旧,面板的上下文注入行仍按 `form` 渲染(署名只换了个名字,呈现不变)。
+- **e2e 里按 v3 形状找工具结果的地方跟着改到 v4**:`toolCallId` 在 v4 挂在**结果消息本身**上(退役前嵌在第一个 content 块里),旧写法让 `CreatePlan` 的两条断言**永远假红**(进程 exit 0、变更记录也落了,断言却报「契约错误」);`--freeform` 那两场的目标/计划断言也改成随形态跳过——与同一份工具里其余断言的判据对齐。
+- **本地「干净安装」门不再随手挑一份 npx 缓存里的宿主**:这台机器的缓存里躺着 0.1.5-rc.1 与 0.1.7-rc.2 两份,`readdir` 挑到旧的那份时 `--dump-config` 会因为我们的 bundle patch 是数组(宿主 0.1.7-alpha.1 起才支持)当场崩,四条组合断言全红——而真正的原因(验的根本不是要支持的宿主)一个字都不在输出里。现在按版本挑最新的一份,并把「dsh 来自哪里、是哪个版本」念出来(CI 走 `DSH_CLI_PREFIX`,不受影响)。
+
+**证据**:拿宿主真代码(`dsh-session-format-v3-to-v4` 的 `assertV4RowAdmission`)验过——新署名接纳,旧署名以那条原话被拒;并确认转换表里没有 `clearai`(所以旧日志正好抬升成同一个值)。内核侧新增一节断言钉住每一条下发消息的署名(非空、不是 `plugin`、等于 `plugin:clearai`、无 `plugin` 字段、form/sections 照旧);旧署名在 `test/host.test.mjs` 与 `test/invariant.test.mjs` 各留一条「仍折得出来」的正向用例。真跑一场(`node tools/e2e-run.mjs --installed`:真宿主 + 装出来的包 + 真模型 + 真会话日志):运行态卡以 `plugin:clearai` 落在日志里、没有接纳报错,`goal/set` 与 `plan/created` 照旧落账、投影长出计划,跨机制不变量全绿(35 通过 / 0 失败)。干净安装门(真 pnpm + 真 `dsh plugin add` + 真宿主 0.1.7-rc.2)18 通过 / 0 失败:装到的是 `clearai-dsh@0.2.5`,组合里 `clearai-host` 恰好一行,名册里 `clearai` 在列表里且没有 broken。
+
 ## [0.2.4] — 2026-09-28
 
 **跟上了宿主的预设换代。** 宿主 `0.1.7-alpha.1` 起把 agent 预设的注册从「root 目录扫描」换成了「组合里的声明行」,而 clearai-dsh 一直靠一条覆盖 `agent-presets` 行的补丁,把名册的 root 指到包内 `presets/`。那行 id 在新宿主里**已经不存在**,补丁没有落点——包照样装得上、宿主行照样起得来,但 **ClearAI 不进模式选择器**。这一版把它接上。

package/README.md

@@ -77,6 +77,8 @@ dsh plugin --profile web add clearai-dsh
 
 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.
 
+**No terminal needed:** open **Settings → Plugins** and enter the package name `clearai-dsh`; 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.
+
 **Also available — one-command installer:**
 
 ```bash

package/README.zh-CN.md

@@ -77,6 +77,8 @@ dsh plugin --profile web add clearai-dsh
 
 从 npm registry 装预构建产物。本机不跑任何编译，因此不需要批准 `allowBuilds` 授权——命令返回时插件就已经可用。
 
+**不想开终端**：打开**设置 → 插件列表**，填包名 `clearai-dsh` 即可，走的是宿主自己那条安装路径。等它进了 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) 目录，也能在 **[dsh-market](https://github.com/dsh-market/dsh-market)** 里搜到并一键安装——那个市场只装目录里有的东西。
+
 **也提供——一条命令的安装器：**
 
 ```bash

package/brand/icon.svg

@@ -0,0 +1,17 @@
+<!--
+  ClearAI 插件图标 —— 与 logo.svg 同一套几何,只把主笔的颜色**写死**。
+
+  为什么单开一份而不是直接指 logo.svg:主笔是 currentColor,而在插件列表里它是以
+  `<img>`/data URL 读进来的,**没有可以继承的 CSS 上下文**——currentColor 落到默认的
+  黑色,暗色卡片上就只剩那颗点。品牌位图又有明暗两版(logo-512 / logo-512-dark),
+  而 `icon` 只能给一个文件。所以这里取一个明暗都读得出的中性色:环 #98A2B3 打底,
+  点仍是产品里「采纳 / 落定」的 emerald。
+
+  几何与 logo.svg 逐字相同(环心线 R=326、笔画 118、开口 90° 以 -35° 为中心;点 r=104),
+  改主标时这一份也要跟着改。
+-->
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1024 1024" width="1024" height="1024" fill="none">
+  <circle cx="512" cy="512" r="326" stroke="#98A2B3" stroke-width="118" pathLength="360"
+          stroke-dasharray="270 90" stroke-linecap="round" transform="rotate(10 512 512)"/>
+  <circle cx="792" cy="308" r="104" fill="#10B981"/>
+</svg>

package/lib/fold.js

@@ -849,6 +849,20 @@ function stampAt(mutations, time) {
 	})
 }
 
+/**
+ * ClearAI 自己署名的上下文消息吗。
+ *
+ * 宿主从 session 格式 v4 起把消息来源改成生产者自有:内核署 `plugin:clearai`
+ * (`kind` 就是生产者身份),共享包装 `{ kind: 'plugin', plugin }` 已退役。
+ * 退回到旧形状时**身份在 `plugin` 字段上**——只认 `clearai`,别的插件冒名不进这道门。
+ * 宿主读已发布 V3 日志时把旧形状抬升成 `plugin:clearai`;但事件被**直接**喂进这个纯函数时
+ * (测试、旧导出、重放工具)仍带着旧形状,所以两侧都认。
+ */
+function isClearaiSource(source) {
+	if (source === null || typeof source !== 'object' || !Array.isArray(source.sections)) return false
+	return source.kind === 'plugin:clearai' || (source.kind === 'plugin' && source.plugin === 'clearai')
+}
+
 /**
  * 会话日志事件 → 状态。这是投影的入口:除了工具结果里的变更记录,
  * 还吃三条**关于过程本身的事实**——
@@ -874,7 +888,7 @@ export function applyEvent(state, event) {
 		 * 将来真要消费它,记住一个坑:结论在「closing message:」之后——运行时前面那行摘要是
 		 * **它自己写的**,不是子会话说的话。
 		 */
-		if (source !== null && typeof source === 'object' && source.kind === 'plugin' && Array.isArray(source.sections)) {
+		if (isClearaiSource(source)) {
 			/**
 			 * 一条插件消息里可能**同时**带好几件事实(内核一次 pre-step 把目录、运行档、候选一起发)。
 			 * 所以这里是「逐件折」而不是「找到一件就 return」——早退会漏掉后面的事件:

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "ClearAI",
+    "description": "An ontology-first agent preset: evidence-checked research that grows into a browsable domain ontology."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "ClearAI",
+    "description": "以本体为纲的智能体预设：经证据核验的研究长成可浏览的领域本体。"
+  }
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "clearai-dsh",
-  "version": "0.2.4",
-  "description": "ClearAI: The Epistemic Loop, native to DSH.",
+  "version": "0.2.6",
+  "description": "ClearAI: an ontology-first DSH agent preset — evidence-checked research that grows into a domain ontology.",
   "type": "module",
   "private": false,
   "license": "Apache-2.0",
+  "icon": "./brand/icon.svg",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Clearailhc/clearai-dsh.git"
@@ -15,6 +16,7 @@
     "./client": "./lib/client.js",
     "./cordis.patch.yml": "./cordis.patch.yml",
     "./package.json": "./package.json",
+    "./locale/*.json": "./locale/*.json",
     "./invariant": "./lib/invariant.js",
     "./presets/*": "./presets/*"
   },
@@ -25,6 +27,7 @@
     "lib",
     "presets",
     "bin",
+    "locale",
     "cordis.patch.yml",
     "CHANGELOG.md",
     "README.md",
@@ -33,7 +36,8 @@
     "brand"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=22",
+    "dsh": ">=0.1.7-alpha.1"
   },
   "dependencies": {
     "zod": "^4.6.1"
@@ -62,6 +66,8 @@
     "plugin",
     "clearai",
     "agent-preset",
+    "ontology",
+    "epistemic-loop",
     "evidence",
     "worldline"
   ],

package/presets/clearai/plugins/clearai-kernel.js

@@ -248,6 +248,16 @@ export function syncTemplateSkills({ skillsDir, templateDir, record }) {
 /** 变更记录的封套标记:宿主投影只认它。 */
 const MUTATION_KIND = 'clearai'
 
+/**
+ * 内核下发的上下文消息**署名**。
+ *
+ * 宿主从 session 格式 v4 起把消息来源改成生产者自有:共享包装 `{ kind: 'plugin', plugin }`
+ * 已退役,原生接纳当场拒绝它(报 `format v4 message requires a producer-owned source kind`)。
+ * `plugin:clearai` 正是宿主读取已发布 V3 日志时给 clearai 抬升出来的那个值——
+ * 于是老会话折得出来、新会话写得进去,两侧只认一个名字。
+ */
+const MESSAGE_SOURCE_KIND = 'plugin:clearai'
+
 /** 自指检测:账本自指四条 + 对话自指三条。 */
 const SELF_REFERENCE = [
 	[/ClosePlan\s*成功/, '判据不得引用「ClosePlan 成功」——那是系统的动作,不是可核对的产物'],
@@ -5947,7 +5957,7 @@ export function apply(ctx, config = {}) {
 			id: `clearai-brain-${payload.turn}-${payload.step}-${Date.now().toString(36)}`,
 			role: 'user',
 			content: text(note),
-			source: { kind: 'plugin', plugin: 'clearai', form: 'snapshot', sections },
+			source: { kind: MESSAGE_SOURCE_KIND, form: 'snapshot', sections },
 		}
 	}
 
@@ -6768,8 +6778,7 @@ export function apply(ctx, config = {}) {
 					role: 'user',
 					content: text(card),
 					source: {
-						kind: 'plugin',
-						plugin: 'clearai',
+						kind: MESSAGE_SOURCE_KIND,
 						form: 'snapshot',
 						sections: [{ name: 'clearai', text: card }, ...brainSections],
 					},