@modusensus/dsh-mneme 0.10.1 → 0.11.0

package/src/api.js

@@ -3,7 +3,7 @@ import { isAbsolute } from "node:path";
 import { existsSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { timingSafeEqual, randomBytes } from "node:crypto";
-import { FEATURE_FLAG_SPEC } from "./settings.js";
+
 import { TYPES } from "./store.js";
 import { TYPE_FILE, renderMirrorText, renderFileHeader, parseHumanEdits, MIRROR_READONLY_TYPES } from "./mirror.js";
 import { langOf } from "./lang.js";
@@ -19,6 +19,14 @@ import { describeLocalRuntime, publicRuntimeStatus } from "./runtime/loader.js";
 import { hostModulesDir, provisionRuntime } from "./runtime/provision.js";
 import { classify, fetchLatestVersion, PACKAGE_VERSION } from "./version-check.js";
 import { parseReclaimQuery, parseReclaimJson, readReclaimFields, reclaimReply, RECLAIM_UNAVAILABLE } from "./reclaim-http.js";
+// Issue #386 第 6 条：从目录引导（bootstrap）在面板侧也要有入口。协议层口径只在
+// bootstrap-http.js 里写一份，与 Bearer 数据面共用（#411 那条纪律：两张皮只许剩
+// 鉴权与路径不同）。
+import { parseBootstrapJson, readBootstrapDir, bootstrapReply, BOOTSTRAP_UNAVAILABLE } from "./bootstrap-http.js";
+import { bootstrapFromDirectory } from "./bootstrap.js";
+// Issue #386 第 7 条：面板能改的键 vs schema 里存在的键，两份清单的唯一算法在这里。
+// 这里引的是同一份（不是照抄），谁改白名单都对得上。
+import { describeConfigKeys, flagKeysFromSpec } from "./config-keys.js";
 import { parseShareBody, shareReply, shareFilename, parseReceiveBody, receiveReply, parseUndoBody, undoReply } from "./share-http.js";
 import { readPipelineDoc, loadPipelines, projectPipelineDir } from "./pipeline.js";
 import { loadRunsById, runsDir, RUNS_SUFFIX } from "./pipeline-runs.js";
@@ -189,7 +197,10 @@ function parseBody(text) {
 // maintenance 是第 9 个位置参数，默认 null：既有调用点（测试里的 14 处）全是位置传参、
 // 不传它，必须继续工作——不传时 /maintenance/reclaim 回 503 maintenance-unavailable，
 // 而不是把「没接线」伪装成崩溃（#386 第 4 条）。
-export function createApi(ctx, service, settings, commands, embedder, semantic = null, apiToken = "", config = null, maintenance = null, profileExtract = null) {
+// choro（M1）：chorography 读侧查询对象（createChoroQueries 产物）。缺省 null =
+// 宿主内 API 在 headless/测试环境没有接 queries，choro 路由回 503。它与 service
+// 刻意分开传——chorography 的所有权模型与记忆域相反（spec §3），不塞进 service。
+export function createApi(ctx, service, settings, commands, embedder, semantic = null, apiToken = "", config = null, maintenance = null, profileExtract = null, choro = null) {
   const disposers = [];
 
   // #182 注入状态探测：面板状态页的「极简模式下注入按宿主设计关闭」提示需要
@@ -231,14 +242,10 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   // **反推不出待重启**，必须另比一次冻结值——这是本字段存在的唯一理由。
   // 只报「显式覆盖 ≠ 冻结值」的键：未被覆盖的键运行时值就是 cfg 值，不存在落差；
   // config 缺席（旧调用方直连、未传 cfg）时无从比较，返回空数组而不编造。
-  const flagKeys = [
-    ...FEATURE_FLAG_SPEC.booleans,
-    ...Object.keys(FEATURE_FLAG_SPEC.ints),
-    ...Object.keys(FEATURE_FLAG_SPEC.numbers),
-    ...FEATURE_FLAG_SPEC.strings,
-    ...FEATURE_FLAG_SPEC.urls,
-    ...Object.keys(FEATURE_FLAG_SPEC.enums)
-  ];
+  // 顺序见 config-keys.js 的 flagKeysFromSpec（booleans → ints → numbers → strings
+  // → urls → enums）。这张表曾经在这里手拼一遍，第 7 条把「面板能改哪些键」做成
+  // 对外清单之后，两处各算一份就会立刻分歧——所以搬进模块，这里只引。
+  const flagKeys = flagKeysFromSpec();
   // 嵌套键在 kv 里按点号平铺（"memoryQualityFilter.enabled"），运行时 cfg 里
   // 是嵌套对象，effective 从对象子字段取值；其余键照旧从 cfg 顶层取。
   // 这张表必须与 settings.js 白名单里的点号键一一对应：#254 加键时漏了这里，
@@ -1308,6 +1315,27 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     }
   });
 
+  // 沉淀曲线（面板「8 周沉淀」图）：按天返回 added / merged / archived 三条序列。
+  // 与 llm-audit/stats 并列但不同源——那边算的是「花了多少 token」，这边算的是
+  // 「进来了多少条、真被巩固掉多少条、归档了多少条」。合并数与新增数背离时
+  // （2026-10-25~10-31 那段：新增照旧、合并归零）这张图是唯一能一眼看出来的地方。
+  // 窗口钳制 1-365 天（缺省 56，正好是热力图的 8 周），口径见 store.getConsolidationStats。
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/semantic/consolidation-stats",
+    policy: "open",
+    handler(req, res) {
+      try {
+        const url = new URL(req.url, "http://localhost");
+        const days = Math.max(1, Math.min(365, Number(url.searchParams.get("days") ?? 56) || 56));
+        const stats = service.getConsolidationStats?.({ days }) ?? null;
+        sendJson(res, 200, stats ?? { error: "unavailable" });
+      } catch {
+        sendJson(res, 500, { error: "internal" });
+      }
+    }
+  });
+
   // --- 记忆级溯源读出口（#399 写、#421 读）-----------------------------------
   // #399 把蒸馏窗口的原文落进 distill_records、把 memory → (session, seq 区间)
   // 的归因写进 memory_provenance，但只做了写：库里有答案、service.provenanceFor
@@ -1548,7 +1576,26 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
         const url = new URL(req.url, "http://localhost");
         const limit = Math.min(1000, Math.max(1, Number(url.searchParams.get("limit") ?? 500) || 500));
         const entities = service.listEntities?.({ limit }) ?? [];
-        sendJson(res, 200, { entities, total: entities.length });
+        // total 是**全库**实体数，不是本次切片长度：目录带 limit，面板拿它当
+        // 「一共抽出多少实体」，填切片长度会让 1.6 万实体永远显示成 500。
+        // 老宿主（service 上没有 countEntities）回落到切片长度，不抛。计数本身失败也
+        // 只回落、不冒泡：它在外层 try 里，一抛整条响应就变成 500，已经把切片读出来的
+        // 那份列表也跟着丢掉——一个装饰性的总数不该决定目录能不能显示。
+        let total = entities.length;
+        // totalExact 是给面板看的：计数失败或老宿主没这个方法时，total 只能退回切片
+        // 长度，那已经不是「全库有多少」而只是「这次取回多少」。不回这个标记，面板
+        // 会把切片长度当成全库数照常显示——正是这条路由原来那个「永远 500」的错法。
+        let totalExact = false;
+        if (typeof service.countEntities === "function") {
+          try {
+            total = service.countEntities();
+            totalExact = true;
+          } catch {
+            total = entities.length;
+            totalExact = false;
+          }
+        }
+        sendJson(res, 200, { entities, total, totalExact });
       } catch {
         sendJson(res, 500, { error: "internal" });
       }
@@ -1808,6 +1855,85 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     }
   });
 
+  // --- 从目录引导（bootstrap，#386 第 6 条）------------------------------------
+  // 后端能力从 #220 起就在（src/bootstrap.js：六类确定性产物、零 LLM、吃
+  // saveWithDedupe 的去重），但只有 Bearer 数据面一条入口，面板够不着——「用户照
+  // 文档去找入口，发现产品界面里没有」。
+  //
+  // policy 取 token 而不是 token-write：它写记忆（虽然幂等），与 /import 同类，
+  // 而 /import 就是整条要 token 的。GET 不给读分支：没有「预览一次引导会写什么」
+  // 的形态，硬造一个 dryRun 等于把 bootstrap.js 拆成两半，收益不抵风险。
+  //
+  // 为什么不在服务端限制目录范围：插件没有「工作区根」概念（bootstrap.js 的注释
+  // 写着不猜路径），而这条路由与 /export、/import 同级，本来就能读写整库；额外加
+  // 一个路径白名单只会让人以为它比邻座更安全。
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/bootstrap",
+    policy: "token",
+    handler(req, res) {
+      try {
+        if (req.method !== "POST") {
+          sendJson(res, 404, { error: "not-found" });
+          return;
+        }
+        return readBody(req, res).then((text) => {
+          if (text === null) return;
+          const parsed = parseBootstrapJson(text);
+          if (!parsed.ok) {
+            sendJson(res, 400, { error: parsed.error });
+            return;
+          }
+          // 顺序：先判 body 形状与 dir，再判能力是否接线。缺 dir 是调用方的问题，
+          // 报「能力没接线」会把人引到错误的排查方向（reclaim 那边同一条纪律）。
+          const dirResult = readBootstrapDir(parsed.body);
+          if (!dirResult.ok) {
+            sendJson(res, 400, { error: dirResult.error });
+            return;
+          }
+          if (typeof service?.saveWithDedupe !== "function") {
+            sendJson(res, 503, { error: BOOTSTRAP_UNAVAILABLE });
+            return;
+          }
+          return bootstrapReply({
+            bootstrapper: ({ dir }) => bootstrapFromDirectory({ service, dir, logger: ctx.logger }),
+            dir: dirResult.dir,
+            warn: (msg) => ctx.logger?.warn?.(msg)
+          }).then(({ status, body }) => sendJson(res, status, body));
+        });
+      } catch {
+        sendJson(res, 500, { error: "internal" });
+      }
+    }
+  });
+
+  // --- 配置键覆盖面（#386 第 7 条，只读）--------------------------------------
+  // 面板能改的键（settings.js 白名单）与 schema 里存在的键（config.js）是两张表，
+  // 从没被摆在一起对过。这条路由把它们交/差出来，回答「哪些键只能改配置文件」。
+  //
+  // 只回**键名与计数**，一个值都不回：apiToken 这类敏感键的名字出现在「仅配置
+  // 文件」清单里正是这条 issue 想让人看见的东西（否则用户不知道它存在），但值
+  // 出这道门就会成为一个新的泄漏面。
+  //
+  // policy 取 open：与 /inject-status、/features 的读分支同级——面板要渲染，且
+  // 键名本身已经逐条写在 docs/CONFIGURATION.md 里（公开文档），不构成新秘密。
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/config-keys",
+    policy: "open",
+    handler(req, res) {
+      try {
+        if (req.method !== "GET") {
+          sendJson(res, 404, { error: "not-found" });
+          return;
+        }
+        sendJson(res, 200, describeConfigKeys());
+      } catch {
+        sendJson(res, 500, { error: "internal" });
+      }
+    }
+  });
+
   // --- 巩固状态（dream 面板）--------------------------------------------------
   // 只读：最近巩固运行（最多 5 条，created_at DESC）+ 未解决冲突队列。
   // pendingMemoryIds 从未解决冲突行提取涉及的记忆 id，去重后上限 200，避免积
@@ -2431,6 +2557,116 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     }
   });
 
+  // --- chorography（仓库地志）M1 读侧路由 -------------------------------
+  // spec §7 消费面的面板数据源。四条全 policy "open"：只读、宿主围栏统一鉴权
+  // （与 /list、/version-check 同级）；**chorographyEnabled 关闭时一律 409
+  // disabled**（#497 先例：路由挂着、逻辑层挡——面板据此渲染「未启用」空态）。
+  // 仓库/模块/页面全部只从 choro_* 表与仓库磁盘读（真源是盘上的 MD），没有
+  // 任何写路径；生成入口在 M2 才有（T1 生成轮同批接）。
+  // choro 参数缺省 null：headless/测试环境没有 queries 时这四条路由回 503
+  // unavailable（语义分叉见 #497：503 = 环境缺件，409 = 用户没开）。
+  function choroGate(req, res) {
+    if (!choro) {
+      sendJson(res, 503, { error: "unavailable", reason: "choro-queries-unavailable" });
+      return false;
+    }
+    if (!config || config.chorographyEnabled !== true) {
+      sendJson(res, 409, { error: "disabled", reason: "chorography-not-enabled" });
+      return false;
+    }
+    return true;
+  }
+  function choroResolveOr4xx(req, res) {
+    const repo = choro.resolveRepo(
+      new URL(req.url, "http://localhost").searchParams.get("repo")
+    );
+    if (!repo || repo.ambiguous) {
+      sendJson(res, repo && repo.ambiguous ? 400 : 404, {
+        error: repo && repo.ambiguous ? "repo-ambiguous" : "repo-not-found",
+        repos: repo && repo.ambiguous ? repo.ambiguous : undefined
+      });
+      return null;
+    }
+    return repo;
+  }
+
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/choro/repos",
+    policy: "open",
+    handler(req, res) {
+      if (!choroGate(req, res)) return;
+      sendJson(res, 200, { repos: choro.listRepos() });
+    }
+  });
+
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/choro/modules",
+    policy: "open",
+    handler(req, res) {
+      if (!choroGate(req, res)) return;
+      const repo = choroResolveOr4xx(req, res);
+      if (!repo) return;
+      const { modules, edges } = choro.moduleMap(repo.id);
+      sendJson(res, 200, {
+        repo: { id: repo.id, name: repo.name, gitBaseline: repo.git_baseline },
+        modules,
+        edges
+      });
+    }
+  });
+
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/choro/page",
+    policy: "open",
+    handler(req, res) {
+      if (!choroGate(req, res)) return;
+      const repo = choroResolveOr4xx(req, res);
+      if (!repo) return;
+      const slug = new URL(req.url, "http://localhost").searchParams.get("slug");
+      if (!slug) {
+        sendJson(res, 400, { error: "slug-required" });
+        return;
+      }
+      const page = choro.readPage(repo.id, slug);
+      if (!page) {
+        sendJson(res, 404, { error: "page-not-found", slug });
+        return;
+      }
+      if (page.error) {
+        // 索引还在、盘上没了：409 让面板知道「重跑一次 T0 就能好」，不是 404 那种
+        // 「这条路本来就不存在」。
+        sendJson(res, 409, {
+          error: page.error,
+          slug: page.slug,
+          relPath: page.relPath,
+          hint: "run `dsh-mneme-choro <repo> --apply` to rebuild"
+        });
+        return;
+      }
+      sendJson(res, 200, { page });
+    }
+  });
+
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/choro/search",
+    policy: "open",
+    handler(req, res) {
+      if (!choroGate(req, res)) return;
+      const repo = choroResolveOr4xx(req, res);
+      if (!repo) return;
+      const url = new URL(req.url, "http://localhost");
+      const hits = choro.search(repo.id, url.searchParams.get("q"), {
+        moduleSlug: url.searchParams.get("module"),
+        limit: Number(url.searchParams.get("limit") ?? 20)
+      });
+      sendJson(res, 200, { q: url.searchParams.get("q"), hits });
+    }
+  });
+
   return {
     routes: countRoutes(),
     dispose: () => {

package/src/bootstrap-http.js

@@ -0,0 +1,105 @@
+// 从目录引导（bootstrap）的 HTTP 口径 —— 唯一实现。
+//
+// 为什么要单独一个模块：这张脸原本只有一个入口（Bearer 数据面 src/api-standalone.js
+// 的 POST /bootstrap），#386 第 6 条要给面板补入口，于是就有了第二个。历史教训写在
+// reclaim-http.js 的开头：#410 修好面板侧之后数据面还停在旧形态（#411），整段复制
+// 必然漂移。所以解析、校验、答复形状从第一份就落在这里，两个入口只留路径与鉴权不同。
+//
+// 这里只做协议层的事：解析、校验、把 bootstrapFromDirectory 的结果包成答复。真正的
+// 解析在 src/bootstrap.js——它读目录、抽六类确定性产物，零 LLM。
+//
+// 与 reclaim-http.js 的一处刻意不同：这里**不做 confirm 两步确认**。bootstrap 是
+// 幂等的（吃 saveWithDedupe 的 (type,title,scope) 去重，`_overwrite` 只刷新内容），
+// 重复跑不会翻倍，也不会删任何东西，所以不需要「先看报告再执行」那道门。
+
+/**
+ * 「引导能力没接线」的错误码。两个入口各有一次顺序敏感的显式检查（503 要赢过 400：
+ * 端点整个没接线时报「dir 不合法」是误导），所以这条不能只藏在 bootstrapReply 里；
+ * 但也必须是同一份字符串。
+ */
+export const BOOTSTRAP_UNAVAILABLE = "bootstrap-unavailable";
+
+/**
+ * 记日志这一手，只许经这里。
+ *
+ * 照 `share-http.js` 的同一份理由抄（C5 评审裁定）：warn 裸调时，宿主 logger 自己坏掉就会
+ * 从 catch 块里再抛出去，而两侧 handler 那个外层 try 在 .then 的回调里早已退栈——现场
+ * 就是「一个字节都没回」（#410）。守卫住在层里，两张脸（in-process 与 Bearer 数据面）
+ * 拿到的就是同一个脾气，不必每张脸各记一次。
+ */
+function warnSafely(warn, message) {
+  try {
+    warn?.(message);
+  } catch { /* 记日志是自己的事，坏了的日志不许把已经算好的答复一起带走 */ }
+}
+
+/** 引导失败的 warn 文案。两条路径共用，日志里不会出现两种拼法。 */
+function bootstrapWarnMessage(error) {
+  return `[dsh-mneme] bootstrap failed: ${String(error)}`;
+}
+
+/**
+ * 解析 POST body（已读成文本）的结构。只判 JSON 与顶层形状，dir 在 readBootstrapDir
+ * 里读——两步分开是为了保住「invalid-json → invalid-body → 能力是否接线 → dir」这个
+ * 顺序，这个顺序是既有对外行为。
+ *
+ * 不用 api.js 的 parseBody：它把坏 JSON 吞成 {}，而 invalid-json 与 invalid-body 是
+ * 两个不同的错（前者是调用方发坏了，后者是发成了数组/null）。
+ *
+ * @returns {{ok: true, body: object} | {ok: false, error: string}}
+ */
+export function parseBootstrapJson(text) {
+  let body;
+  try {
+    body = JSON.parse(text || "{}");
+  } catch {
+    return { ok: false, error: "invalid-json" };
+  }
+  if (body === null || typeof body !== "object" || Array.isArray(body)) {
+    return { ok: false, error: "invalid-body" };
+  }
+  return { ok: true, body };
+}
+
+/**
+ * 读 dir 并归一化。
+ *
+ * 只收非空字符串：插件没有「工作区根目录」的概念，绝不猜路径（猜错就会去读一个
+ * 与用户意图无关的目录，然后把里面的东西写进记忆库）。`trim()` 之后再判空，
+ * 但**回传原串**而不是 trim 后的——两端空白在 Windows 路径里不合法，交给 fs 报
+ * dir-not-found 比在这里静默改写更诚实。
+ *
+ * @returns {{ok: true, dir: string} | {ok: false, error: string}}
+ */
+export function readBootstrapDir(body) {
+  if (typeof body.dir !== "string" || !body.dir.trim()) {
+    return { ok: false, error: "missing-dir" };
+  }
+  return { ok: true, dir: body.dir };
+}
+
+/**
+ * 把一次引导请求变成 { status, body }。调用方只管 sendJson，不自己拼答复。
+ *
+ * 报告一律不加包装层（就是 bootstrapFromDirectory 的原样返回）：面板与数据面都直接
+ * 读 created / merged / items 这几格。
+ *
+ * `BootstrapError` 带 `code`（missing-dir / dir-not-found / not-a-directory），它们
+ * 是**调用方的输入问题**，回 400 并把 code 当错误码；其余异常是内部问题，回 500，
+ * 且不能让 warn 把异常本身吞掉。
+ *
+ * @param {{bootstrapper: ((input: {dir: string}) => Promise<object>)|null,
+ *          dir: string, warn?: ((msg: string) => void)|null}} input
+ * @returns {Promise<{status: number, body: object}>}
+ */
+export function bootstrapReply({ bootstrapper, dir, warn = null }) {
+  if (!bootstrapper) return Promise.resolve({ status: 503, body: { error: BOOTSTRAP_UNAVAILABLE } });
+  return Promise.resolve()
+    .then(() => bootstrapper({ dir }))
+    .then((summary) => ({ status: 200, body: summary }))
+    .catch((error) => {
+      if (error?.code) return { status: 400, body: { error: error.code } };
+      warnSafely(warn, bootstrapWarnMessage(error));
+      return { status: 500, body: { error: "internal" } };
+    });
+}

package/src/bootstrap.js

@@ -177,7 +177,11 @@ async function collectCandidates(root) {
  */
 export async function bootstrapFromDirectory({ service, dir, logger } = {}) {
   if (typeof dir !== "string" || !dir.trim()) throw new BootstrapError("missing-dir");
-  const root = dir.trim();
+  // 只 trim 判空，**不**把 trim 结果当路径（#386 第 6 条评审）：协议层 readBootstrapDir
+  // 刻意回传原串，理由写着「两端空白交给 fs 报 dir-not-found 比静默改写更诚实」；这里
+  // 若再 trim 一次，那个承诺就变成了空话——用户填 " /repo " 会被悄悄换成 "/repo"，
+  // 读的是另一个目录，而他一无所知。路径不合法就让 statSync 去报。
+  const root = dir;
   let st;
   try {
     st = statSync(root);

package/src/choro-command.js

@@ -0,0 +1,104 @@
+// dsh-mneme/src/choro-command.js
+// /choro：仓库地志的只读回执（M3，spec §10）。
+//
+// 与 pipeline-command.js 的区别：那边持有状态（开窗 / 结账），这边**什么都不写**。
+// spec §2 D6 定的是「只手动触发，过期只提示」——重建、富化、切档位全都不在这条
+// 命令里，它只回答三个问题：当前仓库登记过地志吗？基线还一致吗？提纲长什么样？
+import { gitHead } from "./wiki/t0.js";
+import { renderChoroBlock } from "./wiki/inject.js";
+import { STR } from "./lang.js";
+
+export const CHORO_COMMAND = "choro";
+
+/** 短 sha：回执里只用于人眼比对，给全 40 位纯属噪音。 */
+function shortSha(sha) {
+  const text = String(sha ?? "").trim();
+  return text.length > 7 ? text.slice(0, 7) : text;
+}
+
+/** 生成时间只留日期（与注入块同口径：分钟级精度在这块文本里没有信息量）。 */
+function dateOnly(iso) {
+  const m = /^(\d{4}-\d{2}-\d{2})/.exec(String(iso ?? ""));
+  return m ? m[1] : String(iso ?? "");
+}
+
+/**
+ * 过期判定：地志落库时的 git 基线 vs 当前 HEAD。
+ *
+ * **只在这里做**——注入块是每轮都要渲染的热路径，fork 一次 git 在 Windows 上
+ * 几十毫秒起步（P29）。这里是用户主动敲的，付得起一次 rev-parse。
+ * 三种结局分开报：一致 / 不一致 / 读不到 git——不能把「读不到」说成「没过期」。
+ */
+function staleness(repo) {
+  const baseline = String(repo.git_baseline ?? "").trim();
+  const head = gitHead(repo.root_path);
+  if (!head) return { state: "no-git", baseline, head: null };
+  if (baseline && baseline === head) return { state: "fresh", baseline, head };
+  return { state: "stale", baseline, head };
+}
+
+/**
+ * 处理函数。返回 CommandResult 形状 { kind, text }——**只作 UI 回执，不进模型
+ * 上下文**（同 pipeline-command.js 的契约注释）；要模型看提纲，走开局注入那条路。
+ *
+ * @param {object} opts.choro createChoroQueries() 的产物
+ * @param {object} opts.config 合并后的配置
+ * @param {() => string} [opts.language]
+ */
+export function createChoroHandler({ choro, config, language = () => "zh" } = {}) {
+  return (invocation) => {
+    const lang = language() === "en" ? "en" : "zh";
+    const S = STR.choroCommandUsage[lang];
+    try {
+      // 闸只认 chorographyEnabled，不认注入档位：resolveInjectTier 在轻量档下也返回
+      // "off"，用它当闸会让 lightMode 的用户敲 /choro 时听到「没开，去设置里打开」
+      // ——而设置里明明是开着的（档位只管注入，不管这条命令能不能看提纲）。
+      if (!config || config.chorographyEnabled !== true) return { kind: "error", text: S.off };
+      const raw = invocation?.agent?.session?.header?.cwd ?? null;
+      const cwd = typeof raw === "string" ? raw.trim() : "";
+      if (!cwd) return { kind: "error", text: S.noCwd };
+      const repo = choro ? choro.repoByCwd(cwd) : null;
+      if (!repo) return { kind: "error", text: S.noRepo(cwd) };
+      const outline = choro.outline(repo.id);
+      if (!outline || outline.modules.length === 0) {
+        return { kind: "success", text: S.title(repo.name, 0, dateOnly(repo.updated_at)) + "\n" + S.empty };
+      }
+      const lines = [S.title(repo.name, outline.modules.length, dateOnly(outline.generatedAt))];
+      // 命令里的清单不设 light 的 6 行上限：人主动敲了命令就是要看全表。
+      // 但 full 档的字符上限仍由 renderChoroBlock 自己兜——回执是 UI 里一个文本框，
+      // 贴爆它同样是失败（上限不在这里判，两处各判一次迟早对不上）。
+      const block = renderChoroBlock(outline, "full", lang);
+      if (block) lines.push(block.split("\n").slice(1).join("\n"));
+      // 截断语要说「还剩几个」，不是「总共几个」：总表格行数减去真列出来的行数才是
+      // 读者没看到的量。传总数会让人以为「另有 38 个」而实际只漏了 3 个。
+      const listed = block ? block.split("\n").filter((line) => line.startsWith("- ")).length : 0;
+      const rest = Math.max(0, outline.modules.length - listed);
+      if (rest > 0) lines.push(S.truncated(rest));
+      const head = staleness(repo);
+      if (head.state === "fresh") lines.push(S.fresh(shortSha(head.head)));
+      else if (head.state === "stale") lines.push(S.stale(shortSha(head.baseline), shortSha(head.head)));
+      else lines.push(S.noGit);
+      lines.push(S.hint);
+      return { kind: "success", text: lines.filter(Boolean).join("\n") };
+    } catch (error) {
+      // 回执层永不抛进宿主（同 pipeline-command.js）：把原因写进文本就够了。
+      return { kind: "error", text: String(error?.message ?? error) };
+    }
+  };
+}
+
+/**
+ * 注册。返回 disposer 或 null（宿主没有命令注册表时静默返回 null，不抛）。
+ * 形状与 registerMoRunCommand 一致——两条内置命令只有「做什么」不同。
+ */
+export function registerChoroCommand({ ctx, choro, config, enabled, language = () => "zh" }) {
+  if (enabled !== true) return null;
+  if (typeof ctx?.commands?.register !== "function") return null;
+  const lang = language() === "en" ? "en" : "zh";
+  return ctx.commands.register({
+    name: CHORO_COMMAND,
+    description: STR.choroCommandDescription[lang],
+    input: { hint: STR.choroCommandInputHint[lang] },
+    handler: createChoroHandler({ choro, config, language })
+  });
+}