@yottameta/yotta-memory 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,8 +1,36 @@
+## v0.13.0 (2026-09-13)
+
+**P0-4.6 元忆 after_milestone 试点**：
+
+- 新增 `skill-manifest.json`，声明 `after_milestone` / `remember_commit` / `fallback: explicit-unverified`。
+- 里程碑记忆必须有真实 `file_path` 证据才允许标记 verified；缺证据或写入失败时输出 `explicit-unverified` + 一次纠偏。
+- 元阁适配器回归覆盖成功与降级两条路径。
+
+## v0.12.2 (2026-09-12)
+
+**可靠性收口：开工 doctor + 破坏性操作前事务快照**
+
+- 修正 `init --force` 的过期拒绝文案：明确已有记忆库的强制重建必须由完整备份与显式确认保护，当前版本不提供覆盖初始化路径。
+- 新增 `yotta-memory doctor [--json]`：只读检查记忆库根目录、加密库密钥文件、公共索引、`agents.json` 与最近备份；严重异常返回非零退出码，并锁定破坏性写入。
+- 新增 MCP `doctor` 工具；`context` 的开工可靠性提醒改为直接使用 doctor 结果，critical 时明确提示“破坏性写入已锁定”。
+- `maintain --apply`（含 `--dedup --apply`）、`consolidate --apply`、`merge`、`archive` 与 `--purge` 在写入前自动创建新的整库事务快照；未配置独立备份目录、doctor critical 或快照失败时拒绝写入，原记忆保持不变。
+- `--allow-same-volume` 仍只用于 `backup create` 的显式临时备份，不会绕过破坏性写入门；不存在 CLI 级跳过快照开关。
+- 每次事务快照写入 `.archive/audit-<日期>.jsonl`（transaction / operation / snapshot 记录）；`forget` 继续只进 `.trash/`，不重复做整库快照。
+- 新增 `test/reliability-doctor.test.js` 与 `test/reliability-destructive-guard.test.js`；既有 consolidate / maintain 回归补齐临时快照目录。
+
+## v0.12.1 (2026-09-12)
+
+安装与更新文档修复（无功能变更）：
+
+- 明确区分两个 bin：`yotta-memory` 是引擎 CLI，`yotta-memory-install` 是技能安装器；`npx -y @yottameta/yotta-memory` 只临时运行引擎，不安装技能。
+- README 中英版、USER_GUIDE、SKILL、FAQ 补全安装 / 更新命令：更新技能统一使用 `npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <name>`（或 `--dir <技能目录>`）；全局安装后可运行 `yotta-memory-install`。
+- 修正 `bin/install.js` 头部注释中的错误示例，并新增 `test/docs-install-update.test.js` 防止两个 bin 的文档再次漂移。
+
 ## v0.12.0 (2026-09-12)
 
 **可靠性基线（误删事故整改）**：
 
-- `init` 对已有记忆库默认拒绝覆盖；新增 `--attach` 接入现有库；`--force` 在未完成备份前明确拒绝，防止初始化再次清空记忆。
+- `init` 对已有记忆库默认拒绝覆盖；新增 `--attach` 接入现有库；`--force` 也不能覆盖已有记忆库，防止初始化再次清空记忆。
 - `forget` 不再物理删除，改为移动到 `.trash/<timestamp>/<原相对路径>`，并写 `audit-<date>.jsonl` 审计记录。
 - 新增 `backup create / list / doctor / restore <id> --to <目录>`：备份 `facts/`、`private/`、`keys/`（排除 `keys/cache/` 授权缓存）、`agents.json`、`index.json`、`.archive/`，生成 SHA-256 清单；默认拒绝同卷备份；`restore` 默认只恢复到新目录，不覆盖正在使用的记忆库。
 - 新增每日自动备份闭环：`backup volumes` 只枚举当前机器实际存在、可写、与记忆库异卷的路径；用户确认一次位置后 `backup setup` 默认启用每日备份（默认 03:30），Windows Task Scheduler / Linux systemd user timer（cron 降级）/ macOS LaunchAgent 负责无人值守，`serve` 启动与每 6 小时用幂等 `backup ensure-daily` 补跑。

package/README.md

@@ -23,6 +23,10 @@
 
 > 📖 The user-facing operations manual lives in [USER_GUIDE.md](USER_GUIDE.md).
 
+> 🆕 **v0.12.2**: reliability closure — `yotta-memory doctor` checks the store, key material, index, identity registry and latest backup; `maintain --apply`, `consolidate --apply`, `merge`, `archive` and `--purge` create a transaction snapshot before writing and refuse to proceed if the snapshot fails.
+
+> 🆕 **v0.12.1**: installation and update docs now distinguish the engine CLI (`yotta-memory`) from the skill installer (`yotta-memory-install`), with copy-ready upgrade commands.
+
 > 🆕 **v0.12.0**: reliability baseline — `init` refuses to overwrite an existing store (`--attach` to attach); `forget` moves entries into `.trash/`; `backup create / list / doctor / restore` provides independent-volume backups with SHA-256 manifests.
 
 > 🆕 **v0.10.0**: compression & forgetting — `consolidate` turns old low-use memories on the same topic into one **provenance-carrying periodic summary** that stays searchable (originals archived; `consolidate --undo <batch>` restores everything); near-duplicate **auto-merge with confidence** (`maintain --dedup --apply`); **per-type decay curves** (FACT slow / PREF medium / COMMIT task-like fast / BOUND never decays); batch audit via `consolidate --batches`.
@@ -41,7 +45,8 @@ Most memory solutions treat "remembering" as a black box: data goes into a datab
 - **Grows smarter (v0.6.0)** — `profile` aggregates a user profile (the engine infers nothing; it only groups verbatim text) + `context` generates a one-shot start-of-work package (identity + profile + recent memory + boundaries + commitments); the SKILL "memory discipline" injects rule layers (type red lines / trigger signals / know the user / bottom lines / host isolation) — rules and mechanisms only, no personality data; zero data out of the box.
 - **Self-learning / self-evolving / self-improving (v0.8.0)** — `recall` semantic search (synonyms / pinyin full + initials / field weighting / fuzzy match, zero-dependency) with utility-score blended ranking; `feedback` explicit usage feedback loop (useful / useless adjusts weight / confidence / feedback_net); `maintain` rule-layer self-organization (unified utility score + age-based auto-archive / forget candidates / dedup, dry-run by default, immutable / BOUND exempt); `distill` psychological-log distillation (statistical summary / topic profile / knowledge map, optional `--model` external model enhancement).
 - **Compression & forgetting (v0.10.0) — memory that never bloats** — `consolidate` summarizes old, low-use memories on the same topic into one **provenance-carrying periodic summary** that stays in active memory (every original file is listed as provenance; originals move to `.archive/`; `--undo <batch>` restores everything); `maintain --dedup` scores near-duplicates and `--apply` auto-merges high-confidence groups; the utility recency component now decays **per type** (FACT slow / PREF medium / COMMIT task-like fast / BOUND never) so durable facts are not wiped by time and stale commitments step aside quickly; every batch is auditable via `consolidate --batches`.
-- **Reliability baseline (v0.12.0)** — `init` refuses to overwrite an existing store and `--attach` attaches instead; `forget` moves entries to `.trash/` with an audit record; `backup create / list / doctor / restore` backs up the store to an independent volume with a SHA-256 manifest and restores only to a new directory.
+- **Reliability baseline (v0.12.0 / v0.12.2)** — `init` refuses to overwrite an existing store and `--attach` attaches instead; `forget` moves entries to `.trash/` with an audit record; `backup create / list / doctor / restore` backs up the store to an independent volume with a SHA-256 manifest and restores only to a new directory; `yotta-memory doctor` checks the store, key material, index, identity registry and latest backup, and destructive writes take a transaction snapshot first.
+- **Milestone hook declaration** — `skill-manifest.json` declares `after_milestone` / `remember_commit`; a milestone memory write is verified only with a real file-path record.
 - **Private-zone encryption (v0.7.0)** — private files AES-256-GCM envelope encrypted (passphrase-derived master key + recovery key + per-owner encrypted index); `yotta-memory view` user review platform (unlock with passphrase to see all AI memory).
 
 ### Memory types
@@ -176,6 +181,13 @@ bash install.sh --dir <path>     # install to the given directory
 bash install.sh --list           # list agents -> default directories
 ```
 
+### Two commands, two jobs
+
+This package exposes two separate commands:
+
+- `yotta-memory` — the engine CLI that reads and writes the memory store. `npx -y @yottameta/yotta-memory` temporarily runs only this CLI; it does **not** install the skill.
+- `yotta-memory-install` — the skill installer. Install or update the skill with `npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <agent-name>` (or `--dir <skills-dir>`).
+
 > Method 1 uses the npm registry (npmmirror / npmjs) and does not depend on GitHub; Methods 2/3 use GitHub and may fail without a proxy in China.
 ## Example outputs
 
@@ -222,7 +234,17 @@ Two upgrade paths match the two install paths:
 npm i -g @yottameta/yotta-memory
 ```
 
-**Upgrade the skill**: rerun your install command from the `## Install` section (e.g. `npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <name>` or `bash install.sh --agent <name>`) to overwrite the old skill folder.
+**Upgrade the skill**: rerun the command that matches the way you installed it:
+
+```text
+npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <agent-name>
+npx -y --package @yottameta/yotta-memory yotta-memory-install --dir <skills-dir>
+bash install.sh --agent <agent-name>
+```
+
+If you installed the CLI globally, `npm i -g @yottameta/yotta-memory` updates both the engine and the `yotta-memory-install` command; then run `yotta-memory-install --agent <agent-name>` to refresh the skill.
+
+After updating, verify `yotta-memory --version` and the installed `yotta-memory/SKILL.md` frontmatter `version:`.
 
 **v0.10.0 upgrade notes** — upgrading touches no data: no migration, no reindex, no re-init needed. v0.10.0 does not change the memory file format, the `facts/` / `private/<owner>/<type>/` layout, or the index version, so existing stores open as-is.
 
@@ -248,6 +270,7 @@ Optional post-upgrade self-check: `yotta-memory config get` (confirm `memory_hom
 | `yotta-memory profile [--owner <id>]` | Generate a user profile (aggregates `private/<owner>` verbatim, zero inference, writes `profile.md`; cross-owner denied by default) |
 | `yotta-memory context [--limit N] [--owner <id>] [--budget N] [--focus <text>] [--explain] [--embedding <cmd>]` | Generate the start-of-work package (identity + multi-agent rules + profile + task-focused memory + recent memory + boundaries + commitments; --budget caps chars, --focus adds task relevance, --explain shows included/dropped) |
 | `yotta-memory forget <file>` | Delete a memory (by type-dir path or file name) |
+| `yotta-memory doctor [--json]` | Start-of-work reliability check (store / key material / index / identity / latest backup; critical issues lock destructive writes) |
 | `yotta-memory archive [--days 180] [--threshold 0.4]` | Archive old memory (decay-blended utility + age; immutable / BOUND exempt; private to `.archive/private/<owner>/<type>/`) |
 | `yotta-memory reindex` | Rebuild the index (after manually editing .md) |
 | `yotta-memory export [--out f.json]` / `import <f.json>` | Export / import |
@@ -329,7 +352,7 @@ Register the connection in the agent's MCP config (`url` + two headers):
 }
 ```
 
-Once connected, MCP tools (remember / recall / search / context / forget / archive / reindex / export / import / agent_info) read/write memory and confirm identity; management actions (init / config / token / lan / serve) are not exposed via MCP, and token management is never exposed remotely. MCP `export` / `import` paths are restricted inside the memory root, MCP `distill` does not support `--model`, and MCP never accepts a raw embedding command from remote callers — the local embedding plugin must be configured on the engine host with `config set embedding_cmd`. `X-Agent-Id` must match the token's registered agent; read-partition rules are the same as the CLI (FACT public-readable, PREF / BOUND / COMMIT private).
+Once connected, MCP tools (remember / recall / search / context / doctor / forget / archive / reindex / export / import / agent_info) read/write memory and confirm identity; management actions (init / config / token / lan / serve) are not exposed via MCP, and token management is never exposed remotely. MCP `export` / `import` paths are restricted inside the memory root, MCP `distill` does not support `--model`, and MCP never accepts a raw embedding command from remote callers — the local embedding plugin must be configured on the engine host with `config set embedding_cmd`. `X-Agent-Id` must match the token's registered agent; read-partition rules are the same as the CLI (FACT public-readable, PREF / BOUND / COMMIT private).
 
 ### Location persistence
 

package/README.zh-CN.md

@@ -23,6 +23,10 @@
 
 > 📖 面向用户的操作手册见 [USER_GUIDE.md](USER_GUIDE.md)。
 
+> 🆕 **v0.12.2**：可靠性收口——新增 `yotta-memory doctor` 开工检查；`maintain --apply`、`consolidate --apply`、`merge`、`archive` 与 `--purge` 在写入前自动创建事务快照，快照失败或严重异常时拒绝写入。
+
+> 🆕 **v0.12.1**：安装与更新文档明确区分引擎 CLI（`yotta-memory`）和技能安装器（`yotta-memory-install`），并补齐可直接复制的升级命令。
+
 > 🆕 **v0.12.0**：可靠性基线——`init` 对已有记忆库默认拒绝覆盖（用 `--attach` 接入）；`forget` 先移入 `.trash/` 并留审计；`backup create / list / doctor / restore` 支持独立盘备份、SHA-256 清单校验和只恢复到新目录。
 
 > 🆕 **v0.10.0**：压缩遗忘——`consolidate` 周期摘要压缩（同主题旧记忆 → 带溯源摘要 + 原文归档，`--undo <batch>` 一键回滚）；近重复自动合并（`maintain --dedup` 置信度分档，`--apply` 批量执行）；分类型衰减（FACT 慢 / PREF 中 / COMMIT 任务类快 / BOUND 不衰减）；`consolidate --batches` 批次审计可查。
@@ -45,7 +49,7 @@
 - **越用越懂（v0.6.0）**：`profile` 聚合用户画像（引擎零推断，只归组原文）+ `context` 一键生成开工上下文包（身份 + 画像 + 近期记忆 + 边界 + 承诺）；SKILL「记忆守则」注入规则层（类型红线 / 触发信号 / 了解用户 / 底线 / 宿主隔离），只注入规则与机制、不注入人格数据，出厂零数据。
 - **自我学习 / 自我进化 / 自我提升（v0.8.0）**：`recall` 语义检索（同义词 / 拼音全拼+首字母 / 字段加权 / 模糊匹配，零依赖）+ 效用分融合排序；`feedback` 显式使用反馈闭环（useful / useless 调整 weight / confidence / feedback_net，越用越懂）；`maintain` 规则层自组织（统一效用分 + 年龄自动归档 / 遗忘候选 / 去重，默认 dry-run，immutable / BOUND 豁免）；`distill` 心理日志蒸馏（统计摘要 / 主题画像 / 知识地图，可选 `--model` 外部模型增强）。
 - **压缩遗忘（v0.10.0）——记忆越用越精简**：`consolidate` 周期摘要压缩——把超龄 + 长期闲置 + 低效用的同主题旧记忆归纳成 **1 条带溯源的摘要**（每条原文路径都写在正文里）留在活跃区，原文整体进 `.archive/`，`--undo <batch>` 一键回滚；`maintain --dedup` 给近重复打分（≥0.85 高置信自动合并 / 0.65–0.85 建议手动），`--apply` 批量合并同归属重复组；时效分量改**分类型衰减**（FACT 慢 / PREF 中 / COMMIT 任务类快 / BOUND 永不衰减）——持久事实不被时间抹掉，过期承诺快速让位；每一步写批次审计（`--batches` 可查）。
-- **可靠性基线（v0.12.0）**：`init` 遇到已有记忆库默认拒绝覆盖（`--attach` 用于接入）；`forget` 先移入 `.trash/` 并写删除审计；`backup create / list / doctor / restore` 支持独立盘备份、SHA-256 清单校验、恢复默认只写新目录，避免二次覆盖。
+- **可靠性基线（v0.12.0 / v0.12.2）**：`init` 遇到已有记忆库默认拒绝覆盖（`--attach` 用于接入）；`forget` 先移入 `.trash/` 并写删除审计；`backup create / list / doctor / restore` 支持独立盘备份、SHA-256 清单校验、恢复默认只写新目录；`yotta-memory doctor` 检查根目录 / 密钥库 / 索引 / 身份 / 最近备份，破坏性操作在写入前自动创建事务快照。
 - **私密区加密（v0.7.0）**：私密区文件 AES-256-GCM 信封加密（口令派生主密钥 + 恢复钥匙 + 每 owner 加密索引）；`yotta-memory view` 用户查看平台（口令解锁看全部 AI 记忆）；`migrate` 明文→密文迁移；`--no-encrypt` 可降级。跨 AI 私密从「纪律层隔离」升级为「机制层不可解」。
 - **便携记忆盘**：记忆库本身就是记忆引擎——装在硬盘或主机上随盘走，局域网内其它主机上的智能体可远程读写；本地零进程与局域网常驻两种模式可并存，插上硬盘即恢复全部记忆。
 
@@ -216,6 +220,13 @@ bash install.sh --dir <path>     # 装到指定目录
 bash install.sh --list           # 列出智能体 -> 默认目录
 ```
 
+### 两个命令，各管一件事
+
+这个包提供两个不同的命令：
+
+- `yotta-memory`：读写记忆库的引擎 CLI。`npx -y @yottameta/yotta-memory` 只是临时运行这个 CLI，**不会**安装技能。
+- `yotta-memory-install`：技能安装器。安装或更新技能必须使用 `npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <智能体名称>`（或 `--dir <智能体技能目录>`）。
+
 > 方式一走 npm 源（npmmirror / npmjs），不依赖 GitHub；方式二 / 三走 GitHub，国内无代理可能失败。
 ## 命令输出样例
 
@@ -262,7 +273,17 @@ bash install.sh --list           # 列出智能体 -> 默认目录
 npm i -g @yottameta/yotta-memory
 ```
 
-**升级技能**：重跑「安装」节中的命令（如 `npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <name>` 或 `bash install.sh --agent <name>`），覆盖旧版技能文件夹。
+**升级技能**：按你当初的安装方式重跑对应命令，覆盖旧版技能文件夹：
+
+```text
+npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <智能体名称>
+npx -y --package @yottameta/yotta-memory yotta-memory-install --dir <智能体技能目录>
+bash install.sh --agent <智能体名称>
+```
+
+如果你全局安装了 CLI，`npm i -g @yottameta/yotta-memory` 会同时升级引擎和 `yotta-memory-install` 命令；之后运行 `yotta-memory-install --agent <智能体名称>` 即可刷新技能。
+
+升级后请核对 `yotta-memory --version` 和已安装的 `yotta-memory/SKILL.md` frontmatter 中的 `version:`。
 
 **v0.10.0 升级提示**——升级不碰数据：无需迁移 / reindex / 重新 init。v0.10.0 没有改记忆文件格式、`facts/` 与 `private/<owner>/<type>/` 布局，也没有改索引版本，旧库打开即用。
 
@@ -290,6 +311,7 @@ npm i -g @yottameta/yotta-memory
 | `yotta-memory profile [--owner <id>]` | 生成用户画像（聚合 `private/<owner>/` 原文，零推断，写 `profile.md`；跨 owner 默认拒绝）|
 | `yotta-memory context [--limit N] [--owner <id>] [--budget N] [--focus <关键词>] [--explain] [--embedding <命令>]` | 生成开工上下文包（身份 + 多智能体铁律 + 画像 + 任务相关记忆 + 近期记忆 + 边界 + 承诺；--budget 字符预算；--focus 任务聚焦；--explain 输出 included/dropped 选择解释）|
 | `yotta-memory forget <文件>` | 删除一条记忆（按类型目录路径或文件名）|
+| `yotta-memory doctor [--json]` | 开工可靠性检查（根目录 / 密钥库 / 索引 / 身份 / 最近备份；严重异常时锁定破坏性写入）|
 | `yotta-memory archive [--days 180] [--threshold 0.4]` | 归档旧记忆（分类型衰减效用分 + 年龄；immutable / BOUND 豁免；私密入 `.archive/private/<owner>/<type>/`）|
 | `yotta-memory reindex` | 重建索引（手动改 .md 后校正）|
 | `yotta-memory export [--out f.json]` / `import <f.json>` | 导出 / 导入 |
@@ -371,7 +393,7 @@ yotta-memory recall --type FACT --limit 10
 }
 ```
 
-连接后可通过 MCP tools（remember / recall / search / context / forget / archive / reindex / export / import / agent_info）读写记忆与确认身份；管理动作（init / config / token / lan / serve）不进 MCP，token 管理不远程暴露；MCP export/import 路径限记忆库内、distill 不支持 `--model`，MCP 也不接受远端传入 embedding 命令——embedding 插件只能由引擎主机本地 `config set embedding_cmd` 配置。`X-Agent-Id` 必须与 token 登记的智能体一致；读取分区规则与 CLI 相同（FACT 公共可读，PREF / BOUND / COMMIT 私密隔离）。
+连接后可通过 MCP tools（remember / recall / search / context / doctor / forget / archive / reindex / export / import / agent_info）读写记忆与确认身份；管理动作（init / config / token / lan / serve）不进 MCP，token 管理不远程暴露；MCP export/import 路径限记忆库内、distill 不支持 `--model`，MCP 也不接受远端传入 embedding 命令——embedding 插件只能由引擎主机本地 `config set embedding_cmd` 配置。`X-Agent-Id` 必须与 token 登记的智能体一致；读取分区规则与 CLI 相同（FACT 公共可读，PREF / BOUND / COMMIT 私密隔离）。
 
 ### 位置持久化
 

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: yotta-memory
-description: 元忆 —— 有权限边界的文件式智能体记忆。文件式、零依赖、可 diff/可回滚：让任何 AI 智能体活过会话，开工 recall 恢复上下文、重要信息 remember 落盘、收工归档。类型体系 FACT（公共共享）/ PREF / BOUND / COMMIT（私密隔离）。触发：记住、别忘了、记一笔、记忆、remember、recall、跨会话、上次说到、续测、交接、归档、记忆盘、共享记忆、局域网记忆、画像、开工上下文、记忆守则、profile、context、越用越懂、语义检索、反馈、维护、蒸馏、feedback、maintain、distill、explain、自我学习、自我进化、自我提升、查看平台分页、recall 候选预过滤、任务相关记忆、--focus、--embedding、压缩遗忘、consolidate、周期摘要、自动合并、分类型衰减、回滚、备份、backup、防误删
-version: 0.12.0
+description: 元忆 —— 有权限边界的文件式智能体记忆。文件式、零依赖、可 diff/可回滚：让任何 AI 智能体活过会话，开工 recall 恢复上下文、重要信息 remember 落盘、收工归档。类型体系 FACT（公共共享）/ PREF / BOUND / COMMIT（私密隔离）。触发：记住、别忘了、记一笔、记忆、remember、recall、跨会话、上次说到、续测、交接、归档、记忆盘、共享记忆、局域网记忆、画像、开工上下文、记忆守则、profile、context、越用越懂、语义检索、反馈、维护、蒸馏、feedback、maintain、distill、explain、自我学习、自我进化、自我提升、查看平台分页、recall 候选预过滤、任务相关记忆、--focus、--embedding、压缩遗忘、consolidate、周期摘要、自动合并、分类型衰减、回滚、备份、backup、防误删、doctor、事务快照
+version: 0.13.0
 license: MIT
 ---
 
@@ -20,6 +20,15 @@ license: MIT
 - **召回质量与上下文选择（v0.9.0）**：`recall` 支持可选本地 embedding 插件（`--embedding <command>` / `config set embedding_cmd <command>`）；`context --focus <关键词>` 生成任务感知上下文；`--explain` 输出选择 trace，无插件时自动降级为词法检索。
 - **压缩遗忘（v0.10.0）**：记忆库长期可用不膨胀——`consolidate` 周期摘要压缩（把超龄 + 低效用 + 长期闲置的同主题旧记忆归纳成**带溯源**的摘要，原文整体进 `.archive/`，`--undo` 一键回滚）；`maintain --dedup` 近重复**自动合并**（置信度分档，`--apply` 批量执行高置信组）；效用分时效改为**分类型衰减**（FACT 慢 / PREF 中 / COMMIT 任务类快 / BOUND 不衰减）；`consolidate --batches` 批次审计可查。
 - **可靠性基线（v0.12.0）**：`init` 对非空记忆库默认拒绝覆盖（`--attach` 接入现有库）；`forget` 先移入 `.trash/` 并写审计；新增 `backup volumes / setup / status / ensure-daily / schedule / drill`（用户确认真实独立卷后默认每日自动备份）与 `backup create / list / doctor / restore`。
+- **可靠性收口（v0.12.2）**：新增 `yotta-memory doctor` 开工检查（根目录 / 密钥库 / 索引 / 身份 / 最近备份）；`maintain --apply`、`consolidate --apply`、`merge`、`archive`、`--purge` 在写入前自动创建事务快照，快照失败或严重检查异常时拒绝写入。
+- **运行时 hook 声明（v0.13.0）**：manifest 声明 `after_milestone` / `remember_commit`；里程碑记忆必须有真实文件路径证据才标 verified，缺证据时输出 `explicit-unverified` + 一次纠偏。
+
+## 安装 / 更新（两个 bin）
+
+- `yotta-memory`：引擎 CLI，负责读写记忆库。`npx -y @yottameta/yotta-memory` 只是临时运行引擎，不会安装技能。
+- `yotta-memory-install`：技能安装器。安装或更新技能使用 `npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <name>`（或 `--dir <技能目录>`）。
+
+AI 更新流程：先运行 `yotta-memory --version` 记录当前引擎版本；升级 CLI 用 `npm i -g @yottameta/yotta-memory`；升级技能用 `npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <name>`（或原安装时使用的 `--dir` / `install.sh`）；完成后回读 `yotta-memory --version` 与已安装 `SKILL.md` 的 `version:`，两者不一致时不得声称更新成功。
 
 ## 何时使用（触发）
 
@@ -35,7 +44,7 @@ license: MIT
 3. **收工归档**：写会话小结（COMMIT / 笔记）；旧记录定期 `yotta-memory maintain --apply`（单条低效用归档）+ 记忆多了周期 `yotta-memory consolidate --apply`（同主题压缩成带溯源摘要，`--undo` 可回滚）。
 4. **多智能体纪律**：FACT 写入公共区，PREF / BOUND / COMMIT 只写本智能体私密区；不读取其他智能体私密区。**一切读写一律走 `yotta-memory` CLI / MCP 工具**——禁止用 shell（`Get-ChildItem` / `Get-Content` / `cat` / `ls` / `type` 等）直接读或改记忆库目录下的 `.md` / `index.json` / `tokens.json` / `agents.json` / `grants.json` 等文件，否则会绕过权限边界、读到别的智能体私密内容。
 
-## 可靠性基线（v0.12.0）
+## 可靠性基线（v0.12.0 / v0.12.2）
 
 **目的**：防止初始化覆盖、删除不可逆、备份缺失再次造成记忆库丢失。
 
@@ -43,7 +52,7 @@ license: MIT
 
 - 目标已是记忆库时，`yotta-memory init` 默认拒绝覆盖。
 - 接入已有库：`yotta-memory init --attach`。
-- `--force` 在完整备份机制通过前明确拒绝；不得绕过。
+- `--force` 不能覆盖已有记忆库；强制重建需要完整备份与显式确认保护，当前版本不提供覆盖初始化路径。
 - 非 owner 智能体不得初始化、重建或清空记忆库。
 
 ### 2. forget 回收区
@@ -104,6 +113,23 @@ yotta-memory backup drill [<备份ID>]
 - 恢复目标非空时拒绝覆盖；恢复后先校验，再决定是否替换正式记忆库。
 - 备份是可靠性基线的一部分；没有备份时，不得执行永久删除或覆盖初始化。
 
+### 5. 开工 doctor 与事务快照
+
+```bash
+# 开工检查：只读，不修改记忆库
+yotta-memory doctor
+
+# 机器可读输出
+yotta-memory doctor --json
+```
+
+- `doctor` 检查记忆库根目录、加密库密钥文件、公共索引、`agents.json` 与最近备份。
+- 严重异常（根目录缺失、密钥库缺文件、备份目录同卷）会返回非零退出码，并锁定破坏性写入。
+- `maintain --apply`、`consolidate --apply`、`merge`、`archive` 与 `--purge` 在执行前自动创建事务快照；未配置独立备份目录或快照失败时拒绝写入，原记忆保持不变。
+- 不提供 CLI 跳过快照的开关；`--allow-same-volume` 只用于 `backup create` 的显式临时备份，不会绕过破坏性写入门。
+- `context` 会展示 doctor 的 warning / critical；critical 时明确提示“破坏性写入已锁定”。
+- `forget` 仍只移入 `.trash/`，不重复创建整库快照。
+
 
 ## 记忆守则（Memory Doctrine，v0.6.0）
 
@@ -238,6 +264,7 @@ yotta-memory backup drill [<备份ID>]
 | `yotta-memory forget <文件>` | 移入 `.trash/<时间>/` 回收区并写审计（v0.12.0；不再物理删除）|
 | `yotta-memory backup volumes / setup --dir <目录> / status / ensure-daily / schedule enable|disable|status` | 每日自动备份（v0.12.0；只展示实际枚举的异卷、用户确认一次位置后默认每日执行，Windows Task Scheduler / systemd timer / launchd 调度，`serve` 补跑）|
 | `yotta-memory backup create / list / doctor / restore <ID> --to <目录> / drill [<ID>]` | 备份、恢复与恢复演练（v0.12.0；独立盘校验、SHA-256 清单、排除 `keys/cache`、恢复默认只写新目录；drill 验证 manifest / 索引 / 测试私密解密）|
+| `yotta-memory doctor [--json]` | 开工可靠性检查（v0.12.2；根目录 / 密钥库 / 索引 / 身份 / 最近备份；严重异常时锁定破坏性写入）|
 | `yotta-memory archive [--days 180] [--threshold 0.35]` | 归档旧记忆（v0.8.0 统一效用分 + v0.10.0 分类型衰减；immutable / BOUND 豁免；私密归档入 `.archive/private/<owner>/<type>/`；阈值默认读 config `maintain_archived_utility`）|
 | `yotta-memory reindex` | 重建索引（手动改 .md 后校正）|
 | `yotta-memory export [--out f.json]` / `import <f.json>` | 导出 / 导入 |

package/USER_GUIDE.md

@@ -11,6 +11,7 @@
 3.6 自我学习 / 自我进化 / 自我提升（v0.8.0）
 3.7 查看平台分页与检索优化（v0.8.1）
 3.8 可靠性基线：防覆盖、回收区与备份（v0.12.0）
+3.9 开工 doctor 与事务快照（v0.12.2）
 4. 便携记忆盘 · 记忆引擎主机篇（Linux / Windows）
 5. 智能体接入篇（本机 / 局域网其它主机）
 6. CLI 命令速查
@@ -32,7 +33,7 @@
 - **便携记忆盘**：记忆装在固定主机上，本机与局域网其它主机共享同一份记忆（见第 4 / 5 篇）。
 - **越用越懂（v0.6.0）**：AI 按「记忆守则」主动捕获信号，`profile` 聚合画像、`context` 开工注入——用得越久越懂你。
 - **自我学习 / 自我进化 / 自我提升（v0.8.0 + v0.9.0）**：`recall` 语义检索（同义词 / 拼音 / 字段加权 / 模糊，v0.9.0 可选本地 embedding 插件）+ `feedback` 使用反馈闭环 + `maintain` 规则层自组织 + `distill` 心理日志蒸馏——记忆系统会自己整理、提炼、演化。
-- **可靠性基线（v0.12.0）**：`init` 对已有库拒绝覆盖；`forget` 进回收区；`backup volumes/setup/status/ensure-daily/schedule/drill` 在用户确认真实独立卷后默认每日自动备份，并提供校验、恢复与恢复演练。
+- **可靠性基线（v0.12.0 / v0.12.2）**：`init` 对已有库拒绝覆盖；`forget` 进回收区；`backup volumes/setup/status/ensure-daily/schedule/drill` 在用户确认真实独立卷后默认每日自动备份，并提供校验、恢复与恢复演练；`doctor` 开工检查风险，破坏性操作写入前自动创建事务快照。
 
 ## 2. 安装（CLI + 技能）
 
@@ -58,7 +59,13 @@
 
 > CLI 与技能分工不同：CLI 让命令行能读写记忆；技能让 AI 知道「开工 recall 恢复上下文、重要信息 remember 落盘、收工归档」。只装 CLI 不装技能，AI 不会自动使用这套工作流。
 
-**更新：** `npm i -g @yottameta/yotta-memory` 升级 CLI（不带版本号即最新版），再把技能文件夹重新装进智能体（重复执行上面的技能安装命令即可）。
+**更新：**
+
+- 升级 CLI：`npm i -g @yottameta/yotta-memory`（不带版本号即最新版）。
+- 升级技能：`npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <name>`；如果你用 `--dir` 安装，把同一个目录再传一次。
+- 全局安装时：`npm i -g @yottameta/yotta-memory` 会同时升级引擎和安装器，之后可运行 `yotta-memory-install --agent <name>`。
+
+> `npx -y @yottameta/yotta-memory` 只是临时运行引擎 CLI，不会安装技能；技能安装器必须使用上面的 `--package ... yotta-memory-install` 形式，或全局安装后的 `yotta-memory-install` 命令。
 
 **卸载：** `npm rm -g @yottameta/yotta-memory`，并从智能体的 skills 目录删除整个 `yotta-memory` 文件夹。
 
@@ -222,6 +229,13 @@ statement: 本周完成发布
 - `yotta-memory backup status` 查看目录、计划、上次成功、最近失败与调度状态；`backup drill` 恢复到隔离副本，校验 manifest / 索引并解密一条测试私密。
 - 备份目录与记忆库同卷时默认拒绝；这是一条防线，不替代独立盘备份。
 
+## 3.9 开工 doctor 与事务快照（v0.12.2）
+
+- `yotta-memory doctor`：只读检查记忆库根目录、加密库密钥文件、公共索引、`agents.json` 与最近备份；加 `--json` 可输出机器可读结果。
+- 严重异常（根目录缺失、密钥库缺文件、备份目录同卷）会返回非零退出码；此时 `context` 也会显示“破坏性写入已锁定”。
+- `maintain --apply`、`consolidate --apply`、`merge`、`archive` 与 `--purge` 在写入前自动创建新的整库事务快照，并在 `.archive/audit-<日期>.jsonl` 记录 transaction / operation / snapshot。
+- 未配置独立备份目录、doctor critical 或快照失败时，命令直接拒绝执行，原记忆保持不变；`forget` 仍只移入 `.trash/`，不重复创建整库快照。
+
 ## 4. 便携记忆盘 · 记忆引擎主机篇
 
 场景：记忆放在一台主机上（Linux / Windows 均可），本机直接 CLI 读写；局域网内其它主机上的 AI 智能体经 MCP 远程接入。引擎主机只需装 CLI，不需要装任何 AI 智能体。
@@ -359,6 +373,7 @@ yotta-memory remember FACT 主题 内容    # 智能体落盘
 | `yotta-memory profile [--owner <id>]` | 生成用户画像（零推断，写 `profile.md`）|
 | `yotta-memory context [--limit N] [--owner <id>] [--budget N] [--focus <关键词>] [--explain] [--embedding <命令>]` | 开工上下文包（身份+铁律+画像+任务相关记忆+近期记忆+边界+承诺；--focus 任务聚焦；--explain 输出 included/dropped 选择解释）|
 | `yotta-memory forget <文件>` | 删除一条记忆 |
+| `yotta-memory doctor [--json]` | 开工可靠性检查（v0.12.2：根目录 / 密钥库 / 索引 / 身份 / 最近备份；严重异常时锁定破坏性写入）|
 | `yotta-memory archive [--days 180] [--threshold 0.4]` | 归档旧记忆（分类型衰减效用分 + 年龄；immutable / BOUND 豁免；私密入 `.archive/private/<owner>/<type>/`）|
 | `yotta-memory reindex` | 重建索引 |
 | `yotta-memory export [--out 文件.json]` / `import <文件.json>` | 导出 / 导入 |

package/bin/install.js

@@ -2,11 +2,11 @@
 /**
  * yotta-memory 跨平台安装器
  * 用法:
- *   npx -y @yottameta/yotta-memory --agent <name>  # 按智能体默认用户级目录安装（推荐）
- *   npx -y @yottameta/yotta-memory --dir PATH      # 装到指定目录（用户改了目录的智能体）
- *   npx -y @yottameta/yotta-memory -g              # 安装到全部已知智能体用户级目录
- *   npx -y @yottameta/yotta-memory                 # 安装到检测到的项目级目录
- *   npx -y @yottameta/yotta-memory --list          # 列出智能体 -> 默认目录
+ *   npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <name>  # 按智能体默认用户级目录安装（推荐）
+ *   npx -y --package @yottameta/yotta-memory yotta-memory-install --dir PATH      # 装到指定目录（用户改了目录的智能体）
+ *   npx -y --package @yottameta/yotta-memory yotta-memory-install -g              # 安装到全部已知智能体用户级目录
+ *   npx -y --package @yottameta/yotta-memory yotta-memory-install                 # 安装到检测到的项目级目录
+ *   npx -y --package @yottameta/yotta-memory yotta-memory-install --list          # 列出智能体 -> 默认目录
  */
 'use strict';
 const fs = require('fs');

package/bin/yotta-memory.js

@@ -13,6 +13,7 @@
 // v0.7.0 新增：私密区机制级加密（AES-256-GCM 信封加密 + PBKDF2 主密钥 + 恢复钥匙）/ 每 owner 加密索引 / 用户查看平台 yotta-memory view / migrate 迁移 / reset-password / key 授权 / context 收工纪律 / init 新建默认加密（--no-encrypt 降级）
 // v0.8.0 新增：自我学习/自我进化/自我提升——语义检索（同义词/拼音/字段加权/模糊 + 可选 embedding 插件协议预留）/ feedback 显式反馈闭环（weight/confidence/feedback_net 演化）/ maintain 规则层自组织（统一效用分 utility + 归档/遗忘/去重，默认 dry-run）/ distill 心理日志蒸馏（启发式统计/主题画像/知识地图 + 可选 --model）
 // v0.6.2 修复：remember --verify 写后回读改为直查索引 + 权限判定 + 召回匹配性（不再依赖 recall top-N 排序，消除泛化 subject 下偶发误报「回读未命中」）
+// v0.12.2 新增：开工 doctor（根目录/密钥库/索引/身份/最近备份）+ 破坏性操作前事务快照门（maintain/consolidate/merge/archive/purge）
 'use strict';
 
 const fs = require('fs');
@@ -22,7 +23,7 @@ const crypto = require('crypto');
 const http = require('http');
 const child_process = require('child_process');
 
-const VERSION = '0.12.0';
+const VERSION = '0.13.0';
 // MCP 协议（2026-07-28 无状态 + 2025-11-25 legacy 握手，dual-era）
 const MCP_PROTOCOL_MODERN = '2026-07-28';
 const MCP_PROTOCOL_LEGACY = '2025-11-25';
@@ -1123,7 +1124,7 @@ function initCore(opts) {
     return { error: false, text: '已接入现有记忆库: ' + root };
   }
   if (existing && opts.force) {
-    return { error: true, text: '拒绝: --force 重新初始化必须先做完整备份；当前版本尚未实现 backup，不能覆盖现有记忆库。请保留现场并先完成备份机制。' };
+    return { error: true, text: '拒绝: --force 不能覆盖现有记忆库；已有记忆库的强制重建必须由完整备份与显式确认保护，当前版本不提供覆盖初始化路径。如只是接入，请使用 init --attach。' };
   }
   if (existing) {
     return { error: true, text: '拒绝: 目标已是现有记忆库: ' + root + '。如只是接入，请使用 init --attach；不要执行覆盖初始化。' };
@@ -1615,7 +1616,8 @@ function backupStatusCore(opts) {
   opts = opts || {};
   const root = path.resolve(opts.root || userRoot());
   const cfg = loadConfig();
-  const dir = cfg.backup_dir ? path.resolve(String(cfg.backup_dir)) : '';
+  const configuredDir = opts.dir || opts.backupDir || cfg.backup_dir;
+  const dir = configuredDir ? path.resolve(String(configuredDir)) : '';
   const maxAge = Number(cfg.backup_max_age_hours) || 36;
   if (!dir) {
     const manual = cfg.backup_setup_choice === 'manual';
@@ -1656,6 +1658,7 @@ function backupStatusCore(opts) {
     configured: true,
     enabled: !!cfg.backup_enabled,
     healthy: healthy,
+    independent: independent,
     latest: latest,
     ageHours: ageHours,
     text: lines.join('\n'),
@@ -1776,14 +1779,15 @@ function backupEnsureDailyCore(opts) {
 function backupHealthCore(opts) {
   opts = opts || {};
   const cfg = loadConfig();
-  if (!cfg.backup_dir && cfg.backup_setup_choice !== 'manual') {
+  const configuredDir = opts.dir || opts.backupDir || cfg.backup_dir;
+  if (!configuredDir && cfg.backup_setup_choice !== 'manual') {
     return {
       level: 'warning',
       needsSetup: true,
       text: '尚未配置独立盘备份。AI 应先运行 yotta-memory backup volumes，只展示当前实际存在的可写异卷；由用户确认目录后，再运行 backup setup 启用每日自动备份。',
     };
   }
-  if (cfg.backup_setup_choice === 'manual') return { level: 'none', needsSetup: false, text: '' };
+  if (!configuredDir && cfg.backup_setup_choice === 'manual') return { level: 'none', needsSetup: false, text: '' };
   const status = backupStatusCore(opts);
   const maxAge = Number(cfg.backup_max_age_hours) || 36;
   if (cfg.backup_last_error) return { level: 'warning', needsSetup: false, text: '最近一次备份失败: ' + cfg.backup_last_error };
@@ -1794,6 +1798,190 @@ function backupHealthCore(opts) {
   }
   return { level: 'none', needsSetup: false, text: '' };
 }
+// 开工可靠性检查：只读检查根目录、密钥库、索引、身份登记与最近备份。
+function doctorCore(opts) {
+  opts = opts || {};
+  const root = path.resolve(opts.root || userRoot());
+  const cfg = loadConfig();
+  const checks = {};
+  const warnings = [];
+  const critical = [];
+  const exists = isExistingStore(root);
+  checks.root = { ok: exists, path: root };
+  if (!exists) critical.push('记忆库不存在或基本结构缺失: ' + root);
+
+  const encrypted = isEncrypted(root);
+  checks.encrypted = { enabled: encrypted };
+  if (encrypted) {
+    const saltOk = fs.existsSync(encSaltPath(root));
+    const recoveryOk = fs.existsSync(encRecoveryEncPath(root));
+    checks.keys = { salt: saltOk, recovery: recoveryOk };
+    if (!saltOk) critical.push('密钥库异常: 缺少 keys/salt');
+    if (!recoveryOk) critical.push('密钥库异常: 缺少 keys/recovery.key.enc（恢复钥匙文件）');
+  } else if (exists && hasPlaintextPrivate(root)) {
+    checks.keys = { mode: 'plaintext' };
+    warnings.push('当前私密区为明文；建议运行 yotta-memory migrate 启用加密。');
+  } else {
+    checks.keys = { mode: 'plaintext' };
+  }
+
+  const idxFile = indexPath(root);
+  if (!fs.existsSync(idxFile)) {
+    checks.index = { exists: false, valid: false };
+    warnings.push('公共索引缺失；可运行 yotta-memory reindex 重建。');
+  } else if (!loadIndex(root)) {
+    checks.index = { exists: true, valid: false };
+    warnings.push('公共索引无法解析或版本过旧；可运行 yotta-memory reindex 重建。');
+  } else {
+    checks.index = { exists: true, valid: true };
+  }
+
+  if (!fs.existsSync(agentsPath(root))) {
+    checks.agents = { exists: false, valid: false };
+    warnings.push('agents.json 缺失；智能体身份登记不可用。');
+  } else {
+    try {
+      JSON.parse(fs.readFileSync(agentsPath(root), 'utf8'));
+      checks.agents = { exists: true, valid: true };
+    } catch (error) {
+      checks.agents = { exists: true, valid: false };
+      warnings.push('agents.json 无法解析；请先恢复身份登记。');
+    }
+  }
+
+  const configuredDir = opts.dir || opts.backupDir || cfg.backup_dir;
+  if (!configuredDir) {
+    if (cfg.backup_setup_choice === 'manual') {
+      checks.backup = { configured: false, manual: true, independent: false };
+    } else {
+      const health = backupHealthCore({ root: root, now: opts.now, sameVolumeFn: opts.sameVolumeFn });
+      checks.backup = { configured: false, manual: false, independent: false };
+      if (health.text) warnings.push(health.text);
+    }
+  } else {
+    const status = backupStatusCore({
+      root: root,
+      dir: configuredDir,
+      now: opts.now,
+      sameVolumeFn: opts.sameVolumeFn,
+    });
+    checks.backup = {
+      configured: true,
+      manual: false,
+      independent: !!status.independent,
+      latest: status.latest ? status.latest.id : '',
+      ageHours: status.ageHours,
+      healthy: !!status.healthy,
+    };
+    if (!status.independent) {
+      critical.push('备份目录与记忆库在同一卷，不能作为可靠备份。');
+    }
+    if (!status.latest) {
+      warnings.push('备份目录已配置，但还没有成功备份；请运行 yotta-memory backup create 或 backup ensure-daily。');
+    } else {
+      const maxAge = Number(cfg.backup_max_age_hours) || 36;
+      if (status.ageHours !== null && status.ageHours > maxAge) {
+        warnings.push('最近备份已过期（' + status.ageHours.toFixed(1) + ' 小时，超过 ' + maxAge + ' 小时）；请检查备份盘与每日调度。');
+      }
+    }
+    if (cfg.backup_last_error) warnings.push('最近一次备份失败: ' + cfg.backup_last_error);
+    if (cfg.backup_scheduler_error) warnings.push('每日备份调度异常: ' + cfg.backup_scheduler_error);
+  }
+
+  const level = critical.length ? 'critical' : (warnings.length ? 'warning' : 'ok');
+  const lines = [
+    '# yotta-memory doctor（开工可靠性检查）',
+    '',
+    '- 结果: ' + (level === 'critical' ? '严重' : (level === 'warning' ? '警告' : '正常')),
+    '- 记忆库: ' + root,
+    '- 加密: ' + (encrypted ? '是' : '否'),
+    '- 备份目录: ' + (configuredDir || (cfg.backup_setup_choice === 'manual' ? '手动模式' : '(未配置)')),
+  ];
+  for (const message of critical) lines.push('- [严重] ' + message);
+  for (const message of warnings) lines.push('- [警告] ' + message);
+  if (!critical.length && !warnings.length) lines.push('- 检查项: 全部通过');
+  if (level === 'critical') {
+    lines.push('');
+    lines.push('- 破坏性写入已锁定：先运行 yotta-memory doctor 修复严重问题。');
+  }
+  return {
+    error: false,
+    ok: critical.length === 0,
+    level: level,
+    critical: critical,
+    warnings: warnings,
+    checks: checks,
+    root: root,
+    text: lines.join('\n'),
+  };
+}
+// 破坏性写入前的统一快照门：先 doctor，再创建新的整库快照，最后写事务审计。
+function destructiveGuardCore(opts) {
+  opts = opts || {};
+  const root = path.resolve(opts.root || userRoot());
+  // snapshotDir / allowSameVolumeForTest 仅用于 core 测试注入；CLI 的 --allow-same-volume 不进入破坏性写入门。
+  const snapshotDir = opts.snapshotDir || opts.backupDir || loadConfig().backup_dir || '';
+  const sameVolumeFn = opts.sameVolumeFn || (opts.allowSameVolumeForTest ? function () { return false; } : undefined);
+  const report = doctorCore({
+    root: root,
+    backupDir: snapshotDir || undefined,
+    now: opts.now,
+    sameVolumeFn: sameVolumeFn,
+  });
+  if (!report.ok) {
+    return {
+      error: true,
+      doctor: report,
+      text: '拒绝: 开工可靠性检查未通过，破坏性操作已锁定。\n' + report.text,
+    };
+  }
+  if (!snapshotDir) {
+    return {
+      error: true,
+      doctor: report,
+      text: '拒绝: 未配置独立备份目录，不能执行破坏性操作。请先运行 backup volumes，由用户确认位置后执行 backup setup。',
+    };
+  }
+  const snapshot = backupCreateCore({
+    root: root,
+    dir: snapshotDir,
+    now: opts.now,
+    allowSameVolume: !!opts.allowSameVolumeForTest,
+    sameVolumeFn: sameVolumeFn,
+  });
+  if (snapshot.error) {
+    return {
+      error: true,
+      doctor: report,
+      text: '拒绝: 事务快照失败，原记忆未改动。\n' + snapshot.text,
+    };
+  }
+  const transaction = 'txn-' + Date.now() + '-' + crypto.randomBytes(3).toString('hex');
+  const auditOk = appendAudit(root, 'audit', {
+    action: 'transaction_start',
+    ts: new Date().toISOString(),
+    transaction: transaction,
+    operation: opts.action || 'destructive',
+    root: root,
+    snapshot: snapshot.id,
+    snapshotPath: snapshot.path,
+  });
+  if (!auditOk) {
+    return {
+      error: true,
+      doctor: report,
+      snapshot: snapshot,
+      text: '拒绝: 事务审计写入失败，原记忆未改动。快照已保留: ' + snapshot.id,
+    };
+  }
+  return {
+    error: false,
+    doctor: report,
+    snapshot: snapshot,
+    transaction: transaction,
+    text: '事务快照: ' + snapshot.id,
+  };
+}
 function sha256File(file) {
   return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
 }
@@ -1830,7 +2018,8 @@ function backupCreateCore(opts) {
   if (!isExistingStore(root)) return { error: true, text: '记忆库不存在或未初始化: ' + root };
   const destBase = backupDestination(opts);
   if (!destBase) return { error: true, text: '未配置备份目录。请用 --dir <目录>、YOTTA_MEMORY_BACKUP_DIR 或 config set backup_dir <目录>。' };
-  if (!opts.allowSameVolume && sameVolume(root, destBase)) {
+  const same = opts.sameVolumeFn ? !!opts.sameVolumeFn(root, destBase) : sameVolume(root, destBase);
+  if (!opts.allowSameVolume && same) {
     return { error: true, text: '拒绝: 备份目录与记忆库在同一卷。请把备份放到独立盘或独立卷。' };
   }
   const createdAt = new Date(opts.now || Date.now()).toISOString();
@@ -2391,6 +2580,16 @@ function archiveCore(opts) {
   const threshold = (opts.threshold !== undefined && opts.threshold !== null) ? opts.threshold : (parseFloat(cfg.maintain_archived_utility || 0.35));
   const root = userRoot();
   if (!fs.existsSync(root)) return { error: false, text: '记忆库不存在。' };
+  const guard = destructiveGuardCore({
+    root: root,
+    action: 'archive',
+    snapshotDir: opts.snapshotDir,
+    backupDir: opts.backupDir,
+    allowSameVolumeForTest: opts.allowSameVolumeForTest,
+    sameVolumeFn: opts.sameVolumeFn,
+    now: opts.now,
+  });
+  if (guard.error) return { error: true, text: guard.text };
   const cutoff = Date.now() - days * 24 * 60 * 60 * 1000;
   let moved = 0;
   const movedFiles = [];
@@ -2415,7 +2614,7 @@ function archiveCore(opts) {
     }
   }
   if (movedFiles.length) removeIndexEntries(root, movedFiles);
-  return { error: false, text: '已归档 ' + moved + ' 条旧记忆到 ' + path.join(root, ARCHIVE_DIR) };
+  return { error: false, text: '已归档 ' + moved + ' 条旧记忆到 ' + path.join(root, ARCHIVE_DIR) + '\n事务快照: ' + guard.snapshot.id };
 }
 
 // ---- v0.8.0 自我学习/自我进化/自我提升：feedback / explain / maintain / distill ----
@@ -2426,7 +2625,8 @@ function appendAudit(root, kind, rec) {
   try {
     fs.mkdirSync(path.join(root, ARCHIVE_DIR), { recursive: true });
     fs.appendFileSync(auditPath(root, kind), JSON.stringify(rec) + '\n', 'utf8');
-  } catch (e) { /* 审计失败不阻断主流程 */ }
+    return true;
+  } catch (e) { return false; }
 }
 function resolveMemoryTarget(ref) {
   const roots = memoryRoots();
@@ -2561,6 +2761,19 @@ function maintainCore(opts) {
   const purge = !!opts.purge;
   const root = userRoot();
   if (!fs.existsSync(root)) return { error: false, text: '记忆库不存在。' };
+  let guard = null;
+  if (apply) {
+    guard = destructiveGuardCore({
+      root: root,
+      action: opts.dedup ? 'maintain --dedup --apply' : (purge ? 'maintain --apply --purge' : 'maintain --apply'),
+      snapshotDir: opts.snapshotDir,
+      backupDir: opts.backupDir,
+      allowSameVolumeForTest: opts.allowSameVolumeForTest,
+      sameVolumeFn: opts.sameVolumeFn,
+      now: opts.now,
+    });
+    if (guard.error) return { error: true, text: guard.text };
+  }
   const cfg = loadConfig();
   const archU = parseFloat(opts.threshold !== undefined && opts.threshold !== null ? opts.threshold : (cfg.maintain_archived_utility || 0.35));
   const archAge = parseInt(opts.age || cfg.maintain_archived_age || '180', 10) || 180;
@@ -2570,6 +2783,7 @@ function maintainCore(opts) {
   const lines = ['## yotta-memory maintain（记忆自组织）'];
   lines.push('- 模式: ' + mode);
   lines.push('- 归档阈值: utility < ' + archU + ' 且年龄 > ' + archAge + ' 天；遗忘阈值: utility < ' + forgetU + ' 且年龄 > ' + forgetAge + ' 天');
+  if (guard) lines.push('- 事务快照: ' + guard.snapshot.id);
   lines.push('');
   const toArchive = [], toForget = [], skipped = [];
   for (const fp of collectEntryFiles(root)) {
@@ -2660,6 +2874,16 @@ function mergeCore(refA, refB, opts) {
   }
   if (ta.root !== tb.root) return { error: true, text: '暂不支持跨记忆库合并（' + ta.root + ' vs ' + tb.root + '）。' };
   const root = ta.root;
+  const guard = destructiveGuardCore({
+    root: root,
+    action: 'merge',
+    snapshotDir: opts.snapshotDir,
+    backupDir: opts.backupDir,
+    allowSameVolumeForTest: opts.allowSameVolumeForTest,
+    sameVolumeFn: opts.sameVolumeFn,
+    now: opts.now,
+  });
+  if (guard.error) return { error: true, text: guard.text };
   const ea = readEntry(ta.fp, root);
   const eb = readEntry(tb.fp, root);
   const keep = ea.confidence >= eb.confidence ? ea : eb;
@@ -2677,7 +2901,7 @@ function mergeCore(refA, refB, opts) {
   fs.renameSync(dropFp, dest);
   removeIndexEntry(root, drop.file);
   appendAudit(root, 'audit', { ts: new Date().toISOString(), file: drop.file, action: 'merge', reason: '并入 ' + keep.file, utility: round3(utilityScore(keep)) });
-  return { error: false, text: '已合并: ' + drop.file + ' -> ' + keep.file + '\n  保留: [' + keep.type + '] ' + keep.subject + ': ' + keep.statement + '\n  归档低 confidence: ' + drop.file };
+  return { error: false, text: '已合并: ' + drop.file + ' -> ' + keep.file + '\n  保留: [' + keep.type + '] ' + keep.subject + ': ' + keep.statement + '\n  归档低 confidence: ' + drop.file + '\n  事务快照: ' + guard.snapshot.id };
 }
 // 心理日志蒸馏：统计摘要 / 主题画像 / 知识地图（启发式默认，可选 --model）
 function distillCore(opts) {
@@ -3291,6 +3515,12 @@ function cmdBackupDrill(id, opts) {
   console.log(r.text);
   if (r.error) process.exit(2);
 }
+function cmdDoctor(opts) {
+  const r = doctorCore(opts);
+  if (opts.json) console.log(JSON.stringify(r, null, 2));
+  else console.log(r.text);
+  if (!r.ok) process.exit(2);
+}
 function cmdReindex() {
   const roots = memoryRoots();
   if (!roots.length) { console.log('记忆库不存在。'); return; }
@@ -3812,12 +4042,14 @@ function contextCore(opts) {
     if (!trace.length) lines.push('（无选择记录）');
     for (const t of trace) lines.push(t);
   }
-  const backupHealth = backupHealthCore({ root: root });
-  if (backupHealth.level === 'warning') {
+  const reliability = doctorCore({ root: root });
+  if (reliability.level !== 'ok') {
     lines.push('');
     lines.push('## 可靠性提醒');
     lines.push('');
-    lines.push('- ' + backupHealth.text);
+    for (const message of reliability.critical) lines.push('- [严重] ' + message);
+    for (const message of reliability.warnings) lines.push('- [警告] ' + message);
+    if (!reliability.ok) lines.push('- 破坏性写入已锁定：先运行 yotta-memory doctor 修复严重问题。');
   }
   return { error: false, exitCode: 0, text: lines.join('\n') };
 }
@@ -3874,6 +4106,7 @@ function mcpTools() {
     { name: 'recall', description: '检索记忆。query 可选；type 可选；limit 可选（默认 20）；explain 可选。只返回当前智能体可读记忆；embedding 插件只能由本机 config 配置，远端不可传命令', inputSchema: { type: 'object', properties: { query: { type: 'string' }, type: { type: 'string' }, limit: { type: 'number' }, embeddingTimeout: { type: 'number' }, explain: { type: 'boolean' } } } },
     { name: 'search', description: '检索记忆（同 recall）。query 可选；type 可选；limit 可选（默认 20）；explain 可选；embedding 插件只能由本机 config 配置，远端不可传命令', inputSchema: { type: 'object', properties: { query: { type: 'string' }, type: { type: 'string' }, limit: { type: 'number' }, embeddingTimeout: { type: 'number' }, explain: { type: 'boolean' } } } },
     { name: 'context', description: '生成开工上下文包。focus 可选；limit 可选；budget 可选；explain 可选；embedding 插件只能由本机 config 配置，远端不可传命令', inputSchema: { type: 'object', properties: { focus: { type: 'string' }, limit: { type: 'number' }, budget: { type: 'number' }, explain: { type: 'boolean' }, embeddingTimeout: { type: 'number' } } } },
+    { name: 'doctor', description: '开工可靠性检查：检查记忆库根目录、密钥库、索引、身份登记与最近备份；只读，不会修改记忆', inputSchema: { type: 'object', properties: {} } },
     { name: 'forget', description: '删除一条记忆。file 为记忆文件路径（如 facts/2026-08-24-0001.md 或文件名）', inputSchema: { type: 'object', properties: { file: { type: 'string' } }, required: ['file'] } },
     { name: 'archive', description: '归档旧记忆。days 默认 180；threshold 默认 0.4', inputSchema: { type: 'object', properties: { days: { type: 'number' }, threshold: { type: 'number' } } } },
     { name: 'reindex', description: '重建索引（手动改 .md 后校正；扫描 facts/prefs/bounds/commits 四目录）', inputSchema: { type: 'object', properties: {} } },
@@ -3917,6 +4150,10 @@ function callTool(name, args, ctx) {
       });
       return { text: r.text, error: r.error };
     }
+    if (name === 'doctor') {
+      const r = doctorCore({ selfAgent: agent });
+      return { text: r.text, error: !r.ok };
+    }
     if (name === 'forget') {
       const r = forgetCore(String(args.file || ''), { selfAgent: agent });
       return { text: r.text, error: r.error };
@@ -4931,9 +5168,20 @@ function consolidateCore(opts) {
     lines.push('dry-run 未执行任何变更。确认后加 --apply 执行（写入批次审计，可 consolidate --undo <batch> 回滚）。');
     return { error: false, text: lines.join('\n') };
   }
+  const guard = destructiveGuardCore({
+    root: root,
+    action: 'consolidate --apply',
+    snapshotDir: opts.snapshotDir,
+    backupDir: opts.backupDir,
+    allowSameVolumeForTest: opts.allowSameVolumeForTest,
+    sameVolumeFn: opts.sameVolumeFn,
+    now: opts.now,
+  });
+  if (guard.error) return { error: true, text: guard.text };
   const batch = newBatchId();
   appendAudit(root, 'audit', { action: 'manifest', ts: new Date().toISOString(), batch: batch, command: 'consolidate', mode: 'apply', root: root, active_before: collectEntryFiles(root).length, undone: false });
   lines.push('');
+  lines.push('- 事务快照: ' + guard.snapshot.id);
   lines.push('- 批次: ' + batch + '（审计 .archive/audit-<日期>.jsonl；回滚: yotta-memory consolidate --undo ' + batch + '）');
   let made = 0, moved = 0;
   for (const g of groups) {
@@ -5094,6 +5342,7 @@ function usage() {
       ['forget', '删除一条记忆'],
       ['archive', '归档（--days/--threshold 盖棺分+年龄）'],
       ['backup', '备份记忆库（volumes / setup / status / ensure-daily / schedule / create / list / doctor / restore <id> --to <目录> / drill）'],
+      ['doctor', '开工可靠性检查（根目录/密钥库/索引/身份/最近备份；严重异常时锁定破坏性写入）'],
       ['maintain', '记忆自组织（归档/遗忘候选/去重/合并；默认 dry-run；--dedup 查重+置信度，--dedup --apply 自动合并高置信组）'],
       ['consolidate', '周期摘要压缩（默认 dry-run；--apply 执行；--undo <batch> 回滚；--batches 查批次；候选=超龄+闲置+低效用，immutable/BOUND 豁免）'],
       ['distill', '心理日志蒸馏（统计摘要/主题画像/知识地图；--model 可选外部模型）'],
@@ -5257,6 +5506,7 @@ async function main() {
       break;
     }
     case 'reindex': cmdReindex(); break;
+    case 'doctor': cmdDoctor(opts); break;
     case 'profile': cmdProfile(opts); break;
     case 'context': cmdContext(opts); break;
     case 'export': cmdExport(opts.out); break;
@@ -5431,6 +5681,8 @@ module.exports = {
   backupStatusCore: backupStatusCore,
   backupEnsureDailyCore: backupEnsureDailyCore,
   backupHealthCore: backupHealthCore,
+  doctorCore: doctorCore,
+  destructiveGuardCore: destructiveGuardCore,
   backupWindowsTaskXml: backupWindowsTaskXml,
   backupSystemdServiceContent: backupSystemdServiceContent,
   backupSystemdTimerContent: backupSystemdTimerContent,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@yottameta/yotta-memory",
-  "version": "0.12.0",
-  "description": "Yuanyi (元忆) — boundary-aware, file-based memory for AI agents. File-based, zero-dependency, diff/rollback-able; FACT/PREF/BOUND/COMMIT types (public shared / private isolated), user-level + project-level storage; v0.12 reliability baseline (init guard, trash-based deletion, independent-volume backup/list/doctor/restore), v0.10 consolidation (periodic summaries with provenance, near-duplicate auto-merge, per-type decay, batch audit + rollback), v0.9 recall quality + context focus + optional local embedding plugin, plus v0.8 semantic search, feedback loop, self-organization and distillation.",
+  "version": "0.13.0",
+  "description": "Yuanyi (元忆) — boundary-aware, file-based memory for AI agents. File-based, zero-dependency, diff/rollback-able; FACT/PREF/BOUND/COMMIT types (public shared / private isolated), user-level + project-level storage; v0.12 reliability baseline (init guard, trash-based deletion, independent-volume backup/list/doctor/restore, start-of-work doctor, transactional snapshots before destructive writes), v0.10 consolidation (periodic summaries with provenance, near-duplicate auto-merge, per-type decay, batch audit + rollback), v0.9 recall quality + context focus + optional local embedding plugin, plus v0.8 semantic search, feedback loop, self-organization and distillation.",
   "license": "MIT",
   "keywords": [
     "agent-skills",
@@ -13,6 +13,7 @@
   ],
   "files": [
     "SKILL.md",
+    "skill-manifest.json",
     "LICENSE",
     "README.md",
     "USER_GUIDE.md",

package/references/faq.md

@@ -30,13 +30,13 @@
 开工运行 `yotta-memory context`（身份 + 画像 + 近期记忆 + 边界 + 承诺），需要细节再 `recall <关键词>`。
 
 ## 10. 备份与迁移？
-优先使用 `backup create --dir <独立盘目录>` 创建整库备份；`backup list` 查看，`backup doctor` 校验 SHA-256，`backup restore <id> --to <新目录>` 恢复到新目录。备份默认拒绝与记忆库同卷。`export --out 文件.json` 仍可用于跨工具迁移；公共 FACT 是明文文件也可直接 git 备份。
+优先使用 `backup create --dir <独立盘目录>` 创建整库备份；`backup list` 查看，`backup doctor` 校验 SHA-256，`backup restore <id> --to <新目录>` 恢复到新目录。备份默认拒绝与记忆库同卷。`export --out 文件.json` 仍可用于跨工具迁移；公共 FACT 是明文文件也可直接 git 备份。v0.12.2 起，破坏性操作也会在写入前自动创建事务快照。
 
 ## 13. init 会不会覆盖已有记忆？
-不会。v0.12.0 起 `init` 遇到已有记忆库默认拒绝；接入现有库用 `init --attach`。`--force` 在完整备份机制通过前也会明确拒绝，防止再次清空记忆。
+不会。v0.12.0 起 `init` 遇到已有记忆库默认拒绝；接入现有库用 `init --attach`。`--force` 也不能覆盖已有记忆库；强制重建需要完整备份与显式确认保护，当前版本不提供覆盖初始化路径。
 
 ## 11. 记忆太多 / 越来越膨胀怎么办？
-两步走：`yotta-memory maintain --apply` 归档单条低效用旧记忆；同主题积累了很多「又老又不常用」的旧条目时，用 `yotta-memory consolidate`（先预览）→ `consolidate --apply` 把它们归纳成 1 条带溯源的周期摘要并归档原文。也可以先 `config set maintain_decay_halflife_COMMIT 90` 等让任务类承诺更快让位。
+两步走：`yotta-memory maintain --apply` 归档单条低效用旧记忆；同主题积累了很多「又老又不常用」的旧条目时，用 `yotta-memory consolidate`（先预览）→ `consolidate --apply` 把它们归纳成 1 条带溯源的周期摘要并归档原文。v0.12.2 起这些写操作要求先通过 doctor，并会自动创建事务快照；没有独立备份目录时会拒绝执行。也可以先 `config set maintain_decay_halflife_COMMIT 90` 等让任务类承诺更快让位。
 
 ## 12. consolidate 和 distill 有什么区别？
 `distill` 是全库当前快照的统计报告（不淘汰任何记忆，产物是报告）；`consolidate` 是生命周期压缩——只针对超龄 + 长期闲置 + 低效用的旧记忆，生成可检索的周期摘要、把原文归档，让记忆库变小且主题不丢。两者互补：想「看看我记了什么」用 distill；想「给记忆库瘦身」用 consolidate。
@@ -46,3 +46,13 @@
 
 ## 14. 半衰期 / 归档阈值怎么调？
 `yotta-memory config set maintain_decay_halflife_FACT 1000`（FACT 慢衰减，单位天）、`maintain_decay_halflife_PREF` / `maintain_decay_halflife_COMMIT` 同理；BOUND 固定不衰减。归档阈值：`config set maintain_archived_utility 0.3`、`maintain_archived_age 180`；consolidate 参数 `consolidate_min_age` / `consolidate_min_idle` / `consolidate_max_utility` / `consolidate_min_group` / `consolidate_period`。改完 `config get` 可复查；单次运行也可用 CLI 参数（如 `consolidate --min-age 90`）临时覆盖。
+
+## 15. 两个命令有什么区别？怎么更新？
+
+- `yotta-memory` 是引擎 CLI，负责读写记忆库；`npx -y @yottameta/yotta-memory` 只是临时运行引擎，**不会安装技能**。
+- `yotta-memory-install` 是技能安装器。安装或更新技能用 `npx -y --package @yottameta/yotta-memory yotta-memory-install --agent <name>`；用 `--dir` 安装时传入同一个技能目录。
+- 更新 CLI：`npm i -g @yottameta/yotta-memory`。更新技能：重跑上面的 `--package ... yotta-memory-install` 命令，或全局安装后运行 `yotta-memory-install --agent <name>`。
+- 为什么在 `npx -y @yottameta/yotta-memory` 后面加 `--agent <name>` 没有安装技能？因为 npm 默认运行的是包内同名的 `yotta-memory` 引擎 bin，而不是 `yotta-memory-install`；必须用 `--package` 显式指定安装器 bin。
+
+## 16. 开工时怎么知道记忆库是否可靠？
+运行 `yotta-memory doctor`。它只读检查记忆库根目录、加密库密钥文件、公共索引、`agents.json` 与最近备份；`--json` 可输出机器可读结果。严重异常时会锁定 `maintain --apply`、`consolidate --apply`、`merge`、`archive` 与 `--purge` 等破坏性写入，`context` 也会在开工提醒中显示“破坏性写入已锁定”。先按 doctor 提示修复，再继续写操作。

package/references/protocol.md

@@ -194,7 +194,7 @@ magic "YTMIDX1" (7B) | nonce(12B) | tag(16B) | ciphertext(JSON: {version, update
 
 - **语义检索（recall）**：默认开启——精确（字段加权：subject×3 / tags×2 / statement×1）+ 同义词（内置 `SYNONYM_GROUPS`，可扩展）+ 拼音（全拼 `py:` / 首字母 `pyi:` token，内置 3755 常用字表 `references/pinyin-common.json`）+ 模糊（编辑距离 ≤ 2）+ 子串兜底；排序融合 0.65×语义 + 0.35×效用；`--explain` 输出命中理由与效用分项；`--semantic` 显式开启（默认开），旧索引（version<3）首次 recall 自动重建。
 - **feedback（使用反馈闭环）**：`feedback <文件> --useful|--useless [--reason] [--undo]`——useful → weight×1.2（上限 3.0）+ confidence +0.05 + feedback_net +1；useless → weight×0.8（下限 0.2）+ confidence −0.05 + feedback_net −1；审计写 `.archive/feedback-<日期>.jsonl`（含 before/after）；`--undo` 按最近一条回滚。
-- **maintain（规则层自组织）**：统一效用分 `utility = (0.30×confidence + 0.25×usage + 0.20×recency + 0.15×type + 0.10×structure) × weight`（typeScore：BOUND 1.0 / COMMIT 0.9 / PREF 0.8 / FACT 0.6）；归档条件 utility<0.35 且年龄>180 天，遗忘候选 utility<0.12 且年龄>365 天；默认 dry-run，`--apply` 归档（移入 `.archive/`），`--purge` 才真删；immutable / BOUND 豁免；`--dedup` 相似候选（subject 编辑距离 ≤3 且 token Jaccard ≥0.7），`--merge A,B` 手动合并；审计写 `.archive/audit-<日期>.jsonl`。
+- **maintain（规则层自组织）**：统一效用分 `utility = (0.30×confidence + 0.25×usage + 0.20×recency + 0.15×type + 0.10×structure) × weight`（typeScore：BOUND 1.0 / COMMIT 0.9 / PREF 0.8 / FACT 0.6）；归档条件 utility<0.35 且年龄>180 天，遗忘候选 utility<0.12 且年龄>365 天；默认 dry-run，`--apply` 归档（移入 `.archive/`），`--purge` 才真删；v0.12.2 起写操作先通过 doctor 并创建事务快照；immutable / BOUND 豁免；`--dedup` 相似候选（subject 编辑距离 ≤3 且 token Jaccard ≥0.7），`--merge A,B` 手动合并；审计写 `.archive/audit-<日期>.jsonl`。
 - **distill（心理日志蒸馏）**：统计摘要（类型 / 年龄 / 热度 / 反馈）+ 主题画像（按 subject 聚类合并）+ 知识地图（type → tags）；`--model <cmd>` 外部模型协议（stdin JSON → stdout 提炼文本）；私密产物 `private/<owner>/distills/<日期>-<slug>.md`（加密库随 owner key 加密），公共 `facts/distills/`。
 - **explain（效用解释）**：`explain <文件>` 输出效用分项明细与归档 / 遗忘状态判定。
 
@@ -250,4 +250,4 @@ magic "YTMIDX1" (7B) | nonce(12B) | tag(16B) | ciphertext(JSON: {version, update
 ## 6. 与其他系统互操作
 
 - **git**：整个记忆库可纳入版本控制，回滚 / 审计 / 团队同步。
-- **Agent Skills 标准**：本技能 SKILL.md 符合 agentskills.io 开放标准，支持 npx skills 安装。
+- **Agent Skills 标准**：本技能 SKILL.md 符合 agentskills.io 开放标准，支持 npx skills 安装。

package/skill-manifest.json

@@ -0,0 +1,33 @@
+{
+  "manifestVersion": 1,
+  "slug": "yotta-memory",
+  "name": "元忆",
+  "package": "@yottameta/yotta-memory",
+  "version": "0.13.0",
+  "trust": "yottameta",
+  "install": {
+    "idempotent": true
+  },
+  "permissions": {
+    "filesystem": "user-skills-dir",
+    "network": "none",
+    "process": "child-process",
+    "note": "只调用本包内 Node 引擎读写本地记忆库；默认不联网。"
+  },
+  "auto_apply": {
+    "mode": "hook",
+    "note": "关键里程碑完成后写入长期记忆，并保留本地文件证据。"
+  },
+  "hooks": [
+    {
+      "event": "after_milestone",
+      "require_tool": "remember_commit",
+      "condition": "里程碑完成并进入下一步之前",
+      "on_fail": "block",
+      "fallback": "explicit-unverified",
+      "evidence": [
+        "file_path"
+      ]
+    }
+  ]
+}