@xia-sc/dsh-cc-studio 0.9.0 → 0.10.0

package/lib/index.js

@@ -9,6 +9,11 @@ import { fileURLToPath } from "node:url";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { inflateSync as zlibInflateSync } from "node:zlib";
+// 卡组层（0.10.0）：卡组作用域组装 / 世界书分段统计 / 条目体检的**唯一实现**，与预设半共用同一个文件。
+// 以前这些逻辑两半各抄一份、靠测试逐字比对维持同步 —— 「改了四个、漏了第五个」就是这么来的。
+import { REL_TYPES, REL_TYPE_LABELS, REL_BEGIN, REL_END,
+  estimateTokens, contentKeyOf, scanSharedEntries,
+  assembleScope, groupMetrics, runGroupChecks } from "./group-layer.js";
 
 const name = "dsh-cc-studio";
 // dsh >= 0.1.5-rc.1: this package owns its HTTP route outright.
@@ -397,10 +402,7 @@ function isCcPreset(ctx, sessionId){
 // 渲染：关系只活在插件侧，要让分享出去的卡自包含，就把它渲染进 description 的固定标记区
 // （<!-- cc-relations:begin … --> … <!-- cc-relations:end -->）—— 那是**显式动作**，永不自动同步。
 // ——————————————————————————————————————————————————————————————
-const REL_TYPES = ["family","romance","mentor","friend","colleague","rival","enemy","debt","superior","other"];
-const REL_TYPE_LABELS = { family:"亲属", romance:"恋慕", mentor:"师徒", friend:"挚友", colleague:"同门", rival:"竞争", enemy:"敌对", debt:"恩义", superior:"上下级", other:"其他" };
-const REL_BEGIN = "<!-- cc-relations:begin";
-const REL_END = "<!-- cc-relations:end -->";
+// 关系图谱常量（0.10.0 起由 lib/group-layer.js 提供，两半共用一份）—— 这里不再重复定义。
 
 function groupDirs(){ return dataRoots("cc-groups"); }
 function groupDir(){ return groupDirs()[0]; }
@@ -412,13 +414,8 @@ function groupPath(id){ return join(groupDir(), safeGroupId(id) + ".json"); }
 function newGroupId(){ return Date.now() + "-" + Math.random().toString(36).slice(2, 6); }
 async function ensureGroupDir(){ try{ await mkdir(groupDir(), { recursive: true }); }catch{} }
 
-/** 粗略 token 估算（与 lib/agent.js 同构）：CJK 一字≈1 token，其余 4 字符≈1 token。 */
-function estimateTokensLite(text){
-  const s = String(text || "");
-  let cjk = 0;
-  for(const ch of s){ if(ch.charCodeAt(0) > 0x2E7F) cjk++; }
-  return Math.ceil(cjk + (s.length - cjk) / 4);
-}
+/** 粗略 token 估算：委托 lib/group-layer.js 的 estimateTokens（两半共用一份，不再各写一遍）。 */
+function estimateTokensLite(text){ return estimateTokens(text); }
 function relTypeOf(t){ const s = String(t == null ? "" : t); return REL_TYPES.indexOf(s) >= 0 ? s : "other"; }
 function relLabel(edge){ return (edge && edge.label && String(edge.label).trim()) ? String(edge.label).trim() : (REL_TYPE_LABELS[(edge && edge.type) || "other"] || "其他"); }
 
@@ -621,55 +618,16 @@ function spliceRelations(description, section, meta){
 /**
  * 跨卡体检（纯函数）。members / cards 由调用方给：
  *   members = 组内卡的 id 列表；cards = [{id, name, description, constantTokens, tokenBudget}]
+ *
+ * 0.10.0：实现搬进 lib/group-layer.js 的 `runGroupChecks()`（检查注册表，与预设半共用同一个文件）。
+ * 这里保留旧签名与返回形状（issues[].level/code/message/refs + stats），所以既有调用点与测试都不用改；
+ * 新检查项只往那里的 GROUP_CHECKS 加一项。opts.checks 可只跑指定类别。
  */
-function checkGroup(group, members, cards, sharedEntries){
-  const g = normalizeGroup(group);
-  const issues = [];
-  const add = (level, code, message, refs) => issues.push({ level, code, message, refs: refs || [] });
-  const nodeIds = new Set(g.nodes.map(n => n.id));
-  const byId = new Map((Array.isArray(cards) ? cards : []).map(c => [c.id, c]));
-  const dangling = g.edges.filter(e => !nodeIds.has(e.from) || !nodeIds.has(e.to));
-  if(dangling.length) add("error", "dangling-edge", dangling.length + " 条关系的端点节点已不存在（数据可能被外部改坏）", dangling.map(e => e.id));
-  const orphans = g.nodes.filter(n => n.kind === "card" && n.cardId && !byId.has(n.cardId));
-  if(orphans.length) add("warn", "orphan-node", orphans.length + " 个节点指向的卡已不在库里：" + orphans.map(n => n.name).join("、"), orphans.map(n => n.id));
-  const seen = new Map();
-  g.nodes.forEach(n => [n.name].concat(n.aliases || []).forEach(x => {
-    const k = String(x || "").toLowerCase();
-    if(!k) return;
-    if(!seen.has(k)) seen.set(k, []);
-    if(seen.get(k).indexOf(n.id) < 0) seen.get(k).push(n.id);
-  }));
-  const dup = [...seen.entries()].filter(p => p[1].length > 1);
-  if(dup.length) add("error", "duplicate-name", dup.length + " 组名字/别名落在多个节点上（渲染会指向同一个人）：" + dup.map(p => p[0]).join("、"), []);
-  const unknown = g.edges.filter(e => REL_TYPES.indexOf(e.type) < 0);
-  if(unknown.length) add("warn", "type-unknown", unknown.length + " 条关系用了未知类型", unknown.map(e => e.id));
-  const memberCards = (Array.isArray(members) ? members : []).map(m => byId.get(m)).filter(Boolean);
-  const unrendered = [], stale = [];
-  memberCards.forEach(c => {
-    const desc = String(c.description || "");
-    const i = desc.indexOf(REL_BEGIN), j = desc.indexOf(REL_END);
-    if(i < 0 || j < 0){ unrendered.push(c.id); return; }
-    const m = /cc-relations:begin rev=(\d+)/.exec(desc.slice(i, j));
-    if(!m || Number(m[1]) !== g.rev) stale.push(c.id);
-  });
-  if(unrendered.length) add("warn", "unrendered", unrendered.length + " 张成员卡的 description 里还没有【关系】段（关系目前只存在于图谱里，导出的卡看不到）", unrendered);
-  if(stale.length) add("warn", "stale-render", stale.length + " 张成员卡的【关系】段落后于图谱（标记里的 rev 与当前 rev 不一致），建议重新渲染", stale);
-  // 群聊版的「单次触发」陷阱：每张卡的 constant 每轮都进上下文，卡越多固定开销越大
-  const cardConst = memberCards.reduce((n, c) => n + (Number(c.constantTokens) || 0), 0);
-  // 0.9.0 报告：共享世界书的 constant 条目在群聊里**同样每轮插入**（独立一本、由客户端叠加），
-  // 所以「群聊每轮固定开销」必须是 卡内 + 共享 的合计 —— 只报卡内会低报一半。与工具半同构。
-  const sharedConst = (Array.isArray(sharedEntries) ? sharedEntries : [])
-    .filter(e => e && e.enabled !== false && e.constant)
-    .reduce((n, e) => n + estimateTokensLite(e && e.content), 0);
-  const constTokens = cardConst + sharedConst;
-  const minBudget = memberCards.length ? memberCards.reduce((n, c) => Math.min(n, Number(c.tokenBudget) || 1200), Infinity) : 1200;
-  if((memberCards.length > 1 || sharedConst > 0) && constTokens > minBudget * 0.8){
-    add("warn", "constant-budget", "群聊每轮固定开销偏高：成员卡常驻 " + cardConst
-      + (sharedConst ? " + 共享书常驻 " + sharedConst : "") + " = 合计约 " + constTokens
-      + " token（已达最小预算 " + minBudget + " 的 " + Math.round(constTokens / minBudget * 100) + "%）");
-  }
-  return { issues, stats: { nodes: g.nodes.length, edges: g.edges.length, members: memberCards.length,
-    constantTokens: { card: cardConst, shared: sharedConst, total: constTokens }, minBudget } };
+function checkGroup(group, members, cards, sharedEntries, opts){
+  const o = opts || {};
+  return runGroupChecks({ group: normalizeGroup(group), members: members, cards: cards,
+    sharedEntries: sharedEntries, metrics: o.metrics || null, scope: o.scope || null,
+    opts: { checks: o.checks } });
 }
 
 /** 读分组：主根优先，回退旧根（与角色库同规）。 */
@@ -743,11 +701,65 @@ async function readLibraryRaw(id){
   throw lastErr || new Error("找不到角色卡: " + String(id));
 }
 // ========== PNG / CHARX 共享 ==========
+/** tags 在 V1/ST 那边可能是逗号分隔的字符串；V2/V3 要数组。 */
+function normTags(v){
+  if(Array.isArray(v)) return v.map(function(x){ return String(x); });
+  if(typeof v==="string") return v.split(",").map(function(s){ return s.trim(); }).filter(Boolean);
+  return [];
+}
+/**
+ * V2（乃至 V1）卡 → CCv3 升级（0.9.1 的 B2）。返回 `{card, from}`，`from` 为 null = 本来就是 V3。
+ *
+ * 为什么做：SillyTavern 里**绝大多数存量卡是 V2**（ST 界面新建的就是 V2 形状，ST 只是把 `spec` 改写成
+ * 了 v3 标签），而工坊此前只收 `chara_card_v3` —— 用户把 ST 里那张卡的 PNG/JSON 拖进来，只会得到
+ * 一句「spec 需为 chara_card_v3」。升级规则照 ST 自己的 `readFromV2()`（`characters.js:504-556`）：
+ * 顶层那些 V1 平铺字段并进 `data`（**只在 `data` 里没有该值时**，不覆盖 V2 自己的值），其余不认识
+ * 的字段原样留着。`from` 交给调用方，用来**明确告诉用户「这份是升上来的」**（不静默变换）。
+ */
+function upgradeCardToV3(obj){
+  if(!obj || typeof obj!=="object") throw new Error("卡必须是对象");
+  if(obj.spec==="chara_card_v3" && obj.data && typeof obj.data==="object") return { card: obj, from: null, copied: [] };
+  const out=JSON.parse(JSON.stringify(obj));
+  const copied=[];
+  const hasData=!!(out.data && typeof out.data==="object");
+  if(!hasData){
+    // 纯 V1：整份包成 data
+    const flat={};
+    ["name","description","personality","scenario","first_mes","mes_example"].forEach(function(k){ if(out[k]!==undefined) flat[k]=out[k]; });
+    flat.creator_notes = out.creator_notes!==undefined? out.creator_notes : (out.creatorcomment!==undefined? out.creatorcomment : "");
+    flat.system_prompt="";
+    flat.post_history_instructions="";
+    flat.alternate_greetings=Array.isArray(out.alternate_greetings)? out.alternate_greetings : [];
+    flat.tags=normTags(out.tags);
+    flat.creator=out.creator!==undefined? out.creator : "";
+    flat.character_version=out.character_version!==undefined? out.character_version : "";
+    flat.extensions={};
+    if(out.talkativeness!==undefined) flat.extensions.talkativeness=out.talkativeness;
+    if(out.fav!==undefined) flat.extensions.fav=out.fav===true;
+    out.data=flat;
+  } else {
+    out.data.extensions=(out.data.extensions && typeof out.data.extensions==="object")? out.data.extensions : {};
+    ["name","description","personality","scenario","first_mes","mes_example"].forEach(function(k){
+      if(out.data[k]===undefined && out[k]!==undefined){ out.data[k]=out[k]; copied.push("data."+k); }
+    });
+    if(out.data.tags===undefined && out.tags!==undefined){ out.data.tags=normTags(out.tags); copied.push("data.tags"); }
+    if(out.data.creator_notes===undefined){
+      if(out.creator_notes!==undefined){ out.data.creator_notes=out.creator_notes; copied.push("data.creator_notes"); }
+      else if(out.creatorcomment!==undefined){ out.data.creator_notes=out.creatorcomment; copied.push("data.creator_notes"); }
+    }
+    if(out.talkativeness!==undefined && out.data.extensions.talkativeness===undefined){ out.data.extensions.talkativeness=out.talkativeness; copied.push("data.extensions.talkativeness"); }
+    if(out.fav!==undefined && out.data.extensions.fav===undefined){ out.data.extensions.fav=out.fav===true; copied.push("data.extensions.fav"); }
+  }
+  const from=String(out.spec || (hasData? "chara_card_v2" : "chara_card_v1"));
+  if(typeof out.data.name!=="string" || !out.data.name.trim()) throw new Error("不是可识别的卡片（没有名称，spec="+from+"）");
+  out.spec="chara_card_v3";
+  out.spec_version="3.0";
+  return { card: out, from: from, copied: copied };
+}
 function normalizeDraft(d){
   if(!d || typeof d!=="object") throw new Error("draft 必须是对象");
-  if(!d.spec) throw new Error("缺少 spec");
-  if(d.spec!=="chara_card_v3") throw new Error("spec 需为 chara_card_v3，当前 "+String(d.spec));
-  if(!d.data || typeof d.data!=="object") throw new Error("缺少 data");
+  // V2/V1 一律**升级**而不是拒绝（B2）；本来就是 V3 时 up.card 就是原对象
+  d=upgradeCardToV3(d).card;
   d.spec_version=d.spec_version||"3.0";
   d.data.character_book=d.data.character_book||{name:"",description:"",scan_depth:4,token_budget:1200,recursive_scanning:false,extensions:{},entries:[]};
   if(!Array.isArray(d.data.character_book.entries)) d.data.character_book.entries=[];
@@ -777,8 +789,7 @@ function b64DecodeBytes(b64){ return new Uint8Array(Buffer.from(String(b64),"bas
 function extractCardFromPngBytes(bytes){
   if(bytes.length<8 || bytes[0]!==0x89 || bytes[1]!==0x50) throw new Error("不是合法 PNG（缺少 PNG 签名）");
   let off=8;
-  let found=null;
-  let lastError=null;
+  let v3=null, v2=null, sawCardChunk=false, lastError=null;
   while(off+8 <= bytes.length){
     const len=(bytes[off]<<24)|(bytes[off+1]<<16)|(bytes[off+2]<<8)|bytes[off+3];
     if(len<0 || len> 20*1024*1024) break;
@@ -789,15 +800,19 @@ function extractCardFromPngBytes(bytes){
       try{
         const zero=data.indexOf(0);
         if(zero>=0){
-          const keyword=bytesToStr(data.slice(0,zero));
-          const text=bytesToStr(data.slice(zero+1));
-          const kw=String(keyword).trim().toLowerCase();
+          const kw=String(bytesToStr(data.slice(0,zero))).trim().toLowerCase();
           if(kw==="ccv3" || kw==="ccv3_card" || kw==="chara" || kw==="chara_card_v3"){
-            let jsonStr=text.trim();
+            sawCardChunk=true;
+            let jsonStr=bytesToStr(data.slice(zero+1)).trim();
             try{ const decoded=bytesToStr(b64DecodeBytes(jsonStr)); if(decoded.trim().startsWith("{")) jsonStr=decoded; }catch{}
             const obj=JSON.parse(jsonStr);
-            if(obj && obj.spec){ found=obj; break; }
-            if(obj && obj.data){ found={spec:"chara_card_v3",spec_version:"3.0",data:obj}; break; }
+            const cand=(obj && obj.spec)? obj : ((obj && obj.data)? {spec:"chara_card_v3",spec_version:"3.0",data:obj} : null);
+            // 判据用**载荷里的 spec**，不用块名：规范允许 `chara` 块里放回填用的 V2 对象，但现实里
+            // 也有工具把 V3 卡塞进 `chara`（我们自己历史上就写过 `chara_card_v3` 这个块名）。
+            if(cand && cand.data){
+              if(String(cand.spec)==="chara_card_v3"){ if(!v3) v3=cand; if(v3) break; }
+              else if(!v2) v2=cand;
+            }
           }
         }
       }catch(e){ lastError=e; }
@@ -807,33 +822,103 @@ function extractCardFromPngBytes(bytes){
     if(type==="IEND") break;
     off+=12+len;
   }
-  if(!found) throw new Error(lastError? String(lastError.message):"PNG 未找到 ccv3/chara 块（tEXt ccv3），请确认是否为 CCv3 PNG");
-  if(found.data) return found;
+  // 两个块都在时**必须**取 ccv3 —— 规范原文：「if the application detects both `chara` and `ccv3` chunk,
+  // the application *SHOULD* use the `ccv3` chunk」。SillyTavern 自己导出的 PNG 就是 chara 在前、ccv3 在后，
+  // 旧实现「取第一个命中的块」于是读到 V2 那份，再把 spec=chara_card_v2 的卡交给 normalizeDraft 直接报错。
+  if(v3) return v3;
+  // 只有 V2 块（ST 里那张卡的 `chara` 块、或只写过 chara 的老工具）：照样交出去，
+  // 由 normalizeDraft → upgradeCardToV3 升级成 CCv3（B2：升级而不是拒绝）。
+  if(v2) return v2;
+  if(!sawCardChunk) throw new Error(lastError? String(lastError.message):"PNG 未找到 ccv3/chara 块（tEXt ccv3），请确认是否为 CCv3 PNG");
   throw new Error("PNG 内卡格式错误");
 }
-function buildTEXtChunk(cardJson){
+// ========== SillyTavern / V2 兼容层（0.9.1）==========
+// 原则：**底层永远是纯 CCv3**，兼容层只在「导出的那一份副本」上生成（草稿与库里的卡一个字节都不动）。
+// 两个落点，都是规范允许的位置：
+//   ① PNG 的 `chara` 块 = 诚实的 CharacterCardV2 投影（见 pngCardChunks 注释）；
+//   ② `data.extensions.world` = ST 的「角色↔世界书」绑定（ST 只认这个字符串，`characters.js:391,617`）。
+// 规范明文禁止的是「往 CharacterCard 对象里加应用私有字段」（那张卡顶层加 V1 平铺字段就是这一类），所以
+// 我们**不**学 ST 那么干 —— ST 需要的东西全部落在 `extensions` / `chara` 块 / CHARX 资源里。
+/** V2 的 data 字段集（V3 独有的 nickname / creator_notes_multilingual / source / group_only_greetings /
+ *  assets / creation_date / modification_date 一个都不进 —— 那些字段在 V2 里不存在）。 */
+const V2_DATA_FIELDS=["name","description","personality","scenario","first_mes","mes_example","creator_notes",
+  "system_prompt","post_history_instructions","alternate_greetings","character_book","tags","creator","character_version","extensions"];
+/** 摘掉正文**开头连续**的 `@@` 装饰器行（含其后遗留的空行）—— 规范要求回填 V2 时移除全部装饰器。 */
+function stripDecorators(content){
+  const lines=String(content==null? "" : content).split("\n");
+  let i=0;
+  while(i<lines.length && String(lines[i]).slice(0,2)==="@@") i++;
+  while(i<lines.length && !String(lines[i]).trim()) i++;
+  return lines.slice(i).join("\n");
+}
+/** 整张卡 → CharacterCardV2 对象（PNG 的 `chara` 块用；只做投影，不改调用方传进来的对象）。 */
+function stV2Projection(card){
+  const src=(card && typeof card==="object")? card : {};
+  const d=(src.data && typeof src.data==="object")? src.data : {};
+  const data={};
+  V2_DATA_FIELDS.forEach(function(k){
+    if(d[k]===undefined) return;
+    if(k==="character_book"){
+      const book=JSON.parse(JSON.stringify(d[k]));
+      if(book && Array.isArray(book.entries)) book.entries.forEach(function(e){ if(e && typeof e==="object") e.content=stripDecorators(e.content); });
+      data[k]=book;
+      return;
+    }
+    data[k]=d[k];
+  });
+  return { spec:"chara_card_v2", spec_version:"2.0", data };
+}
+/**
+ * 导出副本上写 ST 的世界书绑定。ST 的绑定就是 `data.extensions.world = <世界书文件名>`；
+ * 我们的共享书导出成 `<书名>.json`，所以这里直接写书名 —— 用户在 ST 里导完那本世界书，
+ * 再导这张卡，绑定就自动接上了（没导书时它只是个悬空字符串，ST 不会报错）。
+ * ⚠️ 只在导出副本上做（同「并入本卡」的家规）：草稿与库里的卡不许被这个 ST 专有字段污染。
+ */
+function withStWorld(card, world){
+  const name=String(world==null? "" : world).trim();
+  if(!name) return card;
+  const out=JSON.parse(JSON.stringify(card));
+  out.data=out.data||{};
+  out.data.extensions=Object.assign({}, out.data.extensions);
+  out.data.extensions.world=name;
+  return out;
+}
+function buildTEXtChunk(cardJson, keyword){
   const jsonStr=JSON.stringify(cardJson);
   const b64=Buffer.from(jsonStr,"utf8").toString("base64");
-  const keyword=strToBytes("ccv3");
+  const kwBytes=strToBytes(keyword||"ccv3");
   const textBytes=strToBytes(b64);
-  const chunkData=concatBytes([keyword, new Uint8Array([0]), textBytes]);
+  const chunkData=concatBytes([kwBytes, new Uint8Array([0]), textBytes]);
   const typeBytes=strToBytes("tEXt");
   const crc=crc32(concatBytes([typeBytes, chunkData]));
   return concatBytes([u32be(chunkData.length), typeBytes, chunkData, u32be(crc)]);
 }
+/**
+ * 一张卡要写进 PNG 的两个 tEXt 块：`chara`（V2 投影，给只认 V2 的读取器回填）+ `ccv3`（纯 CCv3，规范里的 MUST）。
+ *
+ * 规范（SPEC_V3「PNG/APNG」节，0.9.1 实测对齐）：
+ * ① `ccv3` 块 MUST 存在，值是 CharacterCardV3 对象的 utf-8→base64；
+ * ② 应用 MAY 用 `chara` 块回填 V2 对象；两个块都在时读取方 **SHOULD** 用 `ccv3`；
+ * ③ 「On backfilling V2, the application SHOULD remove all decorators」—— 所以投影里要摘掉 `@@` 装饰器行。
+ * SillyTavern 自己也是两个块都写（`src/character-card-parser.js:15-46`），且 `chara` 在前 —— 这里保持同样顺序。
+ * ⚠️ 卡片 JSON 的**顶层**绝不许加 ST 的私有字段（V1 平铺那套）：规范同节写着应用 MUST follow the
+ * specification、私有数据只能放 `extensions` —— 兼容层只活在 `chara` 这一块与 `extensions.world` 里。
+ */
+function pngCardChunks(cardJson){
+  return [buildTEXtChunk(stV2Projection(cardJson), "chara"), buildTEXtChunk(cardJson, "ccv3")];
+}
 function buildPngWithCard(cardJson){
-  const chunk=buildTEXtChunk(cardJson);
   const baseB64="iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+ip1sAAAAASUVORK5CYII=";
   const base=new Uint8Array(Buffer.from(baseB64,"base64"));
   const iendOff=base.length-12;
   const head=base.slice(0,iendOff);
   const tail=base.slice(iendOff);
-  return concatBytes([head, chunk, tail]);
+  return concatBytes([head].concat(pngCardChunks(cardJson), [tail]));
 }
 function embedCardIntoPngBytes(pngBytes, cardJson){
   if(pngBytes.length<8 || pngBytes[0]!==0x89 || pngBytes[1]!==0x50) throw new Error("不是合法 PNG（缺少 PNG 签名）");
   if(pngBytes.length > 15*1024*1024) throw new Error("PNG 过大（>15MB）");
-  const newChunk=buildTEXtChunk(cardJson);
+  const newChunks=pngCardChunks(cardJson);
   let off=8;
   const parts=[pngBytes.slice(0,8)];
   let inserted=false;
@@ -845,7 +930,7 @@ function embedCardIntoPngBytes(pngBytes, cardJson){
     const data=pngBytes.slice(off+8, off+8+len);
     const chunkBytes=pngBytes.slice(off, off+12+len);
     if(type==="IEND"){
-      parts.push(newChunk);
+      newChunks.forEach(function(c){ parts.push(c); });
       parts.push(chunkBytes);
       inserted=true;
       break;
@@ -958,9 +1043,16 @@ function makeLibraryEntryMeta(draft, existingMeta, id){
     updatedAt: now,
   };
 }
-async function listLibraryEntries(){
+/**
+ * 卡库快照（0.10.0）：一次目录遍历 + 一次 parse，把 meta 与 draft **一起**留下。
+ *
+ * 以前 listLibraryEntries() 解析完整份卡 JSON 却只留 meta，于是「组体检」要对每张卡再读一遍盘
+ * （N 张成员卡 = 2N 次读盘），而且拿不到 entries —— 卡组级检查（跨卡触发词冲突、五维漂移）根本做不了。
+ * 现在读一次就够：listLibraryEntries() 只是它的投影，groupScope() 直接吃它。与预设半同构。
+ */
+async function readLibrarySnapshot(){
   await ensureLibDir();
-  const seen = new Map();   // id → meta：先到先得，主根排在前 → 同名卡片主根优先
+  const seen = new Map();   // id → {id, meta, draft, dir}：先到先得，主根排在前 → 同名卡片主根优先
   for(const dir of libDirs()){
     let files=[];
     try{ files = await readdir(dir); }catch{ continue; }
@@ -973,17 +1065,22 @@ async function listLibraryEntries(){
         const obj = JSON.parse(raw);
         if(obj && obj.meta && obj.id){
           // 兼容：meta.id 与文件名 id 一致
-          seen.set(id, obj.meta);
+          seen.set(id, { id:id, meta:obj.meta, draft:obj.draft || null, dir:dir });
         } else if(obj && obj.draft){
           // 旧格式兜底：从 draft 重建 meta
-          seen.set(id, makeLibraryEntryMeta(obj.draft, null, id));
+          seen.set(id, { id:id, meta:makeLibraryEntryMeta(obj.draft, null, id), draft:obj.draft, dir:dir });
         }
       }catch{}
     }
   }
-  const entries = [...seen.values()];
-  entries.sort((a,b)=> (b.updatedAt||0)-(a.updatedAt||0));
-  return entries;
+  const rows = [...seen.values()];
+  rows.sort((a,b)=> ((b.meta.updatedAt||0)-(a.meta.updatedAt||0)));
+  return rows;
+}
+/** 库条目 meta 列表（签名与排序语义未变，现在只是卡库快照的投影）。 */
+async function listLibraryEntries(){
+  const rows = await readLibrarySnapshot();
+  return rows.map(r => r.meta);
 }
 async function saveLibraryEntry(draft, opts){
   const dir = await ensureLibDir();
@@ -1019,6 +1116,47 @@ async function groupMemberIds(groupId){
   const entries = await listLibraryEntries();
   return entries.filter(e => String(e.groupId || "") === gid).map(e => e.id);
 }
+/**
+ * 卡组作用域（0.10.0，与预设半同构）—— 取「哪个组、组里有哪些卡、这个组的书是什么」的**唯一入口**。
+ *
+ * 宿主半的来源卡来自 args.cardId 或草稿 sidecar（sessionId 对应的 origin.json）；纯组装在
+ * lib/group-layer.js（两半共用一份），所以界面看到的组与模型看到的组形状只有一种。
+ * 拿不到来源卡 / 没进组 / 组不存在 / 组还没建书 → 返回 ok:false 的空作用域（调用方无需自己判空）。
+ */
+async function groupScope(input){
+  const opt = input || {};
+  // 已经读过快照就传进来（opt.snapshot）—— 一次调用里只读一遍盘，也让「只读一次」可被测试钉住
+  const snap = opt.snapshot ? opt.snapshot : await readLibrarySnapshot();
+  const byId = new Map(snap.map(x => [String(x.id), x]));
+  let cardId = opt.cardId ? String(opt.cardId) : "";
+  if(!cardId && opt.sessionKey){
+    const origin = readDraftOrigin(String(opt.sessionKey));
+    cardId = (origin && origin.libraryId) ? String(origin.libraryId) : "";
+  }
+  const mine = cardId ? (byId.get(cardId) || null) : null;
+  const explicit = opt.groupId ? safeGroupId(opt.groupId) : "";
+  const groupId = explicit || ((mine && mine.meta.groupId) ? String(mine.meta.groupId) : "");
+  const base = { cardId: cardId, include: opt.include, maxCards: opt.maxCards, missing: (cardId && !mine) ? [cardId] : [] };
+  if(!groupId) return assembleScope(Object.assign({ groupId: "" }, base));
+  // ⚠️ 组文件缺失时**不提前返回**（与预设半同构）：成员与共享书照样读出来，只是 group 为 null / ok:false ——
+  // 「组没了但书还在」的历史数据，界面上仍应看得到那本书。
+  const found = await readGroupRaw(groupId);
+  const cards = snap.filter(x => String(x.meta.groupId || "") === groupId);
+  const bf = await readBookRaw(groupId);
+  const book = bf ? normalizeBook(bf.obj, groupId) : null;
+  return assembleScope(Object.assign({
+    groupId: groupId, group: found ? normalizeGroup(found.obj) : null, cards: cards, book: book,
+    bookRev: book ? bookRevOf(book) : 0,
+  }, base));
+}
+/**
+ * 由卡组作用域算一次分段统计（0.10.0）：体检类检查的数字来源，子类不再各自 for 循环求和。
+ * 与预设半同构（那边是 groupScope + groupMetrics 的组合调用）。
+ */
+function metricsForGroup(scope){
+  return groupMetrics({ cardId: scope && scope.cardId, card: [],
+    members: (scope && scope.members) || [], book: (scope && scope.book) ? scope.book.entries : [] });
+}
 /**
  * 按名字找组（建组/改名时查重）：trim 后精确比对；带 exceptId 时排除自己（给自己改名不算撞车）。
  * 两半同构 —— 界面和模型必须落到同一条规则上，否则会出现「模型建不了同名组、界面却建了两个」。
@@ -1065,22 +1203,23 @@ async function assignCardToGroup(cardId, groupId){
   await patchLibraryMeta(cid, { groupId: gid });
   return { cardId: cid, cardName: mine.name, previousGroupId: (mine.groupId ? String(mine.groupId) : null), groupId: gid, nodeId: node.id, groupRev: g.rev, revived };
 }
-/** 0.8.0：体检 / 渲染需要的卡片摘要（只读；卡不在库里就跳过）。 */
+/** 0.8.0：体检 / 渲染需要的卡片摘要（只读；卡不在库里就跳过）—— 0.10.0 起吃卡库快照，不再逐卡重复读盘。 */
 async function libraryCardsFor(ids){
+  const rows = await readLibrarySnapshot();
+  const byId = new Map(rows.map(r => [String(r.id), r]));
   const out = [];
   for(const id of (Array.isArray(ids) ? ids : [])){
-    try{
-      const obj = JSON.parse((await readLibraryRaw(id)).raw);
-      const d = (obj && obj.draft && obj.draft.data) ? obj.draft.data : {};
-      const entries = Array.isArray(d.character_book && d.character_book.entries) ? d.character_book.entries : [];
-      out.push({
-        id: String(id),
-        name: String(d.name || ""),
-        description: String(d.description || ""),
-        constantTokens: entries.filter(e => e && e.constant).reduce((n, e) => n + estimateTokensLite(e && e.content), 0),
-        tokenBudget: Number(d.character_book && d.character_book.token_budget) || 1200,
-      });
-    }catch{}
+    const row = byId.get(String(id));
+    if(!row) continue;   // 卡不在库里：原实现是 readLibraryRaw 抛错→跳过，语义一致
+    const d = (row.draft && row.draft.data) ? row.draft.data : {};
+    const entries = Array.isArray(d.character_book && d.character_book.entries) ? d.character_book.entries : [];
+    out.push({
+      id: String(id),
+      name: String(d.name || ""),
+      description: String(d.description || ""),
+      constantTokens: entries.filter(e => e && e.constant).reduce((n, e) => n + estimateTokensLite(e && e.content), 0),
+      tokenBudget: Number(d.character_book && d.character_book.token_budget) || 1200,
+    });
   }
   return out;
 }
@@ -1678,15 +1817,18 @@ function apply(ctx, config){
           return ok({ group: saved, applied: applied.applied, rejected: applied.rejected, changed: true });
         }
         case "cc_groupCheck":{
-          const found = await readGroupRaw(args.id);
-          if(!found) return fail("not-found", "分组不存在: " + String(args.id));
-          const g = normalizeGroup(found.obj);
-          const memberIds = await groupMemberIds(g.id);
-          const cards = await libraryCardsFor(memberIds);
+          // 0.10.0：组 / 成员 / 共享书都从卡组作用域取（与预设半同一个入口、同一次读盘）。
+          const scope = await groupScope({ groupId: args.id });
+          if(!scope.ok || !scope.group) return fail("not-found", "分组不存在: " + String(args.id));
+          const g = scope.group;
+          const cards = await libraryCardsFor(scope.memberIds);
           // 0.9.0：把该组的共享世界书也端给体检 —— 它的 constant 条目在群聊里同样每轮插入
-          const bkFound = await readBookRaw(g.id);
-          const sharedEntries = bkFound ? normalizeBook(bkFound.obj, g.id).data.entries.filter(e => e && e.enabled !== false) : [];
-          return ok(Object.assign({ groupId: g.id, rev: g.rev, name: g.name }, checkGroup(g, memberIds, cards, sharedEntries)));
+          // 0.10.0：检查项走卡组层的注册表（structure / relations / budget / lore-quality / cross-card），
+          // 用 args.checks 可只跑指定类别；返回带 byCheck 便于界面分组显示。
+          const res = checkGroup(g, scope.memberIds, cards, scope.book ? scope.book.entries : [],
+            { checks: args.checks, metrics: metricsForGroup(scope), scope: scope });
+          return ok(Object.assign({ groupId: g.id, rev: g.rev, name: g.name,
+            checks: res.ran, byCheck: res.byCheck }, res));
         }
         case "cc_renderRelations":{
           // 渲染进**当前草稿**（与工具半共用同一份草稿文件）；要落库仍需再存一次
@@ -1854,29 +1996,54 @@ function apply(ctx, config){
           const b64 = args.b64;
           if(typeof b64!=="string" || !b64) return fail("invalid-b64","b64 必填");
           if(b64.length > 20*1024*1024) return fail("too-large","PNG 过大（>20MB base64）");
-          let draft;
+          let draft, upgradedFrom = null;
           try{
             const bytes = b64DecodeBytes(b64);
             if(bytes.length > 15*1024*1024) return fail("too-large","PNG 过大（>15MB）");
             draft = extractCardFromPngBytes(bytes);
+            // B2：只有 V2 块时也能进（升级而不是拒绝）—— upgradedFrom 让界面把这件事说出来
+            upgradedFrom = upgradeCardToV3(draft).from;
             draft = normalizeDraft(draft);
           }catch(e){ return fail("parse-failed", String(e.message)); }
           const k = draftKeyFrom(ctx, args);
           setDraftFor(k, draft);
-          return ok({ draft, key:k, draftStatus: draftStatusFor(k, draft) });
+          return ok({ draft, key:k, draftStatus: draftStatusFor(k, draft), upgradedFrom });
+        }
+        case "cc_importFromJson":{
+          // 工坊拖进来的 .json 走这里（0.9.1，B2）：V2/V1 卡**升级**成 CCv3，而不是让界面报「spec 不符」。
+          // 客户端此前自己 parse + 只认 chara_card_v3 —— 于是 ST 里导出的卡一张都进不来。
+          const raw = args.json;
+          let obj = null;
+          try{
+            obj = (raw && typeof raw === "object")? raw : JSON.parse(String(raw==null? "" : raw));
+          }catch(e){ return fail("parse-failed", "不是合法 JSON："+String(e.message)); }
+          // 自家草稿文件 / 导出包是 `{key, updatedAt, rev, draft}`，先脱一层
+          if(obj && typeof obj==="object" && obj.draft && typeof obj.draft==="object" && !obj.data) obj = obj.draft;
+          let draft, upgradedFrom = null;
+          try{
+            upgradedFrom = upgradeCardToV3(obj).from;
+            draft = normalizeDraft(obj);
+          }catch(e){ return fail("invalid-card", String(e.message)); }
+          const k = draftKeyFrom(ctx, args);
+          setDraftFor(k, draft);
+          return ok({ draft, key:k, draftStatus: draftStatusFor(k, draft), upgradedFrom });
         }
         case "cc_exportPng":{
           const k = draftKeyFrom(ctx, args);
           const draft = JSON.parse(JSON.stringify(getDraftFor(k)));
           draft.data.modification_date = nowSec();
+          // ST 兼容层（0.9.1）：① 每个 PNG 都写两个块（ccv3 纯 CCv3 + chara 的 V2 投影，见 pngCardChunks）；
+          // ② stWorld 非空时，只在**导出副本**上写 `data.extensions.world`（ST 的角色↔世界书绑定）。
+          // 返回给客户端的 draft 仍是「草稿本身」（多一个 ST 专有字段都不带），与「并入本卡」同一条家规。
+          const exportCard = withStWorld(draft, args.stWorld);
           try{
             let pngBytes;
             if(args.imageB64 && typeof args.imageB64==="string" && args.imageB64.length>0){
               if(args.imageB64.length > 20*1024*1024) return fail("too-large","底图 PNG 过大（>20MB base64）");
               const baseBytes = b64DecodeBytes(args.imageB64);
-              pngBytes = embedCardIntoPngBytes(baseBytes, draft);
+              pngBytes = embedCardIntoPngBytes(baseBytes, exportCard);
             } else {
-              pngBytes = buildPngWithCard(draft);
+              pngBytes = buildPngWithCard(exportCard);
             }
             return ok({ b64: Buffer.from(pngBytes).toString("base64"), filename: (draft.data.name||"card")+".png", draft });
           }catch(e){ return fail("build-failed", String(e.message)); }
@@ -1885,7 +2052,7 @@ function apply(ctx, config){
           const b64 = args.b64;
           if(typeof b64!=="string" || !b64) return fail("invalid-b64","b64 必填");
           if(b64.length > 30*1024*1024) return fail("too-large","CHARX 过大（>30MB base64）");
-          let draft;
+          let draft, upgradedFrom = null;
           try{
             const bytes = b64DecodeBytes(b64);
             if(bytes.length > 22*1024*1024) return fail("too-large","CHARX 过大（>22MB）");
@@ -1895,20 +2062,21 @@ function apply(ctx, config){
             if(!cardEntry) return fail("parse-failed","CHARX 未找到 card.json");
             const jsonStr = bytesToStr(cardEntry.data);
             const obj = JSON.parse(jsonStr);
-            draft = obj && obj.spec ? obj : (obj && obj.data ? obj : null);
-            if(!draft) throw new Error("card.json 格式错误");
-            draft = normalizeDraft(draft);
+            upgradedFrom = upgradeCardToV3(obj).from;
+            draft = normalizeDraft(obj);
           }catch(e){ return fail("parse-failed", String(e.message)); }
           const k = draftKeyFrom(ctx, args);
           setDraftFor(k, draft);
-          return ok({ draft, key:k, draftStatus: draftStatusFor(k, draft) });
+          return ok({ draft, key:k, draftStatus: draftStatusFor(k, draft), upgradedFrom });
         }
         case "cc_exportCharx":{
           const k = draftKeyFrom(ctx, args);
           const draft = JSON.parse(JSON.stringify(getDraftFor(k)));
           draft.data.modification_date = nowSec();
+          // ST 兼容层（0.9.1）：只在**导出副本**上写世界书绑定，草稿/库里的卡不动（同「并入本卡」家规）
+          const exportCard = withStWorld(draft, args.stWorld);
           try{
-            const zipBytes = buildZipCharx(draft);
+            const zipBytes = buildZipCharx(exportCard);
             return ok({ b64: Buffer.from(zipBytes).toString("base64"), filename: (draft.data.name||"card")+".charx", draft });
           }catch(e){ return fail("build-failed", String(e.message)); }
         }
@@ -1976,6 +2144,14 @@ function apply(ctx, config){
 // 存储：<主根>/cc-books/<groupId>.json —— **一本书对一个分组**；文件本身就是可直接发布的
 // lorebook_v3 JSON（拷出去别人就能用），插件自己的状态放 `data.extensions.cc`（规范允许）。
 // 条目字段与卡内 `character_book.entries` **完全同构** —— 提升/回填都是零转换搬运。
+//
+// ⚠️ 0.9.1：这个文件是给**认 CCv3 的客户端**的，**SillyTavern 不认** —— ST 服务端
+// `/api/worldinfo/import` 拿到文件第一件事就是 `if (!('entries' in worldContent)) throw`
+// （用户实机：拖 `.lorebook.json` 进去 = `Error importing world info: … Bad Request`；
+// 1.19.0 的客户端 `importWorldInfo()` 也只转 Novel / Agnai / Risu，整份 `world-info.js`
+// 搜不到 `lorebook_v3`）。所以工坊导出页另给一枚「SillyTavern 世界书」：ST 原生形态
+// `{entries:{…}}`，条目字段按 ST 自己的 `convertCharacterBook()` 映射 —— 两枚按钮各有读者，
+// **别把其中一个说成「就是给客户端的通用格式」**（这正是 0.9.0 那轮写错边界的同一个毛病）。
 // ——————————————————————————————————————————————————————————————
 const BOOK_SPEC = "lorebook_v3";
 const BOOK_MAX_ENTRIES = 200;
@@ -2063,30 +2239,24 @@ async function deleteBook(groupId){
   return removed > 0;
 }
 /**
- * 内容签名：折叠空白后取 djb2 哈希 + 长度，用于「同一条设定」的快速比对 —— 只差换行/空格的两条
- * 不该被当成两条（实测里自动条目与手工条目就常差这点空白）。
- * ⚠️ 它只是**索引**：真正搬运/删除前一律再逐字比对内容（哈希碰撞绝不能变成删数据）。
+ * 内容签名：见 lib/group-layer.js 的 `contentKeyOf()`（只用来筛，动手前一律再逐字比对内容 ——
+ * 哈希碰撞绝不能变成删数据）。
  */
-function contentKeyOf(entry){
-  const s = String((entry && entry.content) != null ? entry.content : "").replace(/\s+/g, " ").trim();
-  let h = 5381;
-  for(let i = 0; i < s.length; i++) h = ((h * 33) ^ s.charCodeAt(i)) >>> 0;
-  return "c" + h.toString(36) + "-" + s.length;
-}
-/** 成员卡的**完整**条目（去重要比内容，摘要不够）——与 libraryCardsFor 同源，多带 entries。 */
+/** 成员卡的**完整**条目（去重要比内容，摘要不够）—— 0.10.0 起吃卡库快照，不再逐卡重复读盘。 */
 async function bookCardsFor(ids){
+  const rows = await readLibrarySnapshot();
+  const byId = new Map(rows.map(r => [String(r.id), r]));
   const out = [];
   for(const id of (Array.isArray(ids) ? ids : [])){
-    try{
-      const obj = JSON.parse((await readLibraryRaw(id)).raw);
-      const d = (obj && obj.draft && obj.draft.data) ? obj.draft.data : {};
-      const entries = Array.isArray(d.character_book && d.character_book.entries) ? d.character_book.entries : [];
-      out.push({
-        id: String(id),
-        name: String(d.name || (obj && obj.meta && obj.meta.name) || ""),
-        entries: entries.map(makeBookEntry),
-      });
-    }catch{}
+    const row = byId.get(String(id));
+    if(!row) continue;   // 卡不在库里：原实现是 readLibraryRaw 抛错→跳过，语义一致
+    const d = (row.draft && row.draft.data) ? row.draft.data : {};
+    const entries = Array.isArray(d.character_book && d.character_book.entries) ? d.character_book.entries : [];
+    out.push({
+      id: String(id),
+      name: String(d.name || (row.meta && row.meta.name) || ""),
+      entries: entries.map(makeBookEntry),
+    });
   }
   return out;
 }
@@ -2111,49 +2281,10 @@ async function newBookFor(gid, explicitName){
   try{ const gf = await readGroupRaw(gid); if(gf) gname = normalizeGroup(gf.obj).name; }catch{}
   return normalizeBook({ data: { name: defaultBookName(gname) } }, gid);
 }
-function scanSharedEntries(cards, bookEntries){
-  const list = Array.isArray(cards) ? cards : [];
-  const seen = new Map();
-  list.forEach(c => {
-    (Array.isArray(c.entries) ? c.entries : []).forEach(e => {
-      if(!String((e && e.content) || "").trim()) return;   // 空内容不会进 prompt，不参与
-      const sig = contentKeyOf(e);
-      if(!seen.has(sig)) seen.set(sig, { signature: sig, content: String(e.content), name: String(e.name || ""), keys: (e.keys || []).map(String), constant: e.constant === true, chars: String(e.content).length, cards: [], cardNames: [], nameMismatch: false, keysMismatch: false });
-      const g = seen.get(sig);
-      if(g.cards.indexOf(c.id) < 0){ g.cards.push(c.id); g.cardNames.push(c.name); }
-      if(String(e.name || "") !== g.name) g.nameMismatch = true;
-      if(JSON.stringify((e.keys || []).map(String)) !== JSON.stringify(g.keys)) g.keysMismatch = true;
-    });
-  });
-  const candidates = [...seen.values()].filter(g => g.cards.length >= 2)
-    .sort((a, b) => b.cards.length - a.cards.length || b.chars - a.chars)
-    .map(g => Object.assign({}, g, { preview: g.content.slice(0, 80).replace(/\s+/g, " "), savedChars: g.chars * (g.cards.length - 1) }));
-  // 第二轮报告 P1：还有一类重复是「卡 ↔ 共享书」—— `cc_apply_shared_book` 回填进卡里的副本。
-  // 它和「卡间重复」的**动作不同**：书里已经有了，只需把卡里那份删掉，不必再往书里搬。
-  // 判据同样是**逐字相符**（签名只用来筛候选）；回填过的、手工抄进卡的都算。
-  const bookDupes = [];
-  (Array.isArray(bookEntries) ? bookEntries : []).forEach(be => {
-    const content = String((be && be.content) == null ? "" : be.content);
-    const g = content.trim() ? seen.get(contentKeyOf(be)) : null;
-    if(!g || g.content !== content) return;
-    bookDupes.push({ kind: "card-vs-book", signature: g.signature, name: String((be && be.name) || g.name || ""),
-      content, keys: (be.keys || []).map(String), chars: content.length,
-      cards: g.cards.slice(), cardNames: g.cardNames.slice(),
-      preview: content.slice(0, 80).replace(/\s+/g, " "), savedChars: content.length * g.cards.length });
-  });
-  const totalEntries = list.reduce((n, c) => n + (Array.isArray(c.entries) ? c.entries.length : 0), 0);
-  return {
-    candidates, bookDupes,
-    stats: {
-      cards: list.length, totalEntries,
-      duplicatedEntries: candidates.reduce((n, g) => n + g.cards.length, 0),
-      savedChars: candidates.reduce((n, g) => n + g.savedChars, 0),
-      bookDuplicatedEntries: bookDupes.reduce((n, g) => n + g.cards.length, 0),
-      bookDupeCount: bookDupes.length,
-      bookSavedChars: bookDupes.reduce((n, g) => n + g.savedChars, 0),
-    },
-  };
-}
+/**
+ * 跨卡重复扫描：见 lib/group-layer.js 的 `scanSharedEntries()`（0.10.0 起两半共用一份实现）。
+ * 签名只用来筛，判等一律再逐字比对内容 —— 哈希碰撞绝不能变成搬错数据。
+ */
 /** 把共享书的条目合并进一张卡的条目表（同内容已存在则跳过）—— 给不支持全局世界书的客户端兜底。 */
 function mergeBookEntries(bookEntries, cardEntries){
   const have = new Set((Array.isArray(cardEntries) ? cardEntries : []).map(contentKeyOf));
@@ -2197,6 +2328,8 @@ function applyBookPromotion(cards, bookEntries, signatures){
 
 export { apply, inject, name, planPresetInstall, installCcPreset, supportsDeclaredPresets, presetTargetRoot, presetSourceRoot,
   draftKeyPartsFrom, draftContentSummary, listDraftSlotsOnDisk, migrateDraftDecision,
+  // 卡组层（0.10.0）：卡库快照 + 卡组作用域 —— 卡组数据的唯一入口，两半共用 lib/group-layer.js 的纯组装
+  readLibrarySnapshot, groupScope,
   // 落盘根与 lib 层 CRUD（供回归测试直接断言「DSH_HOME 优先 + 读时回退」）
   dshHomeDir, legacyDshHomeDir, dataRoots, draftDirs, draftDir, draftPath, findDraftPath, safeDraftFile,
   persistDraftSync, loadPersistedDraftSync, libDirs, libDir, getDraftFor, setDraftFor, cardFingerprint, normalizeCardShape,
@@ -2212,6 +2345,10 @@ export { apply, inject, name, planPresetInstall, installCcPreset, supportsDeclar
   // 0.9.0 组级共享世界书：落盘 + 纯函数（扫描/提升/回填），两半同构、条目与卡内 character_book 同形
   BOOK_SPEC, bookDirs, bookDir, bookPath, makeBookEntry, normalizeBook, bookRevOf, readBookRaw, writeBook, deleteBook,
   contentKeyOf, bookCardsFor, scanSharedEntries, mergeBookEntries, applyBookPromotion,
+  // 0.9.1 SillyTavern 兼容层：PNG 双块（chara 的 V2 投影 + 纯 CCv3）、ccv3 优先读取、ST 世界书绑定
+  stV2Projection, stripDecorators, withStWorld, pngCardChunks, buildTEXtChunk, buildPngWithCard, embedCardIntoPngBytes, extractCardFromPngBytes,
+  // 0.9.1 B2：V2/V1 卡升级成 CCv3（PNG/CHARX/JSON 三条导入路径共用这一份实现）
+  upgradeCardToV3, normTags,
   REL_TYPES, REL_TYPE_LABELS, REL_BEGIN, REL_END };