@yottameta/yotta-memory 0.16.5 → 0.16.7

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## v0.16.7 (2026-09-23)
+
+**迁移口令安全 + view 根指纹复用校验**
+
+- 明文库迁移文档与 CLI `--help` 不再给出可复制的中文占位符管道命令；推荐交互式输入，非 ASCII 口令明确禁止使用 Windows 管道，自动化改用 `YOTTA_MEMORY_PASS` + ASCII 口令。
+- `migrate` 后 `view` 报「口令错误」时，文档给出用恢复钥匙 `reset-password` 的安全恢复路径。
+- `view /api/status` 新增 memory-home `rootId`；`view` 复用已在运行的服务前必须校验根指纹，跨 memory_home 或旧版无指纹服务会拒绝复用并提示关闭进程或换端口。
+- 新增回归：`test/view-root-guard.test.js`（同库复用、跨库拒绝、旧版无指纹拒绝）+ `test/migration-guidance.test.js`（文档安全命令与 CLI help 检查）。
+- 版本对齐：package.json / SKILL.md frontmatter / skill-manifest.json / CHANGELOG / 引擎 VERSION = 0.16.7。
+
+## v0.16.6 (2026-09-23)
+
+**插件 MCP 身份启动器（Agent Plugin 开箱可用）**
+
+- 新增 `bin/plugin-mcp.js`：宿主只替换 `${PLUGIN_ROOT}`、不替换 `${AGENT_ID}` / `${AGENT_KEY_FILE}` 时，按「宿主替换值 → 环境变量 → `PLUGIN_DATA/identity.json` → 未授权可执行指引」解析身份。
+- 未装配身份时不再把字面量占位符传给引擎：以未授权模式启动（公共 FACT 可读、私密 fail-closed），并输出含 `key claim` 与 `identity.json` 的可执行指引。
+- `key claim <id> --plugin-data <PLUGIN_DATA>`：一条命令同时写入插件 key 与 `identity.json`；与 `--to` / `--agent-key-file` 互斥校验。
+- 插件 `mcp.json` 入口由 `yotta-memory.js` 改为 `plugin-mcp.js`；宿主替换占位符的旧路径继续有效。
+- 回归：`test/plugin-mcp-launcher.test.js`（身份优先级 / 无身份指引）+ `test/plugin-claim-binding.test.js`（claim → 插件身份 → 私密读取端到端）；全量 `npm test` 167/167 PASS。
+- 版本对齐：package.json / SKILL.md frontmatter / skill-manifest.json / CHANGELOG / 引擎 VERSION = 0.16.6。
+
 ## v0.16.5 (2026-09-22)
 
 **doctor --json 稳定契约补齐**
@@ -23,7 +44,7 @@
 **迁移最短路径与授权引导修复**
 
 - `migrate` 成功输出不再只提示 `key bind`：现在明确输出“授权二选一（等价）”——推荐 `yotta-memory view` 页面授权，高级 CLI 方式为 `yotta-memory key bind <id>`，随后 AI 统一执行 `key status` → `key claim`。
-- `SKILL.md`、`USER_GUIDE.md`、`references/faq.md`、中英 README 统一加入明文库第一次转加密命令：`echo 主口令 | yotta-memory migrate --password-stdin --recovery-key-out ...`，并补充交互终端 / PowerShell / cmd / 管道等口令传递方式和一个统一报错对照。
+- `SKILL.md`、`USER_GUIDE.md`、`references/faq.md`、中英 README 统一加入明文库第一次转加密命令（v0.16.7 已废弃原中文占位符管道写法）；后续补充交互终端 / PowerShell / cmd / 管道等口令传递方式和一个统一报错对照。
 - 修正迁移后的索引顺序：必须 **授权 → `key claim` → 带 `--agent-key-file` 执行 `reindex` → `recall` 验证**；`migrate` 在没有 agent_key 时无法建立每 owner 加密索引。MCP 自检同时要求配置带 `--agent-key-file`。
 - `--help` 的 `migrate` 行同步给出首次迁移命令与两条等价授权路径。
 - 新增 `test/migration-guidance.test.js`，锁定迁移命令、`view` / `key bind` 等价关系和 CLI 帮助口径。

package/README.md

@@ -23,11 +23,12 @@
 
 > 📖 The user-facing operations manual lives in [USER_GUIDE.md](USER_GUIDE.md).
 
+> 🆕 **v0.16.7 (migration password safety + view root fingerprint)**: use the interactive migration prompt `yotta-memory migrate --recovery-key-out "%USERPROFILE%\yotta-memory-recovery.key"` and type the master password. Automation can set `YOTTA_MEMORY_PASS` with an ASCII password. Do not pipe non-ASCII passwords on Windows (`echo 中文 | ...` can change the bytes). `view` now verifies a memory-home fingerprint before reusing a running server and refuses cross-store or legacy servers without one.
 > 🆕 **v0.16.5 (doctor JSON contract)**: `doctor --json` now exposes stable top-level `schemaVersion`, `encryption`, and `migration_required` fields while preserving the existing `checks` / `warnings` / `identity` structure.
 > 🆕 **v0.16.4 (agent-key prompt scope)**: a missing `--agent-key-file` no longer prints a global `stderr` warning for public or maintenance commands. Only real private-data access fails closed, with the missing path, `view` / `key bind`, and `key status` / `key claim` guidance. `whoami --json`, `doctor --json`, and `config get --json` expose structured `identity.mode` / `identity.agentKeyStatus` fields.
 > 🆕 **v0.16.2 (first-boot fixes)**: an empty encrypted store can unlock `view` with the recovery key; non-TTY hosts can use `--password-stdin`; recovery keys can be written with `--recovery-key-out <file>`; a missing `--agent-key-file` degrades to unauthenticated public-only mode; an empty plaintext store can be migrated to encryption; `view` reports port reuse/conflicts clearly.
-> 🆕 **v0.16.3 (migration quick path)**: convert a plaintext store to encryption with
-> `echo <master-password> | yotta-memory migrate --password-stdin --recovery-key-out "%USERPROFILE%\yotta-memory-recovery.key"`.
+> 🆕 **v0.16.3 (migration quick path)**: convert a plaintext store to encryption with the interactive command
+> `yotta-memory migrate --recovery-key-out "%USERPROFILE%\yotta-memory-recovery.key"`.
 > Then authorize agents with `yotta-memory view`; `view` and `yotta-memory key bind <id>` are equivalent, followed by `key status` / `key claim`, then `reindex` with `--agent-key-file` and a `recall` verification.
 > 🆕 **v0.16.0 (identity model + stable runtime)**: identity is no longer read from environment variables. HTTP / remote MCP uses request headers `Authorization` + `X-Agent-Id` + `X-Agent-Key`; stdio MCP uses explicit `--agent-id` + `--agent-key-file`; CLI uses `--agent` + `--agent-key` / `--agent-key-file`. The new `runtime install --from-current` / `use` / `rollback` / `status` commands create a stable `<runtimeRoot>/current` launcher so managed MCP, autostart and backup tasks do not pin a version directory. `doctor --runtime` checks CLI / current / MCP config / running server / skill-copy drift, and MCP `serverInfo` returns `runtimePath` / `identityMode` / `toolProfile`.
 > 🆕 **v0.15.0 (MCP tool profiles)**: `serve --tools core|full` controls the exposed MCP surface. `core` keeps `context / recall / search / remember` resident; `full` keeps the existing 16 tools for diagnostics and maintenance. Omitting the flag keeps the previous `full` behavior for compatibility.

package/README.zh-CN.md

@@ -23,11 +23,12 @@
 
 > 📖 面向用户的操作手册见 [USER_GUIDE.md](USER_GUIDE.md)。
 
+> 🆕 **v0.16.7（迁移口令安全 + view 根指纹）**：明文库转加密推荐交互式 `yotta-memory migrate --recovery-key-out "$env:USERPROFILE\yotta-memory-recovery.key"`，按提示输入主口令；自动化使用 `YOTTA_MEMORY_PASS`。非 ASCII 口令不要用 Windows 管道（`echo 中文 | ...` 可能改变实际口令）。`view` 复用端口前会校验 memory_home 指纹；跨库或旧版无指纹服务会拒绝复用并提示换端口。
 > 🆕 **v0.16.5（doctor JSON 契约）**：`doctor --json` 顶层新增稳定字段 `schemaVersion` / `encryption` / `migration_required`，同时保留原有 `checks` / `warnings` / `identity` 结构。
 > 🆕 **v0.16.4（agent-key 提示范围）**：`--agent-key-file` 不存在时不再为公共 / 维护命令输出全局 `stderr` 警告；只有真正访问私密区才 fail-closed，并给出缺失路径、`view` / `key bind`、`key status` / `key claim` 步骤。`whoami --json`、`doctor --json`、`config get --json` 返回结构化 `identity.mode` / `identity.agentKeyStatus`。
 > 🆕 **v0.16.2（首启修复）**：空加密库 `view` 可用恢复钥匙解锁；非 TTY 支持 `--password-stdin`；恢复钥匙支持 `--recovery-key-out <文件>`；`--agent-key-file` 不存在时降级未授权（公共 FACT 可读、私密 fail-closed）；空明文库可直接 `migrate` 启用加密；`view` 端口占用给明确提示。
-> 🆕 **v0.16.3（迁移最短路径）**：明文库第一次转加密：
-> `echo 主口令 | yotta-memory migrate --password-stdin --recovery-key-out "%USERPROFILE%\yotta-memory-recovery.key"`
+> 🆕 **v0.16.3（迁移最短路径）**：明文库第一次转加密推荐交互式：
+> `yotta-memory migrate --recovery-key-out "$env:USERPROFILE\yotta-memory-recovery.key"`
 > 迁移后用 `yotta-memory view` 授权 AI；`view` 与 `yotta-memory key bind <id>` 是等价路径，随后执行 `key status` / `key claim`，再带 `--agent-key-file` 执行 `reindex` 重建加密索引并 `recall` 验证。
 > 🆕 **v0.16.0（身份模型 + 稳定运行时）**：身份不再从环境变量读取。HTTP / 远程 MCP 用请求头 `Authorization` + `X-Agent-Id` + `X-Agent-Key`；stdio MCP 用显式参数 `--agent-id` + `--agent-key-file`；CLI 用 `--agent` + `--agent-key` / `--agent-key-file`。新增 `runtime install --from-current` / `use` / `rollback` / `status`，创建 `<runtimeRoot>/current` 稳定入口，受管 MCP、自启与备份任务不再写死版本目录。`doctor --runtime` 检查 CLI / current / MCP 配置 / 运行中 server / 技能副本漂移；MCP `serverInfo` 返回 `runtimePath` / `identityMode` / `toolProfile`。
 > 🆕 **v0.15.0（MCP 工具分组）**：`serve --tools core|full` 控制 MCP 工具暴露面。`core` 常驻 `context / recall / search / remember`；`full` 保留现有 16 个诊断与维护工具。未指定参数时默认 `full`，保持现有配置兼容。

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、防误删、doctor、事务快照
-version: 0.16.5
+version: 0.16.7
 license: MIT
 ---
 
@@ -243,7 +243,9 @@ yotta-memory doctor --json
    - 输出 `memory_home: (未设置，默认 ~/.yottamemory)` → 🔒 征得同意后引导设置：问用户用默认还是指定目录（项目级 `<repo>/.yottamemory`、记忆盘等），确认后 AI 执行 `yotta-memory config set memory_home <目录>`，回读 `config get` 验证。
 2. **已有记忆**：目标目录已存在 `facts/` 等子目录或 `index.json` → 直接 recall；全新目录 → 按「便携记忆盘模式 §0.3」初始化。
 3. **私密区为明文（无 `keys/`；`doctor` 显示「加密: 否」）**：首次使用即主动告知风险——明文私密记忆（PREF / BOUND / COMMIT）可被同机任何能读文件的进程或用户直接看到；然后给出《明文库转加密（第一次最短路径）》。口令与迁移必须由用户本人执行，AI 只讲解并负责后续 `key claim`。用户明确拒绝加密时，记录其选择并复述明文风险，不反复打扰。
-4. **私密区已加密（存在 `keys/`）**：先 `yotta-memory key list` 确认本智能体是否有 agent binding；没有 → 告知用户由用户自己执行 `yotta-memory view` → 浏览器打开平台 → 输入主口令 → 点「授权」并保存只展示一次的 `agent_key`。用户授权后服务端会写 `keys/pending/<id>.key`；AI 在新会话执行 `yotta-memory key status <id>`（需要时显式加 `--to <AI_HOME>` 或 `--agent-key-file <文件>`；默认发现规则见下），有 pending 就执行 `yotta-memory key claim <id>`，落到 `<AI_HOME>/.yotta-memory-agent-key` 后再使用 `--agent-key-file`。**升级后首次调用元忆 / 重启会话时**，若输出 `[YTM_MIGRATION_REQUIRED]`，必须主动把 marker、受影响 agent 和处理步骤转达给用户。**AI 不得代替用户执行 `migrate` / `key bind` 迁移**，只负责提醒和讲解（marker 只列仍有私密数据、未绑定的 agent；仅有 legacy cache、无迁移数据的 owner 会单独提示，不进入迁移清单；公共 FACT 不受影响）。
+4. **Agent Plugin 开箱装配（v0.16.6）**：插件 `mcp.json` 入口是 `bin/plugin-mcp.js`。宿主已替换身份占位符时优先用替换值；未替换时回退到 `YOTTA_MEMORY_AGENT_ID` + `YOTTA_MEMORY_AGENT_KEY_FILE`，再回退到 `PLUGIN_DATA/identity.json`。都没有时插件以未授权模式启动（公共 FACT 可读、私密 fail-closed）并打印绑定指引。绑定一条命令：用户在 `yotta-memory view` 授权后执行 `yotta-memory key claim <id> --plugin-data <PLUGIN_DATA>`（同时写 key 与 `identity.json`），重启会话即可。
+
+5. **私密区已加密（存在 `keys/`）**：先 `yotta-memory key list` 确认本智能体是否有 agent binding；没有 → 告知用户由用户自己执行 `yotta-memory view` → 浏览器打开平台 → 输入主口令 → 点「授权」并保存只展示一次的 `agent_key`。用户授权后服务端会写 `keys/pending/<id>.key`；AI 在新会话执行 `yotta-memory key status <id>`（需要时显式加 `--to <AI_HOME>` 或 `--agent-key-file <文件>`；默认发现规则见下），有 pending 就执行 `yotta-memory key claim <id>`，落到 `<AI_HOME>/.yotta-memory-agent-key` 后再使用 `--agent-key-file`。**升级后首次调用元忆 / 重启会话时**，若输出 `[YTM_MIGRATION_REQUIRED]`，必须主动把 marker、受影响 agent 和处理步骤转达给用户。**AI 不得代替用户执行 `migrate` / `key bind` 迁移**，只负责提醒和讲解（marker 只列仍有私密数据、未绑定的 agent；仅有 legacy cache、无迁移数据的 owner 会单独提示，不进入迁移清单；公共 FACT 不受影响）。
 
 **B. 确认本智能体唯一身份（强制，写私密记忆前必做）**：
 
@@ -278,7 +280,7 @@ yotta-memory doctor --json
 | 命令 | 作用 |
 |---|---|
 | `yotta-memory init [--project] [--dir <目录>] [--attach] [--encrypt|--no-encrypt] [--password-stdin] [--recovery-key-out <文件>]` | 初始化（**新建默认加密**：设主口令 + 抄下恢复钥匙；已有库必须用 `--attach`，默认拒绝覆盖；`--no-encrypt` 降级明文；老明文库用 `migrate`；非 TTY 用 `--password-stdin`；恢复钥匙可写文件）|
-| `yotta-memory migrate [--password-stdin] [--recovery-key-out <文件>]` | 明文库 → 密文迁移（**由用户执行**；首次迁移命令、`view` 授权与 `key bind` 等价关系见《明文库转加密（第一次最短路径）》）|
+| `yotta-memory migrate [--password-stdin] [--recovery-key-out <文件>]` | 明文库 → 密文迁移（**由用户执行**；首次迁移推荐交互式，非 ASCII 口令勿用 Windows 管道；`view` 授权与 `key bind` 等价关系见《明文库转加密（第一次最短路径）》）|
 | `yotta-memory view [--port 8788] [--host 127.0.0.1]` | 用户查看平台（本机 Web：口令解锁浏览 / 搜索 / 导出全部 AI 记忆 + 授权 / 吊销 AI + 重设口令 + 显示恢复钥匙；已在运行则复用 URL，端口占用给明确提示）|
 | `yotta-memory reset-password [--password <当前> | --recovery-key <钥匙>] [--new-password <新>]` | 重设主口令（忘口令用恢复钥匙）|
 | `yotta-memory key list / bind <id> / rotate <id> / claim <id> [--to <AI_HOME> | --agent-key-file <文件>] / status <id> [--to <AI_HOME> | --agent-key-file <文件>] / revoke <id>` | 管理 agent_key binding（**bind/rotate 由用户执行**，需主口令或恢复钥匙；claim/status 由 AI 读取 pending 并落到宿主目录，按同一 AI_HOME 发现规则；revoke 立即吊销该 AI 解密能力，旧 key 随即校验失败；`key list` 合并 `keys/*.key.enc`，显示仅有钥、尚未写记忆的 owner；输出 `[YTM_MIGRATION_REQUIRED]` 时提醒用户走 `view` 重新授权）|
@@ -318,22 +320,22 @@ yotta-memory doctor --json
 
 > 适用于 `yotta-memory 0.16.2+`。迁移前先完整备份。
 
-1. **迁移**：
+1. **迁移**（推荐交互式；非 ASCII 口令不要走 Windows 管道）：
 
-```cmd
-echo 主口令 | yotta-memory migrate --password-stdin --recovery-key-out "%USERPROFILE%\yotta-memory-recovery.key"
+```powershell
+yotta-memory migrate --recovery-key-out "$env:USERPROFILE\yotta-memory-recovery.key"
 ```
 
-口令传递方式（同一迁移命令，按终端选择一种；不要把口令写进 `--password` 参数）：
+按提示输入主口令。自动化场景按终端选择一种；不要直接把中文占位符粘贴到命令里，也不要把口令写进 `--password` 参数：
 
 | 场景 | 命令 |
 |---|---|
-| 非 TTY / 管道（推荐） | `echo 主口令 \| yotta-memory migrate --password-stdin --recovery-key-out "<钥匙文件>"` |
-| 交互终端 | `yotta-memory migrate --recovery-key-out "<钥匙文件>"`，按提示输入口令 |
-| PowerShell 环境变量 | `$env:YOTTA_MEMORY_PASS='<主口令>'; yotta-memory migrate --recovery-key-out "<钥匙文件>"; Remove-Item Env:\YOTTA_MEMORY_PASS` |
-| cmd 环境变量 | `set "YOTTA_MEMORY_PASS=<主口令>"`，执行 `yotta-memory migrate --recovery-key-out "<钥匙文件>"`，最后 `set "YOTTA_MEMORY_PASS="` |
+| 交互终端（推荐，支持非 ASCII） | `yotta-memory migrate --recovery-key-out "<钥匙文件>"`，按提示输入口令 |
+| PowerShell 环境变量（自动化） | `$env:YOTTA_MEMORY_PASS='<ASCII-PASSWORD>'; yotta-memory migrate --recovery-key-out "<钥匙文件>"; Remove-Item Env:\YOTTA_MEMORY_PASS` |
+| cmd 环境变量（自动化） | `set "YOTTA_MEMORY_PASS=<ASCII-PASSWORD>"`，执行 `yotta-memory migrate --recovery-key-out "<钥匙文件>"`，最后 `set "YOTTA_MEMORY_PASS="` |
+| 纯 ASCII 管道（非 ASCII 不要用） | `"<ASCII-PASSWORD>" \| yotta-memory migrate --password-stdin --recovery-key-out "<钥匙文件>"` |
 
-常见报错：`当前为非交互环境` = 没有 stdin 也没有 `YOTTA_MEMORY_PASS`；`'"..."' is not recognized` = 在 `cmd.exe` 里用了 PowerShell 的管道写法。口令含非 ASCII 时，PowerShell 可先设置 `$OutputEncoding=[Text.Encoding]::UTF8`。
+常见报错：`当前为非交互环境` = 没有 stdin 也没有 `YOTTA_MEMORY_PASS`；`'"..."' is not recognized` = 在 `cmd.exe` 里用了 PowerShell 的管道写法。Windows 管道可能按控制台代码页编码非 ASCII 字符，导致实际入库口令与输入口令不一致；因此非 ASCII 口令请使用交互终端或环境变量，不要使用 `echo 中文 | ...`。若迁移后 `view` 报 `口令错误`，优先用恢复钥匙执行 `yotta-memory reset-password --recovery-key "<钥匙文件>"` 重设，不要继续猜口令。
 
 恢复钥匙文件必须离线保存，不要和记忆库或备份放在一起。
 

package/USER_GUIDE.md

@@ -136,11 +136,11 @@ statement: 本周完成发布
 
 1. 迁移：
 
-```cmd
-echo 主口令 | yotta-memory migrate --password-stdin --recovery-key-out "%USERPROFILE%\yotta-memory-recovery.key"
+```powershell
+yotta-memory migrate --recovery-key-out "$env:USERPROFILE\yotta-memory-recovery.key"
 ```
 
-非 TTY 也可以使用 `YOTTA_MEMORY_PASS`（PowerShell / cmd 语法不同）；交互终端直接运行 `yotta-memory migrate --recovery-key-out "<钥匙文件>"` 并按提示输入口令。不要把口令写进 `--password` 参数。
+交互终端按提示输入口令；非 ASCII 口令请使用交互输入。非 TTY 自动化可使用 `YOTTA_MEMORY_PASS`（PowerShell / cmd 语法不同），但不要使用 `echo 中文 | ...`，Windows 管道可能改变实际口令。不要把口令写进 `--password` 参数。若迁移后 `view` 报口令错误，用恢复钥匙执行 `yotta-memory reset-password --recovery-key "<钥匙文件>"` 重设。
 
 2. 授权 AI（二选一，等价）：
 

package/bin/plugin-mcp.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// yotta-memory（元忆）插件 MCP 启动器（v0.16.6）
+// 宿主（Codex / Agent Plugins）只替换 ${PLUGIN_ROOT} 与注入 PLUGIN_ROOT / PLUGIN_DATA，
+// 不替换 mcp.json 里的 ${AGENT_ID} / ${AGENT_KEY_FILE}。本启动器按优先级解析身份：
+//   1) 宿主已替换的 --agent-id / --agent-key-file
+//   2) YOTTA_MEMORY_AGENT_ID + YOTTA_MEMORY_AGENT_KEY_FILE 环境变量
+//   3) PLUGIN_DATA/identity.json（agent_id / key_file；key_file 缺省 <PLUGIN_DATA>/.yotta-memory-agent-key）
+//   4) 都没有 -> 以未授权模式启动，输出可执行的绑定指引（不出现字面量占位符）
+// 绑定路径：用户在 yotta-memory view 授权后，AI 执行
+//   yotta-memory key claim <agent_id> --to <PLUGIN_DATA>
+// 或写入 <PLUGIN_DATA>/identity.json。
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const AGENT_KEY_FILENAME = '.yotta-memory-agent-key';
+const PLACEHOLDER_RE = /^\$\{[A-Z_]+\}$/;
+
+function cleanValue(value) {
+  const v = String(value == null ? '' : value).trim();
+  if (!v || PLACEHOLDER_RE.test(v)) return '';
+  return v;
+}
+
+function readIdentityFile(pluginData) {
+  if (!pluginData) return null;
+  const file = path.join(pluginData, 'identity.json');
+  if (!fs.existsSync(file)) return null;
+  try {
+    const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+    const id = cleanValue(data.agent_id || data.agentId || '');
+    if (!id) return null;
+    const keyFile = cleanValue(data.key_file || data.keyFile || '') ||
+      path.join(pluginData, AGENT_KEY_FILENAME);
+    return { id: id, keyFile: keyFile, source: 'plugin-data' };
+  } catch (e) {
+    return null;
+  }
+}
+
+function resolvePluginIdentity(opts, env) {
+  opts = opts || {};
+  env = env || process.env;
+  const hostId = cleanValue(opts.agentId);
+  const hostKey = cleanValue(opts.keyFile);
+  if (hostId && hostKey) {
+    return { id: hostId, keyFile: hostKey, source: 'host-args' };
+  }
+  const envId = cleanValue(env.YOTTA_MEMORY_AGENT_ID);
+  const envKey = cleanValue(env.YOTTA_MEMORY_AGENT_KEY_FILE);
+  if (envId && envKey) {
+    return { id: envId, keyFile: envKey, source: 'env' };
+  }
+  const fromData = readIdentityFile(cleanValue(env.PLUGIN_DATA));
+  if (fromData) return fromData;
+  return null;
+}
+
+function parseArgs(argv) {
+  const rest = [];
+  const opts = { agentId: '', keyFile: '' };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--agent-id') { opts.agentId = argv[++i]; continue; }
+    if (a === '--agent-key-file') { opts.keyFile = argv[++i]; continue; }
+    rest.push(a);
+  }
+  return { rest: rest, opts: opts };
+}
+
+function guidanceText(pluginData) {
+  const dataDir = pluginData || '<PLUGIN_DATA>';
+  return [
+    '元忆插件 MCP 尚未装配智能体身份：宿主未替换 mcp.json 中的身份占位符，且未找到环境变量或 identity.json。',
+    '当前以未授权模式启动：公共 FACT 可读，私密记忆（PREF / BOUND / COMMIT）fail-closed。',
+    '绑定步骤（用户授权后由 AI 执行）：',
+    '  1) 用户在 yotta-memory view 中授权本智能体；',
+    '  2) AI 执行  yotta-memory key claim <agent_id> --to ' + dataDir,
+    '     或写入 ' + path.join(dataDir, 'identity.json') + '：{"agent_id":"<agent_id>"}',
+    '  3) 重启会话后插件即可读取私密记忆。',
+  ].join('\n');
+}
+
+function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+  const ident = resolvePluginIdentity(parsed.opts, process.env);
+  const cli = path.join(__dirname, 'yotta-memory.js');
+  const args = [cli].concat(parsed.rest);
+  if (ident) {
+    args.push('--agent-id', ident.id, '--agent-key-file', ident.keyFile);
+  } else {
+    process.stderr.write(guidanceText(process.env.PLUGIN_DATA) + '\n');
+  }
+  const child = spawn(process.execPath, args, { stdio: 'inherit' });
+  child.on('exit', function (code, signal) {
+    if (signal) process.kill(process.pid, signal);
+    else process.exit(code == null ? 0 : code);
+  });
+  child.on('error', function (err) {
+    process.stderr.write('元忆插件 MCP 启动失败: ' + (err && err.message ? err.message : String(err)) + '\n');
+    process.exit(2);
+  });
+}
+
+module.exports = {
+  resolvePluginIdentity: resolvePluginIdentity,
+  guidanceText: guidanceText,
+};
+
+if (require.main === module) main();

package/bin/yotta-memory.js

@@ -25,7 +25,7 @@ const net = require('net');
 const child_process = require('child_process');
 const { AsyncLocalStorage } = require('async_hooks');
 
-const VERSION = '0.16.5';
+const VERSION = '0.16.7';
 // @generated view-html:start
 const VIEW_HTML = "<!doctype html><html lang=\"zh\"><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width,initial-scale=1\"><title>元忆 · 用户查看平台</title><style>\r\nbody{font-family:system-ui,-apple-system,\"Microsoft YaHei\",sans-serif;max-width:1000px;margin:24px auto;padding:0 16px;color:#1f2328;background:#fafafa}\r\nh1{font-size:22px} .card{background:#fff;border:1px solid #e2e2e2;border-radius:10px;padding:16px 18px;margin:14px 0;box-shadow:0 1px 2px rgba(0,0,0,.04)}\r\nbutton{background:#2563eb;color:#fff;border:0;border-radius:6px;padding:7px 14px;cursor:pointer;margin:2px;font-size:14px}\r\nbutton.danger{background:#dc2626} button.ghost{background:#e5e7eb;color:#1f2328}\r\ninput,select{padding:8px;border:1px solid #c9c9c9;border-radius:6px;margin:2px;font-size:14px;box-sizing:border-box}\r\ntable{border-collapse:collapse;width:100%;font-size:13px} td,th{border:1px solid #ececec;padding:6px 8px;text-align:left;vertical-align:top}\r\n.owner{display:inline-flex;align-items:center;gap:6px;border:1px solid #ddd;border-radius:8px;padding:5px 10px;margin:4px 6px 4px 0;background:#f6f8fa}\r\n.entry{border-bottom:1px solid #eee;padding:8px 0} .meta{color:#8a8a8a;font-size:12px}\r\n.err{color:#dc2626;margin-top:8px} .ok{color:#16a34a;margin-top:8px}\r\n#app{display:none} code{background:#f0f0f0;padding:1px 5px;border-radius:4px;font-size:12px}\r\n</style></head><body>\r\n<h1>元忆 · 用户查看平台 <span id=\"ver\" style=\"font-size:14px;color:#888\"></span></h1>\r\n<div id=\"lock\" class=\"card\">\r\n  <p><b>输入主口令解锁</b>（口令只在本地内存派生，不落盘、不发送远端）。忘口令可在 CLI 用恢复钥匙重设：<code>yotta-memory reset-password --recovery-key &lt;钥匙&gt;</code></p>\r\n  <input type=\"password\" id=\"pw\" placeholder=\"主口令\" style=\"width:260px\">\r\n  <button onclick=\"unlock()\">解锁</button>\r\n  <div class=\"err\" id=\"lockerr\"></div>\r\n</div>\r\n<div id=\"app\">\r\n  <div class=\"card\">\r\n    <b>AI 列表</b>（✅=已授权可读自己私密，🔒=未授权）\r\n    <div class=\"meta\" style=\"margin-top:6px\">「授权」由你（用户）操作：确认后生成只显示一次的 agent_key，请立即单独保存；服务端同时写临时待领取文件 <code>keys/pending/&lt;agent_id&gt;.key</code>，供该 AI 新会话领取，领取成功后自动删除。</div>\r\n    <div id=\"owners\" style=\"margin-top:8px\"></div>\r\n  </div>\r\n  <div class=\"card\">\r\n    <b>记忆</b>\r\n    <input id=\"q\" placeholder=\"搜索关键词\" style=\"width:220px\" onkeydown=\"if(event.key==='Enter'){off=0;load()}\">\r\n    <button onclick=\"off=0;load()\">搜索</button>\r\n    <button class=\"ghost\" onclick=\"doExport()\">导出 JSON</button>\r\n    <button class=\"ghost\" onclick=\"showRk()\">显示恢复钥匙</button>\r\n    <span id=\"rkout\" style=\"font-size:12px;color:#888;margin-left:8px\"></span>\r\n    <div id=\"meta\" style=\"margin-top:10px;font-size:12px;color:#666\"></div>\r\n    <div id=\"entries\" style=\"margin-top:6px\"></div>\r\n    <div id=\"pager\" style=\"margin-top:10px\">\r\n      <button class=\"ghost\" id=\"prevb\" onclick=\"prevPage()\">上一页</button>\r\n      <span id=\"pageinfo\" style=\"font-size:12px;color:#888;margin:0 8px\"></span>\r\n      <button class=\"ghost\" id=\"nextb\" onclick=\"nextPage()\">下一页</button>\r\n    </div>\r\n  </div>\r\n  <div class=\"card\">\r\n    <b>重设口令</b><br>\r\n    <input type=\"password\" id=\"cur\" placeholder=\"当前口令\">\r\n    <input type=\"password\" id=\"np1\" placeholder=\"新口令\">\r\n    <input type=\"password\" id=\"np2\" placeholder=\"确认新口令\">\r\n    <button onclick=\"resetPw()\">重设</button>\r\n    <span id=\"pwout\"></span>\r\n  </div>\r\n</div>\r\n<script>\r\nfunction esc(s){return String(s==null?'':s).replace(/[&<>\"']/g,function(c){return{'&':'&amp;','<':'&lt;','>':'&gt;','\"':'&quot;',\"'\":'&#39;'}[c];});}\r\nasync function api(p,b){try{const r=await fetch(p,{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify(b||{})});return await r.json();}catch(e){return{error:String(e)};}}\r\nasync function boot(){const s=await api('/api/status');document.getElementById('ver').textContent='v'+(s.version||'');if(s.unlocked){showApp();}}\r\nfunction showApp(){document.getElementById('lock').style.display='none';document.getElementById('app').style.display='block';loadOwners();load();}\r\nasync function unlock(){const d=await api('/api/unlock',{password:document.getElementById('pw').value});if(d.error){document.getElementById('lockerr').textContent=d.error;return;}showApp();}\r\nasync function loadOwners(){const d=await api('/api/owners');const box=document.getElementById('owners');box.innerHTML='';if(!d.owners||!d.owners.length){box.innerHTML=esc(d.hint||'（无 owner）');return;}\r\n  for(const o of d.owners){const c=document.createElement('span');c.className='owner';c.innerHTML=esc(o.owner)+(o.authorized?' ✅':' 🔒')+' <button class=\"ghost\" data-a=\"'+esc(o.owner)+'\">授权</button><button class=\"danger\" data-r=\"'+esc(o.owner)+'\">吊销</button>';box.appendChild(c);}\r\n  box.querySelectorAll('[data-a]').forEach(function(b){b.onclick=function(){var owner=b.getAttribute('data-a');if(!confirm('确认由你为用户授权 '+owner+' 读取其私密记忆？授权后将生成只显示一次的 agent_key，请立即保存；同时写入待领取文件供该 AI 新会话领取。AI 不应代为执行该授权操作。'))return;b.disabled=true;api('/api/authorize',{owner:owner}).then(function(d){b.disabled=false;if(!d||d.error){alert((d&&d.error)||'授权失败');loadOwners();return;}if(d.agentKey){showKey(d.agentKey);}loadOwners();});};});\r\n  box.querySelectorAll('[data-r]').forEach(function(b){b.onclick=function(){if(!confirm('确认吊销 '+b.getAttribute('data-r')+' 的 agent_key？吊销后该智能体立即失去私密读写能力。'))return;api('/api/revoke',{owner:b.getAttribute('data-r')}).then(function(){loadOwners();});};});\r\nfunction showKey(k){var ov=document.createElement('div');ov.style.cssText='position:fixed;inset:0;background:rgba(0,0,0,.45);display:flex;align-items:center;justify-content:center;z-index:99';var box=document.createElement('div');box.className='card';box.style.cssText='max-width:640px;word-break:break-all';var t=document.createElement('div');t.innerHTML='<b>agent_key（只显示一次）</b>';var hint=document.createElement('div');hint.className='meta';hint.textContent='请用户立即单独保存。AI 新会话先执行 yotta-memory key status <agent_id>，有 pending 再执行 key claim <agent_id>；默认写入 AI_HOME/.yotta-memory-agent-key，需要时用 --to 或 --agent-key-file 指定。若 key 丢失，可吊销后重新授权；旧 key 会立即校验失败。';var ta=document.createElement('textarea');ta.readOnly=true;ta.value=k;ta.style.cssText='width:100%;height:72px;margin-top:8px;font-family:monospace;font-size:12px';var close=document.createElement('button');close.textContent='我已保存，关闭';close.onclick=function(){ov.remove();};box.appendChild(t);box.appendChild(hint);box.appendChild(ta);box.appendChild(close);ov.appendChild(box);document.body.appendChild(ov);ta.focus();ta.select();}\r\n}\r\nlet off=0,PS=50;\r\nasync function load(){const d=await api('/api/entries',{query:document.getElementById('q').value,offset:off,limit:PS});const meta=document.getElementById('meta');const pg=document.getElementById('pageinfo');if(meta)meta.textContent='共 '+d.count+' 条';const lim=d.limit||PS;const totalPg=Math.max(1,Math.ceil(d.count/lim));const curPg=Math.floor((d.offset||0)/lim)+1;if(pg)pg.textContent='第 '+curPg+' / '+totalPg+' 页';const box=document.getElementById('entries');box.innerHTML='';if(d.entries)for(const e of d.entries){const div=document.createElement('div');div.className='entry';div.innerHTML='<b>['+esc(e.type)+'] '+esc(e.subject)+'</b><div>'+esc(e.statement)+'</div><div class=\"meta\">'+esc(e.file)+' · owner='+esc(e.owner||'-')+' · '+esc(e.updated||e.created||'')+'</div>';box.appendChild(div);}const pb=document.getElementById('prevb'),nb=document.getElementById('nextb');if(pb)pb.disabled=(d.offset||0)<=0;if(nb)nb.disabled=!d.hasMore;}\r\nfunction prevPage(){if(off>=PS){off-=PS;load();}}\r\nfunction nextPage(){off+=PS;load();}\r\nasync function doExport(){const d=await api('/api/export');if(d.error){alert(d.error);return;}const blob=new Blob([JSON.stringify(d,null,2)],{type:'application/json'});const a=document.createElement('a');a.href=URL.createObjectURL(blob);a.download='yottamemory-view-export.json';a.click();}\r\nasync function showRk(){const d=await api('/api/recovery-key');document.getElementById('rkout').textContent=d.recoveryKey?('恢复钥匙: '+d.recoveryKey):(d.error||'');}\r\nasync function resetPw(){const np1=document.getElementById('np1').value,np2=document.getElementById('np2').value;if(np1!==np2){document.getElementById('pwout').innerHTML='<span class=\"err\">两次新口令不一致</span>';return;}\r\n  const d=await api('/api/reset-password',{currentPassword:document.getElementById('cur').value,newPassword:np1});document.getElementById('pwout').innerHTML=d.error?('<span class=\"err\">'+esc(d.error)+'</span>'):('<span class=\"ok\">'+esc(d.text||'ok')+'</span>');}\r\nboot();\r\n</script></body></html>\r\n";
 // @generated view-html:end
@@ -78,6 +78,11 @@ function userRoot() {
 function projectRoot() {
   return path.join(process.cwd(), '.yottamemory');
 }
+function memoryRootId(root) {
+  let resolved = path.resolve(String(root));
+  if (process.platform === 'win32') resolved = resolved.toLowerCase();
+  return crypto.createHash('sha256').update(resolved, 'utf8').digest('hex');
+}
 // 唯一化记忆库根：projectRoot 与 userRoot 可能指向同一目录（如 cwd=home 或其父时），
 // 若不唯一化，recall/context 等会对同一索引遍历两次 -> 同一条记忆重复展示（v0.6.5 修复）。
 function memoryRoots() {
@@ -336,7 +341,11 @@ function runtimeValidateTarballEntries(entries) {
 }
 function runtimeListTarballEntries(tarball) {
   const tarBin = process.env.YOTTA_RUNTIME_TAR || 'tar';
-  const listed = child_process.spawnSync(tarBin, ['-tzf', tarball], { encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 });
+  const listed = child_process.spawnSync(tarBin, ['-tzf', path.basename(tarball)], {
+    cwd: path.dirname(tarball),
+    encoding: 'utf8',
+    maxBuffer: 8 * 1024 * 1024,
+  });
   if (listed.error) throw new Error('无法执行 tar: ' + listed.error.message);
   if (listed.status !== 0) throw new Error('读取 runtime tarball 失败: ' + String(listed.stderr || listed.stdout || '').trim());
   return String(listed.stdout || '').split(/\r?\n/).filter(Boolean);
@@ -344,7 +353,8 @@ function runtimeListTarballEntries(tarball) {
 function runtimeExtractTarball(tarball, tempDir) {
   runtimeValidateTarballEntries(runtimeListTarballEntries(tarball));
   const tarBin = process.env.YOTTA_RUNTIME_TAR || 'tar';
-  const result = child_process.spawnSync(tarBin, ['-xzf', tarball, '-C', tempDir], { encoding: 'utf8' });
+  const relativeTarball = path.relative(tempDir, tarball).replace(/\\/g, '/');
+  const result = child_process.spawnSync(tarBin, ['-xzf', relativeTarball], { cwd: tempDir, encoding: 'utf8' });
   if (result.error) throw new Error('无法执行 tar: ' + result.error.message);
   if (result.status !== 0) throw new Error('解压 runtime tarball 失败: ' + String(result.stderr || result.stdout || '').trim());
   const packaged = path.join(tempDir, 'package');
@@ -1142,9 +1152,16 @@ function resolveAgentKeyLocation(owner, opts) {
   opts = opts || {};
   const explicitHome = String(opts.to || '').trim();
   const explicitFile = String(opts.agentKeyFile || '').trim();
+  const explicitPluginData = String(opts.pluginData || '').trim();
   if (explicitHome && explicitFile) {
     return { ok: false, error: '--to 与 --agent-key-file 不能同时使用。' };
   }
+  if (explicitPluginData && (explicitHome || explicitFile)) {
+    return { ok: false, error: '--plugin-data 不能与 --to / --agent-key-file 同时使用。' };
+  }
+  if (explicitPluginData) {
+    return { ok: true, file: agentKeyFilePath(explicitPluginData), source: 'option:--plugin-data' };
+  }
   if (explicitFile) {
     return { ok: true, file: path.resolve(explicitFile), source: 'option:--agent-key-file' };
   }
@@ -4557,11 +4574,27 @@ function keyClaimCore(root, owner, opts) {
     return { error: true, text: '写入宿主 key 文件失败：' + e.message + '。pending 文件保留，可重试。' };
   }
   removePendingAgentKey(root, owner);
+  let identityFile = '';
+  if (opts && opts.pluginData) {
+    try {
+      const dataDir = path.resolve(String(opts.pluginData));
+      fs.mkdirSync(dataDir, { recursive: true });
+      identityFile = path.join(dataDir, 'identity.json');
+      const tempIdentity = identityFile + '.tmp-' + process.pid + '-' + crypto.randomBytes(4).toString('hex');
+      fs.writeFileSync(tempIdentity, JSON.stringify({ agent_id: owner }, null, 2) + '\n', { encoding: 'utf8' });
+      try { fs.renameSync(tempIdentity, identityFile); }
+      catch (e) { fs.rmSync(identityFile, { force: true }); fs.renameSync(tempIdentity, identityFile); }
+    } catch (e) {
+      identityFile = '';
+    }
+  }
+  const identityLine = identityFile ? '\n插件身份文件: ' + identityFile : '';
   return {
     error: false,
     targetFile: targetFile,
+    identityFile: identityFile,
     source: location.source,
-    text: '已领取 ' + owner + ' 的 agent_key。\n目标文件: ' + targetFile + '\n发现规则: ' + location.source + '\npending 文件已删除。',
+    text: '已领取 ' + owner + ' 的 agent_key。\n目标文件: ' + targetFile + identityLine + '\n发现规则: ' + location.source + '\npending 文件已删除。',
   };
 }
 
@@ -4645,7 +4678,7 @@ function cmdKeyRevoke(id) {
 
 function cmdKeyClaim(id, opts) {
   const root = userRoot();
-  if (!id) { console.error('请指定 <id>：yotta-memory key claim <id> [--to <AI_HOME> | --agent-key-file <文件>]'); process.exit(2); }
+  if (!id) { console.error('请指定 <id>：yotta-memory key claim <id> [--to <AI_HOME> | --plugin-data <PLUGIN_DATA> | --agent-key-file <文件>]'); process.exit(2); }
   const r = keyClaimCore(root, id, opts);
   console.log(r.text);
   if (r.error) process.exit(2);
@@ -4653,7 +4686,7 @@ function cmdKeyClaim(id, opts) {
 
 function cmdKeyStatus(id, opts) {
   const root = userRoot();
-  if (!id) { console.error('请指定 <id>：yotta-memory key status <id> [--to <AI_HOME> | --agent-key-file <文件>]'); process.exit(2); }
+  if (!id) { console.error('请指定 <id>：yotta-memory key status <id> [--to <AI_HOME> | --plugin-data <PLUGIN_DATA> | --agent-key-file <文件>]'); process.exit(2); }
   const r = keyStatusCore(root, id, opts);
   console.log(r.text);
   if (r.error) process.exit(2);
@@ -4748,7 +4781,7 @@ function viewServerCore(root, port, host, opts) {
       return;
     }
     if (req.method === 'POST' && pathname === '/api/status') {
-      return json(200, { encrypted: isEncrypted(root), unlocked: !!session.umk, version: VERSION });
+      return json(200, { encrypted: isEncrypted(root), unlocked: !!session.umk, version: VERSION, rootId: memoryRootId(root) });
     }
     if (req.method === 'POST' && pathname === '/api/unlock') {
       return readBody(function (d) {
@@ -4909,14 +4942,23 @@ function probeViewStatus(host, port) {
       res.on('end', function () {
         try {
           const parsed = JSON.parse(data);
-          resolve(!!parsed.version && typeof parsed.unlocked === 'boolean');
+          if (!parsed.version || typeof parsed.unlocked !== 'boolean') {
+            resolve({ detected: false });
+            return;
+          }
+          resolve({
+            detected: true,
+            rootId: typeof parsed.rootId === 'string' ? parsed.rootId : '',
+            version: String(parsed.version),
+            unlocked: !!parsed.unlocked,
+          });
         } catch (e) {
-          resolve(false);
+          resolve({ detected: false });
         }
       });
     });
-    req.on('timeout', function () { req.destroy(); resolve(false); });
-    req.on('error', function () { resolve(false); });
+    req.on('timeout', function () { req.destroy(); resolve({ detected: false }); });
+    req.on('error', function () { resolve({ detected: false }); });
     req.end(body);
   });
 }
@@ -4932,11 +4974,18 @@ async function cmdView(opts) {
   const port = opts.port || 8788;
   const state = await probeViewPort(host, port);
   if (state === 'open') {
-    const own = await probeViewStatus(host, port);
-    if (own) {
+    const status = await probeViewStatus(host, port);
+    if (status.detected && status.rootId === memoryRootId(root)) {
       console.log('检测到已在运行的 yotta-memory view: http://' + host + ':' + port + '（无需重复启动）');
       return;
     }
+    if (status.detected) {
+      const reason = status.rootId
+        ? '该服务属于另一个 memory_home（rootId 不匹配）'
+        : '该服务是旧版 view，未提供 memory_home 指纹（rootId）';
+      console.error('检测到端口 ' + host + ':' + port + ' 上的 yotta-memory view 无法复用：' + reason + '。请关闭该进程，或使用 --port <其它端口>。');
+      process.exit(2);
+    }
     console.error('端口已被占用: ' + host + ':' + port + '。请关闭占用进程，或使用 --port <其它端口>。');
     process.exit(2);
   }
@@ -7173,10 +7222,10 @@ function usage() {
       ['token', '生成/列出/吊销访问 token（new --agent / list / revoke --agent）']
     ]],
     ['加密与安全', [
-      ['migrate', '把明文库迁移为密文（需主口令；空明文库同样可用；--password-stdin；--recovery-key-out <文件> 写恢复钥匙；首次迁移：echo 主口令 | yotta-memory migrate --password-stdin --recovery-key-out <文件>；迁移后授权二选一：推荐 yotta-memory view，等价 CLI 为 yotta-memory key bind <id>）'],
-      ['view', '启动用户查看平台（--port/--host；空加密库可用恢复钥匙校验主口令；已在运行则复用 URL）'],
+      ['migrate', '把明文库迁移为密文（需主口令；空明文库同样可用；--password-stdin 仅用于纯 ASCII 管道；--recovery-key-out <文件> 写恢复钥匙；首次迁移推荐交互式：yotta-memory migrate --recovery-key-out <文件>；非 ASCII 口令请交互输入，勿用 echo 中文管道；迁移后授权二选一：推荐 yotta-memory view，等价 CLI 为 yotta-memory key bind <id>）'],
+      ['view', '启动用户查看平台（--port/--host；复用前校验 memory_home 指纹，跨库或旧版无指纹服务会拒绝复用；空加密库可用恢复钥匙校验主口令）'],
       ['reset-password', '重设主口令（忘口令用恢复钥匙）'],
-      ['key', '管理 agent_key binding（list / bind <id> / rotate <id> / claim <id> [--to <AI_HOME> | --agent-key-file <文件>] / status <id> [--to <AI_HOME> | --agent-key-file <文件>] / revoke <id>；bind/rotate 需主口令或恢复钥匙）'],
+      ['key', '管理 agent_key binding（list / bind <id> / rotate <id> / claim <id> [--to <AI_HOME> | --plugin-data <PLUGIN_DATA> | --agent-key-file <文件>] / status <id> [--to <AI_HOME> | --plugin-data <PLUGIN_DATA> | --agent-key-file <文件>] / revoke <id>；bind/rotate 需主口令或恢复钥匙；--plugin-data 供 Agent Plugin 一条命令绑定插件身份）'],
       ['config', '查看/设置配置（get；set memory_home <目录> / backup_dir <目录> / embedding_cmd <命令> / embedding_timeout <毫秒> / maintain_* 阈值与半衰 / consolidate_* 参数）']
     ]],
     ['平台与服务', [
@@ -7206,7 +7255,7 @@ async function main() {
   if (!args.length) { usage(); return; }
   const opts = {};
   const positional = [];
-  const valueOpts = new Set(['--type', '--limit', '--days', '--out', '--owner', '--agent', '--agent-id', '--agent-key', '--agent-key-file', '--threshold', '--scope', '--host', '--port', '--dir', '--name', '--user', '--relationship', '--source', '--weight', '--budget', '--password', '--new-password', '--recovery-key', '--recovery-key-out', '--reason', '--merge', '--model', '--subject', '--embedding', '--focus', '--embedding-timeout', '--min-age', '--min-idle', '--max-utility', '--min-group', '--period', '--to', '--id', '--time', '--tools', '--mcp-config', '--skill-dir']);
+  const valueOpts = new Set(['--type', '--limit', '--days', '--out', '--owner', '--agent', '--agent-id', '--agent-key', '--agent-key-file', '--plugin-data', '--threshold', '--scope', '--host', '--port', '--dir', '--name', '--user', '--relationship', '--source', '--weight', '--budget', '--password', '--new-password', '--recovery-key', '--recovery-key-out', '--reason', '--merge', '--model', '--subject', '--embedding', '--focus', '--embedding-timeout', '--min-age', '--min-idle', '--max-utility', '--min-group', '--period', '--to', '--id', '--time', '--tools', '--mcp-config', '--skill-dir']);
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
     if (a === '--version' || a === '-v') { console.log(VERSION); return; }
@@ -7280,6 +7329,7 @@ async function main() {
       else if (a === '--min-group') opts.minGroup = parseInt(v, 10) || 0;
       else if (a === '--period') opts.period = parseInt(v, 10) || 0;
       else if (a === '--to') opts.to = v;
+      else if (a === '--plugin-data') opts.pluginData = v;
       else if (a === '--id') opts.id = v;
       else if (a === '--time') opts.time = v;
       else if (a === '--tools') opts.toolProfile = v;
@@ -7588,6 +7638,7 @@ module.exports = {
   backupDoctorCore: backupDoctorCore,
   backupRestoreCore: backupRestoreCore,
   backupDrillCore: backupDrillCore,
+  memoryRootId: memoryRootId,
   viewServerCore: viewServerCore,
 
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yottameta/yotta-memory",
-  "version": "0.16.5",
+  "version": "0.16.7",
   "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": [

package/references/faq.md

@@ -10,11 +10,11 @@
 
 **明文库第一次转加密**：
 
-```cmd
-echo 主口令 | yotta-memory migrate --password-stdin --recovery-key-out "%USERPROFILE%\yotta-memory-recovery.key"
+```powershell
+yotta-memory migrate --recovery-key-out "$env:USERPROFILE\yotta-memory-recovery.key"
 ```
 
-迁移后授权二选一（等价）：推荐 `yotta-memory view` 页面授权；高级用户可 `yotta-memory key bind <id>`。授权并 `key claim` 后，带 `--agent-key-file` 执行 `yotta-memory reindex` 重建每 owner 加密索引，再做 `recall` 验证。
+按提示输入主口令；非 ASCII 口令请交互输入，非 TTY 自动化可使用 `YOTTA_MEMORY_PASS`。不要使用 `echo 中文 | ...`，Windows 管道可能改变实际口令；若迁移后 `view` 报口令错误，用恢复钥匙 `reset-password` 重设。迁移后授权二选一（等价）：推荐 `yotta-memory view` 页面授权；高级用户可 `yotta-memory key bind <id>`。授权并 `key claim` 后，带 `--agent-key-file` 执行 `yotta-memory reindex` 重建每 owner 加密索引，再做 `recall` 验证。
 
 ## 2.1 非 TTY / GUI 宿主怎么初始化？
 不要依赖交互提示。用 `--password-stdin` 从管道读主口令（不进 argv），或用 `YOTTA_MEMORY_PASS`；恢复钥匙用 `--recovery-key-out <文件>` 写文件，避免 GUI 宿主吞掉 stdout。非 TTY 且未提供口令时会明确提示改用哪种方式，不会静默「已取消」。

package/skill-manifest.json

@@ -3,7 +3,7 @@
   "slug": "yotta-memory",
   "name": "元忆",
   "package": "@yottameta/yotta-memory",
-  "version": "0.16.5",
+  "version": "0.16.7",
   "trust": "yottameta",
   "install": {
     "idempotent": true