clearai-dsh 0.2.5 → 0.2.7

package/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 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.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)。
+
+这一版**不改包的行为**,只改用户会照抄的那几句,并加一条判据钉住它。
+
+### Changed
+
+- **README(中英)的推荐安装命令改成钉版本的** `dsh plugin --profile web add clearai-dsh@0.2.7`,并新增一段「为什么要钉版本」:机制、两种解法——写死版本(pnpm 会自己记下例外),或在 profile 的 `pnpm-workspace.yaml` 里 `minimumReleaseAgeExclude: [clearai-dsh]` 按**包名**豁免所有版本。「设置 → 插件列表」那条也改成填 `clearai-dsh@0.2.7`。
+- **「一条命令的安装器」标注清楚**:`npx clearai-dsh install` 自己解析当前版本并钉住它(`bin/clearai.mjs` 一直传的是 `clearai-dsh@<自己的版本>`),本来就不受这条延迟影响。
+- `docs/dsh-integration`(中英)的安装段同步;`docs/known-gaps`(中英)的「跑起来之前」补两条:pnpm 的这条年龄策略,以及**版本切换中途刷新插件列表可能看到的一次 `locale` 元信息错误**——那是宿主读到了换了一半的包(清单已声明 `locale/`、目录还没铺上),装稳后消失(装稳的 0.2.5 读出纯回退值,装稳的 0.2.6 读出中英标题、介绍与图标)。
+- **自检门新增一条**:发行物里的 `README.md` / `README.zh-CN.md` 必须出现钉到**本版版本号**的安装命令,且不许出现教人敲裸包名的命令行。
+
+**证据**:pnpm 12.4.1 干净工作区实测——裸名与 `@latest` → `0.2.2`;`clearai-dsh@0.2.6` → `0.2.6`,且 pnpm 自动往 `pnpm-workspace.yaml` 写入 `minimumReleaseAgeExclude: clearai-dsh@0.2.6`;把豁免改成按包名(`- clearai-dsh`)之后,裸名 → `0.2.6`。机制出处:pnpm 文档 `minimumReleaseAge`(默认 `1440`,v11 起)与 `minimumReleaseAgeStrict`(内置默认下为 false)。
+
+## [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,不经过宿主的接纳。

package/README.md

@@ -18,7 +18,7 @@ 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
+dsh plugin --profile web add clearai-dsh@0.2.7
 ```
 
 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,15 +69,24 @@ ClearAI does **not** claim recursive self-improvement. It provides the epistemic
 
 ## Install and use
 
-**Recommended — install from npm:**
+**Recommended — install from npm, with the version pinned:**
 
 ```bash
-dsh plugin --profile web add clearai-dsh
+dsh plugin --profile web add clearai-dsh@0.2.7
 ```
 
 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.
 
-**Also available — one-command installer:**
+> **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`:
+>
+> ```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.
+
+**Also available — one-command installer** (it resolves the current release and pins that version for you, so it is immune to the delay):
 
 ```bash
 npx clearai-dsh install

package/README.zh-CN.md

@@ -18,7 +18,7 @@ ClearAI 是一个**本体发现与探索平台**，核心由两个概念支撑
 
 ```bash
 # 安装（npm 包，预构建——无需构建步骤，不会触发 allowBuilds 授权）
-dsh plugin --profile web add clearai-dsh
+dsh plugin --profile web add clearai-dsh@0.2.7
 ```
 
 重启 `dsh web`，在新建会话顶部的模式选择器里选 **ClearAI** 即可。这就是全部步骤。[完整安装说明 ↓](#安装与使用)
@@ -69,15 +69,24 @@ ClearAI **不**声称递归自我改进。它提供的是自我改进系统所
 
 ## 安装与使用
 
-**推荐——从 npm 安装：**
+**推荐——从 npm 安装，并把版本钉住：**
 
 ```bash
-dsh plugin --profile web add clearai-dsh
+dsh plugin --profile web add clearai-dsh@0.2.7
 ```
 
 从 npm registry 装预构建产物。本机不跑任何编译，因此不需要批准 `allowBuilds` 授权——命令返回时插件就已经可用。
 
-**也提供——一条命令的安装器：**
+> **为什么要钉版本。** pnpm ≥ 11 会**压住刚发布的版本**：`minimumReleaseAge` 默认 1440 分钟，而这条内置默认是**非严格**的，于是裸包名（或 `@latest`）会**静默回退到一天以前的最新版**——刚发完新版时，那就是**上一版**，装完还显示成功。钉版本（pnpm 会自己记下例外），或者在 profile 的 `pnpm-workspace.yaml` 里一次性豁免这个包：
+>
+> ```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)** 里搜到并一键安装——那个市场只装目录里有的东西。
+
+**也提供——一条命令的安装器**（它自己解析当前版本并钉住，因此不受这条延迟影响）：
 
 ```bash
 npx clearai-dsh install

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/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.5",
-  "description": "ClearAI: The Epistemic Loop, native to DSH.",
+  "version": "0.2.7",
+  "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"
   ],