@xia-sc/dsh-cc-studio 0.8.3 → 0.9.1

package/lib/index.js

@@ -622,7 +622,7 @@ function spliceRelations(description, section, meta){
  * 跨卡体检（纯函数）。members / cards 由调用方给：
  *   members = 组内卡的 id 列表；cards = [{id, name, description, constantTokens, tokenBudget}]
  */
-function checkGroup(group, members, cards){
+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 || [] });
@@ -655,12 +655,21 @@ function checkGroup(group, members, cards){
   if(unrendered.length) add("warn", "unrendered", unrendered.length + " 张成员卡的 description 里还没有【关系】段（关系目前只存在于图谱里，导出的卡看不到）", unrendered);
   if(stale.length) add("warn", "stale-render", stale.length + " 张成员卡的【关系】段落后于图谱（标记里的 rev 与当前 rev 不一致），建议重新渲染", stale);
   // 群聊版的「单次触发」陷阱：每张卡的 constant 每轮都进上下文，卡越多固定开销越大
-  const constTokens = memberCards.reduce((n, c) => n + (Number(c.constantTokens) || 0), 0);
+  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 && constTokens > minBudget * 0.8){
-    add("warn", "constant-budget", "群聊每轮固定开销偏高：成员卡常驻条目合计约 " + constTokens + " token（已达最小预算 " + minBudget + " 的 " + Math.round(constTokens / minBudget * 100) + "%）");
+  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: constTokens, minBudget } };
+  return { issues, stats: { nodes: g.nodes.length, edges: g.edges.length, members: memberCards.length,
+    constantTokens: { card: cardConst, shared: sharedConst, total: constTokens }, minBudget } };
 }
 
 /** 读分组：主根优先，回退旧根（与角色库同规）。 */
@@ -734,11 +743,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=[];
@@ -768,8 +831,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;
@@ -780,15 +842,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; }
@@ -798,33 +864,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;
@@ -836,7 +972,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;
@@ -1661,7 +1797,7 @@ function apply(ctx, config){
           if(!found) return fail("not-found", "分组不存在: " + String(args.id));
           const cur = normalizeGroup(found.obj);
           if(typeof args.expectedRev === "number" && args.expectedRev !== cur.rev){
-            return fail("stale-rev", "分组已被外部修改（期望 rev=" + args.expectedRev + "，实际 rev=" + cur.rev + "）—— 先重新读取再改", { staleRev: true, expectedRev: args.expectedRev, actualRev: cur.rev });
+            return fail("stale-rev", "分组已被外部修改（期望 rev=" + args.expectedRev + "，实际 rev=" + cur.rev + "）—— 先重新读取再改", { staleGroupRev: true, expectedRev: args.expectedRev, actualRev: cur.rev });
           }
           const applied = applyGroupOps(cur, args.ops);
           if(!applied.applied.length) return ok({ group: cur, applied: [], rejected: applied.rejected, changed: false });
@@ -1674,7 +1810,10 @@ function apply(ctx, config){
           const g = normalizeGroup(found.obj);
           const memberIds = await groupMemberIds(g.id);
           const cards = await libraryCardsFor(memberIds);
-          return ok(Object.assign({ groupId: g.id, rev: g.rev, name: g.name }, checkGroup(g, memberIds, cards)));
+          // 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)));
         }
         case "cc_renderRelations":{
           // 渲染进**当前草稿**（与工具半共用同一份草稿文件）；要落库仍需再存一次
@@ -1710,10 +1849,11 @@ function apply(ctx, config){
           if(!gid) return fail("invalid-group", "需要 groupId");
           const found = await readBookRaw(gid);
           const cards = await bookCardsFor(await groupMemberIds(gid));
-          const scan = scanSharedEntries(cards);
+          const book = found ? normalizeBook(found.obj, gid) : null;
+          // 把书一起交给 scan → 认得出「卡内条目与共享书逐字重复」那一类（报告 P1）
+          const scan = scanSharedEntries(cards, book ? book.data.entries : []);
           const cardList = cards.map(c => ({ id: c.id, name: c.name, entries: (c.entries || []).length }));
           if(!found) return ok({ exists: false, groupId: gid, cards: cardList, scan });
-          const book = normalizeBook(found.obj, gid);
           return ok({ exists: true, groupId: gid, book, rev: bookRevOf(book),
             tokens: estimateTokensLite(book.data.entries.map(e => e.content).join("\n")),
             cards: cardList, scan });
@@ -1722,10 +1862,10 @@ function apply(ctx, config){
           const gid = safeGroupId(args.groupId);
           if(!gid) return fail("invalid-group", "需要 groupId");
           const found = await readBookRaw(gid);
-          const cur = found ? normalizeBook(found.obj, gid) : normalizeBook({ data: { name: String(args.name || "共享设定") } }, gid);
+          const cur = found ? normalizeBook(found.obj, gid) : await newBookFor(gid, args.name);
           if(typeof args.expectedBookRev === "number" && args.expectedBookRev !== bookRevOf(cur)){
             return fail("stale-rev", "共享世界书已被外部修改（期望 rev=" + args.expectedBookRev + "，实际 rev=" + bookRevOf(cur) + "）—— 先重新读取再改",
-              { staleRev: true, expectedBookRev: args.expectedBookRev, actualBookRev: bookRevOf(cur) });
+              { staleBookRev: true, expectedBookRev: args.expectedBookRev, actualBookRev: bookRevOf(cur) });
           }
           const applied = [], rejected = [];
           if(args.name !== undefined) cur.data.name = String(args.name).slice(0, 80);
@@ -1771,20 +1911,27 @@ function apply(ctx, config){
           const gid = safeGroupId(args.groupId);
           if(!gid) return fail("invalid-group", "需要 groupId");
           const found = await readBookRaw(gid);
-          const cur = found ? normalizeBook(found.obj, gid) : normalizeBook({}, gid);
+          const cur = found ? normalizeBook(found.obj, gid) : await newBookFor(gid);   // 默认名 `<组名>·共享设定`（报告 4.2）
           const cards = await bookCardsFor(await groupMemberIds(gid));
-          const scan = scanSharedEntries(cards);
-          const known = new Map(scan.candidates.map(c => [c.signature, c]));
+          // 候选两类：卡间重复（提升进书）+ 卡内条目与共享书逐字重复（书里已有，只清卡内副本）—— 见 agent 半同一处注释
+          const scan = scanSharedEntries(cards, cur.data.entries);
+          const known = new Map(scan.candidates.concat(scan.bookDupes).map(c => [c.signature, c]));
           // 只认得扫描出来的候选：传了不存在的签名一律拒绝 —— 这是会**从多张卡里删条目**的操作，绝不猜
-          const requested = (Array.isArray(args.keys) && args.keys.length) ? args.keys.map(String) : scan.candidates.map(c => c.signature);
+          const requested = (Array.isArray(args.keys) && args.keys.length) ? args.keys.map(String)
+            : scan.candidates.map(c => c.signature).concat(scan.bookDupes.map(c => c.signature));
           const unknownKeys = requested.filter(s => !known.has(s));
           const use = requested.filter(s => known.has(s));
+          const bookSigs = new Set(cur.data.entries.map(contentKeyOf));
+          const promoteSigs = use.filter(s => !bookSigs.has(s));
+          const cleanSigs = use.filter(s => bookSigs.has(s));
           const plan = applyBookPromotion(cards, cur.data.entries, use);
-          const summary = (g) => ({ signature: g.signature, name: g.name, cards: g.cards.length, cardNames: g.cardNames, chars: g.chars, savedChars: g.savedChars, nameMismatch: g.nameMismatch, keysMismatch: g.keysMismatch, preview: g.preview });
+          const summary = (g) => ({ kind: g.kind || "card-vs-card", signature: g.signature, name: g.name, cards: g.cards.length, cardNames: g.cardNames,
+            chars: g.chars, savedChars: g.savedChars, nameMismatch: g.nameMismatch === true, keysMismatch: g.keysMismatch === true, preview: g.preview });
           if(args.apply !== true){
-            return ok({ dryRun: true, changed: false, wouldPromote: use.length, unknownKeys,
-              removedTotal: plan.removedTotal, perCard: plan.cards.map(c => ({ id: c.id, name: c.name, removed: c.removed, left: c.entries.length })),
-              candidates: scan.candidates.map(summary), stats: scan.stats, rev: bookRevOf(cur) });
+            return ok({ dryRun: true, changed: false, wouldPromote: promoteSigs.length, wouldClean: cleanSigs.length, unknownKeys,
+              removedTotal: plan.removedTotal, savedChars: plan.savedChars,
+              perCard: plan.cards.map(c => ({ id: c.id, name: c.name, removed: c.removed, left: c.entries.length })),
+              candidates: scan.candidates.map(summary), bookDuplicates: scan.bookDupes.map(summary), stats: scan.stats, rev: bookRevOf(cur) });
           }
           const bookNext = Object.assign({}, cur, { data: Object.assign({}, cur.data, { entries: plan.bookEntries }) });
           const saved = await writeBook(gid, bookNext);
@@ -1800,9 +1947,11 @@ function apply(ctx, config){
               touched.push({ id: c.id, name: c.name, removed: c.removed, left: c.entries.length });
             }catch(e){ touched.push({ id: c.id, name: c.name, error: String(e && e.message || e) }); }
           }
-          return ok({ dryRun: false, changed: true, promoted: plan.promoted.length, removedTotal: plan.removedTotal,
+          const promotedCopies = cards.reduce((n, c) => n + (Array.isArray(c.entries) ? c.entries.filter(e => promoteSigs.indexOf(contentKeyOf(e)) >= 0).length : 0), 0);
+          const cleaned = Math.max(0, plan.removedTotal - promotedCopies);
+          return ok({ dryRun: false, changed: true, promoted: plan.promoted.length, cleaned, removedTotal: plan.removedTotal,
             unknownKeys, bookRev: bookRevOf(saved), bookEntries: saved.data.entries.length, perCard: touched,
-            candidates: scan.candidates.map(summary), stats: scan.stats });
+            candidates: scan.candidates.map(summary), bookDuplicates: scan.bookDupes.map(summary), stats: scan.stats });
         }
         case "cc_applyBook":{
           const gid = safeGroupId(args.groupId);
@@ -1832,29 +1981,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)); }
@@ -1863,7 +2037,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）");
@@ -1873,20 +2047,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)); }
         }
@@ -1954,6 +2129,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;
@@ -2072,7 +2255,24 @@ async function bookCardsFor(ids){
  * 跨成员卡找「同一份设定」（纯函数）：按内容签名分组，出现在 **≥2 张卡**里的才算候选。
  * 只报候选、不下结论 —— 同内容不同名、同名不同内容都如实标注，交给用户/模型拍板。
  */
-function scanSharedEntries(cards){
+/**
+ * 新建共享书的默认名：`<组名>·共享设定`（拿不到组名才退回「共享设定」）。
+ * 第二轮报告 4.2：同一个人的多个组各建一本、全叫「共享设定」，导出成文件后根本分不清是哪一组。
+ * 两半同构（`tests/shared-book.test.mjs` 直接比对），改这里记得同步 `lib/agent.js`。
+ */
+function defaultBookName(groupName){
+  const n = String(groupName == null ? "" : groupName).trim();
+  return n ? n + "·共享设定" : "共享设定";
+}
+/** 新建一本空共享书（名字优先用调用方给的，否则 `<组名>·共享设定`）。两半同构。 */
+async function newBookFor(gid, explicitName){
+  const want = String(explicitName == null ? "" : explicitName).trim();
+  if(want) return normalizeBook({ data: { name: want } }, gid);
+  let gname = "";
+  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 => {
@@ -2089,13 +2289,29 @@ function scanSharedEntries(cards){
   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,
+    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),
     },
   };
 }
@@ -2122,19 +2338,22 @@ function applyBookPromotion(cards, bookEntries, signatures){
   const promoted = [];
   const nextCards = (Array.isArray(cards) ? cards : []).map(c => {
     const kept = [];
-    let removed = 0;
+    let removed = 0, removedChars = 0;
     (Array.isArray(c.entries) ? c.entries : []).forEach(e => {
       const sig = contentKeyOf(e);
       if(want.has(sig)){
         if(!have.has(sig)){ have.add(sig); book.push(makeBookEntry(e)); promoted.push(sig); }
         removed += 1;
+        removedChars += String(e.content == null ? "" : e.content).length;
         return;
       }
       kept.push(makeBookEntry(e));
     });
-    return { id: c.id, name: c.name, entries: kept, removed };
+    return { id: c.id, name: c.name, entries: kept, removed, removedChars };
   });
-  return { bookEntries: book, cards: nextCards, promoted, removedTotal: nextCards.reduce((n, c) => n + c.removed, 0) };
+  return { bookEntries: book, cards: nextCards, promoted,
+    removedTotal: nextCards.reduce((n, c) => n + c.removed, 0),
+    savedChars: nextCards.reduce((n, c) => n + c.removedChars, 0) };
 }
 
 export { apply, inject, name, planPresetInstall, installCcPreset, supportsDeclaredPresets, presetTargetRoot, presetSourceRoot,
@@ -2154,6 +2373,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 };
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xia-sc/dsh-cc-studio",
-  "version": "0.8.3",
+  "version": "0.9.1",
   "description": "CCv3 角色卡工坊：融合工坊 + CC 模式 + JSON/PNG/CHARX + 中英双语（跟随全局）",
   "keywords": [
     "dsh",
@@ -38,7 +38,7 @@
     "presets"
   ],
   "scripts": {
-    "test": "node tests/rpc-channel.test.mjs && node tests/preset-install.test.mjs && node tests/cc-detection.test.mjs && node tests/client-greetings.test.mjs && node tests/draft-slot-sync.test.mjs && node tests/nav-highlight.test.mjs && node tests/clear-card.test.mjs && node tests/export-entry.test.mjs && node tests/close-button.test.mjs && node tests/tools-contract.test.mjs && node tests/relations.test.mjs && node tests/relations-view.test.mjs && node tests/shared-book.test.mjs && node tests/data-root.test.mjs",
+    "test": "node tests/rpc-channel.test.mjs && node tests/preset-install.test.mjs && node tests/cc-detection.test.mjs && node tests/client-greetings.test.mjs && node tests/draft-slot-sync.test.mjs && node tests/nav-highlight.test.mjs && node tests/clear-card.test.mjs && node tests/export-entry.test.mjs && node tests/close-button.test.mjs && node tests/tools-contract.test.mjs && node tests/relations.test.mjs && node tests/relations-view.test.mjs && node tests/shared-book.test.mjs && node tests/shared-book-st-export.test.mjs && node tests/st-compat.test.mjs && node tests/promote-draft-sync.test.mjs && node tests/data-root.test.mjs",
     "prepublishOnly": "npm test"
   },
   "dsh": {