dsh-engram 0.3.6 → 0.3.7

package/README.md

@@ -238,6 +238,76 @@ curl -s -X POST http://127.0.0.1:3080/api/dsh-engram/import \
   -d "{\"payload\": $(cat engram-backup.json), \"mode\": \"merge\"}"
 ```
 
+## DSH compatibility
+
+> **Short version.** Every **published** release (`0.2.0` … `0.3.6`) supports
+> the **old** DSH API graph (`0.1.0-rc.7` / `0.1.1`, peers `^0.1.0-rc.7`)
+> **only**. DSH `0.1.2-alpha.2` and newer are **not** compatible with those
+> releases — the settings/client API family broke there. New-DSH support
+> **starts with `0.3.7`**, the first release of the new API generation
+> (described below).
+
+| dsh-engram release | Status | DSH support | Declared via |
+| --- | --- | --- | --- |
+| `0.2.0` … `0.3.6` (npm, GitHub v0.3.3–v0.3.6) | published | **old DSH only** — `0.1.0-rc.7` / `0.1.0-rc.8` / `0.1.1-rc.1` / `0.1.1-rc.2` | peers `@deepseek-ai/dsh-*@^0.1.0-rc.7` |
+| `0.3.7` (npm, GitHub v0.3.7) | published | **new DSH only** — `>=0.1.2-alpha.2 <0.2.0-0` | `engines.dsh` + peers `>=0.1.2-alpha.2 <0.2.0-0` |
+
+### Where the API family broke — `0.1.2-alpha.2`
+
+`0.1.2-alpha.2` is the first version of the new API family and the first that
+**breaks** the released plugin versions:
+
+- `@deepseek-ai/dsh-settings` **removed** `settingsNamespace()` and
+  `installSettingsSection()` — the exact imports every release ≤ `0.3.6` uses —
+  and replaced them with `settings.installSection`. The old host half fails to
+  load on `0.1.2-alpha.2+`.
+- The web client half swapped its inject set: `@deepseek-ai/dsh-client-runtime`
+  no longer exists in the new family (replaced by `dsh-api-remotes` plus
+  `dsh-client-locale` / `-conversation` / `-renderer` / `-ui-settings-plugins`),
+  and the settings card used to talk through `ctx.remote.settings`.
+- Supporting bumps at the same boundary: `@deepseek-ai/cordis` `^4.0.1 → ^4.0.2`,
+  `@deepseek-ai/schemastery` `^3.18.1 → ^3.18.2`, and `@deepseek-ai/dsh` stopped
+  shipping `config/agent-presets` in the package (moved to `dsh.configTrees`).
+
+The web config card no longer depends on any of this: since `0.3.7` it reads
+and writes the `dsh-engram` settings namespace through the plugin's **own**
+HTTP route (`/api/dsh-engram/settings`, same-origin fetch like the memory
+viewer), so the card is generation-agnostic on both sides of the
+`0.1.2-alpha.2` boundary.
+
+So: keep DSH on `0.1.1-rc.2` or older while running a release ≤ `0.3.6`, and
+upgrade the plugin to `>=0.3.7` before moving DSH to `0.1.2-alpha.2`.
+
+### Current release — `0.3.7`
+
+This release declares support for DSH `>=0.1.2-alpha.2 <0.2.0-0` and was fully
+validated against the `dsh-v0.1.5-alpha.1` source and web runtime from the local
+`deepseek-harness` checkout.
+
+| Component | Supported range |
+| --- | --- |
+| DSH runtime / host / client package family | `>=0.1.2-alpha.2 <0.2.0-0` |
+| `@deepseek-ai/cordis` | `^4.0.2` |
+| `@deepseek-ai/schemastery` | `^3.18.2` |
+| Node.js | `>=22.19.0` |
+
+`0.1.2-alpha.2` is the minimum version for this API family: host settings use
+`settings.installSection`, and the browser settings card reads and writes
+through the plugin's own HTTP route (`/api/dsh-engram/settings`, see Route B
+above). Host import and settings-registration smoke checks pass on
+`0.1.2-alpha.2` and `0.1.3-alpha.2`; the full regression suite is validated
+on `0.1.5-alpha.1` (real-machine GET/PUT/conflict/reset/persist-across-restart
+all verified on `dsh 0.1.5-rc.1` with an isolated profile). The older
+`0.1.0-rc.7` and `0.1.1` API graphs are outside this release's compatibility
+range.
+
+To install the DSH version used for validation:
+
+```sh
+npm install --global @deepseek-ai/dsh@0.1.5-alpha.1
+dsh --version
+```
+
 ## Install
 
 ```sh

package/README.zh.md

@@ -149,6 +149,66 @@ curl -s -X POST http://127.0.0.1:3080/api/dsh-engram/import \
   -d "{\"payload\": $(cat engram-backup.json), \"mode\": \"merge\"}"
 ```
 
+## 兼容性
+
+> **一句话结论**：所有**已真正发布**的版本（`0.2.0` … `0.3.6`）**只支持旧版
+> DSH**（`0.1.0-rc.7` / `0.1.1` API 图，peers `^0.1.0-rc.7`）。DSH
+> `0.1.2-alpha.2` 及更新版本与它们**不兼容**——settings/client API 族在该版本
+> 断裂。新版 DSH 支持**自 `0.3.7` 起**提供——它是新 API 代际的第一个发布（见下文）。
+
+| dsh-engram 发布版本 | 状态 | 支持的 DSH | 声明方式 |
+| --- | --- | --- | --- |
+| `0.2.0` … `0.3.6`（npm 全量 + GitHub v0.3.3–v0.3.6） | 已发布 | **仅旧版** —— `0.1.0-rc.7` / `0.1.0-rc.8` / `0.1.1-rc.1` / `0.1.1-rc.2` | peers `@deepseek-ai/dsh-*@^0.1.0-rc.7` |
+| `0.3.7`（npm + GitHub v0.3.7） | 已发布 | **仅新版** —— `>=0.1.2-alpha.2 <0.2.0-0` | `engines.dsh` + peers 同范围 |
+
+### API 族断裂点:`0.1.2-alpha.2`
+
+`0.1.2-alpha.2` 是新 API 族的第一个版本，也是第一个**让已发布插件失效**的版本：
+
+- `@deepseek-ai/dsh-settings` **移除了** `settingsNamespace()` 与
+  `installSettingsSection()`（≤ `0.3.6` 的每个发布都直接 import 这两个符号），
+  改为 `settings.installSection`——旧宿主端在 `0.1.2-alpha.2+` 上直接加载失败。
+- Web 客户端注入集整体更换：`@deepseek-ai/dsh-client-runtime` 在新代际**已不存在**
+  （被 `dsh-api-remotes` + `dsh-client-locale` / `-conversation` / `-renderer` /
+  `-ui-settings-plugins` 取代），设置卡此前改走 `ctx.remote.settings`。
+- 同一边界的伴随升级：`@deepseek-ai/cordis` `^4.0.1 → ^4.0.2`、
+  `@deepseek-ai/schemastery` `^3.18.1 → ^3.18.2`、`@deepseek-ai/dsh` 不再随包
+  发布 `config/agent-presets`（改为 `dsh.configTrees` 机制）。
+
+**web 设置卡已不依赖上面任何一项**：自 `0.3.7` 起，配置卡通过插件**自有**
+HTTP 路由（`/api/dsh-engram/settings`，与记忆 viewer 同样的同源 fetch）读写
+`dsh-engram` settings namespace，因此在 `0.1.2-alpha.2` 分界线两侧都是代际无关的。
+
+所以：跑 ≤ `0.3.6` 的已发布版本时请把 DSH 保持在 `0.1.1-rc.2` 或更旧；升级
+DSH 到 `0.1.2-alpha.2` 之前，先升级插件到 `>=0.3.7`。
+
+### 当前发布版本 —— `0.3.7`
+
+当前发布版本声明适配 DSH `>=0.1.2-alpha.2 <0.2.0-0`，并以本地
+`deepseek-harness` 的 `dsh-v0.1.5-alpha.1` 代码和 Web 运行时完成完整验证。
+
+| 组件 | 适配版本 |
+| --- | --- |
+| DSH runtime / host / client 包族 | `>=0.1.2-alpha.2 <0.2.0-0` |
+| `@deepseek-ai/cordis` | `^4.0.2` |
+| `@deepseek-ai/schemastery` | `^3.18.2` |
+| Node.js | `>=22.19.0` |
+
+`0.1.2-alpha.2` 是这组 API 的最低版本：宿主设置注册使用
+`settings.installSection`，浏览器端设置卡通过插件自有 HTTP 路由
+（`/api/dsh-engram/settings`，见上文 Route B）读写。
+`0.1.2-alpha.2` 和 `0.1.3-alpha.2` 已完成宿主导入与设置注册 smoke 验证；
+`0.1.5-alpha.1` 已完成完整回归（并在 `dsh 0.1.5-rc.1` 隔离 profile 上真机验证
+设置 GET/PUT/冲突/复位/跨重启持久化全通）。旧的 `0.1.0-rc.7` 与 `0.1.1` API 图不在
+本发布版本的兼容范围内。
+
+如需按验证版本安装 DSH：
+
+```sh
+npm install --global @deepseek-ai/dsh@0.1.5-alpha.1
+dsh --version
+```
+
 ## 安装
 
 ```sh

package/docs/RELEASE-NOTES.TEMPLATE.md

@@ -0,0 +1,68 @@
+# Release Notes 模板（每次发布必用）
+
+每个 GitHub Release 正文都应包含以下区块。**「DSH 版本支持」一节为必填**，
+其余按发布内容填写。版本支持信息从 `package.json` 读取，避免手写漂移：
+
+```sh
+# 直接生成「DSH 版本支持」markdown 段（读 package.json 的 engines.dsh + peers）
+npm run dsh-engram:release-notes
+# 或
+node scripts/gen-release-notes.mjs
+```
+
+---
+
+## 模板正文（复制后填空）
+
+```
+## dsh-engram v<版本号>
+
+<一句话：自上一个版本以来的主题>
+
+### 功能
+- ...
+
+### 修复
+- ...
+
+### 其他
+- ...
+
+## DSH 版本支持（必填）
+
+- **支持的 DSH 范围**：`<复制自 package.json engines.dsh，如 >=0.1.2-alpha.2 <0.2.0-0>`
+- **验证版本**：`<如 dsh-v0.1.5-alpha.1>`（本地 deepseek-harness checkout）
+- **最后验证日期**：`<YYYY-MM-DD>`
+- **安装方式已验证**：`<如 dsh plugin --profile web add dsh-engram>`
+- **peer 声明**：`<复制自 package.json peerDependencies 中的 @deepseek-ai/dsh-* 范围>`
+
+> ⚠️ 新旧分界：DSH `0.1.2-alpha.2` 起 settings/client API 族大改
+> （`@deepseek-ai/dsh-settings` 移除 `settingsNamespace`/`installSettingsSection`，
+> 改 `settings.installSection`；client 注入集从 `dsh-client-runtime` 换到
+> `dsh-api-remotes` 等；cordis `^4.0.2`、schemastery `^3.18.2`）。
+> 若本版本仍声明 peers `^0.1.0-rc.7`，说明它**只支持旧版 DSH**
+> （≤ `0.1.1-rc.2`），正文必须写明「仅支持旧版 DSH」并用上面第一段替换当前示例。
+```
+
+---
+
+## 历史版本口径（补注用，legacy releases 说明）
+
+已发布版本 `0.2.0` … `0.3.6` 的 Release/README 如果缺失 DSH 兼容说明，统一补这
+一段：
+
+```
+## DSH 版本支持
+
+- **支持的 DSH 范围**：仅旧版 —— `0.1.0-rc.7` / `0.1.0-rc.8` / `0.1.1-rc.1` / `0.1.1-rc.2`
+- **peer 声明**：`@deepseek-ai/dsh-*@^0.1.0-rc.7`
+- ⚠️ DSH `>=0.1.2-alpha.2` 与本版本**不兼容**（settings/client API 族在该版本断裂）。
+  如需新版 DSH，请升级插件到 `master` 的下一个发布。
+```
+
+## dsh-market 兼容信息格式参考
+
+- 包清单的版本兼容字段是 **semver 范围**：`package.json` / `dsh.plugin.json` 的
+  `engines.dsh`（如 `">=0.1.5-alpha.2"` 或 `"0.1.0-rc.6 || 0.1.2-rc.1"`）。
+- 市场侧 README 公约（`## Compatibility` 段）：
+  `DSH 版本` · `最后验证日期` · `安装方式已验证`。

package/lib/api.js

@@ -5,12 +5,14 @@
  * wears the loopback-only trust fence (copied from the SSH family): these
  * routes expose the on-disk memory store, so a LAN-exposed dsh web must not
  * serve them. All reads go straight at the opened storage-domain handle
- * (synchronous after the first open); the two mutations (archive / delete)
- * go through the same store methods the agent tools use.
+ * (synchronous after the first open); the mutations (archive / delete, and
+ * the settings card's PUT /settings) go through the same store methods the
+ * agent tools use (settings writes through the `service.settings` seam).
  */
 
 import { uuid, shortId } from "./util.js";
 import { collectToolCounts, collectUsageStats } from "./usage.js";
+import { SETTINGS_NS } from "./settings.js";
 
 /** Route family prefix (kept in sync with the client half). */
 export const API_PREFIX = "/api/dsh-engram";
@@ -541,6 +543,71 @@ export function makeEngramRoutes(service) {
     writeJson(res, 200, { items: list });
   };
 
+  /** Settings card transport — read the `dsh-engram` namespace through the
+   *  host settings service (see settings.js for the normalized `service.settings`
+   *  seam). Same-origin fetch, like every other route in this family; this is
+   *  what lets the web config card be DSH-generation-agnostic (no
+   *  connection/remote RPC), at the cost of the same loopback/trustedHosts
+   *  fence the memory viewer already wears. */
+  const getSettings = (_req, res) => {
+    const settings = service.settings;
+    if (!settings) {
+      writeError(res, 503, "settings service not available");
+      return;
+    }
+    try {
+      // dsh-settings `describe()` returns a BARE array of namespace descriptors
+      // (in registration order); older adapters may wrap it as {namespaces:[...]}.
+      // Normalize both onto the HTTP contract {namespaces:[...]} the client uses.
+      const payload = settings.describe();
+      const namespaces = Array.isArray(payload) ? payload : (payload?.namespaces ?? []);
+      const view = namespaces.find((n) => n && n.ns === SETTINGS_NS);
+      writeJson(res, 200, view ? { namespaces: [view] } : { namespaces: [] });
+    } catch (error) {
+      writeError(res, 500, String(error?.message ?? error));
+    }
+  };
+
+  /** Settings card transport — mutate the `dsh-engram` namespace. Accepts
+   *  either path ops (`ops: [{op:"set"|"unset", path:[...], value?}]`, the
+   *  exact shape the card used through the RPC) or a plain partial patch
+   *  (`patch: object`). The provider validates and persists through the same
+   *  document the GUI card always wrote to. */
+  const putSettings = async (req, res) => {
+    const settings = service.settings;
+    if (!settings) {
+      writeError(res, 503, "settings service not available");
+      return;
+    }
+    const body = await readJsonBody(req);
+    if (body.error) return writeError(res, 400, body.error);
+    const { ops, patch, expectedRevision } = body.value ?? {};
+    if (!Array.isArray(ops) && !(patch !== null && typeof patch === "object")) {
+      return writeError(res, 400, "body must provide ops (array of {op,path[,value]}) or patch (object)");
+    }
+    try {
+      if (Array.isArray(ops)) {
+        await settings.mutate(SETTINGS_NS, ops, expectedRevision);
+      } else {
+        await settings.update(SETTINGS_NS, patch, expectedRevision);
+      }
+      writeJson(res, 200, { ok: true });
+    } catch (error) {
+      if (error?.code === "SETTINGS_CONFLICT" || error?.name === "SettingsConflictError") {
+        writeJson(res, 409, {
+          error: {
+            code: "SETTINGS_CONFLICT",
+            message: String(error?.message ?? "settings moved since read"),
+            expected: error?.expected,
+            actual: error?.actual,
+          },
+        });
+        return;
+      }
+      writeError(res, 400, String(error?.message ?? error));
+    }
+  };
+
   const make = (method, path, handler) => ({
     kind: "exact",
     path: `${API_PREFIX}${path}`,
@@ -585,6 +652,7 @@ export function makeEngramRoutes(service) {
     make("GET", "/model", model),
     make("GET", "/preview", preview),
     make("GET", "/config", readConfig),
+    makeUnion("/settings", { GET: getSettings, PUT: putSettings }),
     make("POST", "/memories/archive", archive),
     make("POST", "/memories/delete", remove),
     make("POST", "/tasks/close", closeTask),

package/lib/client.js

@@ -153,6 +153,34 @@ var EngramApi = class {
       })
     );
   }
+  /** Settings card transport — read the `dsh-engram` namespace through our
+   *  own HTTP API instead of the host connection/remote RPC. */
+  async getSettings() {
+    return readJson(await fetch(`${API_PREFIX}/settings`));
+  }
+  /** Settings card transport — persist one or more path ops into the
+   *  `dsh-engram` namespace. Non-2xx surfaces the server's message. */
+  async updateSettings(ops, expectedRevision) {
+    const response = await fetch(`${API_PREFIX}/settings`, {
+      method: "PUT",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        ops,
+        ...expectedRevision !== void 0 ? { expectedRevision } : {}
+      })
+    });
+    let body = null;
+    try {
+      body = await response.json();
+    } catch {
+    }
+    if (!response.ok) {
+      const err = body;
+      const message = typeof err?.error === "string" ? err.error : typeof err?.error === "object" && err.error !== null && typeof err.error.message === "string" ? err.error.message : `HTTP ${response.status}`;
+      throw new EngramApiError(message);
+    }
+    return body ?? { ok: true };
+  }
 };
 
 // client/src/EngramTaskDock.tsx
@@ -3824,14 +3852,7 @@ var EngramScopeImpl = class {
     this.snapshot = LOADING;
     this.notify();
     try {
-      const response = await this.api.settings.describe({});
-      const result = response?.result;
-      if (!result || result.ok !== true) {
-        const err = result && "error" in result ? result.error : { code: "settings.describe", message: "unreachable" };
-        this.fail(`settings.describe failed: ${String(err?.code ?? err)}: ${String(err?.message ?? "")}`);
-        return;
-      }
-      const payload = result.value;
+      const payload = await this.api.getSettings();
       const view = payload.namespaces?.find((n) => n.ns === this.ns);
       if (!view) {
         this.fail(`the '${this.ns}' settings namespace is not served by this host.`);
@@ -3845,27 +3866,16 @@ var EngramScopeImpl = class {
         base: view.base ?? view.value,
         user: view.user,
         revision: view.revision ?? 0,
-        writable: this.opts.writable !== false && payload.writable !== false && applied
+        writable: this.opts.writable !== false && applied
       };
       this.notify();
     } catch (error) {
-      this.fail(`settings.describe threw: ${String(error instanceof Error ? error.message : error)}`);
+      this.fail(`settings fetch failed: ${String(error instanceof Error ? error.message : error)}`);
     }
   }
   async mutate(op) {
     const revision = this.snapshot.revision;
-    const response = await this.api.settings.mutate({
-      ns: this.ns,
-      ops: [op],
-      ...revision ? { expectedRevision: revision } : {}
-    });
-    const result = response?.result;
-    if (!result || result.ok !== true) {
-      const err = result && "error" in result ? result.error : { code: "settings.mutate", message: "unreachable" };
-      throw new Error(`settings.mutate failed: ${String(err?.code ?? err)}: ${String(err?.message ?? "")}`);
-    }
-    const view = result.value;
-    if (view) this.snapshot = { ...this.snapshot, revision: view.revision ?? revision };
+    await this.api.updateSettings([op], revision > 0 ? revision : void 0);
   }
   async set(key, value) {
     await this.mutate({ op: "set", path: [String(key)], value });
@@ -4924,7 +4934,7 @@ var en = {
   refresh: "Refresh",
   error: "Load failed"
 };
-var inject = ["slots", "locale", "connection", "sessions", "workspaces"];
+var inject = ["slots", "locale", "sessions", "workspaces"];
 function apply(ctx) {
   ctx.effect(() => ctx.locale.register(NS, { zh, en }), "dsh-engram: dictionaries");
   const api = new EngramApi();
@@ -4965,8 +4975,7 @@ function apply(ctx) {
   } catch (error) {
     console.warn("[dsh-engram] settings.section registration failed:", error);
   }
-  const connection = ctx.get("connection");
-  const scope = new EngramScopeImpl(connection.api, "dsh-engram");
+  const scope = new EngramScopeImpl(api, "dsh-engram");
   const cardInjected = () => ({ scope });
   try {
     ctx.slots.inject(

package/lib/index.js

@@ -258,7 +258,7 @@ export function apply(ctx, config) {
 
   // User settings (web GUI card): merges stored values onto the live config.
   // Non-blocking — when the settings service is absent this never runs.
-  installEngramSettings(ctx, resolved, resolved);
+  installEngramSettings(ctx, resolved, resolved, service);
 
   // Web API for the GUI: deferred on the webServer service, so headless
   // profiles keep running the plugin without it. `register` returns the

package/lib/settings.js

@@ -12,11 +12,12 @@
  */
 
 import z from "@deepseek-ai/schemastery";
-import { settingsNamespace, installSettingsSection } from "@deepseek-ai/dsh-settings";
 
 /** Namespace join key — must match the client card's `key`. */
 export const SETTINGS_NS_NAME = "dsh-engram";
-export const SETTINGS_NS = settingsNamespace(SETTINGS_NS_NAME);
+// dsh-settings 0.1.5 exposes the namespace as a validated string at the
+// provider boundary; the legacy branding helper was removed.
+export const SETTINGS_NS = SETTINGS_NS_NAME;
 
 /** Fields the GUI exposes (a curated subset of the plugin DEFAULTS). */
 export const SETTINGS_KEYS = [
@@ -86,30 +87,49 @@ export function makeSettingsSchema(defaults) {
 /**
  * Wire the settings section into `ctx` and keep `live` (the plugin's mutable
  * config object) merged with what the user stored. Called from `apply()`.
+ *
+ * When a `service` object is supplied, a normalized `service.settings` seam
+ * ({ describe, mutate, update }) is exposed for the web API — this is the
+ * single host-side adapter point: both the current and the legacy DSH
+ * settings APIs reduce onto the same three calls, so `/api/dsh-engram/settings`
+ * never needs to know which generation it is talking to.
  */
-export function installEngramSettings(ctx, defaults, live) {
+export function installEngramSettings(ctx, defaults, live, service) {
   const base = settingsBaseFrom(defaults);
   const schema = makeSettingsSchema(defaults);
   let source = () => base;
-  installSettingsSection(ctx, SETTINGS_NS, schema, base, {
-    setSource(current) {
-      source = current;
-    },
-    onChange() {
-      let value;
-      try {
-        value = source();
-      } catch {
-        return;
-      }
-      if (value === null || typeof value !== "object") return;
-      for (const key of SETTINGS_KEYS) {
-        if (value[key] !== void 0 && live[key] !== value[key]) live[key] = value[key];
-      }
-    },
-    validate(value) {
-      // The schema already constrains every exposed field; refuse nothing here.
-      void value;
-    },
+  ctx.inject(["settings"], (settingsCtx) => {
+    // dsh-settings 0.1.5 moved the optional-consumer wiring onto the provider
+    // instance. Keeping the registration on the scoped context preserves the
+    // provider attach/detach lifecycle while avoiding a removed helper export.
+    const provider = settingsCtx.settings;
+    if (service) {
+      service.settings = {
+        describe: () => provider.describe({ redactSecrets: true }),
+        mutate: (ns, ops, expectedRevision) => provider.mutate(ns, ops, expectedRevision),
+        update: (ns, patch, expectedRevision) => provider.update(ns, patch, expectedRevision),
+      };
+    }
+    provider.installSection(ctx, SETTINGS_NS, schema, base, {
+      setSource(current) {
+        source = current;
+      },
+      onChange() {
+        let value;
+        try {
+          value = source();
+        } catch {
+          return;
+        }
+        if (value === null || typeof value !== "object") return;
+        for (const key of SETTINGS_KEYS) {
+          if (value[key] !== void 0 && live[key] !== value[key]) live[key] = value[key];
+        }
+      },
+      validate(value) {
+        // The schema already constrains every exposed field; refuse nothing here.
+        void value;
+      },
+    });
   });
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-engram",
   "description": "Minimalist long-term memory for DeepSeek Harness, distilling symbolic-index + pi-esr ideas: zero-LLM auto-capture, a symbolic [ENGRAM] index with progressive disclosure, and an ESR-lite evidence-closure protocol (esr_task / esr_node / esr_close / esr_link). Real agent-behaviour telemetry (usage rollup + /stats) and a deterministic offline recall benchmark (npm run eval). Hot path is model-free; storage on ctx.storageDomain; web memory viewer, observability panel and config card through DSH's native settings slots.",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -33,7 +33,8 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=22.19.0"
+    "node": ">=22.19.0",
+    "dsh": ">=0.1.2-alpha.2 <0.2.0-0"
   },
   "scripts": {
     "setup": "node scripts/setup-links.mjs",
@@ -47,7 +48,8 @@
     "web-compaction:enable": "node scripts/dsh-engram.mjs enable",
     "web-compaction:revert": "node scripts/dsh-engram.mjs revert",
     "dsh-engram": "node scripts/dsh-engram.mjs",
-    "dsh-engram:doctor": "node scripts/dsh-engram.mjs doctor"
+    "dsh-engram:doctor": "node scripts/dsh-engram.mjs doctor",
+    "release-notes": "node scripts/gen-release-notes.mjs"
   },
   "publishConfig": {
     "access": "public"
@@ -59,9 +61,11 @@
     "client": {
       "platform": "web",
       "inject": [
-        "@deepseek-ai/dsh-client-runtime",
-        "@deepseek-ai/dsh-client-connection",
-        "@deepseek-ai/dsh-client-ui-settings"
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-settings-plugins"
       ]
     }
   },
@@ -69,13 +73,13 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-storage-domain": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-settings": "^0.1.0-rc.7",
-    "@deepseek-ai/schemastery": "^3.18.1",
-    "@deepseek-ai/dsh-compaction": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-compaction-basic": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-llm": "^0.1.0-rc.7"
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-storage-domain": ">=0.1.2-alpha.2 <0.2.0-0",
+    "@deepseek-ai/dsh-settings": ">=0.1.2-alpha.2 <0.2.0-0",
+    "@deepseek-ai/schemastery": "^3.18.2",
+    "@deepseek-ai/dsh-compaction": ">=0.1.2-alpha.2 <0.2.0-0",
+    "@deepseek-ai/dsh-compaction-basic": ">=0.1.2-alpha.2 <0.2.0-0",
+    "@deepseek-ai/dsh-llm": ">=0.1.2-alpha.2 <0.2.0-0"
   },
   "peerDependenciesMeta": {
     "@deepseek-ai/cordis": {

package/scripts/gen-release-notes.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * dsh-engram release-note helper.
+ *
+ * Prints the required "DSH 版本支持" markdown stanza for a release note by
+ * reading the single source of truth in package.json (engines.dsh + the
+ * @deepseek-ai/dsh-* peers), so the declared compatibility can never drift
+ * from what the package.json actually claims.
+ *
+ * Usage:
+ *   node scripts/gen-release-notes.mjs            # print the stanza
+ *   node scripts/gen-release-notes.mjs --watch    # also echo engines + peers
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(readFileSync(resolve(root, "package.json"), "utf8"));
+
+const engines = pkg.engines ?? {};
+const peers = pkg.peerDependencies ?? {};
+
+const DSH_PEER_PREFIX = "@deepseek-ai/dsh-";
+const dshPeers = Object.entries(peers)
+  .filter(([name]) => name.startsWith(DSH_PEER_PREFIX))
+  .sort(([a], [b]) => a.localeCompare(b));
+
+const range = engines.dsh;
+const legacyOld =
+  !range && dshPeers.every(([, r]) => r.includes("0.1.0-rc.7"));
+const supportLine = legacyOld
+  ? "仅旧版 —— `0.1.0-rc.7` / `0.1.0-rc.8` / `0.1.1-rc.1` / `0.1.1-rc.2`"
+  : range ?? "（package.json 未声明 engines.dsh —— 补注历史版本时按上一行规则填写）";
+
+const peerLine = dshPeers.length
+  ? dshPeers.map(([n, r]) => `  - \`${n}\`: \`${r}\``).join("\n")
+  : "  - （无 @deepseek-ai/dsh-* peer 声明）";
+
+const body = `## DSH 版本支持
+
+- **支持的 DSH 范围**：${supportLine}
+- **peer 声明**：
+${peerLine}
+${
+  legacyOld
+    ? "- ⚠️ DSH `>=0.1.2-alpha.2` 与本版本**不兼容**（settings/client API 族在该版本断裂：`@deepseek-ai/dsh-settings` 移除 `settingsNamespace`/`installSettingsSection`，改 `settings.installSection`；client 注入集换到 `dsh-api-remotes` 等；cordis `^4.0.2`、schemastery `^3.18.2`）。如需新版 DSH，请升级插件到 `master` 的下一个发布。"
+    : range
+      ? `- **验证版本**：<如 dsh-v0.1.5-alpha.1>（本地 deepseek-harness checkout）
+- **最后验证日期**：<YYYY-MM-DD>
+- **安装方式已验证**：<如 dsh plugin --profile web add dsh-engram>`
+      : ""
+}
+`;
+
+if (process.argv.includes("--watch")) {
+  console.log(`engines.dsh = ${range ?? "<未声明>"}`);
+  console.log(`engines.node = ${engines.node ?? "<未声明>"}`);
+  console.log(`@deepseek-ai/cordis peer = ${peers["@deepseek-ai/cordis"] ?? "<未声明>"}`);
+  console.log(`@deepseek-ai/schemastery peer = ${peers["@deepseek-ai/schemastery"] ?? "<未声明>"}`);
+  console.log("---");
+}
+process.stdout.write(body);

package/scripts/prepublish-check.mjs

@@ -23,10 +23,10 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const tmp = mkdtempSync(join(tmpdir(), "dsh-engram-pack-"));
 const PEERS = [
-  "@deepseek-ai/cordis@^4.0.1",
-  "@deepseek-ai/dsh-settings@^0.1.0-rc.7",
-  "@deepseek-ai/dsh-storage-domain@^0.1.0-rc.7",
-  "@deepseek-ai/schemastery@^3.18.1",
+  "@deepseek-ai/cordis@^4.0.2",
+  "@deepseek-ai/dsh-settings@>=0.1.2-alpha.2 <0.2.0-0",
+  "@deepseek-ai/dsh-storage-domain@>=0.1.2-alpha.2 <0.2.0-0",
+  "@deepseek-ai/schemastery@^3.18.2",
 ];
 
 function sh(cmd, args, cwd) {

package/scripts/setup-links.mjs

@@ -93,6 +93,11 @@ function findStoreZod(harness) {
 function buildPlan(harness) {
   const zodDir = findStoreZod(harness);
   const plan = [
+    {
+      label: "@deepseek-ai/cordis",
+      mount: join(SCOPE, "cordis"),
+      target: join(harness, "vendor", "cordis"),
+    },
     {
       label: "zod",
       mount: join(NODE_MODULES, "zod"),
@@ -141,7 +146,9 @@ function buildPlan(harness) {
 function isInstalled(mount, expected) {
   if (existsSync(mount)) {
     try {
-      if (resolve(readlinkSync(mount)) === resolve(expected)) return true;
+      // readlinkSync() returns a relative target for pnpm-created links; resolve
+      // it from the mount's parent, rather than from the process cwd.
+      return resolve(dirname(mount), readlinkSync(mount)) === resolve(expected);
     } catch {
       /* not a symlink — fall through */
     }
@@ -185,24 +192,27 @@ function ensureLink(item) {
       return;
     }
     // 允许替换：符号链接直接 unlink；pnpm 预建的空目录用 rmdir 清掉。
+    let removed = false;
     try {
       unlinkSync(mount);
       console.log(`  ~ ${label}: 替换旧链接`);
-      return;
+      removed = true;
     } catch {
       /* not a symlink */
     }
-    try {
-      if (readdirSync(mount).length === 0) {
-        rmdirSync(mount);
-        console.log(`  ~ ${label}: 移除空目录后重建`);
-      } else {
-        console.log(`  ! ${label}: ${mount} 是含文件的真实目录，无法自动替换，请手动清理后重试`);
+    if (!removed) {
+      try {
+        if (readdirSync(mount).length === 0) {
+          rmdirSync(mount);
+          console.log(`  ~ ${label}: 移除空目录后重建`);
+        } else {
+          console.log(`  ! ${label}: ${mount} 是含文件的真实目录，无法自动替换，请手动清理后重试`);
+          return;
+        }
+      } catch {
+        console.log(`  ! ${label}: ${mount} 无法自动替换，请手动清理后重试`);
         return;
       }
-    } catch {
-      console.log(`  ! ${label}: ${mount} 无法自动替换，请手动清理后重试`);
-      return;
     }
   }
   if (CHECK_ONLY) {