@xia-sc/dsh-cc-studio 0.8.1 → 0.8.2

package/lib/agent.js

@@ -12,7 +12,7 @@ const name = "dsh-cc-studio-agent";
 // 由来：第五轮实测里测试者第一遍跑出「四项全无变化」，其实只是**没重启 dsh** —— LLM 侧完全无法
 // 分辨「代码没改」和「改了但没加载」。有了这个字段，任何一次调用都能先确认自己测的是哪一版。
 // 发版时与 package.json 的 version 同步。
-const BUILD = "0.8.1";
+const BUILD = "0.8.2";
 const inject = ["tools", "agents"];
 
 function nowSec(){ return Math.floor(Date.now()/1000); }
@@ -481,22 +481,33 @@ function applyGroupOps(group, ops){
   g.updatedAt = nowSec();
   return { group: g, applied, rejected };
 }
+/**
+ * 出边口径（渲染与 outgoing 计数**共用这一处**，避免「预览说 N 条、实际写出 M 条」）。
+ * mutual（对等）边是双向的：不管它从哪一端写的，两端都该看到它 —— 所以「指向我的 mutual 边」
+ * 也算我的出边。⚠️ 曾经 outgoing 只认 `from === myNodeId`，而 incoming 又显式排除 mutual，
+ * 于是 mutual 边**两头都不落**、渲染时被静默丢弃（做的「对等关系」在导出的卡里彻底消失）。
+ */
+function outgoingEdgesOf(myNodeId, edges){
+  return (Array.isArray(edges) ? edges : []).filter(e => e.from === myNodeId || (e.direction === "mutual" && e.to === myNodeId));
+}
 function renderRelationsSection(myNodeId, nodes, edges, opts){
   const o = opts || {};
   const byId = new Map((Array.isArray(nodes) ? nodes : []).map(n => [n.id, n]));
   const nameOf = (id) => { const n = byId.get(id); return n ? (n.name || "未命名") : "（未知）"; };
   const all = (Array.isArray(edges) ? edges : []).filter(e => byId.has(e.from) && byId.has(e.to));
-  const outgoing = all.filter(e => e.from === myNodeId);
+  const outgoing = outgoingEdgesOf(myNodeId, all);
+  // incoming 仍排除 mutual：同一条对等关系不必在两节各说一遍（出边那节已带「，互向」标记）
   const incoming = all.filter(e => e.to === myNodeId && e.direction !== "mutual");
+  const otherOf = (e) => (e.from === myNodeId ? e.to : e.from);   // mutual 边可能是反向写着的，对方在 from 端
   const order = (t) => { const i = REL_TYPES.indexOf(t); return i < 0 ? REL_TYPES.length : i; };
   const fmt = (e, otherId) => "- " + nameOf(otherId) + "（" + relLabel(e) + "｜" + e.strength + "/5" + (e.direction === "mutual" ? "，互向" : "") + "）" + (e.note ? "：" + e.note : "");
-  const byTypeThenStrength = (other) => (a, b) => (order(a.type) - order(b.type)) || (b.strength - a.strength) || nameOf(a[other]).localeCompare(nameOf(b[other]));
+  const byTypeThenStrength = (other) => (a, b) => (order(a.type) - order(b.type)) || (b.strength - a.strength) || nameOf(other(a)).localeCompare(nameOf(other(b)));
   const lines = ["【关系】"];
   if(!outgoing.length) lines.push("- （暂无）");
-  else outgoing.slice().sort(byTypeThenStrength("to")).forEach(e => lines.push(fmt(e, e.to)));
+  else outgoing.slice().sort(byTypeThenStrength(otherOf)).forEach(e => lines.push(fmt(e, otherOf(e))));
   if(o.includeIncoming && incoming.length){
     lines.push("", "【他们眼中的我】");
-    incoming.slice().sort(byTypeThenStrength("from")).forEach(e => lines.push(fmt(e, e.from)));
+    incoming.slice().sort(byTypeThenStrength(e => e.from)).forEach(e => lines.push(fmt(e, e.from)));
   }
   return lines.join("\n");
 }
@@ -634,6 +645,83 @@ async function resolveGroupFor(ctx, exec, explicitGroupId){
   return { ok: true, cardId, groupId, group: g, myNode, groups };
 }
 
+// —— 0.8.0：分组的增删改查（LLM 侧）——
+// 此前 LLM 只能读写**组内图谱**，改不了「哪张卡属于哪个组」：卡一旦因任何原因掉组，
+// 模型既救不回来也建不了新组（只能干等用户点界面），而真正高频使用这套工具的恰恰是模型。
+// 这四个函数就是那几个工具的实现，落盘规则与宿主半的 cc_createGroup / cc_renameGroup /
+// cc_deleteGroup / cc_setCardGroup 逐条对齐（同一份 cc-groups 目录、同一份库条目 meta.groupId）。
+
+/** 按名字找组（建组/改名时查重）：trim 后精确比对；带 exceptId 时排除自己（给自己改名不算撞车）。 */
+function findGroupByName(groups, name, exceptId){
+  const want = String(name || "").trim();
+  if(!want) return null;
+  const eid = exceptId ? safeGroupId(exceptId) : "";
+  return (Array.isArray(groups) ? groups : []).find(g => g.id !== eid && String(g.name || "").trim() === want) || null;
+}
+/** 每个组一行摘要：成员数由库条目 meta.groupId **派生**（与 groupMemberIds 同一套口径）。 */
+async function groupSummaries(){
+  const groups = await listGroups();
+  const entries = await listLibraryEntries();
+  const countOf = (gid) => entries.filter(e => String(e.groupId || "") === gid).length;
+  return groups.map(g => ({
+    id: g.id, name: g.name, note: g.note,
+    nodeCount: g.nodes.length, edgeCount: g.edges.length,
+    memberCount: countOf(g.id), rev: g.rev, updatedAt: g.updatedAt,
+  }));
+}
+/**
+ * 把一张已存卡放进分组（groupId 传空 = 移出）。入组时若组里还没有它的节点就自动补一个 ——
+ * 调用方只需要表达「把这张卡放进这个组」，不必先手工建节点。
+ * 移出**不删节点、不删关系**：那是用户建过的资产，挪回来时关系还在（与「删卡降级 orphan、保留边」同一原则）。
+ */
+async function assignCardToGroup(cardId, groupId){
+  const cid = String(cardId || "");
+  if(!cid) throw new Error("需要 cardId");
+  const entries = await listLibraryEntries();
+  const mine = entries.find(e => e.id === cid);
+  if(!mine) throw Object.assign(new Error("找不到角色卡: " + cid), { code: "ENOENT" });
+  const gid = (groupId === null || groupId === undefined || groupId === "") ? "" : safeGroupId(groupId);
+  if(!gid){
+    await patchLibraryMeta(cid, { groupId: null });
+    return { cardId: cid, cardName: mine.name, previousGroupId: (mine.groupId ? String(mine.groupId) : null), groupId: null, nodeId: null };
+  }
+  const found = await readGroupRaw(gid);
+  if(!found) throw Object.assign(new Error("分组不存在: " + gid), { code: "not-found" });
+  const g = normalizeGroup(found.obj);
+  let node = g.nodes.find(n => n.kind === "card" && n.cardId === cid);
+  let revived = false;
+  if(!node){
+    // 卡曾经被删（节点被 orphanCardNodes 降级成 orphan）后又同名回来时**复活那个节点**，
+    // 让它原来的关系继续有效；否则会新建第二个同名节点 —— 体检立刻报 duplicate-name，
+    // 而旧节点上挂着的那些关系永远悬空（关系是用户资产，不该被一次误删永久切断）。
+    node = g.nodes.find(n => n.kind === "card" && !n.cardId && n.orphanOf && n.orphanOf === String(mine.name || ""));
+    if(node){ node.cardId = cid; node.orphanOf = null; revived = true; }
+  }
+  if(!node){
+    node = { id: "n" + (g.nextNodeSeq++), kind: "card", cardId: cid, name: mine.name || "未命名角色", aliases: [], orphanOf: null };
+    g.nodes.push(node);
+    await writeGroup(g);
+  } else if(revived){
+    await writeGroup(g);
+  }
+  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 };
+}
+/** 删组：组文件（节点 + 关系）不可恢复；成员卡**不删**，只清掉它们指向该组的 meta.groupId。组不存在返回 null。 */
+async function deleteGroupWithMembers(groupId){
+  const gid = safeGroupId(groupId);
+  const found = await readGroupRaw(gid);
+  if(!found) return null;
+  const g = normalizeGroup(found.obj);
+  const members = await groupMemberIds(gid);
+  await unlink(groupPath(gid));
+  let memberCleared = 0;
+  for(const id of members){
+    try{ await patchLibraryMeta(id, { groupId: null }); memberCleared += 1; }catch{}
+  }
+  return { deleted: { id: g.id, name: g.name, nodeCount: g.nodes.length, edgeCount: g.edges.length }, memberCleared };
+}
+
 // —— 已存角色库：<主根>/cc-library/<id>.json（读盘回退 0.3.6 之前的 homedir()/.dsh）——
 function libDirs(){ return dataRoots("cc-library"); }
 function libDir(){ return libDirs()[0]; }
@@ -663,6 +751,12 @@ function makeLibraryEntryMeta(draft, existingMeta, id){
     name:(data.name && String(data.name).trim()) || (existingMeta && existingMeta.name) || "未命名角色",
     loreCount, tags, tagsTotal: allTags.length,
     descriptionSnippet:String(data.description||"").slice(0,80),
+    // 0.8.0 关系图谱：卡属于哪个分组（**单一真源** —— 分组文件里不存成员列表，避免双写漂移）。
+    // 继承既有值，所以「改卡内容再保存」不会把卡踢出分组。
+    // ⚠️ 这一行曾经**只有宿主半有**：工具半重建 meta 时把 groupId 抹掉，表现为「LLM 侧保存一次，
+    // 卡就静默退组」（返回仍是 action:"updated"，零提示），而关系工具在卡退组后全部拒绝服务。
+    // 两半的 makeLibraryEntryMeta 必须逐字同构 —— 加字段时两边一起加（tests/relations.test.mjs 钉住）。
+    groupId: (existingMeta && existingMeta.groupId) ? String(existingMeta.groupId) : null,
     createdAt: existingMeta && existingMeta.createdAt ? existingMeta.createdAt : now,
     updatedAt: now,
   };
@@ -740,6 +834,16 @@ async function renameLibraryEntry(id,newName){
   await writeFile(found.path, JSON.stringify(obj,null,2), "utf8");
   return obj.meta;
 }
+/** 0.8.0：就地改某个库条目的 meta（写在解析到的那一份上，与 renameLibraryEntry 同规，不搬家）。与 lib/index.js 同构。 */
+async function patchLibraryMeta(id,patch){
+  const found=await readLibraryRaw(id);
+  const obj=JSON.parse(found.raw);
+  if(!obj || !obj.meta) throw new Error("文件格式错误");
+  Object.assign(obj.meta, patch||{});
+  obj.meta.updatedAt=nowSec();
+  await writeFile(found.path, JSON.stringify(obj,null,2), "utf8");
+  return obj;
+}
 
 function out(schema){ return { schema, render: (args, result) => [{ type:"text", text: JSON.stringify(result, null, 2) }] }; }
 
@@ -1745,7 +1849,9 @@ function apply(ctx){
       const before = String((cur.data && cur.data.description) || "");
       const after = spliceRelations(before, section, "rev=" + g.rev + " group=" + g.id);
       const changed = before !== after;
-      const outgoing = g.edges.filter(e => e.from === r.myNode.id).length;
+      // 计数必须与渲染**同一口径**（outgoingEdgesOf 含「指向我的 mutual 边」），否则会出现
+      // 「预览说 1 条、实际写出 2 条」这种对不上账的返回。
+      const outgoing = outgoingEdgesOf(r.myNode.id, g.edges).length;
       if(args.dryRun === true){
         return { ok:true, dryRun:true, changed, outgoing, section, preview: after,
           group: { id: g.id, name: g.name, rev: g.rev },
@@ -1795,6 +1901,363 @@ function apply(ctx){
     }
   });
 
+  // ———————————————— 分组管理（0.8.0 补：LLM 侧的增删改查）————————————————
+  // 此前 LLM 只能读写**组内图谱**，却改不了「哪张卡属于哪个组」：卡一旦掉组，模型既救不回来、
+  // 也建不了新组，只能干等用户点界面 —— 而真正高频使用这套工具的恰恰是模型（用户自己说的）。
+  // 四个动作（查/增/改/删）+ 一个归位，落盘规则与宿主半的 cc_listGroups / cc_createGroup /
+  // cc_renameGroup / cc_deleteGroup / cc_setCardGroup 逐条对齐。
+
+  tool({
+    name: "cc_list_groups",
+    description: "【分组·查】列出全部人物关系分组：每组有多少成员卡 / 节点 / 关系，以及**当前卡在哪一组**。改某张卡的分组用 cc_set_card_group；建组 / 改名 / 删组用 cc_create_group / cc_rename_group / cc_delete_group。",
+    parameters: {
+      type:"object",
+      properties:{ includeCards:{ type:"boolean", description:"是否额外列出未分组的卡（默认 true，最多 20 张）" } },
+      additionalProperties:false
+    },
+    output: out({ type:"object", additionalProperties:true }),
+    async execute(args, exec){
+      const k = keyFor(ctx, exec);
+      const origin = readOriginSync(k);
+      const cardId = (origin && origin.libraryId) ? String(origin.libraryId) : "";
+      const entries = await listLibraryEntries();
+      const mine = cardId ? (entries.find(e => e.id === cardId) || null) : null;
+      const groups = await groupSummaries();
+      const ungrouped = entries.filter(e => !String(e.groupId || ""));
+      const myGroupId = (mine && mine.groupId) ? String(mine.groupId) : null;
+      const myGroup = myGroupId ? (groups.find(g => g.id === myGroupId) || null) : null;
+      const res = {
+        ok:true,
+        groups: groups.map(g => Object.assign({}, g, { isMine: g.id === myGroupId })),
+        groupCount: groups.length, cardCount: entries.length, ungroupedCount: ungrouped.length,
+        cardId: cardId || null, cardName: mine ? mine.name : "", groupId: myGroupId,
+        message: groups.length
+          ? "共 " + groups.length + " 个分组、库里 " + entries.length + " 张卡（" + ungrouped.length + " 张未分组）"
+            + (mine
+              ? "；当前卡「" + mine.name + "」" + (myGroup
+                ? "在分组「" + myGroup.name + "」里"
+                : (myGroupId ? "的 groupId 指向一个已不存在的分组（" + myGroupId + "），建议用 cc_set_card_group 重新归位" : "还没有加入分组"))
+              : "")
+            + "。"
+          : "还没有任何分组" + (entries.length ? "（库里有 " + entries.length + " 张卡）" : "") + "：用 cc_create_group 建一个，再用 cc_set_card_group 把卡放进去。",
+      };
+      if(args.includeCards !== false) res.ungroupedCards = ungrouped.slice(0, 20).map(e => ({ id: e.id, name: e.name }));
+      return res;
+    }
+  });
+
+  tool({
+    name: "cc_create_group",
+    description: "【分组·增】新建一个人物关系分组（群聊 / 同一世界观的一批卡放一起）。分组是插件侧数据、不会自动进卡 —— 关系要进卡请再调 cc_render_relations。同名分组已存在时**默认拒绝**并回已有 id（避免出现两个同名组）；确实要重名再传 allowDuplicate:true。",
+    parameters: {
+      type:"object",
+      properties:{
+        name:{ type:"string", description:"分组名（≤60 字）" },
+        note:{ type:"string", description:"可选备注（≤200 字）" },
+        allowDuplicate:{ type:"boolean", description:"默认 false：同名分组已存在则拒绝并告知 existingGroupId" },
+      },
+      required:["name"],
+      additionalProperties:false
+    },
+    output: out({ type:"object", additionalProperties:true }),
+    async execute(args){
+      const name = String(args.name || "").trim().slice(0, 60);
+      if(!name) return { ok:false, error:"分组名不能为空" };
+      const dup = findGroupByName(await listGroups(), name, "");
+      if(dup && args.allowDuplicate !== true){
+        return { ok:false, duplicate:true, existingGroupId: dup.id, groups: await groupSummaries(),
+          message:"已有同名分组「" + dup.name + "」（id " + dup.id + "）—— 直接把卡放进去就行：cc_set_card_group({groupId:\"" + dup.id + "\"})；确实要另建一个同名的再传 allowDuplicate:true。" };
+      }
+      const g = await writeGroup({ id: newGroupId(), name, note: String(args.note || "").slice(0, 200), nodes: [], edges: [] });
+      return { ok:true, group: { id:g.id, name:g.name, note:g.note, rev:g.rev },
+        groups: await groupSummaries(),
+        message:"已建分组「" + g.name + "」（id " + g.id + "）。用 cc_set_card_group 把卡放进去，再用 cc_patch_relations 在组内建关系。" };
+    }
+  });
+
+  tool({
+    name: "cc_rename_group",
+    description: "【分组·改】改分组名或备注（至少传一个）。只改分组本身，不动成员卡与关系；改成与别的分组同名时默认拒绝，除非 allowDuplicate:true。",
+    parameters: {
+      type:"object",
+      properties:{
+        groupId:{ type:"string", description:"分组 id（见 cc_list_groups）" },
+        name:{ type:"string", description:"新分组名（≤60 字）" },
+        note:{ type:"string", description:"新备注（≤200 字；空串 = 清空备注）" },
+        allowDuplicate:{ type:"boolean", description:"默认 false：与别的分组撞名则拒绝" },
+      },
+      required:["groupId"],
+      additionalProperties:false
+    },
+    output: out({ type:"object", additionalProperties:true }),
+    async execute(args){
+      const gid = safeGroupId(args.groupId);
+      const found = await readGroupRaw(gid);
+      if(!found) return { ok:false, notFound:true, groups: await groupSummaries(), message:"分组不存在：" + String(args.groupId) + " —— 先 cc_list_groups 看现有分组。" };
+      const g = normalizeGroup(found.obj);
+      const wantName = (typeof args.name === "string" && args.name.trim()) ? args.name.trim().slice(0, 60) : "";
+      const wantNote = (typeof args.note === "string") ? args.note.slice(0, 200) : null;
+      if(!wantName && wantNote === null) return { ok:false, error:"至少传 name 或 note 之一" };
+      if(wantName){
+        const dup = findGroupByName(await listGroups(), wantName, gid);
+        if(dup && args.allowDuplicate !== true){
+          return { ok:false, duplicate:true, existingGroupId: dup.id, groups: await groupSummaries(),
+            message:"已有同名分组「" + dup.name + "」（id " + dup.id + "）—— 换个名字，或确实要重名再传 allowDuplicate:true。" };
+        }
+      }
+      const changed = [];
+      if(wantName && wantName !== g.name){ changed.push("name"); g.name = wantName; }
+      if(wantNote !== null && wantNote !== g.note){ changed.push("note"); g.note = wantNote; }
+      // 无实际改动不写盘：同 N4 家规（空改动不该白涨 rev，否则别人手上的 rev 前提会被无变化打掉）
+      if(!changed.length) return { ok:true, changed:[], group:{ id:g.id, name:g.name, note:g.note, rev:g.rev }, message:"分组「" + g.name + "」的名字与备注本来就是这两样，没有改动。" };
+      const saved = await writeGroup(g);
+      return { ok:true, changed, group:{ id:saved.id, name:saved.name, note:saved.note, rev:saved.rev },
+        groups: await groupSummaries(),
+        message:"已改分组「" + saved.name + "」的 " + changed.join(" / ") + "（rev=" + saved.rev + "）。" };
+    }
+  });
+
+  tool({
+    name: "cc_delete_group",
+    description: "【分组·删·破坏性】删除一个人物关系分组：**组里的节点与关系会一起消失且不可恢复**；成员卡本身不会被删，只是离开这个组。默认必须带 confirm:true 才真的执行 —— 第一次调用只回该组有多少节点/关系，供你先与用户确认。",
+    parameters: {
+      type:"object",
+      properties:{
+        groupId:{ type:"string", description:"分组 id（见 cc_list_groups）" },
+        confirm:{ type:"boolean", description:"必须显式传 true 才执行删除" },
+      },
+      required:["groupId"],
+      additionalProperties:false
+    },
+    output: out({ type:"object", additionalProperties:true }),
+    async execute(args){
+      const gid = safeGroupId(args.groupId);
+      const found = await readGroupRaw(gid);
+      if(!found) return { ok:false, notFound:true, groups: await groupSummaries(), message:"分组不存在：" + String(args.groupId) + " —— 先 cc_list_groups 看现有分组。" };
+      const g = normalizeGroup(found.obj);
+      const members = await groupMemberIds(gid);
+      if(args.confirm !== true){
+        return { ok:false, needConfirm:true,
+          group: { id:g.id, name:g.name, nodeCount:g.nodes.length, edgeCount:g.edges.length, memberCount:members.length },
+          message:"「" + g.name + "」里有 " + g.nodes.length + " 个节点 / " + g.edges.length + " 条关系，删组会一起删掉且不可恢复；" + members.length + " 张成员卡不会被删，只会离开这个组。与用户确认后重调并带 confirm:true。" };
+      }
+      const del = await deleteGroupWithMembers(gid);
+      const bookDeleted = await deleteBook(gid);   // 0.9.0：组级共享世界书随组一起删（留下就是孤儿文件）
+      return { ok:true, deleted: del.deleted, memberCleared: del.memberCleared, bookDeleted,
+        groups: await groupSummaries(),
+        message:"已删除分组「" + del.deleted.name + "」（连同 " + del.deleted.nodeCount + " 个节点 / " + del.deleted.edgeCount + " 条关系）；" + del.memberCleared + " 张成员卡已移出分组，卡本身没删。"
+          + (bookDeleted ? "该组的共享世界书也一并删除了。" : "") };
+    }
+  });
+
+  tool({
+    name: "cc_set_card_group",
+    description: "【分组·归位】把一张已存卡放进分组 / 换组 / 移出。**不传 groupId（或传 null / 空串）= 移出分组**。cardId 省略时用**当前草稿的来源卡**（你正在做的那张）。入组时若组里还没有它的节点会自动补一个；移出**不删节点与关系**（以后放回来关系还在）。卡因任何原因掉了组，也用它自救。",
+    parameters: {
+      type:"object",
+      properties:{
+        groupId:{ type:"string", description:"目标分组 id（见 cc_list_groups）。**不传 / null / 空串 = 移出分组**" },
+        cardId:{ type:"string", description:"可选：要归位的已存卡 id（见 cc_list_library）；默认用当前草稿的来源卡" },
+      },
+      additionalProperties:false
+    },
+    output: out({ type:"object", additionalProperties:true }),
+    async execute(args, exec){
+      const entries = await listLibraryEntries();
+      const k = keyFor(ctx, exec);
+      const origin = readOriginSync(k);
+      const fromOrigin = (origin && origin.libraryId) ? String(origin.libraryId) : "";
+      const cardId = (typeof args.cardId === "string" && args.cardId.trim()) ? args.cardId.trim() : fromOrigin;
+      if(!cardId){
+        const ungrouped = entries.filter(e => !String(e.groupId || ""));
+        return { ok:false, needCardId:true, cardId:null,
+          groups: await groupSummaries(),
+          cards: entries.slice(0, 20).map(e => ({ id:e.id, name:e.name, groupId: e.groupId ? String(e.groupId) : null })),
+          message:"当前草稿还没入库（没有来源卡 id），不知道要归位哪张卡：先用 cc_save_to_library 落库，或从 cc_list_library 拿到 id 后带上 cardId 重调。"
+            + (ungrouped.length ? " 库里现在有 " + ungrouped.length + " 张未分组的卡。" : "") };
+      }
+      let r;
+      try{ r = await assignCardToGroup(cardId, (args.groupId === null || args.groupId === undefined) ? null : String(args.groupId)); }
+      catch(e){
+        const code = e && e.code;
+        if(code === "ENOENT") return { ok:false, notFound:true, cardId, cards: entries.slice(0, 20).map(x => ({ id:x.id, name:x.name })),
+          message:"库里找不到这张卡：" + cardId + "（可能已被删除）—— 卡 id 见 cc_list_library。" };
+        if(code === "not-found") return { ok:false, notFound:true, groupId: String(args.groupId), groups: await groupSummaries(),
+          message:"分组不存在：" + String(args.groupId) + " —— 先 cc_create_group 建组，或 cc_list_groups 看现有 id。" };
+        throw e;
+      }
+      const groups = await groupSummaries();
+      const g = r.groupId ? (groups.find(x => x.id === r.groupId) || null) : null;
+      return { ok:true,
+        cardId: r.cardId, cardName: r.cardName,
+        groupId: r.groupId, group: g ? { id:g.id, name:g.name, rev:g.rev, memberCount:g.memberCount } : null,
+        previousGroupId: r.previousGroupId, nodeId: r.nodeId || null, revived: r.revived === true,
+        groups,
+        message: r.groupId
+          ? "已把「" + r.cardName + "」放进分组「" + (g ? g.name : r.groupId) + "」"
+            + (r.previousGroupId && r.previousGroupId !== r.groupId ? "（从分组 " + r.previousGroupId + " 换过来的）" : "")
+            + "，这组现在有 " + (g ? g.memberCount : "?") + " 张成员卡。关系用 cc_patch_relations 改，写完用 cc_render_relations 进卡。"
+          : "已把「" + r.cardName + "」移出分组"
+            + (r.previousGroupId ? "（原来在分组 " + r.previousGroupId + "）" : "")
+            + "。组里的节点与关系**保留**了 —— 之后放回去，关系还在。" };
+    }
+  });
+
+  // ———————————————— 组级共享世界书（0.9.0）————————————————
+  // 一组一份：世界设定（年表/势力/地理/力量/日常）提到共享书，成员卡里只留角色私有条目。
+  // 导出后是 CCv3 官方 lorebook_v3 JSON，在客户端里绑成全局世界书即可，多卡共用、零重复。
+
+  tool({
+    name: "cc_get_shared_book",
+    description: "【共享书·查】读当前（或指定）分组的**组级共享世界书**（一组一份、整组共用），并报出「成员卡之间有多少条重复条目」—— 那些就是该提升到共享书的。共享书是独立文件（CCv3 官方 lorebook_v3 格式），导出后可在客户端里绑成全局世界书，于是每张成员卡里不必再存这些设定。",
+    parameters: {
+      type:"object",
+      properties:{
+        groupId:{ type:"string", description:"可选：默认用当前卡所属分组" },
+        includeContent:{ type:"boolean", description:"true = 连条目全文一起回（默认只回 name/keys/长度/前 80 字，省上下文）" },
+      },
+      additionalProperties:false
+    },
+    output: out({ type:"object", additionalProperties:true }),
+    async execute(args, exec){
+      const r = await resolveGroupFor(ctx, exec, args.groupId);
+      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 scan = scanSharedEntries(cards);
+      const duplicates = scan.candidates.map(c => ({ signature: c.signature, name: c.name, cardNames: c.cardNames,
+        chars: c.chars, savedChars: c.savedChars, nameMismatch: c.nameMismatch, keysMismatch: c.keysMismatch, preview: c.preview }));
+      const base = { ok:true, group:{ id:g.id, name:g.name, rev:g.rev }, exists: !!found,
+        bookRev: found ? bookRevOf(normalizeBook(found.obj, g.id)) : 0,
+        cards: cards.map(c => ({ id:c.id, name:c.name, entries:(c.entries||[]).length })),
+        duplicates, duplicateStats: scan.stats };
+      if(!found){
+        return Object.assign(base, { message: "分组「" + g.name + "」还没有共享世界书。"
+          + (scan.candidates.length
+            ? "成员卡之间有 " + scan.candidates.length + " 条内容重复的条目（合计可省约 " + scan.stats.savedChars + " 字符）—— 用 cc_promote_shared_entries 提升到共享书，再从各卡里删掉。"
+            : "成员卡之间也没有内容重复的条目。") });
+      }
+      const book = normalizeBook(found.obj, g.id);
+      const tokens = estimateTokens(book.data.entries.map(e => e.content).join("\n"));
+      return Object.assign(base, {
+        book: bookBrief(book, args.includeContent === true), tokens,
+        message: "共享世界书「" + book.data.name + "」共 " + book.data.entries.length + " 条（rev " + bookRevOf(book) + "，约 " + tokens + " token"
+          + "，预算 " + book.data.token_budget + "）；分组里有 " + cards.length + " 张成员卡"
+          + (scan.candidates.length ? "，其中仍有 " + scan.candidates.length + " 条内容重复（可用 cc_promote_shared_entries 收进共享书）" : "，卡片间已无重复条目") + "。" });
+    }
+  });
+
+  tool({
+    name: "cc_patch_shared_book",
+    description: "【共享书·改】增删改组级共享世界书的条目与书级参数。ops：{op:\"addEntry\",entry:{keys,content,name?,constant?,insertion_order?,use_regex?,...}} / {op:\"updateEntry\",contentKey,patch:{…}} / {op:\"removeEntry\",contentKey}（contentKey 由 cc_get_shared_book 给出）。书级参数直接传 name / description / scan_depth / token_budget / recursive_scanning。条目字段与卡内 character_book 条目**完全同构**（改完可以原样搬回卡里）。只改共享书本身 —— 成员卡里已有的旧副本要用 cc_promote_shared_entries 清掉。",
+    parameters: {
+      type:"object",
+      properties:{
+        groupId:{ type:"string", description:"可选：默认用当前卡所属分组" },
+        name:{ type:"string", description:"书级：书名" },
+        description:{ type:"string", description:"书级：备注" },
+        scan_depth:{ type:"number", description:"书级：扫描深度" },
+        token_budget:{ type:"number", description:"书级：token 预算" },
+        recursive_scanning:{ type:"boolean", description:"书级：递归扫描" },
+        ops:{ type:"array", items:{ type:"object", additionalProperties:true }, description:"条目动作数组" },
+        expectedBookRev:{ type:"number", description:"可选乐观锁：传上次 cc_get_shared_book 的 bookRev（与 expectedRev / expectedGroupRev 都不同：那是草稿 / 图谱的版本）" },
+      },
+      additionalProperties:false
+    },
+    output: out({ type:"object", additionalProperties:true }),
+    async execute(args, exec){
+      const r = await resolveGroupFor(ctx, exec, args.groupId);
+      if(!r.ok) return { ok:false, needGroup:true, cardId:r.cardId || null, groups:r.groups,
+        message:"当前卡还没入库或没加入分组，共享世界书无处可放 —— 先把它归到一组。" };
+      const res = await patchSharedBook(r.group.id, args);
+      if(!res.ok){
+        return { ok:false, staleRev: res.staleRev === true,
+          expectedBookRev: res.expectedBookRev == null ? null : res.expectedBookRev,
+          actualBookRev: res.actualBookRev == null ? null : res.actualBookRev,
+          error: String(res.error || "") };
+      }
+      const entries = res.book.data.entries.length;
+      return { ok:true, changed: res.changed, applied: res.applied, rejected: res.rejected,
+        bookRev: res.rev, group:{ id:r.group.id, name:r.group.name },
+        book: { name: res.book.data.name, entries, tokens: estimateTokens(res.book.data.entries.map(e => e.content).join("\n")) },
+        message: res.changed
+          ? "已改共享世界书（rev " + res.rev + "，共 " + entries + " 条）" + (res.rejected.length ? "；" + res.rejected.length + " 项被拒：" + res.rejected.map(x => x.error).join("；") : "")
+            + "。注意：成员卡里如果还留着这些条目的旧副本，用 cc_promote_shared_entries 清掉才不会重复。"
+          : "没有任何改动（" + (res.rejected.length ? res.rejected.map(x => x.error).join("；") : "ops 为空且没有书级参数") + "）。" };
+    }
+  });
+
+  tool({
+    name: "cc_promote_shared_entries",
+    description: "【共享书·去重】把成员卡里**内容重复的条目**提升进共享世界书，并从每一张出现过它的卡里删掉 —— 这就是「群聊卡世界书重复」的正解。**默认只回预览（dryRun）**，要真动手必须传 apply:true。不带 keys 时处理扫描出的全部候选；也可只传其中几个 signature。执行前会逐字比对内容（签名只用来筛，绝不按哈希删数据）。",
+    parameters: {
+      type:"object",
+      properties:{
+        groupId:{ type:"string", description:"可选：默认用当前卡所属分组" },
+        keys:{ type:"array", items:{ type:"string" }, description:"可选：只处理这些 signature（来自 cc_get_shared_book 的 duplicates）" },
+        apply:{ type:"boolean", description:"必须显式 true 才真的写盘（要从多张卡里删条目）" },
+      },
+      additionalProperties:false
+    },
+    output: out({ type:"object", additionalProperties:true }),
+    async execute(args, exec){
+      const r = await resolveGroupFor(ctx, exec, args.groupId);
+      if(!r.ok) return { ok:false, needGroup:true, cardId:r.cardId || null, groups:r.groups,
+        message:"当前卡还没入库或没加入分组，共享世界书按组存放 —— 先把它归到一组。" };
+      const res = await promoteSharedBook(r.group.id, args);
+      if(!res.ok) return { ok:false, error: String(res.error || "") };
+      if(res.dryRun){
+        return { ok:true, dryRun:true, wouldPromote: res.wouldPromote, unknownKeys: res.unknownKeys,
+          removedTotal: res.removedTotal, perCard: res.perCard, duplicates: res.candidates, stats: res.stats,
+          group:{ id:r.group.id, name:r.group.name }, bookRev: res.rev,
+          message: res.wouldPromote
+            ? "预览：将把 " + res.wouldPromote + " 条提升进共享世界书，并从成员卡里共删掉 " + res.removedTotal + " 条重复（可省约 " + res.stats.savedChars + " 字符）。确认后带 apply:true 重调。"
+            : "没有可提升的重复条目" + (res.unknownKeys.length ? "（" + res.unknownKeys.length + " 个 signature 不认识，已忽略）" : "") + "。" };
+      }
+      return { ok:true, dryRun:false, promoted: res.promoted, removedTotal: res.removedTotal, unknownKeys: res.unknownKeys,
+        bookRev: res.bookRev, bookEntries: res.bookEntries, perCard: res.perCard, stats: res.stats,
+        group:{ id:r.group.id, name:r.group.name },
+        message: "已把 " + res.promoted + " 条设定提升进共享世界书（rev " + res.bookRev + "，共 " + res.bookEntries + " 条），并从成员卡里删掉 " + res.removedTotal + " 条重复："
+          + res.perCard.map(c => c.name + " -" + (c.removed || 0)).join("、")
+          + "。导出时记得一并给客户端配这本共享世界书（工坊导出页可导出独立 JSON）。" };
+    }
+  });
+
+  tool({
+    name: "cc_apply_shared_book",
+    description: "【共享书·回填】把共享世界书的条目**合并进当前卡**（或指定 cardId）的 character_book —— 给那些不支持全局世界书的客户端兜底。同内容已存在会跳过，所以重复调用安全。dryRun:true 只回预览。默认不合并：先导出独立文件、在客户端里绑全局世界书，才是零重复的做法。",
+    parameters: {
+      type:"object",
+      properties:{
+        groupId:{ type:"string", description:"可选：默认用当前卡所属分组" },
+        cardId:{ type:"string", description:"可选：默认用当前草稿的来源卡" },
+        dryRun:{ type:"boolean", description:"true = 只回会加几条，不改卡" },
+      },
+      additionalProperties:false
+    },
+    output: out({ type:"object", additionalProperties:true }),
+    async execute(args, exec){
+      const r = await resolveGroupFor(ctx, exec, args.groupId);
+      if(!r.ok) return { ok:false, needGroup:true, cardId:r.cardId || null, groups:r.groups,
+        message:"当前卡还没入库或没加入分组，没有可回填的共享世界书。" };
+      const k = keyFor(ctx, exec);
+      const origin = readOriginSync(k);
+      const cardId = args.cardId ? String(args.cardId) : ((origin && origin.libraryId) ? String(origin.libraryId) : "");
+      const res = await applySharedBook(r.group.id, cardId, args.dryRun === true);
+      if(!res.ok) return { ok:false, needCard: res.needCard === true, notFound: res.notFound === true, error: String(res.error || "") };
+      if(res.dryRun){
+        return { ok:true, dryRun:true, cardId: res.cardId, wouldAdd: res.wouldAdd, bookEntries: res.bookEntries, cardEntries: res.cardEntries,
+          message: "预览：这张卡会新增 " + res.wouldAdd + " 条来自共享世界书的条目（现有 " + res.cardEntries + " 条）。" };
+      }
+      return { ok:true, cardId: res.cardId, added: res.added, changed: res.changed === true, loreCount: res.loreCount,
+        message: res.added
+          ? "已把这本共享世界书的 " + res.added + " 条合并进这张卡（现在 " + res.loreCount + " 条）。这只改了**库里的卡**；若你正在编辑草稿，记得重新载入或让用户在工坊里载入这张卡。"
+          : "这张卡已经包含共享世界书里的全部条目，没有需要补充的。" };
+    }
+  });
+
   // 【导出干跑】补上「五维到底导不导出」这个此前没人能回答的问题
   tool({
     name: "cc_preview_export",
@@ -1893,8 +2356,296 @@ function apply(ctx){
   });
 }
 
+// ——————————————————————————————————————————————————————————————
+// 组级共享世界书（0.9.0）—— 与 lib/index.js **同构实现**（同样的常量、纯函数、落盘规则）。
+// 理由见宿主半那段注释：群聊卡的世界设定在每张成员卡里逐字重复（实测 4 卡 20 条里 5 条相同），
+// CCv3 规范允许 Lorebook 单独导出（`{ spec:"lorebook_v3", data }`）且 character_book 本就该
+// 与全局 lorebook 叠加 —— 所以把共享设定提到组级独立文件，成员卡里只留角色私有条目。
+// ——————————————————————————————————————————————————————————————
+const BOOK_SPEC = "lorebook_v3";
+const BOOK_MAX_ENTRIES = 200;
+
+function bookDirs(){ return dataRoots("cc-books"); }
+function bookDir(){ return bookDirs()[0]; }
+function bookPath(groupId){ return join(bookDir(), safeGroupId(groupId) + ".json"); }
+async function ensureBookDir(){ try{ await mkdir(bookDir(), { recursive: true }); }catch{} }
+
+/** 条目归一化：**只补缺、不裁剪**（CCv3 要求把不认识的字段也原样保存）。 */
+function makeBookEntry(e){
+  const src = (e && typeof e === "object") ? e : {};
+  const out = Object.assign({}, src);
+  out.keys = Array.isArray(src.keys) ? src.keys.map(String) : [];
+  out.content = String(src.content == null ? "" : src.content);
+  out.enabled = src.enabled !== false;
+  out.insertion_order = Number.isFinite(Number(src.insertion_order)) ? Number(src.insertion_order) : 0;
+  out.constant = src.constant === true;
+  out.use_regex = src.use_regex === true;
+  if(typeof out.name !== "string") out.name = out.name == null ? "" : String(out.name);
+  if(!out.extensions || typeof out.extensions !== "object" || Array.isArray(out.extensions)) out.extensions = {};
+  return out;
+}
+function bookCcOf(obj){
+  const data = (obj && obj.data && typeof obj.data === "object") ? obj.data : {};
+  const ext = (data.extensions && typeof data.extensions === "object") ? data.extensions : {};
+  return (ext.cc && typeof ext.cc === "object") ? ext.cc : {};
+}
+function bookRevOf(obj){ const n = Number(bookCcOf(obj).rev); return Number.isFinite(n) && n > 0 ? Math.round(n) : 0; }
+function normalizeBook(obj, groupId){
+  const src = (obj && typeof obj === "object") ? obj : {};
+  const raw = (src.data && typeof src.data === "object") ? src.data : (Array.isArray(src.entries) ? src : {});
+  const cc = bookCcOf(src);
+  const data = Object.assign({}, raw, {
+    name: String(raw.name || "").slice(0, 80),
+    description: String(raw.description || "").slice(0, 300),
+    scan_depth: Math.max(1, Math.round(Number(raw.scan_depth) || 4)),
+    token_budget: Math.max(100, Math.round(Number(raw.token_budget) || 2000)),
+    recursive_scanning: raw.recursive_scanning === true,
+    entries: (Array.isArray(raw.entries) ? raw.entries : []).slice(0, BOOK_MAX_ENTRIES).map(makeBookEntry),
+  });
+  const ext = Object.assign({}, (raw.extensions && typeof raw.extensions === "object") ? raw.extensions : {});
+  ext.cc = Object.assign({}, (ext.cc && typeof ext.cc === "object") ? ext.cc : {}, {
+    groupId: safeGroupId(groupId || cc.groupId),
+    rev: Math.max(0, Math.round(Number(cc.rev) || 0)),
+    updatedAt: Number(cc.updatedAt) || nowSec(),
+  });
+  data.extensions = ext;
+  return Object.assign({}, src, { spec: BOOK_SPEC, data });
+}
+async function readBookRaw(groupId){
+  const file = safeGroupId(groupId) + ".json";
+  for(const dir of bookDirs()){
+    try{
+      const raw = await readFile(join(dir, file), "utf8");
+      const obj = JSON.parse(raw);
+      if(obj && typeof obj === "object") return { raw, obj };
+    }catch{}
+  }
+  return null;
+}
+async function writeBook(groupId, book){
+  await ensureBookDir();
+  const gid = safeGroupId(groupId);
+  const prev = await readBookRaw(gid);
+  const cur = normalizeBook(book, gid);
+  cur.data.extensions.cc.rev = (prev ? bookRevOf(prev.obj) : 0) + 1;
+  cur.data.extensions.cc.updatedAt = nowSec();
+  await writeFile(bookPath(gid), JSON.stringify(cur, null, 2), "utf8");
+  return cur;
+}
+async function deleteBook(groupId){
+  const gid = safeGroupId(groupId);
+  if(!gid) return false;
+  let removed = 0;
+  for(const dir of bookDirs()){
+    try{ await unlink(join(dir, gid + ".json")); removed += 1; }
+    catch(e){ if(e && e.code !== "ENOENT") throw e; }
+  }
+  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;
+}
+async function bookCardsFor(ids){
+  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{}
+  }
+  return out;
+}
+function scanSharedEntries(cards){
+  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) }));
+  const totalEntries = list.reduce((n, c) => n + (Array.isArray(c.entries) ? c.entries.length : 0), 0);
+  return { candidates, stats: { cards: list.length, totalEntries,
+    duplicatedEntries: candidates.reduce((n, g) => n + g.cards.length, 0),
+    savedChars: candidates.reduce((n, g) => n + g.savedChars, 0) } };
+}
+function mergeBookEntries(bookEntries, cardEntries){
+  const have = new Set((Array.isArray(cardEntries) ? cardEntries : []).map(contentKeyOf));
+  const added = [];
+  (Array.isArray(bookEntries) ? bookEntries : []).forEach(e => {
+    const sig = contentKeyOf(e);
+    if(have.has(sig)) return;
+    have.add(sig);
+    added.push(makeBookEntry(e));
+  });
+  return { entries: (Array.isArray(cardEntries) ? cardEntries : []).map(makeBookEntry).concat(added), added };
+}
+function applyBookPromotion(cards, bookEntries, signatures){
+  const want = new Set((Array.isArray(signatures) ? signatures : []).map(String));
+  const book = (Array.isArray(bookEntries) ? bookEntries : []).map(makeBookEntry);
+  const have = new Set(book.map(contentKeyOf));
+  const promoted = [];
+  const nextCards = (Array.isArray(cards) ? cards : []).map(c => {
+    const kept = [];
+    let removed = 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;
+        return;
+      }
+      kept.push(makeBookEntry(e));
+    });
+    return { id: c.id, name: c.name, entries: kept, removed };
+  });
+  return { bookEntries: book, cards: nextCards, promoted, removedTotal: nextCards.reduce((n, c) => n + c.removed, 0) };
+}
+
+// —— 0.9.0：三个编排动作（与宿主半 cc_patchBook / cc_promoteBook / cc_applyBook 端点行为等价）——
+
+/** 条目摘要（返回体卫生：默认只回 name/keys/长度/前 80 字，`includeContent` 才给全文）。 */
+function bookEntryBrief(e, includeContent){
+  const brief = { contentKey: contentKeyOf(e), name: String(e.name || ""), keys: (e.keys || []).map(String),
+    constant: e.constant === true, enabled: e.enabled !== false, chars: String(e.content || "").length };
+  if(includeContent) brief.content = String(e.content || "");
+  else brief.preview = String(e.content || "").slice(0, 80).replace(/\s+/g, " ");
+  return brief;
+}
+function bookBrief(book, includeContent){
+  const d = book.data;
+  return { spec: BOOK_SPEC, rev: bookRevOf(book), name: d.name, description: d.description,
+    scan_depth: d.scan_depth, token_budget: d.token_budget, recursive_scanning: d.recursive_scanning,
+    entries: d.entries.map(e => bookEntryBrief(e, includeContent)) };
+}
+/** 改共享世界书（书级 meta + 条目 ops）。返回 { ok, ... }。 */
+async function patchSharedBook(groupId, args){
+  const gid = safeGroupId(groupId);
+  if(!gid) return { ok: false, error: "需要 groupId" };
+  const found = await readBookRaw(gid);
+  const cur = found ? normalizeBook(found.obj, gid) : normalizeBook({ data: { name: String(args.name || "共享设定") } }, gid);
+  if(typeof args.expectedBookRev === "number" && args.expectedBookRev !== bookRevOf(cur)){
+    return { ok: false, staleRev: true, expectedBookRev: args.expectedBookRev, actualBookRev: bookRevOf(cur),
+      error: "共享世界书已被外部修改（期望 rev=" + args.expectedBookRev + "，实际 rev=" + bookRevOf(cur) + "）—— 先 cc_get_shared_book 重新读一遍再改。" };
+  }
+  const applied = [], rejected = [];
+  if(args.name !== undefined) cur.data.name = String(args.name).slice(0, 80);
+  if(args.description !== undefined) cur.data.description = String(args.description).slice(0, 300);
+  if(args.scan_depth !== undefined) cur.data.scan_depth = Math.max(1, Math.round(Number(args.scan_depth) || 4));
+  if(args.token_budget !== undefined) cur.data.token_budget = Math.max(100, Math.round(Number(args.token_budget) || 2000));
+  if(args.recursive_scanning !== undefined) cur.data.recursive_scanning = args.recursive_scanning === true;
+  ["name", "description", "scan_depth", "token_budget", "recursive_scanning"].forEach(k => { if(args[k] !== undefined) applied.push({ op: "setMeta", field: k }); });
+  (Array.isArray(args.ops) ? args.ops : []).forEach(op => {
+    const kind = String((op && op.op) || "");
+    if(kind === "addEntry"){
+      const e = makeBookEntry(op.entry);
+      if(!e.content.trim()){ rejected.push({ op, error: "content 不能为空" }); return; }
+      if(cur.data.entries.some(x => contentKeyOf(x) === contentKeyOf(e))){ rejected.push({ op, error: "同内容的条目已存在" }); return; }
+      if(cur.data.entries.length >= BOOK_MAX_ENTRIES){ rejected.push({ op, error: "条目数已达上限 " + BOOK_MAX_ENTRIES }); return; }
+      cur.data.entries.push(e);
+      applied.push({ op: kind, key: contentKeyOf(e), name: e.name });
+    } else if(kind === "updateEntry"){
+      const idx = cur.data.entries.findIndex(x => contentKeyOf(x) === String(op.contentKey || ""));
+      if(idx < 0){ rejected.push({ op, error: "找不到条目（contentKey 不匹配）" }); return; }
+      cur.data.entries[idx] = makeBookEntry(Object.assign({}, cur.data.entries[idx], (op.patch && typeof op.patch === "object") ? op.patch : {}));
+      applied.push({ op: kind, key: contentKeyOf(cur.data.entries[idx]) });
+    } else if(kind === "removeEntry"){
+      // 支持两种定位：`index`（工坊列表直接用它）或 `contentKey`（模型读到的签名）
+      const byIndex = Number.isInteger(op.index) ? op.index : -1;
+      if(byIndex >= 0 && byIndex < cur.data.entries.length){
+        const gone = cur.data.entries.splice(byIndex, 1)[0];
+        applied.push({ op: kind, index: byIndex, key: contentKeyOf(gone) });
+        return;
+      }
+      const before = cur.data.entries.length;
+      cur.data.entries = cur.data.entries.filter(x => contentKeyOf(x) !== String(op.contentKey || ""));
+      if(cur.data.entries.length === before){ rejected.push({ op, error: "找不到条目（index / contentKey 都不匹配）" }); return; }
+      applied.push({ op: kind, key: String(op.contentKey) });
+    } else rejected.push({ op, error: "未知 op：" + kind });
+  });
+  if(!applied.length) return { ok: true, book: cur, rev: bookRevOf(cur), applied, rejected, changed: false };
+  const saved = await writeBook(gid, cur);
+  return { ok: true, book: saved, rev: bookRevOf(saved), applied, rejected, changed: true };
+}
+/** 提升去重：把成员卡里重复的条目搬进共享书，并从各卡删掉（默认 dryRun，`apply:true` 才动手）。 */
+async function promoteSharedBook(groupId, args){
+  const gid = safeGroupId(groupId);
+  if(!gid) return { ok: false, error: "需要 groupId" };
+  const found = await readBookRaw(gid);
+  const cur = found ? normalizeBook(found.obj, gid) : normalizeBook({}, gid);
+  const cards = await bookCardsFor(await groupMemberIds(gid));
+  const scan = scanSharedEntries(cards);
+  const known = new Map(scan.candidates.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 unknownKeys = requested.filter(s => !known.has(s));
+  const use = requested.filter(s => known.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 });
+  if(args.apply !== true){
+    return { ok: true, 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) };
+  }
+  const saved = await writeBook(gid, Object.assign({}, cur, { data: Object.assign({}, cur.data, { entries: plan.bookEntries }) }));
+  const touched = [];
+  for(const c of plan.cards){
+    if(!c.removed) continue;
+    try{
+      const rawOne = await readLibraryRaw(c.id);
+      const obj = JSON.parse(rawOne.raw);
+      obj.draft.data.character_book = Object.assign({}, obj.draft.data.character_book, { entries: c.entries });
+      if(obj.meta){ obj.meta.loreCount = c.entries.length; obj.meta.updatedAt = nowSec(); }   // 只动这两个字段，其余 meta 原样保留（B4 的教训）
+      await writeFile(rawOne.path, JSON.stringify(obj, null, 2), "utf8");
+      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: true, dryRun: false, changed: true, promoted: plan.promoted.length, removedTotal: plan.removedTotal, unknownKeys,
+    bookRev: bookRevOf(saved), bookEntries: saved.data.entries.length, perCard: touched, candidates: scan.candidates.map(summary), stats: scan.stats };
+}
+/** 回填：把共享书条目合并进某张卡（同内容已存在则跳过）—— 给不支持全局世界书的客户端兜底。 */
+async function applySharedBook(groupId, cardId, dryRun){
+  const gid = safeGroupId(groupId);
+  if(!gid) return { ok: false, error: "需要 groupId" };
+  const found = await readBookRaw(gid);
+  if(!found) return { ok: false, notFound: true, error: "这个分组还没有共享世界书" };
+  const cur = normalizeBook(found.obj, gid);
+  if(!cardId) return { ok: false, needCard: true, error: "没有指定 cardId，当前草稿也没有来源卡（先保存到侧边栏）" };
+  const rawOne = await readLibraryRaw(cardId);
+  const obj = JSON.parse(rawOne.raw);
+  const cardEntries = (obj.draft && obj.draft.data && obj.draft.data.character_book && Array.isArray(obj.draft.data.character_book.entries))
+    ? obj.draft.data.character_book.entries : [];
+  const merged = mergeBookEntries(cur.data.entries, cardEntries);
+  if(dryRun) return { ok: true, dryRun: true, cardId, wouldAdd: merged.added.length, bookEntries: cur.data.entries.length, cardEntries: cardEntries.length };
+  if(!merged.added.length) return { ok: true, cardId, added: 0, changed: false, loreCount: cardEntries.length };
+  obj.draft.data.character_book = Object.assign({}, obj.draft.data.character_book, { entries: merged.entries });
+  if(obj.meta){ obj.meta.loreCount = merged.entries.length; obj.meta.updatedAt = nowSec(); }
+  await writeFile(rawOne.path, JSON.stringify(obj, null, 2), "utf8");
+  return { ok: true, cardId, added: merged.added.length, changed: true, loreCount: merged.entries.length };
+}
+
 export { apply, inject, name, safeDraftFile, draftDirs, libDirs, dataRoots, originPath, readOriginSync, writeOriginSync,
   // 人物关系图谱（0.8.0）：导出纯函数与落盘根，供 tests/relations.test.mjs 与宿主半逐字比对同构实现
   groupDirs, groupDir, groupPath, safeGroupId, normalizeGroup, validateGroupOp, applyGroupOps,
   renderRelationsSection, spliceRelations, checkGroup, listGroups, readGroupRaw, writeGroup, groupMemberIds, libraryCardsFor,
+  // 0.8.0 分组管理：出边口径（渲染与计数共用）、建组查重、meta 就地写 —— 都与宿主半同构，测试直接比对
+  outgoingEdgesOf, findGroupByName, patchLibraryMeta, listLibraryEntries, saveLibraryEntry,
+  groupSummaries, assignCardToGroup, deleteGroupWithMembers,
+  // 0.9.0 组级共享世界书：落盘 + 纯函数 + 三个编排动作（与宿主半同构，测试交叉比对行为）
+  BOOK_SPEC, bookDirs, bookDir, bookPath, makeBookEntry, normalizeBook, bookRevOf, readBookRaw, writeBook, deleteBook,
+  contentKeyOf, bookCardsFor, scanSharedEntries, mergeBookEntries, applyBookPromotion,
+  bookEntryBrief, bookBrief, patchSharedBook, promoteSharedBook, applySharedBook,
   REL_TYPES, REL_TYPE_LABELS, REL_BEGIN, REL_END };