@modusensus/dsh-mneme 0.10.1 → 0.12.0

package/README.md

@@ -5,7 +5,7 @@
 [![npm version](https://img.shields.io/npm/v/@modusensus/dsh-mneme?color=blue&label=npm)](https://www.npmjs.com/package/@modusensus/dsh-mneme)
 [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![Awesome](https://awesome-dsh-plugin.com/badge.svg)](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
-[![tests](https://img.shields.io/badge/tests-2681%20passed-success)](https://github.com/slow-stack/mneme)
+[![tests](https://img.shields.io/badge/tests-2881%20total-success)](https://github.com/slow-stack/mneme)
 [![CI](https://img.shields.io/github/actions/workflow/status/slow-stack/mneme/ci.yml)](https://github.com/slow-stack/mneme/actions)
 [![node](https://img.shields.io/badge/node-22%2B-blue)](https://nodejs.org)
 [![npm downloads](https://img.shields.io/npm/d18m/@modusensus/dsh-mneme.svg?color=blue&label=downloads)](https://www.npmjs.com/package/@modusensus/dsh-mneme)
@@ -49,7 +49,7 @@ dsh web
   - 逐 type 记录 `committed / failed / pending` 回执，健康端点区分 `ok / degraded / unknown`
   - 状态写失败不静默：同步失败落日志并留债务，重启自动收敛
 
-### 模型工具（默认注册 11 个；开 `organizeEnabled` 后 12 个）
+### 模型工具（默认注册 12 个；开 `organizeEnabled` 后 13 个）
 
 
 | 工具 | 功能 |
@@ -62,11 +62,14 @@ dsh web
 | `memory_delete` | 删除记忆（按记忆 ID 精确删除） |
 | `memory_forget` | 抑制注入（降权不删除，可恢复） |
 | `memory_archive` | 归档/恢复记忆（v0.2.5；归档后隐藏于列表/搜索/注入/整理，`archived=false` 可恢复） |
+| `memory_pin` | 钉住一条记忆：无论类型、无论它和其他记忆怎么竞争，每轮都注入在记忆块最前面（#249 第二批；受 `pinnedInjectBudget` 上限约束，钉的顺序是「先钉的占位」，预算不够时最早钉的优先）。**只在她明确说「这条必须一直在」时用**，不是标记重要性的手段——重要性本来就参与排序。钉着 ≠ 会注入：遗忘 / 归档 / 暂停作用域都优先于 pin，回执里的 `injectable` 如实报告这件事。`unpin: true` 松开 |
 | `set_scope_state` | 按下/松开某个作用域的**可逆闸门**（#471：政策轴。暂停期间该作用域的记忆照旧存着，只是不注入、不参与巩固，松开即原样回来；不改任何一条记忆的标注，与上面逐条操作的 `memory_forget` / `memory_archive` 是两根不同的轴）。两级开关 `scopeState.enabled` / `.enforce` 默认都关，没开时按下不产生拦截效果 |
 | `memory_register_document` | 登记 agent 产长文档的指针行（#230：摘要 + `doc_path` + evidence 落 `document` 类型；正文留在磁盘、由 agent 自管，注册口唯一，旁路写入被拒） |
 | `memory_organize` | 主动整理（#231，**要 `organizeEnabled` 打开才注册**）：`mode=dryRun` 先出比对报告（每条候选 `exact` / `near` / `new` + 命中行，**不写一行库**、只留审计回执），agent 判断后 `mode=apply` 引用那份报告的 `run_id` 落地。两种「不要它」要分清——**`discard`** = 这条候选不写，什么都不动（只进回执）；**`archive`** = 把报告标为被取代的那条**既有行**归档（可恢复，绝不物理删除）。没有比对过的候选写不进库，一份报告也只许落地一次 |
 | `memory_runtime` | 本地推理运行时的状态 / 供给 / 校验（v0.7.32，自管运行时三档取件） |
 
+开启 `chorographyEnabled` 后可用仓库地志工具。多个仓库已登记时请传仓库 ID。若搜索只读到部分页面，结果会标明漏查的页。
+
 ### 工作流（M.O.，v0.9 beta）
 
 记忆库答的是「这件事**为什么**这么办」，答不了「这件事**到底怎么跑**」。v0.9 把后者从记忆库里的一行文字变成项目里可提交、可 review、可被 CI 读的一份文件——一条工作流一个 JSON：
@@ -247,6 +250,12 @@ v0.3.0 起新增**记忆基因**层：从记忆里抽取**命名实体**、**带
 
 > 只读端点，与 list/search/semantic 一样在设置 `apiToken` 后仍保持开放。
 
+沉淀曲线（面板状态页「8 周沉淀」图的数据源）：
+
+- `GET /api/dsh-mneme/semantic/consolidation-stats?days=` — 近 N 天（缺省 56，钳 1–365）按天返回三条序列：`added`（新建记忆，排除外来导入行）、`merged`（当天被巩固掉的**去重记录数**，取自 `receipt_chain` 里 `kind∈(merge,update)` 且 `verdict='live'`）、`archived`（当天进入归档面的条数），另附三个窗口合计。
+
+`merged` 刻意按去重 `record_id` 数而不是行数：同一条记录被多轮巩固重复记账是常态（活库实测 2412 行只对应 1796 个记录），按行数会把「又记了一遍」算成「又沉淀了一条」。新增与合并背离才是这张图要看的东西——2026-10-25–10-31 那段新增照旧、合并归零，只看新增或只看总量都发现不了。
+
 ### 记忆库主区视图与记忆图谱 🕸️（v0.5.0）
 
 记忆功能从侧边栏抽屉收进**主内容区全宽 tab**（conversation.view 插槽，与「对话 / Trajectory」并列），侧边栏「记忆」入口点击后直接激活该 tab。页面顶部子 tab 行切换三个子视图：
@@ -286,6 +295,8 @@ v0.3.0 起新增**记忆基因**层：从记忆里抽取**命名实体**、**带
 | **v0.9.5**（2026-10-30） | 记忆能安全地递给别人，也能整包收回来：**分享包 `mneme.share/v1`**（`dsh-mneme share` / `receive` / `undo-share`，面板「⋯」里同一批三件事）只含活跃行，scope 与 home 前缀不进包，命中密钥 / PII 的行整条不进；出包先给报告再给文件，超 3 MiB 水位回 413、按 `--type` / `--tag` 分批；入包一条不合格整包拒、干跑为默认、按 `share_external_id` 幂等，整包退出走物删。「本机巩固不许改写别人导入的原文」由单一谓词 `isImportedRow` 守在汇流口与九个行池上。同版给记忆来源加了读出口 `GET /memory/provenance`（#421，@z2Ace0107 实现；409 = 用户关了、503 = 装配坏了），修掉同标题重复入库（#505）、扫描谎报「没东西可扫」（#515）、五处未围栏的巩固 prompt（#501）与 dream 合并护栏整类误拦（#521），面板新增设置页分组目录（#518） |
 | **v0.10.0**（2026-11-02） | 归因与闸门——给已经发生的事补上它自己的身份：**蒸馏有了运行身份**（窗口级 `distill_runs` 记 `ok`/`degraded`/`noop`/`failed`/`aborted` 与 `audit_id`，行级 `memory_mints` 记「这条记忆出生自哪一轮巩固」；历史行留空**不猜**，失败轮也真记一行），此前归因只到「会话区间」——那是输入的坐标不是运行的身份；**溯源补上反方向** `GET /memory/provenance?sessionId=`（两个主键互斥，`limit` 越界 400 不静默截断，撞上限带 `truncated: true`）；**会话级无痕闸门** `sessionGateEnabled`（指定会话与子代理不进不出，其余会话照常；子代理判据只认宿主委派标记，`parentSession` 不是判据——本机 641 个会话头实测会误判 3 个 fork 主会话）；**防谄媚补到写入面**（蒸馏与总览加「立场纪律」四条与「叙述纪律」，排在与时间换算的指令之前）。另修 `differentiate` 正反馈闭环（注记改落 `differentiated_pairs` 账本、正文一个字节都改不了，实测单条曾堆 19 段）、sleep 冲突相位的输入侧预算与续排（分批后不再隔夜才轮到）、面板「最近巩固」区分 organize 回执（#495）、面板首次有移动端与 481–519px 中间带断点（#542） |
 | **v0.10.1**（2026-11-03） | 打开记忆详情不再崩掉整个宿主：0.10.0 里点开侧边栏任意一条记忆的详情抽屉，渲染进程立刻抛 `ReferenceError: provenance is not defined`，整个宿主跟着重启、进行中的会话被打断，100% 复现（#553）。根因是两个隔了三千多行的组件——`MemoryDrawer` 的归因 effect 与渲染块在读 `provenance` / `setProvenance`，而那句 `useState` 落在了同文件**上一个**组件 `EntityPanel` 里，在那里是纯死代码（整个函数体除声明外对 `provenance` 零引用）。这个形状躲得过眼睛、语法检查与原有用例，所以补的不是「锁一个名字」的用例，而是按组件扫「调了 `setXxx(` 却没有声明」。同版带上 v0.10.0 之后合入的图谱锚定层收尾（#24）：Tag 与向量两路起点接线（`normalizePath` 补回通路身份、`findEntitiesByTags` 走全等匹配并按 500 分块、反查改 UNION 三源以覆盖只看关系不建 attr 行的记忆、向量路复用同一份 query 向量并滤掉 0 分种子），以及被动确认的复核出口（`GET /semantic/graph/boosted-relations` 按「合法抬升量 > 0」列出、ego 边补 `weight`/`source`、面板默认收起的审计视角） |
+| **v0.11.0**（2026-11-05） | 仓库地志（chorography）落地并接到消费面：读一个 JS/TS 仓库，把文件树与 import 图编译成模块划分与 `.chorography/` 下的 Markdown 地志页——T0 骨架全程零模型零网络、`plan.yaml` 正面控制、`CHORO:HUMAN` 保留区跨重生成逐字节存活；T1 逐模块一次 headless 会话补架构/约定/技术栈/构建四段语义正文并落可核验的 claims（三重上限、编造锚点整轮拒）。消费面三张脸：面板第二座位 `dsh-mneme-wiki`、三个只读工具、`/choro/*` 读路由，外加每轮开局一小块标题级提纲注入（`chorographyInject` = light/full/off）与只读 `/choro` 命令（过期只提示、绝不自动重跑）。`chorographyEnabled` opt-in 默认关。wiki 行与记忆行物理隔离，永不进巩固/质量过滤任何行池。另修 #573：宽态侧栏的记忆入口落在「更多」行下面、被展开的菜单盖住 |
+| **v0.12.0**（2026-11-07） | pin 从「按类型推断」变成你亲手钉的显式事实：另开 `pinned_memories` 表 + `memory_pin`（取消钉选是同一个工具传 `unpin: true`，没有单独的 unpin 工具），钉住的行在注入里优先占位，不再依赖它恰好是 `constraint` / `preference`；顺带修掉两处旁路——pin 筛选发生在 hybrid 合并之后、而合并结果已按 `poolSize` 封顶（生产 10 条），规则窗口里的 pin 行一条都进不了候选池（真库副本 pin 注入 2/5 → 5/5、总数 7 → 10，原有条目只后移无一条被挤出），判据也从「表里有几行」改成「有几条能用」（pin 行会在记忆侧被归档 / 遗忘 / 硬删而 pin 表一无所知，旧判据只要剩一行就永不回落；`pinnedStats.source` 分 `explicit` / `fallback-none-usable` / `type-fallback` 三档）。`pinnedInjectBudget` **默认 0，即默认状态下 pin 池整体关闭**——钉住不等于会抢占注入位次，要显式设成正数才启用，关着时注入序列与改前逐条相同。同版带上「Agent 眼中的你」自动事实（`profileFactsEnabled` 默认关，按身份分卡维护、参与注入、面板可管）、向量解析缓存从恒 0% 命中到跟工作集自适应（真库四轮 0.0% → 第二轮起 100%，A/B 1.8–2.4s → 370–424ms，存储换 `Float32Array` 55.5MB → 29.7MB，并摘掉「只取 id 却带 `embedding != ''`」的谓词）、[#579](https://github.com/slow-stack/mneme/issues/579) 地志工具改走宿主错误路径且检索不再把「读不到」答成「没匹配」（@Oscar-Williams）、[#590](https://github.com/slow-stack/mneme/issues/590) 严格寻址不再把「一张卡都没建」判成「没有这张卡」，以及面板跨组件广播 `mneme:store-changed`、chorography 收尾（面板「重建骨架」+ 页级向量检索）。 |
 
 | **v0.8.x** | 作用域隔离（agent / workspace 双维 + opt-in 硬过滤）、冲突队列人工裁决、生态化（stdio MCP server / 图召回轴 / 冷启动 / 注入截断） |
 
@@ -685,7 +696,7 @@ Claude Code 挂载示例（项目根 `.mcp.json`；token 在面板「设置 →
 │  服务层：saveWithDedupe / injectCandidates        │
 │         / mergeHumanEdits / onWrite 钩子          │
 ├─────────────────────────────────────────────────┤
-│  模型接口：11 个工具 + 自动注入 + 会话摘要         │
+│  模型接口：12 个工具 + 自动注入 + 会话摘要         │
 ├─────────────────────────────────────────────────┤
 │  autoDream：阈值调度 → LLM 决策清单               │
 │            → 校验（fail-safe）→ 应用 → 摘要       │
@@ -703,7 +714,7 @@ src/
 ├── service.js        # 领域逻辑（去重合并、注入筛选、写入钩子、scope 加权/硬过滤、冲突队列）
 ├── scope.js          # 作用域解析（agentPreset + workspace registry 反查，issue #17）
 ├── config.js         # schemastery 配置 schema
-├── tools.js          # 11 个模型工具（defineTool；memory_organize 要 organizeEnabled 打开才注册，开了是 12 个）
+├── tools.js          # 12 个模型工具（defineTool；memory_organize 要 organizeEnabled 打开才注册，开了是 13 个）
 ├── user-settings.js  # 「用户设置」注入块（人格 → 画像 → 规则）的唯一渲染处，注入与面板预览共用
 ├── profile-extract.js # 从活跃记忆提取「助手眼中的用户」画像草稿（只出草稿，不写 user_settings）
 ├── organize.js       # agent 主动整理：dryRun 比对报告 → agent 判断 → apply 落库（筛除=归档不删，留 dream_runs 回执）
@@ -722,7 +733,7 @@ src/
 ├── api.js            # HTTP 路由（Web 面板数据通道，含 /conflicts 冲突队列）
 └── index.js          # 插件接线
 lib/                  # src 的同步分发产物（npm run sync，prepack 钩子在发布时自动跑；一致性由 scripts/check-sync.js 在 CI 与 release.yml 校验——它只查不同步；唯一手写例外 lib/client.js——Web 面板 bundle，sync 不覆盖）
-test/                 # 2681 个 node:test 测试（审计与三轴线压测不变量；src↔lib 一致性由 scripts/check-sync.js 发布闸门校验）
+test/                 # 2881 个 node:test 测试（审计与三轴线压测不变量；src↔lib 一致性由 scripts/check-sync.js 发布闸门校验）
 scripts/              # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压测 · sync-lib.js 同步 · check-sync.js 发布闸门 · benchmark-recall.js / benchmark-embed.js / benchmark-rerank.js 基准 · sync-test-badge.mjs 测试徽章 · build-runtime-manifest.mjs 运行时清单
 ```
 
@@ -731,7 +742,7 @@ scripts/              # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压
 ```bash
 cd dsh-mneme
 npm install        # 安装 peer 依赖（以 devDependencies 形式，用于本地测试）
-npm test           # 运行 2681 个测试
+npm test           # 运行 2881 个测试
 npm run stress     # 三轴线压测：长会话检索 / 冲突仲裁 / 多 Agent 并发（离线 mock LLM）
 npm run sync       # 把 src/ 同步到 lib/（发布时由 prepack 钩子自动执行）
 ```

package/bin/dsh-mneme-choro.mjs

@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+// bin/dsh-mneme-choro.mjs —— chorography（仓库地志）T0 确定性骨架的命令行入口。
+//
+// 为什么独立成 bin 而不是 cli.mjs 的子命令：CONTRIBUTING「The CLI is dependency-free
+// by contract」禁止给 bin/cli.mjs 加 import，而 T0 要挂 lib/ 的扫描/划分/渲染与
+// store（写 choro_* 表）；命名循 dsh-mneme-serve / dsh-mneme-mcp 先例。
+//
+// 为什么缺省 dry-run、--apply 才写：会动仓库磁盘的东西先给数字再执行（reclaim 同款
+// 纪律）。dry-run 零写入，receipt 里有「会写哪些文件、各多大」。
+//
+// T1（--t1）沿用同一条纪律，且以「花不花钱」再加一道：dry-run 只列候选模块与跳过
+// 原因，--apply 才真开 headless 会话（吃宿主模型额度）。
+//
+// stdout 纪律：一次成功/dry-run 的 receipt 走 stdout（人读或 --json 机器读），错误
+// 与拒绝走 stderr；exit 0 = dry-run 或成功，exit 1 = 拒绝/失败。
+import fs, { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createStore } from "../lib/store.js";
+import { runChoroT0, ChoroRefusal } from "../lib/wiki/t0.js";
+import { createT1, DEFAULT_T1_MODEL, T1Refusal } from "../lib/wiki/t1.js";
+
+const BIN_NAME = "dsh-mneme-choro";
+const PKG = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8"));
+
+const USAGE = `${BIN_NAME} — 仓库地志（chorography）：T0 确定性骨架 + T1 语义生成轮
+
+用法:
+  ${BIN_NAME} <repo-path> [选项]
+
+选项:
+  --apply        实际写入 <repo>/.chorography/ 并落库（缺省 dry-run，只报数字）
+  --t1           T1 语义生成轮：逐模块一轮 headless 会话补四段语义正文 + claims。
+                 缺省 dry-run 只列候选；--apply 才开会话（花宿主模型额度）
+  --module <slug>      只跑一个模块（T1）
+  --model <p/m>        T1 模型路由（缺省 xdpool/deepseek-v4.1-flash）
+  --timeout <秒>       T1 单模块墙钟上限（缺省 240s）
+  --retry-failed       把 failed 页拉进来重试（T1；成功后计数清零）
+  --dsh-exe <路径>     DeepSeek Harness 主程序定位（缺省走 DSH_EXE / 标准安装位）
+  --db <path>    memory.db 路径（缺省 ~/.dsh/memory/memory.db，前导 ~ 会展开）
+  --json         receipt 用机器可读 JSON 输出
+  -h, --help     本帮助
+  -V, --version  版本
+
+T0 是确定性骨架（零模型、可离线）：文件树 + import 图 → 模块划分 → 骨架页。
+T1 用 headless 会话补语义段落与溯源 claims（逐模块、三重上限、失败不推进）。
+
+页面里 CHORO:HUMAN 标记块的内容在重生成时逐字节保留；块外手改不保留。
+`;
+
+function parseArgv(argv) {
+  const positionals = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--apply") flags.apply = true;
+    else if (arg === "--json") flags.json = true;
+    else if (arg === "--t1") flags.t1 = true;
+    else if (arg === "--retry-failed") flags.retryFailed = true;
+    else if (arg === "--module" || arg === "--model" || arg === "--dsh-exe") {
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) {
+        throw new Error(`${arg} 需要一个参数`);
+      }
+      flags[arg.slice(2)] = next;
+      i++;
+    } else if (arg === "--timeout") {
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) {
+        throw new Error("--timeout 需要一个秒数");
+      }
+      // 现算一次：NaN 会一路混进 spawn 的 timeoutMs，表现成「上限不生效」而不是报错。
+      const secs = Number(next);
+      if (!Number.isFinite(secs) || secs <= 0) throw new Error(`--timeout 需要正数秒：${next}`);
+      flags.timeout = secs;
+      i++;
+    } else if (arg === "--db") {
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) {
+        throw new Error("--db 需要一个路径参数");
+      }
+      flags.db = next;
+      i++;
+    } else if (arg === "-h" || arg === "--help") flags.help = true;
+    else if (arg === "-V" || arg === "--version") flags.version = true;
+    else if (arg.startsWith("--")) throw new Error(`未知选项: ${arg}`);
+    else positionals.push(arg);
+  }
+  return { positionals, flags };
+}
+
+// 前导 ~ 展开，语义与 src/serve.js 同款（~ 只在开头、后面跟 / 或 \ 或结尾）。
+function expandHome(path) {
+  const home = homedir();
+  return String(path).replace(/^~(?=$|[\\/])/, home);
+}
+
+function defaultDbPath() {
+  return expandHome("~/.dsh/memory/memory.db");
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  let parsed;
+  try {
+    parsed = parseArgv(argv);
+  } catch (err) {
+    console.error(String(err?.message ?? err));
+    process.exit(1);
+  }
+  const { positionals, flags } = parsed;
+  if (flags.version) {
+    console.log(PKG.version);
+    return;
+  }
+  if (flags.help) {
+    console.log(USAGE.trimEnd());
+    return;
+  }
+  if (positionals.length === 0) {
+    console.error(USAGE.trimEnd());
+    console.error(`\n缺仓库路径：${BIN_NAME} <repo-path> [--apply]`);
+    process.exit(1);
+  }
+  if (positionals.length > 1) {
+    console.error(`多余的位置参数：${positionals.slice(1).join(" ")}（仓库路径只有一个，含空格请加引号）`);
+    process.exit(1);
+  }
+
+  const repoPath = resolve(positionals[0]);
+  const dbPath = resolve(expandHome(flags.db ?? defaultDbPath()));
+
+  let store;
+  try {
+    store = createStore(dbPath);
+  } catch (err) {
+    console.error(`打开 memory.db 失败（${dbPath}）：${String(err?.message ?? err)}`);
+    process.exit(1);
+  }
+
+  try {
+    if (flags.t1) {
+      // T1 档（M2）：缺省 dry-run 只列候选模块与章程预览（零会话零写入）；
+      // --apply 才真开会话花钱。三重上限与降级表在 createT1 里。
+      const t1 = createT1({ store });
+      const receipt = await t1.runT1({
+        repoRoot: repoPath,
+        model: flags.model ?? DEFAULT_T1_MODEL,
+        moduleSlug: flags.module ?? null,
+        retryFailed: flags.retryFailed === true,
+        dryRun: flags.apply !== true,
+        dshExe: flags["dsh-exe"] ?? null,
+        limits: flags.timeout ? { timeoutMs: flags.timeout * 1000 } : null,
+      });
+      console.log(flags.json ? JSON.stringify(receipt, null, 2) : renderT1Receipt(receipt, { apply: flags.apply === true }));
+      return;
+    }
+    const receipt = runChoroT0({ repoRoot: repoPath, store, apply: flags.apply === true });
+    console.log(flags.json ? JSON.stringify(receipt, null, 2) : renderReceipt(receipt));
+  } catch (err) {
+    if (err instanceof ChoroRefusal || err instanceof T1Refusal) {
+      console.error(`拒绝运行（${err.code}）：${err.message}`);
+    } else {
+      console.error(`${BIN_NAME} 失败：${err?.stack ?? String(err)}`);
+    }
+    process.exitCode = 1;
+  } finally {
+    try { store.close(); } catch { /* WAL 关闭异常不遮蔽主结果 */ }
+  }
+  if (process.exitCode) process.exit(process.exitCode);
+}
+
+function renderT1Receipt(r, { apply }) {
+  const lines = [];
+  const head = r.dryRun ? "T1 dry-run（未开任何会话；确认后加 --apply）" : "T1 已跑";
+  lines.push(`${head} · ${r.repoName} · 模型 ${r.model}`);
+  if (r.t1Unavailable) {
+    lines.push(`T1 整档不可用（环境级，页状态未动）：${r.t1Unavailable}`);
+    lines.push("候选模块仍在下面，环境修好后重跑即可。");
+    lines.push("");
+  }
+  if (r.dryRun) {
+    lines.push(`将富化的模块（${r.candidates.length}）：`);
+    for (const c of r.candidates) lines.push(`  ${c.slug.padEnd(24)} ${String(c.fileCount).padStart(4)} 文件 · ${c.status}`);
+    lines.push(`跳过（${r.skipped.length}）：`);
+    for (const s of r.skipped) lines.push(`  ${s.slug} — ${s.reason}`);
+    lines.push(`三重上限：${r.limits.timeoutMs}ms 墙钟 / ${r.limits.maxToolCalls} 次工具 / ${r.limits.maxOutputBytes}B 输出`);
+    lines.push("");
+    lines.push("每个模块一轮 headless 会话，会花宿主模型额度；确认后加 --apply。");
+  } else {
+    lines.push(`富化 ${r.enriched.length} · 失败 ${r.failed.length} · 跳过 ${r.skipped.length}${r.t1Unavailable ? " · 整档中止（见上）" : ""}`);
+    for (const e of r.enriched) lines.push(`  ✓ ${e.slug}（${e.sections.join("/")} · claims ×${e.claims}）`);
+    for (const f of r.failed) lines.push(`  ✗ ${f.slug} — ${f.reason}${f.marked ? "（连续失败达阈值，标记 failed）" : ""}`);
+    for (const s of r.skipped) lines.push(`  · ${s.slug} — ${s.reason}`);
+  }
+  for (const w of r.warnings ?? []) lines.push(`提示：${w}`);
+  return lines.join("\n");
+}
+
+function renderReceipt(r) {
+  const lines = [];
+  const head = r.dryRun ? "dry-run（未写任何东西；确认后加 --apply）" : "已写入";
+  lines.push(`${head} · ${r.repoName} @ ${r.repoPath}`);
+  lines.push(`git 基线 ${r.gitBaseline} · 计划 ${r.planPath ?? "（无 plan.yaml，走默认启发式）"}`);
+  lines.push(
+    `扫描 ${r.fileCount} 个文件 → ${r.moduleCount} 个模块 → ${r.pageCount} 页` +
+    (r.skippedByWhitelist > 0 ? `（白名单挡掉 ${r.skippedByWhitelist} 页）` : "") +
+    ` · generatedAt ${r.generatedAt}${r.reusedGeneratedAt ? "（沿用上次）" : ""}`
+  );
+  if (r.skippedFiles.length > 0) {
+    lines.push(`跳过 ${r.skippedFiles.length} 个读不了的文件：`);
+    for (const s of r.skippedFiles.slice(0, 5)) lines.push(`  · ${s.file} — ${s.reason}`);
+    if (r.skippedFiles.length > 5) lines.push(`  … 共 ${r.skippedFiles.length} 个`);
+  }
+  if (r.unresolvedCount > 0) lines.push(`${r.unresolvedCount} 条相对引用未解析（别名/动态路径），未计入依赖图。`);
+  lines.push("");
+  lines.push("模块划分：");
+  for (const m of r.moduleSummary) {
+    lines.push(`  ${m.slug.padEnd(28)} ${String(m.fileCount).padStart(4)} 文件 · ${m.internalEdges} 边 · ${m.externalDeps} 外部依赖 · ${m.title}`);
+  }
+  lines.push("");
+  if (r.dryRun) {
+    lines.push("将写入：");
+    for (const w of r.wouldWrite) lines.push(`  ${w.path}（${w.bytes} B）`);
+    lines.push(`会保留的 CHORO:HUMAN 保留区：${r.humanBlocksSeen} 块`);
+    lines.push("");
+    lines.push("确认无误后加 --apply 执行。");
+  } else {
+    lines.push(`写入 ${r.bytes} B；保留区 ${r.humanBlocksPreserved} 块逐字节未动；choro_* 表已整仓替换。`);
+  }
+  for (const w of r.warnings) lines.push(`提示：${w}`);
+  return lines.join("\n");
+}
+
+// 直接运行才进 main（import 只取 parseArgv 做单测时必须安静）：npm 全局安装走
+// node_modules/.bin 的符号链接，argv[1] 是链接路径而非真身，所以 realpath 两侧再比。
+const invokedDirectly = (() => {
+  if (process.argv[1] == null) return false;
+  try {
+    return fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+
+if (invokedDirectly) {
+  main().catch((err) => {
+    console.error(err?.stack ?? String(err));
+    process.exit(1);
+  });
+}
+
+export { parseArgv };

package/docs/CONFIGURATION.md

@@ -12,6 +12,11 @@
 - 行为开关（布尔键）默认关的即 opt-in：不开 = 行为与该键存在之前逐字节一致。
 - 绝大多数行为开关与部分阈值/路由键在 `settings.js` 的白名单里，可在面板「功能开关」
   逐项启停（线上回滚开关）；未入白名单的键（路径、词典、枚举外的杂项）只能改 bundle 配置。
+- **「面板能改 / 只能改文件」不用在这里逐行标注**：面板「设置 → 连接 → 配置键覆盖面」
+  那张只读卡会实时把两者交/差出来（`GET /api/dsh-mneme/config-keys`，只回键名与计数、
+  不回任何值）。清单由 `src/config-keys.js` 从 schema 与白名单现算，改哪边都不会漏。
+  那里还会单独列出「白名单登记了、但 schema 没给默认值」的键——这类键在面板上有输入框，
+  留空时却不会进「当前生效值」。
 
 ## 全局与存储
 
@@ -162,7 +167,8 @@
 | `injectTimePrefix` | `false` | 对话开始注入一次当前时间（#34，v0.7.11 误删后随 #333 恢复） | opt-in；格式与键名与 v0.7.2 一致，存量 feature_flags 恢复即生效 |
 | `personaEnabled` | `false` | 人格段：用户自写的一小段常驻注入文本 | opt-in；只是轻量常驻文本、不引入重型后台路径，故不进 `LIGHT_MODE_OFF` |
 | `personaStrictAddressing` | `false` | 人格寻址口径。关（历史行为）：会话身份没建卡、或该卡被显式关掉时，落 `default` 卡 | 开：这两种情况都不注入人格，`default` 只兜「解析不到会话身份」的无名会话。用途是宿主里跑着自带身份的外部 bot 时，别让某个人格无条件进它每一帧。默认关 = 升级零变化 |
-| `profileExtractEnabled` **light** | `false` | 画像提取草稿：`POST /api/dsh-mneme/profile/extract` 从活跃记忆反向写一段「助手眼中的用户」草稿（面板「用户画像」卡上的按钮） | opt-in；一次调用一轮 LLM + 读上百行记忆，故 `LIGHT_MODE_OFF` 里有它。**只出草稿**：它不写 `user_settings`，采用草稿是面板里另一次显式保存——画像正文必须是用户手写的原文。空库直接报 `no-input`、模型没按格式回报 `unparseable`，两者都不回空草稿 |
+| `profileExtractEnabled` **light** | `false` | 画像提取草稿：`POST /api/dsh-mneme/profile/extract` 从活跃记忆反向写一段「助手眼中的用户」草稿（面板「Agent 眼中的你」卡上的按钮） | opt-in；一次调用一轮 LLM + 读上百行记忆，故 `LIGHT_MODE_OFF` 里有它。**只出草稿副本**：它不写 `user_settings`，面板也只把结果当副本展示、可一键复制（2026-11-04 改口径，此前「采用为画像」会直接覆盖手写画像且无撤销）——画像正文必须是用户自己手写的原文。空库直接报 `no-input`、模型没按格式回报 `unparseable`，两者都不回空草稿 |
+| `profileFactsEnabled` **light** | `false` | 自动画像事实：「Agent 眼中的你」按会话身份分卡维护一份逐条事实清单（对标 ChatGPT 记忆 / DS Bot 每 bot 的 MEMORY.md）——dream 巩固轮成功后逐卡增量维护（有新记忆才跑），注入在手填画像之后；面板可手动触发与逐条增改归档，账本逐 op 可查 | opt-in；自动维护轮是 dream 级 LLM 调用 + 读上百行记忆，故 `LIGHT_MODE_OFF` 里有它（注入段本身是几十行常驻文本，关掉省的是维护调用不是注入）。事实住 `profile_facts` 独立三表，**绝不写 `user_settings`**（#497 口径不变：手填画像是用户原文，模型只有读权）。输入行严格按 `agent_scope` 分区、排除外来行；账本 `profile_fact_journal` 每卡裁剪到最近 200 条 |
 
 ## 巩固（autoDream）
 
@@ -310,6 +316,8 @@
 | `disableMemorySearch` | `false` | 对模型隐藏 `memory_search` 工具（v0.8.5） | 慢/轻量模型的工具往返节流；隐藏即不可调 |
 | `disableMemoryArchive` | `false` | 对模型隐藏 `memory_archive` 工具 | 同上 |
 | `organizeEnabled` | `false` | 对模型开放 `memory_organize` 工具（#231：先 dryRun 出比对报告，agent 判断后 apply 落库） | 与上面两个**反向**：那两个藏默认在场的工具，本键开默认不在场的能力。关 = 工具根本不注册（模型看不到就不会调）。dryRun→apply 是两步协议，弱模型容易漏 `run_id` 或跳过报告，所以 `LIGHT_MODE_OFF` 里有它；apply 只能引用一次真实报告、且一份报告只许落地一次 |
+| `chorographyEnabled` | `false` | chorography（仓库地志，spec 见 docs/specs/）暴露闸：对模型开放三个只读工具（`choro_search` / `choro_read_page` / `choro_module_map`）+ 面板「仓库地志」浏览页 + 每轮的开局提纲注入 + `/choro` 命令 | 与 `organizeEnabled` 同款反向语义：关 = 工具根本不注册、面板页空态、注入块不渲染、命令不注册，行为与旧版逐字节一致。本键是「是否启用这个子系统」，不是「每轮付多少」——所以它仍**不进 `LIGHT_MODE_OFF`**，轻量档要压的是下面那条 `chorographyInject`。检索是关键词子串（M1）；生成走 `dsh-mneme-choro` CLI（T0 确定性骨架 + `--t1` headless 语义富化） |
+| `chorographyInject` | `"light"` | 开局注入档位：`light` 只列文件数最多的 6 个模块（约 8 行）、`full` 列全部模块、`off` 不注入 | 只注模块名 / 文件数 / 页状态 / 页相对路径，**不含正文**（正文由模型 `choro_read_page` 取）；注入块折进既有 memory context，不新开 context（spec §7「合并成一次拼装」）。`lightMode: true` 时在消费侧压成 `off`（见 `wiki/inject.js` 的 `resolveInjectTier`）——它**不进 `LIGHT_MODE_OFF` 表**，因为那张表对平铺键一律赋 `false`，枚举值塞进去会与 schema 不符 |
 | `actionPipelineEnabled` | `false` | M.O. 只读视图的门控：做法图谱 + 对话行结算卡 | opt-in beta；只是纯 UI 入口、不引入重型后台路径，故不进 `LIGHT_MODE_OFF`。写账另有独立的执行记账键（`/mo-run`），看图 ≠ 写账 |
 | `actionRunEnabled` | `false` | M.O. 执行记账：`/mo-run` 开一次执行窗口，窗口内命令执行才可能被记成一条 run | opt-in beta；挂在热路径（每个会话事件都过一次监听），故 `LIGHT_MODE_OFF` 里有它 |
 | `actionNudgeEnabled` | `false` | M.O. 自动沉淀：每轮结束（`turn/end`）后挖一次「这个项目重复走的动作」，结果落成 `memoryDir/proposals/<项目键>/` 里的提议，等人确认 | opt-in beta；三个 M.O. 键里最重的一条——挂 `session/event` 且要**同步解压 zstd 会话日志**（本机 118 份实测 16.2s，单次预算 `budgetMs`=4s 兜底），故 `LIGHT_MODE_OFF` 里有它。**永不自动落草稿**：`materialize` 恒 false，进仓库必须是人的显式动作 |
@@ -348,6 +356,7 @@
 `dreamNarrativeEnabled` · `documentMemoryEnabled` · `heatEnabled` · `continuityRescueEnabled` ·
 `organizeEnabled`（#231） ·
 `profileExtractEnabled`（#497） ·
+`profileFactsEnabled`（2026-11-06） ·
 `preInjectGate.enabled`（#380） · `distillRecords.enabled`（#399）
 
 预设只是默认值而非强制：用户显式写进 feature_flags 的值在装配顺序上后展开、仍然生效

package/lib/api-standalone.js

@@ -18,6 +18,7 @@ import { randomBytes, timingSafeEqual } from "node:crypto";
 import { homedir } from "node:os";
 import { TYPES } from "./store.js";
 import { bootstrapFromDirectory } from "./bootstrap.js";
+import { parseBootstrapJson, readBootstrapDir, bootstrapReply } from "./bootstrap-http.js";
 import { PACKAGE_VERSION } from "./version-check.js";
 import { parseReclaimJson, readReclaimFields, reclaimReply, RECLAIM_UNAVAILABLE } from "./reclaim-http.js";
 import { parseShareBody, shareReply, parseReceiveBody, receiveReply, parseUndoBody, undoReply } from "./share-http.js";
@@ -763,34 +764,29 @@ export function createStandaloneApi({ service, store, config = {}, logger, setti
       // --- POST /bootstrap: cold-start memories from repo files (#220) -------
       // 显式收 dir（插件没有工作区根目录概念，不猜路径）；确定性解析零 LLM；
       // 幂等骑 saveWithDedupe 的 (type, title, scope) 去重 + _overwrite 刷新。
+      //
+      // 解析、校验、答复形状全走 bootstrap-http.js：#386 第 6 条给宿主内路由补了
+      // 第二张脸，按 #411 的纪律，两张皮只许剩鉴权与路径不同。这里刻意**不**再
+      // 自己 JSON.parse 一遍——真要写第二份，test/reclaim-http.test.js 那类静态锁
+      // 会转红，而漂移在两边都只表现为「某个错误码不一样了」。
       if (req.method === "POST" && pathname === "/bootstrap") {
         void readBody(req, res).then((text) => {
           if (text === null) return;
-          let body;
-          try {
-            body = JSON.parse(text || "{}");
-          } catch {
-            sendJson(res, 400, { error: "invalid-json" });
-            return;
-          }
-          if (body === null || typeof body !== "object" || Array.isArray(body)) {
-            sendJson(res, 400, { error: "invalid-body" });
+          const parsed = parseBootstrapJson(text);
+          if (!parsed.ok) {
+            sendJson(res, 400, { error: parsed.error });
             return;
           }
-          if (typeof body.dir !== "string" || !body.dir.trim()) {
-            sendJson(res, 400, { error: "missing-dir" });
+          const dirResult = readBootstrapDir(parsed.body);
+          if (!dirResult.ok) {
+            sendJson(res, 400, { error: dirResult.error });
             return;
           }
-          bootstrapFromDirectory({ service, dir: body.dir, logger })
-            .then((summary) => sendJson(res, 200, summary))
-            .catch((error) => {
-              if (error?.code) {
-                sendJson(res, 400, { error: error.code });
-                return;
-              }
-              logger?.warn?.(`[dsh-mneme] standalone API bootstrap failed: ${String(error)}`);
-              sendJson(res, 500, { error: "internal" });
-            });
+          bootstrapReply({
+            bootstrapper: ({ dir }) => bootstrapFromDirectory({ service, dir, logger }),
+            dir: dirResult.dir,
+            warn: (msg) => logger?.warn?.(msg)
+          }).then(({ status, body }) => sendJson(res, status, body));
         });
         return;
       }