dsh-engramory 0.2.6 → 0.2.8

package/README.md

@@ -4,11 +4,10 @@
 
 [![dsh-xray](https://img.shields.io/endpoint?url=https%3A%2F%2Funstone.github.io%2Fdsh-xray%2Fbadge%2Ftinqiao-oss__engramory.json)](https://unstone.github.io/dsh-xray/registry.html#tinqiao-oss__engramory)
 
-<sub>`C2` is the level `manifest.bundle.patch` puts every mountable dsh plugin at (74.6% of the scanned ecosystem); it is the only flag on this card — no `exec`, `eval`, install script, outbound domain, or environment read.</sub>
-
 Curated, file-based long-term memory for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) —
-plain markdown notes you can open with anything, one store shared across every host you
-use, and an index cap that is a **real refusal** rather than a request. (If the store
+plain markdown notes you can open with anything,
+[one writer and many readers](../../reader/README.md) across hosts, and a pre-write
+index guard for matched file tools. (If the store
 lives inside a project's git repo it must be git-ignored — memories carry machine-local
 detail; see SKILL.md §1. A *dedicated private* repo for the store itself is fine.)
 
@@ -16,20 +15,24 @@ Part of [Engramory](https://github.com/tinqiao-oss/engramory).
 
 ## Why a plugin, when an `AGENTS.md` block already works
 
-The block does carry the discipline, and for recall that is enough. Two things it cannot
-do:
-
-**The cap becomes deterministic.** Engramory keeps its index under 200 lines / 25 KB
-because the index loads every session and everything past the cap silently stops being
-recalled. On most hosts that limit is rules plus a checker the agent has to remember to
-run. dsh exposes `ctx.tools.guard()` — a synchronous, **monotonic** refusal: once a guard
-returns a reason, no later listener can turn it back into an allow. So here the limit is
-enforced, not requested. Use **0.2.6 or later**: 0.2.0 shipped before profile installs
-worked upstream and carried an `inject` declaration this Cordis does not accept — it
-installed but never activated (issue #8) — and up to 0.2.5 an edit could slip past the
-cap on a CRLF index, or on dsh 0.2 through a relative path after a cd (see Known limits). Outside Claude Code, dsh is the first host with
-the shim actually written (a few others expose equivalent pre-write seams — see
-PORTING.md — but have no shim yet).
+The block carries the discipline. Three things it cannot do:
+
+**The index is already in context — recall needs no read.** On every step the plugin
+puts the memory index into dsh's runtime context: the project store
+(`<project>/.engramory-memory/MEMORY.md`, the nearest one between the session's
+directory and its git root — the way dsh finds a project's `AGENTS.md`) and the global one
+(`$DSH_HOME/.engramory-memory/MEMORY.md`, `~/.dsh` when `$DSH_HOME` is unset) —
+where `tools/engramory_init.py dsh` puts them — or, when set, `indexPath` alone. It is
+re-read whenever it changes, so a write shows on the next request, and cut at the cap:
+lines past it are left out, and the model is told to compact. Turn it off with
+`injectIndex: false`.
+
+**The cap becomes deterministic for matched tools.** `ctx.tools.guard()` is a
+synchronous, **monotonic** refusal: once a guard returns a reason, later listeners
+cannot allow the call. This keeps the index within its configured growth limits
+without relying on the agent to run a checker. Use **`dsh-engramory >= 0.2.7`**;
+[PORTING.md](../../../PORTING.md) records which hosts have shipped guards, and
+[CHANGELOG.md](../../../CHANGELOG.md) holds release history.
 
 **The protocol arrives with the plugin.** The skill is registered at runtime through
 dsh's skill registry — via a reactive `ctx.inject(['skills'], …)` child, so a profile
@@ -39,11 +42,18 @@ roots dsh scans, a path that is easy to get subtly wrong and fails silently when
 
 ## Install
 
+Zero-dependency ESM with no build step; requires Node.js 18+ and `pnpm` on PATH
+for dsh's plugin command.
+
 ```sh
 dsh plugin --profile <name> add dsh-engramory
 ```
 
-That is the whole install. The package ships a `dsh.bundle` manifest pointing at its own
+Check `dsh.compatibility.dshReleases` in [`package.json`](package.json) for the
+exact compatible releases, backed by [`results.json`](../../../tests/dsh_e2e/results.json).
+Use the [E2E guide](../../../tests/dsh_e2e/README.md) to verify another release.
+
+The package ships a `dsh.bundle` manifest pointing at its own
 `cordis.patch.yml`, so the row is inserted into the profile's plugin tree for you — no
 hand-editing. To change a default, patch the EXISTING row by id in your profile's own
 patch layer — do **not** use a second `- insert:` (insert always appends, so you would
@@ -63,15 +73,22 @@ For the store itself and the always-on block, use the installer in the Engramory
 (`python tools/engramory_init.py dsh --install-skill`). This plugin enforces the cap and
 supplies the protocol; it does not create the store.
 
+To uninstall:
+
+```sh
+dsh plugin --profile <name> remove dsh-engramory
+```
+
 ## Configuration
 
 | Field | Default | Meaning |
 |---|---|---|
-| `indexName` | `MEMORY.md` | Basename treated as the memory index (case-insensitive; both `file_path` and `str_replace_editor`'s `path` are checked). An empty or non-string value falls back to the default. Nothing else is inspected. |
+| `indexName` | `MEMORY.md` | Basename treated as the memory index (case-insensitive; both `file_path` and `str_replace_editor`'s `path` are checked) — the name a write is called by, or the name of the file it lands on, so a symlink under another name is caught too. An empty or non-string value falls back to the default. |
 | `maxLines` | `200` | Hard line cap. Non-positive or non-finite values fall back to the default. |
 | `maxBytes` | `25600` | Hard UTF-8 byte cap (25 KB). |
-| `indexPath` | unset | Absolute path of the ONE index to guard. Without it the guard matches on basename alone, so an unrelated `MEMORY.md` in another project is gated too; set this and only that exact file is. Compared by identity (symlinks and `..` resolved; case-folded on Windows only), and a path that does not exist yet still has its first write guarded. |
+| `indexPath` | unset | Absolute path of the ONE index to guard. Without it the guard matches on basename alone, so an unrelated `MEMORY.md` in another project is gated too; set this and only that exact file is. Compared by identity — the file the write lands on, whatever it is called (symlinks and `..` resolved; case-folded on Windows only) — and a path that does not exist yet still has its first write guarded. |
 | `registerSkill` | `true` | Set `false` to keep the cap but skip the runtime skill. |
+| `injectIndex` | `true` | Put the memory index into dsh's runtime context on every step (see above). Set `false` to recall by reading the file instead. |
 | `skill` | built-in | Replace the skill body with your own markdown. |
 
 ## What the guard actually does
@@ -81,69 +98,48 @@ supplies the protocol; it does not create the store.
 | `write` (or `str_replace_editor` `create`) ending within caps | allow |
 | `write`/`create` that GROWS the index past a cap | **deny**, naming the numbers and what to compact |
 | `write`/`create` that SHRINKS or keeps an over-cap index | allow — incremental compaction (210 → 205 → 198) must stay possible |
-| Edit carrying `old_str`/`new_str`: result simulated | judged by the RESULT, same grow/shrink rule as a write |
+| Edit carrying `old_str`/`new_str`: result simulated | judged by the RESULT, same grow/shrink rule as a write — sized before it is built, so a `replace_all` whose result would be too long to build is judged on lower bounds of its bytes and lines |
 | Unsimulable partial (e.g. `insert`) on an over-cap index | **deny**, telling the agent a shrinking whole-file write passes |
 | Unsimulable partial on a healthy index | allow |
 | `read`, `view`, or any unknown tool | allow — recall must never be blocked, even over cap |
 | Any write to any other file | allow — not the guard's business |
 | Missing/unreadable current index on a whole-file write | treated as EMPTY (mirrors the Python guard) — a within-caps write passes, an over-cap first write is refused |
 | Missing/unreadable index on a partial edit | allow — a guard must never block work over a path it cannot read |
+| A FIFO, device, or directory under the index's name | never read — counts as unreadable (a read there would hang or flood the host, which runs guards on its main thread) |
+| An index past the read limit (`min(16 MiB, max(1 MiB, 4 × maxBytes))`) | not read whole: a whole-file write is judged on bytes against the filesystem's size (every shrink passes; its line count is unknown, so lines are not capped there), and an edit passes unmeasured, as on an unreadable index |
 | Malformed execution (no arguments, non-string path/content) | allow — not recognisably a write |
 
-The deny rule mirrors `hooks/engramory_index_guard.py` exactly: refuse only a result
-that is over a cap AND grew past the current file. The line count ignores a trailing
-newline, so an index sitting exactly at the cap stays writable.
+For measured results, deny only a dimension that is over its cap AND grew past
+the current file. The line count ignores a trailing newline, so an index exactly
+at the cap stays writable. This decision table is pinned by `node --test` in CI.
+
+Relative paths use the session's `workingDirectory` service when available,
+falling back to the process cwd. Edits match LF-normalised text and preserve the
+file's line endings when sizing the result, including CRLF bytes.
 
 ## Known limits
 
-- **An unsimulable partial that crosses the cap from under it is not caught.** `insert`
-  and friends do not carry the resulting text. The breach is caught by the next
-  whole-file write, or by `engramory_check.py`. What is guaranteed: an already-over
-  index cannot be grown further, and a shrinking write always passes.
-- **The tool roster follows dsh's documented tool-fs contract** (`write`/`edit` with
-  `file_path`, `str_replace_editor` with `path`) and is deliberately conservative:
-  unknown tools pass.
-- **0.2.0 never activated; 0.2.1 is the first version that runs.** While the rc.6
-  preview bug blocked all third-party profile installs upstream, the only coverage a
-  plugin could have was mocks — and 0.2.0's mock hid two activation bugs: an
-  older-Cordis `{ required, optional }` inject shape (read as waiting for services
-  literally named `required`/`optional`, pending forever) and a bare `ctx.skills` read
-  of an undeclared service (throws under Cordis' reflective context). The first field
-  install caught both the moment installs became possible (issue #8). 0.2.1 fixes them,
-  verified end to end on a live dsh 0.1.0-rc.7 web profile (0.2.0 reproduces the boot
-  failure byte for byte; 0.2.1 boots and serves) and against the vendored
-  `@deepseek-ai/cordis` resolver (activation with, without, and with a late-mounted
-  skill registry). The test mock now mirrors the reflective-context access rules, and
-  the guard's decision table stays covered by `node --test` (37 cases, run in
-  Engramory's CI).
-- **A relative path is measured where dsh writes it.** dsh 0.2 gives every session its
-  own working directory (moved by its `working_directory` tool) and resolves a
-  relative `file_path` against that. Up to 0.2.5 the guard resolved against the
-  process's cwd instead, so after a cd an edit of a bare `MEMORY.md` read no current
-  file and went through unmeasured — on dsh 0.2.1-rc.2 it grew the index to 253
-  lines. 0.2.6 reads the session's directory from dsh's `workingDirectory` service
-  when the profile has one, and falls back to the process's cwd when it does not
-  (every 0.1.x release).
-- **A CRLF index is edited the way dsh edits it.** dsh matches an edit on
-  LF-normalised text and writes the result back in the file's own line endings. Up
-  to 0.2.5 the guard matched the raw bytes, so on a CRLF `MEMORY.md` — the usual
-  shape on Windows — an LF `old_string` looked absent, the edit was predicted to
-  change nothing, and dsh applied it. 0.2.6 normalises the same way and sizes a CRLF
-  index in CRLF bytes.
-- **Checked against the dsh you are likely running, not only the one it was written
-  on.** `tests/dsh_e2e/run.py` in the Engramory repo installs a dsh release into a
-  throwaway prefix, adds this plugin with `dsh plugin add`, and drives one headless
-  task against a scripted stand-in for the DeepSeek API: a 260-line write and an edit
-  past the cap must come back refused by this guard with nothing reaching the disk, a
-  small write must land byte for byte, the skill must be advertised, every tool dsh
-  offers must already be classified (a new one could write past the cap), and removal
-  must leave a profile that still boots. The releases it passed on are listed in
-  `package.json` under `dsh.compatibility.dshReleases`; a unit test rejects a
-  `compatible` there without a recorded run of the same plugin version and code.
-- dsh is a developer preview and its plugin API can change. This plugin deliberately
-  touches only `ctx.tools.guard()` and two reactive `ctx.inject()` children — one
-  registers the skill, one reads each session's working directory — so it stays cheap
-  to fix.
+- **Unsimulable partial edits can cross the cap from below.** On a readable,
+  already-over-cap index they are denied; use a shrinking whole-file write to
+  compact. Missing/unreadable files and the read-limit exceptions are listed above.
+  Run `engramory_check.py` after index edits and `engramory_doctor.py` periodically.
+- **Coverage is limited to known file tools:** `write`/`edit` with `file_path`,
+  `str_replace`/`insert`, and mutating `str_replace_editor` commands with `path`.
+  Unknown tools pass. **Shell tools, MCP file tools, and external editors bypass
+  the guard.**
+- **Injection finds the stores where the installer puts them.** A store elsewhere
+  (`--memory-root`) needs `indexPath`. The project root is found by dsh's default `.git`
+  marker only (a profile's custom `projectRootMarkers` are not visible to a plugin), and
+  a project store created mid-session can take up to ten seconds to appear. A project
+  store whose real path leaves the project — a symlink out of the checkout — is not
+  read; point `indexPath` at it if that is deliberate. The global store's location comes
+  from `$DSH_HOME`, resolved the way dsh resolves it. What is injected is framed as notes,
+  not instructions, that may be stale; a host without runtime context
+  (no `ctx.systemPrompt.context`) goes without it.
+- dsh's plugin API can change. The plugin uses `ctx.tools.guard()` and three reactive
+  `ctx.inject()` children for the skill registry, the session working directory, and
+  the prompt registry; a compatible-release declaration needs recorded host evidence,
+  not just unit tests.
 
 ## License
 

package/README.zh-CN.md

@@ -4,28 +4,29 @@
 
 [![dsh-xray](https://img.shields.io/endpoint?url=https%3A%2F%2Funstone.github.io%2Fdsh-xray%2Fbadge%2Ftinqiao-oss__engramory.json)](https://unstone.github.io/dsh-xray/registry.html#tinqiao-oss__engramory)
 
-<sub>`C2` 是 `manifest.bundle.patch` 给每个可挂载 dsh 插件定的档位(被扫描生态里 74.6% 都在这一档);它是这张卡片上**唯一**的标记 —— 没有 `exec`、没有 `eval`、没有安装脚本、没有外连域名、不读环境变量。</sub>
-
 给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 用的**策展式、文件式**长期记忆 ——
-纯 markdown 笔记,随便什么工具都能打开;一个记忆库被你用的所有宿主共用;索引上限是一次
-**真正的拒绝**,而不是一句请求。(记忆库若位于某个项目的 git 仓库内,必须 git-ignore ——
+纯 markdown 笔记,随便什么工具都能打开;跨宿主共享遵循
+[一个写入者、多个只读者](../../reader/README.md),索引守卫会在匹配的文件工具写入前检查上限。(记忆库若位于某个项目的 git 仓库内,必须 git-ignore ——
 记忆里带着本机独有的细节,见 SKILL.md §1。给记忆库单独开一个*私有仓*则完全可以。)
 
 隶属于 [Engramory](https://github.com/tinqiao-oss/engramory)。
 
 ## 已经有 `AGENTS.md` 常驻块了,为什么还要插件
 
-那个常驻块确实承载了纪律,单论召回也够用了。但有两件事它做不到:
+那个常驻块承载了纪律。但有三件事它做不到:
+
+**索引已经在上下文里 —— 召回不用再读文件。** 插件在每一步都把记忆索引放进 dsh 的运行时
+上下文:项目库(`<项目>/.engramory-memory/MEMORY.md`,取会话目录到 git 根目录之间离会话最近的那个,和 dsh 找项目 `AGENTS.md` 的方式一致)和全局库
+(`$DSH_HOME/.engramory-memory/MEMORY.md`,未设 `$DSH_HOME` 时为 `~/.dsh`)—— 正是
+`tools/engramory_init.py dsh` 建库的位置;设了 `indexPath` 时则只注入它。内容一变就重新读取,
+所以写入后下一轮请求就能看到;超过上限的行会被截掉,并提示模型去压缩。用
+`injectIndex: false` 关闭。
 
-**上限从此是确定性的。** Engramory 把索引控制在 200 行 / 25 KB 以内,是因为索引每次会话
-都要加载,超出的部分会**悄无声息地不再被召回**。在多数宿主上,这个限制只是"规则 + 一个
-要靠 agent 自己记得去跑的校验器"。而 dsh 暴露了 `ctx.tools.guard()` —— 一个同步的、
-**单调**的否决:守卫一旦返回理由,后面任何监听器都无法把它翻回放行。所以在这里,上限是被
-**强制执行**的,不是被请求的。请用 **0.2.6 或更高版本**:0.2.0 发布时上游的 profile 安装还
-没打通,而且它的 `inject` 声明是这版 Cordis 不接受的写法 —— 装得上,但**永远激活不了**
-(issue #8);0.2.5 及以前,在 CRLF 换行的索引上、或在 dsh 0.2 上 cd 之后用相对路径,edit
-能绕过上限(见下文「已知限制」)。在 Claude Code 之外,dsh 是第一个真正把这层垫片写出来的宿主(另有几个宿主
-同样暴露了等价的写前接缝,见 PORTING.md,但还没有垫片实现)。
+**匹配工具的上限由守卫确定性执行。** `ctx.tools.guard()` 提供同步、**单调**的否决:
+守卫一旦返回理由,后续监听器就不能再放行。索引的增长受配置上限约束,无需依赖 agent
+记得运行校验器。请用 **`dsh-engramory >= 0.2.7`**;
+[PORTING.md](../../../PORTING.md) 记录各宿主是否已有守卫实现,
+[CHANGELOG.md](../../../CHANGELOG.md) 保存版本历史。
 
 **协议随插件一起到达。** skill 是在运行时通过 dsh 的 skill 注册表注册的 —— 走一个响应式的
 `ctx.inject(['skills'], …)` 子上下文,所以没有注册表的 profile 照样拿到上限,而注册表晚一步
@@ -34,11 +35,17 @@
 
 ## 安装
 
+零依赖 ESM,不需要构建;需要 Node.js 18+,dsh 的插件命令还要求 PATH 中有 `pnpm`。
+
 ```sh
 dsh plugin --profile <名字> add dsh-engramory
 ```
 
-装到这里就完了。这个包自带 `dsh.bundle` manifest 指向它自己的 `cordis.patch.yml`,所以那一行
+确切的兼容版本以 [`package.json`](package.json) 的 `dsh.compatibility.dshReleases` 为准,
+由 [`results.json`](../../../tests/dsh_e2e/results.json) 的记录支持。
+验证其他版本请看[端到端验证指南](../../../tests/dsh_e2e/README.md)。
+
+这个包自带 `dsh.bundle` manifest 指向它自己的 `cordis.patch.yml`,所以那一行
 会被自动插进 profile 的插件树里 —— 不需要手改配置。要改默认值,请在你自己 profile 的 patch
 层里**按 id 修改那一行已存在的配置**,**不要**再写一个 `- insert:`(insert 永远是追加,你会得到
 两行 engramory,而原来那行的上限依旧在生效):
@@ -57,15 +64,22 @@ dsh plugin --profile <名字> add dsh-engramory
 (`python tools/engramory_init.py dsh --install-skill`)。本插件负责强制上限、提供协议;
 **它不创建记忆库**。
 
+卸载:
+
+```sh
+dsh plugin --profile <名字> remove dsh-engramory
+```
+
 ## 配置
 
 | 字段 | 默认值 | 含义 |
 |---|---|---|
-| `indexName` | `MEMORY.md` | 被当作记忆索引的文件名(不区分大小写;`file_path` 与 `str_replace_editor` 的 `path` 都会检查)。空值或非字符串会回退到默认值。除此之外不检查任何东西。 |
+| `indexName` | `MEMORY.md` | 被当作记忆索引的文件名(不区分大小写;`file_path` 与 `str_replace_editor` 的 `path` 都会检查)—— 看写入时用的文件名,或写入实际落到的那个文件的文件名,所以换了名字的 symlink 也会被拦。空值或非字符串会回退到默认值。 |
 | `maxLines` | `200` | 硬性行数上限。非正数或非有限值回退到默认值。 |
 | `maxBytes` | `25600` | 硬性 UTF-8 字节上限(25 KB)。 |
-| `indexPath` | 未设置 | 要守护的**那一个**索引的绝对路径。不设它时,守卫只按文件名匹配,于是**别的项目里一个无关的 `MEMORY.md` 也会被拦**;设了它就只有这个确切的文件会被守。比较走的是身份而非拼写(symlink 与 `..` 都会解析;仅在 Windows 上折叠大小写),而且即使文件尚不存在,它的第一次写入照样受守护。 |
+| `indexPath` | 未设置 | 要守护的**那一个**索引的绝对路径。不设它时,守卫只按文件名匹配,于是**别的项目里一个无关的 `MEMORY.md` 也会被拦**;设了它就只有这个确切的文件会被守。比较走的是身份而非拼写 —— 看写入实际落到的那个文件,不管它叫什么名字(symlink 与 `..` 都会解析;仅在 Windows 上折叠大小写),而且即使文件尚不存在,它的第一次写入照样受守护。 |
 | `registerSkill` | `true` | 设为 `false` 则保留上限、但跳过运行时 skill。 |
+| `injectIndex` | `true` | 每一步都把记忆索引放进 dsh 的运行时上下文(见上文)。设为 `false` 则改回由 agent 读文件召回。 |
 | `skill` | 内置 | 用你自己的 markdown 替换 skill 正文。 |
 
 ## 守卫到底做了什么
@@ -75,54 +89,40 @@ dsh plugin --profile <名字> add dsh-engramory
 | `write`(或 `str_replace_editor` 的 `create`)且结果在上限内 | 放行 |
 | `write`/`create` 会让索引**增长**并越过上限 | **拒绝**,并报出具体数字和该压缩什么 |
 | `write`/`create` 让一个已超限的索引**缩小或持平** | 放行 —— 增量压缩(210 → 205 → 198)必须走得通 |
-| 带 `old_str`/`new_str` 的 edit:结果可模拟 | 按**结果**判定,增长/缩小规则与整文件写入相同 |
+| 带 `old_str`/`new_str` 的 edit:结果可模拟 | 按**结果**判定,增长/缩小规则与整文件写入相同 —— 先算大小再构建,结果长到没法构建的 `replace_all` 按字节与行数的下界判定 |
 | 无法模拟的部分写入(如 `insert`)落在已超限的索引上 | **拒绝**,并告诉 agent:缩小的整文件写入是放行的 |
 | 无法模拟的部分写入落在健康的索引上 | 放行 |
 | `read`、`view`,以及任何未知工具 | 放行 —— 哪怕已超限,召回也绝不能被挡住 |
 | 对任何其他文件的写入 | 放行 —— 不关守卫的事 |
 | 整文件写入时当前索引缺失/读不到 | 视为**空**(与 Python 版守卫一致)—— 上限内的写入放行,而首次就超限的写入被拒 |
 | 部分编辑时索引缺失/读不到 | 放行 —— 守卫绝不能因为一个自己读不了的路径而挡住工作 |
+| 用索引名字的 FIFO、设备或目录 | 一律不读,按读不到处理(在那里读会把宿主卡死或撑爆内存,而宿主在主线程上跑守卫) |
+| 超过读取上限的索引(`min(16 MiB, max(1 MiB, 4 × maxBytes))`) | 不整份读入:整文件写入按文件系统报告的大小比较字节(缩小一律放行;行数未知,这时不卡行数),edit 无法测量,按读不到的索引处理,放行 |
 | 畸形的执行(没有 arguments、路径/内容不是字符串) | 放行 —— 它压根不像一次写入 |
 
-拒绝规则与 `hooks/engramory_index_guard.py` **完全一致**:只拒绝那种结果既超过上限、
-又比当前文件更大的写入。行数统计忽略结尾换行,所以一个正好卡在上限的索引仍然可写。
+对可测量的结果,只拒绝某个维度既超出上限、又比当前文件增长的写入。行数统计忽略结尾换行,
+所以正好卡在上限的索引仍然可写。此判决表由 CI 中的 `node --test` 固定验证。
+
+相对路径优先通过会话的 `workingDirectory` 服务解析,服务不存在时退回进程 cwd。
+edit 在统一为 LF 的文本上匹配,计算结果大小时保留文件原有换行,包括 CRLF 的字节数。
 
 ## 已知限制
 
-- **从上限之下一跃越过上限的、无法模拟的部分写入,抓不住。** `insert` 这类调用并不携带
-  写入后的文本。这种越界会由下一次整文件写入、或 `engramory_check.py` 抓到。能保证的是:
-  一个**已经超限**的索引不会被继续撑大,而缩小的写入永远放行。
-- **工具名单遵循 dsh 文档化的 tool-fs 契约**(`write`/`edit` 用 `file_path`,
-  `str_replace_editor` 用 `path`),并且刻意保守:未知工具一律放行。
-- **0.2.0 从未激活成功;0.2.1 才是第一个真正跑得起来的版本。** 在 rc.6 预览版那个 bug
-  堵住上游所有第三方 profile 安装期间,插件能有的覆盖只有 mock —— 而 0.2.0 的 mock 恰好
-  掩盖了两个激活期 bug:一个是旧版 Cordis 的 `{ required, optional }` inject 写法(被解读成
-  在等待名字就叫 `required`/`optional` 的服务,于是永远 pending),另一个是裸读未声明的
-  `ctx.skills`(在 Cordis 的反射式上下文下会直接抛错)。安装一旦成为可能,**首个真实安装
-  当场把两个都暴露了**(issue #8)。0.2.1 修掉了它们,并在一个真跑着的 dsh 0.1.0-rc.7 web
-  profile 上端到端验证过(0.2.0 逐字节复现启动失败;0.2.1 能启动并提供服务),也对着 dsh
-  内置的 `@deepseek-ai/cordis` 解析器验过(注册表存在、不存在、以及晚挂载三种情况下的激活)。
-  测试用的 mock 现在会照着反射式上下文的访问规则来,守卫的判决表则由 `node --test`
-  持续覆盖(37 个用例,在 Engramory 的 CI 里跑)。
-- **相对路径按 dsh 实际写入的位置来量。** dsh 0.2 给每个会话一个自己的工作目录(由它的
-  `working_directory` 工具切换),并按这个目录解析相对的 `file_path`。0.2.5 及以前的守卫却按
-  进程的 cwd 解析,于是 cd 之后对裸 `MEMORY.md` 的 edit 读不到当前文件、不经测量就放行 ——
-  在 dsh 0.2.1-rc.2 上它把索引撑到了 253 行。0.2.6 在 profile 提供 `workingDirectory` 服务时
-  读取会话目录,没有时(所有 0.1.x 版本)退回进程 cwd。
-- **CRLF 索引按 dsh 的方式来模拟 edit。** dsh 先把文本统一成 LF 再匹配 edit,写回时恢复文件
-  原来的换行。0.2.5 及以前的守卫按原始字节匹配,于是在 CRLF 的 `MEMORY.md` 上(Windows 上很
-  常见),LF 的 `old_string` 看起来不存在,edit 被预测成"什么都不改"而放行,dsh 却照常改了。
-  0.2.6 用同样的方式归一化,并按 CRLF 字节数计算 CRLF 索引的大小。
-- **验的是你大概率正在用的 dsh,不只是写它时的那一版。** Engramory 仓库里的
-  `tests/dsh_e2e/run.py` 会把指定的 dsh 版本装进临时目录,用 `dsh plugin add` 装上本插件,
-  再对着一个脚本化的 DeepSeek API 替身跑一次 headless 任务:260 行的整文件写入、把索引撑过
-  上限的 edit,都必须被本守卫拒绝,而且磁盘上什么都没变;小写入必须逐字节落盘;skill 必须出现
-  在发给模型的技能目录里;dsh 提供的每个工具都必须已经归过类(没归类的新工具可能绕过上限写文件);卸载后
-  profile 必须还能启动。通过的版本逐个写在 `package.json` 的 `dsh.compatibility.dshReleases`
-  里;没有同一插件版本、同一份代码的通过记录,单元测试就不接受把它标成 `compatible`。
-- dsh 目前是开发者预览版,插件 API 可能变化。本插件刻意只碰 `ctx.tools.guard()` 和两个
-  响应式 `ctx.inject()` 子上下文 —— 一个注册 skill,一个读取各会话的工作目录 —— 所以要跟着改
-  也很便宜。
+- **无法模拟的部分编辑可能从上限之下直接越界。** 若索引可读且已经超限,则拒绝这种编辑;
+  可以用缩小的整文件写入来压缩。文件缺失、不可读和超过读取上限的例外见上表。
+  编辑索引后运行 `engramory_check.py`,定期运行 `engramory_doctor.py`。
+- **只覆盖已知文件工具:**使用 `file_path` 的 `write`/`edit`、`str_replace`/`insert`,
+  以及使用 `path` 的 `str_replace_editor` 修改命令。未知工具放行。
+  **Shell 工具、MCP 文件工具和外部编辑器都绕过守卫。**
+- **注入只在安装器建库的位置找记忆库。** 库放在别处(`--memory-root`)时要设 `indexPath`。
+  项目根只按 dsh 默认的 `.git` 标记判断(profile 里自定义的 `projectRootMarkers` 插件看不到);
+  会话中途新建的项目库最多要十秒才会出现。真实路径跑出项目之外的项目库(比如指向仓库外的符号
+  链接)不会被读取;如果是有意为之,请把 `indexPath` 指向它。全局库的位置来自 `$DSH_HOME`,
+  解析方式与 dsh 自己一致。注入的内容被标注为"笔记而非指令、可能过时";没有运行时上下文
+  (`ctx.systemPrompt.context`)的宿主则不注入。
+- dsh 的插件 API 可能变化。本插件使用 `ctx.tools.guard()` 和三个响应式 `ctx.inject()`
+  子上下文,分别接入 skill 注册表、会话工作目录和提示词注册表;兼容声明需要真实宿主的
+  运行记录,不能只凭单元测试。
 
 ## 许可