@yottameta/yotta-memory 0.16.1 → 0.16.3

package/CHANGELOG.md

@@ -1,3 +1,32 @@
+## v0.16.3 (2026-09-22)
+
+**迁移最短路径与授权引导修复**
+
+- `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 / 管道等口令传递方式和一个统一报错对照。
+- 修正迁移后的索引顺序：必须 **授权 → `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.json / SKILL.md frontmatter / skill-manifest.json / CHANGELOG / 引擎 VERSION = 0.16.3。
+
+## v0.16.2 (2026-09-21)
+
+**首启修复：空加密库可解锁、非 TTY 可自举、缺 key 降级未授权**
+
+- 修复空加密库 `view` 授权死锁：`/api/unlock` 在无 owner key 时用恢复钥匙校验主口令，空库可进入授权平台；无 owner 时页面提示先执行 `yotta-memory iam <id>`。
+- 非 TTY 环境不再静默「已取消」：`init --encrypt` / `migrate` / `reset-password` / `key bind` 给出可操作错误；新增 `--password-stdin`（管道读口令，不进 argv）。
+- `--agent-key-file` 指向不存在的文件时降级为未授权模式：公共 FACT 可读，私密操作 fail-closed 并提示 `key bind`；文件存在但为空 / 不可读仍报错。
+- 空加密库 `iam` 先登记身份、不因自我档案写失败而退出；授权后带 `--agent-key-file` 重新执行 `iam --force` 写入加密档案。
+- `migrate` 支持空明文库直接启用加密（创建 salt + recovery，不创建 owner key），迁移后提示 `key bind`。
+- 新增 `--recovery-key-out <文件>`：恢复钥匙写文件（`init` / `migrate`），不在 stdout 打印完整钥匙，适配 GUI 宿主 stdout 不可捕获场景。
+- `init --attach` / `init --no-encrypt` 明确输出当前模式（明文 / 加密）与下一步。
+- `isExistingStore` 不再把 `agents.json` 单独视为现有库；`key list` 合并 `keys/*.key.enc`，显示仅有钥、尚未写记忆的 owner。
+- `doctor` 对全新空库的缺失 index / agents 降为 info（不再误报）；只有私密数据、没有公共 FACT 的库不再误报公共索引缺失；输出 agent home 发现规则与 `YOTTA_MEMORY_AGENT_HOME` 提示。
+- `view` 启动前做端口健康检查：已在运行则复用并打印 URL；端口被占用给明确错误；`server.on('error')` 不再抛未处理异常。
+- 明文库 `view` 提示改写 stdout，GUI 宿主可感知。
+- 新增 `test/firstboot-0.16.2.test.js`（15 项首启回归）；全量 `npm test` 148/148 PASS。
+- 版本对齐：package.json / SKILL.md frontmatter / skill-manifest.json / CHANGELOG / 引擎 VERSION = 0.16.2。
+
 ## v0.16.1 (2026-09-19)
 
 维护性重发（无功能变更）：

package/README.md

@@ -23,6 +23,10 @@
 
 > 📖 The user-facing operations manual lives in [USER_GUIDE.md](USER_GUIDE.md).
 
+> 🆕 **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"`.
+> 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,6 +23,10 @@
 
 > 📖 面向用户的操作手册见 [USER_GUIDE.md](USER_GUIDE.md)。
 
+> 🆕 **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"`
+> 迁移后用 `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.1
+version: 0.16.3
 license: MIT
 ---
 
@@ -230,7 +230,8 @@ yotta-memory doctor --json
    - 输出 `memory_home: <目录>`（已显式设置）→ 直接用该位置。
    - 输出 `memory_home: (未设置，默认 ~/.yottamemory)` → 🔒 征得同意后引导设置：问用户用默认还是指定目录（项目级 `<repo>/.yottamemory`、记忆盘等），确认后 AI 执行 `yotta-memory config set memory_home <目录>`，回读 `config get` 验证。
 2. **已有记忆**：目标目录已存在 `facts/` 等子目录或 `index.json` → 直接 recall；全新目录 → 按「便携记忆盘模式 §0.3」初始化。
-3. **私密区已加密（存在 `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 不受影响）。
+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 不受影响）。
 
 **B. 确认本智能体唯一身份（强制，写私密记忆前必做）**：
 
@@ -264,11 +265,11 @@ yotta-memory doctor --json
 
 | 命令 | 作用 |
 |---|---|
-| `yotta-memory init [--project] [--dir <目录>] [--attach] [--encrypt|--no-encrypt]` | 初始化（**新建默认加密**：设主口令 + 抄下恢复钥匙；已有库必须用 `--attach`，默认拒绝覆盖；`--no-encrypt` 降级明文；老明文库用 `migrate`）|
-| `yotta-memory migrate` | 明文私密区 → 密文迁移（**由用户执行**；需主口令；迁移后打印恢复钥匙；不写明文授权缓存，授权由用户在 `view` 平台完成）|
-| `yotta-memory view [--port 8788] [--host 127.0.0.1]` | 用户查看平台（本机 Web：口令解锁浏览 / 搜索 / 导出全部 AI 记忆 + 授权 / 吊销 AI + 重设口令 + 显示恢复钥匙）|
+| `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 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` 输出 `[YTM_MIGRATION_REQUIRED]` 时提醒用户走 `view` 重新授权）|
+| `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` 重新授权）|
 | `yotta-memory remember <type> <subject> <statement> [--owner <id>] [--source <来源>] [--weight <0..>] [--verify] [--no-hint]` | 写入（同 subject+statement 自动更新；--owner 标注归属；--source 记录来源；--weight 重要性权重默认 1.0、去重取 max；--verify 写后回读校验；--no-hint 关闭类型启发式提示）|
 | `yotta-memory recall [关键词] [--type T] [--limit N] [--agent <id>] [--owner <id>] [--all] [--unsafe] [--explain] [--semantic] [--embedding <command>] [--embedding-timeout N]` | 检索（v0.8.0 默认语义检索：同义词 / 拼音全拼+首字母 / 字段加权 / 模糊匹配 + 效用分融合排序；v0.9.0 支持可选本地 embedding 插件，失败自动降级；`--explain` 显示命中理由与效用分项；`--semantic` 显式开启；读取分区过滤；越界读其它智能体私密默认拒绝，需 grant / identity=user / `--unsafe`；`--agent <其它>` 只作身份声明/展示，不授予跨读——读他人私密同样要授权；项目级优先）|
 | `yotta-memory profile [--owner <id>]` | 生成用户画像（聚合 `private/<owner>/` 原文，零推断，写 `profile.md`；跨 owner 默认拒绝）|
@@ -276,7 +277,7 @@ yotta-memory doctor --json
 | `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] [--runtime] [--mcp-config <文件>] [--skill-dir <目录>]` | 开工可靠性检查（v0.12.2；根目录 / 密钥库 / 索引 / 身份 / 最近备份；严重异常时锁定破坏性写入）；加 `--runtime` 检查 CLI / current / MCP 配置 / 运行中 server / 技能副本漂移 |
+| `yotta-memory doctor [--json] [--runtime] [--mcp-config <文件>] [--skill-dir <目录>]` | 开工可靠性检查（v0.12.2；根目录 / 密钥库 / 索引 / 身份 / 最近备份；严重异常时锁定破坏性写入）；全新空库的缺失 index / agents 降为 info；输出 agent home 发现规则与 `YOTTA_MEMORY_AGENT_HOME` 提示；加 `--runtime` 检查 CLI / current / MCP 配置 / 运行中 server / 技能副本漂移 |
 | `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>` | 导出 / 导入 |
@@ -293,6 +294,77 @@ yotta-memory doctor --json
 | `yotta-memory distill [--owner <id>] [--subject <主题>] [--model <cmd>] [--out <路径>]` | 心理日志蒸馏（v0.8.0 自我提升：统计摘要 / 主题画像 / 知识地图；启发式零依赖，`--model` 可选外部模型 stdin→stdout 提炼；私密产物入 `private/<owner>/distills/`，公共入 `facts/distills/`）|
 | `yotta-memory explain <文件|主题>` | 查看单条记忆效用分项与归档 / 遗忘状态判定（v0.8.0）|
 
+### 首启（非 TTY / GUI 宿主）
+
+- **非 TTY 初始化 / 迁移**：完整步骤见下一节《明文库转加密（第一次最短路径）》。
+- **恢复钥匙写文件**：`--recovery-key-out <文件>`（`init` / `migrate`）把恢复钥匙写入文件，适配 Windows GUI 宿主 stdout 不可捕获；不要把钥匙粘贴到对话。
+- **缺 `--agent-key-file`**：文件不存在时降级为未授权模式（公共 FACT 可读，私密操作 fail-closed 并提示 `key bind <id>`）；文件存在但为空 / 不可读仍报错。
+- **空加密库授权**：`yotta-memory view` 在无 owner key 时可用恢复钥匙校验主口令进入平台；无 owner 时先 `yotta-memory iam <id>`，再回页面授权。
+- **view 端口**：启动前做健康检查；已在运行则打印 URL 复用，端口被占用给明确提示，不再抛未处理的 `EADDRINUSE`。
+
+### 明文库转加密（第一次最短路径）
+
+> 适用于 `yotta-memory 0.16.2+`。迁移前先完整备份。
+
+1. **迁移**：
+
+```cmd
+echo 主口令 | yotta-memory migrate --password-stdin --recovery-key-out "%USERPROFILE%\yotta-memory-recovery.key"
+```
+
+口令传递方式（同一迁移命令，按终端选择一种；不要把口令写进 `--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="` |
+
+常见报错：`当前为非交互环境` = 没有 stdin 也没有 `YOTTA_MEMORY_PASS`；`'"..."' is not recognized` = 在 `cmd.exe` 里用了 PowerShell 的管道写法。口令含非 ASCII 时，PowerShell 可先设置 `$OutputEncoding=[Text.Encoding]::UTF8`。
+
+恢复钥匙文件必须离线保存，不要和记忆库或备份放在一起。
+
+2. **授权 AI（二选一，完全等价）**：
+
+推荐：网页授权
+
+```cmd
+yotta-memory view
+```
+
+浏览器输入主口令，点击 `授权 <id>`，保存只显示一次的 `agent_key`。
+
+高级：CLI 等价方式
+
+```cmd
+yotta-memory key bind <id>
+```
+
+两种方式都会写 binding + pending，效果相同。
+
+3. **AI 领取 key**：
+
+```cmd
+yotta-memory key status <id>
+yotta-memory key claim <id> --to "<AI_HOME>"
+```
+
+默认写入 `<AI_HOME>/.yotta-memory-agent-key`。
+
+4. **重建加密索引并验证**：
+
+```cmd
+yotta-memory reindex --agent <id> --agent-key-file "<AI_HOME>/.yotta-memory-agent-key"
+yotta-memory recall <关键词> --agent <id> --agent-key-file "<AI_HOME>/.yotta-memory-agent-key"
+```
+
+必须在授权并领取 agent_key 后执行 `reindex`。`migrate` 在没有 agent_key 时无法建立每 owner 加密索引；跳过这步会让私密 `recall` 看起来像“无匹配记忆”。
+
+5. **MCP 自检**：宿主 MCP 配置必须带 `--agent-key-file <AI_HOME>/.yotta-memory-agent-key`；只有 `--agent-id` 时，加密库的私密 MCP 调用会报缺少 agent_key，而 CLI 可能仍正常。补参后重启 MCP / 会话并回读验证。
+
+> 加密范围：`private/` 下的 PREF / BOUND / COMMIT 与画像索引；公共 `facts/` 仍为明文。
+
 ## 存储格式（摘要）
 
 目录结构（v0.5.0 起，私密记忆按 owner 物理分目录）：
@@ -331,8 +403,8 @@ yotta-memory doctor --json
 
 ### 流程
 1. **建加密库**：`yotta-memory init --encrypt`（新建默认加密）→ 设主口令 → 抄下恢复钥匙离线保存。
-2. **老库迁移**：由用户执行 `yotta-memory migrate`（需主口令）→ 明文私密逐文件加密后删除明文 → 打印恢复钥匙。迁移不写明文授权缓存；每个 AI 的重新授权由用户自己在 `yotta-memory view` 平台完成并自行备份弹窗 `agent_key`；AI 随后用 `key status` / `key claim` 领取（AI 只提醒授权，不代执行 `migrate` / `key bind`）。
-3. **AI 读写自己的私密（v0.16.0）**：用户侧完成一次 `yotta-memory view` 授权（或用户自行执行 `yotta-memory key bind <id>`），生成只展示一次的 `agent_key`，并写入 `keys/bindings/<id>.key.agent` 与临时 `keys/pending/<id>.key`。AI 新会话用 `key status` / `key claim` 将 pending 落到 `<AI_HOME>/.yotta-memory-agent-key`，之后 CLI 用 `--agent <id> --agent-key-file <宿主key文件>`；stdio MCP 用 `--agent-id <id> --agent-key-file <宿主key文件>`；HTTP MCP 用 `X-Agent-Id` + `X-Agent-Key` 请求头。owner ID 单独存在时不能解密私密；legacy `keys/cache/<id>.key` 不再加载。
+2. **老库迁移 / 重新授权**：完整步骤见《明文库转加密（第一次最短路径）》。迁移与授权由用户执行，AI 只提醒，不代执行 `migrate` / `key bind`。
+3. **AI 读写自己的私密（v0.16.0）**：授权入口为 `yotta-memory view` 或等价的 `yotta-memory key bind <id>`；生成只展示一次的 `agent_key`，并写入 `keys/bindings/<id>.key.agent` 与临时 `keys/pending/<id>.key`。AI 新会话用 `key status` / `key claim` 将 pending 落到 `<AI_HOME>/.yotta-memory-agent-key`，之后 CLI 用 `--agent <id> --agent-key-file <宿主key文件>`；stdio MCP 用 `--agent-id <id> --agent-key-file <宿主key文件>`；HTTP MCP 用 `X-Agent-Id` + `X-Agent-Key` 请求头。owner ID 单独存在时不能解密私密；legacy `keys/cache/<id>.key` 不再加载。
 4. **用户查看全部 AI 记忆**：`yotta-memory view` → 输口令 → 浏览 / 搜索 / 导出全部（含各 AI 私密明文，仅用户可见）。口令只在本地内存派生，不落盘、不发远端；默认仅 127.0.0.1，远程需 `--host` 显式开启。
 5. **口令管理**：`yotta-memory reset-password`（当前口令或恢复钥匙）；`key revoke <id>` 立即吊销某 AI 的 agent binding（该 AI 随即失去解密能力）。`view` 平台的「授权」只对未绑定 agent 生成新 key；已绑定的 agent 需先「吊销」再授权，避免误打断在用的 agent_key。
 

package/USER_GUIDE.md

@@ -127,11 +127,47 @@ statement: 本周完成发布
 **启用与迁移**
 
 - **新库**：`yotta-memory init`（新建默认加密）→ 输入主口令两次 → **抄下打印的恢复钥匙**（44 位 base64，离线保存；忘口令时用它重设）。不要加密用 `--no-encrypt`。
-- **老明文库升级**：`yotta-memory migrate` → 输入主口令 → 私密文件逐个加密、明文删除 → 抄下恢复钥匙。
+- **老明文库升级 / 非 TTY**：见下方《明文库转加密（第一次最短路径）》，只保留一套步骤。
+- **缺 `--agent-key-file`**：文件不存在时降级为未授权模式——公共 FACT 可读，私密操作 fail-closed 并提示 `key bind <id>`；文件存在但为空 / 不可读仍报错。
+
+**明文库转加密（第一次最短路径）**
+
+> 适用于 `yotta-memory 0.16.2+`。迁移前先完整备份。
+
+1. 迁移：
+
+```cmd
+echo 主口令 | yotta-memory migrate --password-stdin --recovery-key-out "%USERPROFILE%\yotta-memory-recovery.key"
+```
+
+非 TTY 也可以使用 `YOTTA_MEMORY_PASS`（PowerShell / cmd 语法不同）；交互终端直接运行 `yotta-memory migrate --recovery-key-out "<钥匙文件>"` 并按提示输入口令。不要把口令写进 `--password` 参数。
+
+2. 授权 AI（二选一，等价）：
+
+- 推荐：`yotta-memory view` → 浏览器输入主口令 → 点「授权 <id>」→ 保存一次性 `agent_key`。
+- 高级：`yotta-memory key bind <id>`。
+
+3. AI 领取 key：
+
+```cmd
+yotta-memory key status <id>
+yotta-memory key claim <id> --to "<AI_HOME>"
+```
+
+4. 授权并领取 key 后，重建加密索引：
+
+```cmd
+yotta-memory reindex --agent <id> --agent-key-file "<AI_HOME>/.yotta-memory-agent-key"
+yotta-memory recall <关键词> --agent <id> --agent-key-file "<AI_HOME>/.yotta-memory-agent-key"
+```
+
+顺序必须是：迁移 → `view` / `key bind` → `key claim` → `reindex`。没有 agent_key 时 `reindex` 无法建立每 owner 加密索引。
+
+5. MCP 配置必须包含 `--agent-key-file <AI_HOME>/.yotta-memory-agent-key`；只有 `--agent-id` 时，加密库的私密 MCP 会报缺少 agent_key。
 
 **用户查看平台（看所有 AI 的记忆）**
 
-`yotta-memory view` → 浏览器打开 http://127.0.0.1:8788 → 输入主口令解锁 → 浏览 / 搜索 / 导出全部记忆（含各 AI 私密）；也可在此**授权 / 吊销**某 AI 读取其私密、**重设口令**、**查看恢复钥匙**。点击「授权」后会弹窗展示只显示一次的 `agent_key`，请立即单独保存；引擎同时写临时 `keys/pending/<id>.key`，该 AI 新会话用 `key claim` 领取到自己的宿主目录，领取成功后 pending 删除。已绑定的 agent 需先「吊销」再授权，旧 key 随即校验失败。口令只在本地内存派生，不落盘、不发远端；默认仅本机，远程需 `--host` 显式开启。
+`yotta-memory view` → 浏览器打开 http://127.0.0.1:8788 → 输入主口令解锁 → 浏览 / 搜索 / 导出全部记忆（含各 AI 私密）；也可在此**授权 / 吊销**某 AI 读取其私密、**重设口令**、**查看恢复钥匙**。空加密库没有 owner key 时，`view` 会用恢复钥匙校验主口令进入平台；此时先在终端执行 `yotta-memory iam <id>`，页面才会出现可授权的 owner。`view` 启动前会做端口健康检查：已在运行则直接打印 URL 复用；端口被占用会给出明确提示。点击「授权」后会弹窗展示只显示一次的 `agent_key`，请立即单独保存；引擎同时写临时 `keys/pending/<id>.key`，该 AI 新会话用 `key claim` 领取到自己的宿主目录，领取成功后 pending 删除。已绑定的 agent 需先「吊销」再授权，旧 key 随即校验失败。口令只在本地内存派生，不落盘、不发远端；默认仅本机，远程需 `--host` 显式开启。
 
 **AI 接入加密库**
 

package/assets/view.html

@@ -53,7 +53,7 @@ async function api(p,b){try{const r=await fetch(p,{method:'POST',headers:{'Conte
 async function boot(){const s=await api('/api/status');document.getElementById('ver').textContent='v'+(s.version||'');if(s.unlocked){showApp();}}
 function showApp(){document.getElementById('lock').style.display='none';document.getElementById('app').style.display='block';loadOwners();load();}
 async function unlock(){const d=await api('/api/unlock',{password:document.getElementById('pw').value});if(d.error){document.getElementById('lockerr').textContent=d.error;return;}showApp();}
-async function loadOwners(){const d=await api('/api/owners');const box=document.getElementById('owners');box.innerHTML='';if(!d.owners||!d.owners.length){box.innerHTML='（无 owner）';return;}
+async 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;}
   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);}
   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();});};});
   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();});};});

package/bin/yotta-memory.js

@@ -21,12 +21,13 @@ const path = require('path');
 const os = require('os');
 const crypto = require('crypto');
 const http = require('http');
+const net = require('net');
 const child_process = require('child_process');
 const { AsyncLocalStorage } = require('async_hooks');
 
-const VERSION = '0.16.1';
+const VERSION = '0.16.3';
 // @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='（无 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";
+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
 // MCP 协议（2026-07-28 无状态 + 2025-11-25 legacy 握手，dual-era）
 const MCP_PROTOCOL_MODERN = '2026-07-28';
@@ -618,6 +619,15 @@ function resolveIdentity(opts) {
   if (keyFile) {
     let fileKey = '';
     try { fileKey = fs.readFileSync(path.resolve(keyFile), 'utf8').trim(); } catch (e) {
+      if (e && e.code === 'ENOENT') {
+        return {
+          id: explicit,
+          agentKey: '',
+          source: 'missing-key-file',
+          warning: '未找到 agent-key 文件: ' + keyFile + '；已降级为未授权模式（公共 FACT 可读，私密操作需要显式授权）。',
+          error: '',
+        };
+      }
       return { id: '', agentKey: '', source: 'invalid-key-file', error: '无法读取 agent-key 文件: ' + keyFile };
     }
     if (!fileKey) return { id: '', agentKey: '', source: 'invalid-key-file', error: 'agent-key 文件为空: ' + keyFile };
@@ -1872,7 +1882,7 @@ function verifyWrittenReadable(root, rel, subj, agent) {
 
 // ---- 命令 core（CLI 与 MCP 共用；返回 { error, exitCode, text }，不 process.exit）----
 function isExistingStore(root) {
-  return ['facts', 'private', 'keys', 'agents.json', 'index.json'].some(function (name) {
+  return ['facts', 'private', 'keys', 'index.json'].some(function (name) {
     return fs.existsSync(path.join(root, name));
   });
 }
@@ -1881,7 +1891,10 @@ function initCore(opts) {
   const root = opts.dir ? path.resolve(String(opts.dir)) : (opts.project ? projectRoot() : userRoot());
   const existing = isExistingStore(root);
   if (existing && opts.attach) {
-    return { error: false, text: '已接入现有记忆库: ' + root };
+    const mode = isEncrypted(root) ? '加密' : '明文';
+    let text = '已接入现有记忆库（当前模式：' + mode + '）: ' + root;
+    if (!isEncrypted(root)) text += '\n提示：当前为明文模式，私密内容未加密；如需启用加密，请运行 yotta-memory migrate（空明文库同样可用）。';
+    return { error: false, text: text };
   }
   if (existing && opts.force) {
     return { error: true, text: '拒绝: --force 不能覆盖现有记忆库；已有记忆库的强制重建必须由完整备份与显式确认保护，当前版本不提供覆盖初始化路径。如只是接入，请使用 init --attach。' };
@@ -1896,11 +1909,17 @@ function initCore(opts) {
     if (isEncrypted(root)) return { error: false, text: '已初始化记忆库（已启用加密）: ' + root };
     if (hasPlaintextPrivate(root)) return { error: true, text: '检测到明文私密区，请先 yotta-memory migrate 迁移到密文；新建空库可直接 init --encrypt。' };
     const password = String(opts.password || process.env.YOTTA_MEMORY_PASS || '');
-    if (!password) return { error: true, text: '启用加密需要主口令：交互输入，或 YOTTA_MEMORY_PASS 环境变量（自动化）。' };
+    if (!password) return { error: true, text: '启用加密需要主口令：交互输入、--password-stdin（推荐）或 YOTTA_MEMORY_PASS 环境变量（自动化）。' };
     const r = initEncryptionCore(root, password, null);
+    if (opts.recoveryKeyOut) {
+      const outPath = path.resolve(String(opts.recoveryKeyOut));
+      fs.mkdirSync(path.dirname(outPath), { recursive: true });
+      fs.writeFileSync(outPath, r.rk.toString('base64') + '\n', { encoding: 'utf8', mode: 0o600 });
+      return { error: false, text: '已初始化加密记忆库: ' + root + '\n[恢复钥匙] 已写入文件: ' + outPath + '（务必离线保存，仅此一次，泄露=可解全部私密；不要把钥匙粘贴到对话中）' };
+    }
     return { error: false, text: '已初始化加密记忆库: ' + root + '\n[恢复钥匙]（务必离线保存，仅此一次，泄露=可解全部私密）: ' + r.rk.toString('base64') };
   }
-  return { error: false, text: '已初始化记忆库: ' + root + (isEncrypted(root) ? '（已启用加密）' : '（明文；建议 init --encrypt 或 migrate 启用加密）') };
+  return { error: false, text: '已初始化记忆库: ' + root + (isEncrypted(root) ? '（已启用加密）' : '（明文；私密内容未加密，如需启用加密请运行 migrate）') };
 }
 
 function backupDestination(opts) {
@@ -2900,6 +2919,34 @@ function runtimeDoctorCore(opts) {
     text: lines.join('\n'),
   };
 }
+function storeHasMemoryData(root) {
+  const factsDir = path.join(root, PUBLIC_DIR);
+  if (fs.existsSync(factsDir)) {
+    try {
+      if (fs.readdirSync(factsDir).some(function (f) { return /\.md(\.enc)?$/.test(f); })) return true;
+    } catch (e) {}
+  }
+  if (hasPlaintextPrivate(root)) return true;
+  for (const owner of collectOwners(root)) {
+    for (const t of PRIVATE_LEAF) {
+      const dir = path.join(root, PRIVATE_DIR, owner, t);
+      if (!fs.existsSync(dir)) continue;
+      try {
+        if (fs.readdirSync(dir).some(function (f) { return f.endsWith(ENC_SUFFIX); })) return true;
+      } catch (e) {}
+    }
+  }
+  return false;
+}
+function storeHasPublicFacts(root) {
+  const factsDir = path.join(root, PUBLIC_DIR);
+  if (!fs.existsSync(factsDir)) return false;
+  try {
+    return fs.readdirSync(factsDir).some(function (f) { return /\.md(\.enc)?$/.test(f); });
+  } catch (e) {
+    return false;
+  }
+}
 // 开工可靠性检查：只读检查根目录、密钥库、索引、身份登记与最近备份。
 function doctorCore(opts) {
   opts = opts || {};
@@ -2909,6 +2956,8 @@ function doctorCore(opts) {
   const warnings = [];
   const critical = [];
   const exists = isExistingStore(root);
+  const hasData = storeHasMemoryData(root);
+  const hasPublicFacts = storeHasPublicFacts(root);
   checks.root = { ok: exists, path: root };
   if (!exists) critical.push('记忆库不存在或基本结构缺失: ' + root);
 
@@ -2930,7 +2979,8 @@ function doctorCore(opts) {
   const idxFile = indexPath(root);
   if (!fs.existsSync(idxFile)) {
     checks.index = { exists: false, valid: false };
-    warnings.push('公共索引缺失；可运行 yotta-memory reindex 重建。');
+    if (hasPublicFacts) warnings.push('公共索引缺失；可运行 yotta-memory reindex 重建。');
+    else checks.index.fresh = true;
   } else if (!loadIndex(root)) {
     checks.index = { exists: true, valid: false };
     warnings.push('公共索引无法解析或版本过旧；可运行 yotta-memory reindex 重建。');
@@ -2940,7 +2990,8 @@ function doctorCore(opts) {
 
   if (!fs.existsSync(agentsPath(root))) {
     checks.agents = { exists: false, valid: false };
-    warnings.push('agents.json 缺失；智能体身份登记不可用。');
+    if (hasData) warnings.push('agents.json 缺失；智能体身份登记不可用。');
+    else checks.agents.fresh = true;
   } else {
     try {
       JSON.parse(fs.readFileSync(agentsPath(root), 'utf8'));
@@ -3011,12 +3062,14 @@ function doctorCore(opts) {
   }
 
   const level = critical.length ? 'critical' : (warnings.length ? 'warning' : 'ok');
+  const agentHomeEnv = String(process.env.YOTTA_MEMORY_AGENT_HOME || '').trim();
   const lines = [
     '# yotta-memory doctor（开工可靠性检查）',
     '',
     '- 结果: ' + (level === 'critical' ? '严重' : (level === 'warning' ? '警告' : '正常')),
     '- 记忆库: ' + root,
     '- 加密: ' + (encrypted ? '是' : '否'),
+    '- agent home: ' + (agentHomeEnv || '(未设置 YOTTA_MEMORY_AGENT_HOME，按宿主默认检测)'),
     '- 备份目录: ' + (configuredDir || (cfg.backup_setup_choice === 'manual' ? '手动模式' : '(未配置)')),
   ];
   for (const message of critical) lines.push('- [严重] ' + message);
@@ -4209,12 +4262,42 @@ function promptPassword(promptText) {
   });
 }
 
+function readPasswordFromStdin() {
+  try {
+    const text = fs.readFileSync(0, 'utf8');
+    return String(text || '').replace(/\r?\n$/, '');
+  } catch (e) {
+    return '';
+  }
+}
+
+async function resolvePasswordInput(opts, promptText, options) {
+  opts = opts || {};
+  options = options || {};
+  const direct = options.field === 'new' ? String(opts.newPassword || '') : String(opts.password || '');
+  if (direct) return { password: direct, source: 'option', error: '' };
+  if (opts.passwordStdin) {
+    const password = readPasswordFromStdin();
+    if (!password) {
+      return { password: '', source: 'stdin', error: '--password-stdin 没有读到内容；请通过管道传入主口令。' };
+    }
+    return { password: password, source: 'stdin', error: '' };
+  }
+  const envPass = String(process.env.YOTTA_MEMORY_PASS || '');
+  if (envPass) return { password: envPass, source: 'env', error: '' };
+  if (!process.stdin.isTTY) {
+    return { password: '', source: 'non-tty', error: '当前为非交互环境，无法读取主口令。请使用 --password-stdin（推荐，管道传入）或设置 YOTTA_MEMORY_PASS；不要把口令直接写在命令行参数里。' };
+  }
+  const password = await promptPassword(promptText);
+  if (!password) return { password: '', source: 'prompt', error: '已取消。' };
+  return { password: password, source: 'prompt', error: '' };
+}
+
 function migrateCore(root, password, recoveryKeyIn) {
   // 第三个参数历史上是 recovery key；兼容旧调用，同时支持 { agent, recoveryKey } 选项对象。
   const opts = recoveryKeyIn && typeof recoveryKeyIn === 'object' ? recoveryKeyIn : {};
   if (!fs.existsSync(root)) return { error: true, text: '记忆库不存在，请先 yotta-memory init。' };
   if (isEncrypted(root)) return { error: true, text: '记忆库已启用加密（keys/ 存在），无需迁移。' };
-  if (!hasPlaintextPrivate(root)) return { error: false, text: '无私密明文可迁移（private/ 下无 .md 文件）；如需新建加密库请 init --encrypt。' };
   const salt = crypto.randomBytes(16);
   ensureKeysDir(root);
   fs.writeFileSync(encSaltPath(root), salt);
@@ -4247,23 +4330,36 @@ function migrateCore(root, password, recoveryKeyIn) {
     }
   }
   buildIndex(root);
-  let tail = '已迁移 ' + moved + ' 个私密文件（' + owners.length + ' 个 owner）到密文。';
-  tail += '\n[恢复钥匙]（务必离线保存，仅此一次，泄露=可解全部私密）: ' + rk.toString('base64');
-  tail += '\n迁移不会写明文 owner key cache；请为每个 agent 执行一次 yotta-memory key bind <id>，再注入 agent_key。';
-  if (self && owners.indexOf(self) !== -1) tail += '\n你的身份：' + self + '，请先执行 yotta-memory key bind ' + self + '。';
+  let tail = moved > 0
+    ? ('已迁移 ' + moved + ' 个私密文件（' + owners.length + ' 个 owner）到密文。')
+    : '私密区为空；已为明文库启用加密（未迁移文件、未创建 owner key）。';
+  if (opts.recoveryKeyOut) {
+    const outPath = path.resolve(String(opts.recoveryKeyOut));
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, rk.toString('base64') + '\n', { encoding: 'utf8', mode: 0o600 });
+    tail += '\n[恢复钥匙] 已写入文件: ' + outPath + '（务必离线保存，仅此一次，泄露=可解全部私密；不要把钥匙粘贴到对话中）';
+  } else {
+    tail += '\n[恢复钥匙]（务必离线保存，仅此一次，泄露=可解全部私密）: ' + rk.toString('base64');
+  }
+  tail += '\n迁移不会写明文 owner key cache。下一步为每个 agent 做一次授权，二选一（等价）：';
+  tail += '\n  推荐：yotta-memory view → 浏览器解锁 → 授权 <id> → 保存一次性 agent_key';
+  tail += '\n  高级：yotta-memory key bind <id>';
+  tail += '\n授权后 AI 执行：yotta-memory key status <id> → yotta-memory key claim <id> → <AI_HOME>/.yotta-memory-agent-key';
+  tail += '\n然后带 agent-key-file 重建加密索引：yotta-memory reindex --agent <id> --agent-key-file <AI_HOME>/.yotta-memory-agent-key';
+  if (self && owners.indexOf(self) !== -1) tail += '\n你的身份：' + self + '。推荐直接在 yotta-memory view 页面授权它。';
   return { error: false, text: tail };
 }
 
 async function cmdMigrate(opts) {
   const root = userRoot();
   if (isEncrypted(root)) { console.error('记忆库已启用加密，无需迁移。'); process.exit(2); }
-  if (!hasPlaintextPrivate(root)) { console.error('无私密明文可迁移。'); process.exit(2); }
   let password = opts.password || process.env.YOTTA_MEMORY_PASS || '';
   if (!password) {
-    password = await promptPassword('主口令（迁移后私密区加密，勿忘；忘口令可用恢复钥匙重设）: ') || '';
-    if (!password) { console.error('已取消。'); process.exit(2); }
+    const got = await resolvePasswordInput(opts, '主口令（迁移后私密区加密，勿忘；忘口令可用恢复钥匙重设）: ');
+    if (got.error) { console.error(got.error); process.exit(2); }
+    password = got.password;
   }
-  const r = migrateCore(root, password, { agent: opts.agent, recoveryKey: null });
+  const r = migrateCore(root, password, { agent: opts.agent, recoveryKey: null, recoveryKeyOut: opts.recoveryKeyOut });
   console.log(r.text);
   if (r.error) process.exit(2);
 }
@@ -4315,14 +4411,18 @@ async function cmdResetPassword(opts) {
   let rk = opts.recoveryKey || '';
   let np = opts.newPassword || process.env.YOTTA_MEMORY_PASS || '';
   if (!rk && !cur) {
-    cur = await promptPassword('当前口令（或 --recovery-key 用恢复钥匙）: ') || '';
-    if (!cur) { console.error('已取消。'); process.exit(2); }
+    const got = await resolvePasswordInput(opts, '当前口令（或 --recovery-key 用恢复钥匙）: ');
+    if (got.error) { console.error(got.error); process.exit(2); }
+    cur = got.password;
   }
   if (!np) {
-    np = await promptPassword('新口令: ') || '';
-    if (!np) { console.error('已取消。'); process.exit(2); }
-    const np2 = await promptPassword('再次输入确认: ') || '';
-    if (np2 !== np) { console.error('两次输入不一致。'); process.exit(2); }
+    const got = await resolvePasswordInput(opts, '新口令: ', { field: 'new' });
+    if (got.error) { console.error(got.error); process.exit(2); }
+    np = got.password;
+    if (got.source === 'prompt') {
+      const np2 = await promptPassword('再次输入确认: ') || '';
+      if (np2 !== np) { console.error('两次输入不一致。'); process.exit(2); }
+    }
   }
   const r = resetPasswordCore(root, { password: cur, recoveryKey: rk, newPassword: np });
   console.log(r.text);
@@ -4458,7 +4558,7 @@ function keyStatusCore(root, owner, opts) {
 function keyListCore(root) {
   root = root || userRoot();
   if (!isEncrypted(root)) return { text: '记忆库未启用加密。' };
-  const owners = collectOwners(root);
+  const owners = keyOwners(root);
   const bound = owners.filter(function (o) { return fs.existsSync(encAgentBindingPath(root, o)); });
   const pending = owners.filter(function (o) { return fs.existsSync(encPendingPath(root, o)); });
   const legacy = owners.filter(function (o) { return fs.existsSync(encCachePath(root, o)); });
@@ -4486,8 +4586,9 @@ async function cmdKeyBind(id, opts) {
   if (!id) { console.error('请指定 <id>：yotta-memory key bind <id>'); process.exit(2); }
   let password = opts.password || process.env.YOTTA_MEMORY_PASS || '';
   if (!password && !opts.recoveryKey) {
-    password = await promptPassword('主口令: ') || '';
-    if (!password) { console.error('已取消。'); process.exit(2); }
+    const got = await resolvePasswordInput(opts, '主口令: ');
+    if (got.error) { console.error(got.error); process.exit(2); }
+    password = got.password;
   }
   const r = keyBindCore(root, id, { password: password, recoveryKey: opts.recoveryKey });
   console.log(r.text);
@@ -4571,7 +4672,8 @@ function viewOriginAllowed(req) {
   const requestHost = String(req.headers.host || '').trim().toLowerCase();
   return !!requestHost && originHost === requestHost;
 }
-function viewServerCore(root, port, host) {
+function viewServerCore(root, port, host, opts) {
+  opts = opts || {};
   let session = { umk: null, ownerKeys: {} };
   const server = http.createServer(function (req, res) {
     if (!viewHostAllowed(req, host) || !viewOriginAllowed(req)) {
@@ -4625,9 +4727,16 @@ function viewServerCore(root, port, host) {
         for (const o of owners) {
           try { ownerKeys[o] = unwrapOwnerKey(root, o, umk); verified = true; } catch (e) {}
         }
-        if (!verified) return json(401, { error: '口令错误。' });
+        if (!verified && owners.length === 0) {
+          try { unwrapRecoveryEnc(root, umk); verified = true; } catch (e) {}
+        }
+        if (!verified) return json(401, { error: owners.length === 0 ? '口令错误；空加密库已用恢复钥匙校验失败。' : '口令错误。' });
         session = { umk: umk, ownerKeys: ownerKeys };
-        json(200, { ok: true, owners: Object.keys(ownerKeys) });
+        json(200, {
+          ok: true,
+          owners: Object.keys(ownerKeys),
+          hint: owners.length === 0 ? '当前没有 owner。请先在终端执行 yotta-memory iam <id>，再回到本页授权。' : '',
+        });
       });
     }
     if (req.method === 'POST' && pathname === '/api/owners') {
@@ -4635,7 +4744,10 @@ function viewServerCore(root, port, host) {
       const agents = loadAgents(root).agents || {};
       const owners = keyOwners(root);
       const all = Array.from(new Set(owners.concat(Object.keys(agents))));
-      return json(200, { owners: all.map(function (o) { return { owner: o, registered: !!agents[o], authorized: fs.existsSync(encAgentBindingPath(root, o)) }; }) });
+      return json(200, {
+        owners: all.map(function (o) { return { owner: o, registered: !!agents[o], authorized: fs.existsSync(encAgentBindingPath(root, o)) }; }),
+        hint: all.length ? '' : '当前没有 owner。请先在终端执行 yotta-memory iam <id>，再回到本页授权。',
+      });
     }
     if (req.method === 'POST' && pathname === '/api/entries') {
       if (!session.umk) return json(401, { error: '请先解锁。' });
@@ -4712,6 +4824,14 @@ function viewServerCore(root, port, host) {
     res.writeHead(404, { 'Content-Type': 'text/plain' });
     res.end('not found');
   });
+  server.on('error', function (e) {
+    const message = 'yotta-memory view 启动失败: ' + (e && e.message ? e.message : String(e)) + '；请检查端口是否被占用，或使用 --port <其它端口>。';
+    if (typeof opts.onError === 'function') {
+      opts.onError(e, message);
+      return;
+    }
+    console.error(message);
+  });
   server.listen(port, host, function () {
     console.log('yotta-memory 用户查看平台已启动（v' + VERSION + '）');
     console.log('URL: http://' + host + ':' + port + '（默认仅本机 127.0.0.1；远程需 --host 显式开启）');
@@ -4722,16 +4842,75 @@ function viewServerCore(root, port, host) {
   return server;
 }
 
-function cmdView(opts) {
+function probeViewPort(host, port) {
+  return new Promise(function (resolve) {
+    const socket = net.connect({ host: host, port: port });
+    let done = false;
+    function finish(state) {
+      if (done) return;
+      done = true;
+      try { socket.destroy(); } catch (e) {}
+      resolve(state);
+    }
+    socket.setTimeout(800, function () { finish('timeout'); });
+    socket.once('connect', function () { finish('open'); });
+    socket.once('error', function (e) { finish(e && e.code === 'ECONNREFUSED' ? 'closed' : 'error'); });
+  });
+}
+
+function probeViewStatus(host, port) {
+  return new Promise(function (resolve) {
+    const body = JSON.stringify({});
+    const req = http.request({
+      host: host,
+      port: port,
+      path: '/api/status',
+      method: 'POST',
+      timeout: 800,
+      headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) },
+    }, function (res) {
+      let data = '';
+      res.on('data', function (chunk) { data += chunk; });
+      res.on('end', function () {
+        try {
+          const parsed = JSON.parse(data);
+          resolve(!!parsed.version && typeof parsed.unlocked === 'boolean');
+        } catch (e) {
+          resolve(false);
+        }
+      });
+    });
+    req.on('timeout', function () { req.destroy(); resolve(false); });
+    req.on('error', function () { resolve(false); });
+    req.end(body);
+  });
+}
+
+async function cmdView(opts) {
   const root = userRoot();
   ensureInit(root);
   if (!isEncrypted(root)) {
-    console.error('记忆库未启用加密（无 keys/）。yotta-memory view 是加密库的用户查看平台；请先 init --encrypt 或 migrate。');
+    console.log('记忆库未启用加密（无 keys/）。yotta-memory view 是加密库的用户查看平台；请先 init --encrypt 或 migrate。');
     process.exit(2);
   }
   const host = opts.host || '127.0.0.1';
   const port = opts.port || 8788;
-  viewServerCore(root, port, host);
+  const state = await probeViewPort(host, port);
+  if (state === 'open') {
+    const own = await probeViewStatus(host, port);
+    if (own) {
+      console.log('检测到已在运行的 yotta-memory view: http://' + host + ':' + port + '（无需重复启动）');
+      return;
+    }
+    console.error('端口已被占用: ' + host + ':' + port + '。请关闭占用进程，或使用 --port <其它端口>。');
+    process.exit(2);
+  }
+  viewServerCore(root, port, host, {
+    onError: function (e, message) {
+      console.error(message);
+      process.exit(2);
+    },
+  });
 }
 
 function viewHtml() {
@@ -4750,12 +4929,14 @@ async function cmdInit(opts) {
   const fresh = !isExistingStore(root);
   const wantEncrypt = opts.encrypt || (!opts.noEncrypt && fresh);
   let o = Object.assign({}, opts);
-  if (wantEncrypt && !o.password && !process.env.YOTTA_MEMORY_PASS) {
-    const pw = await promptPassword('主口令（启用加密，勿忘；忘口令可用恢复钥匙重设）: ');
-    if (!pw) { console.error('已取消。'); process.exit(2); }
-    const pw2 = await promptPassword('再次输入确认: ');
-    if (pw2 !== pw) { console.error('两次输入不一致。'); process.exit(2); }
-    o.password = pw;
+  if (wantEncrypt && !o.password) {
+    const got = await resolvePasswordInput(o, '主口令（启用加密，勿忘；忘口令可用恢复钥匙重设）: ');
+    if (got.error) { console.error(got.error); process.exit(2); }
+    if (got.source === 'prompt') {
+      const pw2 = await promptPassword('再次输入确认: ');
+      if (pw2 !== got.password) { console.error('两次输入不一致。'); process.exit(2); }
+    }
+    o.password = got.password;
   }
   const r = initCore(o);
   console.log(r.text);
@@ -5152,12 +5333,28 @@ function cmdIam(agentId, opts) {
   const existed = data.agents[agentId];
   data.agents[agentId] = { host: host, created: (existed && existed.created) || today() };
   saveAgents(root, data);
-  const file = writeSelfProfile(root, agentId, { mcpMode: 'stdio', name: opts.name, userName: opts.user, relationship: opts.relationship });
+  const profileIdentity = resolveIdentity({ agent: agentId, agentKey: opts.agentKey, agentKeyFile: opts.agentKeyFile });
+  if (profileIdentity && !profileIdentity.error && profileIdentity.id) {
+    setRuntimeAgent(profileIdentity.id, profileIdentity.agentKey);
+  }
+  let profile = '';
+  let profileWarning = '';
+  try {
+    profile = writeSelfProfile(root, agentId, { mcpMode: 'stdio', name: opts.name, userName: opts.user, relationship: opts.relationship });
+  } catch (e) {
+    const message = e && e.message ? e.message : String(e);
+    if (isEncrypted(root) && /授权密钥|加密/.test(message)) {
+      profileWarning = '自我档案暂未写入：当前加密库还没有 ' + agentId + ' 的授权密钥。请先完成授权（yotta-memory view 或 yotta-memory key bind ' + agentId + '），再在已授权的会话中执行 yotta-memory iam ' + agentId + ' --force --agent-key-file <宿主key文件> 写入档案。';
+    } else {
+      throw e;
+    }
+  }
   console.log('已登记智能体身份: ' + agentId + '（host=' + host + '，' + (conflict ? '--force 覆盖' : '新建') + '）');
   if (opts.name || opts.user || opts.relationship) {
     console.log('自我档案扩展: ' + [opts.name && '显示名=' + opts.name, opts.user && '用户=' + opts.user, opts.relationship && '关系=' + opts.relationship].filter(Boolean).join(' / '));
   }
-  console.log('已写入自我档案: ' + file);
+  if (profile) console.log('已写入自我档案: ' + profile);
+  if (profileWarning) console.log(profileWarning);
   console.log('本机免 token：以后用 whoami 确认身份；远端接入需 token new --agent ' + agentId);
 }
 function cmdWhoami(opts) {
@@ -6894,13 +7091,13 @@ function usage() {
   const banner = 'yotta-memory v' + VERSION + ' — 元忆：有权限边界的文件式智能体记忆';
   const sections = [
     ['核心记忆', [
-      ['init', '初始化记忆库（新建默认加密：需主口令 + 恢复钥匙；--attach 接入已有库；--no-encrypt 降级明文）'],
+      ['init', '初始化记忆库（新建默认加密：需主口令 + 恢复钥匙；--attach 接入已有库；--no-encrypt 降级明文；非 TTY 用 --password-stdin；--recovery-key-out <文件> 写恢复钥匙）'],
       ['remember <type> <subject> <statement>', '写入记忆（--source 来源；--weight 权重；--verify 写后回读校验；--no-hint 关启发）'],
       ['recall [关键词]', '检索记忆（--type/--limit/--agent/--owner/--all/--unsafe）'],
       ['forget', '删除一条记忆'],
       ['archive', '归档（--days/--threshold 盖棺分+年龄）'],
       ['backup', '备份记忆库（volumes / setup / status / ensure-daily / schedule / create / list / doctor / restore <id> --to <目录> / drill）'],
-      ['doctor', '开工可靠性检查（根目录/密钥库/索引/身份/最近备份；--runtime 加查 CLI/current/MCP/进程/技能副本漂移）'],
+      ['doctor', '开工可靠性检查（根目录/密钥库/索引/身份/最近备份；全新空库缺失 index/agents 降为 info；输出 YOTTA_MEMORY_AGENT_HOME 提示；--runtime 加查 CLI/current/MCP/进程/技能副本漂移）'],
       ['maintain', '记忆自组织（归档/遗忘候选/去重/合并；默认 dry-run；--dedup 查重+置信度，--dedup --apply 自动合并高置信组）'],
       ['consolidate', '周期摘要压缩（默认 dry-run；--apply 执行；--undo <batch> 回滚；--batches 查批次；候选=超龄+闲置+低效用，immutable/BOUND 豁免）'],
       ['distill', '心理日志蒸馏（统计摘要/主题画像/知识地图；--model 可选外部模型）'],
@@ -6918,8 +7115,8 @@ function usage() {
       ['token', '生成/列出/吊销访问 token（new --agent / list / revoke --agent）']
     ]],
     ['加密与安全', [
-      ['migrate', '把明文私密区迁移为密文（需主口令；迁移后打印恢复钥匙）'],
-      ['view', '启动用户查看平台（--port/--host；口令解锁浏览/授权/吊销 AI）'],
+      ['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）'],
       ['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 需主口令或恢复钥匙）'],
       ['config', '查看/设置配置（get；set memory_home <目录> / backup_dir <目录> / embedding_cmd <命令> / embedding_timeout <毫秒> / maintain_* 阈值与半衰 / consolidate_* 参数）']
@@ -6951,7 +7148,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', '--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', '--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; }
@@ -6971,6 +7168,7 @@ async function main() {
     else if (a === '--no-hint') opts.noHint = true;
     else if (a === '--encrypt') opts.encrypt = true;
     else if (a === '--no-encrypt') opts.noEncrypt = true;
+    else if (a === '--password-stdin') opts.passwordStdin = true;
     else if (a === '--json') opts.json = true;
     else if (a === '--manual') opts.manual = true;
     else if (a === '--skip-schedule') opts.skipSchedule = true;
@@ -7010,6 +7208,7 @@ async function main() {
       else if (a === '--password') opts.password = v;
       else if (a === '--new-password') opts.newPassword = v;
       else if (a === '--recovery-key') opts.recoveryKey = v;
+      else if (a === '--recovery-key-out') opts.recoveryKeyOut = v;
       else if (a === '--reason') opts.reason = v;
       else if (a === '--merge') opts.merge = v;
       else if (a === '--model') opts.model = v;
@@ -7057,6 +7256,7 @@ async function main() {
     process.exit(2);
   }
   const runtimeIdentity = resolveIdentity(opts);
+  if (runtimeIdentity.warning) console.error(runtimeIdentity.warning);
   setRuntimeAgent(runtimeIdentity.error ? '' : runtimeIdentity.id, runtimeIdentity.error ? '' : runtimeIdentity.agentKey);
   switch (first) {
     case 'init': await cmdInit(opts); break;
@@ -7109,7 +7309,7 @@ async function main() {
       break;
     }
     case 'migrate': await cmdMigrate(opts); break;
-    case 'view': cmdView(opts); break;
+    case 'view': await cmdView(opts); break;
     case 'reset-password': await cmdResetPassword(opts); break;
     case 'key': {
       const sub = rest[0];

package/package.json

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

@@ -8,6 +8,36 @@
 ## 2. 私密区加密怎么用？
 `init` 默认初始化加密库（需主口令 + 恢复钥匙，请妥善保存）；明文库可用 `migrate` 升级为加密。私密区文件为 `.md.enc`，可 git 版本化。查看/授权用 `yotta-memory view`（口令解锁，浏览/授权/吊销 AI）；授权时一次性展示的 `agent_key` 请立即保存，服务端同时写 `keys/pending/<id>.key` 供该 AI 新会话用 `key claim` 领取。出现 `[YTM_MIGRATION_REQUIRED]` 说明还有 agent 未绑定，请由你在 `view` 平台逐个点「授权」完成重新授权（AI 只提醒、不代执行）。
 
+**明文库第一次转加密**：
+
+```cmd
+echo 主口令 | yotta-memory migrate --password-stdin --recovery-key-out "%USERPROFILE%\yotta-memory-recovery.key"
+```
+
+迁移后授权二选一（等价）：推荐 `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 且未提供口令时会明确提示改用哪种方式，不会静默「已取消」。
+
+## 2.2 空加密库 `view` 打不开？
+v0.16.2 起，空加密库（没有 owner key）可用恢复钥匙校验主口令进入 `view`。如果页面显示「无 owner」，先在终端执行 `yotta-memory iam <id>` 登记身份，再回页面授权；也可以由用户在终端执行 `yotta-memory key bind <id>`。
+
+## 2.3 `--agent-key-file` 指向的文件不存在？
+文件不存在时不再致命：元忆降级为未授权模式，公共 FACT 仍可读；私密操作 fail-closed，并提示 `key bind <id>`。文件存在但为空或不可读仍会报错。推荐用 `YOTTA_MEMORY_AGENT_HOME` 指定宿主目录，授权后 key 原地生效。
+
+## 2.4 迁移后必须 `key bind` 吗？
+不必。`yotta-memory view` 页面授权和 `yotta-memory key bind <id>` 是两条等价路径：两条都会写 `binding + pending`，随后 AI 都执行 `yotta-memory key status <id>` → `yotta-memory key claim <id>`，再落到 `<AI_HOME>/.yotta-memory-agent-key`。普通用户推荐 `view`，高级用户或无可视化环境再用 `key bind`。
+
+## 2.5 迁移后 `recall` 读不到私密怎么办？
+先确认已经完成授权和 `key claim`，再带 agent key 重建加密索引：
+
+```cmd
+yotta-memory reindex --agent <id> --agent-key-file "<AI_HOME>/.yotta-memory-agent-key"
+yotta-memory recall <关键词> --agent <id> --agent-key-file "<AI_HOME>/.yotta-memory-agent-key"
+```
+
+`migrate` 在没有 agent_key 时无法建立每 owner 加密索引，所以 `reindex` 必须在授权 / claim 之后执行。MCP 场景还要确认宿主配置带 `--agent-key-file`，只有 `--agent-id` 会报缺少 agent_key。
+
 ## 3. 多智能体权限怎么隔离？
 公共 FACT 所有智能体可读；PREF / BOUND / COMMIT 按 owner 物理隔离，调用方必须持有匹配的 `agent_key`（用户执行 `key bind <id>`，或在 `view` 平台授权获得）。owner ID 单独存在不构成认证，不授权 / 无 key 读不到。私密操作缺 key 时会输出 `[YTM_MIGRATION_REQUIRED]`；授权完成后该标记消失。AI 新会话用 `key status <id>` 检查，pending 存在则 `key claim <id>` 落到 `<AI_HOME>/.yotta-memory-agent-key`；`AI_HOME` 默认规则由 claim / status 共用（显式 `--to` / `--agent-key-file` > `YOTTA_MEMORY_AGENT_HOME` / `YOTTA_MEMORY_AGENT_KEY_FILE` > Codex / OpenCode / 通用宿主默认），status 会显示 `checked` 与 `discovery`。吊销后旧 key 立即校验失败，需重新授权。
 

package/skill-manifest.json

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