@modusensus/dsh-mneme 0.11.0 → 0.13.0

package/src/user-settings.js

@@ -1,5 +1,5 @@
 // dsh-mneme/src/user-settings.js
-// 「用户设置」注入块（人格 / 画像 / 规则）的唯一渲染处。
+// 「用户设置」注入块（人格 / 画像 / 自动画像事实 / 规则）的唯一渲染处。
 //
 // 为什么要单独成模块：面板「Agent 眼中的画像」那张卡原本自己在前端拼了一份 profile +
 // rules 的列表，注释写着「注入生效文本」——但它没有表头、没有「- 用户画像：」前缀，
@@ -7,10 +7,18 @@
 // 「看着像」。现在注入器与预览路由调同一个函数，前端只显示后端给的文本。
 //
 // 顺序是设计口径（人格设计稿⑥）：特化指令（人格）先出，画像与规则后出、后写覆盖占
-// 上风，rules 恒最硬。改这个顺序等于改提示词权重，别顺手调。
+// 上风，rules 恒最硬。改这个顺序等于改提示词权重，别顺手调。自动画像事实（2026-11-06，
+// src/profile-facts.js）插在画像之后、规则之前——它是「画像的 agent 侧补充」，与
+// 手填画像物理分离（模型对 user_settings.profile 永远只有读权）。
 
 import { STR, langOf } from "./lang.js";
 
+// 事实段的注入预算（本块此前无任何截断机制——它是「身份文本」，从不轮换）。
+// 不设上限的话，一次失控的维护轮能把每帧 systemPrompt 撑爆；行数与总字符双帽，
+// 截断不静默（尾注如实说还剩几条，与 #164① 同一纪律）。
+const PROFILE_FACTS_MAX_LINES = 40;
+const PROFILE_FACTS_MAX_CHARS = 1200;
+
 /**
  * 提示词变量转义：宿主模板插值对 `{{`/`}}` 会按变量名解析并在缺失时抛错，整轮崩掉。
  * 所以把 2 个以上连续花括号逐字符插 `\`，让任何 `{{`/`}}` 子串都不残留；转换幂等，
@@ -28,6 +36,14 @@ export function escapePromptVars(config, text) {
  * 按会话身份取人格卡。返回 `{ card, source }`，`source` 是给面板解释「用的哪张卡」的
  * 读数，不参与判定。
  *
+ * 寻址维度（#606 起两维，子 agent 继承再加一维共三维）：`sessionId`（绑会话卡，
+ * 最具体）优先于 `parentSessionId`（子 agent 继承父会话卡），最后是 `agentId`（按预设建卡）。
+ * 理由是具体性——会话比预设更具体，而 DS Bot 这类宿主里 `agentPreset` 恒为
+ * `"standard"`（`ds-bot/src/host/roster.js:72-80` 强制写入，实测 50 个会话里 43 个是
+ * 它），若让 byAgent 优先，则谁给 `standard` 建一张卡就会盖掉所有按会话建的卡。
+ * 父会话卡排在 byAgent 之前：子 agent 自己没卡时，它属于哪段对话比它属于哪个预设
+ * 更能说明「该用谁的人格」。
+ *
  * `strict`（config.personaStrictAddressing，默认关）决定「有身份、没这张身份的卡」
  * 与「这张卡被显式关掉」这两种情况：
  * - 关（现状）：落 default 卡。default 于是变成「所有没建卡的 agent 都能拿到它」，
@@ -35,44 +51,180 @@ export function escapePromptVars(config, text) {
  * - 开：不注入人格（`source: "none"`）。default 退回它的本意：只兜「这一帧解析不到
  *   身份」的会话（无名会话本来就是 default 卡的受众）。
  * 默认关是有意的：这是一次口径变更，不能让老用户的注入文本在升级后静默变化。
+ *
+ * 严格模式有一格例外（#587）：两维**都没建过卡**时仍回落 default。两种处境必须
+ * 分开——「建了卡、只是没这一张的卡」是真该按 none 处理（否则关掉一张卡等于没关），
+ * 而「一张卡都没建」时 default 是用户手里唯一的一张卡，按 none 处理等于把它永久
+ * 废掉，且面板不报错。判据看两维合起来的键数（#606 起）：只建了 bySession 卡时，
+ * 一个按 byAgent 寻址的会话同样不该被 default 兜底——用户已经做过分区了。
  */
-export function resolvePersonaCard(settings, agentId, { strict = false } = {}) {
+export function resolvePersonaCard(
+  settings,
+  agentId,
+  { strict = false, sessionId = null, parentSessionId = null } = {}
+) {
   const store = settings.getPersona();
   const id = typeof agentId === "string" && agentId.trim() ? agentId.trim() : "";
+  const sid = typeof sessionId === "string" && sessionId.trim() ? sessionId.trim() : "";
+  const pid =
+    typeof parentSessionId === "string" && parentSessionId.trim() ? parentSessionId.trim() : "";
+  // 第一维：绑会话卡（最具体）
+  const sessionCard = sid ? store.bySession?.[sid] : null;
+  if (sessionCard && sessionCard.enabled === true) return { card: sessionCard, source: "bySession" };
+  // 第二维（子 agent 继承）：自己没卡就取父会话的卡。
+  // 为什么必须有这一维：子 agent 是新会话，用户不可能给每个派生会话都建一张卡；而
+  // strict 一旦生效，「有身份、没这张身份的卡」= 不注入人格，子 agent 会从「自称父
+  // 会话的人格」变成「不知道自己是谁」——比串味更糟。继承父会话卡才是用户能预期的
+  // 语义：同一个 agent 派生出去的手脚，仍是同一个 agent。
+  // 注意与 `src/session-gate.js` 的口径区别：那里**刻意不**用 parentSession 判「是不是
+  // 子代理」（宿主 fork 出来的主会话同样带 parentSession，用它判会把主会话误关）。
+  // 这里要问的不是「你是不是子代理」而是「你自己有没有卡」，所以 fork 出的分支继承
+  // 父卡也是正确的（它就是同一段对话的副本）。父 id 与自身 id 相同（脏数据）时跳过，
+  // 免得一次寻址查两遍同一个键。
+  const parentCard = pid && pid !== sid ? store.bySession?.[pid] : null;
+  if (parentCard && parentCard.enabled === true) return { card: parentCard, source: "parentSession" };
+  // 第三维：按预设/身份建的卡
   const card = id ? store.byAgent[id] : null;
   if (card && card.enabled === true) return { card, source: "byAgent" };
-  if (id && strict) return { card: {}, source: "none" };
+  // 严格模式只在「确实建过卡」时才拒绝兜底：两维都空时兜底是唯一的出路。
+  const anyCard = Object.keys(store.byAgent ?? {}).length > 0 || Object.keys(store.bySession ?? {}).length > 0;
+  // 身份判定要把父会话 id 算进来：子 agent 只有父会话 id、没有自己的卡时，也是
+  // 「确实有身份」，不许被 default 兜底。
+  if ((id || sid || pid) && strict && anyCard) return { card: {}, source: "none" };
   return { card: store.default, source: "default" };
 }
 
 /**
- * 渲染整块「用户设置」。`agentId` 是会话身份（解析不到传 null → 走 default 兜底）。
- * 返回 `{ text, source, agent, configGate }`：`text` 为最终注入文本（全空时 ""），
- * `configGate` 是 personaEnabled 的现值——面板要靠它解释「卡开着为什么没生效」。
+ * 按会话身份取自动事实卡（resolvePersonaCard 的镜像，形状不同：facts 没有
+ * enabled 位，「卡存在」就是非空数组）。strict 语义与人格一致：有身份但没这张
+ * 身份的卡时不落 default——两个 bot 对用户的认知不互串是 store 层分区（输入行）
+ * 与本层寻址（输出注入）共同守住的边界。与人格同一条例外（#587）：`byAgent` 整体
+ * 为空时仍落 default，「一张都没建」不等于「这一张没建」。
+ */
+export function resolveFactsCard(factsStore, agentId, { strict = false } = {}) {
+  const id = typeof agentId === "string" && agentId.trim() ? agentId.trim() : "";
+  const byAgent = factsStore?.byAgent ?? {};
+  const card = id ? (byAgent[id] ?? null) : null;
+  if (card && card.length) return { facts: card, source: "byAgent" };
+  if (id && strict && Object.keys(byAgent).length > 0) return { facts: [], source: "none" };
+  return { facts: factsStore?.default ?? [], source: "default" };
+}
+
+/**
+ * 渲染整块「用户设置」。`agentId` 是会话身份（解析不到传 null → 走 default 兜底），
+ * `sessionId` 是绑会话卡的键（#606；解析不到传 null）。
+ * `factsProvider` 是 profile-facts 域的读口（返回 `{ default: [...], byAgent: {...} }`），
+ * 可选；**开关与 provider 双闸**——profileFactsEnabled 关着时连 provider 都不调，
+ * 「关」必须是零读数而不是「读了不渲染」。返回 `{ text, source, agent, session, configGate }`：
+ * `text` 为最终注入文本（全空时 ""），`configGate` 是 personaEnabled 的现值——面板
+ * 要靠它解释「卡开着为什么没生效」。
  */
-export function renderUserSettingsBlock({ settings, config, agentId = null }) {
+export function renderUserSettingsBlock({
+  settings,
+  config,
+  agentId = null,
+  sessionId = null,
+  parentSessionId = null,
+  factsProvider = null
+}) {
   const language = langOf(config);
   const profile = settings.getProfile().trim();
   const rules = settings.getRules();
   const enabled = config?.personaEnabled === true;
+  const strict = config?.personaStrictAddressing === true;
   const resolved = enabled
-    ? resolvePersonaCard(settings, agentId, { strict: config?.personaStrictAddressing === true })
+    ? resolvePersonaCard(settings, agentId, { strict, sessionId, parentSessionId })
     : { card: {}, source: "default" };
   const persona = resolved.card;
-  const personaLines = persona?.enabled === true
-    ? [
-        ...(typeof persona.name === "string" && persona.name.trim() ? [STR.personaNameLine[language](persona.name.trim())] : []),
-        ...(typeof persona.personality === "string" && persona.personality.trim() ? [STR.personaPersonalityLine[language](persona.personality.trim())] : []),
-        ...(typeof persona.replyStyle === "string" && persona.replyStyle.trim() ? [STR.personaReplyStyleLine[language](persona.replyStyle.trim())] : [])
-      ]
-    : [];
+  // 段（#600）：每一行都带上它的 kind 与写回所需的定位信息，供面板按段读、按段改。
+  // 段文本是**未转义**的原样行；整串 `text` 仍走原来的「先 join 再统一转义」，
+  // 所以注入字节不变（转义只动连续花括号，换行不参与，逐段转义与整串转义等价）。
+  //
+  // `text` 是**带模板前缀的整行**（如 `- 用户画像：xxx`），不能拿去当新值回写，
+  // 否则每写一次叠一层前缀。可回写的段另带 `value`＝原始值（无前缀、未转义）；
+  // 没有原始值的段（表头、事实表头、截断尾注）不带 `value` 键。
+  const personaLines = [];
+  if (persona?.enabled === true) {
+    if (typeof persona.name === "string" && persona.name.trim()) {
+      const value = persona.name.trim();
+      personaLines.push({ kind: "personaName", field: "name", value, text: STR.personaNameLine[language](value) });
+    }
+    if (typeof persona.personality === "string" && persona.personality.trim()) {
+      const value = persona.personality.trim();
+      personaLines.push({ kind: "personaPersonality", field: "personality", value, text: STR.personaPersonalityLine[language](value) });
+    }
+    if (typeof persona.replyStyle === "string" && persona.replyStyle.trim()) {
+      const value = persona.replyStyle.trim();
+      personaLines.push({ kind: "personaReplyStyle", field: "replyStyle", value, text: STR.personaReplyStyleLine[language](value) });
+    }
+    // scenario / mesExample（#606）：只有设置了才输出，未设置时本块逐字节不变。
+    if (typeof persona.scenario === "string" && persona.scenario.trim()) {
+      const value = persona.scenario.trim();
+      personaLines.push({ kind: "personaScenario", field: "scenario", value, text: STR.personaScenarioLine[language](value) });
+    }
+    if (typeof persona.mesExample === "string" && persona.mesExample.trim()) {
+      const value = persona.mesExample.trim();
+      personaLines.push({ kind: "personaMesExample", field: "mesExample", value, text: STR.personaMesExampleLine[language](value) });
+    }
+  }
+  // 事实段：开关关 / 无 provider / 该卡没事实三种情况都不渲染，注入文本与
+  // 未启用事实时逐字节一致（老用户零变化）。
+  const factsResolved = config?.profileFactsEnabled === true && typeof factsProvider === "function"
+    ? resolveFactsCard(factsProvider(), agentId, { strict })
+    : { facts: [], source: "none" };
+  const factLines = [];
+  if (factsResolved.facts.length) {
+    let chars = 0;
+    let shown = 0;
+    for (const fact of factsResolved.facts) {
+      const value = String(fact);
+      const line = STR.profileFactLine[language](value);
+      if (shown >= PROFILE_FACTS_MAX_LINES || chars + line.length > PROFILE_FACTS_MAX_CHARS) break;
+      factLines.push({ kind: "fact", index: shown, value, text: line });
+      chars += line.length;
+      shown += 1;
+    }
+    const remaining = factsResolved.facts.length - shown;
+    if (remaining > 0) factLines.push({ kind: "factsTruncated", remaining, text: STR.profileFactsTruncated[language](remaining) });
+    if (factLines.length) {
+      // 表头的 n 是**总条数**（含没注入的），与「另有 N 条未注入」互补，别改成 shown。
+      factLines.unshift({
+        kind: "factsHeader",
+        shown,
+        total: factsResolved.facts.length,
+        text: STR.profileFactsHeader[language](factsResolved.facts.length)
+      });
+    }
+  }
   const id = typeof agentId === "string" && agentId.trim() ? agentId.trim() : null;
-  if (!profile && !rules.length && !personaLines.length) {
-    return { text: "", source: resolved.source, agent: id, configGate: enabled };
+  const sid = typeof sessionId === "string" && sessionId.trim() ? sessionId.trim() : null;
+  const pid =
+    typeof parentSessionId === "string" && parentSessionId.trim() ? parentSessionId.trim() : null;
+  if (!profile && !rules.length && !personaLines.length && !factLines.length) {
+    // `parent` 是读数（面板要能说清「这张卡是从父会话继承来的」），不参与判定。
+    return {
+      text: "",
+      segments: [],
+      source: resolved.source,
+      agent: id,
+      session: sid,
+      parent: pid,
+      configGate: enabled
+    };
   }
-  const lines = [STR.userSettingsHeader[language]];
-  lines.push(...personaLines);
-  if (profile) lines.push(STR.profileLine[language](profile));
-  for (const rule of rules) lines.push(STR.ruleLine[language](rule));
-  return { text: escapePromptVars(config, lines.join("\n")), source: resolved.source, agent: id, configGate: enabled };
+  const segments = [{ kind: "header", text: STR.userSettingsHeader[language] }];
+  segments.push(...personaLines);
+  if (profile) segments.push({ kind: "profile", value: profile, text: STR.profileLine[language](profile) });
+  segments.push(...factLines);
+  for (const rule of rules) segments.push({ kind: "rule", value: rule, text: STR.ruleLine[language](rule) });
+  const lines = segments.map((s) => s.text);
+  return {
+    text: escapePromptVars(config, lines.join("\n")),
+    segments,
+    source: resolved.source,
+    agent: id,
+    session: sid,
+    parent: pid,
+    configGate: enabled
+  };
 }

package/src/vector-index.js

@@ -65,35 +65,105 @@ export function createVectorIndex({ store, logger }) {
       return store.searchVector(queryVector, { limit, threshold });
     },
 
-    /** Re-embed every row missing an embedding. Returns indexed count. */
+    /**
+     * Re-embed every row whose vector is missing OR came from another model.
+     *
+     * Returns { indexed, failed, skipped, remaining, error? } — three distinct
+     * outcomes instead of one `skipped` bucket that meant "failed", "threw" and
+     * "did not fit in the limit" all at once. #604.
+     */
     async rebuildIndex(embedder, { limit = 1000 } = {}) {
       // The loop needs a single-text embedder. Native embedSingle is preferred;
       // embed-only OpenAI-compatible clients (issue #10) are accepted too via
       // their `embed` single-text interface, so /vector-reindex no longer
       // silently returns 0 for them. An embedder exposing neither is ignored.
+      // #604: prefer the detailed entry point when the embedder has one. The
+      // legacy OpenAI-compatible client drops the failure reason on its normal
+      // path (embedText returns only the vector), so a provider outage and an
+      // unembeddable row both surfaced here as a bare null. The reason is what
+      // tells them apart, and the operator needs it to know whether pressing
+      // the button again is worth anything.
       let embedOne = null;
+      let embedOneDetailed = null;
+      if (embedder && typeof embedder.embedSingleDetailed === "function") {
+        embedOneDetailed = (text) => embedder.embedSingleDetailed(text);
+      }
       if (embedder && typeof embedder.embedSingle === "function") {
         embedOne = (text) => embedder.embedSingle(text);
       } else if (embedder && typeof embedder.embed === "function") {
         embedOne = (text) => Promise.resolve(embedder.embed(text));
       }
-      if (!embedOne) return { indexed: 0, skipped: 0 };
-      const rows = store.needsEmbedding(limit);
+      if (!embedOne && !embedOneDetailed) {
+        return { indexed: 0, failed: 0, skipped: 0, remaining: 0, error: "no-embedder" };
+      }
+      const model = embedder?.modelHash ?? null;
+      // #604: this used to call needsEmbedding(), which only matches empty
+      // vectors. After a model switch every row already has a vector — from the
+      // previous model — so "reindex" selected nothing, embedded nothing, and
+      // reported {indexed: 0, skipped: 0} as if the index were already current.
+      // The boot sweep has always used the model-aware selector; using the same
+      // one here is what makes the button mean what it says.
+      const rows = model && typeof store.needsEmbeddingFor === "function"
+        ? store.needsEmbeddingFor(model, limit)
+        : store.needsEmbedding(limit);
       let indexed = 0;
+      let failed = 0;
+      const failureReasons = {};
+      const noteFailure = (reason) => {
+        failureReasons[reason] = (failureReasons[reason] ?? 0) + 1;
+      };
       for (const row of rows) {
         try {
           const text = [row.title, row.content].filter(Boolean).join("\n");
-          const vector = await embedOne(text);
+          let vector;
+          if (embedOneDetailed) {
+            const detailed = await embedOneDetailed(text);
+            vector = detailed ? detailed.vector : null;
+            if (!vector && detailed?.reason) noteFailure(`error:${detailed.reason}`);
+          } else {
+            vector = await embedOne(text);
+          }
           if (vector && vector.length) {
-            store.setEmbedding(row.id, vector);
+            // #604: the model fingerprint was omitted here, so every rebuilt
+            // row kept embedding_model NULL. needsEmbeddingFor() then treated
+            // it as stale forever: the boot sweep re-embedded it on each start,
+            // the panel counted it as unsearchable, and pressing reindex again
+            // found nothing (the vector was no longer empty). Passing the
+            // fingerprint closes the loop between the write and the selector.
+            store.setEmbedding(row.id, vector, model ?? undefined);
             indexed++;
+          } else {
+            failed++;
+            // A detailed adapter already recorded why; the plain path has no
+            // reason to record, so name the only thing it can mean.
+            if (!embedOneDetailed) noteFailure("empty-vector");
+            logger?.warn?.(`[dsh-mneme] rebuild produced no vector for ${row.id}`);
           }
         } catch (error) {
+          failed++;
+          noteFailure(`error:${String(error)}`);
           logger?.warn?.(`[dsh-mneme] rebuild embed failed for ${row.id}: ${String(error)}`);
         }
       }
       if (indexed > 0 && embedder.modelHash) this.markModel(embedder.modelHash, embedder.dimension);
-      return { indexed, skipped: rows.length - indexed };
+      // remaining = still selected by the same predicate after this run. Rows
+      // that failed stay in it (they were never written), which is exactly the
+      // number the caller needs to decide whether to run again.
+      const remaining = typeof store.countNeedsEmbeddingFor === "function"
+        ? store.countNeedsEmbeddingFor(model)
+        : null;
+      // `skipped` is 0 by definition here, not as a placeholder: every row the
+      // selector returned is attempted in the loop above, so nothing is left
+      // untouched. Rows that produced no vector are `failed`. The remaining
+      // bucket is the selector's own count, which is why a row can be both
+      // failed and remaining — it was tried and it is still stale.
+      //
+      // `failureReasons` mirrors the boot sweep's bucket names so the two paths
+      // read the same: `empty-vector` means this row will never embed, while an
+      // `error:` bucket means the provider or the store failed and the same
+      // press may well succeed next time. A run that only ever reports
+      // empty-vector is not a retry candidate.
+      return { indexed, failed, skipped: 0, remaining, failureReasons };
     },
 
     /** Index stats for the Web panel / debugging. */

package/src/wiki/cli-hint.js

@@ -0,0 +1,90 @@
+// dsh-mneme/src/wiki/cli-hint.js
+// issue #607：面板空态让用户「在仓库目录里跑 `dsh-mneme-choro <仓库路径> --apply`」，
+// 但插件是装在 profile 依赖里的，npm 只为**全局**安装把 shim 放进 PATH。profile 的
+// shim 落在 `<profile>/node_modules/.bin`，那里不在 PATH 上 —— 用户照着抄必然
+// command not found。issue 作者实测后的原话是「完全就是 AI 自己编的」。
+//
+// 所以提示里的命令必须**能直接粘贴就跑**：给绝对路径的入口，而不是一个只对全局
+// 安装成立的光名字。入口从插件自身位置推导（不信 PATH、不信 cwd）。
+//
+// 做法是逐级向上找「同时存在 bin/dsh-mneme-choro.mjs 与 package.json」的目录，
+// 而不是固定 dirname 几次：本仓库的 src 与 lib 是同一层，但 wiki/ 是第二层，
+// bin/ 里的脚本又在第一层 —— 写死层数的推导只要有一处调用方挪个位置就悄悄算错，
+// 而算错的表现正是「又给出一条跑不起来的命令」，与这条 issue 的病因同源。
+//
+// 这条对 hoisted 与 pnpm isolated 两种 linker 都成立：后者的真实路径在
+// `.pnpm/<pkg>/node_modules/@modusensus/dsh-mneme/`，包根照样是它的父目录。
+//
+// 刻意**只给 `node <entry>` 这一种形态**：`.bin` 的 shim 在 hoisted 布局下位于
+// 包根的 `../../../node_modules/.bin`，isolated 布局下却在 profile 根 —— 猜错就是
+// 再给一条跑不起来的命令。宁可只给一条一定对的，也不并列两条一条错的。
+//
+// 找不到入口就返回 null（源码树被裁剪、或调用方在包外），调用方退回通用说法，
+// 不硬编一个假路径。
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const ENTRY_BASENAME = "dsh-mneme-choro.mjs";
+// 从 `src/wiki/` 到包根是 2 层，从 `bin/` 是 1 层；留到 6 层是为了 pnpm 的
+// `.pnpm/<pkg>/node_modules/@modusensus/<name>/` 这种深路径，同时不至于一路走到盘符。
+const MAX_LEVELS = 6;
+
+/**
+ * choro CLI 入口的绝对路径；找不到（源码树被裁剪、调用方在包外）返回 null。
+ *
+ * @param {string} fromModuleUrl - 调用方自己的 `import.meta.url`。
+ * @returns {string|null}
+ */
+export function choroCliEntry(fromModuleUrl) {
+  let dir;
+  try {
+    dir = dirname(fileURLToPath(fromModuleUrl));
+  } catch {
+    return null;
+  }
+  for (let level = 0; level <= MAX_LEVELS; level += 1) {
+    const entry = join(dir, "bin", ENTRY_BASENAME);
+    // 两个条件都要：只有 bin/ 没有 package.json 的目录可能是别人的同名 bin；
+    // 只有 package.json 没有 bin/ 的是源码树被裁剪（`files` 少了 bin）。
+    if (existsSync(entry) && existsSync(join(dir, "package.json"))) return entry;
+    const up = dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return null;
+}
+
+/**
+ * 给一句可直接粘贴的命令。只负责引号与形态，仓库路径由调用方给（面板给
+ * `<仓库路径>` 占位符，工具报错给 `<repo>`）。
+ *
+ * 引号按平台分：Windows 的 cmd / PowerShell 用双引号；POSIX 用单引号并把内嵌
+ * 单引号转成 `'\''` —— 安装路径里带空格是常态（`C:\Program Files\`），不带引号的
+ * 示例等于又给人一条跑不起来的命令。
+ *
+ * @param {string|null} entry - `choroCliEntry()` 的产物。
+ * @param {string} repoPlaceholder - 仓库路径占位符的展示形态。
+ * @param {string} [platform] - 覆盖 `process.platform`（测试用）。
+ * @returns {string|null}
+ */
+export function choroCliCommand(entry, repoPlaceholder, platform = process.platform) {
+  if (!entry) return null;
+  const quoted = platform === "win32"
+    ? `"${entry}"`
+    : `'${entry.replace(/'/g, "'\\''")}'`;
+  return `node ${quoted} ${repoPlaceholder} --apply`;
+}
+
+/**
+ * 一站式的便捷口：从调用方的 `import.meta.url` 直接拿到命令串。
+ * 找不到入口返回 null，调用方据此选通用说法。
+ *
+ * @param {string} fromModuleUrl
+ * @param {string} repoPlaceholder
+ * @param {string} [platform]
+ * @returns {string|null}
+ */
+export function choroCliCommandFrom(fromModuleUrl, repoPlaceholder, platform = process.platform) {
+  return choroCliCommand(choroCliEntry(fromModuleUrl), repoPlaceholder, platform);
+}