@yottameta/yotta-memory 0.16.7 → 0.17.0

package/bin/yotta-memory.js

@@ -25,9 +25,268 @@ const net = require('net');
 const child_process = require('child_process');
 const { AsyncLocalStorage } = require('async_hooks');
 
-const VERSION = '0.16.7';
+const VERSION = '0.17.0';
+const CLI_VALUE_OPTS = 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', '--year', '--evalset', '--k', '--seed', '--bootstrap', '--gate', '--against', '--template', '--path']);
+const CLI_FLAG_OPTS = new Set(['--project', '--all', '--unsafe', '--no-auth', '--stdio', '--onstart', '--from-current', '--restart', '--force', '--attach', '--allow-same-volume', '--verify', '--no-hint', '--encrypt', '--no-encrypt', '--password-stdin', '--json', '--manual', '--skip-schedule', '--useful', '--useless', '--undo', '--dry-run', '--apply', '--purge', '--dedup', '--batches', '--explain', '--semantic', '--runtime', '--ablate', '--timing', '--baseline', '--probe', '--quarantine', '--restore', '--yes', '--keep-memories', '--keep-identity']);
+
+function helpOption(flag, arg, what, when, caution) {
+  return { flag: flag, arg: arg || '', what: what, when: when || '', caution: caution || '' };
+}
+function helpSub(name, usage, what, when, options) {
+  return { name: name, usage: usage || name, what: what, when: when || '', options: options || [] };
+}
+const HELP_MODEL = [
+  { group: '核心记忆', commands: [
+    { name: 'init', usage: 'init [--project | --dir <目录>] [--attach | --encrypt | --no-encrypt] [--password-stdin] [--recovery-key-out <文件>]', what: '初始化记忆库', when: '第一次使用，或把已有记忆库接入当前项目 / 智能体时', options: [
+      helpOption('--project', '', '把记忆库放在当前项目根目录', '只希望这个项目使用这份记忆时', ''),
+      helpOption('--dir', '<目录>', '指定记忆库位置', '不想用默认用户级位置时', ''),
+      helpOption('--attach', '', '接入已有记忆库', '目录里已经有一份库，不要重新初始化时', ''),
+      helpOption('--encrypt', '', '新建加密记忆库', '想显式要求加密时', ''),
+      helpOption('--no-encrypt', '', '新建明文记忆库', '只做临时实验、明确接受明文风险时', '私密记忆会以明文落盘；正式使用不要加这个选项'),
+      helpOption('--password-stdin', '', '从标准输入读取主口令', '脚本或非交互环境设置口令时', '只适合纯 ASCII 口令；中文口令请交互输入'),
+      helpOption('--recovery-key-out', '<文件>', '把恢复钥匙写到文件', '新建或迁移后需要立刻保存恢复钥匙时', '恢复钥匙能重置主口令，必须单独妥善保管'),
+      helpOption('--force', '', '允许覆盖已存在的运行文件', '确认要替换旧运行文件时', '可能覆盖现有内容；先确认目标路径和备份'),
+    ] },
+    { name: 'remember', usage: 'remember <type> <subject> <statement> [选项]', what: '写入一条记忆', when: '出现事实、偏好、边界或承诺，需要跨会话保留时', options: [
+      helpOption('--source', '<来源>', '记录这条记忆的来源', '需要以后追溯「谁说的 / 哪来的」时', ''),
+      helpOption('--weight', '<数值>', '设置重要性权重', '这条记忆比普通条目更重要或更次要时', ''),
+      helpOption('--verify', '', '写完立刻回读校验', '关键记忆担心写失败或索引异常时', ''),
+      helpOption('--no-hint', '', '关闭类型启发式提示', '已经明确知道类型、不想看额外提醒时', ''),
+    ] },
+    { name: 'recall', usage: 'recall [关键词] [选项]；search 是别名', what: '检索记忆', when: '开工恢复上下文、找旧决定或确认边界时', options: [
+      helpOption('--type', '<类型>', '只查某一种类型', '只想看 FACT / PREF / BOUND / COMMIT 中的一类时', ''),
+      helpOption('--limit', '<条数>', '限制返回条数', '结果太多、只需看最相关的几条时', ''),
+      helpOption('--agent', '<id>', '声明当前智能体身份或按智能体筛选', '当前会话身份需要明确声明时', '声明身份不等于获得跨读权限'),
+      helpOption('--owner', '<id>', '指定记忆归属者', '查询某个 owner 的私密记忆时', '读其它智能体的私密区需要授权'),
+      helpOption('--all', '', '跨 owner 检索', '确实需要看所有可读范围内的记忆时', '跨读其它智能体私密仍未授权会拒绝并提示'),
+      helpOption('--unsafe', '', '跳过越界读取保护', '只有用户明确授权做隔离排查时', '会放宽私密读取边界，日常不要使用'),
+      helpOption('--explain', '', '输出命中理由和效用分项', '想理解为什么这条记忆被排到前面时', ''),
+      helpOption('--semantic', '', '显式开启语义检索', '想强制使用同义词 / 拼音 / 模糊匹配时', ''),
+      helpOption('--embedding', '<命令>', '临时指定本地 embedding 插件命令', '这次检索想使用自定义本地向量命令时', '只在本地执行，不会把记忆上传远端'),
+      helpOption('--embedding-timeout', '<毫秒>', '设置 embedding 插件超时', '插件较慢或需要快速失败时', ''),
+      helpOption('--year', '<yyyy>', '只检索指定年份的记忆', '库很大、只想在某一年的记忆里找时', '可重复传多次；不传则检索全部年份'),
+    ] },
+    { name: 'forget', usage: 'forget <记忆 id> [选项]', what: '删除一条记忆', when: '确认某条记忆不应继续保留时', options: [
+      helpOption('--reason', '<原因>', '记录删除原因', '需要留下为什么删除的审计线索时', ''),
+      helpOption('--unsafe', '', '跳过越界删除保护', '只有获得明确授权处理隔离库时', '会放宽删除边界，误删风险很高'),
+    ] },
+    { name: 'archive', usage: 'archive [选项]', what: '把低价值或过期记忆归档', when: '库变大，想让旧记忆退出主检索但保留可回溯时', options: [
+      helpOption('--days', '<天数>', '按未使用天数判断归档', '想调整「多久没用才归档」时', ''),
+      helpOption('--threshold', '<数值>', '按效用分阈值判断归档', '想调整「用得少不少」时', ''),
+      helpOption('--dry-run', '', '只预览归档结果', '先看会动哪些记忆，再决定是否执行时', ''),
+    ] },
+    { name: 'backup', usage: 'backup <子命令> [选项]', what: '备份、恢复和演练记忆库', when: '配置自动备份、创建备份、恢复误删或验证备份可用时', subcommands: [
+      helpSub('volumes', 'volumes [--json]', '列出可用备份卷', '想知道备份会写到哪里时', [helpOption('--json', '', '输出 JSON', '脚本处理备份卷列表时', '')]),
+      helpSub('setup', 'setup [--manual] [--skip-schedule] [--allow-same-volume]', '配置备份目录和计划任务', '第一次启用自动备份时', [
+        helpOption('--manual', '', '只配置目录，不改计划任务', '由你自己管理定时任务时', ''),
+        helpOption('--skip-schedule', '', '跳过自动计划任务', '只想先建备份目录、不注册系统计划时', ''),
+        helpOption('--allow-same-volume', '', '允许备份和记忆库在同一磁盘卷', '只有临时测试且接受同盘故障风险时', '同盘备份无法防止整盘损坏；正式使用必须换独立盘'),
+      ]),
+      helpSub('status', 'status [--json]', '查看备份健康状态', '开工检查或排查备份是否正常时', [helpOption('--json', '', '输出 JSON', '脚本读取备份状态时', '')]),
+      helpSub('ensure-daily', 'ensure-daily [--json]', '确保每日备份任务存在', '修复自动备份任务缺失时', [helpOption('--json', '', '输出 JSON', '自动化里检查任务时', '')]),
+      helpSub('schedule', 'schedule <on|off|status> [--time <HH:MM>]', '管理每天自动备份', '设置或关闭每日备份时', [helpOption('--time', '<HH:MM>', '设置每日备份时间', '默认 03:30 不合适时', '')]),
+      helpSub('create', 'create [--json]', '立即创建一份备份', '手动留一个恢复点、或改库前先备份时', [helpOption('--json', '', '输出 JSON', '脚本读取新备份 id 时', '')]),
+      helpSub('list', 'list [--json]', '列出备份历史', '选一个恢复点时', [helpOption('--json', '', '输出 JSON', '脚本读取备份列表时', '')]),
+      helpSub('doctor', 'doctor [--json]', '检查备份目录和文件是否健康', '怀疑备份损坏或磁盘异常时', [helpOption('--json', '', '输出 JSON', '自动化体检时', '')]),
+      helpSub('restore', 'restore <id> --to <目录> [--force]', '从备份恢复到指定目录', '误删、迁移或需要验证恢复内容时', [
+        helpOption('--to', '<目录>', '指定恢复目标目录', '恢复时必须显式给出目标位置', ''),
+        helpOption('--id', '<id>', '指定备份 id', '不用位置参数、想显式点名备份时', ''),
+        helpOption('--force', '', '允许覆盖非空目标目录', '确认目标可以覆盖时', '可能覆盖目标目录现有文件；先确认目标和备份'),
+      ]),
+      helpSub('drill', 'drill <id> [--to <目录>] [--probe]', '恢复演练', '验证备份真的能恢复时', [
+        helpOption('--to', '<目录>', '指定演练恢复目录', '演练时使用临时空目录更安全', ''),
+        helpOption('--id', '<id>', '指定备份 id', '不用位置参数、想显式点名备份时', ''),
+        helpOption('--probe', '', '恢复后自动跑恢复 / 迁移基线探针', '想确认恢复副本的身份、近期条目与操作规则都可用时', '复制的索引与访问计数不变，探针只读'),
+        helpOption('--against', '<库路径>', '指定对比库做差集校验', '想确认备份没有落后于源库、迁移没有丢条目时', '对比库只读；差集缺失会列出清单并非零退出'),
+      ]),
+    ] },
+    { name: 'doctor', usage: 'doctor [选项]', what: '开工可靠性检查', when: '开工前、异常后或升级后确认系统状态时', options: [
+      helpOption('--runtime', '', '同时检查 CLI、current、MCP、进程和技能副本是否漂移', '升级后版本对不上时', ''),
+      helpOption('--mcp-config', '<文件>', '补充检查指定 MCP 配置文件', '排查宿主 MCP 是否指向旧运行时', ''),
+      helpOption('--skill-dir', '<目录>', '补充检查指定技能副本目录', '排查技能目录是否落后', ''),
+      helpOption('--baseline', '', '追加恢复 / 迁移基线探针（六类，只读）', '恢复、迁移或升级后要确认记忆真的可用时', '探针失败会列出缺失清单并以非零状态退出'),
+      helpOption('--against', '<库路径>', '探针的对比库（通常是迁移前的源库）', '要确认目标库没有丢条目时', '差集条目缺失会逐条列出'),
+      helpOption('--template', '<文件>', '用模板声明显式期望（owner / 最小条数 / 类型条数 / 查询）', '有明确验收清单、要按清单核对时', '模板只加严判定，不会放宽或改写探针'),
+      helpOption('--json', '', '输出 JSON', '脚本或自动化读取体检结果时', ''),
+    ] },
+    { name: 'maintain', usage: 'maintain [选项]', what: '记忆自组织：归档、遗忘候选、去重和合并', when: '定期清理低价值记忆、合并重复条目时', options: [
+      helpOption('--dedup', '', '只做重复检查并给置信度', '想先看哪些条目重复时', ''),
+      helpOption('--apply', '', '真正执行，而不是只预览', '确认预览结果后要落盘时', '会改动记忆库并创建事务快照；先跑 dry-run'),
+      helpOption('--purge', '', '对遗忘候选执行真删', '确认候选确实不再需要时', '真删不可逆；通常先用归档而不是 purge'),
+      helpOption('--dry-run', '', '只预览，不改库', '默认行为，想显式表达时', ''),
+      helpOption('--min-age', '<天数>', '设置遗忘候选最小年龄', '想调整「放多久才考虑遗忘」时', ''),
+      helpOption('--min-idle', '<天数>', '设置遗忘候选最小闲置天数', '想调整「多久没碰才考虑遗忘」时', ''),
+      helpOption('--max-utility', '<数值>', '设置效用分上限', '想调整「用得少到什么程度」时', ''),
+      helpOption('--min-group', '<条数>', '设置重复组最小条数', '调整查重灵敏度时', ''),
+      helpOption('--merge', '<id列表>', '显式合并指定条目', '已经确认这些条目可以合并时', ''),
+      helpOption('--json', '', '输出 JSON', '自动化处理维护结果时', ''),
+    ] },
+    { name: 'consolidate', usage: 'consolidate [--apply | --undo <batch> | --batches] [选项]', what: '把旧记忆压缩成周期摘要', when: '库很大，想把超龄、闲置、低效用条目压成摘要时', options: [
+      helpOption('--apply', '', '真正执行压缩', '确认 dry-run 结果后要落盘时', '会改动记忆库并创建事务快照；先预览'),
+      helpOption('--undo', '<batch>', '回滚一个摘要批次', '压缩后发现结果不合适时', ''),
+      helpOption('--batches', '', '列出历史批次', '想找回滚批次号时', ''),
+      helpOption('--period', '<天数>', '设置摘要周期', '想改变摘要覆盖的时间跨度时', ''),
+      helpOption('--threshold', '<数值>', '设置候选效用阈值', '想调整进入摘要的门槛时', ''),
+      helpOption('--min-age', '<天数>', '设置候选最小年龄', '想调整「放多久才进入摘要」时', ''),
+      helpOption('--min-idle', '<天数>', '设置候选最小闲置天数', '想调整「多久没碰才进入摘要」时', ''),
+      helpOption('--max-utility', '<数值>', '设置候选效用分上限', '想调整「用得少到什么程度」时', ''),
+      helpOption('--min-group', '<条数>', '设置摘要组最小条数', '调整合并力度时', ''),
+      helpOption('--json', '', '输出 JSON', '自动化处理摘要结果时', ''),
+    ] },
+    { name: 'distill', usage: 'distill [--model <命令>] [选项]', what: '把心理日志蒸馏成统计摘要、主题画像和知识地图', when: '想把长期记录整理成更高层的自我画像时', options: [
+      helpOption('--model', '<命令>', '调用本地外部模型辅助蒸馏', '需要更高质量摘要、且已准备本地模型命令时', '命令在本地执行；不要指向会外传原文的服务'),
+      helpOption('--subject', '<标题>', '指定蒸馏输出主题', '想给这次摘要一个固定标题时', ''),
+      helpOption('--json', '', '输出 JSON', '自动化处理蒸馏结果时', ''),
+    ] },
+    { name: 'feedback', usage: 'feedback <记忆 id> [--useful | --useless | --undo]', what: '记录记忆是否有用', when: '一条记忆刚刚帮助了你，或明显误导了你时', options: [
+      helpOption('--useful', '', '记为有用', '这条记忆确实帮上忙时', ''),
+      helpOption('--useless', '', '记为没用', '这条记忆造成误导或噪音时', ''),
+      helpOption('--undo', '', '撤销上一次反馈', '误点反馈时', ''),
+    ] },
+    { name: 'explain', usage: 'explain <记忆 id> [--json]', what: '解释一条记忆的效用分和归档判定', when: '想理解为什么它被排序、归档或遗忘时', options: [helpOption('--json', '', '输出 JSON', '脚本读取解释结果时', '')] },
+    { name: 'bench', usage: 'bench [--evalset <文件>] [--k <条数>] [--seed <数值>] [--bootstrap <次数>] [--ablate] [--gate <指标>=<数值>] [--timing] [--json] [--out <文件>]', what: '可复算的检索基准评测', when: '改检索 / 索引逻辑前后要证明「没变差」，或把质量门禁接进 CI 时', options: [
+      helpOption('--evalset', '<文件>', '指定评测集 JSON 文件', '想固定一组查询来复算指标时', '不指定时按库内条目做确定性抽样，生成基线评测集'),
+      helpOption('--k', '<条数>', '设置结果窗口大小', '想按 Recall@k / nDCG@k 的 k 口径统计时', '默认 5'),
+      helpOption('--seed', '<数值>', '设置抽样与置信区间的随机种子', '要让评测集和置信区间可复算时', '默认 20260925；同种子同库必须同结果'),
+      helpOption('--bootstrap', '<次数>', '设置 bootstrap 重采样次数', '想调整 95% 置信区间的精度时', '默认 1000；0 表示不重采样'),
+      helpOption('--ablate', '', '输出关键词 / 语义 × 融合 / 纯分的消融对比', '想知道哪一层检索贡献最大时', ''),
+      helpOption('--gate', '<指标>=<数值>', '设置质量门禁', 'CI 里要求指标达到阈值时', '不达标 exit 1；可重复传多次，指标可选 recall / mrr / ndcg / hit'),
+      helpOption('--timing', '', '附带检索耗时 p50 / p95', '想了解检索耗时分布时', '带上耗时后报告不再逐字节可复算'),
+      helpOption('--year', '<yyyy>', '只评测指定年份的记忆', '库很大、只想对某一年做基准时', '可重复传多次；不传则覆盖全部年份'),
+      helpOption('--json', '', '输出 JSON', '脚本读取指标与门禁结果时', ''),
+      helpOption('--out', '<文件>', '把报告写到文件', '想把评测报告归档或交给 CI 时', ''),
+    ] },
+    { name: 'scan', usage: 'scan [--path <目录>] [--gate <安全级别>] [--quarantine --yes] [--restore] [--json]', what: '扫描记忆库里的注入、凭证泄漏与越权指令', when: '怀疑记忆被污染、要做安全复核或把门禁接进 CI 时', options: [
+      helpOption('--path', '<目录>', '指定要扫描的目录', '想扫描另一个记忆库或临时导出目录时', '默认扫描当前记忆库'),
+      helpOption('--gate', '<安全级别>', '设置安全门禁', 'CI 里要求不出现某个级别及以上的命中时', '命中该级别及以上 exit 1；可选 safe / low / medium / high / critical'),
+      helpOption('--json', '', '输出 JSON', '脚本读取命中清单与分级统计时', ''),
+      helpOption('--quarantine', '', '把命中行脱敏隔离（原文件先备份）', '确认某条记忆被污染、要立刻止住它被检索时', '会改写记忆文件：必须先备份原件，且需要显式确认'),
+      helpOption('--yes', '', '跳过交互确认', '自动化里执行隔离时', '跳过确认后不再二次询问，请先看一遍命中清单'),
+      helpOption('--restore', '', '还原最近一个隔离批次', '隔离后发现问题、要恢复原文时', '会覆盖当前文件；批次已还原过则拒绝重复还原'),
+      helpOption('--id', '<id>', '指定要还原的隔离批次', '要还原的不是最近一批时', ''),
+    ] },
+    { name: 'reindex', usage: 'reindex', what: '重建记忆索引', when: '索引损坏、手动改过记忆文件或 doctor 提示索引异常时', options: [] },
+    { name: 'export', usage: 'export --out <文件.json>', what: '导出全部记忆', when: '备份、迁移或做离线检查时', options: [helpOption('--out', '<文件>', '指定导出文件', '导出时必须给出目标 JSON 文件', '')] },
+    { name: 'import', usage: 'import <文件.json>', what: '导入记忆 JSON', when: '从导出文件恢复或迁移时', options: [] },
+  ] },
+  { group: '身份与画像', commands: [
+    { name: 'iam', usage: 'iam --name <名字> --user <用户> --relationship <关系>', what: '登记当前智能体身份', when: '第一次接入，或身份信息需要更新时', options: [
+      helpOption('--name', '<名字>', '设置智能体显示名', '登记或更新身份时', ''),
+      helpOption('--user', '<用户>', '设置用户称呼', '登记或更新身份时', ''),
+      helpOption('--relationship', '<关系>', '设置与用户的关系定位', '登记或更新身份时', ''),
+    ] },
+    { name: 'identity', usage: 'identity remove <id> [选项]', what: '彻底删除一个 AI 身份与它的私密记忆', when: '某个 AI 不再使用、要把它的身份与私密记忆清干净时', subcommands: [
+      helpSub('remove', 'remove <id> [--dry-run] [--yes] [--keep-memories] [--keep-identity] [--password <口令> | --recovery-key <钥匙>]', '彻底删除身份 + 私密记忆（真删）', '确认某个 AI 不再使用、要一次清干净时', [
+        helpOption('--dry-run', '', '先列出将删除的内容', '想核对清单再决定时', '预演只读，不改任何文件'),
+        helpOption('--yes', '', '跳过交互确认', '自动化里执行删除时', '会立刻真删；请先跑 --dry-run 核对'),
+        helpOption('--keep-memories', '', '只删身份与授权，保留私密记忆', '想注销身份但保住记忆时', ''),
+        helpOption('--keep-identity', '', '只删私密记忆与授权，保留身份登记', '想清记忆但保留登记时', ''),
+        helpOption('--password', '<口令>', '用户主口令（加密库用它证明是用户本人）', '由用户本人在 CLI 执行时', '命令行会留下痕迹；优先交互输入'),
+        helpOption('--recovery-key', '<钥匙>', '用恢复钥匙证明用户身份', '忘记主口令时', '恢复钥匙只能由用户本人保管'),
+      ]),
+    ] },
+    { name: 'whoami', usage: 'whoami [--json]', what: '查看当前身份和登记状态', when: '不确定当前是谁、是否已登记时', options: [helpOption('--json', '', '输出 JSON', '脚本读取身份状态时', '')] },
+    { name: 'profile', usage: 'profile [--owner <id>] [--json]', what: '生成用户画像', when: '想按私密记忆原文结构化查看用户画像时', options: [
+      helpOption('--owner', '<id>', '指定画像归属者', '查某个 owner 的私密画像时', '仍然受私密区权限约束'),
+      helpOption('--json', '', '输出 JSON', '自动化读取画像时', ''),
+    ] },
+    { name: 'context', usage: 'context [选项]', what: '生成开工上下文包', when: '每个会话开工时恢复身份、边界、近期记忆和承诺', options: [
+      helpOption('--limit', '<条数>', '限制近期记忆条数', '上下文太长、想缩短时', ''),
+      helpOption('--owner', '<id>', '指定 owner 范围', '需要看某个 owner 的上下文时', '仍然受私密区权限约束'),
+      helpOption('--budget', '<字符数>', '设置动态记忆字符预算', '需要控制上下文包大小时', '0 表示不限制'),
+      helpOption('--focus', '<关键词>', '按当前任务聚焦', '这次任务很明确、想优先拉相关记忆时', ''),
+      helpOption('--explain', '', '输出 included / dropped 选择解释', '想理解上下文为什么收录或丢弃时', ''),
+      helpOption('--embedding', '<命令>', '临时指定本地 embedding 插件命令', '上下文检索想用本地向量命令时', '只在本地执行'),
+      helpOption('--embedding-timeout', '<毫秒>', '设置 embedding 插件超时', '插件较慢或需要快速失败时', ''),
+      helpOption('--year', '<yyyy>', '只装载指定年份的记忆', '只想让上下文包覆盖某一年份时', '可重复传多次；不传则装载全部年份'),
+    ] },
+    { name: 'token', usage: 'token <子命令> [选项]', what: '管理远端 MCP 访问 token', when: '给远端 MCP 客户端发放或吊销访问凭据时', subcommands: [
+      helpSub('new', 'new --agent <id> [--scope <范围>] [--json]', '生成一个访问 token', '远端客户端第一次接入时', [
+        helpOption('--agent', '<id>', '指定 token 对应的智能体 id', '发 token 时必须明确给谁用', ''),
+        helpOption('--scope', '<范围>', '限制 token 权限范围', '只想给某一类访问权限时', ''),
+        helpOption('--json', '', '输出 JSON', '脚本读取新 token 时', ''),
+      ]),
+      helpSub('list', 'list [--json]', '列出 token', '查当前有哪些 token 时', [helpOption('--json', '', '输出 JSON', '自动化盘点 token 时', '')]),
+      helpSub('revoke', 'revoke --agent <id>', '吊销 token', '设备丢失或凭据泄漏时', [helpOption('--agent', '<id>', '指定要吊销 token 的智能体 id', '吊销时必须明确对象', '')]),
+    ] },
+  ] },
+  { group: '加密与安全', commands: [
+    { name: 'migrate', usage: 'migrate [--password-stdin] [--recovery-key-out <文件>]', what: '把明文记忆库迁移成加密记忆库；迁移后授权二选一：推荐 yotta-memory view，等价 CLI 为 yotta-memory key bind <id>', when: '旧库还是明文，确认要启用私密区加密时', options: [
+      helpOption('--password', '<口令>', '直接提供主口令', '自动化环境无法交互输入时', '命令行会留下痕迹；优先交互输入'),
+      helpOption('--password-stdin', '', '从标准输入读取主口令', '脚本迁移时', '只适合纯 ASCII 口令；中文口令请交互输入'),
+      helpOption('--agent', '<id>', '声明迁移使用的身份', '迁移时需要指定 owner 时', ''),
+      helpOption('--recovery-key', '<钥匙>', '用恢复钥匙参与迁移', '已有恢复钥匙、需要恢复访问时', '恢复钥匙能重置主口令，注意不要泄漏'),
+      helpOption('--recovery-key-out', '<文件>', '把恢复钥匙写到文件', '迁移后要立刻保存恢复钥匙时', '恢复钥匙必须单独妥善保管'),
+    ] },
+    { name: 'view', usage: 'view [--port <端口>] [--host <地址>]', what: '启动用户查看平台', when: '用户本人要浏览、授权或导出记忆时', options: [
+      helpOption('--port', '<端口>', '设置查看平台端口', '默认端口被占用时', ''),
+      helpOption('--host', '<地址>', '设置监听地址', '需要只在指定网卡上开放时', '监听公网地址前先确认访问控制和防火墙'),
+    ] },
+    { name: 'reset-password', usage: 'reset-password [--password <旧口令>] [--new-password <新口令>] [--recovery-key <钥匙>]', what: '重设主口令', when: '知道旧口令想更换，或用恢复钥匙救回访问时', options: [
+      helpOption('--password', '<口令>', '提供当前主口令', '正常更换口令时', '命令行会留下痕迹；优先交互输入'),
+      helpOption('--new-password', '<口令>', '设置新主口令', '更换口令时', '新口令只保存在本地密钥材料中'),
+      helpOption('--password-stdin', '', '从标准输入读取口令', '脚本重设口令时', '只适合纯 ASCII 口令'),
+      helpOption('--recovery-key', '<钥匙>', '用恢复钥匙重设口令', '忘记主口令时', '恢复钥匙只显示一次；泄漏等于可重置口令'),
+    ] },
+    { name: 'key', usage: 'key <子命令> [选项]', what: '管理 agent_key 授权绑定', when: '用户授权智能体读取自己的私密记忆、轮换或吊销 key 时', subcommands: [
+      helpSub('list', 'list', '列出授权绑定', '盘点哪些智能体已授权时', []),
+      helpSub('bind', 'bind <id> [--password <口令> | --recovery-key <钥匙>]', '给智能体绑定 agent_key', '用户明确授权后绑定', [
+        helpOption('--password', '<口令>', '提供主口令', '绑定或轮换时', '命令行会留下痕迹；优先交互输入'),
+        helpOption('--recovery-key', '<钥匙>', '用恢复钥匙完成绑定', '忘记主口令时', '恢复钥匙必须妥善保管'),
+      ]),
+      helpSub('rotate', 'rotate <id> [--password <口令> | --recovery-key <钥匙>]', '轮换 agent_key', '怀疑旧 key 泄漏或定期更换时', [
+        helpOption('--password', '<口令>', '提供主口令', '轮换时', '命令行会留下痕迹；优先交互输入'),
+        helpOption('--recovery-key', '<钥匙>', '用恢复钥匙完成轮换', '忘记主口令时', '恢复钥匙必须妥善保管'),
+      ]),
+      helpSub('authorize', 'authorize <id> [--password <口令>]', '授权一个 owner', '用户查看平台不方便时，由 CLI 显式授权', [helpOption('--password', '<口令>', '提供主口令', '授权时', '这是用户侧操作，AI 不应代做')]),
+      helpSub('claim', 'claim <id> [--to <AI_HOME> | --plugin-data <目录> | --agent-key-file <文件>]', '领取待绑定的 agent_key', '用户授权后，智能体新会话领取只显示一次的 key', [
+        helpOption('--to', '<AI_HOME>', '把 key 写到指定 AI_HOME', '宿主有标准 AI_HOME 目录时', ''),
+        helpOption('--plugin-data', '<目录>', '把 key 写到插件数据目录', 'Agent Plugin 形态接入时', ''),
+        helpOption('--agent-key-file', '<文件>', '把 key 写到显式文件', '希望完全指定路径时', ''),
+      ]),
+      helpSub('status', 'status <id> [--to <AI_HOME> | --plugin-data <目录> | --agent-key-file <文件>]', '检查 key 是否已领取、绑定是否有效', '新会话开始或 MCP 连不上时', [
+        helpOption('--to', '<AI_HOME>', '检查指定 AI_HOME 下的 key', '宿主有标准 AI_HOME 目录时', ''),
+        helpOption('--plugin-data', '<目录>', '检查插件数据目录下的 key', 'Agent Plugin 形态接入时', ''),
+        helpOption('--agent-key-file', '<文件>', '检查显式 key 文件', '希望完全指定路径时', ''),
+      ]),
+      helpSub('revoke', 'revoke <id>', '吊销一个 agent_key', '设备丢失、泄漏或不再授权时', []),
+    ] },
+    { name: 'config', usage: 'config <get | set <键> <值>>', what: '查看或修改元忆配置', when: '调整记忆位置、embedding 命令、备份或维护阈值时', subcommands: [
+      helpSub('get', 'get', '查看当前配置', '想知道实际生效值 / 路径时', []),
+      helpSub('set', 'set <键> <值>', '修改配置键', '调整 memory_home / backup_dir / embedding_cmd / embedding_timeout / maintain_* / consolidate_* / scale_* 时', []),
+    ] },
+  ] },
+  { group: '平台与服务', commands: [
+    { name: 'runtime', usage: 'runtime <子命令> [选项]', what: '管理稳定运行时入口', when: '安装、切换、回滚或盘点元忆运行时版本时', subcommands: [
+      helpSub('install', 'install <tarball|版本> [--from-current] [--force]', '安装一个运行时版本', '升级或回退前准备版本目录时', [
+        helpOption('--from-current', '', '把当前运行目录打包安装为运行时版本', '把正在用的副本固化成稳定版本时', ''),
+        helpOption('--force', '', '允许覆盖内容不同的已安装版本', '确认要替换同版本目录时', '会覆盖已有运行时内容；先确认版本和备份'),
+      ]),
+      helpSub('use', 'use <版本> [--restart]', '切换 current 到指定版本', '升级后要把 MCP 切到新版本时', [helpOption('--restart', '', '切换后重启托管服务', '希望立即生效时', '')]),
+      helpSub('rollback', 'rollback [--restart]', '回滚到上一个运行时版本', '新版本出问题时', [helpOption('--restart', '', '回滚后重启托管服务', '希望立即恢复服务时', '')]),
+      helpSub('status', 'status [--json]', '查看 current 与运行时状态', '排查版本漂移时', [helpOption('--json', '', '输出 JSON', '自动化读取运行时状态时', '')]),
+      helpSub('list', 'list [--json]', '列出已安装运行时版本', '盘点可切换版本时', [helpOption('--json', '', '输出 JSON', '自动化盘点运行时版本时', '')]),
+    ] },
+    { name: 'serve', usage: 'serve [--stdio] [--tools core|full] [--host <地址>] [--port <端口>]', what: '启动 MCP 记忆引擎', when: '宿主需要以 MCP 方式访问元忆时', options: [
+      helpOption('--stdio', '', '用本地 stdio 模式启动', '本地宿主不需要 HTTP 服务时', ''),
+      helpOption('--tools', 'core|full', '选择工具分组', '想减少工具常驻开销时', 'core 更省上下文，full 暴露全部工具'),
+      helpOption('--host', '<地址>', '设置 HTTP 监听地址', '需要远端 MCP 接入时', '监听公网前必须配置鉴权和防火墙'),
+      helpOption('--port', '<端口>', '设置 HTTP 监听端口', '默认端口被占用时', ''),
+      helpOption('--no-auth', '', '关闭 HTTP 鉴权', '只在本机临时调试时', '任何能访问端口的人都可读写；不要用于远端或正式环境'),
+      helpOption('--agent-id', '<id>', 'stdio 模式下声明智能体 id', '本地宿主用固定身份启动时', ''),
+      helpOption('--agent-key', '<key>', 'stdio 模式下直接提供 agent_key', '宿主把 key 作为启动参数传入时', '命令行参数可能被进程列表看到；优先用 key 文件'),
+      helpOption('--agent-key-file', '<文件>', 'stdio 模式下从文件读取 agent_key', '宿主使用标准 key 文件时', ''),
+    ] },
+    { name: 'lan', usage: 'lan <子命令> [选项]', what: '管理开机自启', when: '需要元忆服务随系统或登录启动时', subcommands: [
+      helpSub('enable', 'enable [--onstart]', '启用开机自启', '希望元忆服务长期可用时', [helpOption('--onstart', '', '同时启用未登录也启动', 'Linux 上希望开机即启动、不依赖登录时', 'Windows 上此选项不改变计划任务语义')]),
+      helpSub('disable', 'disable', '关闭开机自启', '不再需要常驻服务时', []),
+      helpSub('status', 'status', '查看自启状态', '确认服务是否会随系统启动时', []),
+    ] },
+    { name: '--version', usage: '--version；短写法 -v', what: '显示当前版本', when: '确认安装的是哪个版本时', options: [] },
+  ] },
+];
 // @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";
+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><button class=\"danger\" data-d=\"'+esc(o.owner)+'\">删除</button>';box.appendChild(c);}\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();});};});\n  box.querySelectorAll('[data-d]').forEach(function(b){b.onclick=function(){var owner=b.getAttribute('data-d');var typed=prompt('彻底删除 '+owner+' 的身份与私密记忆（不可恢复；公共明文保留，其它 AI 不受影响）。请输入完整 ID 确认：');if(typed!==owner)return;b.disabled=true;api('/api/identity-remove',{owner:owner,confirm:typed}).then(function(d){b.disabled=false;if(!d||d.error){alert((d&&d.error)||'删除失败');loadOwners();return;}alert(d.text||'已删除');loadOwners();});};});\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';
@@ -581,7 +840,8 @@ function runtimeRestartManagedServer() {
   }
   return { error: true, text: '未检测到可管理的 server 自启配置，未执行重启。' };
 }
-function today() {
+function today(override) {
+  if (override && /^\d{4}-\d{2}-\d{2}$/.test(String(override))) return String(override);
   const d = new Date();
   const p = (n) => String(n).padStart(2, '0');
   return d.getFullYear() + '-' + p(d.getMonth() + 1) + '-' + p(d.getDate());
@@ -695,6 +955,40 @@ function typeSubdir(type, owner) {
   const id = owner || '';
   return path.join(PRIVATE_DIR, id, TYPE_DIRS[t]);
 }
+// v0.17.0 规模：新写入按 <yyyy>/<mm> 分层（公共 facts/<yyyy>/<mm>/，私密 private/<owner>/<type>/<yyyy>/<mm>/）。
+// 只影响新写入；旧平铺文件保持原位继续可读，不自动迁移。
+function dateSubdir(dateStr) {
+  const d = String(dateStr || '');
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(d)) return '';
+  return path.join(d.slice(0, 4), d.slice(5, 7));
+}
+function entryWriteDir(root, type, owner, dateStr) {
+  const base = path.join(root, typeSubdir(type, owner));
+  const sub = dateSubdir(dateStr);
+  return sub ? path.join(base, sub) : base;
+}
+// 归档保留年/月分层（不同月份的同名文件不再互相覆盖）；旧平铺文件仍按原样落到归档根。
+const MEMORY_FILE_RE = /\.md(\.enc)?$/;
+function entryRelParts(rel) {
+  const seg = String(rel || '').replace(/\\/g, '/').split('/').filter(Boolean);
+  if (seg[0] === PRIVATE_DIR) return { kind: 'private', owner: seg[1] || '', type: seg[2] || '' };
+  if (seg[0] === PUBLIC_DIR) return { kind: 'public', owner: '', type: 'facts' };
+  return null;
+}
+function archiveRelFor(root, rel, type, owner) {
+  const parts = entryRelParts(rel);
+  const t = String(type || (parts && parts.type) || 'FACT').toUpperCase();
+  const normalized = String(rel || '').replace(/\\/g, '/');
+  const seg = normalized.split('/');
+  const idx = seg.findIndex(function (s) { return /^\d{4}$/.test(s); });
+  const sub = (idx >= 0 && /^\d{2}$/.test(seg[idx + 1] || '')) ? seg[idx] + '/' + seg[idx + 1] : '';
+  const baseName = path.basename(normalized);
+  if (t === 'FACT' || (parts && parts.kind === 'public')) {
+    return path.posix.join(ARCHIVE_DIR, 'facts', sub, baseName);
+  }
+  const o = owner || (parts && parts.owner) || '';
+  return path.posix.join(ARCHIVE_DIR, PRIVATE_DIR, o, TYPE_DIRS[t] || 'facts', sub, baseName);
+}
 function defaultScope(type) {
   return PRIVATE_TYPES.indexOf(String(type).toUpperCase()) === -1 ? 'public' : 'private';
 }
@@ -1094,19 +1388,62 @@ function ensureInit(root) {
   fs.mkdirSync(path.join(root, ARCHIVE_DIR), { recursive: true });
   const readme = path.join(root, 'README.md');
   if (!fs.existsSync(readme)) {
-    fs.writeFileSync(readme, '# yotta-memory（元忆）记忆库\n\n有权限边界的文件式智能体记忆存储目录。结构：facts/（公共 FACT） private/<agent_id>/{prefs,bounds,commits}/（各智能体私密，物理隔离） .archive/（归档）。\n', 'utf8');
+    fs.writeFileSync(readme, '# yotta-memory（元忆）记忆库\n\n有权限边界的文件式智能体记忆存储目录。结构：facts/<年>/<月>/（公共 FACT） private/<agent_id>/{prefs,bounds,commits}/<年>/<月>/（各智能体私密，物理隔离） .archive/（归档）。v0.16 及更早的平铺文件（facts/*.md、private/<agent_id>/<type>/*.md）继续可读，不做自动迁移。\n', 'utf8');
+  }
+}
+// 递归收集目录下（含年/月子目录）的记忆文件路径，跳过 distills/profile.md 等非记忆文件。
+function walkEntryFiles(dir, out) {
+  let names;
+  try { names = fs.readdirSync(dir, { withFileTypes: true }); } catch (e) { return; }
+  for (const entry of names) {
+    const fp = path.join(dir, entry.name);
+    if (entry.isDirectory()) { walkEntryFiles(fp, out); continue; }
+    if (!entry.isFile()) continue;
+    if (!MEMORY_FILE_RE.test(entry.name)) continue;
+    out.push(fp);
   }
 }
-function nextSeq(dir) {
+// 序号在「类型目录 + owner」范围内唯一，跨越旧平铺与新年/月分层，避免同名覆盖。
+function maxSeqInTree(dir) {
   let max = 0;
-  if (fs.existsSync(dir)) {
-    for (const f of fs.readdirSync(dir)) {
-      const m = f.match(/^\d{4}-\d{2}-\d{2}-(\d{4})\.md(\.enc)?$/);
-      if (m) max = Math.max(max, parseInt(m[1], 10));
-    }
+  const files = [];
+  if (fs.existsSync(dir)) walkEntryFiles(dir, files);
+  for (const fp of files) {
+    const f = path.basename(fp);
+    const m = f.match(/^\d{4}-\d{2}-\d{2}-(\d{4})\.md(\.enc)?$/);
+    if (m) max = Math.max(max, parseInt(m[1], 10));
   }
   return String(max + 1).padStart(4, '0');
 }
+function nextSeq(dir) { return maxSeqInTree(dir); }
+// 分层写入时序号要跨该类型全部分层计算（否则同一年不同月份会重复 0001）。
+function nextSeqFor(typeDir, writeDir) {
+  return maxSeqInTree(typeDir || writeDir);
+}
+// 去重只看「最近写入窗口」：当前年/月子目录 + 平铺根，避免大库每次写入都全量扫一遍。
+function recentlyWrittenFiles(typeDir, writeDir) {
+  const out = [];
+  if (path.resolve(typeDir) === path.resolve(writeDir)) {
+    if (fs.existsSync(typeDir)) walkEntryFiles(typeDir, out);
+    return out;
+  }
+  if (fs.existsSync(writeDir)) walkEntryFiles(writeDir, out);
+  const yearDir = path.dirname(writeDir);
+  const seen = new Set(out);
+  if (fs.existsSync(yearDir)) {
+    for (const fp of fs.readdirSync(yearDir)) {
+      const full = path.join(yearDir, fp);
+      if (fs.statSync(full).isFile() && MEMORY_FILE_RE.test(fp) && !seen.has(full)) out.push(full);
+    }
+  }
+  if (fs.existsSync(typeDir)) {
+    for (const f of fs.readdirSync(typeDir)) {
+      const full = path.join(typeDir, f);
+      if (fs.statSync(full).isFile() && MEMORY_FILE_RE.test(f) && !seen.has(full)) out.push(full);
+    }
+  }
+  return out;
+}
 
 
 // ================= v0.7.0 加密（AES-256-GCM 信封加密 + PBKDF2 主密钥 + 恢复钥匙）=================
@@ -1559,6 +1896,24 @@ const INDEX_SHARD_THRESHOLD = 5000;
 const SHARD_RE = /^index-\d{4}\.json$/;
 function isSafeShardName(name) { return typeof name === 'string' && SHARD_RE.test(name); }
 function indexShardName(year) { return 'index-' + year + '.json'; }
+function shardYear(name) { return String(name).slice('index-'.length, -'.json'.length); }
+function entryYear(entry) {
+  return String((entry && entry.created) || '').slice(0, 4) || String(today()).slice(0, 4);
+}
+// v0.17.0：--year 只接受四位年份，可重复；不传即全量（既有行为零变化）。
+function normalizeYearList(value) {
+  if (value === undefined || value === null) return { years: [], error: '' };
+  const list = Array.isArray(value) ? value : [value];
+  const years = [];
+  for (const raw of list) {
+    const year = String(raw === undefined || raw === null ? '' : raw).trim();
+    if (!/^\d{4}$/.test(year)) {
+      return { years: [], error: '年份格式不正确: ' + String(raw) + '。--year 只接受四位年份（例如 --year 2026），可重复传多次。' };
+    }
+    if (years.indexOf(year) === -1) years.push(year);
+  }
+  return { years: years, error: '' };
+}
 function loadIndexManifest(root) {
   const p = indexPath(root);
   if (!fs.existsSync(p)) return null;
@@ -1595,6 +1950,52 @@ function loadIndex(root) {
   } catch (e) { /* ignore */ }
   return null;
 }
+// v0.17.0 B3：按年份懒加载索引——命中分片 manifest 时只读 years 覆盖的分片；
+// years 为空维持全量 loadIndex（逐字节行为不变）。平铺索引无法少读文件，按条目年份过滤。
+function loadIndexFor(root, options) {
+  const filter = normalizeYearList(options && (options.years !== undefined ? options.years : options.year));
+  if (filter.error) return null;
+  const years = filter.years;
+  if (!years.length) return loadIndex(root);
+  const p = indexPath(root);
+  if (!fs.existsSync(p)) return null;
+  try {
+    const d = JSON.parse(fs.readFileSync(p, 'utf8'));
+    if (!d) return null;
+    if (Array.isArray(d.entries)) {
+      if (d.version && d.version < INDEX_VERSION) return null;
+      const want = new Set(years);
+      return d.entries.filter(function (e) { return want.has(entryYear(e)); });
+    }
+    if (Array.isArray(d.shards)) {
+      if (d.version && d.version < INDEX_VERSION) return null;
+      const want = new Set(years);
+      const out = [];
+      for (const sh of d.shards) {
+        if (!isSafeShardName(sh)) continue;
+        if (!want.has(shardYear(sh))) continue; // 只读取命中年份的分片文件
+        const sp = path.join(root, sh);
+        if (!fs.existsSync(sp)) continue;
+        const sd = JSON.parse(fs.readFileSync(sp, 'utf8'));
+        if (sd && Array.isArray(sd.entries)) out.push.apply(out, sd.entries);
+      }
+      return out;
+    }
+  } catch (e) { /* ignore */ }
+  return null;
+}
+function indexEntriesFor(root, options) {
+  const filter = normalizeYearList(options && options.years);
+  if (filter.error) return { entries: [], error: filter.error };
+  if (filter.years.length) {
+    const lazy = loadIndexFor(root, { years: filter.years });
+    if (lazy) return { entries: lazy, error: '' };
+  }
+  const all = ensureIndex(root);
+  if (!filter.years.length) return { entries: all, error: '' };
+  const want = new Set(filter.years);
+  return { entries: all.filter(function (e) { return want.has(entryYear(e)); }), error: '' };
+}
 function getIndex(root) { return loadIndex(root) || []; }
 function saveIndex(root, entries) {
   const clean = entries.map(function (e) { const c = Object.assign({}, e); delete c.meta; return c; });
@@ -1602,7 +2003,7 @@ function saveIndex(root, entries) {
   if (clean.length > INDEX_SHARD_THRESHOLD) {
     const byYear = {};
     for (const e of clean) {
-      const y = String(e.created || '').slice(0, 4) || String(today()).slice(0, 4);
+      const y = entryYear(e);
       (byYear[y] = byYear[y] || []).push(e);
     }
     const newShards = [];
@@ -1638,14 +2039,102 @@ function collectEntryFiles(root) {
     }
   }
   const out = [];
-  for (const dir of dirs) {
-    for (const f of fs.readdirSync(dir)) {
-      if (!/\.md(\.enc)?$/.test(f)) continue;
-      const fp = path.join(dir, f);
-      if (fs.statSync(fp).isFile()) out.push(fp);
+  // v0.17.0：递归下探年/月子目录；旧平铺文件依旧按原路径收集。
+  for (const dir of dirs) walkEntryFiles(dir, out);
+  return out;
+}
+// v0.17.0：平铺 / 分层只影响存放位置，不改变条目身份。
+// 身份键 = 类型 + owner + 文件名（YYYY-MM-DD-NNNN.md），同身份先比较内容摘要。
+const LAYOUT_TYPE_BY_DIR = { facts: 'FACT', prefs: 'PREF', bounds: 'BOUND', commits: 'COMMIT' };
+function publicFrontmatterOwner(fp) {
+  try {
+    return String(parseFrontmatter(fs.readFileSync(fp, 'utf8')).meta.owner || '').trim();
+  } catch (e) {
+    return '';
+  }
+}
+function layoutEntryIdentity(root, fp) {
+  const rel = path.relative(root, fp).replace(/\\/g, '/');
+  const parts = entryRelParts(rel);
+  if (!parts) return null;
+  const type = LAYOUT_TYPE_BY_DIR[parts.type];
+  if (!type) return null;
+  const base = path.basename(rel).replace(/\.enc$/, '');
+  if (!/^\d{4}-\d{2}-\d{2}-\d{4}\.md$/.test(base)) return null;
+  const owner = parts.kind === 'public' ? publicFrontmatterOwner(fp) : parts.owner;
+  return {
+    key: [parts.kind, owner, type, base].join('\0'),
+    rel: rel,
+    owner: owner,
+  };
+}
+function normalizedLayoutDigest(buf) {
+  // latin1 往返保留原始字节，同时把 CRLF 归一，避免 Windows / Linux 检出差异制造假冲突。
+  const normalized = Buffer.from(buf.toString('latin1').replace(/\r\n/g, '\n'), 'latin1');
+  return crypto.createHash('sha256').update(normalized).digest('hex');
+}
+function layoutFileDigests(root, fp, owner) {
+  const buf = fs.readFileSync(fp);
+  const rawDigest = normalizedLayoutDigest(buf);
+  if (!isEncFile(fp)) return { rawDigest: rawDigest, plainDigest: rawDigest };
+  const key = getOwnerKeyFor(root, owner);
+  if (key) {
+    try {
+      return { rawDigest: rawDigest, plainDigest: normalizedLayoutDigest(Buffer.from(decryptMemoryText(buf, key), 'utf8')) };
+    } catch (e) { /* 密钥不可用或密文损坏时按待核处理 */ }
+  }
+  return { rawDigest: rawDigest, plainDigest: null };
+}
+function layoutCollisionReport(root) {
+  const grouped = new Map();
+  for (const fp of collectEntryFiles(root)) {
+    const info = layoutEntryIdentity(root, fp);
+    if (!info) continue;
+    if (!grouped.has(info.key)) grouped.set(info.key, []);
+    grouped.get(info.key).push({ fp: fp, rel: info.rel, owner: info.owner });
+  }
+  const report = { ok: true, duplicates: 0, conflicts: 0, unverified: 0, groups: [], warnings: [] };
+  for (const items of grouped.values()) {
+    if (items.length < 2) continue;
+    for (const item of items) {
+      try {
+        const digests = layoutFileDigests(root, item.fp, item.owner);
+        item.rawDigest = digests.rawDigest;
+        item.plainDigest = digests.plainDigest;
+      } catch (e) {
+        item.rawDigest = null;
+        item.plainDigest = null;
+      }
+    }
+    const plainDigests = items.map(function (item) { return item.plainDigest; });
+    const rawDigests = items.map(function (item) { return item.rawDigest; });
+    let status;
+    if (plainDigests.every(Boolean)) status = new Set(plainDigests).size === 1 ? 'duplicate' : 'conflict';
+    else if (rawDigests.every(Boolean) && new Set(rawDigests).size === 1) status = 'duplicate';
+    else status = 'unverified';
+    const sorted = items.slice().sort(function (a, b) {
+      const depth = b.rel.split('/').length - a.rel.split('/').length;
+      return depth !== 0 ? depth : a.rel.localeCompare(b.rel);
+    });
+    const paths = items.map(function (item) { return item.rel; }).sort();
+    const group = {
+      status: status,
+      paths: paths,
+      keep: sorted[0].rel,
+      drop: sorted.slice(1).map(function (item) { return item.rel; }),
+    };
+    report.groups.push(group);
+    if (status === 'duplicate') report.duplicates++;
+    else if (status === 'conflict') {
+      report.conflicts++;
+      report.warnings.push('布局: 平铺/分层同序号冲突（内容不同，两份均保留可读）: ' + paths.join(' ↔ '));
+    } else {
+      report.unverified++;
+      report.warnings.push('布局: 平铺/分层同序号待核（加密内容当前无法比较，两份均保留）: ' + paths.join(' ↔ '));
     }
   }
-  return out;
+  report.ok = report.conflicts === 0 && report.unverified === 0;
+  return report;
 }
 // 迁移：把根下旧平铺 prefs|bounds|commits/*.md 按 frontmatter owner 迁入 private/<owner>/<type>/
 function migrateLayout(root) {
@@ -1669,10 +2158,17 @@ function migrateLayout(root) {
 }
 function buildIndex(root) {
   migrateLayout(root);
+  const layout = layoutCollisionReport(root);
+  const skip = new Set();
+  for (const group of layout.groups) {
+    if (group.status !== 'duplicate') continue;
+    for (const rel of group.drop) skip.add(rel);
+  }
   const publicEntries = [];
   const privateByOwner = {};
   for (const fp of collectEntryFiles(root)) {
     const rel = path.relative(root, fp).replace(/\\/g, '/');
+    if (skip.has(rel)) continue;
     if (rel.indexOf(PRIVATE_DIR + '/') === 0) {
       const owner = rel.split('/')[1] || '';
       if (!getOwnerKeyFor(root, owner)) continue;
@@ -1825,13 +2321,18 @@ function bumpReadMeta(root, relFiles) {
     rewriteFrontmatter(fp, { access_count: acc, last_accessed: now }, root, owner);
   }
 }
-function touchIndex(root, relFiles) {
+function touchIndex(root, relFiles, options) {
   const set = new Set(relFiles);
   const now = today();
+  // v0.17.0 B3：带 --year 的检索只碰命中年份的分片（命中条目必然来自这些分片），
+  // 不传年份时行为与旧版一致（遍历全部 shards）。
+  const filterYears = (options && Array.isArray(options.years)) ? options.years : [];
+  const yearSet = filterYears.length ? new Set(filterYears) : null;
   const manifest = loadIndexManifest(root);
   if (manifest && Array.isArray(manifest.shards)) {
     for (const sh of manifest.shards) {
       if (!isSafeShardName(sh)) continue;
+      if (yearSet && !yearSet.has(shardYear(sh))) continue;
       const sp = path.join(root, sh);
       if (!fs.existsSync(sp)) continue;
       let sd = null; try { sd = JSON.parse(fs.readFileSync(sp, 'utf8')); } catch (e) { continue; }
@@ -2966,32 +3467,92 @@ function runtimeDoctorCore(opts) {
   };
 }
 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 (storeHasPublicFacts(root)) return true;
   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) {}
-    }
-  }
+  // v0.17.0：年/月分层后必须递归统计，否则新布局会被误判为空库。
+  if (collectEntryFiles(root).length) return true;
   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;
+  const files = [];
+  walkEntryFiles(factsDir, files);
+  return files.length > 0;
+}
+// ---- v0.17.0 B2：doctor 规模体检（只读；阈值走 config，info / warning 两级）----
+const SCALE_THRESHOLD_DEFAULTS = {
+  scale_warn_entries: 50000,
+  scale_warn_files_per_dir: 500,
+  scale_warn_index_bytes: 5 * 1024 * 1024,
+  scale_warn_cold_start_ms: 2000,
+};
+function scaleThreshold(cfg, key) {
+  const raw = cfg ? cfg[key] : undefined;
+  if (raw === undefined || raw === null || raw === '') return SCALE_THRESHOLD_DEFAULTS[key];
+  const n = parseFloat(raw);
+  return (n >= 0) ? n : SCALE_THRESHOLD_DEFAULTS[key];
+}
+function maxFilesInDir(dir) {
+  let max = 0;
+  let names;
+  try { names = fs.readdirSync(dir, { withFileTypes: true }); } catch (e) { return 0; }
+  let files = 0;
+  for (const item of names) {
+    if (item.isDirectory()) max = Math.max(max, maxFilesInDir(path.join(dir, item.name)));
+    else if (item.isFile()) files++;
+  }
+  return Math.max(max, files);
+}
+function indexSizeBytes(root) {
+  let total = 0;
+  const manifest = indexPath(root);
+  try { total += fs.statSync(manifest).size; } catch (e) { /* 尚未建索引 */ }
+  for (const sh of (loadIndexManifest(root) || { shards: [] }).shards || []) {
+    if (!isSafeShardName(sh)) continue;
+    try { total += fs.statSync(path.join(root, sh)).size; } catch (e) { /* 分片缺失已由 doctor 其它段报出 */ }
+  }
+  return total;
+}
+function measureIndexColdStart(root) {
+  const started = process.hrtime.bigint();
+  loadIndex(root);
+  const elapsed = Number(process.hrtime.bigint() - started) / 1e6;
+  return Math.round(elapsed * 1000) / 1000;
+}
+function scaleReport(root, cfg) {
+  const thresholds = {};
+  for (const key of Object.keys(SCALE_THRESHOLD_DEFAULTS)) thresholds[key] = scaleThreshold(cfg, key);
+  const entries = collectEntryFiles(root).length;
+  const filesPerDir = Math.max(maxFilesInDir(path.join(root, PUBLIC_DIR)), maxFilesInDir(path.join(root, PRIVATE_DIR)));
+  const indexBytes = indexSizeBytes(root);
+  // 冷启动取多次测量的中位数，避免单次抖动影响只读体检结果。
+  const samples = [];
+  for (let i = 0; i < 3; i++) samples.push(measureIndexColdStart(root));
+  samples.sort(function (a, b) { return a - b; });
+  const coldStartMs = samples[Math.floor(samples.length / 2)];
+  const warnings = [];
+  if (entries > thresholds.scale_warn_entries) {
+    warnings.push('规模: 记忆条数 ' + entries + ' 超过阈值 ' + thresholds.scale_warn_entries + '（考虑按年归档旧条目，或分批导出冷数据）');
   }
+  if (filesPerDir > thresholds.scale_warn_files_per_dir) {
+    warnings.push('规模: 单个目录文件数 ' + filesPerDir + ' 超过阈值 ' + thresholds.scale_warn_files_per_dir + '（检查是否有目录未按年/月分层）');
+  }
+  if (indexBytes > thresholds.scale_warn_index_bytes) {
+    warnings.push('规模: 索引总体积 ' + indexBytes + ' 字节超过阈值 ' + thresholds.scale_warn_index_bytes + '（可用 reindex 重建，或按年份分片）');
+  }
+  if (coldStartMs > thresholds.scale_warn_cold_start_ms) {
+    warnings.push('规模: 索引冷启动 ' + coldStartMs + 'ms 超过阈值 ' + thresholds.scale_warn_cold_start_ms + 'ms（可用 reindex 重建索引）');
+  }
+  return {
+    entries: entries,
+    files_per_dir: filesPerDir,
+    index_bytes: indexBytes,
+    cold_start_ms: coldStartMs,
+    thresholds: thresholds,
+    level: warnings.length ? 'warning' : 'ok',
+    warnings: warnings,
+  };
 }
 // 开工可靠性检查：只读检查根目录、密钥库、索引、身份登记与最近备份。
 function doctorCore(opts) {
@@ -3035,6 +3596,16 @@ function doctorCore(opts) {
     checks.index = { exists: true, valid: true };
   }
 
+  // v0.17.0 B2：规模体检（只读，不产生写入）
+  if (exists) {
+    const scale = scaleReport(root, cfg);
+    checks.scale = scale;
+    for (const message of scale.warnings) warnings.push(message);
+    const layout = layoutCollisionReport(root);
+    checks.layout = layout;
+    for (const message of layout.warnings) warnings.push(message);
+  }
+
   if (!fs.existsSync(agentsPath(root))) {
     checks.agents = { exists: false, valid: false };
     if (hasData) warnings.push('agents.json 缺失；智能体身份登记不可用。');
@@ -3109,6 +3680,31 @@ function doctorCore(opts) {
     for (const warning of runtimeReport.warnings || []) warnings.push(warning);
   }
 
+  // v0.17.0 A2：基线探针只在显式 --baseline 时运行；失败进 warnings + baselineError，并让 CLI 非零退出。
+  let baselineReport = null;
+  let baselineError = '';
+  if (opts.baseline) {
+    baselineReport = baselineCore({
+      root: root,
+      against: opts.against,
+      template: opts.template,
+      seed: opts.seed,
+      agent: opts.agent,
+      agentId: opts.agentId,
+      agentKey: opts.agentKey,
+      agentKeyFile: opts.agentKeyFile,
+    });
+    checks.baseline = baselineReport;
+    if (baselineReport.error) {
+      baselineError = baselineReport.text;
+      warnings.push(baselineReport.text);
+    } else {
+      for (const probe of baselineReport.probes || []) {
+        if (probe.status === 'fail') warnings.push('基线探针 [' + probe.id + '] 失败: ' + probe.detail);
+      }
+    }
+  }
+
   const level = critical.length ? 'critical' : (warnings.length ? 'warning' : 'ok');
   const agentHomeEnv = String(process.env.YOTTA_MEMORY_AGENT_HOME || '').trim();
   const lines = [
@@ -3120,9 +3716,19 @@ function doctorCore(opts) {
     '- agent home: ' + (agentHomeEnv || '(未设置 YOTTA_MEMORY_AGENT_HOME，按宿主默认检测)'),
     '- 备份目录: ' + (configuredDir || (cfg.backup_setup_choice === 'manual' ? '手动模式' : '(未配置)')),
   ];
+  if (checks.scale) {
+    lines.push('- 规模: ' + checks.scale.entries + ' 条记忆 / 单目录最大 ' + checks.scale.files_per_dir + ' 个文件 / 索引 ' + checks.scale.index_bytes + ' 字节 / 冷启动 ' + checks.scale.cold_start_ms + 'ms（' + (checks.scale.level === 'warning' ? '有告警' : '正常') + '）');
+  }
+  if (checks.layout && (checks.layout.duplicates || checks.layout.conflicts || checks.layout.unverified)) {
+    lines.push('- 布局: 同序号重复 ' + checks.layout.duplicates + ' 组 / 冲突 ' + checks.layout.conflicts + ' 组 / 待核 ' + checks.layout.unverified + ' 组');
+  }
   for (const message of critical) lines.push('- [严重] ' + message);
   for (const message of warnings) lines.push('- [警告] ' + message);
   if (!critical.length && !warnings.length) lines.push('- 检查项: 全部通过');
+  if (baselineReport && !baselineReport.error) {
+    lines.push('');
+    lines.push(baselineReport.text);
+  }
   if (runtimeReport) {
     lines.push('');
     lines.push(runtimeReport.text);
@@ -3140,6 +3746,8 @@ function doctorCore(opts) {
     migration_required: migration ? migration.entries : [],
     critical: critical,
     warnings: warnings,
+    baseline: baselineReport,
+    baselineError: baselineError,
     checks: checks,
     identity: identity,
     root: root,
@@ -3455,19 +4063,46 @@ function backupDrillCore(opts) {
   if (tempParent) {
     try { fs.rmSync(tempParent, { recursive: true, force: true }); } catch (_) {}
   }
-  const checks = { manifest: true, index: true, private: privateCheck };
+  // v0.17.0 A2：--probe 时在恢复副本上跑基线探针（探针只读；探针失败则整体演练失败，临时副本照旧清理）。
+  let probeReport = null;
+  if (opts.probe) {
+    probeReport = baselineCore({
+      root: target,
+      against: opts.against,
+      template: opts.template,
+      seed: opts.seed,
+      agent: opts.agent,
+      agentId: opts.agentId,
+      agentKey: opts.agentKey,
+      agentKeyFile: opts.agentKeyFile,
+    });
+    if (probeReport.error || !probeReport.ok) {
+      return fail('恢复演练失败: 基线探针未通过。\n' + probeReport.text, {
+        manifest: true,
+        index: true,
+        private: privateCheck,
+        baseline: probeReport,
+      });
+    }
+  }
+  const checks = { manifest: true, index: true, private: privateCheck, baseline: probeReport };
   const lines = [
     '恢复演练通过: ' + id,
     '- manifest / SHA-256: 通过',
     '- 恢复副本索引: 通过',
     '- 测试私密解密: ' + (privateCheck.checked ? ('通过（' + privateCheck.source + '，' + privateCheck.file + '）') : '跳过（备份中没有加密私密条目）'),
   ];
+  if (probeReport) {
+    lines.push('');
+    lines.push(probeReport.text);
+  }
   return {
     error: false,
     ok: true,
     id: id,
     restoredTo: tempParent ? '(临时副本已清理)' : target,
     checks: checks,
+    probes: probeReport ? probeReport.probes : null,
     text: lines.join('\n'),
   };
 }
@@ -3502,17 +4137,19 @@ function rememberCore(type, subject, statement, opts) {
   if (scope === 'private' && encrypted && !getOwnerKeyFor(root, owner)) {
     return { error: true, text: '私密区已加密：当前无 ' + owner + ' 的授权密钥，请在用户平台授权（yotta-memory view → 授权本智能体）后再写私密记忆。公共 FACT 不受影响。' };
   }
-  const dir = path.join(root, typeSubdir(t, owner));
+  const typeDir = path.join(root, typeSubdir(t, owner));
+  const writeDate = today(opts._today);
+  const dir = entryWriteDir(root, t, owner, writeDate);
   fs.mkdirSync(dir, { recursive: true });
-  if (fs.existsSync(dir)) {
-    for (const f of fs.readdirSync(dir)) {
-      const fp = path.join(dir, f);
-      if (!fs.statSync(fp).isFile()) continue;
+  // 去重扫描覆盖旧平铺 + 最近写入窗口，避免同一内容按两种布局各存一份。
+  const existingFiles = recentlyWrittenFiles(typeDir, dir);
+  if (existingFiles.length) {
+    for (const fp of existingFiles) {
       let parsed;
       try { parsed = parseFrontmatter(readMemoryText(root, fp, owner)); } catch (err) { continue; }
       const meta = parsed.meta;
       if ((meta.type || '').toUpperCase() === t && meta.subject === subj && meta.statement === stmt) {
-        const patch = { updated: today() };
+        const patch = { updated: writeDate };
         if (owner && !meta.owner) patch.owner = owner;
         if (scope && !meta.scope) patch.scope = scope;
         if (opts.source && !meta.source) patch.source = opts.source;
@@ -3533,12 +4170,12 @@ function rememberCore(type, subject, statement, opts) {
       }
     }
   }
-  const seq = nextSeq(dir);
+  const seq = nextSeqFor(typeDir, dir);
   const suffix = (encrypted && scope === 'private') ? ENC_SUFFIX : '';
-  const file = path.join(dir, today() + '-' + seq + '.md' + suffix);
+  const file = path.join(dir, writeDate + '-' + seq + '.md' + suffix);
   const rec = {
     type: t, subject: subj, statement: stmt,
-    confidence: 1.0, created: today(), updated: today(),
+    confidence: 1.0, created: writeDate, updated: writeDate,
     tags: [], immutable: false,
     scope: scope, owner: owner,
     source: opts.source || '',
@@ -3595,6 +4232,84 @@ function recallPrefilter(q) {
     return false;
   };
 }
+// v0.17.0：命中打分与排序抽成共享原语，recall 与 bench 用同一套逻辑（评测才不会与真实检索漂移）。
+function scoreCandidates(entries, query, options) {
+  options = options || {};
+  const useSemantic = options.semantic !== false;
+  const prefilter = options.prefilter || null;
+  const wantExplain = !!options.wantExplain;
+  const embeddingMap = options.embeddingMap || null;
+  const root = options.root ? String(options.root) : '';
+  const out = [];
+  for (const e of entries || []) {
+    let score = 0;
+    let detail = null;
+    const embeddingHit = embeddingMap ? (embeddingMap.get(root + '\0' + e.file) || null) : null;
+    if (query) {
+      if (useSemantic) {
+        if (prefilter && !prefilter(e) && !embeddingHit) continue; // v0.8.1 候选预过滤：粗筛后再语义打分；embedding 命中可越过词法预过滤
+        const m = semanticMatch(e, query, wantExplain);
+        score = m.score;
+        if (wantExplain && m.detail && m.detail.length) detail = m.detail;
+        if (embeddingHit) {
+          score = Math.max(score, embeddingHit.score);
+          if (wantExplain && embeddingHit.detail) detail = (detail || []).concat(embeddingHit.detail);
+        }
+      } else {
+        const qtoks = tokenize(query);
+        for (const tt of qtoks) { if (e.tokens && e.tokens[tt]) score += e.tokens[tt]; }
+        if (score === 0) {
+          const hay = ((e.subject || '') + ' ' + (e.statement || '') + ' ' + (e.tags || []).join(' ')).toLowerCase();
+          if (hay.indexOf(query) !== -1) score = 1;
+        }
+      }
+      if (score === 0) continue;
+    } else {
+      score = 1;
+    }
+    out.push({ entry: e, score: score, detail: detail });
+  }
+  return out;
+}
+function rankHits(hits, options) {
+  options = options || {};
+  const fuse = options.fuse !== false;
+  if (hits.length > 1 && fuse) {
+    // v0.8.0 融合排序：0.65 × 语义分归一 + 0.35 × 效用分归一
+    let minSem = Infinity, maxSem = -Infinity, minUtil = Infinity, maxUtil = -Infinity;
+    for (const h of hits) {
+      if (h.score < minSem) minSem = h.score;
+      if (h.score > maxSem) maxSem = h.score;
+      const u = utilityScore(h.entry);
+      if (u < minUtil) minUtil = u;
+      if (u > maxUtil) maxUtil = u;
+    }
+    const spanSem = maxSem - minSem;
+    const spanUtil = maxUtil - minUtil;
+    for (const h of hits) {
+      h.semNorm = spanSem > 0 ? (h.score - minSem) / spanSem : 1;
+      h.utilNorm = spanUtil > 0 ? (utilityScore(h.entry) - minUtil) / spanUtil : 1;
+      h.finalScore = 0.65 * h.semNorm + 0.35 * h.utilNorm;
+    }
+    hits.sort(function (a, b) {
+      if (b.finalScore !== a.finalScore) return b.finalScore - a.finalScore;
+      if (b.score !== a.score) return b.score - a.score;
+      const pa = a.root === projectRoot() ? 0 : 1;
+      const pb = b.root === projectRoot() ? 0 : 1;
+      if (pa !== pb) return pa - pb;
+      return String(b.entry.created).localeCompare(String(a.entry.created));
+    });
+    return hits;
+  }
+  hits.sort(function (a, b) {
+    if (options.sortByScore && b.score !== a.score) return b.score - a.score;
+    const pa = a.root === projectRoot() ? 0 : 1;
+    const pb = b.root === projectRoot() ? 0 : 1;
+    if (pa !== pb) return pa - pb;
+    return String(b.entry.created).localeCompare(String(a.entry.created));
+  });
+  return hits;
+}
 function recallCore(query, opts) {
   opts = opts || {};
   const roots = memoryRoots();
@@ -3629,13 +4344,16 @@ function recallCore(query, opts) {
   const explicitCross = !!opts.all || (!!ownerFilter && ownerFilter !== agent);
   const wantExplain = !!opts.explain;
   const useSemantic = opts.semantic !== false;
+  const yearFilter = normalizeYearList(opts.years);
+  if (yearFilter.error) return { error: true, exitCode: 2, text: yearFilter.error };
+  const years = yearFilter.years;
   const prefilter = (q && useSemantic) ? recallPrefilter(q) : null;
   const embeddingMap = new Map();
   const embeddingCommand = effectiveEmbeddingCommand(opts);
   const embeddingTimeout = effectiveEmbeddingTimeout(opts);
   if (q && embeddingCommand) {
     for (const root of roots) {
-      const rootEntries = ensureIndex(root).filter(function (e) {
+      const rootEntries = indexEntriesFor(root, { years: years }).entries.filter(function (e) {
         return classifyRead(e, agent, ownerFilter, allSafe, selfAgent) !== 'denied';
       });
       try {
@@ -3655,74 +4373,26 @@ function recallCore(query, opts) {
   const hits = [];
   let deniedCount = 0;
   for (const root of roots) {
-    const entries = ensureIndex(root);
+    const entries = indexEntriesFor(root, { years: years }).entries;
+    const readable = [];
     for (const e of entries) {
       if (onlyType && e.type !== onlyType) continue;
       const r = classifyRead(e, agent, ownerFilter, allSafe, selfAgent);
       if (r === 'denied') { deniedCount++; continue; }
-      let score = 0;
-      let detail = null;
-      const embeddingHit = embeddingMap.get(root + '\0' + e.file) || null;
-      if (q) {
-        if (useSemantic) {
-          if (prefilter && !prefilter(e) && !embeddingHit) continue; // v0.8.1 候选预过滤：粗筛后再语义打分；embedding 命中可越过词法预过滤
-          const m = semanticMatch(e, q, wantExplain);
-          score = m.score;
-          if (wantExplain && m.detail && m.detail.length) detail = m.detail;
-          if (embeddingHit) {
-            score = Math.max(score, embeddingHit.score);
-            if (wantExplain && embeddingHit.detail) {
-              detail = (detail || []).concat(embeddingHit.detail);
-            }
-          }
-        } else {
-          const qtoks = tokenize(q);
-          for (const tt of qtoks) { if (e.tokens && e.tokens[tt]) score += e.tokens[tt]; }
-          if (score === 0) {
-            const hay = ((e.subject || '') + ' ' + (e.statement || '') + ' ' + e.tags.join(' ')).toLowerCase();
-            if (hay.indexOf(q) !== -1) score = 1;
-          }
-        }
-        if (score === 0) continue;
-      } else {
-        score = 1;
-      }
-      hits.push({ entry: e, score: score, root: root, detail: detail });
-    }
-  }
-  // v0.8.0 融合排序：0.65 × 语义分归一 + 0.35 × 效用分归一
-  if (hits.length > 1) {
-    let minSem = Infinity, maxSem = -Infinity, minUtil = Infinity, maxUtil = -Infinity;
-    for (const h of hits) {
-      if (h.score < minSem) minSem = h.score;
-      if (h.score > maxSem) maxSem = h.score;
-      const u = utilityScore(h.entry);
-      if (u < minUtil) minUtil = u;
-      if (u > maxUtil) maxUtil = u;
-    }
-    const spanSem = maxSem - minSem;
-    const spanUtil = maxUtil - minUtil;
-    for (const h of hits) {
-      h.semNorm = spanSem > 0 ? (h.score - minSem) / spanSem : 1;
-      h.utilNorm = spanUtil > 0 ? (utilityScore(h.entry) - minUtil) / spanUtil : 1;
-      h.finalScore = 0.65 * h.semNorm + 0.35 * h.utilNorm;
+      readable.push(e);
     }
-    hits.sort(function (a, b) {
-      if (b.finalScore !== a.finalScore) return b.finalScore - a.finalScore;
-      if (b.score !== a.score) return b.score - a.score;
-      const pa = a.root === projectRoot() ? 0 : 1;
-      const pb = b.root === projectRoot() ? 0 : 1;
-      if (pa !== pb) return pa - pb;
-      return String(b.entry.created).localeCompare(String(a.entry.created));
-    });
-  } else {
-    hits.sort(function (a, b) {
-      const pa = a.root === projectRoot() ? 0 : 1;
-      const pb = b.root === projectRoot() ? 0 : 1;
-      if (pa !== pb) return pa - pb;
-      return String(b.entry.created).localeCompare(String(a.entry.created));
+    const scored = scoreCandidates(readable, q, {
+      semantic: useSemantic,
+      prefilter: prefilter,
+      wantExplain: wantExplain,
+      embeddingMap: embeddingMap,
+      root: root,
     });
+    for (const s of scored) {
+      hits.push({ entry: s.entry, score: s.score, root: root, detail: s.detail });
+    }
   }
+  rankHits(hits, {});
   const shown = hits.slice(0, limit);
   if (!shown.length) {
     if (deniedCount > 0 && explicitCross) {
@@ -3734,7 +4404,7 @@ function recallCore(query, opts) {
   if (touchRel.length) {
     for (const root of roots) {
       bumpReadMeta(root, touchRel);
-      touchIndex(root, touchRel);
+      touchIndex(root, touchRel, { years: years });
     }
   }
   const lines = ['共 ' + shown.length + ' 条记忆（' + (hits.length > limit ? '前 ' + limit + ' 条' : '全部') + '）：'];
@@ -3861,10 +4531,11 @@ function archiveCore(opts) {
     if (t === 'BOUND') continue; // v0.10.0 BOUND 豁免归档（边界常驻）
     // v0.8.0 统一效用分（盖棺分）替代 vitality
     if (utilityScore(meta) < threshold && createdTs < cutoff) {
-      const destDir = archiveDirFor(root, t, owner);
-      fs.mkdirSync(destDir, { recursive: true });
-      fs.renameSync(fp, path.join(destDir, path.basename(fp)));
       const rel = relOf(root, fp);
+      const dest = path.join(root, archiveRelFor(root, rel, t, owner));
+      const destDir = path.dirname(dest);
+      fs.mkdirSync(destDir, { recursive: true });
+      fs.renameSync(fp, dest);
       movedFiles.push(rel);
       moved++;
     }
@@ -4067,9 +4738,10 @@ function maintainCore(opts) {
     for (const rec of toArchive) {
       lines.push('- [' + rec.type + '] ' + rec.rel + '（utility ' + round3(rec.utility) + '，' + rec.ageDays + ' 天）— ' + (rec.meta.subject || '') + ': ' + String(rec.meta.statement || '').slice(0, 40) + (rec.type === 'COMMIT' ? '  ⚠️ COMMIT 收工纪律锚点，请确认' : ''));
       if (apply && !opts.dedup) {
-        const destDir = archiveDirFor(root, rec.type, rec.owner);
+        const dest = path.join(root, archiveRelFor(root, rec.rel, rec.type, rec.owner));
+        const destDir = path.dirname(dest);
         fs.mkdirSync(destDir, { recursive: true });
-        fs.renameSync(rec.fp, path.join(destDir, path.basename(rec.fp)));
+        fs.renameSync(rec.fp, dest);
         appendAudit(root, 'audit', { ts: new Date().toISOString(), file: rec.rel, action: 'archive', reason: 'utility<' + round3(rec.utility) + ',age>' + rec.ageDays, utility: round3(rec.utility) });
         archived++;
       }
@@ -4081,9 +4753,9 @@ function maintainCore(opts) {
     for (const rec of toForget) {
       lines.push('- [' + rec.type + '] ' + rec.rel + '（utility ' + round3(rec.utility) + '，' + rec.ageDays + ' 天）');
       if (apply && purge && !opts.dedup) {
-        const destDir = archiveDirFor(root, rec.type, rec.owner);
+        const dest = path.join(root, archiveRelFor(root, rec.rel, rec.type, rec.owner));
+        const destDir = path.dirname(dest);
         fs.mkdirSync(destDir, { recursive: true });
-        const dest = path.join(destDir, path.basename(rec.fp));
         fs.renameSync(rec.fp, dest);
         appendAudit(root, 'audit', { ts: new Date().toISOString(), file: rec.rel, action: 'forget', reason: 'utility<' + round3(rec.utility) + ',age>' + rec.ageDays + ',purge', utility: round3(rec.utility) });
         // 真删前二次确认标记：purge 已显式授权，删除 .archive 内副本前的最终动作 = 记录审计后删除
@@ -4314,6 +4986,66 @@ function promptPassword(promptText) {
   });
 }
 
+// 交互确认输入（回显明文，用于「输入 id 确认删除」这类非机密输入）。
+function promptLine(promptText) {
+  return new Promise(function (resolve) {
+    const stdin = process.stdin;
+    if (!stdin.isTTY) { resolve(null); return; }
+    process.stdout.write(promptText);
+    let buf = '';
+    function done(abort) {
+      try { stdin.setRawMode(false); } catch (e) {}
+      stdin.pause();
+      stdin.removeListener('data', onData);
+      process.stdout.write('\n');
+      resolve(abort ? null : buf);
+    }
+    function onData(chunk) {
+      const s = String(chunk);
+      for (const c of s) {
+        if (c === '\r' || c === '\n') { done(false); return; }
+        if (c === '\u0003') { done(true); return; }
+        if (c === '\u007f' || c === '\b') {
+          if (buf.length) { buf = buf.slice(0, -1); process.stdout.write('\b \b'); }
+          continue;
+        }
+        buf += c;
+        process.stdout.write(c);
+      }
+    }
+    try { stdin.setRawMode(true); } catch (e) { resolve(null); return; }
+    stdin.resume();
+    stdin.setEncoding('utf8');
+    stdin.on('data', onData);
+  });
+}
+
+async function cmdIdentityRemove(id, opts) {
+  opts = opts || {};
+  const root = userRoot();
+  if (!id) {
+    console.error('请指定 <id>：yotta-memory identity remove <id> [--dry-run] [--yes] [--keep-memories] [--keep-identity]');
+    process.exit(2);
+  }
+  let local = Object.assign({}, opts);
+  if (!local.dryRun && !local.yes && process.stdin.isTTY) {
+    const typed = await promptLine('将彻底删除 ' + id + ' 的身份与私密记忆（不可恢复；公共明文保留）。请输入 ' + id + ' 确认: ');
+    if (typed !== id) {
+      console.log('已取消：未删除任何内容。');
+      process.exit(2);
+    }
+    local.yes = true;
+  }
+  if (!local.dryRun && isEncrypted(root) && !local.password && !local.recoveryKey && !process.env.YOTTA_MEMORY_PASS) {
+    const got = await resolvePasswordInput(local, '主口令: ');
+    if (got.error) { console.error(got.error); process.exit(2); }
+    local.password = got.password;
+  }
+  const result = identityRemoveCore(root, id, local);
+  console.log(result.text);
+  if (result.error) process.exit(result.exitCode || 2);
+}
+
 function readPasswordFromStdin() {
   try {
     const text = fs.readFileSync(0, 'utf8');
@@ -4364,9 +5096,19 @@ function migrateCore(root, password, recoveryKeyIn) {
     for (const t of PRIVATE_LEAF) {
       const d = path.join(root, PRIVATE_DIR, owner, t);
       if (!fs.existsSync(d)) continue;
-      for (const f of fs.readdirSync(d)) {
-        if (!f.endsWith('.md')) continue;
-        const fp = path.join(d, f);
+      // v0.17.0：递归下探年/月子目录，明文库迁移到加密时不能漏掉分层文件。
+      const plaintexts = [];
+      const collectPlaintext = function (current) {
+        let names = [];
+        try { names = fs.readdirSync(current, { withFileTypes: true }); } catch (e) { return; }
+        for (const item of names) {
+          const fp = path.join(current, item.name);
+          if (item.isDirectory()) { collectPlaintext(fp); continue; }
+          if (item.isFile() && /\.md$/.test(item.name) && !isEncFile(fp)) plaintexts.push(fp);
+        }
+      };
+      collectPlaintext(d);
+      for (const fp of plaintexts) {
         const text = fs.readFileSync(fp, 'utf8');
         fs.writeFileSync(fp + ENC_SUFFIX, encryptMemoryText(text, ok));
         fs.unlinkSync(fp);
@@ -4533,12 +5275,256 @@ function keyRevokeCore(root, owner) {
   return { error: false, text: '已吊销 ' + owner + ' 的 agent_key binding；该 agent 将无法解密其私密。' };
 }
 
-function keyClaimCore(root, owner, opts) {
-  if (!isSafeAgentId(owner)) return { error: true, text: '非法 agent ID：只允许单段名称，禁止 /、\\、.. 和控制字符。' };
-  const location = resolveAgentKeyLocation(owner, opts);
-  if (!location.ok) return { error: true, text: location.error };
-  const pending = encPendingPath(root, owner);
-  if (!fs.existsSync(pending)) {
+// ---- v0.17.0：彻底删除一个 AI 身份 + 它的私密记忆（只能用户本人执行；公共明文保留）----
+const IDENTITY_REMOVE_STEPS = [
+  ['agents', 'agents.json 身份登记'],
+  ['owner-key', 'keys/<id>.key.enc（owner 密钥与恢复侧文件）'],
+  ['binding', 'keys/bindings/<id>.key.agent（授权绑定）'],
+  ['pending', 'keys/pending/<id>.key（待领取 key）'],
+  ['cache', 'keys/cache/<id>.key（明文缓存）'],
+  ['memories', 'private/<id>/（私密记忆 + owner 索引 + profile / distill）'],
+  ['token', '.server/tokens.json 里的 token'],
+  ['grants', 'grants.json 里的授权引用'],
+  ['reindex', '重建索引并写审计'],
+];
+function countFilesInTree(dir) {
+  let count = 0;
+  (function walk(current) {
+    let items = [];
+    try { items = fs.readdirSync(current, { withFileTypes: true }); } catch (error) { return; }
+    for (const item of items) {
+      const fp = path.join(current, item.name);
+      if (item.isDirectory()) walk(fp);
+      else if (item.isFile()) count++;
+    }
+  })(dir);
+  return count;
+}
+function identityRemoveInventory(root, id) {
+  const agents = loadAgents(root);
+  const grants = loadGrants(root);
+  const tokens = loadTokens(root);
+  const grantRefs = [];
+  for (const key of Object.keys(grants)) {
+    if (key === id) grantRefs.push(key + ' → 其它 owner');
+    if (Array.isArray(grants[key]) && grants[key].indexOf(id) !== -1) grantRefs.push(key + ' → ' + id);
+  }
+  const privateDir = path.join(root, PRIVATE_DIR, id);
+  const hasDir = fs.existsSync(privateDir);
+  return {
+    registered: !!(agents.agents && agents.agents[id]),
+    ownerKey: fs.existsSync(encOwnerKeyPath(root, id)),
+    ownerRecovery: fs.existsSync(encOwnerRecPath(root, id)),
+    binding: fs.existsSync(encAgentBindingPath(root, id)),
+    pending: fs.existsSync(encPendingPath(root, id)),
+    cache: fs.existsSync(encCachePath(root, id)),
+    memories: hasDir,
+    memoryFiles: hasDir ? countFilesInTree(privateDir) : 0,
+    token: Object.prototype.hasOwnProperty.call(tokens, id),
+    grants: grantRefs,
+  };
+}
+function identityRemoveExists(inventory) {
+  return !!(inventory.registered || inventory.ownerKey || inventory.ownerRecovery || inventory.binding
+    || inventory.pending || inventory.cache || inventory.memories || inventory.token || inventory.grants.length);
+}
+// 用户授权证明：加密库要主口令（能解开任一 owner key 或恢复材料）或恢复钥匙；
+// view 已用主口令解锁的会话视为用户本人；明文库无机密凭据可校验，要求显式 --agent user。AI 不得删除身份。
+function verifyIdentityRemoveAuthority(root, id, opts) {
+  if (opts.userUnlocked === true) return { ok: true, mode: 'view-session' };
+  if (isEncrypted(root)) {
+    const candidates = [id].concat(collectOwners(root));
+    if (opts.recoveryKey) {
+      const rk = Buffer.from(String(opts.recoveryKey), 'base64');
+      if (rk.length !== 32) return { ok: false, error: '恢复钥匙须为 32 字节（base64），已拒绝删除。' };
+      for (const owner of candidates) {
+        if (!fs.existsSync(encOwnerKeyPath(root, owner))) continue;
+        try { if (unwrapOwnerKeyRecovery(root, owner, rk)) return { ok: true, mode: 'recovery-key' }; } catch (error) { /* 试下一个 */ }
+      }
+      return { ok: false, error: '恢复钥匙无法解开任何 owner key，已拒绝删除。' };
+    }
+    const password = String(opts.password || process.env.YOTTA_MEMORY_PASS || '');
+    if (!password) {
+      return { ok: false, error: '加密库删除身份必须由用户本人执行：请提供主口令（--password / YOTTA_MEMORY_PASS / 交互输入）或 --recovery-key，或用 yotta-memory view 操作。AI 不得删除身份。' };
+    }
+    const salt = loadSalt(root);
+    if (!salt) return { ok: false, error: '密钥库损坏（缺 keys/salt），无法校验主口令；请改用 --recovery-key。' };
+    const umk = deriveUmk(password, salt);
+    for (const owner of candidates) {
+      if (!fs.existsSync(encOwnerKeyPath(root, owner))) continue;
+      try { if (unwrapOwnerKey(root, owner, umk)) return { ok: true, mode: 'password' }; } catch (error) { /* 试下一个 */ }
+    }
+    let rk = null;
+    try { rk = unwrapRecoveryEnc(root, umk); } catch (error) { rk = null; }
+    if (rk) return { ok: true, mode: 'password' };
+    return { ok: false, error: '主口令不正确（用它解不开任何 owner 密钥与恢复材料），已拒绝删除；也可以改用 --recovery-key。' };
+  }
+  if (String(opts.agent || '').trim() !== 'user') {
+    return { ok: false, error: '明文库没有可校验的用户凭据：请显式声明用户身份（CLI 加 --agent user，或用 yotta-memory view 操作）。AI 不得删除身份。' };
+  }
+  return { ok: true, mode: 'user-claim' };
+}
+function renderIdentityRemoveInventory(id, inventory, opts) {
+  const lines = [
+    '# 删除 AI 身份与私密记忆: ' + id,
+    '',
+    '将删除（私密侧；公共明文 FACT 按口径保留，其它 owner 不受影响）:',
+    '- 身份登记 agents.json: ' + (inventory.registered ? '有' : '无'),
+    '- owner 密钥 keys/' + id + '.key.enc: ' + (inventory.ownerKey ? '有' : '无') + (inventory.ownerRecovery ? '（含恢复侧文件）' : ''),
+    '- 授权绑定 / 待领取 key / 明文缓存: ' + [inventory.binding, inventory.pending, inventory.cache].map(function (x) { return x ? '有' : '无'; }).join(' / '),
+    '- 私密记忆 private/' + id + '/: ' + (inventory.memories ? inventory.memoryFiles + ' 个文件' : '无'),
+    '- token / grants 引用: ' + (inventory.token ? '有 token' : '无 token') + ' / ' + (inventory.grants.length ? inventory.grants.join('；') : '无引用'),
+  ];
+  if (opts.keepMemories) lines.push('- 开关: --keep-memories 只删身份与授权，private/' + id + '/ 保留');
+  if (opts.keepIdentity) lines.push('- 开关: --keep-identity 只删私密记忆与授权，agents.json 登记保留');
+  return lines.join('\n');
+}
+function identityRemoveCore(root, id, opts) {
+  opts = opts || {};
+  root = path.resolve(root || userRoot());
+  if (!isSafeAgentId(id)) {
+    return { error: true, exitCode: 2, removed: [], steps: [], text: '非法 agent ID：只允许单段名称，禁止 /、\\、.. 和控制字符。' };
+  }
+  const inventory = identityRemoveInventory(root, id);
+  if (!identityRemoveExists(inventory)) {
+    return { error: false, exitCode: 0, removed: [], steps: [], inventory: inventory, text: id + ' 不存在（无需处理）。' };
+  }
+  const summary = renderIdentityRemoveInventory(id, inventory, opts);
+  if (opts.dryRun) {
+    return { error: false, exitCode: 0, dryRun: true, removed: [], steps: [], inventory: inventory, text: summary + '\n\n预演结束：未改动任何文件；确认后加 --yes 执行。' };
+  }
+  const authority = verifyIdentityRemoveAuthority(root, id, opts);
+  if (!authority.ok) {
+    return { error: true, exitCode: 2, removed: [], steps: [], inventory: inventory, text: authority.error + '\n\n' + summary };
+  }
+  if (!opts.yes) {
+    return { error: true, exitCode: 2, removed: [], steps: [], inventory: inventory, text: summary + '\n\n需要显式确认：CLI 加 --yes，或在交互提示里输入完整 id。' };
+  }
+  const guard = destructiveGuardCore({
+    root: root,
+    action: 'identity_remove:' + id,
+    snapshotDir: opts.snapshotDir,
+    backupDir: opts.backupDir,
+    allowSameVolumeForTest: !!opts.allowSameVolumeForTest,
+    sameVolumeFn: opts.sameVolumeFn,
+    now: opts.now,
+  });
+  if (guard.error) {
+    return { error: true, exitCode: 2, removed: [], steps: [], inventory: inventory, doctor: guard.doctor, text: guard.text + '\n\n' + summary };
+  }
+
+  const steps = [];
+  function step(stepId, changed, detail) {
+    const meta = IDENTITY_REMOVE_STEPS.filter(function (row) { return row[0] === stepId; })[0];
+    steps.push({ id: stepId, label: meta ? meta[1] : stepId, changed: !!changed, detail: detail || '' });
+  }
+
+  if (opts.keepIdentity) {
+    step('agents', false, '按 --keep-identity 保留');
+  } else {
+    const data = loadAgents(root);
+    if (data.agents && data.agents[id]) {
+      delete data.agents[id];
+      saveAgents(root, data);
+      step('agents', true, '');
+    } else {
+      step('agents', false, '未登记');
+    }
+  }
+
+  let keyChanged = false;
+  for (const fp of [encOwnerKeyPath(root, id), encOwnerRecPath(root, id)]) {
+    if (!fs.existsSync(fp)) continue;
+    fs.unlinkSync(fp);
+    keyChanged = true;
+  }
+  step('owner-key', keyChanged, keyChanged ? 'owner key 已删除（密文不可再解）' : '无密钥文件');
+
+  const bindingPath = encAgentBindingPath(root, id);
+  const bindingChanged = fs.existsSync(bindingPath);
+  if (bindingChanged) fs.unlinkSync(bindingPath);
+  step('binding', bindingChanged, '');
+
+  const pendingChanged = removePendingAgentKey(root, id);
+  step('pending', pendingChanged, '');
+
+  const cacheChanged = revokeOwnerKeyCache(root, id);
+  step('cache', cacheChanged, '');
+
+  const privateDir = path.join(root, PRIVATE_DIR, id);
+  if (opts.keepMemories) {
+    step('memories', false, '按 --keep-memories 保留');
+  } else if (fs.existsSync(privateDir)) {
+    fs.rmSync(privateDir, { recursive: true, force: true });
+    step('memories', true, inventory.memoryFiles + ' 个文件已删除');
+  } else {
+    step('memories', false, '无目录');
+  }
+
+  const tokens = loadTokens(root);
+  if (Object.prototype.hasOwnProperty.call(tokens, id)) {
+    delete tokens[id];
+    saveTokens(root, tokens);
+    step('token', true, '');
+  } else {
+    step('token', false, '无 token');
+  }
+
+  const grants = loadGrants(root);
+  let grantChanged = false;
+  if (Object.prototype.hasOwnProperty.call(grants, id)) {
+    delete grants[id];
+    grantChanged = true;
+  }
+  for (const key of Object.keys(grants)) {
+    if (!Array.isArray(grants[key]) || grants[key].indexOf(id) === -1) continue;
+    grants[key] = grants[key].filter(function (x) { return x !== id; });
+    grantChanged = true;
+  }
+  if (grantChanged) fs.writeFileSync(path.join(root, 'grants.json'), JSON.stringify(grants, null, 2), 'utf8');
+  step('grants', grantChanged, '');
+
+  let reindexed = false;
+  try { buildIndex(root); reindexed = true; } catch (error) { reindexed = false; }
+  const auditOk = appendAudit(root, 'audit', {
+    action: 'identity_remove',
+    ts: new Date().toISOString(),
+    transaction: guard.transaction,
+    owner: id,
+    snapshot: guard.snapshot ? guard.snapshot.id : '',
+    authority: authority.mode,
+    inventory: inventory,
+    removed: steps.filter(function (s) { return s.changed; }).map(function (s) { return s.id; }),
+  });
+  step('reindex', reindexed || auditOk, 'reindex=' + (reindexed ? 'ok' : 'failed') + ' audit=' + (auditOk ? 'ok' : 'failed'));
+
+  const removed = steps.filter(function (s) { return s.changed; }).map(function (s) { return s.id; });
+  const lines = [summary, '', '执行结果（' + removed.length + ' / ' + steps.length + ' 步有改动）:'];
+  for (const row of steps) {
+    lines.push('- [' + (row.changed ? '已删除' : '未改动') + '] ' + row.label + (row.detail ? '：' + row.detail : ''));
+  }
+  lines.push('');
+  lines.push('- 事务快照: ' + (guard.snapshot ? guard.snapshot.id : '(无)'));
+  lines.push('- 公共明文 FACT 属共享事实，本命令不会删除；如需清理请单独用 forget / maintain 处理。');
+  return {
+    error: false,
+    exitCode: 0,
+    removed: removed,
+    steps: steps,
+    inventory: inventory,
+    authority: authority.mode,
+    snapshot: guard.snapshot,
+    transaction: guard.transaction,
+    text: lines.join('\n'),
+  };
+}
+
+function keyClaimCore(root, owner, opts) {
+  if (!isSafeAgentId(owner)) return { error: true, text: '非法 agent ID：只允许单段名称，禁止 /、\\、.. 和控制字符。' };
+  const location = resolveAgentKeyLocation(owner, opts);
+  if (!location.ok) return { error: true, text: location.error };
+  const pending = encPendingPath(root, owner);
+  if (!fs.existsSync(pending)) {
     return { error: true, text: '未找到待领取 agent_key：' + pending + '。请先在 yotta-memory view 中授权，或执行 yotta-memory key bind ' + owner + '。' };
   }
   let agentKey;
@@ -4873,6 +5859,25 @@ function viewServerCore(root, port, host, opts) {
         json(200, { ok: true });
       });
     }
+    if (req.method === 'POST' && pathname === '/api/identity-remove') {
+      if (!session.umk) return json(401, { error: '请先解锁。' });
+      return readBody(function (d) {
+        const owner = String((d && d.owner) || '');
+        const confirm = String((d && d.confirm) || '');
+        if (!isSafeAgentId(owner)) return json(400, { error: '非法 owner ID：只允许单段名称，禁止 /、\\、.. 和控制字符。' });
+        if (confirm !== owner) return json(400, { error: '确认串不匹配：请输入完整 agent ID 以确认删除。' });
+        const result = identityRemoveCore(root, owner, {
+          yes: true,
+          userUnlocked: true,
+          snapshotDir: opts.snapshotDir,
+          backupDir: opts.backupDir,
+          allowSameVolumeForTest: !!opts.allowSameVolumeForTest,
+          now: opts.now,
+        });
+        if (result.error) return json(400, { error: result.text });
+        json(200, { ok: true, removed: result.removed, steps: result.steps, text: result.text });
+      });
+    }
     if (req.method === 'POST' && pathname === '/api/reset-password') {
       if (!session.umk) return json(401, { error: '请先解锁。' });
       return readBody(function (d) {
@@ -5157,6 +6162,8 @@ function cmdDoctor(opts) {
   if (opts.json) console.log(JSON.stringify(r, null, 2));
   else console.log(r.text);
   if (!r.ok) process.exit(2);
+  if (r.baselineError) process.exit(2);
+  if (r.checks && r.checks.baseline && r.checks.baseline.error === false && r.checks.baseline.ok === false) process.exit(2);
 }
 function cmdReindex() {
   const roots = memoryRoots();
@@ -5218,18 +6225,20 @@ function importCore(root, src) {
     const owner = meta.owner || '';
     const scope = meta.scope || defaultScope(t);
     if (encrypted && scope === 'private' && !getOwnerKeyFor(root, owner)) { skippedPriv++; continue; }
-    const dir = path.join(root, typeSubdir(t, owner));
+    // 导入沿用条目的 created 日期决定分层目录，避免历史记忆被塞进当前月。
+    const importDate = /^\d{4}-\d{2}-\d{2}$/.test(String(meta.created || '')) ? String(meta.created) : today();
+    const dir = entryWriteDir(root, t, owner, importDate);
     fs.mkdirSync(dir, { recursive: true });
-    let seq = nextSeq(dir);
+    let seq = nextSeqFor(path.join(root, typeSubdir(t, owner)), dir);
     const suffix = (encrypted && scope === 'private') ? ENC_SUFFIX : '';
-    let file = path.join(dir, today() + '-' + seq + '.md' + suffix);
-    while (fs.existsSync(file)) { seq = String(parseInt(seq, 10) + 1).padStart(4, '0'); file = path.join(dir, today() + '-' + seq + '.md' + suffix); }
+    let file = path.join(dir, importDate + '-' + seq + '.md' + suffix);
+    while (fs.existsSync(file)) { seq = String(parseInt(seq, 10) + 1).padStart(4, '0'); file = path.join(dir, importDate + '-' + seq + '.md' + suffix); }
     const rec = {
       type: t,
       subject: meta.subject || '',
       statement: meta.statement || '',
       confidence: parseFloat(meta.confidence || 1.0),
-      created: meta.created || today(),
+      created: importDate,
       updated: meta.updated || today(),
       tags: parseTags(meta.tags),
       immutable: meta.immutable === true || meta.immutable === 'true',
@@ -5615,6 +6624,9 @@ function contextCore(opts) {
   const unsafe = !!opts.unsafe;
   const budget = opts.budget ? parseInt(opts.budget, 10) : 0;
   const focus = opts.focus ? String(opts.focus) : '';
+  const yearFilter = normalizeYearList(opts.years);
+  if (yearFilter.error) return { error: true, exitCode: 2, text: yearFilter.error };
+  const years = yearFilter.years;
   const explain = !!opts.explain;
   const embeddingCommand = effectiveEmbeddingCommand(opts);
   const embeddingTimeout = effectiveEmbeddingTimeout(opts);
@@ -5692,7 +6704,7 @@ function contextCore(opts) {
 
   const readableEntries = [];
   for (const r of roots) {
-    for (const e of ensureIndex(r)) {
+    for (const e of indexEntriesFor(r, { years: years }).entries) {
       if (classifyRead(e, owner, '', unsafe, selfAgent) === 'denied') continue;
       readableEntries.push(e);
     }
@@ -5716,6 +6728,7 @@ function contextCore(opts) {
       owner: owner,
       unsafe: unsafe,
       selfAgent: selfAgent,
+      years: years,
       embedding: embeddingCommand,
       embeddingTimeout: embeddingTimeout
     });
@@ -5805,12 +6818,1100 @@ function cmdContext(opts) {
   if (r.exitCode) process.exit(r.exitCode);
 }
 
+// ---- v0.17.0 A1: bench 可复算基准评测（只读 / 本地 / 零依赖）----
+const BENCH_SCHEMA_VERSION = 1;
+const BENCH_DEFAULT_SEED = 20260925;
+const BENCH_DEFAULT_BOOTSTRAP = 1000;
+const BENCH_AUTO_QUERY_LIMIT = 20;
+const BENCH_GATE_METRICS = {
+  recall: 'recallAtK',
+  recall_at_k: 'recallAtK',
+  mrr: 'mrr',
+  ndcg: 'ndcgAtK',
+  ndcg_at_k: 'ndcgAtK',
+  hit: 'hitRate',
+  hitrate: 'hitRate',
+  hit_rate: 'hitRate',
+};
+// 消融四组：关键词 / 语义 × 融合（0.65 语义 + 0.35 效用）/ 纯分排序
+const BENCH_VARIANTS = [
+  { variant: 'semantic-fused', semantic: true, fuse: true },
+  { variant: 'lexical-fused', semantic: false, fuse: true },
+  { variant: 'semantic-score', semantic: true, fuse: false },
+  { variant: 'lexical-score', semantic: false, fuse: false },
+];
+function sha256Hex(buf) { return crypto.createHash('sha256').update(buf).digest('hex'); }
+function round4(n) { return Math.round((Number(n) || 0) * 10000) / 10000; }
+function seededRandom(seed) {
+  let a = (Number(seed) || 0) >>> 0;
+  if (!a) a = 1;
+  return function () {
+    a = (a + 0x6D2B79F5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+// 索引指纹：index.json + 各分片内容一起哈希，改一条记忆就会变。
+function indexFingerprint(root) {
+  const manifestPath = indexPath(root);
+  if (!fs.existsSync(manifestPath)) return { sha256: '', bytes: 0, files: 0 };
+  const parts = ['ytm-index-fingerprint-v1\n'];
+  let bytes = 0;
+  let files = 0;
+  const manifestBytes = fs.readFileSync(manifestPath);
+  bytes += manifestBytes.length;
+  files++;
+  parts.push(INDEX_FILE + '\n' + sha256Hex(manifestBytes) + '\n');
+  let shards = [];
+  try {
+    const d = JSON.parse(manifestBytes.toString('utf8'));
+    if (d && Array.isArray(d.shards)) shards = d.shards;
+  } catch (e) { /* ignore */ }
+  for (const sh of shards) {
+    if (!isSafeShardName(sh)) continue;
+    const sp = path.join(root, sh);
+    if (!fs.existsSync(sp)) continue;
+    const buf = fs.readFileSync(sp);
+    bytes += buf.length;
+    files++;
+    parts.push(sh + '\n' + sha256Hex(buf) + '\n');
+  }
+  return { sha256: sha256Hex(Buffer.from(parts.join(''), 'utf8')), bytes: bytes, files: files };
+}
+function benchEvalsetDigest(queries) {
+  return sha256Hex(Buffer.from(JSON.stringify({ version: 1, queries: queries }), 'utf8'));
+}
+function autoBenchQueries(entries, seed) {
+  const pool = entries
+    .filter(function (e) { return String(e.subject || '').trim().length > 0; })
+    .sort(function (a, b) { return String(a.file).localeCompare(String(b.file)); });
+  const count = Math.min(BENCH_AUTO_QUERY_LIMIT, pool.length);
+  const remaining = pool.slice();
+  const rnd = seededRandom(seed);
+  const queries = [];
+  for (let i = 0; i < count; i++) {
+    const picked = remaining.splice(Math.floor(rnd() * remaining.length), 1)[0];
+    queries.push({ query: String(picked.subject), expect: [String(picked.file)] });
+  }
+  return queries;
+}
+function loadBenchEvalset(file, entries, seed) {
+  if (!file) {
+    const queries = autoBenchQueries(entries, seed);
+    return { source: 'auto', file: '', queries: queries, sha256: benchEvalsetDigest(queries) };
+  }
+  const fp = path.resolve(String(file));
+  if (!fs.existsSync(fp)) {
+    return { error: '找不到评测集文件: ' + fp + '。请检查路径，或省略 --evalset 用库内自动基线集。' };
+  }
+  let data = null;
+  try {
+    data = JSON.parse(fs.readFileSync(fp, 'utf8'));
+  } catch (e) {
+    return { error: '评测集不是合法 JSON: ' + fp + '（' + (e && e.message ? e.message : String(e)) + '）' };
+  }
+  if (!data || data.version !== 1) {
+    return { error: '评测集版本不支持: ' + fp + '。bench 评测集 v1 格式为 { "version": 1, "queries": [ { "query": "...", "expect": ["<记忆 id>"] } ] }。' };
+  }
+  if (!Array.isArray(data.queries) || !data.queries.length) {
+    return { error: '评测集缺少 queries: ' + fp + '。至少需要一条 { "query": "...", "expect": ["<记忆 id>"] }。' };
+  }
+  const queries = [];
+  for (const row of data.queries) {
+    const query = row && typeof row.query === 'string' ? row.query.trim() : '';
+    const expect = row && Array.isArray(row.expect) ? row.expect.map(String).filter(Boolean) : [];
+    if (!query) return { error: '评测集存在空 query: ' + fp + '。每条查询都需要非空 query 字符串。' };
+    if (!expect.length) return { error: '评测集缺少 expect: ' + fp + '（query=' + query + '）。expect 必须是记忆 id 数组。' };
+    queries.push({ query: query, expect: expect });
+  }
+  return { source: 'file', file: fp, queries: queries, sha256: benchEvalsetDigest(queries) };
+}
+function parseBenchGates(list) {
+  const out = [];
+  for (const raw of list || []) {
+    const text = String(raw);
+    const cut = text.indexOf('=');
+    if (cut <= 0) {
+      return { error: '门禁格式不正确: ' + text + '。应为 <指标>=<数值>，例如 --gate mrr=0.6；指标可选 recall / mrr / ndcg / hit。' };
+    }
+    const metric = text.slice(0, cut).trim().toLowerCase();
+    const value = parseFloat(text.slice(cut + 1));
+    if (!BENCH_GATE_METRICS[metric]) {
+      return { error: '门禁指标不支持: ' + text.slice(0, cut).trim() + '。可选指标: recall / mrr / ndcg / hit。' };
+    }
+    if (!isFinite(value)) {
+      return { error: '门禁数值不正确: ' + text + '。门禁需要可比较的数值，例如 --gate mrr=0.6。' };
+    }
+    out.push({ metric: metric, key: BENCH_GATE_METRICS[metric], value: value });
+  }
+  return { gates: out, error: '' };
+}
+function entryMatchesExpect(entry, expectSet) {
+  const ref = String((entry && entry.file) || '');
+  return expectSet.has(ref) || expectSet.has(path.basename(ref));
+}
+function benchQueryMetrics(hits, expect, k) {
+  const expectSet = new Set((expect || []).map(String));
+  const top = hits.slice(0, k);
+  let found = 0;
+  let rr = 0;
+  let dcg = 0;
+  for (let i = 0; i < top.length; i++) {
+    if (!entryMatchesExpect(top[i].entry, expectSet)) continue;
+    found++;
+    if (!rr) rr = 1 / (i + 1);
+    dcg += 1 / Math.log2(i + 2);
+  }
+  let idcg = 0;
+  const idealCount = Math.min(k, expectSet.size);
+  for (let i = 0; i < idealCount; i++) idcg += 1 / Math.log2(i + 2);
+  return {
+    recall: expectSet.size ? Math.min(1, found / expectSet.size) : 0,
+    mrr: rr,
+    ndcg: idcg > 0 ? Math.min(1, dcg / idcg) : 0,
+    hit: found ? 1 : 0,
+  };
+}
+function bootstrapCI(values, seed, rounds) {
+  if (!values.length) return [0, 0];
+  const mean = values.reduce(function (s, v) { return s + v; }, 0) / values.length;
+  const n = parseInt(rounds, 10) || 0;
+  if (n <= 0) return [round4(mean), round4(mean)];
+  const rnd = seededRandom(seed);
+  const means = [];
+  for (let b = 0; b < n; b++) {
+    let sum = 0;
+    for (let i = 0; i < values.length; i++) sum += values[Math.floor(rnd() * values.length)];
+    means.push(sum / values.length);
+  }
+  means.sort(function (a, b) { return a - b; });
+  const pick = function (p) {
+    const idx = Math.min(means.length - 1, Math.max(0, Math.floor(p * (means.length - 1))));
+    return round4(means[idx]);
+  };
+  return [pick(0.025), pick(0.975)];
+}
+function benchEvaluate(corpusByRoot, queries, options) {
+  const perQuery = [];
+  for (const row of queries) {
+    const prefilter = options.semantic ? recallPrefilter(row.query) : null;
+    const hits = [];
+    for (const group of corpusByRoot) {
+      const scored = scoreCandidates(group.entries, row.query, { semantic: options.semantic, prefilter: prefilter });
+      for (const s of scored) hits.push({ entry: s.entry, score: s.score, root: group.root, detail: s.detail });
+    }
+    rankHits(hits, { fuse: options.fuse !== false, sortByScore: options.fuse === false });
+    perQuery.push(benchQueryMetrics(hits, row.expect, options.k));
+  }
+  const mean = function (pick) {
+    if (!perQuery.length) return 0;
+    return perQuery.reduce(function (s, row) { return s + pick(row); }, 0) / perQuery.length;
+  };
+  const metrics = {
+    recallAtK: round4(mean(function (r) { return r.recall; })),
+    mrr: round4(mean(function (r) { return r.mrr; })),
+    ndcgAtK: round4(mean(function (r) { return r.ndcg; })),
+    hitRate: round4(mean(function (r) { return r.hit; })),
+  };
+  const ci95 = {
+    recallAtK: bootstrapCI(perQuery.map(function (r) { return r.recall; }), options.seed, options.bootstrap),
+    mrr: bootstrapCI(perQuery.map(function (r) { return r.mrr; }), options.seed, options.bootstrap),
+    ndcgAtK: bootstrapCI(perQuery.map(function (r) { return r.ndcg; }), options.seed, options.bootstrap),
+    hitRate: bootstrapCI(perQuery.map(function (r) { return r.hit; }), options.seed, options.bootstrap),
+  };
+  return { metrics: metrics, ci95: ci95, perQuery: perQuery.length };
+}
+function benchCore(opts) {
+  opts = opts || {};
+  const k = parseInt(opts.k, 10) > 0 ? Math.min(50, parseInt(opts.k, 10)) : 5;
+  const seed = opts.seed === undefined || opts.seed === null || isNaN(parseInt(opts.seed, 10)) ? BENCH_DEFAULT_SEED : parseInt(opts.seed, 10);
+  if (seed < 0) return { error: true, exitCode: 2, text: '随机种子必须是非负整数: ' + opts.seed };
+  const bootstrap = opts.bootstrap === undefined || opts.bootstrap === null || isNaN(parseInt(opts.bootstrap, 10)) ? BENCH_DEFAULT_BOOTSTRAP : parseInt(opts.bootstrap, 10);
+  if (bootstrap < 0) return { error: true, exitCode: 2, text: 'bootstrap 次数必须是非负整数: ' + opts.bootstrap };
+  const yearFilter = normalizeYearList(opts.years);
+  if (yearFilter.error) return { error: true, exitCode: 2, text: yearFilter.error };
+  const years = yearFilter.years;
+  const gates = parseBenchGates(opts.gate);
+  if (gates.error) return { error: true, exitCode: 2, text: gates.error };
+
+  const roots = memoryRoots();
+  if (!roots.length) return { error: true, exitCode: 2, text: '记忆库不存在，请先运行: yotta-memory init' };
+  const ident = resolveIdentity(opts);
+  if (ident.error) return { error: true, exitCode: 3, text: ident.error };
+  const selfAgent = ident.id;
+
+  const corpusByRoot = [];
+  const rootReports = [];
+  let denied = 0;
+  let privateSkipped = 0;
+  for (const root of roots) {
+    const pub = loadIndexFor(root, { years: years });
+    if (!pub) {
+      return { error: true, exitCode: 2, text: '索引缺失或版本过旧（' + root + '）：请先运行 yotta-memory reindex，再执行 bench。' };
+    }
+    const entries = [];
+    for (const e of pub) {
+      if (classifyRead(e, selfAgent, '', false, selfAgent) === 'denied') { denied++; continue; }
+      entries.push(e);
+    }
+    if (isEncrypted(root)) {
+      for (const owner of collectOwners(root)) {
+        const key = getOwnerKeyFor(root, owner, { id: ident.id, agentKey: ident.agentKey });
+        if (!key) { privateSkipped++; continue; }
+        let idx = [];
+        try { idx = loadOwnerIndex(root, owner, key); } catch (err) { idx = []; }
+        for (const e of idx) {
+          if (years.length && years.indexOf(entryYear(e)) === -1) continue;
+          if (classifyRead(e, selfAgent, '', false, selfAgent) === 'denied') { denied++; continue; }
+          entries.push(e);
+        }
+      }
+    }
+    corpusByRoot.push({ root: root, entries: entries });
+    rootReports.push({ path: root, entries: entries.length, index: indexFingerprint(root) });
+  }
+  const corpusEntries = [];
+  for (const group of corpusByRoot) for (const e of group.entries) corpusEntries.push(e);
+
+  const evalset = loadBenchEvalset(opts.evalset, corpusEntries, seed);
+  if (evalset.error) return { error: true, exitCode: 2, text: evalset.error };
+
+  const baseOptions = { k: k, seed: seed, bootstrap: bootstrap, semantic: true, fuse: true };
+  let timing = null;
+  if (opts.timing) {
+    const samples = [];
+    for (const row of evalset.queries) {
+      const started = process.hrtime.bigint();
+      benchEvaluate(corpusByRoot, [row], baseOptions);
+      samples.push(Number(process.hrtime.bigint() - started) / 1e6);
+    }
+    samples.sort(function (a, b) { return a - b; });
+    const pick = function (p) { return round4(samples[Math.min(samples.length - 1, Math.max(0, Math.round(p * (samples.length - 1))))]); };
+    timing = { p50Ms: pick(0.5), p95Ms: pick(0.95) };
+  }
+  const baseline = benchEvaluate(corpusByRoot, evalset.queries, baseOptions);
+  const gateResults = (gates.gates || []).map(function (g) {
+    const actual = baseline.metrics[g.key];
+    return { metric: g.metric, value: g.value, actual: actual, pass: actual >= g.value };
+  });
+  const level = gateResults.every(function (g) { return g.pass; }) ? 'ok' : 'fail';
+  const report = {
+    schemaVersion: BENCH_SCHEMA_VERSION,
+    command: 'bench',
+    version: VERSION,
+    params: { k: k, seed: seed, bootstrap: bootstrap },
+    corpus: {
+      entries: corpusEntries.length,
+      denied: denied,
+      privateSkipped: privateSkipped,
+      roots: rootReports,
+    },
+    evalset: {
+      source: evalset.source,
+      file: evalset.file || '',
+      sha256: evalset.sha256,
+      queries: evalset.queries.length,
+    },
+    metrics: Object.assign({}, baseline.metrics, { ci95: baseline.ci95 }),
+    gates: gateResults,
+    embedding: {
+      status: 'not-run',
+      reason: 'bench 只跑本地确定性检索（关键词 / 语义），不调用外部 embedding 插件，保证可复算与只读',
+    },
+    reproducible: !opts.timing,
+    level: level,
+  };
+  if (years.length) report.years = years.slice();
+  if (opts.ablate) {
+    report.ablation = BENCH_VARIANTS.map(function (v) {
+      const result = benchEvaluate(corpusByRoot, evalset.queries, { k: k, seed: seed, bootstrap: bootstrap, semantic: v.semantic, fuse: v.fuse });
+      return { variant: v.variant, metrics: result.metrics };
+    });
+  }
+  if (timing) report.timing = timing;
+  return { error: false, exitCode: level === 'fail' ? 1 : 0, text: renderBenchText(report), report: report };
+}
+function renderBenchText(report) {
+  const lines = [];
+  const m = report.metrics;
+  lines.push('# 元忆基准评测（bench）');
+  lines.push('');
+  lines.push('- 记忆库: ' + report.corpus.roots.map(function (r) { return r.path; }).join('、'));
+  lines.push('- 条目数: ' + report.corpus.entries +
+    '；索引指纹: ' + report.corpus.roots.map(function (r) { return String(r.index.sha256).slice(0, 12) + '…'; }).join('、') +
+    '（' + report.corpus.roots.map(function (r) { return r.index.files + ' 个文件 / ' + r.index.bytes + ' 字节'; }).join('；') + '）');
+  lines.push('- 评测集: ' + (report.evalset.source === 'auto' ? '库内自动基线集（确定性抽样）' : report.evalset.file) +
+    '；sha256 ' + report.evalset.sha256.slice(0, 12) + '…；' + report.evalset.queries + ' 条查询');
+  lines.push('- 参数: k=' + report.params.k + '；seed=' + report.params.seed + '；bootstrap=' + report.params.bootstrap +
+    (report.years && report.years.length ? '；年份=' + report.years.join(',') : ''));
+  lines.push('');
+  lines.push('检索质量：');
+  lines.push('- Recall@' + report.params.k + ': ' + m.recallAtK + '（95% CI ' + m.ci95.recallAtK[0] + ' - ' + m.ci95.recallAtK[1] + '）');
+  lines.push('- MRR: ' + m.mrr + '（95% CI ' + m.ci95.mrr[0] + ' - ' + m.ci95.mrr[1] + '）');
+  lines.push('- nDCG@' + report.params.k + ': ' + m.ndcgAtK + '（95% CI ' + m.ci95.ndcgAtK[0] + ' - ' + m.ci95.ndcgAtK[1] + '）');
+  lines.push('- HitRate: ' + m.hitRate + '（95% CI ' + m.ci95.hitRate[0] + ' - ' + m.ci95.hitRate[1] + '）');
+  if (report.ablation && report.ablation.length) {
+    lines.push('');
+    lines.push('消融对比：');
+    for (const row of report.ablation) {
+      lines.push('- ' + row.variant + ': Recall@' + report.params.k + ' ' + row.metrics.recallAtK +
+        '；MRR ' + row.metrics.mrr + '；nDCG@' + report.params.k + ' ' + row.metrics.ndcgAtK + '；HitRate ' + row.metrics.hitRate);
+    }
+    lines.push('- 口径: 关键词 / 语义 × 融合排序（0.65 语义 + 0.35 效用）/ 纯分排序；embedding 插件不参与。');
+  }
+  if (report.timing) {
+    lines.push('');
+    lines.push('检索耗时（--timing，非可复算项）：');
+    lines.push('- p50: ' + report.timing.p50Ms + ' ms；p95: ' + report.timing.p95Ms + ' ms');
+  }
+  lines.push('');
+  lines.push('门禁：');
+  if (!report.gates.length) {
+    lines.push('- 未设置（--gate <指标>=<数值> 可接入 CI）');
+  } else {
+    for (const g of report.gates) {
+      lines.push('- ' + g.metric + ' >= ' + g.value + '：' + (g.pass ? '通过' : '未通过') + '（实际 ' + g.actual + '）');
+    }
+  }
+  if (report.corpus.denied) lines.push('- 已跳过 ' + report.corpus.denied + ' 条当前身份不可读的记忆');
+  lines.push('');
+  lines.push('复算口径：库指纹 + 评测集指纹 + 参数一致时必须同输出；默认报告不含墙钟时间，只读、不写生产库。');
+  return lines.join('\n');
+}
+function cmdBench(opts) {
+  const r = benchCore(opts || {});
+  if (r.error) {
+    console.error(r.text);
+    process.exit(r.exitCode || 2);
+  }
+  const json = JSON.stringify(r.report, null, 2);
+  if (opts && opts.out) {
+    const target = path.resolve(String(opts.out));
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, json + '\n', 'utf8');
+  }
+  console.log(opts && opts.json ? json : r.text);
+  if (r.exitCode) process.exit(r.exitCode);
+}
+
+// ---- v0.17.0 A2：恢复 / 迁移基线探针（只读 / 本地 / 零依赖）----
+const BASELINE_SCHEMA_VERSION = 1;
+const BASELINE_DEFAULT_SEED = 20260925;
+const BASELINE_MISSING_LIMIT = 20;
+const CJK_RE = /[\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff]/;
+// 探针只读遍历记忆文件（不建索引、不碰访问计数）：恢复 / 迁移场景要验的是文件本身，而不是可能过期的索引。
+function baselineReadEntries(root) {
+  const entries = [];
+  const unreadable = [];
+  for (const fp of collectEntryFiles(root)) {
+    const rel = relOf(root, fp);
+    const owner = ownerFromPrivatePath(root, fp);
+    if (isEncFile(fp) && !getOwnerKeyFor(root, owner)) {
+      unreadable.push({ file: rel, reason: 'encrypted', owner: owner });
+      continue;
+    }
+    try {
+      entries.push(readEntry(fp, root));
+    } catch (error) {
+      const message = error && error.message ? error.message : String(error);
+      // .enc 后缀但内容是明文（历史恢复残留）与「密钥在位但解不开」要分开报，修法完全不同。
+      const reason = isEncFile(fp) ? (message.indexOf('非密文文件') !== -1 ? 'mislabelled' : 'undecryptable') : 'unreadable';
+      unreadable.push({ file: rel, reason: reason, owner: owner, error: message });
+    }
+  }
+  return { entries: entries, unreadable: unreadable };
+}
+// 条目身份键与布局无关（旧平铺 facts/x.md 与新年/月分层指向同一条记忆时键相同）。
+function baselineEntryKey(entry) {
+  return String(entry.type || 'FACT') + '/' + String(entry.owner || 'public') + '/' + path.basename(String(entry.file || ''));
+}
+function baselineSample(pool, seed, count) {
+  const list = pool.slice().sort(function (a, b) { return String(a.file).localeCompare(String(b.file)); });
+  const rnd = seededRandom(seed);
+  const picked = [];
+  const remaining = list.slice();
+  for (let i = 0; i < Math.min(count, remaining.length); i++) {
+    picked.push(remaining.splice(Math.floor(rnd() * remaining.length), 1)[0]);
+  }
+  return picked;
+}
+function baselineRecall(root, entries, query, limit) {
+  const prefilter = query ? recallPrefilter(query) : null;
+  const hits = [];
+  for (const scored of scoreCandidates(entries, query, { semantic: true, prefilter: prefilter, root: root })) {
+    hits.push({ entry: scored.entry, score: scored.score, root: root, detail: scored.detail });
+  }
+  rankHits(hits, { fuse: true });
+  return hits.slice(0, limit || 5);
+}
+function loadBaselineTemplate(file) {
+  const fp = path.resolve(String(file));
+  if (!fs.existsSync(fp)) {
+    return { error: '找不到基线模板: ' + fp + '。请检查路径，或省略 --template 用库内确定性探针。' };
+  }
+  let data = null;
+  try {
+    data = JSON.parse(fs.readFileSync(fp, 'utf8'));
+  } catch (error) {
+    return { error: '基线模板不是合法 JSON: ' + fp + '（' + (error && error.message ? error.message : String(error)) + '）' };
+  }
+  if (!data || data.version !== 1) {
+    return { error: '基线模板版本不支持: ' + fp + '。v1 格式为 { "version": 1, "expect_owners": [], "expect_min_entries": 0, "expect_types": {}, "queries": [] }。' };
+  }
+  const out = { version: 1, file: fp, expect_owners: [], expect_min_entries: 0, expect_types: {}, queries: [] };
+  if (data.expect_owners !== undefined) {
+    if (!Array.isArray(data.expect_owners)) return { error: '基线模板 expect_owners 必须是数组: ' + fp };
+    out.expect_owners = data.expect_owners.map(String).filter(Boolean);
+  }
+  if (data.expect_min_entries !== undefined) {
+    const n = parseInt(data.expect_min_entries, 10);
+    if (!isFinite(n) || n < 0) return { error: '基线模板 expect_min_entries 必须是非负整数: ' + fp };
+    out.expect_min_entries = n;
+  }
+  if (data.expect_types !== undefined) {
+    if (!data.expect_types || typeof data.expect_types !== 'object' || Array.isArray(data.expect_types)) {
+      return { error: '基线模板 expect_types 必须是 { "类型": 最小条数 } 对象: ' + fp };
+    }
+    for (const key of Object.keys(data.expect_types)) {
+      const type = String(key).toUpperCase();
+      if (TYPES.indexOf(type) === -1) {
+        return { error: '基线模板 expect_types 含未知类型 ' + key + '（可选: ' + TYPES.join(' / ') + '）: ' + fp };
+      }
+      const n = parseInt(data.expect_types[key], 10);
+      if (!isFinite(n) || n < 0) return { error: '基线模板 expect_types.' + key + ' 必须是非负整数: ' + fp };
+      out.expect_types[type] = n;
+    }
+  }
+  if (data.queries !== undefined) {
+    if (!Array.isArray(data.queries)) return { error: '基线模板 queries 必须是数组: ' + fp };
+    for (const row of data.queries) {
+      const query = row && typeof row.query === 'string' ? row.query.trim() : '';
+      const expect = row && Array.isArray(row.expect) ? row.expect.map(String).filter(Boolean) : [];
+      if (!query) return { error: '基线模板存在空 query: ' + fp };
+      if (!expect.length) return { error: '基线模板缺少 expect（query=' + query + '）: ' + fp };
+      out.queries.push({ id: String((row && row.id) || query), query: query, expect: expect });
+    }
+  }
+  return out;
+}
+// 六类固定探针：身份 / 近期 / 仅源库独有 / CJK / 操作规则 / owner 范围；模板可在其上追加显式期望。
+function baselineCore(opts) {
+  opts = opts || {};
+  const root = path.resolve(opts.root || userRoot());
+  const seed = parseInt(opts.seed, 10) || BASELINE_DEFAULT_SEED;
+  const empty = { schemaVersion: BASELINE_SCHEMA_VERSION, error: true, exitCode: 2, ok: false, level: 'fail', root: root, against: '', template: '', seed: seed, counts: {}, probes: [], unreadable: [] };
+  let template = null;
+  if (opts.template) {
+    template = loadBaselineTemplate(opts.template);
+    if (template.error) return Object.assign({}, empty, { text: template.error });
+  }
+  const against = opts.against ? path.resolve(String(opts.against)) : '';
+  if (against && !fs.existsSync(against)) {
+    return Object.assign({}, empty, { against: against, text: '找不到对比库: ' + against + '。--against 需要指向另一个记忆库根目录（通常是迁移前的源库）。' });
+  }
+  const ident = resolveIdentity(opts);
+  const selfAgent = (ident && !ident.error && ident.id) ? ident.id : '';
+  const read = baselineReadEntries(root);
+  const entries = read.entries;
+  const readable = entries.filter(function (e) { return classifyRead(e, selfAgent, '', false, selfAgent) !== 'denied'; });
+  const probes = [];
+  const baselineCounts = {};
+  function record(id, title, status, detail) {
+    probes.push({ id: id, title: title, status: status, detail: detail });
+  }
+  function recallProbe(id, title, pick) {
+    const query = String(pick.subject || '').trim() || String(pick.statement || '').trim().slice(0, 24);
+    const hits = baselineRecall(root, readable, query, 5);
+    const expect = new Set([String(pick.file)]);
+    if (query && hits.some(function (h) { return entryMatchesExpect(h.entry, expect); })) {
+      record(id, title, 'pass', '可召回: ' + pick.file);
+    } else {
+      record(id, title, 'fail', '无法召回: ' + pick.file + '（按该条目自己的主题检索未命中）');
+    }
+  }
+
+  // ① 身份：agents.json / iam 在位
+  const expectedOwners = template ? template.expect_owners : [];
+  const agentsFile = agentsPath(root);
+  if (!fs.existsSync(agentsFile)) {
+    if (entries.length) record('identity', '身份登记', 'fail', '缺少 agents.json（智能体身份登记）；恢复后请用 yotta-memory iam <id> 重新登记。');
+    else record('identity', '身份登记', 'skip', '库内没有记忆条目且没有 agents.json，暂不判定。');
+  } else {
+    let data = null;
+    let parseError = '';
+    try { data = JSON.parse(fs.readFileSync(agentsFile, 'utf8')); } catch (error) { parseError = error && error.message ? error.message : String(error); }
+    const registered = data && data.agents && typeof data.agents === 'object' ? Object.keys(data.agents) : [];
+    if (parseError) {
+      record('identity', '身份登记', 'fail', 'agents.json 无法解析（' + parseError + '）；请先恢复身份登记。');
+    } else if (!registered.length) {
+      record('identity', '身份登记', 'fail', 'agents.json 没有任何智能体登记；恢复后请用 yotta-memory iam <id> 重新登记。');
+    } else {
+      const missingOwners = expectedOwners.filter(function (o) { return registered.indexOf(o) === -1; });
+      if (missingOwners.length) {
+        record('identity', '身份登记', 'fail', 'agents.json 缺少模板要求的 owner: ' + missingOwners.join(', ') + '（已登记: ' + registered.join(', ') + '）');
+      } else {
+        record('identity', '身份登记', 'pass', 'agents.json 已登记 ' + registered.join(', '));
+      }
+    }
+  }
+
+  // ② 近期：最近条目可召回
+  const byRecency = readable.slice().sort(function (a, b) {
+    return String(b.created || '').localeCompare(String(a.created || '')) || String(b.file).localeCompare(String(a.file));
+  });
+  if (!byRecency.length) record('recent', '近期条目', 'skip', '没有当前身份可读的记忆条目。');
+  else recallProbe('recent', '近期条目', byRecency[0]);
+
+  // ③ 仅源库独有：--against 差集条目必须已在目标库
+  if (!against) {
+    record('source-only', '对比库差集', 'skip', '未提供 --against 对比库，跳过迁移差集校验。');
+  } else {
+    const sourceRead = baselineReadEntries(against);
+    const targetKeys = new Set(entries.map(baselineEntryKey));
+    const sourceKeys = new Set();
+    const missing = [];
+    for (const e of sourceRead.entries) {
+      const key = baselineEntryKey(e);
+      if (sourceKeys.has(key)) continue;
+      sourceKeys.add(key);
+      if (!targetKeys.has(key)) missing.push(e);
+    }
+    let targetOnly = 0;
+    for (const key of targetKeys) if (!sourceKeys.has(key)) targetOnly++;
+    const counts = { source_entries: sourceRead.entries.length, missing: missing.length, target_only: targetOnly };
+    if (missing.length) {
+      const shown = missing.slice(0, BASELINE_MISSING_LIMIT).map(function (e) { return e.file; });
+      record('source-only', '对比库差集', 'fail', '相对对比库缺失 ' + missing.length + ' 条: ' + shown.join(', ') + (missing.length > shown.length ? ' …' : ''));
+    } else {
+      record('source-only', '对比库差集', 'pass', '对比库 ' + sourceRead.entries.length + ' 条全部在目标库命中' + (targetOnly ? '（目标库另有 ' + targetOnly + ' 条新增）' : ''));
+    }
+    baselineCounts.sourceOnly = counts;
+  }
+
+  // ④ CJK：中文条目可召回
+  const cjkPool = readable.filter(function (e) { return CJK_RE.test(String(e.subject || '') + String(e.statement || '')); });
+  if (!cjkPool.length) record('cjk', '中文条目', 'skip', '没有当前身份可读的中文条目。');
+  else recallProbe('cjk', '中文条目', baselineSample(cjkPool, seed, 1)[0]);
+
+  // ⑤ 操作规则：BOUND 类可读
+  const boundPool = entries.filter(function (e) { return e.type === 'BOUND'; });
+  if (!boundPool.length) {
+    record('rules', '操作规则', 'skip', '库内没有 BOUND 操作规则条目。');
+  } else {
+    const pick = boundPool.slice().sort(function (a, b) { return String(a.file).localeCompare(String(b.file)); })[0];
+    const fp = path.join(root, String(pick.file));
+    try {
+      readEntry(fp, root);
+      record('rules', '操作规则', 'pass', 'BOUND 规则可读: ' + pick.file);
+    } catch (error) {
+      const owner = ownerFromPrivatePath(root, fp);
+      if (isEncFile(fp) && !getOwnerKeyFor(root, owner)) {
+        record('rules', '操作规则', 'skip', 'BOUND 规则为加密私密条目，缺少 ' + owner + ' 的授权密钥，未做可读性验证。');
+      } else {
+        record('rules', '操作规则', 'fail', 'BOUND 规则不可读: ' + pick.file + '（' + (error && error.message ? error.message : String(error)) + '）');
+      }
+    }
+  }
+
+  // ⑥ owner 范围：各 owner 计数 + 模板条数期望
+  const ownerCounts = {};
+  for (const fp of collectEntryFiles(root)) {
+    const owner = ownerFromPrivatePath(root, fp) || 'public';
+    ownerCounts[owner] = (ownerCounts[owner] || 0) + 1;
+  }
+  baselineCounts.owners = ownerCounts;
+  const ownerNames = Object.keys(ownerCounts).sort();
+  const corrupted = read.unreadable.filter(function (u) { return u.reason !== 'encrypted'; });
+  if (!ownerNames.length) {
+    record('owner', 'owner 范围', 'skip', '库内没有记忆文件。');
+  } else if (corrupted.length) {
+    const labels = { undecryptable: '密钥在位但解不开', mislabelled: '.enc 后缀但内容是明文', unreadable: '读取失败' };
+    const reasonCounts = {};
+    for (const item of corrupted) reasonCounts[item.reason] = (reasonCounts[item.reason] || 0) + 1;
+    const summary = Object.keys(reasonCounts).map(function (reason) {
+      return (labels[reason] || reason) + ' ' + reasonCounts[reason] + ' 个';
+    }).join('；');
+    record('owner', 'owner 范围', 'fail', '存在无法作为记忆读取的文件: ' + summary + '；例如 ' + corrupted.slice(0, 5).map(function (u) { return u.file; }).join(', '));
+  } else if (template && template.expect_min_entries && entries.length < template.expect_min_entries) {
+    const parts = ownerNames.map(function (o) { return o + '=' + ownerCounts[o]; });
+    record('owner', 'owner 范围', 'fail', '记忆条数 ' + entries.length + ' 少于模板要求的 ' + template.expect_min_entries + '：缺少 ' + (template.expect_min_entries - entries.length) + ' 条（owner: ' + parts.join(', ') + '）');
+  } else {
+    const typeCounts = {};
+    for (const e of entries) typeCounts[e.type] = (typeCounts[e.type] || 0) + 1;
+    const shortTypes = [];
+    const expectedTypes = template ? template.expect_types : {};
+    for (const type of Object.keys(expectedTypes)) {
+      const got = typeCounts[type] || 0;
+      if (got < expectedTypes[type]) shortTypes.push(type + ' 缺少 ' + (expectedTypes[type] - got) + ' 条');
+    }
+    const parts = ownerNames.map(function (o) { return o + '=' + ownerCounts[o]; });
+    if (shortTypes.length) {
+      record('owner', 'owner 范围', 'fail', '模板要求的类型条数不足: ' + shortTypes.join('；') + '（owner: ' + parts.join(', ') + '）');
+    } else {
+      record('owner', 'owner 范围', 'pass', 'owner 计数: ' + parts.join(', ') + (read.unreadable.length ? '（另有 ' + read.unreadable.length + ' 个加密条目未读取）' : ''));
+    }
+  }
+
+  // 模板显式查询（可选追加探针，不替代上面六类）
+  if (template && template.queries.length) {
+    const failed = [];
+    for (const row of template.queries) {
+      const hits = baselineRecall(root, readable, row.query, 5);
+      const expect = new Set(row.expect);
+      if (!hits.some(function (h) { return entryMatchesExpect(h.entry, expect); })) failed.push(row.id);
+    }
+    if (failed.length) record('template-queries', '模板查询', 'fail', '模板查询未命中: ' + failed.join(', ') + '（共 ' + template.queries.length + ' 条）');
+    else record('template-queries', '模板查询', 'pass', '模板查询全部命中（共 ' + template.queries.length + ' 条）');
+  }
+
+  const fails = probes.filter(function (p) { return p.status === 'fail'; });
+  const skips = probes.filter(function (p) { return p.status === 'skip'; });
+  const counts = {
+    entries: entries.length,
+    readable: readable.length,
+    unreadable: read.unreadable.length,
+    owners: baselineCounts.owners,
+    missing: baselineCounts.sourceOnly ? baselineCounts.sourceOnly.missing : 0,
+    target_only: baselineCounts.sourceOnly ? baselineCounts.sourceOnly.target_only : 0,
+    source_entries: baselineCounts.sourceOnly ? baselineCounts.sourceOnly.source_entries : 0,
+  };
+  const report = {
+    schemaVersion: BASELINE_SCHEMA_VERSION,
+    error: false,
+    ok: fails.length === 0,
+    level: fails.length ? 'fail' : 'pass',
+    root: root,
+    against: against,
+    template: template ? template.file : '',
+    seed: seed,
+    counts: counts,
+    probes: probes,
+    unreadable: read.unreadable,
+  };
+  const statusLabel = { pass: '通过', fail: '失败', skip: '跳过' };
+  const lines = [
+    '# 元忆基线探针（恢复 / 迁移）',
+    '',
+    '- 记忆库: ' + root,
+    '- 对比库: ' + (against || '(未提供，跳过差集校验)'),
+    '- 条目: ' + counts.entries + ' 条可读 / ' + counts.readable + ' 条当前身份可读 / ' + counts.unreadable + ' 个未读取',
+    '- 结果: ' + (report.ok ? '通过' : '失败') + '（通过 ' + (probes.length - fails.length - skips.length) + ' / 失败 ' + fails.length + ' / 跳过 ' + skips.length + '）',
+  ];
+  for (const probe of probes) {
+    lines.push('- [' + statusLabel[probe.status] + '] ' + probe.title + ' · ' + probe.detail);
+  }
+  if (fails.length) lines.push('- 缺失项清单: ' + fails.map(function (p) { return p.id; }).join(', '));
+  report.text = lines.join('\n');
+  return report;
+}
+
+// ---- v0.17.0 A4：记忆库安全扫描（默认只读 / 本地 / 零依赖）----
+// 分工口径：元钥扫源码仓库、元信扫技能包、元忆扫记忆库。规则词表不另起一套——
+// 每条规则的 ref 指向家族规则表里的原始规则 id（<规则 id>@<技能 slug>），
+// test/memory-scan.test.js 会在源码仓库内逐条回查这些规则 id 在对应技能里是否仍存在。
+const SCAN_SCHEMA_VERSION = 1;
+const SCAN_CLASSES = ['malicious-instruction', 'prompt-injection', 'credential-leak', 'data-exfiltration', 'guardrail-bypass', 'behavior-manipulation', 'privilege-escalation'];
+const SCAN_SEVERITIES = ['safe', 'low', 'medium', 'high', 'critical'];
+const SCAN_MAX_FINDINGS = 500;
+const SCAN_MAX_FILES = 20000;
+const SCAN_QUARANTINE_DIR = '.memory-scan';
+const MEMORY_SCAN_RULES = [
+  // ── 恶意指令（元安 DownloadExec / 元盾危险命令）──
+  { id: 'YTM-MAL-001', class: 'malicious-instruction', severity: 'critical', ref: 'DEX-001@yotta-security-audit', title: 'curl 下载内容交给 shell 执行', mask: false, re: /\bcurl\b[^\n|;]{0,120}\|\s*(?:ba)?sh\b/i },
+  { id: 'YTM-MAL-002', class: 'malicious-instruction', severity: 'critical', ref: 'CMD-PIPE-WGET@yotta-guardian', title: 'wget 下载内容交给 shell 执行', mask: false, re: /\bwget\b[^\n|;]{0,120}\|\s*(?:ba)?sh\b/i },
+  { id: 'YTM-MAL-003', class: 'malicious-instruction', severity: 'critical', ref: 'CMD-REV-BASH@yotta-guardian', title: '反弹 shell', mask: false, re: /\b(?:bash\s+-i\s*>&?\s*\/dev\/tcp|nc\s+-e\s+\/bin\/(?:ba)?sh)\b/i },
+  { id: 'YTM-MAL-004', class: 'malicious-instruction', severity: 'high', ref: 'CMD-PS-ENCODED@yotta-guardian', title: '编码后的 PowerShell 命令', mask: false, re: /powershell(?:\.exe)?[^\n]{0,40}\s-(?:enc|e|encodedcommand)\b/i },
+  // ── Prompt 注入（元信 PIJ）──
+  { id: 'YTM-PIJ-001', class: 'prompt-injection', severity: 'high', ref: 'PIJ-001@yotta-verify', title: '要求忽略之前的指令', mask: false, re: /(?:ignore|disregard|forget|overlook|skip)\s+(?:all\s+|any\s+|the\s+|previous\s+)*(?:previous\s+|earlier\s+)*(?:instructions?|prompts?|directives?|guidelines?|rules?|context|messages?)/i },
+  { id: 'YTM-PIJ-002', class: 'prompt-injection', severity: 'high', ref: 'PIJ-002@yotta-verify', title: '要求忽略之前指令（中文）', mask: false, re: /(?:忽略|无视|忘记|不要理会|别管|忘掉)(?:之前|以上|前面|所有|一切)?(?:的)?(?:指令|提示|设定|规则|上下文|内容)/ },
+  { id: 'YTM-PIJ-003', class: 'prompt-injection', severity: 'high', ref: 'PIJ-009@yotta-verify', title: '伪系统消息', mask: false, re: /(?:以下内容|下面这段|注意).{0,30}(?:系统消息|系统指令|来自系统|这是系统)/ },
+  { id: 'YTM-PIJ-004', class: 'prompt-injection', severity: 'medium', ref: 'PIJ-014@yotta-verify', title: '伪系统标签', mask: false, re: /<\s*(?:system|sysadmin)\s*(?:message|prompt|instruction|role)?\s*>/i },
+  { id: 'YTM-PIJ-005', class: 'prompt-injection', severity: 'high', ref: 'PIJ-015@yotta-verify', title: '要求泄露系统提示词', mask: false, re: /(?:reveal|show|print|output|display)\s+(?:me\s+|your\s+)?(?:system\s+)?(?:prompt|instructions?|system\s+message)/i },
+  { id: 'YTM-PIJ-006', class: 'prompt-injection', severity: 'high', ref: 'PIJ-016@yotta-verify', title: '要求泄露系统提示词（中文）', mask: false, re: /(?:输出|显示|打印|告诉我).{0,20}(?:你的|系统)?(?:系统提示词|系统指令|内部指令)/ },
+  { id: 'YTM-PIJ-007', class: 'prompt-injection', severity: 'medium', ref: 'PIJ-017@yotta-verify', title: '条件触发注入', mask: false, re: /when\s+(?:i|the\s+user)\s+(?:say|type|send|input)\s+[^\n]{0,40}\s*(?:then|you\s+will|ignore|do)/i },
+  // ── 凭证泄漏（元钥；命中片段一律打码，避免二次泄露）──
+  { id: 'YTM-SEC-001', class: 'credential-leak', severity: 'critical', ref: 'github@yotta-secret', title: 'GitHub Token', mask: true, re: /\bgh[pousr]_[0-9A-Za-z]{36,}\b|\bgithub_pat_[0-9A-Za-z_]{20,}\b/ },
+  { id: 'YTM-SEC-002', class: 'credential-leak', severity: 'critical', ref: 'aws_secret@yotta-secret', title: 'AWS 秘密访问密钥', mask: true, re: /aws[_-]?secret[_-]?access[_-]?key\b\s*[=:]\s*["']?[A-Za-z0-9/+=]{40}/i },
+  { id: 'YTM-SEC-003', class: 'credential-leak', severity: 'high', ref: 'openai@yotta-secret', title: 'OpenAI API Key', mask: true, re: /\bsk-(?!ant-)[A-Za-z0-9_-]{20,}\b/ },
+  { id: 'YTM-SEC-004', class: 'credential-leak', severity: 'critical', ref: 'pem_private@yotta-secret', title: 'PEM 私钥块', mask: true, re: /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/ },
+  { id: 'YTM-SEC-005', class: 'credential-leak', severity: 'high', ref: 'credential@yotta-secret', title: '凭据赋值', mask: true, re: /(?:password|passwd|pwd|secret|api[_-]?key|access[_-]?token|auth[_-]?token|client[_-]?secret|private[_-]?key|token)\s*[:=]\s*["']?[^\s"',;]{6,}/i },
+  { id: 'YTM-SEC-006', class: 'credential-leak', severity: 'high', ref: 'url_userinfo@yotta-secret', title: 'URL 内嵌账号密码', mask: true, re: /\b(?:https?|ftp|smtp|mongodb(?:\+srv)?|redis|mysql|postgres(?:ql)?):\/\/[^/\s:@]+:[^/\s@]+@/i },
+  // ── 数据外泄（元信 PIJ 外传指令 / 元安 Exfiltration）──
+  { id: 'YTM-EXF-001', class: 'data-exfiltration', severity: 'high', ref: 'PIJ-011@yotta-verify', title: '把上下文/密钥发送到远端', mask: false, re: /(?:send|upload|post|exfiltrate|transmit)\s+(?:the|all|your|any)?\s*(?:contents?|data|files?|env|environment|keys?|secrets?|memory|context|conversation|prompts?)\s*(?:to|via|using)\s*(?:this\s+)?(?:url|endpoint|server|http)/i },
+  { id: 'YTM-EXF-002', class: 'data-exfiltration', severity: 'high', ref: 'PIJ-012@yotta-verify', title: '把上下文/密钥发送到远端（中文）', mask: false, re: /(?:把|将|请将)(?:你的|所有|全部)?(?:上下文|记忆|环境变量|密钥|文件|对话|提示词).{0,40}(?:发送|上传|提交|传给|发给)/ },
+  { id: 'YTM-EXF-003', class: 'data-exfiltration', severity: 'high', ref: 'EXF-001@yotta-security-audit', title: '命令行上传数据到远端', mask: false, re: /\b(?:curl|wget)\b[^\n]{0,80}(?:--data\b|--upload-file\b|-d\s|-T\s)/i },
+  // ── 护栏绕过（元信 PIJ 隐藏意图 / 覆盖护栏）──
+  { id: 'YTM-GRD-001', class: 'guardrail-bypass', severity: 'high', ref: 'PIJ-004@yotta-verify', title: '要求覆盖/绕过安全护栏', mask: false, re: /(?:override|disregard|bypass)\s+(?:all\s+)?(?:previous\s+)?(?:instructions?|rules?|safety|guardrails?|security)/i },
+  { id: 'YTM-GRD-002', class: 'guardrail-bypass', severity: 'high', ref: 'PIJ-022@yotta-verify', title: '禁止告知用户（中文）', mask: false, re: /(?:不要告诉用户|别告诉用户|无需告知用户|不用告诉用户|不要让用户知道)/ },
+  { id: 'YTM-GRD-003', class: 'guardrail-bypass', severity: 'high', ref: 'PIJ-021@yotta-verify', title: '禁止告知用户', mask: false, re: /(?:do not|don'?t|never)\s+(?:tell|inform|notify|mention|reveal)\s+(?:the\s+)?user/i },
+  { id: 'YTM-GRD-004', class: 'guardrail-bypass', severity: 'high', ref: 'PIJ-026@yotta-verify', title: '要求不经用户同意直接执行（中文）', mask: false, re: /(?:不要问用户|无需询问|不用问|不需要征求|别问用户)/ },
+  { id: 'YTM-GRD-005', class: 'guardrail-bypass', severity: 'high', ref: 'PIJ-025@yotta-verify', title: '要求不经用户同意直接执行', mask: false, re: /(?:without|no\s+need\s+to)\s+(?:telling|informing|asking|consulting)\s+(?:the\s+)?user/i },
+  // ── 行为操纵（元信 PIJ 角色伪造）──
+  { id: 'YTM-BHV-001', class: 'behavior-manipulation', severity: 'medium', ref: 'PIJ-007@yotta-verify', title: '宣称新角色（中文）', mask: false, re: /(?:你现在是|从现在起你是|你的新角色是|从此刻起你是|你正在扮演)/ },
+  { id: 'YTM-BHV-002', class: 'behavior-manipulation', severity: 'medium', ref: 'PIJ-005@yotta-verify', title: '角色伪造：冒充系统/管理员', mask: false, re: /\byou\s+are\s+now\b[^\n]{0,60}(?:mode|role|system|admin|root|developer|assistant)/i },
+  { id: 'YTM-BHV-003', class: 'behavior-manipulation', severity: 'medium', ref: 'PIJ-006@yotta-verify', title: '角色伪造：扮演系统/管理员', mask: false, re: /(?:act|behave|pretend)\s+as\s+(?:a\s+|an\s+)?(?:system|admin|root|god\s+mode|developer)/i },
+  { id: 'YTM-BHV-004', class: 'behavior-manipulation', severity: 'high', ref: 'PIJ-003@yotta-verify', title: '从现在起重定向行为', mask: false, re: /from\s+now\s+on[^\n]{0,40}(?:follow|obey|you\s+are|act)/i },
+  { id: 'YTM-BHV-005', class: 'behavior-manipulation', severity: 'high', ref: 'PIJ-024@yotta-verify', title: '要求只回复确认词（中文）', mask: false, re: /(?:只回复|仅回复|直接回复)\s*(?:OK|ok|收到|好|是)/ },
+  // ── 权限提升（元信 PIJ 全权暗示 / 元盾 setuid / 元安 PrivilegeEscalation）──
+  { id: 'YTM-PRV-001', class: 'privilege-escalation', severity: 'high', ref: 'PIJ-008@yotta-verify', title: '以全权/管理员权限执行', mask: false, re: /with\s+(?:full|super|root|admin|system|unrestricted|unlimited)\s+(?:privileges|access|permissions?|power)/i },
+  { id: 'YTM-PRV-002', class: 'privilege-escalation', severity: 'critical', ref: 'CMD-CHMOD-SETUID@yotta-guardian', title: '设置 setuid 权限', mask: false, re: /\bchmod\s+(?:[ug]\+s|[0-7]{0,3}4[0-7]{3})\b/ },
+  { id: 'YTM-PRV-003', class: 'privilege-escalation', severity: 'high', ref: 'PRI-001@yotta-security-audit', title: '提权到 shell', mask: false, re: /\bsudo\s+(?:su|bash|sh|-i)\b/ },
+  { id: 'YTM-PRV-004', class: 'privilege-escalation', severity: 'high', ref: 'PIJ-027@yotta-verify', title: '采集键盘/凭据', mask: false, re: /(?:capture|record|log|monitor)\s+(?:all\s+)?(?:keystrokes|input|credentials?|passwords?|everything\s+the\s+user)/i },
+  { id: 'YTM-PRV-005', class: 'privilege-escalation', severity: 'high', ref: 'PIJ-028@yotta-verify', title: '采集键盘/凭据（中文）', mask: false, re: /(?:记录|收集|监控|窃取)(?:用户)?(?:输入|键盘|密码|凭据|按键)/ },
+  { id: 'YTM-PRV-006', class: 'privilege-escalation', severity: 'high', ref: 'PIJ-020@yotta-verify', title: '要求执行下载内容（中文）', mask: false, re: /(?:执行|运行|下载并运行|安装).{0,40}(?:curl|wget|下载).{0,60}(?:然后|并)?(?:执行|运行)/ },
+];
+function scanSeverityRank(severity) { return SCAN_SEVERITIES.indexOf(String(severity || '').toLowerCase()); }
+function scanEmptySummary() {
+  const byClass = {};
+  for (const cls of SCAN_CLASSES) byClass[cls] = 0;
+  const bySeverity = {};
+  for (const sev of SCAN_SEVERITIES) bySeverity[sev] = 0;
+  return { files: 0, encrypted: 0, mislabelled: 0, scanned: 0, hits: 0, byClass: byClass, bySeverity: bySeverity, maxSeverity: 'safe', truncated: false };
+}
+function isSafeRelPath(rel) {
+  const value = String(rel || '');
+  if (!value || value.indexOf('\u0000') !== -1) return false;
+  if (path.isAbsolute(value)) return false;
+  const norm = path.normalize(value);
+  if (norm === '..' || norm.indexOf('..' + path.sep) === 0 || norm.indexOf('/') === 0) return false;
+  return true;
+}
+// 命中片段一律做凭证打码：规则本身命中的密钥不会出现在报告里，同一行里的其它密钥也不会被顺带泄露。
+function scrubSecrets(line) {
+  let out = String(line);
+  for (const rule of MEMORY_SCAN_RULES) {
+    if (!rule.mask) continue;
+    const re = new RegExp(rule.re.source, rule.re.flags.indexOf('g') === -1 ? rule.re.flags + 'g' : rule.re.flags);
+    out = out.replace(re, '[已打码]');
+  }
+  return out;
+}
+function scanTargetFiles(root) {
+  // 递归扫记忆库内的 .md / .md.enc（含 facts、private、.archive、distills、profile）；
+  // 跳过 .git / node_modules / 隔离目录本身，避免把隔离副本再扫一遍。
+  const skip = ['.git', 'node_modules', SCAN_QUARANTINE_DIR];
+  const out = [];
+  (function walk(dir) {
+    if (out.length >= SCAN_MAX_FILES) return;
+    let names;
+    try { names = fs.readdirSync(dir, { withFileTypes: true }); } catch (e) { return; }
+    for (const item of names) {
+      const fp = path.join(dir, item.name);
+      if (item.isDirectory()) {
+        if (skip.indexOf(item.name) !== -1) continue;
+        walk(fp);
+        continue;
+      }
+      if (!item.isFile()) continue;
+      if (!MEMORY_FILE_RE.test(item.name)) continue;
+      out.push(fp);
+      if (out.length >= SCAN_MAX_FILES) return;
+    }
+  })(root);
+  return Array.from(new Set(out)).sort();
+}
+function scanQuarantineCore(root, findings) {
+  if (!findings.length) return { error: false, batch: '', files: 0, lines: 0, text: '没有命中项，无需隔离。' };
+  const batch = 'scan-' + Date.now() + '-' + crypto.randomBytes(2).toString('hex');
+  const batchDir = path.join(root, SCAN_QUARANTINE_DIR, 'quarantine', batch);
+  const byFile = new Map();
+  for (const finding of findings) {
+    if (!byFile.has(finding.file)) byFile.set(finding.file, []);
+    byFile.get(finding.file).push(finding);
+  }
+  const manifest = { version: 1, batch: batch, created: new Date().toISOString(), root: root, restored: false, files: [] };
+  let lineCount = 0;
+  for (const rel of Array.from(byFile.keys()).sort()) {
+    if (!isSafeRelPath(rel)) return { error: true, text: '拒绝隔离: 非法相对路径 ' + rel };
+    const src = path.join(root, rel);
+    if (!fs.existsSync(src)) continue;
+    const backup = path.join(batchDir, rel);
+    fs.mkdirSync(path.dirname(backup), { recursive: true });
+    fs.copyFileSync(src, backup);
+    const lineMap = new Map();
+    for (const hit of byFile.get(rel)) if (!lineMap.has(hit.line)) lineMap.set(hit.line, hit);
+    const lines = fs.readFileSync(src, 'utf8').split(/\r?\n/);
+    for (const lineNo of Array.from(lineMap.keys()).sort(function (a, b) { return a - b; })) {
+      if (lineNo < 1 || lineNo > lines.length) continue;
+      lines[lineNo - 1] = '[已隔离: ' + lineMap.get(lineNo).rule + ' ' + lineMap.get(lineNo).class + ']';
+      lineCount++;
+    }
+    fs.writeFileSync(src, lines.join('\n'), 'utf8');
+    manifest.files.push({
+      file: rel,
+      lines: Array.from(lineMap.keys()).sort(function (a, b) { return a - b; }),
+      rules: Array.from(new Set(byFile.get(rel).map(function (h) { return h.rule; }))),
+    });
+  }
+  fs.writeFileSync(path.join(batchDir, 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf8');
+  return {
+    error: false,
+    batch: batch,
+    files: manifest.files.length,
+    lines: lineCount,
+    text: '已隔离 ' + lineCount + ' 行（' + manifest.files.length + ' 个文件）到 ' + path.join(SCAN_QUARANTINE_DIR, 'quarantine', batch) + '；原文件命中行已替换为占位符，可用 scan --restore 还原。',
+  };
+}
+function scanRestoreCore(root, opts) {
+  const base = path.join(root, SCAN_QUARANTINE_DIR, 'quarantine');
+  const report = { schemaVersion: SCAN_SCHEMA_VERSION, error: true, exitCode: 2, ok: false, level: 'safe', root: root, findings: [], summary: scanEmptySummary() };
+  if (!fs.existsSync(base)) return Object.assign(report, { text: '没有可还原的隔离批次: ' + base + '。' });
+  const wanted = opts && opts.id ? String(opts.id) : '';
+  const batches = fs.readdirSync(base).filter(function (name) {
+    return fs.existsSync(path.join(base, name, 'manifest.json'));
+  }).sort();
+  const chosen = wanted
+    ? (batches.indexOf(wanted) === -1 ? null : wanted)
+    : (batches.length ? batches[batches.length - 1] : null);
+  if (!chosen) return Object.assign(report, { text: wanted ? ('找不到隔离批次: ' + wanted + '。') : '没有可还原的隔离批次。' });
+  const batchDir = path.join(base, chosen);
+  let manifest = null;
+  try {
+    manifest = JSON.parse(fs.readFileSync(path.join(batchDir, 'manifest.json'), 'utf8'));
+  } catch (error) {
+    return Object.assign(report, { text: '隔离批次 manifest 无法解析: ' + chosen + '（' + (error && error.message ? error.message : String(error)) + '）' });
+  }
+  if (manifest && manifest.restored) {
+    return Object.assign(report, { text: '隔离批次 ' + chosen + ' 已还原过，不会重复还原。' });
+  }
+  let restored = 0;
+  for (const item of (manifest && manifest.files) || []) {
+    if (!isSafeRelPath(item.file)) return Object.assign(report, { text: '拒绝还原: 非法相对路径 ' + item.file });
+    const backup = path.join(batchDir, item.file);
+    if (!fs.existsSync(backup)) continue;
+    const target = path.join(root, item.file);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.copyFileSync(backup, target);
+    restored++;
+  }
+  manifest.restored = true;
+  manifest.restored_at = new Date().toISOString();
+  fs.writeFileSync(path.join(batchDir, 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf8');
+  return {
+    schemaVersion: SCAN_SCHEMA_VERSION,
+    error: false,
+    exitCode: 0,
+    ok: true,
+    level: 'safe',
+    root: root,
+    batch: chosen,
+    files: restored,
+    findings: [],
+    summary: scanEmptySummary(),
+    text: '已还原 ' + restored + ' 个文件（批次 ' + chosen + '）。',
+  };
+}
+function renderScanText(report) {
+  const label = { safe: '安全', low: '低危', medium: '中危', high: '高危', critical: '严重' };
+  const lines = [
+    '# 元忆记忆库安全扫描（scan）',
+    '',
+    '- 扫描路径: ' + report.root,
+    '- 扫描文件: ' + report.summary.files + '（加密跳过 ' + report.summary.encrypted + (report.summary.mislabelled ? '；.enc 后缀但内容是明文 ' + report.summary.mislabelled + ' 个已按文本扫描' : '') + '）',
+    '- 结果: ' + label[report.level] + ' · 命中 ' + report.summary.hits + ' 条' + (report.summary.truncated ? '（已达上限，结果被截断）' : ''),
+    '- 分级: ' + SCAN_SEVERITIES.map(function (s) { return s + '=' + report.summary.bySeverity[s]; }).join(' / '),
+    '- 类别: ' + SCAN_CLASSES.map(function (c) { return c + '=' + report.summary.byClass[c]; }).join(' / '),
+  ];
+  if (report.gate) lines.push('- 门禁: 命中 ' + report.gate + ' 及以上即 exit 1（当前 ' + report.level + '）');
+  if (!report.findings.length) lines.push('- 未发现可疑内容。');
+  for (const finding of report.findings) {
+    lines.push('- [' + label[finding.severity] + '] ' + finding.evidence + ' ' + finding.rule + ' ' + finding.title + '（' + finding.class + ' / ' + finding.ref + '）');
+    lines.push('  片段: ' + finding.snippet);
+  }
+  if (report.quarantine) {
+    lines.push('');
+    lines.push(report.quarantine.text);
+  }
+  if (report.restore) {
+    lines.push('');
+    lines.push(report.restore.text);
+  }
+  return lines.join('\n');
+}
+function scanCore(opts) {
+  opts = opts || {};
+  const root = path.resolve(opts.path || opts.root || userRoot());
+  const gateRaw = Array.isArray(opts.gate) ? opts.gate[opts.gate.length - 1] : opts.gate;
+  let gate = '';
+  if (gateRaw !== undefined && gateRaw !== null && String(gateRaw) !== '') {
+    gate = String(gateRaw).trim().toLowerCase();
+    if (SCAN_SEVERITIES.indexOf(gate) === -1) {
+      const bad = Object.assign({ schemaVersion: SCAN_SCHEMA_VERSION, error: true, exitCode: 2, ok: false, level: 'safe', root: root, findings: [], summary: scanEmptySummary() }, {});
+      bad.text = '安全级别不支持: ' + gateRaw + '。门禁可选安全级别: safe / low / medium / high / critical（例如 --gate high）。';
+      return bad;
+    }
+  }
+  if (!fs.existsSync(root)) {
+    const missing = Object.assign({ schemaVersion: SCAN_SCHEMA_VERSION, error: true, exitCode: 2, ok: false, level: 'safe', root: root, findings: [], summary: scanEmptySummary() }, {});
+    missing.text = '扫描路径不存在: ' + root + '。请检查 --path 指向的记忆库目录。';
+    return missing;
+  }
+  if (opts.restore) return scanRestoreCore(root, opts);
+
+  const findings = [];
+  const byClass = {};
+  for (const cls of SCAN_CLASSES) byClass[cls] = 0;
+  const bySeverity = {};
+  for (const sev of SCAN_SEVERITIES) bySeverity[sev] = 0;
+  let files = 0;
+  let encrypted = 0;
+  let mislabelled = 0;
+  let truncated = false;
+  for (const fp of scanTargetFiles(root)) {
+    files++;
+    if (isEncFile(fp)) {
+      // 历史恢复残留：.enc 后缀但内容其实是明文（缺 YTMENC1 头）→ 按文本继续扫，否则等于漏扫。
+      let head = Buffer.alloc(0);
+      try { head = fs.readFileSync(fp).slice(0, ENC_MAGIC.length); } catch (error) { encrypted++; continue; }
+      if (head.toString('utf8') !== ENC_MAGIC) mislabelled++;
+      else { encrypted++; continue; }
+    }
+    let text = '';
+    try { text = fs.readFileSync(fp, 'utf8'); } catch (error) { continue; }
+    const rel = relOf(root, fp);
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (!line.trim()) continue;
+      for (const rule of MEMORY_SCAN_RULES) {
+        rule.re.lastIndex = 0;
+        const match = rule.re.exec(line);
+        if (!match) continue;
+        if (findings.length >= SCAN_MAX_FINDINGS) { truncated = true; break; }
+        // 片段给命中位置前后各 40 字符（不是行首），否则长行会看起来「没有命中内容」。
+        const start = Math.max(0, match.index - 40);
+        const end = Math.min(line.length, match.index + match[0].length + 40);
+        const snippet = scrubSecrets((start > 0 ? '…' : '') + line.slice(start, end) + (end < line.length ? '…' : '')).slice(0, 200);
+        findings.push({
+          file: rel,
+          line: i + 1,
+          evidence: rel + ':' + (i + 1),
+          rule: rule.id,
+          class: rule.class,
+          severity: rule.severity,
+          title: rule.title,
+          ref: rule.ref,
+          match: scrubSecrets(match[0]).slice(0, 80),
+          snippet: snippet,
+        });
+        byClass[rule.class]++;
+        bySeverity[rule.severity]++;
+      }
+      if (truncated) break;
+    }
+    if (truncated) break;
+  }
+  const hitSeverities = SCAN_SEVERITIES.filter(function (sev) { return bySeverity[sev] > 0; });
+  const level = hitSeverities.length ? hitSeverities[hitSeverities.length - 1] : 'safe';
+  const summary = {
+    files: files,
+    encrypted: encrypted,
+    mislabelled: mislabelled,
+    scanned: files - encrypted,
+    hits: findings.length,
+    byClass: byClass,
+    bySeverity: bySeverity,
+    maxSeverity: level,
+    truncated: truncated,
+  };
+  const report = {
+    schemaVersion: SCAN_SCHEMA_VERSION,
+    error: false,
+    exitCode: 0,
+    ok: level === 'safe',
+    level: level,
+    root: root,
+    gate: gate,
+    findings: findings,
+    summary: summary,
+    quarantine: null,
+    restore: null,
+  };
+  if (opts.quarantine) {
+    if (!opts.yes) {
+      report.error = true;
+      report.exitCode = 2;
+      report.text = '拒绝: --quarantine 会改写记忆文件，需要显式确认。确认后重试：yotta-memory scan --quarantine --yes；未确认时不会改动任何文件。';
+      return report;
+    }
+    const quarantined = scanQuarantineCore(root, findings);
+    if (quarantined.error) {
+      report.error = true;
+      report.exitCode = 2;
+      report.text = quarantined.text;
+      return report;
+    }
+    report.quarantine = quarantined;
+  }
+  report.text = renderScanText(report);
+  if (gate) {
+    const gateRank = scanSeverityRank(gate);
+    const levelRank = scanSeverityRank(level);
+    const failed = gate === 'safe' ? level !== 'safe' : levelRank >= gateRank;
+    if (failed) report.exitCode = 1;
+  }
+  return report;
+}
+// 交互确认：非 TTY 一律返回 null（由调用方给 --yes 指引），避免自动化里静默改写记忆。
+function promptYesNo(promptText) {
+  return new Promise(function (resolve) {
+    const stdin = process.stdin;
+    if (!stdin.isTTY) { resolve(null); return; }
+    process.stdout.write(promptText + ' [y/N] ');
+    let buf = '';
+    function done(abort) {
+      try { stdin.setRawMode(false); } catch (e) {}
+      stdin.pause();
+      stdin.removeListener('data', onData);
+      process.stdout.write('\n');
+      resolve(abort ? null : /^y(es)?$/i.test(buf.trim()));
+    }
+    function onData(chunk) {
+      const s = String(chunk);
+      for (const c of s) {
+        if (c === '\r' || c === '\n') { done(false); return; }
+        if (c === '\u0003') { done(true); return; }
+        if (c === '\u007f' || c === '\b') buf = buf.slice(0, -1);
+        else buf += c;
+      }
+    }
+    try { stdin.setRawMode(true); } catch (e) { resolve(null); return; }
+    stdin.resume();
+    stdin.setEncoding('utf8');
+    stdin.on('data', onData);
+  });
+}
+async function cmdScan(opts) {
+  opts = opts || {};
+  if (opts.quarantine && !opts.yes) {
+    const preview = scanCore(Object.assign({}, opts, { quarantine: false }));
+    if (preview.error) {
+      console.log(opts.json ? JSON.stringify(preview, null, 2) : preview.text);
+      process.exit(2);
+    }
+    const answer = await promptYesNo('即将隔离 ' + preview.summary.hits + ' 处命中（原文件先备份到 ' + SCAN_QUARANTINE_DIR + '/quarantine）');
+    if (answer !== true) {
+      console.log('已取消：未确认时不会改动记忆文件。确认后请重试：yotta-memory scan --quarantine --yes');
+      process.exit(2);
+    }
+    opts = Object.assign({}, opts, { yes: true });
+  }
+  const r = scanCore(opts);
+  console.log(opts.json ? JSON.stringify(r, null, 2) : r.text);
+  if (r.error) process.exit(r.exitCode || 2);
+  if (r.exitCode) process.exit(r.exitCode);
+}
+
 // ---- config 命令 ----
 // v0.10.0：maintain_* / consolidate_* 数值键纳入 config set/get（此前只支持 3 个键但文档已写可调）
-function isNumericConfigKey(key) { return /^(maintain_|consolidate_|backup_max_age_hours$)/.test(key); }
+function isNumericConfigKey(key) { return /^(maintain_|consolidate_|scale_|backup_max_age_hours$)/.test(key); }
+// v0.17.0 B2：doctor 规模体检阈值键（0 表示只要超过 0 就告警，便于压测与演练）
+const SCALE_CONFIG_KEYS = ['scale_warn_entries', 'scale_warn_files_per_dir', 'scale_warn_index_bytes', 'scale_warn_cold_start_ms'];
 function cmdConfigSet(key, value) {
-  const known = ['memory_home', 'embedding_cmd', 'embedding_timeout', 'backup_dir', 'backup_enabled', 'backup_schedule', 'backup_time', 'backup_max_age_hours', 'backup_setup_choice', 'maintain_archived_utility', 'maintain_archived_age', 'maintain_forget_utility', 'maintain_forget_age', 'maintain_decay_halflife_FACT', 'maintain_decay_halflife_PREF', 'maintain_decay_halflife_COMMIT', 'consolidate_min_age', 'consolidate_min_idle', 'consolidate_max_utility', 'consolidate_min_group', 'consolidate_period'];
-  if (known.indexOf(key) === -1) { console.error('未知配置项: ' + key + '（可用: memory_home / backup_dir / embedding_cmd / embedding_timeout / maintain_* / consolidate_*）'); process.exit(2); }
+  const known = ['memory_home', 'embedding_cmd', 'embedding_timeout', 'backup_dir', 'backup_enabled', 'backup_schedule', 'backup_time', 'backup_max_age_hours', 'backup_setup_choice', 'maintain_archived_utility', 'maintain_archived_age', 'maintain_forget_utility', 'maintain_forget_age', 'maintain_decay_halflife_FACT', 'maintain_decay_halflife_PREF', 'maintain_decay_halflife_COMMIT', 'consolidate_min_age', 'consolidate_min_idle', 'consolidate_max_utility', 'consolidate_min_group', 'consolidate_period'].concat(SCALE_CONFIG_KEYS);
+  if (known.indexOf(key) === -1) { console.error('未知配置项: ' + key + '（可用: memory_home / backup_dir / embedding_cmd / embedding_timeout / maintain_* / consolidate_* / scale_*）'); process.exit(2); }
   if (value === undefined || value === null || value === '') { console.error('缺少值: config set ' + key + ' <值>'); process.exit(2); }
   const cfg = loadConfig();
   if (key === 'memory_home') cfg.memory_home = value;
@@ -5843,7 +7944,7 @@ function cmdConfigGet(opts) {
   console.log('backup_time: ' + (cfg.backup_time || '(未设置)'));
   console.log('embedding_cmd: ' + (cfg.embedding_cmd || '(未设置)'));
   console.log('embedding_timeout: ' + (cfg.embedding_timeout || 3000));
-  const keys = ['memory_home', 'backup_dir', 'backup_enabled', 'backup_schedule', 'backup_time', 'backup_max_age_hours', 'backup_setup_choice', 'embedding_cmd', 'embedding_timeout', 'maintain_archived_utility', 'maintain_archived_age', 'maintain_forget_utility', 'maintain_forget_age', 'maintain_decay_halflife_FACT', 'maintain_decay_halflife_PREF', 'maintain_decay_halflife_COMMIT', 'consolidate_min_age', 'consolidate_min_idle', 'consolidate_max_utility', 'consolidate_min_group', 'consolidate_period'];
+  const keys = ['memory_home', 'backup_dir', 'backup_enabled', 'backup_schedule', 'backup_time', 'backup_max_age_hours', 'backup_setup_choice', 'embedding_cmd', 'embedding_timeout', 'maintain_archived_utility', 'maintain_archived_age', 'maintain_forget_utility', 'maintain_forget_age', 'maintain_decay_halflife_FACT', 'maintain_decay_halflife_PREF', 'maintain_decay_halflife_COMMIT', 'consolidate_min_age', 'consolidate_min_idle', 'consolidate_max_utility', 'consolidate_min_group', 'consolidate_period'].concat(SCALE_CONFIG_KEYS);
   for (const k of keys) {
     if (k === 'memory_home' || k === 'backup_dir' || k === 'backup_enabled' || k === 'backup_schedule' || k === 'backup_time' || k === 'embedding_cmd' || k === 'embedding_timeout') continue;
     if (cfg[k] !== undefined) console.log(k + ': ' + cfg[k]);
@@ -7194,68 +9295,89 @@ function cmdRuntimeStatus() {
 function cmdRuntimeList() {
   console.log(runtimeListCore().text);
 }
-function usage() {
-  const banner = 'yotta-memory v' + VERSION + ' — 元忆：有权限边界的文件式智能体记忆';
-  const sections = [
-    ['核心记忆', [
-      ['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', '开工可靠性检查（根目录/密钥库/索引/身份/最近备份；全新空库缺失 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 可选外部模型）'],
-      ['feedback', '使用反馈（--useful/--useless/--undo）'],
-      ['explain', '查看单条记忆效用分项与归档/遗忘状态判定'],
-      ['reindex', '重建索引'],
-      ['export', '导出全部记忆（--out 文件.json）'],
-      ['import', '导入记忆（<文件.json>）']
-    ]],
-    ['身份与画像', [
-      ['iam', '登记本智能体唯一身份（--name/--user/--relationship；agents.json）'],
-      ['whoami', '查看当前智能体身份与登记状态'],
-      ['profile', '生成用户画像（聚合 private/<owner>/ 原文，零推断）'],
-      ['context', '生成开工上下文包（--limit/--owner/--budget）'],
-      ['token', '生成/列出/吊销访问 token（new --agent / list / revoke --agent）']
-    ]],
-    ['加密与安全', [
-      ['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> | --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_* 参数）']
-    ]],
-    ['平台与服务', [
-      ['serve', '启动 MCP 记忆引擎（streamable HTTP；--stdio 本地零进程；--tools core|full 控制工具分组）'],
-      ['runtime', '运行时稳定入口（list / install <tarball|版本> [--from-current] [--force] / use <版本> [--restart] / rollback [--restart] / status）'],
-      ['lan', '开机自启管理（enable/disable/status；Windows 计划任务 / Linux systemd/crontab）'],
-      ['--version', '版本']
-    ]]
+function helpDisplayWidth(text) {
+  let width = 0;
+  for (const ch of String(text)) {
+    const cp = ch.codePointAt(0);
+    width += (
+      (cp >= 0x1100 && cp <= 0x115f) ||
+      (cp >= 0x2e80 && cp <= 0xa4cf) ||
+      (cp >= 0xac00 && cp <= 0xd7a3) ||
+      (cp >= 0xf900 && cp <= 0xfaff) ||
+      (cp >= 0xfe30 && cp <= 0xfe6f) ||
+      (cp >= 0xff00 && cp <= 0xff60) ||
+      (cp >= 0xffe0 && cp <= 0xffe6)
+    ) ? 2 : 1;
+  }
+  return width;
+}
+function helpPad(text, width) {
+  return text + ' '.repeat(Math.max(0, width - helpDisplayWidth(text)));
+}
+function helpText(item) {
+  const parts = [];
+  if (item.what) parts.push('做什么：' + item.what);
+  if (item.when) parts.push('什么时候用：' + item.when);
+  if (item.caution) parts.push('注意：' + item.caution);
+  return parts.join('；');
+}
+function helpOptionLabel(option) {
+  return option.flag + (option.arg ? ' ' + option.arg : '');
+}
+function renderHelp(model) {
+  const commands = [];
+  for (const group of model) for (const command of group.commands) commands.push(command);
+
+  let optionCol = 0;
+  for (const command of commands) {
+    for (const option of command.options || []) optionCol = Math.max(optionCol, helpDisplayWidth(helpOptionLabel(option)));
+    for (const sub of command.subcommands || []) {
+      for (const option of sub.options || []) optionCol = Math.max(optionCol, helpDisplayWidth(helpOptionLabel(option)));
+    }
+  }
+  optionCol += 2;
+
+  const lines = [
+    'yotta-memory v' + VERSION + ' — 元忆：有权限边界的文件式智能体记忆',
+    '',
+    '用法:',
+    '  yotta-memory <命令> [选项]',
+    '  yotta-memory --help    显示这份完整帮助',
+    '  yotta-memory --version 显示版本',
+    '',
   ];
-  let col = 0;
-  for (const s of sections) for (const r of s[1]) if (r[0].length > col) col = r[0].length;
-  col += 2;
-  const lines = [banner, '', '用法:', '  yotta-memory <命令> [选项]', ''];
-  for (const s of sections) {
-    lines.push(s[0] + ':');
-    for (const r of s[1]) lines.push('  ' + r[0].padEnd(col) + r[1]);
+  for (const group of model) {
+    lines.push(group.group + ':');
+    for (const command of group.commands) {
+      lines.push('  ' + command.name + '  ' + helpText(command));
+      lines.push('    用法: yotta-memory ' + command.usage);
+      for (const sub of command.subcommands || []) {
+        lines.push('    ' + (sub.usage || sub.name) + '  ' + helpText(sub));
+        for (const option of sub.options || []) {
+          lines.push('      ' + helpPad(helpOptionLabel(option), optionCol) + helpText(option));
+        }
+      }
+      for (const option of command.options || []) {
+        lines.push('    ' + helpPad(helpOptionLabel(option), optionCol) + helpText(option));
+      }
+    }
     lines.push('');
   }
   lines.push('类型: FACT(公共共享) / PREF(偏好) / BOUND(边界) / COMMIT(承诺)');
   lines.push('环境变量: YOTTA_MEMORY_HOME 临时覆盖用户级位置; 身份不再读取 env；CLI 用 --agent + --agent-key/--agent-key-file，stdio MCP 用 --agent-id + --agent-key-file，HTTP MCP 用请求头');
   lines.push('隔离: 公共 FACT 在 facts/；私密 PREF/BOUND/COMMIT 物理分目录 private/<agent_id>/<type>/，禁止 shell 直读写记忆库，一律走本命令');
   lines.push('远端接入: MCP url http://<主机IP>:8787/mcp；请求头 Authorization: Bearer <token> + X-Agent-Id: <id> + X-Agent-Key: <agent_key>');
-  console.log(lines.join('\n'));
+  return lines.join('\n');
+}
+function usage() {
+  console.log(renderHelp(HELP_MODEL));
 }
 async function main() {
   const args = process.argv.slice(2);
   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', '--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']);
+  const valueOpts = CLI_VALUE_OPTS;
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
     if (a === '--version' || a === '-v') { console.log(VERSION); return; }
@@ -7290,6 +9412,15 @@ async function main() {
     else if (a === '--explain') opts.explain = true;
     else if (a === '--semantic') opts.semantic = true;
     else if (a === '--runtime') opts.runtime = true;
+    else if (a === '--ablate') opts.ablate = true;
+    else if (a === '--timing') opts.timing = true;
+    else if (a === '--baseline') opts.baseline = true;
+    else if (a === '--probe') opts.probe = true;
+    else if (a === '--quarantine') opts.quarantine = true;
+    else if (a === '--restore') opts.restore = true;
+    else if (a === '--yes') opts.yes = true;
+    else if (a === '--keep-memories') opts.keepMemories = true;
+    else if (a === '--keep-identity') opts.keepIdentity = true;
     else if (valueOpts.has(a)) {
       const v = args[++i];
       if (a === '--type') opts.type = v;
@@ -7335,6 +9466,15 @@ async function main() {
       else if (a === '--tools') opts.toolProfile = v;
       else if (a === '--mcp-config') opts.mcpConfigPaths = (opts.mcpConfigPaths || []).concat(v);
       else if (a === '--skill-dir') opts.skillDirs = (opts.skillDirs || []).concat(v);
+      else if (a === '--year') opts.years = (opts.years || []).concat(v);
+      else if (a === '--evalset') opts.evalset = v;
+      else if (a === '--k') opts.k = parseInt(v, 10);
+      else if (a === '--seed') opts.seed = parseInt(v, 10);
+      else if (a === '--bootstrap') opts.bootstrap = parseInt(v, 10);
+      else if (a === '--gate') opts.gate = (opts.gate || []).concat(v);
+      else if (a === '--against') opts.against = v;
+      else if (a === '--template') opts.template = v;
+      else if (a === '--path') opts.path = v;
     } else if (a.startsWith('--')) {
       if (a === '--query') {
         console.error('未知选项: --query。recall/search 的关键词是位置参数：yotta-memory recall [关键词]');
@@ -7369,6 +9509,12 @@ async function main() {
     case 'init': await cmdInit(opts); break;
     case 'whoami': cmdWhoami(opts); break;
     case 'iam': cmdIam(rest[0], opts); break;
+    case 'identity': {
+      const sub = rest[0];
+      if (sub === 'remove') await cmdIdentityRemove(rest[1], opts);
+      else { console.error('identity 子命令: remove <id> [--dry-run] [--yes] [--keep-memories] [--keep-identity] [--password <口令> | --recovery-key <钥匙>]'); process.exit(2); }
+      break;
+    }
     case 'config': {
       const sub = rest[0];
       if (sub === 'set') cmdConfigSet(rest[1], rest[2]);
@@ -7381,6 +9527,8 @@ async function main() {
     case 'search': cmdRecall(rest[0] || null, opts); break;
     case 'feedback': cmdFeedback(rest[0], opts); break;
     case 'explain': cmdExplain(rest[0], opts); break;
+    case 'bench': cmdBench(opts); break;
+    case 'scan': await cmdScan(opts); break;
     case 'maintain': cmdMaintain(opts); break;
     case 'distill': cmdDistill(opts); break;
     case 'consolidate': if (opts.undo === true && rest.length) opts.undo = rest[0]; cmdConsolidate(opts); break;
@@ -7459,6 +9607,10 @@ async function main() {
 if (require.main === module) { main().catch(function (e) { console.error('错误: ' + (e && e.message ? e.message : String(e))); console.error('修复建议: 若与记忆库/密钥/权限有关，请检查 memory_home 路径、主口令与恢复钥匙，或运行 yotta-memory config get 确认位置；仍无法解决请把上面的错误信息反馈给开发者。'); process.exit(2); }); }
 module.exports = {
   VERSION: VERSION,
+  HELP_MODEL: HELP_MODEL,
+  CLI_FLAG_OPTS: CLI_FLAG_OPTS,
+  CLI_VALUE_OPTS: CLI_VALUE_OPTS,
+  renderHelp: renderHelp,
   userRoot: userRoot,
   projectRoot: projectRoot,
   memoryRoots: memoryRoots,
@@ -7484,8 +9636,32 @@ module.exports = {
   loadTokens: loadTokens,
   saveTokens: saveTokens,
   collectEntryFiles: collectEntryFiles,
+  walkEntryFiles: walkEntryFiles,
   migrateLayout: migrateLayout,
+  loadIndexFor: loadIndexFor,
+  indexEntriesFor: indexEntriesFor,
+  normalizeYearList: normalizeYearList,
+  indexFingerprint: indexFingerprint,
+  benchCore: benchCore,
+  baselineCore: baselineCore,
+  loadBaselineTemplate: loadBaselineTemplate,
+  scanCore: scanCore,
+  scanQuarantineCore: scanQuarantineCore,
+  scanRestoreCore: scanRestoreCore,
+  promptYesNo: promptYesNo,
+  MEMORY_SCAN_RULES: MEMORY_SCAN_RULES,
+  SCAN_CLASSES: SCAN_CLASSES,
+  SCAN_SEVERITIES: SCAN_SEVERITIES,
+  SCAN_QUARANTINE_DIR: SCAN_QUARANTINE_DIR,
+  exportCore: exportCore,
+  importCore: importCore,
   typeSubdir: typeSubdir,
+  dateSubdir: dateSubdir,
+  entryWriteDir: entryWriteDir,
+  archiveRelFor: archiveRelFor,
+  SCALE_CONFIG_KEYS: SCALE_CONFIG_KEYS,
+  SCALE_THRESHOLD_DEFAULTS: SCALE_THRESHOLD_DEFAULTS,
+  scaleReport: scaleReport,
   runtimeRoot: runtimeRoot,
   runtimeManifestPath: runtimeManifestPath,
   runtimeVersionsDir: runtimeVersionsDir,
@@ -7592,6 +9768,7 @@ module.exports = {
 
   loadIndex: loadIndex,
   saveIndex: saveIndex,
+  buildIndex: buildIndex,
   getIndex: getIndex,
   touchIndex: touchIndex,
   loadIndexManifest: loadIndexManifest,
@@ -7607,6 +9784,10 @@ module.exports = {
   keyBindCore: keyBindCore,
   keyRevokeCore: keyRevokeCore,
   keyClaimCore: keyClaimCore,
+  identityRemoveCore: identityRemoveCore,
+  identityRemoveInventory: identityRemoveInventory,
+  verifyIdentityRemoveAuthority: verifyIdentityRemoveAuthority,
+  IDENTITY_REMOVE_STEPS: IDENTITY_REMOVE_STEPS,
   keyStatusCore: keyStatusCore,
   writeAgentBinding: writeAgentBinding,
   unwrapAgentBinding: unwrapAgentBinding,