dsh-engramory-recall 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -3,6 +3,81 @@
 本项目的所有重要变更都记在这里。格式参照 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [0.4.1] — 2026-10-15
+
+### 变更
+
+- `index.js` 的注释里去掉一处个人用户名 —— 发布包里唯一带私人痕迹的地方。
+  **没有任何行为变化**，纯粹是让别人打开源码时不看见作者的本机名。
+
+## [0.4.0] — 2026-10-15
+
+**本插件从此是一个完整的记忆系统 —— 不再依赖 `dsh-engramory`。**
+
+### 新增
+
+- **融入 `dsh-engramory` 的两件事**（它一共只做这两件，逻辑与措辞逐字保留）：
+  - **索引上限闸门**（`index-guard.js`）：`MEMORY.md` 长过 200 行 / 25 KB 就**拒绝写入**，
+    但「缩小的重写永远放行」—— 那条例外看着像后门，实则是唯一的出路：索引一旦超限，
+    若不放行缩小，就没有任何一次写入能把它降下来，闸门会把自己锁死。
+    路径不必配置，固定是 `<storePath>/MEMORY.md`（原插件为此要人手钉一个绝对路径，
+    因为它按 basename 匹配会误伤别的项目里同名的 `MEMORY.md`）。
+  - **`engramory` 技能**（`skill.js`）：写入纪律的正文，注册进 `ctx.skills`。
+    `description` / `whenToUse` 与正文逐字保留它的措辞 —— 那些句子被反复打磨过，
+    尤其「问候不算任务」那段边界，改一个字都可能松动纪律。
+  新配置项 `indexMaxLines` / `indexMaxBytes` / `registerSkill`。
+  融进来的理由不只是省一个依赖：两套闸门各管一半（这边管笔记文件、那边管索引），
+  **判据一旦漂移就会互相打架**，而这个项目已经因为「同一个概念有两处定义」栽过三次。
+- **对照 C（正文独有词当查询）** 加进探针：query 词取自某篇正文、且任何标题里都没有它。
+  它是**唯一能中立评价标题权重**的构造（A/B 都拿标题当查询，对此结构性偏袒）。
+  60 篇 / 172 chunk 下 159 条：`top1 123/159 · recall@4 148/159`。
+
+### 变更
+
+- **`TITLE_EXTRA` 3 → 24。** 0.3.1 把它定成 3 的理由有个没发现的漏洞：「口径在 3 之后
+  不再动，所以后面的增量全来自对照，而对照只是别掉分的底线」—— 可对照 A/B **都拿标题
+  当查询**，对标题权重是**结构性偏袒**的，它们既不能当目标函数，**也不能**用来证明
+  「抬高标题权重是安全的」（它们测不出这件事）。补上中立的对照 C 后，数据说 3 太保守：
+  C 从 0 到 96 **一路不降**（`118/140 → 122/140 → … → 148/159`），在 **24** 到达平台，
+  之后 32/48/96 一动不动。原先担心的「标题压过正文」在数据里**不存在**。
+  取 24 = 第一个让 C 到达平台的取值（48/96 只多 1 个 top1，@4 一个不涨）。
+  口径在**所有**取值上恒为 20/21，对这个参数**没有分辨力** —— 这一点必须写下来，
+  免得下一轮又有人拿「口径没动」当作「所以取哪个都行」。
+
+### 测试
+
+- 128 个用例全绿（原 94）。新增 `test/index-guard.test.mjs`（17）与 `test/skill.test.mjs`（17）。
+  技能那套守的是**融合的完整性**：正文是搬来的，最容易出的不是语法错，而是**边界被悄悄放松**
+  （比如「问候不算任务」那句没了），而那不会有任何报错。
+
+## [0.3.1] — 2026-10-15
+
+来源：清点灵枢（`dsh-memory`）最后一份可读产物时，发现两个**我们还没吸收**的机制。
+一个采纳、一个实测量到**有害**并否决 —— 两条都留在代码里当证据。
+
+### 新增
+
+- **字段加权（`TITLE_EXTRA = 3`）**：标题与描述里的词额外多计 3 遍（BM25F 的廉价近似）。
+  此前 `title/description/body` 被拼成一坨等权处理，于是「长笔记正文里偶然提过一次」
+  和「标题就叫这个」同分。实测（指纹 `c9f7fcbf9426`）：对照A `top1 20→21 | @4 79→91`、
+  对照B `top1 134→141 | @4 144→146`，口径 / 桥探针 / 别名探针**一项未变**。
+  出处：灵枢 `scoreEntry`（`lib/index.js:127-129`）的标题 3 / 标签 2 / 正文 1。
+
+### 记录在案（否决）
+
+- **整句子串命中奖励（`PHRASE_BONUS`）实测有害，保持 0**：机制与常量都保留，
+  但实测让它单调恶化 —— 在 `TITLE_EXTRA=3` 之上取 `2/5/10` 时，对照A top1 从
+  `21 → 20 → 19 → 17`，而口径一步不动。机理与踩过两次的自污染一致：它奖励的是
+  「逐字引用了查询」的笔记，于是把更该命中的那篇挤下去。常量旁的注释里有完整数据表，
+  将来谁想加，先看那张表。
+
+### 说明（判断）
+
+- 字段加权的扫描里，`6` 与 `24` 在**对照**上继续变好（`24/92`、`33/93`），但口径
+  在 `3` 之后**一步都不再动**。取 `3`（设计值）而非扫描极值：对照在本项目的 README 里
+  写明是「别掉分的底线」而非目标函数，拿它当目标去调参正是 `EXTRA_WEIGHT` 那次
+  「把功劳记错对象」的同一个坑。要往上抬，`bm25.js` 的常量注释里有现成证据表。
+
 ## [0.3.0] — 2026-10-15
 
 这一版的共同点是：**把「看起来在工作」变成「量得出来在工作」**。

package/README.md

@@ -95,11 +95,11 @@
    `form: notice`），内容是「可能相关的既有条目」= 文件名 + 命中行片段 + 一句「需要细节自己 read」；
 5. 没命中 → 原样放行。
 
-### 八个机制一览
+### 十个机制一览
 
 | # | 机制 | 治什么 |
 |---|---|---|
-| 1 | 同义扩展（65 条口语→技术词）+ 连字符再切分 | 中文口语与笔记用词对不上的「同义鸿沟」 |
+| 1 | 同义扩展（105 条口语→技术词）+ 连字符再切分 | 中文口语与笔记用词对不上的「同义鸿沟」 |
 | 2 | 超长正文按 `##` 切桶 + **整篇**长度归一 | 单篇巨文霸榜（一篇 267KB 的笔记曾占掉 1/4 召回位） |
 | 3 | 寒暄 / 极短消息门控 | 「继续 / 嗯」这类消息 10/10 注入噪音 |
 | 4 | **写入闸门（fail-closed）** | 不合规文件名、缺失 frontmatter、疑似真实凭据 |
@@ -107,6 +107,14 @@
 | 6 | 预算降级阶梯 | 装不下的条目塌缩成只剩文件名，而不是静默丢掉 |
 | 7 | 跨轮轮换降权 | 最近注入过的条目在后续轮次乘 0.5，把机会让给别的笔记 |
 | 8 | 沉淀提醒 | **长会话一次都没写过记忆库时，提醒一次** —— 补「该记的没记」 |
+| 9 | **索引上限闸门**（`index-guard.js`） | `MEMORY.md` 长过 200 行 / 25KB 就拒绝写入 —— 索引是每次都读的，超限部分会被**静默地**不再召回 |
+| 10 | **`engramory` 技能**（`skill.js`） | 什么时候该记、什么时候不该记这套纪律本身 —— 把它注册成技能，才不依赖外部插件 |
+
+> 9 与 10 是 **2026-10-15 从 `dsh-engramory` 整个融进来的**（逻辑与措辞逐字保留）。
+> 那个插件一共只做这两件事，收完之后它就可以从 profile 里摘掉了。
+> 融进来的理由不只是省一个依赖：两套闸门各管一半（这边管笔记文件、那边管索引）、
+> 判据一旦漂移就会互相打架，而这个项目**已经因为「同一个概念有两处定义」栽过三次**
+> （见文末第五条）。一个概念一处定义。
 
 ### 写入闸门（`guard.js`）
 
@@ -319,6 +327,9 @@ aliases: 梯子, 翻墙, 科学上网, 美国节点, 代理
         decayHalfLifeDays: 0     # freshness 指数衰减
         recencyWeight: 0         # 时间乘性加权
         autoArchive: false       # 全自动归档（默认关：归档是改库，先手动点几轮再决定）
+        indexMaxLines: 200       # 索引 MEMORY.md 的行数上限（融合自 dsh-engramory）
+        indexMaxBytes: 25600     # 索引的字节上限（同上）
+        registerSkill: true      # 注册 engramory 技能（写入纪律的正文）
 ```
 
 > `autoArchive` 打开后归档会在两处自动跑：每轮 pre-step 兜底（10 分钟 TTL，不会每轮扫库），
@@ -328,7 +339,8 @@ aliases: 梯子, 翻墙, 科学上网, 美国节点, 代理
 ## 安装 / 卸载
 
 ```bash
-dsh plugin --profile <profile> add /path/to/dsh-engramory-recall
+npm i dsh-engramory-recall                              # 从 npm 装
+dsh plugin --profile <profile> add /path/to/dsh-engramory-recall   # 或从源码目录装
 dsh plugin --profile <profile> remove dsh-engramory-recall
 ```
 
@@ -336,17 +348,24 @@ dsh plugin --profile <profile> remove dsh-engramory-recall
 > 软链断链时宿主只会打印一行 `skipping profile bundle`，**插件整轮不加载却不影响其它功能**
 > —— 这个坑我们真踩过（白测了三天）。
 
+> ⚠️ **`dsh plugin` 是「全有或全无」的**：它每次都会重装 profile 的**整个**依赖集，
+> 所以只要 `package.json` 里有**任何一个** spec 解析不了（版本被 registry 下架、
+> 被供应链策略拦住、指向已删的路径），**添/删任何插件都会一起失败**，
+> 而且报错说的是那个无关的包。2026-10-15 真踩过：`dsh-boot-animation@^0.1.2`
+> 的版本被镜像下架，导致「移除 `dsh-engramory`」报的是 `dsh-boot-animation` 的错。
+> 排查时看 `.plugin-manager/logs/operation-*/pnpm.log`，别盯被操作的那个包。
+
 ## 测试与自检
 
 ```bash
-npm test        # 89 个用例：分词 / BM25 / 切桶 / 门控 / 闸门 / 体检 / 审计 / 沉淀提醒 / 归档 / 打包 / 路由
+npm test        # 132 个用例：分词 / BM25 / 切桶 / 门控 / 闸门 / 索引闸门 / 技能注册 / 体检 / 审计 / 沉淀提醒 / 归档 / 打包 / 路由
 npm run check   # 检查 profile 接线是否还覆盖得住上游默认键
-npm run probe   # 召回质量探针：3 组 query（36 条）+ 两道对照，跑在**真实记忆库**上
+npm run probe   # 召回质量探针：3 组 query（36 条）+ 三道对照，跑在**真实记忆库**上
 npm run probe -- --save   # 把这次结果存成基线，之后每次跑自动比对
 ```
 
 > 这三条是**克隆仓库开发时**用的：`test/` 与 `scripts/` 不在 npm 包的 `files` 白名单里。
-> 发布出去的是运行时真正需要的那 12 个文件（`npm pack --dry-run` 可核），
+> 发布出去的是运行时真正需要的那 15 个文件（`npm pack --dry-run` 可核），
 > 其中 `package.test.mjs` 会从 `index.js` 递归跟所有 `./x.js` 的 import，
 > 逐个核对是否都在白名单里 —— 这个检查已经抓到过两次真事故（漏 `audit.js`、漏 `archive.js`），
 > 两次的后果都是别人装上一装就 `ERR_MODULE_NOT_FOUND`、整个插件加载失败。
@@ -359,8 +378,15 @@ npm run probe -- --save   # 把这次结果存成基线，之后每次跑自动
 | **桥探针** | 10 | 全局同义表（大白话问英文/术语密集的笔记） | recall@4 **10/10** |
 | **别名探针** | 5 | 笔记自己的 `aliases:`（关键词在全局桥里一个都没有） | recall@4 **5/5** |
 | **死桥自检** | 301 值 | 同义桥每个值是否真的存在于语料（不存在 = 白写） | **25 个死值**（均为通用词，见上） |
-| 对照 A | 169 | 把文件名当 query 的底线 | top1 22/169 · recall@4 82/169 |
-| 对照 B | 144 | 把笔记中文标题当 query 的底线 | top1 135/144 · recall@4 142/144 |
+| 对照 A | 172 | 把文件名当 query 的底线（**对标题权重有偏袒，见下**） | top1 33/172 · recall@4 93/172 |
+| 对照 B | 147 | 把笔记中文标题当 query 的底线（**同上，偏袒**） | top1 142/147 · recall@4 146/147 |
+| **对照 C** | 159 | **正文独有词**当 query（词在任何标题里都没有） | top1 123/159 · recall@4 **148/159** |
+
+> 对照 A 与对照 B **都拿标题当查询**，所以它们对「标题里的词多计几遍」这类参数是
+> **结构性偏袒**的：抬高标题权重几乎必然让这两组变好 —— 那不是证据，是同义反复。
+> 它们既不该当目标函数，**也不能**用来证明「抬高标题权重是安全的」（它们测不出这件事）。
+> 唯一中立的是**对照 C**：query 词取自某篇正文、且任何标题里都没有它，此时抬高标题权重
+> 只会让标题里恰好撞上这个词的**别的**笔记平白加分、把正确答案挤下去。
 
 `npm run probe` 存在的理由值得单说：`bm25.js` 里的同义表与 `EXTRA_WEIGHT`（同义桥权重）
 是**语料统计量撑起来的经验值**，在小 fixture 里测不出差异 —— 我们写过一版单测，
@@ -396,6 +422,12 @@ node verify-panel.mjs
 
 ## 集百家之长：一半的机制不是我们想出来的
 
+**2026-10-15 补完最后两块拼图：`dsh-engramory` 已整个融进来。** 它一共只做两件事 ——
+`MEMORY.md` 的行数/字节上限闸门（逻辑搬进 `index-guard.js`）和注册 `engramory` 技能
+（正文搬进 `skill.js`，措辞逐字保留）。两件都收进来之后，**本插件就是一个完整的记忆系统，
+不再依赖任何外部记忆插件**；那个插件现在可以从 profile 里摘掉了。
+
+
 四家竞品的源码逐个读完（hindsight / 灵枢 dsh-memory / dsh-mnemon / dsh-mneme），
 产出要求是「机制 + `文件:行号` + 能否在纯 JS、零依赖、零出网下复刻」。**能搬的搬，
 搬不动或搬了没用的当场证伪** —— 证伪的那两条同样有价值，见文末。
@@ -427,7 +459,7 @@ node verify-panel.mjs
 | DSH-SEP | 每步 ~1250 字符 guidance + ≤4200 字符快照 | 同上 | 抽取走 `api.deepseek.com` |
 | **本插件** | **0** | **≤480 字符，且只有指针** | **无** |
 
-## 四条被实测证伪的路（留着别再走一遍）
+## 五条被实测证伪的路（留着别再走一遍）
 
 | 尝试 | 结果 |
 |---|---|
@@ -435,6 +467,7 @@ node verify-panel.mjs
 | freshness 时间衰减（学灵枢 / mneme） | 六档半衰期扫描：recall 恒为 28/28、top-1 只有一档 +1（噪声级）。库里「旧」的那批恰好是基础事实，衰减就是误伤 |
 | 时间乘性加权（学 hindsight） | 五档扫描净收益为零，w ≥ 0.1 起反而伤对照组 |
 | 给一个已有同义桥**继续加词**（`主题` 从 `['theme']` 扩到含 `light-dark / color-mix / data-theme / token`） | 看着全是相关的技术词，实测**对照 B 掉 3 分**（136→133）。机制：把词加进查询扩展后，**同一篇笔记自己的其它 chunk 会把"标题里真的写着这个词"的那个 chunk 挤下去** —— 长笔记里这叫自己跟自己抢。判据不是"这词相不相关"，而是"加了它，谁会往上浮"。这 4 个词已全部退回 |
+| **拿偏袒的对照当护栏**：用对照 A/B 证明"抬高标题权重是安全的" | 它们**都拿标题当查询**，对标题权重结构性偏袒 —— 抬高它必然让两组变好。这不是证据，是同义反复。`TITLE_EXTRA` 第一次定成 3 就是被这个漏洞困住的（"口径在 3 之后不再动，所以后面的增量全来自对照"—— 对照根本测不出这件事）。补了中立的**对照 C** 之后，数据说 3 太保守：C 从 0 到 96 一路不降，在 **24** 到达平台。已按 C 的拐点改成 24 |
 
 ## 许可
 

package/bm25.js

@@ -34,6 +34,75 @@ const B = 0.75;
  * 教训：**A/B 要在最终状态上做**。中途量出来的差值，可能只是「另一半还没做完」。
  */
 const EXTRA_WEIGHT = 0.5;
+/**
+ * 字段加权：标题与描述里的词额外多计几遍（BM25F 的廉价近似）。
+ *
+ * 出处：灵枢 `dsh-memory` 的 `scoreEntry`（`lib/index.js:127-129`）给标题 3 分、
+ * 标签 2 分、正文 1 分，理由是「在标题里出现」本身就是强信号。我们原来把
+ * title/description/body 拼成一坨等权处理（`buildIndex`），于是「一篇长笔记
+ * 正文里偶然提过一次」和「标题就叫这个」拿一样的分。
+ *
+ * 用「多计几遍」而不是真做字段分离：BM25 的长度归一化会跟着一起变，
+ * 而短笔记的标题命中本来就该更值钱。
+ *
+ * 实测（2026-10-15，60 篇 / 172 chunk，指纹 c9f7fcbf9426）：
+ *   值   口径     桥     别名   对照A top1/@4   对照B top1/@4   对照C top1/@4
+ *   0   20/21  10/10   5/5    20 / 79        134 / 144      118 / 140
+ *   1   20/21  10/10   5/5    20 / 77        138 / 144      122 / 140
+ *   3   20/21  10/10   5/5    21 / 91        141 / 146      122 / 141
+ *   6   20/21  10/10   5/5    24 / 92        142 / 146      122 / 141
+ *   8   20/21  10/10   5/5     —              —              122 / 145
+ *  12   20/21  10/10   5/5    24 / 92        142 / 146      122 / 146
+ *  16   20/21  10/10   5/5     —              —              123 / 146
+ *  24   20/21  10/10   5/5    33 / 93        142 / 146      123 / 148
+ *  32   20/21  10/10   5/5     —              —              123 / 148
+ *  48   20/21  10/10   5/5     —              —              124 / 148
+ *  96   20/21  10/10   5/5     —              —              123 / 148
+ *
+ * ── 为什么从 3 改到 24（2026-10-15 第二次定这个值时想清楚的）──
+ *
+ * 第一次取 3 的理由是「口径在 3 之后不再动，所以后面的增量全来自对照，而对照只是
+ * 别掉分的底线」。那个理由有个**没被发现的漏洞**：对照 A 与对照 B **都拿标题当查询**，
+ * 所以它们对标题权重是**结构性偏袒**的 —— 抬高标题权重几乎必然让这两组变好，那不是
+ * 证据，是同义反复。拿它们当目标函数固然错，拿它们当「没变差就行」的护栏**也**证明
+ * 不了抬高标题权重是安全的：它们根本测不出这件事。
+ *
+ * 于是补了**对照 C（正文独有词当查询）**：query 词取自某篇正文、且**任何**标题/描述
+ * 里都没有它（df ≤ 3）。这时抬高标题权重只会让标题里恰好撞上这个词的**别的**笔记
+ * 平白加分、把正确答案挤下去 —— 这是唯一能中立评价标题权重的构造。
+ *
+ * 对照 C 的结果：**从 0 到 96 一路不降**（118 → 122 → … → 148），在 **24** 到达平台，
+ * 之后 32/48/96 一动不动。原先担心的「标题压过正文」现象**在数据里不存在**。
+ * 机制上讲得通：同一篇笔记的每个 chunk 共用同一个标题，所以标题权重实质上是一个
+ * **笔记级的话题先验**，而不是「标题党的胜利」。
+ *
+ * 取 **24**（= 第一个让不受偏袒的对照 C 到达平台的取值），不取 48/96 ——
+ * 它们只多 1 个 top1、@4 一个不涨。口径在**所有**取值上都恒为 20/21，
+ * 所以它对这个参数**没有分辨力**，不能拿它做任何取舍（这一点必须诚实地写下来，
+ * 免得下一轮又有人拿「口径没动」当作「所以取哪个都行」）。
+ */
+const TITLE_EXTRA = 24;
+/**
+ * 整句子串命中奖励：文档里逐字出现了整条查询时加的分。
+ *
+ * 出处：灵枢 `dsh-memory`（`lib/index.js:133`，它加 2 分）。
+ * 对中文特别有意义：没有分词器时「浏览器起不来」被拆成 `浏览/览器/器起/起不/不来`，
+ * 通用谓语的碎片反而 IDF 更高；而整句子串命中是**不需要分词器**的强证据。
+ *
+ * ⚠️ 风险（诚实写明）：这条奖励的是「逐字引用了查询」的笔记 —— 而那正是我们
+ * 踩过两次的自污染形态（调优笔记抄了探针 query 就霸榜）。
+ *
+ * **实测否决（2026-10-15，在 TITLE_EXTRA=3 之上）**：
+ *   PHRASE_BONUS   口径     对照A top1   对照B top1
+ *       0         20/21      21         141
+ *       2         20/21      20         142
+ *       5         20/21      19         142
+ *      10         20/21      17         142
+ * 口径一步不动，对照A 单调恶化（21 → 17）—— 奖励「抄了查询的笔记」确实会把
+ * 更该命中的那篇挤下去，与自污染的机理一致。**所以保持 0，机制留在代码里当证据**：
+ * 将来若有人想加，先看这张表。常量与实现都保留，是为了让这次否决可复现，不是待办。
+ */
+const PHRASE_BONUS = 0;
 /**
  * 单次查询最多参与打分的词项数（IDF 选词的 cap，抄 hindsight
  * `engine/search/bm25_term_selection.py`，与灵枢 `cn_recall_grams` 的 cap 同源）。
@@ -293,12 +362,19 @@ export function buildIndex(docs, options = {}) {
     // 没写 aliases 的笔记不受影响。
     const aliases = Array.isArray(doc.aliases) ? doc.aliases.filter(Boolean).join(' ') : '';
     const tokens = tokenize(aliases ? `${text}\n${aliases} ${aliases}` : text);
+    // 字段加权：标题/描述里的词额外多计几遍（见 TITLE_EXTRA）。默认关闭时整段不执行。
+    if (TITLE_EXTRA > 0) {
+      const head = [doc.title, doc.description].filter(Boolean).join('\n');
+      if (head) for (let i = 0; i < TITLE_EXTRA; i += 1) tokens.push(...tokenize(head));
+    }
     const tf = new Map();
     for (const t of tokens) tf.set(t, (tf.get(t) ?? 0) + 1);
     return {
       ...doc,
       tf,
       len: tokens.length || 1,
+      // 整句子串命中用的小写全文（见 PHRASE_BONUS）。关闭时不建，省一份内存。
+      plain: PHRASE_BONUS > 0 ? text.toLowerCase() : '',
       decay: decayFactor(doc.mtimeMs, halfLifeDays, now),
       boost: recencyBoost(doc.mtimeMs, oldestMs, newestMs, recencyWeight),
     };
@@ -322,6 +398,11 @@ export function search(index, query, limit = 5) {
   const extras = expandQuery(query);
   if (!base.length && !extras.length) return [];
 
+  // 整句子串命中的针（见 PHRASE_BONUS）。太短的查询不判：像「线上」这种两个字，
+  // 逐字命中满库都是，只会制造噪声。
+  const needle = PHRASE_BONUS > 0 ? String(query ?? '').trim().toLowerCase() : '';
+  const usePhrase = needle.length >= 2;
+
   const weights = new Map();
   for (const term of base) weights.set(term, 1);
   for (const term of extras) if (!weights.has(term)) weights.set(term, EXTRA_WEIGHT);
@@ -369,6 +450,8 @@ export function search(index, query, limit = 5) {
     // decay 无界（指数，默认关）、boost 有界（±w，默认关），各自独立开关。
     score *= doc.decay ?? 1;
     score *= doc.boost ?? 1;
+    // 整句子串命中：加在乘性调整之后，是纯粹的加法微调，不参与 BM25 的饱和曲线。
+    if (usePhrase && score > 0 && doc.plain.includes(needle)) score += PHRASE_BONUS;
     if (score > 0) hits.push({ id: doc.id, section: doc.section, score, snippet: bestLine(doc, matched), matched });
   }
   hits.sort((a, b) => b.score - a.score || String(a.id).localeCompare(String(b.id)));

package/index-guard.js

@@ -0,0 +1,171 @@
+/**
+ * index-guard.js —— `MEMORY.md` 索引上限闸门（默认 200 行 / 25KB）。
+ *
+ * **融合自 `dsh-engramory` v0.2.5 的 `refuseOversizedIndex`（其 `index.js:128-230`）。**
+ * 吸收它的理由：本插件要做**完整的记忆系统**，不该把「索引上限」这一块留在外部依赖里
+ * —— 那个插件一共只做两件事（本闸门 + 注册 `engramory` 技能），我们把两件都收进来之后，
+ * 它就可以退场了。
+ *
+ * 原文的核心设计逐条保留（这些是踩过坑才有的，不要想当然地简化）：
+ *
+ *  1. **只拒绝「确实在长大」的写入**。判据是「某一维**最终超限** 且 **比当前文件大**」，
+ *     所以任何**缩小**的重写永远放行 —— 否则索引一旦超限就再也压不回去，变成死锁。
+ *     用户看到的是「先压缩」的提示，而压缩这条路必须是通的。
+ *  2. **当前文件不存在/读不到 = 空**（0 行 0 字节），所以「第一次写入就超限」照样拒绝。
+ *  3. **字节数取原始 buffer**，不先 decode。原文注释记了原因：非 UTF-8 的索引解码后
+ *     每个坏字节变成 3 字节的 U+FFFD，会把一次**真增长**算成**缩小**而放行。
+ *     行数可以用解码后的文本（换行不会因有损解码而改变）。
+ *  4. **片段写入（edit）先做模拟**：能还原出结果就按结果判；还原不出来（参数形状不认），
+ *     就只在「当前已经超限」时拒绝盲改 —— 且明确告诉对方出口是整篇重写。
+ *  5. **basename 大小写不敏感**：macOS/Windows 上 `memory.md` 就是那个索引。
+ *  6. 行数按**末尾换行不敏感**计（`"a\n"` 是 1 行不是 2 行）。
+ *
+ * 我们**没有**搬过来的部分（诚实写明，别以为它有）：
+ *  - `str_replace_editor` 那套工具名与 `old_str`/`new_str` 参数形状 —— 本宿主用的是
+ *    `write` / `edit`（`old_string`/`new_string`），搬一套用不上的分支是纯负担。
+ *  - `indexName` 配置项：本插件**知道**库在哪，索引路径直接由 `storePath` 推出来
+ *    （`<storePath>/MEMORY.md`），比人手钉一个绝对路径更不容易错。
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+/** 行数上限。与 `AGENTS.md` 里写的「索引上限 200 行 / 25KB」一致。 */
+export const DEFAULT_MAX_INDEX_LINES = 200;
+/** 字节上限（25KB = 25600，取十进制，与 dsh-engramory 的默认值一致）。 */
+export const DEFAULT_MAX_INDEX_BYTES = 25600;
+
+/** 能整篇替换内容的工具：给了 `content` 就能算出写入后的完整结果。 */
+const WHOLE_FILE_TOOLS = new Set(['write']);
+/** 只给片段的工具：只能靠模拟还原结果。 */
+const PARTIAL_TOOLS = new Set(['edit']);
+
+/**
+ * 末尾换行不敏感的行数。`""` → 0，`"a\n"` → 1，`"a\nb"` → 2。
+ * （与 dsh-engramory 的 `countLines` 逐字一致 —— 两边算出来的数必须一样，
+ * 否则同一个索引在两次检查里会有两个高度。）
+ */
+export function countLines(text) {
+  if (!text) return 0;
+  return text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
+}
+
+/** 人类可读的超限描述；没超返回 `null`。 */
+export function measureIndex(text, maxLines, maxBytes) {
+  const lines = countLines(text);
+  const bytes = Buffer.byteLength(text, 'utf8');
+  const over = [];
+  if (lines > maxLines) over.push(`${lines} 行 > ${maxLines}`);
+  if (bytes > maxBytes) over.push(`${bytes} 字节 > ${maxBytes}`);
+  return over.length ? over.join('，') : null;
+}
+
+/** 还原一次 edit 的写入结果；参数形状认不出来时返回 `undefined`。 */
+function simulateEdit(current, oldString, newString) {
+  if (typeof oldString !== 'string' || oldString === '') return undefined;
+  const next = typeof newString === 'string' ? newString : '';
+  const first = current.indexOf(oldString);
+  // 找不到 old_string：真正的工具会报错、什么也不改 —— 那「当前内容」就是诚实的预测。
+  if (first === -1) return current;
+  // 出现多次：真正的工具同样会报错，什么都不改。
+  if (current.indexOf(oldString, first + oldString.length) !== -1) return current;
+  return current.slice(0, first) + next + current.slice(first + oldString.length);
+}
+
+/** 读原始 buffer；读不到返回 `undefined`（读不到不算超限，见文件头第 2 条）。 */
+function readRaw(filePath) {
+  try {
+    return readFileSync(filePath);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * 判一次写入是否会把索引顶过上限。
+ *
+ * @param {object} input
+ * @param {string} input.filePath   目标文件（write/edit 的 file_path）
+ * @param {string} input.storePath  记忆库根目录；索引固定是它下面的 `MEMORY.md`
+ * @param {string} input.tool       `write` 或 `edit`
+ * @param {string} [input.content]  全量内容（write）
+ * @param {string} [input.oldString] 被替换的片段（edit）
+ * @param {string} [input.newString] 替换成的片段（edit）
+ * @param {number} [input.maxLines]
+ * @param {number} [input.maxBytes]
+ * @returns {{ ok: true, skipped?: string } | { ok: false, reason: string }}
+ */
+export function checkIndexWrite({
+  filePath,
+  storePath,
+  tool,
+  content,
+  oldString,
+  newString,
+  maxLines = DEFAULT_MAX_INDEX_LINES,
+  maxBytes = DEFAULT_MAX_INDEX_BYTES,
+}) {
+  const root = String(storePath ?? '').trim();
+  if (!root || !filePath) return { ok: true, skipped: 'not-configured' };
+
+  const abs = path.resolve(String(filePath));
+  const indexAbs = path.resolve(root, 'MEMORY.md');
+  // 只认「就是那个索引文件」：同一个目录、同一个名字（大小写不敏感，见文件头第 5 条）。
+  if (path.dirname(abs) !== path.dirname(indexAbs)) return { ok: true, skipped: 'outside-store' };
+  if (path.basename(abs).toLowerCase() !== path.basename(indexAbs).toLowerCase()) {
+    return { ok: true, skipped: 'not-index' };
+  }
+
+  const name = path.basename(abs);
+  const reject = (reason) => ({ ok: false, reason });
+
+  if (WHOLE_FILE_TOOLS.has(tool)) {
+    if (typeof content !== 'string') return { ok: true, skipped: 'no-content' };
+    return verdict(content, readRaw(abs), name, maxLines, maxBytes);
+  }
+
+  if (!PARTIAL_TOOLS.has(tool)) return { ok: true, skipped: 'not-a-write' };
+
+  const currentRaw = readRaw(abs);
+  if (currentRaw === undefined) return { ok: true, skipped: 'no-current' };
+  const current = currentRaw.toString('utf8');
+  const simulated = simulateEdit(current, oldString, newString);
+  if (simulated !== undefined) return verdict(simulated, currentRaw, name, maxLines, maxBytes);
+
+  // 结果还原不出来。诚实的便宜规则：索引**已经**超限时，不许再盲改它，
+  // 并且要指出出口 —— 只说「先压缩」而不说怎么压，等于把路堵死。
+  const breach = measureIndex(current, maxLines, maxBytes);
+  if (!breach) return { ok: true, skipped: 'unmeasurable' };
+  return reject(
+    `拒绝盲改索引：${name} 当前已超上限（${breach}），而这次编辑的结果无法从参数还原。` +
+      `请改用整篇重写来压缩：**缩小的重写永远放行**（哪怕仍然超限）。` +
+      `把过长的行改成「一句钩子 + 链接」、合并重复项、把冷笔记归档 —— ` +
+      `索引是目录，超限之后的部分会被静默地不再被召回。`,
+  );
+}
+
+/**
+ * 核心判据：只在「某一维最终超限、且比当前文件大」时拒绝。
+ * 照抄 dsh-engramory 的 `verdict`（其 `index.js:204-230`），逐条保留其注释里的坑。
+ */
+function verdict(text, currentRaw, name, maxLines, maxBytes) {
+  const lines = countLines(text);
+  const bytes = Buffer.byteLength(text, 'utf8');
+  // 当前尺寸取**原始 buffer**：先解码会把非 UTF-8 的坏字节膨胀成 U+FFFD，
+  // 让一次真增长看起来像缩小而放行（原文记录的真实缺陷）。
+  const curLines = currentRaw === undefined ? 0 : countLines(currentRaw.toString('utf8'));
+  const curBytes = currentRaw === undefined ? 0 : currentRaw.length;
+
+  const over = [];
+  if (lines > maxLines && lines > curLines) over.push(`${lines} 行 > ${maxLines}`);
+  if (bytes > maxBytes && bytes > curBytes) over.push(`${bytes} 字节 > ${maxBytes}`);
+  if (!over.length) return { ok: true };
+
+  return {
+    ok: false,
+    reason:
+      `拒绝写入记忆库：这次写入会把索引 ${name} 顶过上限（${over.join('，')}）。` +
+      `索引每次会话都要读、而宿主只读前面那么多，超限的部分会被静默地不再被召回。` +
+      `请先压缩再写：把细节挪进各自的笔记文件、合并重复、归档冷笔记，` +
+      `每行保持「一句短钩子 + 链接」。**缩小的重写永远放行**，可以一步一步压。`,
+  };
+}

package/index.js

@@ -22,6 +22,8 @@ import { homedir } from 'node:os';
 import path from 'node:path';
 import { buildIndex, search, clip } from './bm25.js';
 import { checkMemoryWrite } from './guard.js';
+import { checkIndexWrite, DEFAULT_MAX_INDEX_BYTES, DEFAULT_MAX_INDEX_LINES } from './index-guard.js';
+import { registerSkill, skillStatus } from './skill.js';
 import { appendAudit, readAudit, GUARD_EPOCH } from './audit.js';
 import { readDocs } from './store.js';
 import { auditStore } from './doctor.js';
@@ -120,6 +122,27 @@ const DEFAULTS = {
    * 这种绕过闸门的情况。自动执行的每一步都进写入审计，`reason` 里写明触发源。
    */
   autoArchive: false,
+  /**
+   * 索引上限闸门：`MEMORY.md` 长过这里就拒绝写入（缩小的重写永远放行）。
+   *
+   * **融合自 `dsh-engramory` v0.2.5**，逻辑逐条搬进了 `index-guard.js`。吸收它的理由：
+   * 本插件要做完整的记忆系统，不该把「索引上限」留在外部依赖里 —— 那个插件一共只做
+   * 两件事（本闸门 + 注册 `engramory` 技能），两件都收进来之后它就可以退场了。
+   *
+   * 路径不必配置：本插件知道库在哪，索引固定是 `<storePath>/MEMORY.md`。
+   * 这比让人手钉一个绝对路径更不容易错（原插件正是为此加了 `indexPath` 配置项，
+   * 因为它按 basename 匹配会误伤别的项目里同名的 `MEMORY.md`）。
+   */
+  indexMaxLines: DEFAULT_MAX_INDEX_LINES,
+  indexMaxBytes: DEFAULT_MAX_INDEX_BYTES,
+  /**
+   * 注册 `engramory` 技能（写入纪律的正文）。默认开。
+   *
+   * 同样融合自 `dsh-engramory`（正文与 description/whenToUse 逐字保留它的措辞）。
+   * 两者同时装着时会注册同名技能 —— 内容一致，谁赢都一样；注册处包了 try/catch，
+   * 万一注册表对重名是抛错而非覆盖，不会因为一个技能名把宿主拖崩。
+   */
+  registerSkill: true,
 };
 
 /** 只在用户句子里出现明确的「长期记住」意图时才追加一行提示（默认开）。 */
@@ -157,7 +180,7 @@ const textOf = (message) =>
 const isHuman = (message) => message?.role === 'user' && message?.source?.kind === 'user';
 
 /**
- * 把配置里的 `~/xxx` 展开成真实家目录。别人装这个插件时不会恰好也叫 yangfu，
+ * 把配置里的 `~/xxx` 展开成真实家目录。这步不能省：别人机器上的家目录不是配置里那个字面量，
  * 而 cordis 的 yaml 配置里 `~` 不会被自动展开——不处理的话 `storePath` 会静默无效
  * （readDocs 读不到目录、返回空数组，召回从此一条都不出，且没有任何报错）。
  */
@@ -315,20 +338,35 @@ export function apply(ctx, config = {}) {
         const filePath = args.file_path ?? args.filePath;
         if (!filePath) return undefined;
         const isWrite = toolName === 'write';
-        const verdict = checkMemoryWrite({
+        // 笔记文件规则先判；命中索引文件时它返回 skipped:'index'，此时改由索引上限闸门
+        // 接手（融合自 dsh-engramory，逻辑在 index-guard.js，文件头写明了为什么这么设计）。
+        let verdict = checkMemoryWrite({
           filePath: String(filePath),
           storePath: settings.storePath,
           content: isWrite ? args.content : undefined,
           fragment: isWrite ? undefined : args.new_string,
         });
+        if (verdict.ok && verdict.skipped === 'index') {
+          verdict = checkIndexWrite({
+            filePath: String(filePath),
+            storePath: settings.storePath,
+            tool: toolName,
+            content: isWrite ? args.content : undefined,
+            oldString: isWrite ? undefined : args.old_string,
+            newString: isWrite ? undefined : args.new_string,
+            maxLines: settings.indexMaxLines,
+            maxBytes: settings.indexMaxBytes,
+          });
+        }
         // 放行与拒绝都落审计（库外的写入上面已经 return，不进审计——那是噪音）。
         // 只记「谁动了库里的哪个文件」，内容一律不记（凭据可能就在里面）。
         const bytes = isWrite
           ? Buffer.byteLength(String(args.content ?? ''), 'utf8')
           : Buffer.byteLength(String(args.new_string ?? ''), 'utf8');
         if (verdict.ok) {
-          // 库外 / 索引 / 未配置（skipped）不记：那不是「对记忆库的写入」，记了是噪音。
-          // edit 的片段校验（partial）要记——它确实动了库里的文件。
+          // 库外 / 未配置（skipped）不记：那不是「对记忆库的写入」，记了是噪音。
+          // 索引写入**要**记：它通过索引闸门就是一次真实的库内写入。
+          // edit 的片段校验（partial）也要记——它确实动了库里的文件。
           if (!verdict.skipped) {
             storeWrites += 1; // 沉淀提醒的判据之一：本会话真的往库里写过东西
             appendAudit(settings.storePath, {
@@ -362,6 +400,16 @@ export function apply(ctx, config = {}) {
     });
   }
 
+  // ── 注册 engramory 技能（写入纪律的正文）──────────────────────────────
+  // 融合自 dsh-engramory：正文与 description/whenToUse 逐字保留它的措辞。
+  // 收进来的理由与索引闸门相同 —— 本插件要做完整的记忆系统，纪律这一层不能留在外部。
+  registerSkill(ctx, {
+    registerSkill: settings.registerSkill !== false,
+    storePath: settings.storePath,
+    maxLines: settings.indexMaxLines,
+    maxBytes: settings.indexMaxBytes,
+  });
+
   ctx.on('agent/pre-step', async (payload, next) => {
     const decision = await next();
     if (decision?.kind !== 'enter' || !Array.isArray(decision.messages)) return decision;
@@ -693,6 +741,9 @@ export function apply(ctx, config = {}) {
       writeAudit: storePath ? { epoch: GUARD_EPOCH, entries: readAudit(storePath, 40) } : { epoch: GUARD_EPOCH, entries: [] },
       // 归档计划：只出计划不动手。真正的执行在 POST /api/engramory-recall/archive。
       archive: storePath ? archivePlans(storePath) : { plans: [], skipped: [] },
+      // 技能注册的自报状态。这条链失败时**完全静默**（注入表没就绪、或同名技能已被
+      // dsh-engramory 注册而注册表选择抛错），不回报就只能在摘掉那个插件之后才发现。
+      skill: skillStatus(),
       config: {
         enabled: settings.enabled !== false,
         maxPointers: Number(settings.maxPointers) || 4,
@@ -703,6 +754,9 @@ export function apply(ctx, config = {}) {
         nudgeSediment: settings.nudgeSediment !== false,
         sedimentMinTurns: SEDIMENT_MIN_TURNS,
         autoArchive: settings.autoArchive === true,
+        indexMaxLines: Number(settings.indexMaxLines) || DEFAULT_MAX_INDEX_LINES,
+        indexMaxBytes: Number(settings.indexMaxBytes) || DEFAULT_MAX_INDEX_BYTES,
+        registerSkill: settings.registerSkill !== false,
         recencyWeight: Number(settings.recencyWeight) || 0,
         rotationPenalty: Number(settings.rotationPenalty ?? 0),
         dedupeInjection: settings.dedupeInjection !== false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-engramory-recall",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Local BM25 auto-recall, fail-closed write guard, static doctor and a memory panel for the Engramory markdown store — no network, no model, no daemon.",
   "keywords": [
     "dsh",
@@ -33,6 +33,8 @@
     "./audit": "./audit.js",
     "./package.json": "./package.json",
     "./archive": "./archive.js",
+    "./index-guard": "./index-guard.js",
+    "./skill": "./skill.js",
     "./index": "./index.js"
   },
   "files": [
@@ -44,6 +46,8 @@
     "doctor.js",
     "audit.js",
     "archive.js",
+    "index-guard.js",
+    "skill.js",
     "CHANGELOG.md",
     "cordis.patch.yml",
     "README.md"

package/skill.js

@@ -0,0 +1,200 @@
+/**
+ * skill.js —— 注册 `engramory` 技能。
+ *
+ * **融合自 `dsh-engramory` v0.2.5 的 `builtinSkillBody()`（其 `index.js:370-454`）
+ * 与它的 `ctx.inject(['skills'], …)` 注册块（`index.js:91-118`）。**
+ *
+ * 为什么连技能一起收进来：那个插件一共只做两件事 —— 索引上限闸门（已收进
+ * `index-guard.js`）和这个技能。两件都进来之后它才能退场，本插件才真的是
+ * 「完整的记忆系统」。
+ *
+ * 正文与 description/whenToUse **逐字保留**它的措辞：那些句子是被反复打磨过的
+ * （尤其是「问候不算任务」那一段的边界），改一个字都可能松动纪律。我们只在末尾
+ * 追加一节描述本插件自己新增的行为（自动召回、沉淀提醒、体检、归档）。
+ */
+
+/** 技能名。与 dsh-engramory 用同一个名字，行为一致。 */
+export const SKILL_NAME = 'engramory';
+
+/**
+ * 技能描述。逐字来自 dsh-engramory（`index.js:98-113`）——
+ * 它回答的是「什么时候该想起来有这个技能」。
+ */
+export const SKILL_DESCRIPTION =
+  'Curated file-based long-term memory: recall through MEMORY.md at the start of ' +
+  'a task, save durable user/feedback/project/reference facts, run a curation ' +
+  'checkpoint when a task finishes, and sync before compacting or opening a ' +
+  'fresh thread. A turn that starts no work — a greeting, an acknowledgement — ' +
+  'is not a task and needs none of this, but never judge that by length: a ' +
+  'one-word reply continuing work underway inherits that task.';
+
+/** 何时该用它。逐字来自 dsh-engramory（`index.js:105-113`）。 */
+export const SKILL_WHEN_TO_USE =
+  'Starting or resuming work, learning something durable worth a future session, ' +
+  'finishing a task — including one that leaves nothing worth saving, since the ' +
+  'checkpoint is still a decision to make — or approaching a ' +
+  'compact/clear/new-thread boundary. Not for a bare greeting, ' +
+  'acknowledgement, or reaction, which starts no task — but a terse reply ' +
+  'that continues work underway does, and material already in hand (a ' +
+  'pasted diff to review) does not make work a non-task. Unsure? Treat it ' +
+  'as a task.';
+
+/**
+ * 技能正文（按需拉取的那部分细节）。
+ *
+ * 「纪律」那几节（Recall / Write / 任务结束时 / Sync / 上限）是 dsh-engramory 的原文；
+ * 末尾「本插件另外做了什么」一节是我们加的，描述自动召回、沉淀提醒、体检与归档 ——
+ * 这些是同一个系统的行为，不写进技能里，模型就不知道它存在。
+ */
+export function skillBody({ storePath = '~/memory/engramory', maxLines = 200, maxBytes = 25600 } = {}) {
+  return [
+    '# Engramory — curated file-based memory',
+    '',
+    `One canonical store at \`${storePath}\`: \`MEMORY.md\` is an index of pointers, one`,
+    'line per memory; each fact lives in its own small markdown file beside it. Never',
+    'put content in the index, and never keep a second parallel store for handoffs.',
+    'The ACTIVE store is flat — the four type names are values of the `type:` field,',
+    'not subdirectories to create; `archive/` is the one reserved subdirectory, for',
+    'notes retired out of the index.',
+    '',
+    '## Recall',
+    '',
+    'A turn, a message, or a session is NOT BY ITSELF a task: a greeting, an',
+    'acknowledgement, or a reaction starts none, so it gets no recall and no',
+    'checkpoint. A task is user-directed work whose CORRECT handling could depend',
+    'on what the store holds — read-only work (analysis, diagnosis, planning,',
+    'review)',
+    'counts, and changing a file is not required. HAVING THE MATERIAL IN HAND does',
+    'not make work a non-task: a diff pasted for review is still a task. NEVER INFER',
+    'THIS FROM LENGTH: a one-word reply that picks an option or carries on work',
+    'underway inherits that task. Still unclear? Treat it as a task.',
+    '',
+    'At the start of a task, read the index and open only the notes whose hooks look',
+    'relevant. Treat what you recall as background that may be stale: re-verify any',
+    'file, flag, or version against the repo before acting on it.',
+    '',
+    '## Write',
+    '',
+    'Before writing, confirm the fact is not already in the repo, git history, or the',
+    'instruction files, and that it is not a secret value. Search the index and update',
+    'an existing note rather than adding a near-duplicate. A new note is one atomic',
+    'fact with frontmatter:',
+    '',
+    '```markdown',
+    '---',
+    'name: <kebab-case-slug>',
+    'description: <one sharp line — this is what future-you reads to decide to open it>',
+    'type: user | feedback | project | reference',
+    'scope: global | repo        # optional: does this still hold in another repo?',
+    'created: YYYY-MM-DD',
+    'updated: YYYY-MM-DD',
+    '---',
+    '```',
+    '',
+    '`feedback` and `project` notes MUST carry a `**Why:**` line and a',
+    '`**How to apply:**` line. Add exactly one pointer line to the index, and delete',
+    'memories that turn out to be wrong.',
+    '',
+    'Store settled facts, never current state: "2.0 shipped on 2026-01-15" is durable;',
+    '"the current version is X", the tip commit, or a passing test count will rot —',
+    'record where to read those instead.',
+    '',
+    'An unfinished task may keep AT MOST ONE live `project` note holding its goal,',
+    'status, decisions, constraints, blockers, and next step together — the single',
+    'exception to one-file-one-fact, and a ceiling rather than a quota: a task that',
+    'needs no resumable state keeps no note. Update it IN PLACE. Never a dated',
+    'series (`state-2026-01-15.md`, `state-2026-01-16.md`, …), never a second',
+    'handoff log indexed beside it, and retire its transient state once it ends.',
+    '',
+    '## When a task finishes',
+    '',
+    'Run one curation checkpoint. It is a judgement, not a write: promote what is',
+    'durable, retire the transient state the CURRENT task left on its own live',
+    '`project` note if it has one, and when nothing is worth keeping, write',
+    'nothing and say so. Never append a per-turn log TO THE STORE, and never touch',
+    'a file just to mark it fresh — a timestamp is not a memory.',
+    '',
+    '## Sync',
+    '',
+    'Before a deliberate compact, clear, or new thread: scan the task, dedup and update,',
+    'refresh project state, promote only reusable feedback, retire completed transient',
+    'state, then report what was added, updated, archived, and skipped.',
+    '',
+    '## The cap is enforced here',
+    '',
+    `This host denies a write that would GROW the index past ${maxLines} lines / ` +
+      `${Math.round(maxBytes / 1024)} KB. That is`,
+    'a real refusal, not a warning — but a write that shrinks the index always passes,',
+    'so compact first, step by step if needed: the index is loaded every session, and',
+    'anything past the cap silently stops being recalled.',
+    '',
+    'Never write credentials, keys, tokens, or cookies into memory — record only where',
+    'the secret lives.',
+    '',
+    '## What this plugin does on its own',
+    '',
+    'The store is indexed and searched locally (BM25 over Chinese character bigrams;',
+    'no embedding, no network). Two things happen without being asked for:',
+    '',
+    '- **Auto-recall.** On a task turn, a few notes whose hooks match the request are',
+    'injected automatically as POINTERS. They are hints, not facts — open the file',
+    'before relying on it. If nothing matches, nothing is injected.',
+    '- **A sediment nudge.** After many turns with no write to the store, one reminder',
+    'is injected suggesting a checkpoint. It is a nudge, not an instruction: if',
+    'nothing durable was settled, writing nothing is the correct response.',
+    '',
+    'A write to a memory file is gated: bad filenames, missing frontmatter, oversized',
+    'notes and anything that looks like a real credential are refused. The memory pane',
+    '(`记忆` in settings) shows recall logs, a read-only doctor and index inspection.',
+  ].join('\n');
+}
+
+/**
+ * 注册技能。
+ *
+ * 照抄 dsh-engramory 的注册方式（其 `index.js:91-118`），包括那两条注释里的坑：
+ *  - 用 `ctx.inject(['skills'], …)` 而不是在这里直接读 `ctx.skills` ——
+ *    技能注册表可能在本插件**之后**才激活，一次性探测会静默漏注册；
+ *    而且在这一层裸读未声明的服务会抛（原文记的 issue #8 崩溃）。
+ *  - 用 `inner.effect(…)` 把注册绑到子 fiber，卸载时随之释放，
+ *    否则重载会累积重复注册。
+ *
+ * 与 dsh-engramory 打交道的注意点：两者若同时装着，会注册**同名**技能。
+ * 正文与描述是逐字一致的，所以谁赢都一样；这里仍包一层 try/catch ——
+ * 万一注册表对重名是抛错而非覆盖，绝不能因为一个技能名把整个宿主拖崩。
+ */
+export function registerSkill(ctx, options = {}) {
+  if (options.registerSkill === false) return { ok: false, reason: 'disabled' };
+  try {
+    ctx.inject(['skills'], (inner) => {
+      const content = options.skill ?? skillBody(options);
+      inner.effect(() =>
+        inner.skills.register({
+          name: SKILL_NAME,
+          description: SKILL_DESCRIPTION,
+          whenToUse: SKILL_WHEN_TO_USE,
+          source: 'runtime',
+          content,
+        }),
+      );
+    });
+    // 自报状态：注册这条链是**同步失败、静默失败**的（注入表可能还没就绪、
+    // 或者同名技能已被 dsh-engramory 注册而注册表选择抛错）。不回报，
+    // 摘掉那个插件之后才发现技能根本没注册，就太晚了 —— 那正是本函数存在的唯一目的。
+    lastSkillStatus = { ok: true, reason: 'injected' };
+  } catch (err) {
+    // 技能注册表不可用照常工作：闸门与召回都不依赖它。
+    lastSkillStatus = { ok: false, reason: String(err?.message ?? err) };
+  }
+  return lastSkillStatus;
+}
+
+/**
+ * 最近一次注册尝试的结果。暴露给面板与状态接口，用来回答
+ * 「技能到底注册上了没有」—— 这条链失败时是静默的。
+ */
+let lastSkillStatus = { ok: false, reason: 'not-attempted' };
+
+export function skillStatus() {
+  return { ...lastSkillStatus, name: SKILL_NAME };
+}