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

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.
@@ -93,7 +98,7 @@ function makeDefaultDraft(){
       first_mes:"", alternate_greetings:[], group_only_greetings:[],
       mes_example:"", creator_notes:"", creator_notes_multilingual:{}, source:[], assets:[{type:"icon", uri:"ccdefault:", name:"main", ext:"png"}],
       creation_date: nowSec(), modification_date: nowSec(),
-      character_book:{ name:"", description:"", scan_depth:4, token_budget:1200, recursive_scanning:false, extensions:{}, entries:[] }
+      character_book:{ name:"", description:"", scan_depth:4, token_budget:2400, recursive_scanning:false, extensions:{}, entries:[] }
     }
   };
 }
@@ -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 } });
 }
 
 /** 读分组：主根优先，回退旧根（与角色库同规）。 */
@@ -803,7 +761,7 @@ function normalizeDraft(d){
   // 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:[]};
+  d.data.character_book=d.data.character_book||{name:"",description:"",scan_depth:4,token_budget:2400,recursive_scanning:false,extensions:{},entries:[]};
   if(!Array.isArray(d.data.character_book.entries)) d.data.character_book.entries=[];
   if(!Array.isArray(d.data.group_only_greetings)) d.data.group_only_greetings=[];
   if(!Array.isArray(d.data.alternate_greetings)) d.data.alternate_greetings=[];
@@ -1085,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; }
@@ -1100,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();
@@ -1146,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 时排除自己（给自己改名不算撞车）。
  * 两半同构 —— 界面和模型必须落到同一条规则上，否则会出现「模型建不了同名组、界面却建了两个」。
@@ -1192,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) || 2400,
+    });
   }
   return out;
 }
@@ -1805,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":{
           // 渲染进**当前草稿**（与工具半共用同一份草稿文件）；要落库仍需再存一次
@@ -2224,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;
 }
@@ -2272,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));
@@ -2358,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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xia-sc/dsh-cc-studio",
-  "version": "0.9.1",
+  "version": "0.10.3",
   "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/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",
+    "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/group-scope.test.mjs && node tests/group-metrics.test.mjs && node tests/group-checks.test.mjs && node tests/group-consistency.test.mjs && node tests/group-layer-guard.test.mjs && node tests/data-root.test.mjs",
     "prepublishOnly": "npm test"
   },
   "dsh": {

package/presets/cc/agent.cordis.yml

@@ -22,12 +22,18 @@
 # The preset's own persona, shadowing the deployment default for this agent.
 # dsh >= 0.1.5-rc.1: the persona row takes `prefix` (required) + optional `suffix`
 # — the old `text` key was replaced and now fails the config schema.
-# `{{model}}` and `{{cwd}}` resolve from the agent's own route and workspace.
+#
+# dsh >= 0.2.1-rc.2: only `provider` / `model` are registered prompt
+# variables. The old `cwd` variable is NOT one of them — `dsh-system-prompt`
+# interpolates strictly and throws `unknown prompt variable` before the first
+# model request, which makes every turn in CC mode fail. The working directory
+# reaches the model as required runtime context instead, so never add that
+# variable back here.
 - id: persona
   name: '@deepseek-ai/dsh-persona'
   config:
     prefix: |
-      你是 CC 角色卡工坊的专属引导员（CC 模式），模型 {{model}}，工作目录 {{cwd}}。
+      你是 CC 角色卡工坊的专属引导员（CC 模式），模型 {{model}}。
       你的唯一任务是把用户的一句话点子变成可导入 SillyTavern / Risu 的完整 CCv3 卡（spec: chara_card_v3）。
       必须走完强制工作流，不可偷懒跳过 5 维世界观和世界书：
       1) cc_get_card — 先看草稿，告诉用户还缺什么
@@ -41,6 +47,8 @@
 
       规则：每次对话只追问 1-2 个薄弱点，问完立刻调工具写入；用户说“随便/跳过”也要你合理推断补全，不能留空；严禁跳过 3/4 步直接做问候语；每调一次工具要简要总结“已写入 X，下一步 Y”，并让胶囊实时同步；结束前必须 cc_validate。工具返回里只有一份 workflow.next（下一步该做什么）与 workflow.hint（进度摘要），照它走即可；用户还没回答就别抢跑。
 
+      **工具参数必须是严格合法的 JSON**：最后一个字段 / 数组元素后不要写逗号，不要用 ```json 代码块包裹，不要注释、不要单引号；字符串里的换行写成 \n、双引号写成 \"。一次只传 1-3 个字段，长字段（description/personality/scenario）分多次调用写；tags / loreKeys 这类数组或对象字段单独一次调用，不要和长文本同批。参数 JSON 非法时 provider 会在调用前直接判本轮失败（用户只看到「本轮运行失败」），所以宁可分多次小调用。
+
 - id: agent-instructions
   name: '@deepseek-ai/dsh-agent-instructions'
   config:

package/presets/cc.patch.yml

@@ -57,12 +57,18 @@
           # The preset's own persona, shadowing the deployment default for this agent.
           # dsh >= 0.1.5-rc.1: the persona row takes `prefix` (required) + optional `suffix`
           # — the old `text` key was replaced and now fails the config schema.
-          # `{{model}}` and `{{cwd}}` resolve from the agent's own route and workspace.
+          #
+          # dsh >= 0.2.1-rc.2: only `provider` / `model` are registered prompt
+          # variables. The old `cwd` variable is NOT one of them — `dsh-system-prompt`
+          # interpolates strictly and throws `unknown prompt variable` before the first
+          # model request, which makes every turn in CC mode fail. The working directory
+          # reaches the model as required runtime context instead, so never add that
+          # variable back here.
           - id: persona
             name: '@deepseek-ai/dsh-persona'
             config:
               prefix: |
-                你是 CC 角色卡工坊的专属引导员（CC 模式），模型 {{model}}，工作目录 {{cwd}}。
+                你是 CC 角色卡工坊的专属引导员（CC 模式），模型 {{model}}。
                 你的唯一任务是把用户的一句话点子变成可导入 SillyTavern / Risu 的完整 CCv3 卡（spec: chara_card_v3）。
                 必须走完强制工作流，不可偷懒跳过 5 维世界观和世界书：
                 1) cc_get_card — 先看草稿，告诉用户还缺什么
@@ -76,6 +82,8 @@
 
                 规则：每次对话只追问 1-2 个薄弱点，问完立刻调工具写入；用户说“随便/跳过”也要你合理推断补全，不能留空；严禁跳过 3/4 步直接做问候语；每调一次工具要简要总结“已写入 X，下一步 Y”，并让胶囊实时同步；结束前必须 cc_validate。工具返回里只有一份 workflow.next（下一步该做什么）与 workflow.hint（进度摘要），照它走即可；用户还没回答就别抢跑。
 
+                **工具参数必须是严格合法的 JSON**：最后一个字段 / 数组元素后不要写逗号，不要用 ```json 代码块包裹，不要注释、不要单引号；字符串里的换行写成 \n、双引号写成 \"。一次只传 1-3 个字段，长字段（description/personality/scenario）分多次调用写；tags / loreKeys 这类数组或对象字段单独一次调用，不要和长文本同批。参数 JSON 非法时 provider 会在调用前直接判本轮失败（用户只看到「本轮运行失败」），所以宁可分多次小调用。
+
           - id: agent-instructions
             name: '@deepseek-ai/dsh-agent-instructions'
             config: