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

package/lib/agent.js

@@ -7,12 +7,19 @@ import { mkdir, readdir, readFile, writeFile, unlink } from "node:fs/promises";
 import { mkdirSync, existsSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+// 卡组层（0.10.0）：卡组作用域组装 / 世界书分段统计 / 条目体检的**唯一实现**。
+// 宿主半 import 同一个文件 —— 以前这些逻辑两半各抄一份、靠测试逐字比对维持同步，
+// 「改了四个、漏了第五个」就是这么来的（见 lib/group-layer.js 顶部）。
+import { REL_TYPES, REL_TYPE_LABELS, REL_BEGIN, REL_END,
+  WORLD_DIMS, AUTO_NAMES, isAutoEntry, looksLikeLegacyAuto,
+  estimateTokens, lorebookTokens, contentKeyOf, scanSharedEntries,
+  assembleScope, groupMetrics, lorebookMetrics, metricsBrief, auditLoreEntries, runGroupChecks } from "./group-layer.js";
 const name = "dsh-cc-studio-agent";
 // 版本标识（0.7.1）：每次工具返回都带 `build`。
 // 由来：第五轮实测里测试者第一遍跑出「四项全无变化」，其实只是**没重启 dsh** —— LLM 侧完全无法
 // 分辨「代码没改」和「改了但没加载」。有了这个字段，任何一次调用都能先确认自己测的是哪一版。
 // 发版时与 package.json 的 version 同步。
-const BUILD = "0.9.1";
+const BUILD = "0.10.0";
 const inject = ["tools", "agents"];
 
 function nowSec(){ return Math.floor(Date.now()/1000); }
@@ -327,10 +334,7 @@ function setDraft(ctx, draft, exec){
 // 「卡属于哪个组」记在库条目 meta.groupId（单一真源），分组文件里刻意**不存成员列表**。
 // 关系只活在插件侧；要让分享出去的卡自包含，用 cc_render_relations 渲染进 description 的固定标记区。
 // ——————————————————————————————————————————————————————————————
-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]; }
@@ -525,53 +529,19 @@ function spliceRelations(description, section, meta){
   const head = desc.replace(/\s*$/, "");
   return (head + (head ? "\n\n" : "") + block).trim();
 }
-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);
-  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 } };
+/**
+ * 跨卡体检（0.10.0 起是 lib/group-layer.js 的 `runGroupChecks()` 的薄包装）。
+ *
+ * 老签名与返回形状**逐字保留**（issues[].level/code/message/refs + stats），所以宿主 cc_groupCheck、
+ * 工具 cc_group_check 与既有测试都不用改；实现搬去卡组层是为了让「卡组的下一个新检查项」只加一个
+ * 注册表项（那里的 GROUP_CHECKS），而不是在三个地方各写一遍清单、各报一套 code。
+ * opts.checks 可只跑指定类别（structure / relations / budget / lore-quality / cross-card）。
+ */
+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 } });
 }
 async function readGroupRaw(id){
   const file = safeGroupId(id) + ".json";
@@ -616,22 +586,23 @@ async function groupMemberIds(groupId){
   const entries = await listLibraryEntries();
   return entries.filter(e => String(e.groupId || "") === gid).map(e => e.id);
 }
-/** 体检 / 渲染需要的卡片摘要（卡不在库里就跳过）。 */
+/** 体检 / 渲染需要的卡片摘要（卡不在库里就跳过）—— 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;
 }
@@ -653,6 +624,42 @@ async function resolveGroupFor(ctx, exec, explicitGroupId){
   const myNode = cardId ? (g.nodes.find(n => n.kind === "card" && n.cardId === cardId) || null) : null;
   return { ok: true, cardId, groupId, group: g, myNode, groups };
 }
+/**
+ * 卡组作用域（0.10.0）—— 取「这次操作哪个组、组里有哪些卡、这个组的书是什么」的**唯一入口**。
+ *
+ * 为什么立这一层：共享书上线后，每个工具都自己写了一遍「来源卡 → meta.groupId → 读书」，
+ * 实测连着两轮出现「改了四个、漏了第五个」。现在数据只从这里出：工具半传 sessionKey
+ * （草稿的来源卡 id 记在 sidecar origin.json 里），宿主半传 cardId / groupId。
+ * 纯组装在 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 = readOriginSync(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));
+  // ⚠️ 组文件缺失（用户手工删过 cc-groups，或历史数据）时**不提前返回**：成员与共享书照样读出来，
+  // 只是 group 为 null / ok:false —— 旧实现（sharedBookScopeFor）根本不看组文件，提前返回会让
+  // 「组没了但书还在」的卡突然看不到自己的书（0.9.x 行为回归）。
+  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.8.0：分组的增删改查（LLM 侧）——
 // 此前 LLM 只能读写**组内图谱**，改不了「哪张卡属于哪个组」：卡一旦因任何原因掉组，
@@ -770,9 +777,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; }
@@ -783,14 +797,19 @@ async function listLibraryEntries(){
       try{
         const raw=await readFile(join(dir,f),"utf8");
         const obj=JSON.parse(raw);
-        if(obj && obj.meta && obj.id) seen.set(id,obj.meta);
-        else if(obj && obj.draft) seen.set(id,makeLibraryEntryMeta(obj.draft,null,id));
+        if(obj && obj.meta && obj.id) seen.set(id,{ id:id, meta:obj.meta, draft:obj.draft||null, dir:dir });
+        else if(obj && obj.draft) 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();
@@ -862,20 +881,12 @@ function out(schema){ return { schema, render: (args, result) => [{ type:"text",
 //      的自相矛盾组合（模型无法据此决策，只能忽略）；
 //   ② **lore 的「完成」要求至少 1 条非自动条目**：否则 autoLorebook 一次生成 5 条就顶替了第 4 步的共创，
 //      而 `cc_add_lorebook_entries` 的契约写着「必调」—— 两条相反指令同时下发正是实测到的卡壳点。
-const WORLD_DIMS = ["timeline","factions","geo","power","daily"];
 const DIM_NAMES = { timeline:"年表", factions:"势力", geo:"地理", power:"力量体系", daily:"日常" };
 // 英文 key 与 0.4.x 生成过的完全一致（老卡里就是这个写法），避免升级后触发词看起来「悄悄变了」
 const DIM_EN = { timeline:"timeline", factions:"faction", geo:"geography", power:"power", daily:"daily" };
-// 旧数据没有 cc_auto 标记，靠「名字是维度名」兜底；但**必须同时看内容**，
-// 否则用户手工建的、恰好叫「日常」的条目会被下一次 cc_patch_world 静默删掉（0.5.0 修）。
-const AUTO_NAMES = new Set(["年表","势力","地理","力量体系","日常"]);
-function isAutoEntry(e){
-  return !!(e && (e.cc_auto === true || (e.extensions && e.extensions.cc_auto)));
-}
-function looksLikeLegacyAuto(e){
-  if(!e || !AUTO_NAMES.has(String(e.name||""))) return false;
-  return /^\s*@@/.test(String(e.content||"")) || Array.isArray(e.keys) && e.keys.some(k => ["timeline","faction","geography","power","daily"].includes(String(k)));
-}
+// WORLD_DIMS / AUTO_NAMES / isAutoEntry / looksLikeLegacyAuto 由 lib/group-layer.js 提供（两半共用）。
+// 这里曾经各有一份：AUTO_NAMES 的判据（名字是维度名**且**内容/keys 像自动条目）如果两边漂移，
+// 就会出现「工具以为这条是 auto、工坊以为不是」——同一份数据两种结论。
 /**
  * 工作流状态。第二个参数是**该组共享世界书**（`{ bookName, entries, tokens }`，没有就传 null/省略）。
  *
@@ -954,6 +965,8 @@ function workflowStatus(draft, shared){
     sharedBook: sharedLoreCount ? { name: String((shared && shared.bookName) || ""), entries: sharedLoreCount, tokens: Number((shared && shared.tokens) || 0) } : null,
     constantEntries,                             // { card, shared, total } —— 与 cc_lint_lorebook 同一口径
     sharedHasDecorator,                          // 共享书里有没有 @@decorator（存在性检查用合计）
+    metrics: metricsBrief(metrics),              // 只有数字、**不带条目正文**：`all` 数组会随每个工具的返回出去
+                                                 // （0.10.0 LLM 侧实测多带约 1800 token —— 见 metricsBrief 的注释）
     next,
     // 0.6.0（R1/R2）：`hint` 只报**进度**，不再内嵌 `next` 全文 ——
     // 旧版 `hint = 进度 + " → " + next` 让同一句话在一份返回里出现三遍（hint 内嵌 next、message 又等于 hint）。
@@ -978,145 +991,16 @@ function progressHint(step, state, worldFilled, loreCount, manualLoreCount, done
     + " " + mark(state.greetings) + "问候语"
     + (done ? " · 已完成，可导出/保存" : "");
 }
-// 粗略 token 估算：CJK 一字≈1 token，其余按 4 字符≈1 token（用于 validate 的预算告警与 lint/preview 报告）
-function estimateTokens(text){
-  const s = String(text||"");
-  let cjk = 0;
-  for(const ch of s){ if(ch.charCodeAt(0) > 0x2E7F) cjk++; }
-  const rest = s.length - cjk;
-  return Math.ceil(cjk + rest/4);
-}
-function lorebookTokens(entries){
-  return (Array.isArray(entries)? entries : []).reduce((n,e) => n + estimateTokens(e && e.content), 0);
-}
+// —— 世界书口径与体检的实现都在 lib/group-layer.js（0.10.0）——
+// estimateTokens / lorebookTokens / lorebookMetrics / auditLoreEntries / worstCaseTrigger 等
+// 以前在这里各有一份、宿主半再抄一份，靠测试逐字比对维持同步（「改了四个、漏了第五个」的根因）；
+// 现在两半 import 同一个文件，改口径只改一处。
 /**
- * 世界书的三段基础统计（**卡内 / 共享书 / 合计**）—— 一处实现，多处引用。
- *
- * 为什么收口（第四轮报告的教训）：共享书的条目/token 口径已经散落在 simulate / lint /
- * group_check / preview_export / validate 五个工具里，于是连着两轮出现「改了四个、漏了第五个」
- * 与「validate 改了、lint 漏了」——都是同一个语义写了两遍。基础统计收在这里（同
- * `outgoingEdgesOf()` 之于渲染与计数），各工具只在其上做自己的派生（最坏情况、单次触发、预算占用…）。
- *
- * 同时给出两个**存在性**判断的合计口径：有没有 constant、有没有 `@@decorator` ——
- * 这两条是「整本世界书」的性质，只数卡内会让「卡内没有、共享书里有」的组合被误报。
- * ⚠️ **逐条质量**检查（死 keys / 只有维度名的 keys / keys 与正文无交集 / 触发词冲突）**不在这里**：
- * 那是各工具自己决定范围的事 —— `cc_lint_lorebook` 的整改清单面向「你正在编辑的这张卡」，
- * `cc_validate` 是卡的收尾判定，两者都只覆盖卡内条目（共享书的条目质量走 cc_get_shared_book 那条线）。
+ * 世界书的三段基础统计：见 lib/group-layer.js 的 `lorebookMetrics()`（0.10.0 起是 groupMetrics 的
+ * 薄包装，形状与数字与 0.9.x 逐字一致）。历史与理由（为什么必须收口）也记在那个文件里。
  */
-function lorebookMetrics(cardEntries, sharedEntries){
-  const card = Array.isArray(cardEntries) ? cardEntries : [];
-  const shared = Array.isArray(sharedEntries) ? sharedEntries : [];
-  const seg = (list) => ({
-    entries: list.length,
-    tokens: lorebookTokens(list),
-    constant: list.filter(e => e && e.constant === true).length,
-    constantTokens: list.filter(e => e && e.constant === true).reduce((n, e) => n + estimateTokens(e && e.content), 0),
-    manual: list.filter(e => !isAutoEntry(e)).length,
-    hasDecorator: list.some(e => String((e && e.content) || "").includes("@@")),
-  });
-  return { card: seg(card), shared: seg(shared), total: seg(card.concat(shared)), all: card.concat(shared) };
-}
-/**
- * 世界书条目的**逐条质量检查** —— 一把尺子，卡内与共享书共用。
- *
- * 四类：非 constant 却没 keys / keys 只有维度名 / keys 与正文无交集 / 触发词被多条条目共用。
- *
- * 为什么收口（第五轮报告）：这四类此前只写在 `cc_lint_lorebook` 里、只作用于**卡内**，当时的理由是
- * 「共享书条目的质量走 `cc_get_shared_book` 那条线」—— 可那条线上**根本没有这个能力**（只有重复检测），
- * 于是共享书成了没人体检的一格：往书里塞一条同时踩三类的坏条目，两个工具都不出声。
- * 而共享书恰恰**比卡内更需要主动报**：它多卡共用（一条死 key 在**所有**成员卡上都不生效）、
- * 又**没有「卡」这个载体**（用户不会顺手翻到它）。
- *
- * 用法：`auditLoreEntries([{ source:"card", entries }, { source:"shared", entries: sharedEntries }])`。
- * 触发词冲突**跨来源一起算** —— 同一个词同时命中卡内与共享书的两条，是真实存在的 token 叠加。
- * 每条 issue 带 `entries`（条目名，冲突类则是**冲突的触发词**）、`contentKeys`（便于直接定位改）、
- * 与 `source`（`card` / `shared` / `mixed`）。
- */
-function auditLoreEntries(groups){
-  const gs = (Array.isArray(groups) ? groups : []).map(g => ({
-    source: String((g && g.source) || "card"),
-    list: (g && Array.isArray(g.entries) ? g.entries : []).filter(e => e && e.enabled !== false),
-  }));
-  const all = gs.reduce((n, g) => n.concat(g.list), []);
-  const sourceOf = (e) => { for(const g of gs){ if(g.list.indexOf(e) >= 0) return g.source; } return "card"; };
-  const srcOf = (items) => { const out = []; items.forEach(e => { const s = sourceOf(e); if(out.indexOf(s) < 0) out.push(s); }); return out.length > 1 ? "mixed" : (out[0] || "card"); };
-  const issues = [];
-  const push = (level, code, message, items) => issues.push({ level, code, message,
-    entries: items.map(e => String((e && e.name) || "")).filter(Boolean),
-    contentKeys: items.map(contentKeyOf), source: srcOf(items) });
-  const isDimKey = k => AUTO_NAMES.has(String(k)) || ["timeline","faction","geography","power","daily"].includes(String(k));
-  const nonConst = all.filter(e => !e.constant);
-  const keyed = nonConst.filter(e => Array.isArray(e.keys) && e.keys.length > 0);
-  const noKeys = nonConst.filter(e => !Array.isArray(e.keys) || e.keys.length === 0);
-  if(noKeys.length) push("error", "no-keys", noKeys.length + " 条非 constant 条目没有 keys（永远触发不了）", noKeys);
-  const dimOnly = keyed.filter(e => e.keys.every(isDimKey));
-  if(dimOnly.length) push("error", "dim-only-keys", dimOnly.length + " 条条目的 keys 只有维度名，真实对话不会命中（可用 cc_simulate_trigger 验证）", dimOnly);
-  const notInContent = keyed.filter(e => !e.keys.some(k => String(e.content || "").indexOf(String(k)) >= 0));
-  if(notInContent.length) push("warn", "key-not-in-content", notInContent.length + " 条条目的 keys 在自身 content 里找不到（可能误填或内容已改）", notInContent);
-  const seen = new Map();
-  all.forEach(e => (Array.isArray(e.keys) ? e.keys : []).forEach(k => {
-    const kk = String(k).toLowerCase();
-    if(!seen.has(kk)) seen.set(kk, []);
-    const arr = seen.get(kk);
-    if(arr.indexOf(e) < 0) arr.push(e);
-  }));
-  const dup = [...seen.entries()].filter(p => p[1].length > 1);
-  if(dup.length){
-    const items = [];
-    dup.forEach(p => p[1].forEach(e => { if(items.indexOf(e) < 0) items.push(e); }));
-    issues.push({ level: "warn", code: "duplicate-keys",
-      message: dup.length + " 个触发词被多条条目共用（会同时触发，可能互相打架）",
-      entries: dup.map(p => p[0]),          // 与既有行为一致：这一项的 entries 是**冲突的触发词**
-      contentKeys: items.map(contentKeyOf), source: srcOf(items) });
-  }
-  return { issues, errorCount: issues.filter(i => i.level === "error").length };
-}
-/**
- * 最坏情况单次触发量（0.7.0，N2）。
- *
- * 为什么不能只看总量：`token_budget` 管的是**一轮对话**里世界书能塞多少，而真正的坑是
- * 「用户随便一句话被好几个条目同时命中」—— 第四轮实测：总量 2272 / 预算 1200 看着只是超一点，
- * 但一句「剑冢到底是什么地方」单独就吃掉 **1139 token**（势力 + 地理 + 力量体系(constant) + 剑冢(constant)）。
- * 更糟的是它太好「修好」了：把 token_budget 调大，lint 立刻只剩一条 warning，可单次爆炸一点没变。
- *
- * 算法：把**共享同一个触发词的条目**并成一组（传递闭包 —— A/B 共享 x、B/C 共享 y，那么一句话
- * 可以把三条全带出来），再叠加**每轮必插的 constant**，取最大的那组作为最坏情况。
- * 单字符 key 不参与共现（"a" 这种会把整本书并成一组，报告全是噪音）。
- */
-function worstCaseTrigger(entries){
-  const list = (Array.isArray(entries) ? entries : []).filter(e => e && e.enabled !== false);
-  const constantEntries = list.filter(e => e.constant);
-  const constantTokens = constantEntries.reduce((n, e) => n + estimateTokens(e && e.content), 0);
-  const varEntries = list.filter(e => !e.constant);
-  const parent = new Map();
-  const find = x => { let r = x; while(parent.get(r) !== r) r = parent.get(r); while(parent.get(x) !== r){ const nx = parent.get(x); parent.set(x, r); x = nx; } return r; };
-  varEntries.forEach((e, i) => parent.set(i, i));
-  const byKey = new Map();
-  varEntries.forEach((e, i) => {
-    (Array.isArray(e.keys) ? e.keys : []).forEach(k => {
-      const kk = String(k).trim().toLowerCase();
-      if(kk.length < 2) return;
-      if(!byKey.has(kk)) byKey.set(kk, []);
-      byKey.get(kk).push(i);
-    });
-  });
-  byKey.forEach(idxList => { for(let i = 1; i < idxList.length; i++) parent.set(find(idxList[i]), find(idxList[0])); });
-  const groups = new Map();
-  varEntries.forEach((e, i) => {
-    const root = find(i);
-    if(!groups.has(root)) groups.set(root, { tokens: 0, names: [] });
-    const g = groups.get(root);
-    g.tokens += estimateTokens(e && e.content);
-    g.names.push(String((e && e.name) || ""));
-  });
-  let best = { tokens: constantTokens, names: [] };
-  groups.forEach(g => {
-    if(g.tokens + constantTokens > best.tokens) best = { tokens: g.tokens + constantTokens, names: g.names.slice() };
-  });
-  // 单条自己就最重的情况已含在上面（没有共享 key 的条目自成一组），这里只把常驻条目的名字补进名单。
-  const names = best.names.concat(constantEntries.map(e => String((e && e.name) || "")));
-  return { tokens: best.tokens, constantTokens, entries: names };
-}
+/** 世界书条目的逐条质量检查：见 lib/group-layer.js 的 `auditLoreEntries()`（两半共用一把尺子）。 */
+/** 最坏情况单次触发量：见 lib/group-layer.js 的 `worstCaseTrigger()`（算法与理由记在那里）。 */
 
 
 function apply(ctx){
@@ -1277,7 +1161,7 @@ function apply(ctx){
 
   tool({
     name: "cc_patch_world",
-    description: "【工作流第3步·共创·必调】写入 5 维世界观（timeline/factions/geo/power/daily 至少 3 项）。若用户已提供世界观文档，先用 2-3 句归纳你理解的 5 维，再问用户“哪几维最想展开？有无私设要加？”；若世界观薄弱，则与用户讨论 1-2 个薄弱点后再填。严禁未与用户讨论就直接照搬文档填满 5 维。调后下一步是 cc_add_lorebook_entries。",
+    description: "【工作流第3步·共创·必调】写入 5 维世界观（timeline/factions/geo/power/daily 至少 3 项）。若用户已提供世界观文档，先用 2-3 句归纳你理解的 5 维，再问用户“哪几维最想展开？有无私设要加？”；若世界观薄弱，则与用户讨论 1-2 个薄弱点后再填。严禁未与用户讨论就直接照搬文档填满 5 维。⚠️ 若本卡已在**有共享世界书**的分组里，本工具默认**不再**往卡内抄五维骨架（那些共同设定属于共享书，卡内副本会与它双重插入）—— 要卡内副本才显式传 autoLorebook:true。调后下一步是 cc_add_lorebook_entries。",
     parameters: {
       type:"object",
       properties:{
@@ -1286,7 +1170,7 @@ function apply(ctx){
         geo:{type:"string", description:"地理"},
         power:{type:"string", description:"力量体系"},
         daily:{type:"string", description:"日常"},
-        autoLorebook:{type:"boolean", description:"是否基于 5 维自动生成 3-6 条带 @@decorator 的 lorebook 条目，强烈建议 true"},
+        autoLorebook:{type:"boolean", description:"是否基于 5 维在**卡内**自动生成 3-6 条带 @@decorator 的 lorebook 条目。**不传时**：本卡所属分组若已有共享世界书覆盖这些维度 → 不生成（避免与共享书双重插入、触发词互相打架）；否则生成。true 强制生成，false 强制不生成。多卡同组时建议不传或传 false —— 共同设定留在共享书里。"},
         loreKeys:{
           type:"object",
           description:"**强烈建议提供**：为每一维自报触发词（真实对话里用户会说的实体名），如 {\"geo\":[\"旧校舍\",\"广播室\",\"天台\"],\"factions\":[\"夜巡\",\"学生会\"]}。不给的话自动条目只能用维度名当 key —— 用户永远不会说「地理」，那几条等于死条目。",
@@ -1310,7 +1194,17 @@ function apply(ctx){
       if(args.power!==undefined) w.power = String(args.power).slice(0,1000);
       if(args.daily!==undefined) w.daily = String(args.daily).slice(0,1000);
       cur.data.extensions.cc_world = w;
-      const shouldAuto = args.autoLorebook !== false; // 默认 true，防偷懒
+      // 0.10.0：默认值必须看得见「组里已经有什么」——
+      // 没显式传 autoLorebook 时，若本卡所属分组的共享书已覆盖这些维度，就**不在卡内生成副本**：
+      // 用户只想改五维里的一个字，不该被抄回整套骨架（那会抵消共享书的去重价值，并立刻踩
+      // 「卡内与书逐字重复」+「跨卡触发词冲突」两条检查）。显式 true / false 一律照办。
+      const explicitAuto = (typeof args.autoLorebook === "boolean") ? args.autoLorebook : null;
+      let shouldAuto = (explicitAuto === null) ? true : explicitAuto;
+      let autoSkipped = null;
+      if(explicitAuto === null){
+        const cover = await sharedBookCoversDims(ctx, exec);
+        if(cover.covered){ shouldAuto = false; autoSkipped = cover; }
+      }
       const autoDropped = [];
       const autoEdited = [];
       if(shouldAuto){
@@ -1391,9 +1285,21 @@ function apply(ctx){
       }
       const res = { ok:true, worldFilled: wf.worldFilled, loreCount: wf.loreCount,
         autoLoreAdded: autoEntries.length, autoLoreReplaced: autoDropped.length, autoLoreEdited: autoEdited.length,
+        autoLoreSkipped: !!autoSkipped,
+        autoLoreSkipReason: autoSkipped ? "shared-book-covers-dims" : null,
         sharedLoreKeys, heavyAutoEntries: heavyAuto.length,
         draftStatus: draftStatusFor(k, cur), workflow: wf,
-        message: "已写入五维（" + wf.worldFilled + "/5），自动生成 " + autoEntries.length + " 条基础条目。" + wf.next };
+        message: "已写入五维（" + wf.worldFilled + "/5），"
+          + (autoSkipped
+            ? "本组共享世界书已覆盖这些维度，**没有**在卡内生成副本（要卡内副本请显式传 autoLorebook:true）"
+            : "自动生成 " + autoEntries.length + " 条基础条目")
+          + "。" + wf.next };
+      if(autoSkipped){
+        warnings.push("本卡所属分组已有共享世界书「" + (autoSkipped.bookName || "未命名") + "」，其中 "
+          + autoSkipped.count + " 条覆盖了 年表/势力/地理/力量体系/日常 —— 本次**没有**在卡内生成基础条目："
+          + "卡内副本会在群聊里与共享书双重插入，触发词也会互相打架（组体检会报「卡内条目与共享书逐字重复」和「跨卡触发词冲突」两类问题）。"
+          + "确实需要卡内副本时显式传 autoLorebook:true；正常的下一步是 cc_add_lorebook_entries 补共创条目。");
+      }
       if(autoEdited.length) warnings.push("被替换的 " + autoEdited.length + " 条旧自动条目（" + autoEdited.join("、") + "）的 keys 曾被手工改过，这次已重建回默认维度名，手工触发词会丢。想保住它们：先用 cc_update_lorebook_entry 写回，或以后调本工具时带上 loreKeys。");
       if(args.verbose === true) res.draft = cur;
       if(warnings.length) res.warnings = warnings;
@@ -1774,8 +1680,10 @@ function apply(ctx){
       const texts = [];
       // 0.9.0 报告：共享书里的条目在真实聊天里**同样会被触发**（客户端把全局书与卡内 character_book
       // 叠加），所以模拟必须把它们一起算 —— 否则会把「会命中」报成「不会命中」（实测低估约 3 倍）。
+      // 0.10.0：作用域与 token 口径都走卡组层（sharedBookScopeFor / lorebookMetrics），本工具不再自己求和。
       const scope = await sharedBookScopeFor(ctx, exec);
       const shared = scope.entries;
+      const metrics = lorebookMetrics(entries, shared);
       const pool = entries.map(e => ({ e: e, src: "card" })).concat(shared.map(e => ({ e: e, src: "shared" })));
       if(typeof args.text === "string" && args.text.trim()) texts.push(args.text);
       if(Array.isArray(args.texts)) args.texts.forEach(x => { if(typeof x === "string" && x.trim()) texts.push(x); });
@@ -1811,10 +1719,10 @@ function apply(ctx){
       if(pool.length && results.every(r => r.hitCount === 0)) warnings.push("这些测试句一条都没触发。若用户很可能这么说，说明世界书的 keys 需要改成实体名（cc_update_lorebook_entry 或下次 cc_patch_world 带 loreKeys）");
       const never = entries.filter(e => e.enabled !== false && !e.constant && (!Array.isArray(e.keys) || e.keys.length === 0));
       if(never.length) warnings.push(never.length + " 条非 constant 条目没有 keys，永远触发不了：" + never.map(e=>String(e.name||"")).join("、"));
-      const totalTokens = lorebookTokens(entries.concat(shared));
+      const totalTokens = metrics.total.tokens;
       const res = { ok:true, simulated: results.length, results,
         lorebookTokens: totalTokens,
-        tokenSplit: { card: lorebookTokens(entries), shared: lorebookTokens(shared), total: totalTokens },
+        tokenSplit: { card: metrics.card.tokens, shared: metrics.shared.tokens, total: totalTokens },
         sharedBook: shared.length ? { groupId: scope.groupId, name: scope.bookName, entries: shared.length, tokens: scope.tokens } : null,
         scanDepth: book.scan_depth,
         message: "模拟完成：" + results.map(r => "「" + r.text.slice(0,16) + "」→ 命中 " + r.hitCount + " 条（约 " + r.tokens + " token"
@@ -1841,7 +1749,9 @@ function apply(ctx){
       // 所以预算、最坏情况都得把它们并起来算；同时拆出「卡内 / 共享 / 合计」三段，免得又变成一笔糊涂账。
       const scope = await sharedBookScopeFor(ctx, exec);
       const shared = scope.entries;
-      const m = lorebookMetrics(entries, shared);   // 三段基础统计（一处实现，与 cc_validate 同一份）
+      // 0.10.0：三段统计与「最坏情况」都从卡组层取 —— 数字只有一个来源，本工具不再自己求和。
+      const metrics = groupMetrics({ card: entries, book: shared });
+      const m = metrics.legacy;   // { card, shared, total, all } —— 与 0.9.x 的 lorebookMetrics 同形
       const all = m.all;
       const cardTokens = m.card.tokens;
       const sharedTokens = m.shared.tokens;
@@ -1863,7 +1773,8 @@ function apply(ctx){
           + (shared.length ? " —— 注意共享书是**独立一本**、由客户端分别管预算，调本卡预算盖不住它" : ""), [], "card");
       }
       // N2（0.7.0）：总量与「单次触发」是两个独立风险，只报总量会让「调大预算」看起来像修好了。
-      const worst = worstCaseTrigger(all);
+      // 范围 = 卡内 + 共享书（derived.worstCase 就是按这个范围算的，与 0.9.x 逐字一致）。
+      const worst = metrics.derived.worstCase;
       const worstCase = { tokens: worst.tokens, constantTokens: worst.constantTokens, budget, entries: worst.entries,
         overBudget: budget > 0 && worst.tokens > budget, sharedEntries: shared.length };
       if(worstCase.overBudget){
@@ -2042,10 +1953,13 @@ function apply(ctx){
 
   tool({
     name: "cc_group_check",
-    description: "【关系·体检】跨卡检查一个分组：孤儿节点（卡已删除）、悬空关系、重名节点（渲染会指向同一个人）、未渲染/已过期的【关系】段，以及**群聊每轮固定开销**（所有成员卡 constant 条目之和 vs 最小预算 —— 群聊时卡越多这块钱越贵，一张卡的单卡体检看不出来）。做完一批群聊卡后调一次。",
+    description: "【关系·体检】跨卡检查一个分组：图谱结构（孤儿节点 / 悬空关系 / 重名节点 / 未知类型）、卡内【关系】段（没渲染 / 落后于图谱）、**群聊每轮固定开销**（成员卡 constant + 共享书 constant vs 最小预算 —— 卡越多这块钱越贵，单卡体检看不出来）、**共享书条目质量**（死 key / 只有维度名的 key）、**跨卡一致性**（同一个触发词被多张卡共用、卡内条目与共享书逐字重复、组内五维漂移、成员卡全 auto）。做完一批群聊卡后调一次。用 checks 可只跑其中几类（structure / relations / budget / lore-quality / cross-card）。",
     parameters: {
       type:"object",
-      properties:{ groupId:{ type:"string", description:"可选：默认用当前卡所属分组" } },
+      properties:{
+        groupId:{ type:"string", description:"可选：默认用当前卡所属分组" },
+        checks:{ type:"array", items:{ type:"string" }, description:"可选：只跑指定检查类别（structure / relations / budget / lore-quality / cross-card），缺省全跑" },
+      },
       additionalProperties:false
     },
     output: out({ type:"object", additionalProperties:true }),
@@ -2056,16 +1970,19 @@ function apply(ctx){
           message: "这张卡还没入库或没加入分组，没有可体检的对象。" };
       }
       const g = r.group;
-      const memberIds = await groupMemberIds(g.id);
+      // 0.10.0：成员与共享书从卡组作用域取（一次读盘、形状唯一）—— 不再自己 readBookRaw + normalizeBook。
+      const scope = await groupScope({ groupId: g.id, include: "summary" });
+      const memberIds = scope.memberIds;
       const cards = await libraryCardsFor(memberIds);
-      // 0.9.0：体检的是**这个组**，所以读这个组的共享书（显式传 groupId 时它与当前卡所在组可能不同）
-      const bkFound = await readBookRaw(g.id);
-      const sharedEntries = bkFound ? normalizeBook(bkFound.obj, g.id).data.entries.filter(e => e && e.enabled !== false) : [];
-      const res = checkGroup(g, memberIds, cards, sharedEntries);
+      const sharedEntries = scope.book ? scope.book.entries : [];
+      // 数字与跨卡检查的输入都来自卡组层：metrics 给预算类，scope 给跨卡一致性（成员条目与五维）
+      const metrics = groupMetrics({ cardId: scope.cardId, card: [], members: scope.members, book: sharedEntries });
+      const res = checkGroup(g, memberIds, cards, sharedEntries, { checks: args.checks, scope: scope, metrics: metrics });
       const errorCount = res.issues.filter(i => i.level === "error").length;
       return { ok:true,
         group: { id: g.id, name: g.name, rev: g.rev },
         issues: res.issues, stats: res.stats,
+        checks: res.ran, byCheck: res.byCheck,     // 跑过哪些类别 / 每类几条（0.10.0）
         errorCount, warningCount: res.issues.length - errorCount,
         members: cards.map(c => ({ id: c.id, name: c.name })),
         message: res.issues.length
@@ -2306,9 +2223,11 @@ function apply(ctx){
       if(!r.ok) return { ok:false, needGroup:true, cardId:r.cardId || null, groups:r.groups,
         message:"当前卡还没入库或没加入分组，而共享世界书是按组存放的 —— 先 cc_create_group / cc_set_card_group 把它归到一组。" };
       const g = r.group;
-      const found = await readBookRaw(g.id);
-      const cards = await bookCardsFor(await groupMemberIds(g.id));
-      const book = found ? normalizeBook(found.obj, g.id) : null;
+      // 0.10.0：书与成员都从卡组作用域取（一次读盘、形状唯一）—— 本工具不再自己 readBookRaw + normalizeBook。
+      const scope = await groupScope({ groupId: g.id, include: "summary" });
+      const cards = await bookCardsFor(scope.memberIds);   // scan 要比内容，需要完整条目
+      const book = (scope.book && scope.book.doc) ? scope.book.doc : null;
+      const found = !!book;
       // 把**书**一起交给 scan —— 否则「卡内条目与共享书逐字重复」这一类（`cc_apply_shared_book` 回填进卡的副本）
       // 谁都看不见：卡片之间没有重复、书里也没有重复，于是两个工具都说「没有重复」，而那几份副本就躺在卡里
       // 等着和共享书双重插入（第二轮报告 P1）。
@@ -2496,8 +2415,9 @@ function apply(ctx){
       // 是「卡内 character_book + 该组共享书」叠加，所以这里必须把共享书单列一行。
       const scope = await sharedBookScopeFor(ctx, exec);
       const shared = scope.entries;
-      const cardTokens = lorebookTokens(entries);
-      const sharedTokens = lorebookTokens(shared);
+      const metrics = lorebookMetrics(entries, shared);   // 0.10.0：token 口径走卡组层（数字与文案都不变）
+      const cardTokens = metrics.card.tokens;
+      const sharedTokens = metrics.shared.tokens;
       return { ok:true,
         bytes, tokens: estimateTokens(json),
         lorebookTokens: cardTokens + sharedTokens,
@@ -2561,7 +2481,7 @@ function apply(ctx){
       if(dimOnly.length) warnings.push(dimOnly.length + " 条条目的 keys 只有维度名（" + dimOnly.map(e=>String(e.name||"未命名")).join("、") + "），真实对话不会命中；可用 cc_simulate_trigger 拿一句用户会说的话验证，建议改成实体名");
       const keyless = entries.filter(e => { const keys=Array.isArray(e.keys)?e.keys:[]; return keys.length>0 && !e.constant && !keys.some(k => String(e.content||"").indexOf(String(k))>=0); });
       if(keyless.length) warnings.push(keyless.length + " 条条目的 keys 在自身 content 里找不到（可能是误填）：" + keyless.map(e=>String(e.name||"未命名")).join("、"));
-      const used = lorebookTokens(entries);
+      const used = wf.metrics.card.tokens;   // 0.10.0：数字来自卡组层（workflowStatus 里那一次统计）
       const budget = Number(book.token_budget||0) || 0;
       if(budget>0 && used > budget) warnings.push("世界书内容估算约 "+used+" token，已超出 token_budget="+budget+"，建议调大预算或精简条目（cc_patch_book_meta）");
       // —— 终态：校验通过后 next 不再指向 cc_validate（P0-3：那正是弱模型死循环的诱因）——
@@ -2579,7 +2499,8 @@ function apply(ctx){
         hint: progressHint(valid ? 7 : wf.step, wf.state, wf.worldFilled, wf.loreCount, wf.manualLoreCount, valid, wf.sharedLoreCount),
       });
       const warningsAll = [recoveredNotice(k, d)].filter(Boolean).concat(warnings);   // 新草稿提示同上，交给包装
-      const sharedUsed = (wf.sharedBook && Number(wf.sharedBook.tokens)) || 0;
+      // 同上：共享书那一段（wf.metrics 是 lorebookMetrics 的旧命名形状：card / shared / total / all）
+      const sharedUsed = wf.metrics.shared.tokens;
       return { ok:true, valid, done: valid, errors, warnings: warningsAll,
         loreCount: wf.loreCount, manualLoreCount: wf.manualLoreCount, name: d.data.name,
         // 世界书的两个口径都报出来（第二轮报告 P0）：卡内 / 共享 / 合计 —— `cc_lint_lorebook` 早就是这个口径了，
@@ -2688,22 +2609,17 @@ async function deleteBook(groupId){
   }
   return removed > 0;
 }
-/** 内容签名（折叠空白 + djb2 + 长度）：只用来**筛**，真正搬运/删除前一律再逐字比对内容。 */
-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;
-}
+/** 内容签名：见 lib/group-layer.js 的 `contentKeyOf()`（只用来筛，动手前一律再逐字比对内容）。 */
 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;
 }
@@ -2724,44 +2640,7 @@ 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;
-      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));
   const added = [];
@@ -3011,38 +2890,63 @@ async function applySharedBook(groupId, cardId, dryRun){
 }
 
 /**
- * 度量类工具的统一口径：世界设定现在有一部分活在**组级共享书**里，所以任何「这张卡有多少条 /
- * 多少 token」的统计都必须把它算上，并拆成 **卡内 / 共享 / 合计** 三段。
+ * 度量类工具的统一口径（0.10.0 起是 `groupScope()` 的薄包装，返回形状与 0.9.x 逐字一致）。
  *
- * 为什么单列一个函数：LLM 侧实测报告指出 —— 共享书改变了**数据的位置**，却没有改变工具的**度量口径**；
- * 四个「读」类工具（simulate / lint / group_check / preview_export）全都默认「卡内 character_book
- * 就是全部」，于是 simulate 把「会命中」判成「不会命中」（实测低估约 3 倍），lint 的 worstCase
- * 漏掉共享书里的 constant 条目，group_check 的群聊固定开销也只算了一半。
+ * 为什么当初单列一个函数：LLM 侧实测报告指出 —— 共享书改变了**数据的位置**，却没有改变工具的
+ * **度量口径**；四个「读」类工具（simulate / lint / group_check / preview_export）全都默认
+ * 「卡内 character_book 就是全部」，于是 simulate 把「会命中」判成「不会命中」（实测低估约 3 倍），
+ * lint 的 worstCase 漏掉共享书里的 constant 条目，group_check 的群聊固定开销也只算了一半。
+ * 现在「取作用域」只有 groupScope 一处、数字只有 groupMetrics 一处，这里只负责把书的字段摊平
+ * 成调用方熟悉的 `{ bookName, entries, tokens, constantTokens }`。
  *
  * 没有来源卡 / 没有分组 / 该组还没有书 → 一律返回空（调用方无需自己判空）。
  */
 async function sharedBookScopeFor(ctx, exec){
-  const k = keyFor(ctx, exec);
-  const origin = readOriginSync(k);
-  const cardId = (origin && origin.libraryId) ? String(origin.libraryId) : "";
-  const empty = { cardId, groupId: "", bookName: "", rev: 0, entries: [], tokens: 0, constantTokens: 0 };
-  if(!cardId) return empty;
-  const mine = (await listLibraryEntries()).find(e => e.id === cardId);
-  const gid = (mine && mine.groupId) ? String(mine.groupId) : "";
-  if(!gid) return empty;
-  const found = await readBookRaw(gid);
-  if(!found) return Object.assign({}, empty, { groupId: gid });
-  const book = normalizeBook(found.obj, gid);
-  const entries = book.data.entries.filter(e => e && e.enabled !== false);
+  const scope = await groupScope({ sessionKey: keyFor(ctx, exec) });
+  const cardId = scope.cardId || "";
+  const groupId = scope.groupId || "";
+  if(!scope.book) return { cardId: cardId, groupId: groupId, bookName: "", rev: 0, entries: [], tokens: 0, constantTokens: 0 };
+  const entries = scope.book.entries;
   return {
-    cardId, groupId: gid, bookName: book.data.name, rev: bookRevOf(book), entries,
+    cardId: cardId, groupId: groupId, bookName: scope.book.name, rev: scope.book.rev, entries: entries,
     tokens: lorebookTokens(entries),
     constantTokens: entries.filter(e => e.constant).reduce((n, e) => n + estimateTokens(e && e.content), 0),
-    lastPromote: (book.data.extensions && book.data.extensions.cc && book.data.extensions.cc.lastPromote) || null,
+    lastPromote: scope.book.lastPromote || null,
   };
 }
+/**
+ * 本卡所属分组的共享世界书**是否已经覆盖了这五个维度** —— 决定「没显式传 autoLorebook 时」还要不要在
+ * 卡内生成一份骨架副本。
+ *
+ * 为什么需要它（0.10.0 LLM 侧回归报告第三节，实测踩到）：`autoLorebook` 的默认值是**单卡时代**的 ——
+ * 那时「生成骨架条目」是净收益。共享书上线后它变成净损失：用户只想改五维里的一个字，结果整套骨架被
+ * 抄回卡里，正好抵消共享书的去重价值，还会立刻踩两条检查（卡内与书逐字重复 + 跨卡触发词冲突），
+ * 而且新副本的 keys 只有维度名 —— 等于把当初修好的「实体词 keys」又退回成死条目。
+ *
+ * 判据**取窄**（宁可漏判、不可误判）：只看书里明确是维度条目的那些 —— 名字就是维度名，或 keys 命中
+ * 维度名/英文维度名。真要卡内副本，显式传 `autoLorebook:true` 即可。
+ */
+async function sharedBookCoversDims(ctx, exec){
+  const out = { covered: false, count: 0, bookName: "", names: [] };
+  let scope = null;
+  try{ scope = await sharedBookScopeFor(ctx, exec); }catch(e){ return out; }
+  const entries = (scope && Array.isArray(scope.entries)) ? scope.entries : [];
+  if(!entries.length) return out;
+  const enKeys = WORLD_DIMS.map(d => DIM_EN[d]);
+  const hits = entries.filter(e => {
+    if(!e || e.enabled === false) return false;
+    if(AUTO_NAMES.has(String(e.name || "").trim())) return true;
+    const keys = (Array.isArray(e.keys) ? e.keys : []).map(k => String(k).trim().toLowerCase());
+    return keys.some(k => WORLD_DIMS.indexOf(k) >= 0 || enKeys.indexOf(k) >= 0);
+  });
+  if(!hits.length) return out;
+  return { covered: true, count: hits.length, bookName: String(scope.bookName || ""),
+    names: hits.map(e => String(e.name || "")).filter(Boolean).slice(0, 6) };
+}
 
 export { apply, inject, name, safeDraftFile, draftDirs, libDirs, dataRoots, originPath, readOriginSync, writeOriginSync,
+  // 卡组层（0.10.0）：卡库快照 + 卡组作用域 —— 卡组数据的唯一入口，两半共用 lib/group-layer.js 的纯组装
+  readLibrarySnapshot, groupScope,
   // 人物关系图谱（0.8.0）：导出纯函数与落盘根，供 tests/relations.test.mjs 与宿主半逐字比对同构实现
   groupDirs, groupDir, groupPath, safeGroupId, normalizeGroup, validateGroupOp, applyGroupOps,
   renderRelationsSection, spliceRelations, checkGroup, listGroups, readGroupRaw, writeGroup, groupMemberIds, libraryCardsFor,