clearai-dsh 0.2.6 → 0.2.8

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 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.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)。
+
+这一版**不改包的行为**,只改用户会照抄的那几句,并加一条判据钉住它。
+
+### 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)、一个通用图标。装上它的人在一个「插件市场」式的列表里看到的,是一句没有说清装上得到什么的英文。

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
+dsh plugin --profile web add clearai-dsh@0.2.8
+# or in the app: Plugins → Add plugin → clearai-dsh@0.2.8
 ```
 
 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,17 +74,31 @@ ClearAI does **not** claim recursive self-improvement. It provides the epistemic
 
 ## Install and use
 
-**Recommended — install from npm:**
+**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.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.)
+
+**Or from a terminal — the same install:**
 
 ```bash
-dsh plugin --profile web add clearai-dsh
+dsh plugin --profile web add clearai-dsh@0.2.8
 ```
 
 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.
+> **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:
+>
+> - **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:**
+**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
@@ -87,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

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
+dsh plugin --profile web add clearai-dsh@0.2.8
+# 或在应用里：侧栏「插件」→ 添加插件 → clearai-dsh@0.2.8
 ```
 
 重启 `dsh web`，在新建会话顶部的模式选择器里选 **ClearAI** 即可。这就是全部步骤。[完整安装说明 ↓](#安装与使用)
@@ -69,17 +74,31 @@ ClearAI **不**声称递归自我改进。它提供的是自我改进系统所
 
 ## 安装与使用
 
-**推荐——从 npm 安装：**
+**要求：** DSH ≥ `0.1.7-alpha.1`——预设靠的是那一代引入的组合声明行。已在宿主的 `0.1.7-rc.2` 与 `0.2.0-rc.1` 上验过。
+
+**推荐——在应用里装，并把版本钉住：**
+
+侧栏打开**「插件」→ 添加插件**，填 `clearai-dsh@0.2.8`，安装。这就是 DSH 自己的插件管理器：它把你填的东西交给 pnpm，校验这个包声明了组合包、与当前宿主兼容，然后当场生效。（设置里的**插件列表**是**只读清单**；安装入口在侧栏那个「插件」页。）
+
+**或者开终端——同一次安装：**
 
 ```bash
-dsh plugin --profile web add clearai-dsh
+dsh plugin --profile web add clearai-dsh@0.2.8
 ```
 
 从 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)** 里搜到并一键安装——那个市场只装目录里有的东西。
+> **为什么要钉版本。** pnpm ≥ 11 会**压住刚发布的版本**：`minimumReleaseAge` 默认 1440 分钟，而这条内置默认是**非严格**的，于是裸包名（或 `@latest`）会**静默回退到一天以前的最新版**——刚发完新版时，那就是**上一版**。DSH 的插件管理器把你填的 spec **原样**转给 pnpm，而且**不比对**装到的是不是你要求的，所以这次降级会显示成安装成功；它的预览卡也帮不上忙：预览走 `pnpm view`，**不受**这条策略过滤，于是可能出现「预览显示最新版、装下去是上一版」。两种写确切版本的办法：
+>
+> - **把版本钉住**（上面两条命令都是）——pnpm 会自己记下例外。
+> - **或者一次性豁免这个包**，写在 profile 的 `pnpm-workspace.yaml` 里；之后裸包名也能装：
+>
+>   ```yaml
+>   minimumReleaseAgeExclude:
+>     - clearai-dsh
+>   ```
 
-**也提供——一条命令的安装器：**
+**也提供——一条命令的安装器**（它自己解析当前版本并钉住，因此不受这条延迟影响）：
 
 ```bash
 npx clearai-dsh install
@@ -87,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

package/lib/client.js

@@ -3705,11 +3705,32 @@ window.__ModuleLoader__.load({
 			// 面板的 CSS(原生那套药丸按钮与主题令牌):带 data-plugin 标记,插件卸载时一起收掉。
 			ctx.effect(installStyles, 'clearai: panel css')
 
-			const isCurrentPreset = () => {
+			/**
+			 * **当前主视图里的那个会话**。
+			 *
+			 * 这里原来是 `sessions.list.getSnapshot().current`(照抄当年的原生 chat)。宿主的
+			 * `SessionListState` 现在只有 `{ ids, byId, phase, projectionsBySession }` —— **没有
+			 * `current`**:读到的永远是 `undefined`,于是 `isCurrentPreset()` 恒为 false,
+			 * `occupy()` / `syncRail()` **一个座位都不注册**。失效形态:模式在、宿主半一切正常、
+			 * 右栏只剩宿主自带的页签、中栏没有「产物」——而且不报错。
+			 *
+			 * 宿主自己的取法(两处都用它):在 `byId` 里找 `retainedBy.mainView > 0` 的那一行
+			 * (`dsh-client-ui-open-in-app`、`dsh-client-ui-agent-preset`)。老宿主若还留着
+			 * `current`,照旧认它——那一份更精确。
+			 */
+			const currentSessionRow = () => {
 				try {
 					const state = sessions.list.getSnapshot()
-					const session = state === undefined || state.current === undefined ? undefined : state.byId[state.current]
-					const preset = session === undefined || session === null ? undefined : session.projectionValues?.agentPreset
+					if (state === undefined || state === null) return undefined
+					if (typeof state.current === 'string' && state.current !== '') return state.byId?.[state.current]
+					return Object.values(state.byId ?? {}).find((row) => (row?.retainedBy?.mainView ?? 0) > 0)
+				} catch {
+					return undefined
+				}
+			}
+			const isCurrentPreset = () => {
+				try {
+					const preset = currentSessionRow()?.projectionValues?.agentPreset
 					return typeof preset === 'string' && preset === PRESET_ID
 				} catch {
 					return false
@@ -3883,19 +3904,15 @@ window.__ModuleLoader__.load({
 			 * 三处入口(产物 / 技能 / 记忆文件)共用这一个闭包,所以是一处坏、三处全坏。
 			 *
 			 * 取法:座位自己的 `props.sessionId` 优先(更精确);props 没有时兜底读当前会话
-			 * (原生 chat 同款:`sessions.list.getSnapshot().current`)。兜底在这里成立,是因为
-			 * 面板**只在当前会话的预设是 clearai 时挂载**(`isCurrentPreset`,见上),会话切走
-			 * 时面板先注销 —— 不存在「面板还挂着、行的会话已经换了」的窗口。
+			 * (`currentSessionRow`,见上)。兜底在这里成立,是因为面板**只在当前会话的预设是
+			 * clearai 时挂载**(`isCurrentPreset`,见上),会话切走时面板先注销 ——
+			 * 不存在「面板还挂着、行的会话已经换了」的窗口。
 			 */
 			const sessionIdFor = (props) => {
 				const fromProps = props === null || props === undefined ? undefined : props.sessionId
 				if (typeof fromProps === 'string' && fromProps !== '') return fromProps
-				try {
-					const current = sessions.list.getSnapshot()?.current
-					return typeof current === 'string' && current !== '' ? current : undefined
-				} catch {
-					return undefined
-				}
+				const id = currentSessionRow()?.id
+				return typeof id === 'string' && id !== '' ? id : undefined
 			}
 			/** 每个座位按自己的 props 造一个打开器:共用一个「反正差不多」的闭包就是上面那个 bug。 */
 			const openPreviewFor = (props) => (path) => openNativePreview(sidebarRight, sessionIdFor(props), path)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clearai-dsh",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "ClearAI: an ontology-first DSH agent preset — evidence-checked research that grows into a domain ontology.",
   "type": "module",
   "private": false,