@xia-sc/dsh-cc-studio 0.4.1 → 0.8.0

package/lib/index.js

@@ -3,7 +3,7 @@
  * CCv3 工坊：校验 + 共享草稿（供 CC 模式的 LLM Tools 与浏览器胶囊同步）+ 已存角色侧边栏落盘。
  */
 import { mkdir, readdir, readFile, writeFile, unlink } from "node:fs/promises";
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { join } from "node:path";
@@ -97,6 +97,38 @@ function makeDefaultDraft(){
     }
   };
 }
+/**
+ * 草稿形状规范化（0.7.1，B1，与 lib/agent.js 同构）。
+ *
+ * DSH 对工具/远端返回值做 lossless-JSON 校验：**任何嵌套 `undefined` 都会让整次调用报错**。
+ * 外部导入的卡（PNG / CHARX）或早期版本写下的草稿可能缺 `spec_version` / `creation_date` 这类字段，
+ * 前端直接读它就会渲染出 `undefined`、导出的卡也缺字段。所以读盘恢复时按空卡模板补齐缺失键：
+ * 只补 `undefined`，不覆盖已有值、不改类型（类型问题交给校验报）。
+ */
+function normalizeCardShape(draft){
+  const tpl = makeDefaultDraft();
+  if(!draft || typeof draft !== "object") return tpl;
+  const out = {
+    spec: (draft.spec !== undefined && draft.spec !== null) ? draft.spec : tpl.spec,
+    spec_version: (draft.spec_version !== undefined && draft.spec_version !== null) ? draft.spec_version : tpl.spec_version,
+    data: {},
+  };
+  const src = (draft.data && typeof draft.data === "object") ? draft.data : {};
+  for(const k of Object.keys(tpl.data)){
+    out.data[k] = (src[k] !== undefined) ? src[k] : tpl.data[k];
+  }
+  for(const k of Object.keys(src)){ if(!(k in out.data)) out.data[k] = src[k]; }
+  const book = (out.data.character_book && typeof out.data.character_book === "object") ? out.data.character_book : {};
+  const bTpl = tpl.data.character_book;
+  const nb = {};
+  for(const k of Object.keys(bTpl)){ nb[k] = (book[k] !== undefined) ? book[k] : bTpl[k]; }
+  for(const k of Object.keys(book)){ if(!(k in nb)) nb[k] = book[k]; }
+  if(!Array.isArray(nb.entries)) nb.entries = [];
+  if(!nb.extensions || typeof nb.extensions !== "object") nb.extensions = {};
+  out.data.character_book = nb;
+  if(!out.data.extensions || typeof out.data.extensions !== "object") out.data.extensions = {};
+  return out;
+}
 if(!globalThis.__CC_DRAFTS__) globalThis.__CC_DRAFTS__ = new Map();
 // —— 落盘根（0.3.6 起统一）：DSH_HOME 优先，homedir()/.dsh 兜底 ——
 // 预设目录一直走这里；草稿与角色库在 0.3.5 及以前写死 homedir()/.dsh，现在统一到同一套根，
@@ -132,6 +164,27 @@ function safeDraftFile(key){
 }
 function draftPath(key){ return join(draftDir(), safeDraftFile(key)); }
 /** 读盘用：主根没有就回退旧根（0.3.6 之前草稿写死的地方）。找不到返回 null。 */
+// —— 草稿的「来源 id」sidecar（0.5.0，与 lib/agent.js 同构）——
+// 记「这份草稿是从哪张已存卡载入的」，让「载入 → 改 → 保存」更新原卡而不是新建一张同名重复卡。
+// 浏览器侧刷新页面会丢掉内存里的 currentLibraryId，所以这份关联必须落盘；存 sidecar 而不是塞进
+// draft.extensions，是因为后者会跟着导出进用户的卡里。
+function originFilePath(key){ return join(draftDir(), safeDraftFile(key).replace(/\.json$/, ".origin.json")); }
+function readDraftOrigin(key){
+  try{
+    const p = originFilePath(key);
+    if(!existsSync(p)) return null;
+    const obj = JSON.parse(readFileSync(p, "utf8"));
+    if(obj && typeof obj.libraryId === "string" && obj.libraryId) return obj;
+  }catch{}
+  return null;
+}
+function writeDraftOrigin(key, libraryId, name){
+  try{
+    if(!libraryId){ try{ unlinkSync(originFilePath(key)); }catch{} return; }
+    mkdirSync(draftDir(), { recursive: true });
+    writeFileSync(originFilePath(key), JSON.stringify({ key: String(key), libraryId: String(libraryId), name: String(name||""), savedAt: nowSec() }, null, 2), "utf8");
+  }catch(e){ try{ console.error("[dsh-cc-studio] persist draft origin failed:", (e && e.message) || e); }catch{} }
+}
 function findDraftPath(key){
   const file = safeDraftFile(key);
   for(const dir of draftDirs()){
@@ -154,17 +207,36 @@ function loadPersistedDraftSync(key){
 function persistDraftSync(key, draft){
   try{
     mkdirSync(draftDir(), { recursive: true });
-    writeFileSync(draftPath(key), JSON.stringify({ key: String(key), updatedAt: nowSec(), draft }, null, 2), "utf8");
-  }catch(e){ try{ console.error("[dsh-cc-studio] persist draft failed:", (e && e.message) || e); }catch{} }
+    // revision（0.6.0，P0-6）：与 lib/agent.js 同构 —— 工具半与宿主半各写各的文件、各持各的内存，
+    // **只有草稿文件里的 rev 是共同真相**。工坊这边每写一次盘就 +1，工具侧下次调用读到新 rev 就知道
+    // 「草稿被外部换过了」，从而重载而不是拿过期前提去写（否则会静默覆盖用户在工坊里的修改）。
+    let rev = 1;
+    try{
+      const prev = JSON.parse(readFileSync(draftPath(key), "utf8"));
+      if(prev && typeof prev.rev === "number" && prev.rev > 0) rev = prev.rev + 1;
+    }catch{}
+    writeFileSync(draftPath(key), JSON.stringify({ key: String(key), updatedAt: nowSec(), rev, draft }, null, 2), "utf8");
+    return rev;
+  }catch(e){ try{ console.error("[dsh-cc-studio] persist draft failed:", (e && e.message) || e); }catch{} return null; }
 }
 function draftMeta(key){
   const k = key || "default";
-  if(!globalThis.__CC_DRAFT_META__.has(k)) globalThis.__CC_DRAFT_META__.set(k, { isNew: false, recovered: false });
+  if(!globalThis.__CC_DRAFT_META__.has(k)) globalThis.__CC_DRAFT_META__.set(k, { isNew: false, recovered: false, newReason: null });
   return globalThis.__CC_DRAFT_META__.get(k);
 }
+/** 卡片内容指纹（忽略 modification_date）：判断「这次写入到底有没有真的改变内容」（N4，与工具半同构）。 */
+function cardFingerprint(draft){
+  try{
+    const d = JSON.parse(JSON.stringify((draft && draft.data) ? draft.data : {}));
+    delete d.modification_date;
+    return JSON.stringify(d);
+  }catch{ return ""; }
+}
 function draftStatusFor(key, draft){
   const m = draftMeta(key);
-  return { isNew: !!m.isNew, recovered: !!m.recovered, creation_date: (draft && draft.data) ? draft.data.creation_date : null, key: String(key) };
+  // B1（0.7.1）：缺 `creation_date` 的外部导入卡不能再漏出 `undefined`（工具侧会因此整次调用失败，
+  // 前端也会把 undefined 渲染成字面量）。
+  return { isNew: !!m.isNew, recovered: !!m.recovered, creation_date: (draft && draft.data && draft.data.creation_date !== undefined) ? draft.data.creation_date : null, key: String(key) };
 }
 /**
  * 解析「这次调用读写哪把草稿槽」，并把来源一并带出来（诊断用）。
@@ -261,20 +333,25 @@ function getDraftFor(key){
     // fix #2：内存 miss 时先尝试从磁盘恢复，而非静默建空
     const restored = loadPersistedDraftSync(k);
     if(restored){
-      globalThis.__CC_DRAFTS__.set(k, restored);
-      const m = draftMeta(k); m.isNew = false; m.recovered = true;
+      globalThis.__CC_DRAFTS__.set(k, normalizeCardShape(restored));   // B1：补齐外部导入卡缺失的字段
+      const m = draftMeta(k); m.isNew = false; m.recovered = true; m.newReason = null;
     } else {
       globalThis.__CC_DRAFTS__.set(k, makeDefaultDraft());
-      const m = draftMeta(k); m.isNew = true; m.recovered = false;
+      const m = draftMeta(k); m.isNew = true; m.recovered = false; m.newReason = "welcome";
     }
   }
   return globalThis.__CC_DRAFTS__.get(k);
 }
 function setDraftFor(key, draft){
-  draft.data.modification_date = nowSec();
   const k = key || "default";
+  const prev = globalThis.__CC_DRAFTS__.get(k);
+  // N4（0.7.0，与 lib/agent.js 同构）：内容一字未变时不写盘、不递增 rev。工坊侧每次编辑都调
+  // cc_setDraft，同值覆盖（失焦、重复输入、只动了别的槽）不该白耗一个版本号 —— 否则模型手上的
+  // rev 前提会被「其实没发生的变化」打掉一次，而它只能看到一句「草稿已被外部修改」。
+  if(prev && cardFingerprint(prev) === cardFingerprint(draft)) return draft;
+  draft.data.modification_date = nowSec();
   globalThis.__CC_DRAFTS__.set(k, draft);
-  const m = draftMeta(k); m.isNew = false; m.recovered = false;
+  const m = draftMeta(k); m.isNew = false; m.recovered = false; m.newReason = null;
   persistDraftSync(k, draft);
   return draft;
 }
@@ -307,6 +384,327 @@ function isCcPreset(ctx, sessionId){
 }
 
 // —— 已存角色侧边栏：落盘到 <主根>/cc-library/<id>.json（读盘回退 0.3.6 之前的 homedir()/.dsh）——
+// ——————————————————————————————————————————————————————————————
+// 人物关系图谱（0.8.0）：分组文件 + 三维关系（方向 × 类型 × 强度）
+//
+// 落盘 <主根>/cc-groups/<id>.json；「卡属于哪个组」记在库条目 meta.groupId（**单一真源**），
+// 分组文件**不存 members** —— 成员由 listLibraryEntries() 过滤得出，删卡/移组天然一致，不会双写漂移。
+//
+// 纯函数（normalizeGroup / validateGroupOp / applyGroupOps / renderRelationsSection / spliceRelations /
+// checkGroup / estimateTokensLite）在 lib/index.js 与 lib/agent.js 各有一份**同构实现**
+// （与 dataRoots / safeDraftFile 同模式）；tests/relations.test.mjs 会逐字比对两半的渲染输出。
+//
+// 渲染：关系只活在插件侧，要让分享出去的卡自包含，就把它渲染进 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 -->";
+
+function groupDirs(){ return dataRoots("cc-groups"); }
+function groupDir(){ return groupDirs()[0]; }
+/** 分组 id 只允许 [A-Za-z0-9_-]：它直接进文件名，必须挡住路径穿越。 */
+function safeGroupId(id){
+  return String(id == null ? "" : id).replace(/[^a-zA-Z0-9_-]/g, "").slice(0, 64);
+}
+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);
+}
+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"] || "其他"); }
+
+/**
+ * 结构兜底（沿用 0.7.1 B1 的教训：外部改坏的文件不能让 undefined 漏进返回值）。
+ * ⚠️ **不丢弃端点不存在的边** —— 那是用户数据，破坏它比报错更糟；体检会报 dangling-edge、
+ * 渲染时会自动跳过。
+ */
+function normalizeGroup(g){
+  const src = (g && typeof g === "object") ? g : {};
+  const nodes = Array.isArray(src.nodes) ? src.nodes.filter(n => n && typeof n === "object" && n.id).map(n => ({
+    id: String(n.id),
+    kind: (n.kind === "card") ? "card" : "npc",
+    cardId: (typeof n.cardId === "string" && n.cardId) ? n.cardId : null,
+    name: String(n.name || "").slice(0, 60),
+    aliases: Array.isArray(n.aliases) ? n.aliases.map(String).map(s => s.trim()).filter(Boolean).slice(0, 8) : [],
+    orphanOf: (typeof n.orphanOf === "string" && n.orphanOf) ? n.orphanOf : null,
+  })) : [];
+  const edges = Array.isArray(src.edges) ? src.edges.filter(e => e && typeof e === "object" && e.id).map(e => ({
+    id: String(e.id),
+    from: String(e.from || ""),
+    to: String(e.to || ""),
+    type: relTypeOf(e.type),
+    label: String(e.label || "").slice(0, 24),
+    strength: Math.max(1, Math.min(5, Math.round(Number(e.strength) || 3))),
+    direction: (e.direction === "mutual") ? "mutual" : "one-way",
+    note: String(e.note || "").slice(0, 200),
+    updatedAt: Number(e.updatedAt) || nowSec(),
+  })) : [];
+  return {
+    id: safeGroupId(src.id),
+    name: String(src.name || "").slice(0, 60) || "未命名分组",
+    note: String(src.note || "").slice(0, 200),
+    nodes, edges,
+    nextNodeSeq: Math.max(1, Math.round(Number(src.nextNodeSeq) || (nodes.length + 1))),
+    nextEdgeSeq: Math.max(1, Math.round(Number(src.nextEdgeSeq) || (edges.length + 1))),
+    rev: Math.max(0, Math.round(Number(src.rev) || 0)),
+    updatedAt: Number(src.updatedAt) || nowSec(),
+  };
+}
+/** 组内名字/别名是否与别的节点撞车（撞了渲染就会指向同一个人）。 */
+function dupNodeName(g, name, aliases, exceptId){
+  const wanted = [String(name || "").trim()].concat(Array.isArray(aliases) ? aliases.map(s => String(s).trim()) : [])
+    .filter(Boolean).map(s => s.toLowerCase());
+  if(!wanted.length) return false;
+  return g.nodes.some(n => {
+    if(exceptId && n.id === exceptId) return false;
+    const have = [n.name].concat(Array.isArray(n.aliases) ? n.aliases : []).filter(Boolean).map(s => String(s).toLowerCase());
+    return have.some(x => wanted.indexOf(x) >= 0);
+  });
+}
+/** 单条 op 的合法性（纯函数）。返回错误文案，null = 通过。 */
+function validateGroupOp(g, op){
+  if(!op || typeof op !== "object") return "op 必须是对象";
+  const kind = String(op.op || "");
+  const has = (id) => g.nodes.some(n => n.id === id);
+  if(kind === "addNode"){
+    if(!String(op.name || "").trim()) return "addNode 需要 name";
+    if(dupNodeName(g, op.name, op.aliases, null)) return "节点名或别名与组内既有节点重复：" + String(op.name).trim();
+    return null;
+  }
+  if(kind === "updateNode"){
+    const cur = g.nodes.find(n => n.id === String(op.nodeId || ""));
+    if(!cur) return "节点不存在：" + op.nodeId;
+    if(op.name !== undefined || op.aliases !== undefined){
+      const name = (op.name !== undefined) ? op.name : cur.name;
+      const aliases = (op.aliases !== undefined) ? op.aliases : cur.aliases;
+      if(dupNodeName(g, name, aliases, cur.id)) return "节点名或别名与组内既有节点重复：" + String(name).trim();
+    }
+    return null;
+  }
+  if(kind === "removeNode") return has(String(op.nodeId || "")) ? null : "节点不存在：" + op.nodeId;
+  if(kind === "addEdge"){
+    if(!has(String(op.from || ""))) return "from 节点不存在：" + op.from;
+    if(!has(String(op.to || ""))) return "to 节点不存在：" + op.to;
+    if(String(op.from) === String(op.to)) return "不能给自己建关系（from 与 to 相同）";
+    const st = Number(op.strength === undefined ? 3 : op.strength);
+    if(!(st >= 1 && st <= 5)) return "strength 必须在 1..5";
+    if(op.type !== undefined && REL_TYPES.indexOf(String(op.type)) < 0) return "type 不在枚举内：" + op.type;
+    return null;
+  }
+  if(kind === "updateEdge"){
+    const e = g.edges.find(x => x.id === String(op.edgeId || ""));
+    if(!e) return "边不存在：" + op.edgeId;
+    if(op.strength !== undefined){ const st = Number(op.strength); if(!(st >= 1 && st <= 5)) return "strength 必须在 1..5"; }
+    if(op.type !== undefined && REL_TYPES.indexOf(String(op.type)) < 0) return "type 不在枚举内：" + op.type;
+    return null;
+  }
+  if(kind === "removeEdge") return g.edges.some(e => e.id === String(op.edgeId || "")) ? null : "边不存在：" + op.edgeId;
+  return "未知 op：" + kind;
+}
+/** 应用 ops（纯函数）：返回 {group, applied, rejected:[{op,error}]}；不修改入参。 */
+function applyGroupOps(group, ops){
+  const g = normalizeGroup(JSON.parse(JSON.stringify(group || {})));
+  const applied = [], rejected = [];
+  (Array.isArray(ops) ? ops : []).forEach(op => {
+    const err = validateGroupOp(g, op);
+    if(err){ rejected.push({ op, error: err }); return; }
+    const kind = String(op.op);
+    if(kind === "addNode"){
+      const id = "n" + (g.nextNodeSeq++);
+      g.nodes.push({
+        id, kind: (op.kind === "card") ? "card" : "npc",
+        cardId: (op.kind === "card" && op.cardId) ? String(op.cardId) : null,
+        name: String(op.name).trim().slice(0, 60),
+        aliases: (Array.isArray(op.aliases) ? op.aliases : []).map(String).map(s => s.trim()).filter(Boolean).slice(0, 8),
+        orphanOf: null,
+      });
+      applied.push({ op: kind, nodeId: id });
+    } else if(kind === "updateNode"){
+      const n = g.nodes.find(x => x.id === String(op.nodeId));
+      if(op.name !== undefined) n.name = String(op.name).trim().slice(0, 60);
+      if(op.aliases !== undefined) n.aliases = (Array.isArray(op.aliases) ? op.aliases : []).map(String).map(s => s.trim()).filter(Boolean).slice(0, 8);
+      applied.push({ op: kind, nodeId: n.id });
+    } else if(kind === "removeNode"){
+      const nid = String(op.nodeId);
+      g.nodes = g.nodes.filter(n => n.id !== nid);
+      if(op.removeEdges !== false) g.edges = g.edges.filter(e => e.from !== nid && e.to !== nid);
+      applied.push({ op: kind, nodeId: nid, edgesRemoved: (op.removeEdges !== false) });
+    } else if(kind === "addEdge"){
+      const id = "e" + (g.nextEdgeSeq++);
+      g.edges.push({
+        id, from: String(op.from), to: String(op.to), type: relTypeOf(op.type),
+        label: String(op.label || "").slice(0, 24),
+        strength: Math.max(1, Math.min(5, Math.round(Number(op.strength === undefined ? 3 : op.strength)))),
+        direction: (op.direction === "mutual") ? "mutual" : "one-way",
+        note: String(op.note || "").slice(0, 200), updatedAt: nowSec(),
+      });
+      applied.push({ op: kind, edgeId: id });
+    } else if(kind === "updateEdge"){
+      const e = g.edges.find(x => x.id === String(op.edgeId));
+      if(op.type !== undefined) e.type = relTypeOf(op.type);
+      if(op.label !== undefined) e.label = String(op.label).slice(0, 24);
+      if(op.strength !== undefined) e.strength = Math.max(1, Math.min(5, Math.round(Number(op.strength))));
+      if(op.direction !== undefined) e.direction = (op.direction === "mutual") ? "mutual" : "one-way";
+      if(op.note !== undefined) e.note = String(op.note).slice(0, 200);
+      e.updatedAt = nowSec();
+      applied.push({ op: kind, edgeId: e.id });
+    } else if(kind === "removeEdge"){
+      const eid = String(op.edgeId);
+      g.edges = g.edges.filter(e => e.id !== eid);
+      applied.push({ op: kind, edgeId: eid });
+    }
+  });
+  g.updatedAt = nowSec();
+  return { group: g, applied, rejected };
+}
+/**
+ * 生成【关系】段（纯函数）。默认只写出边（我 → 他）—— 卡片是以"我"为视角的；
+ * includeIncoming 时追加一节「他们眼中的我」（扮演时知道对方怎么看我，是剧情张力来源，默认关）。
+ */
+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 incoming = all.filter(e => e.to === myNodeId && e.direction !== "mutual");
+  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 lines = ["【关系】"];
+  if(!outgoing.length) lines.push("- （暂无）");
+  else outgoing.slice().sort(byTypeThenStrength("to")).forEach(e => lines.push(fmt(e, e.to)));
+  if(o.includeIncoming && incoming.length){
+    lines.push("", "【他们眼中的我】");
+    incoming.slice().sort(byTypeThenStrength("from")).forEach(e => lines.push(fmt(e, e.from)));
+  }
+  return lines.join("\n");
+}
+/**
+ * 把段文本并入 description：有标记区就**整段替换**，没有就末尾追加；section 为空 = 移除标记区。
+ * 幂等：同一段内容渲染两次结果逐字相同（tests/relations.test.mjs 钉住）。
+ */
+function spliceRelations(description, section, meta){
+  const desc = String(description || "");
+  const i = desc.indexOf(REL_BEGIN), j = desc.indexOf(REL_END);
+  const block = section ? (REL_BEGIN + (meta ? " " + meta : "") + " -->\n" + section + "\n" + REL_END) : "";
+  if(i >= 0 && j > i){
+    const before = desc.slice(0, i).replace(/\s*$/, "");
+    const after = desc.slice(j + REL_END.length);
+    const head = block ? (before + (before ? "\n\n" : "") + block) : before;
+    return (head + after).replace(/\n{3,}/g, "\n\n").trim();
+  }
+  if(!block) return desc;
+  const head = desc.replace(/\s*$/, "");
+  return (head + (head ? "\n\n" : "") + block).trim();
+}
+/**
+ * 跨卡体检（纯函数）。members / cards 由调用方给：
+ *   members = 组内卡的 id 列表；cards = [{id, name, description, constantTokens, tokenBudget}]
+ */
+function checkGroup(group, members, cards){
+  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 constTokens = memberCards.reduce((n, c) => n + (Number(c.constantTokens) || 0), 0);
+  const minBudget = memberCards.length ? memberCards.reduce((n, c) => Math.min(n, Number(c.tokenBudget) || 1200), Infinity) : 1200;
+  if(memberCards.length > 1 && constTokens > minBudget * 0.8){
+    add("warn", "constant-budget", "群聊每轮固定开销偏高：成员卡常驻条目合计约 " + constTokens + " token（已达最小预算 " + minBudget + " 的 " + Math.round(constTokens / minBudget * 100) + "%）");
+  }
+  return { issues, stats: { nodes: g.nodes.length, edges: g.edges.length, members: memberCards.length, constantTokens: constTokens, minBudget } };
+}
+
+/** 读分组：主根优先，回退旧根（与角色库同规）。 */
+async function readGroupRaw(id){
+  const file = safeGroupId(id) + ".json";
+  for(const dir of groupDirs()){
+    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 listGroups(){
+  await ensureGroupDir();
+  const seen = new Map();
+  for(const dir of groupDirs()){
+    let files = [];
+    try{ files = await readdir(dir); }catch{ continue; }
+    for(const f of files){
+      if(!f.endsWith(".json")) continue;
+      const id = f.replace(/\.json$/, "");
+      if(seen.has(id)) continue;
+      try{
+        const obj = JSON.parse(await readFile(join(dir, f), "utf8"));
+        seen.set(id, normalizeGroup(obj));
+      }catch{}
+    }
+  }
+  return [...seen.values()].sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
+}
+/** 写分组：读盘上 rev 再 +1（与 persistDraftSync 同思路），只写主根。 */
+async function writeGroup(group){
+  await ensureGroupDir();
+  const cur = normalizeGroup(group);
+  let rev = cur.rev || 0;
+  const prev = await readGroupRaw(cur.id);
+  if(prev && prev.obj && typeof prev.obj.rev === "number") rev = prev.obj.rev + 1;
+  else if(!prev) rev = 1;
+  cur.rev = rev;
+  cur.updatedAt = nowSec();
+  await writeFile(groupPath(cur.id), JSON.stringify(cur, null, 2), "utf8");
+  return cur;
+}
+/** 删除：两个根里的同名副本都删（否则回退读会把刚删的组「复活」，与 deleteLibraryEntry 同规）。 */
+async function deleteGroupFile(id){
+  const file = safeGroupId(id) + ".json";
+  let removed = 0;
+  for(const dir of groupDirs()){
+    try{ await unlink(join(dir, file)); removed++; }catch{}
+  }
+  return removed;
+}
+
 function libDirs(){ return dataRoots("cc-library"); }
 function libDir(){ return libDirs()[0]; }
 async function ensureLibDir(){
@@ -524,13 +922,18 @@ function makeLibraryEntryMeta(draft, existingMeta, id){
   const data = draft && draft.data ? draft.data : {};
   const now = nowSec();
   const loreCount = Array.isArray(data.character_book?.entries) ? data.character_book.entries.length : 0;
-  const tags = Array.isArray(data.tags) ? data.tags.slice(0,6).map(String) : [];
+  const allTags = Array.isArray(data.tags) ? data.tags.map(String) : [];
+  const tags = allTags.slice(0, 6);
   return {
     id: String(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 关系图谱：卡属于哪个分组（**单一真源** —— 分组文件里不存成员列表，避免双写漂移）。
+    // 继承既有值，所以「改卡内容再保存」不会把卡踢出分组。
+    groupId: (existingMeta && existingMeta.groupId) ? String(existingMeta.groupId) : null,
     createdAt: existingMeta && existingMeta.createdAt ? existingMeta.createdAt : now,
     updatedAt: now,
   };
@@ -574,13 +977,15 @@ async function saveLibraryEntry(draft, opts){
     id = String(Date.now())+"-"+Math.random().toString(36).slice(2,6);
   }
   const meta = makeLibraryEntryMeta(draft, existing ? existing.meta : null, id);
-  // 若调用方显式传 name，覆盖 meta.name（不改 draft.data.name，保持原样）
-  if(opts && typeof opts.name==="string" && opts.name.trim()){
-    meta.name = String(opts.name).trim().slice(0,60);
+  // 改名 = 单一事实来源：meta.name 与 draft.data.name 一起改（否则「列表名 / 导出名」两套，用户改名看不出效果）
+  if(opts && typeof opts.name === "string" && opts.name.trim()){
+    const n = String(opts.name).trim().slice(0,60);
+    meta.name = n;
+    draft.data.name = n;
   }
   const payload = { id, meta, draft };
   await writeFile(join(dir, id+".json"), JSON.stringify(payload, null, 2), "utf8");
-  return { id, meta, draft };
+  return { id, meta, draft, action: existing ? "updated" : "created" };
 }
 async function loadLibraryEntry(id){
   await ensureLibDir();
@@ -588,6 +993,72 @@ async function loadLibraryEntry(id){
   if(!obj || !obj.draft) throw new Error("文件格式错误");
   return obj;
 }
+/** 0.8.0：组内成员卡的 id —— 由库条目 meta.groupId 派生（分组文件里刻意不存成员列表）。 */
+async function groupMemberIds(groupId){
+  const gid = safeGroupId(groupId);
+  const entries = await listLibraryEntries();
+  return entries.filter(e => String(e.groupId || "") === gid).map(e => e.id);
+}
+/** 0.8.0：体检 / 渲染需要的卡片摘要（只读；卡不在库里就跳过）。 */
+async function libraryCardsFor(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 || ""),
+        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{}
+  }
+  return out;
+}
+/** 0.8.0：就地改某个库条目的 meta（写在解析到的那一份上，与 renameLibraryEntry 同规，不搬家）。 */
+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;
+}
+/**
+ * 0.8.0：卡被删除后，把各分组里指向它的节点降级为 orphan。
+ * **不删边** —— 关系是用户手工建立的资产，卡没了不代表关系该消失；节点保留名字，体检会报 orphan-node。
+ */
+async function orphanCardNodes(cardId, cardName){
+  const touched = [];
+  for(const g of await listGroups()){
+    let hit = false;
+    g.nodes.forEach(n => {
+      if(n.kind === "card" && n.cardId === cardId){
+        n.cardId = null;
+        n.orphanOf = String(cardName || n.name || "").slice(0, 60);
+        hit = true;
+      }
+    });
+    if(hit){ await writeGroup(g); touched.push(g.id); }
+  }
+  return touched;
+}
+/** 0.8.0：卡改名后同步各分组里对应节点的 name（按 cardId 匹配；别名不动 —— 那是用户为它写的称呼）。 */
+async function syncCardNodeName(cardId, name){
+  const touched = [];
+  const clean = String(name || "").trim().slice(0, 60);
+  if(!clean) return touched;
+  for(const g of await listGroups()){
+    let hit = false;
+    g.nodes.forEach(n => { if(n.kind === "card" && n.cardId === cardId && n.name !== clean){ n.name = clean; hit = true; } });
+    if(hit){ await writeGroup(g); touched.push(g.id); }
+  }
+  return touched;
+}
 /**
  * 删除：**两个根里的同名副本都要删**，否则读盘回退会把刚删掉的卡「复活」。
  * 一个都没删到时仍然抛错（保持「删不存在的 id 是失败」的既有语义）。
@@ -611,6 +1082,8 @@ async function renameLibraryEntry(id, newName){
   if(!name) throw new Error("name 不能为空");
   obj.meta.name = name;
   obj.meta.updatedAt = nowSec();
+  // 单一事实来源（0.5.0）：列表名与卡内 data.name 一起改 —— 此前只改 meta，侧边栏改了名、导出的卡里还是旧名
+  if(obj.draft && obj.draft.data) obj.draft.data.name = name;
   await writeFile(found.path, JSON.stringify(obj, null, 2), "utf8");
   return obj.meta;
 }
@@ -871,7 +1344,8 @@ function apply(ctx, config){
           const k = parts.key;
           const d = getDraftFor(k);
           const status = draftStatusFor(k, d);
-          const payload = { draft: d, key: k, keySource: parts.source, isCc: isCcPreset(ctx, (parts.source==="arg"||parts.source==="arg-snapshot") ? k : null), draftStatus: status };
+          const origin = readDraftOrigin(k);
+          const payload = { draft: d, key: k, keySource: parts.source, isCc: isCcPreset(ctx, (parts.source==="arg"||parts.source==="arg-snapshot") ? k : null), draftStatus: status, originId: origin ? origin.libraryId : null };
           // 只在「当前槽是个新空壳」时才去盘上翻别的槽（issue #5 的救回入口）。
           // 而且只翻**这次错位真正会牵涉到的另一把槽**，不是把所有会话的槽都端出来：
           //   · 当前是会话槽（session-<id>）→ 候选只有 default —— 旧前端在没有会话 id 时
@@ -927,6 +1401,7 @@ function apply(ctx, config){
           if(patch.mes_example!==undefined) cur.data.mes_example = String(patch.mes_example).slice(0,4000);
           if(Array.isArray(patch.tags)) cur.data.tags = patch.tags.map(String).slice(0,12);
           if(patch.creator_notes!==undefined) cur.data.creator_notes = String(patch.creator_notes).slice(0,2000);
+          if(patch.creator!==undefined) cur.data.creator = String(patch.creator).slice(0,120);   // N1：作者名此前没有写入路径
           if(patch.world && typeof patch.world==="object"){
             cur.data.extensions = cur.data.extensions || {};
             cur.data.extensions.cc_world = Object.assign({}, cur.data.extensions.cc_world||{}, patch.world);
@@ -981,29 +1456,54 @@ function apply(ctx, config){
         }
         case "cc_saveToLibrary":{
           // args: {draft?, id?, name?, sessionId?}  draft 缺省则取当前会话草稿
+          const k = draftKeyFrom(ctx, args);
           let draft = args.draft;
           if(!draft || typeof draft!=="object"){
-            const k = draftKeyFrom(ctx, args);
             draft = JSON.parse(JSON.stringify(getDraftFor(k)));
           }
+          // 不传 id 时沿用草稿的**来源 id**：工坊里「载入 → 改 → 保存」应当是更新原卡，
+          // 而不是新建一张同名重复卡（刷新页面会丢掉内存里的 currentLibraryId，所以来源落在盘上）。
+          const explicitId = (typeof args.id==="string" && args.id) ? args.id : "";
+          const origin = explicitId ? null : readDraftOrigin(k);
+          const targetId = explicitId || (origin ? origin.libraryId : "");
           // 允许保存未完全校验的草稿，但至少需要 name？不强制，meta 会兜底“未命名角色”
-          const res = await saveLibraryEntry(draft, { id: args.id, name: args.name });
-          return ok(res);
+          const res = await saveLibraryEntry(draft, { id: targetId || undefined, name: args.name });
+          writeDraftOrigin(k, res.id, res.meta.name);
+          // 0.8.0 修：action 用 saveLibraryEntry 的实测判定（它按「该 id 的文件是否已存在」算）。
+          // 旧写法 `targetId ? "updated" : "created"` 在「传一个库里不存在的新 id」时会谎报 updated ——
+          // 而那正是群聊场景「从母卡派生出一批角色卡」的唯一路径，模型会以为自己覆盖了别人。
+          return ok({ id: res.id, meta: res.meta, action: res.action });
         }
         case "cc_loadFromLibrary":{
           const id = args.id;
           if(typeof id!=="string" || !id) return fail("invalid-id","id 必填");
           const obj = await loadLibraryEntry(id);
-          // 载入到当前会话草稿
+          // 载入到当前会话草稿，并记下来源 id（sidecar）：之后不传 id 保存就是更新这一张
           const k = draftKeyFrom(ctx, args);
           setDraftFor(k, JSON.parse(JSON.stringify(obj.draft)));
-          return ok({ draft: obj.draft, meta: obj.meta, key: k, draftStatus: draftStatusFor(k, obj.draft) });
+          writeDraftOrigin(k, obj.id, obj.meta ? obj.meta.name : "");
+          return ok({ draft: obj.draft, meta: obj.meta, key: k, originId: obj.id, draftStatus: draftStatusFor(k, obj.draft) });
         }
         case "cc_deleteFromLibrary":{
           const id = args.id;
           if(typeof id!=="string" || !id) return fail("invalid-id","id 必填");
+          const k = draftKeyFrom(ctx, args);
+          const origin = readDraftOrigin(k);
+          const wasOrigin = !!(origin && origin.libraryId === id);
           await deleteLibraryEntry(id);
-          return ok({ ok:true, id });
+          // 删掉的正是当前草稿的来源卡 → 清掉关联，否则下次保存会「更新」一张已不存在的卡
+          if(wasOrigin) writeDraftOrigin(k, null);
+          // 0.8.0：关系图谱里不能留下指向已删卡的节点（降级为 orphan 并保留边，见 orphanCardNodes）
+          const groupsTouched = await orphanCardNodes(id, "");
+          const entries = await listLibraryEntries();
+          return ok({ id, remaining: entries.length, originCleared: wasOrigin, groupsTouched });
+        }
+        case "cc_setOrigin":{
+          // 前端显式设/清「当前草稿的来源 id」：id 传 null/空 = 清（清空草稿、另存为新时用）
+          const k = draftKeyFrom(ctx, args);
+          const id = (typeof args.id === "string" && args.id) ? args.id : null;
+          writeDraftOrigin(k, id, args.name);
+          return ok({ key: k, originId: id });
         }
         case "cc_renameInLibrary":{
           const id = args.id;
@@ -1011,7 +1511,9 @@ function apply(ctx, config){
           if(typeof id!=="string" || !id) return fail("invalid-id","id 必填");
           if(typeof newName!=="string" || !newName.trim()) return fail("invalid-name","name 必填");
           const meta = await renameLibraryEntry(id, newName);
-          return ok({ meta });
+          // 0.8.0：图谱节点名跟着改（按 cardId 匹配）——否则卡改名后关系里还挂着旧名
+          const groupsTouched = await syncCardNodeName(id, newName);
+          return ok({ meta, syncedDraftName: true, groupsTouched });
         }
         case "cc_getLibraryEntry":{
           const id = args.id;
@@ -1019,6 +1521,119 @@ function apply(ctx, config){
           const obj = await loadLibraryEntry(id);
           return ok(obj);
         }
+        // ———————————————— 人物关系图谱（0.8.0）————————————————
+        case "cc_listGroups":{
+          const groups = await listGroups();
+          const entries = await listLibraryEntries();
+          const countOf = (gid) => entries.filter(e => String(e.groupId || "") === gid).length;
+          return ok({ groups: 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,
+          })) });
+        }
+        case "cc_createGroup":{
+          const name = String(args.name || "").trim().slice(0, 60);
+          if(!name) return fail("invalid-name", "分组名不能为空");
+          const g = await writeGroup({ id: newGroupId(), name, note: String(args.note || "").slice(0, 200), nodes: [], edges: [] });
+          return ok({ group: g });
+        }
+        case "cc_renameGroup":{
+          const found = await readGroupRaw(args.id);
+          if(!found) return fail("not-found", "分组不存在: " + String(args.id));
+          const g = normalizeGroup(found.obj);
+          if(typeof args.name === "string" && args.name.trim()) g.name = args.name.trim().slice(0, 60);
+          if(typeof args.note === "string") g.note = args.note.slice(0, 200);
+          return ok({ group: await writeGroup(g) });
+        }
+        case "cc_deleteGroup":{
+          const removed = await deleteGroupFile(args.id);
+          if(!removed) return fail("not-found", "分组不存在: " + String(args.id));
+          const gid = safeGroupId(args.id);
+          const entries = await listLibraryEntries();
+          let memberCleared = 0;
+          for(const e of entries){
+            if(String(e.groupId || "") !== gid) continue;
+            try{ await patchLibraryMeta(e.id, { groupId: null }); memberCleared += 1; }catch{}
+          }
+          return ok({ deleted: removed, memberCleared });
+        }
+        case "cc_setCardGroup":{
+          const cardId = String(args.cardId || "");
+          if(!cardId) return fail("invalid-card", "需要 cardId");
+          const want = (args.groupId === null || args.groupId === undefined || args.groupId === "") ? null : safeGroupId(args.groupId);
+          if(want){
+            const found = await readGroupRaw(want);
+            if(!found) return fail("not-found", "分组不存在: " + want);
+            const g = normalizeGroup(found.obj);
+            // 入组时若还没有该卡的节点就自动补一个：用户只需要"把卡拉进组"，不必手工建节点
+            let node = g.nodes.find(n => n.kind === "card" && n.cardId === cardId);
+            if(!node){
+              const card = (await libraryCardsFor([cardId]))[0];
+              node = { id: "n" + (g.nextNodeSeq++), kind: "card", cardId, name: (card && card.name) || "未命名角色", aliases: [], orphanOf: null };
+              g.nodes.push(node);
+              await writeGroup(g);
+            }
+            await patchLibraryMeta(cardId, { groupId: want });
+            return ok({ cardId, groupId: want, nodeId: node.id });
+          }
+          await patchLibraryMeta(cardId, { groupId: null });
+          return ok({ cardId, groupId: null });
+        }
+        case "cc_getGroup":{
+          const found = await readGroupRaw(args.id);
+          if(!found) return fail("not-found", "分组不存在: " + String(args.id));
+          const g = normalizeGroup(found.obj);
+          const cards = await libraryCardsFor(await groupMemberIds(g.id));
+          return ok({ group: g, members: cards.map(c => ({ id: c.id, name: c.name })), rev: g.rev });
+        }
+        case "cc_patchGroup":{
+          const found = await readGroupRaw(args.id);
+          if(!found) return fail("not-found", "分组不存在: " + String(args.id));
+          const cur = normalizeGroup(found.obj);
+          if(typeof args.expectedRev === "number" && args.expectedRev !== cur.rev){
+            return fail("stale-rev", "分组已被外部修改（期望 rev=" + args.expectedRev + "，实际 rev=" + cur.rev + "）—— 先重新读取再改", { staleRev: true, expectedRev: args.expectedRev, actualRev: cur.rev });
+          }
+          const applied = applyGroupOps(cur, args.ops);
+          if(!applied.applied.length) return ok({ group: cur, applied: [], rejected: applied.rejected, changed: false });
+          const saved = await writeGroup(applied.group);
+          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);
+          return ok(Object.assign({ groupId: g.id, rev: g.rev, name: g.name }, checkGroup(g, memberIds, cards)));
+        }
+        case "cc_renderRelations":{
+          // 渲染进**当前草稿**（与工具半共用同一份草稿文件）；要落库仍需再存一次
+          const k = draftKeyFrom(ctx, args);
+          const origin = readDraftOrigin(k);
+          const cardId = args.cardId ? String(args.cardId) : ((origin && origin.libraryId) || "");
+          if(!cardId) return fail("no-card", "这张草稿还没入库（没有来源卡 id）：先在工坊「保存当前」或显式传 cardId");
+          const mine = (await listLibraryEntries()).find(e => e.id === cardId);
+          const groupId = args.groupId ? safeGroupId(args.groupId) : ((mine && mine.groupId) ? String(mine.groupId) : "");
+          if(!groupId) return fail("no-group", "这张卡还没有加入任何分组");
+          const found = await readGroupRaw(groupId);
+          if(!found) return fail("not-found", "分组不存在: " + groupId);
+          const g = normalizeGroup(found.obj);
+          const myNode = g.nodes.find(n => n.kind === "card" && n.cardId === cardId);
+          if(!myNode) return fail("no-node", "分组里没有这张卡的节点：先在工坊关系视图里把它加入分组");
+          const section = renderRelationsSection(myNode.id, g.nodes, g.edges, { includeIncoming: args.includeIncoming === true });
+          const draft = getDraftFor(k);
+          const before = String((draft.data && draft.data.description) || "");
+          const after = spliceRelations(before, section, "rev=" + g.rev + " group=" + g.id);
+          const changed = before !== after;
+          if(args.dryRun === true) return ok({ changed, preview: after, section, groupId: g.id, rev: g.rev });
+          if(changed){
+            const copy = JSON.parse(JSON.stringify(draft));
+            copy.data.description = after;
+            setDraftFor(k, copy);
+          }
+          return ok({ changed, groupId: g.id, rev: g.rev, description: after });
+        }
         case "cc_importFromPng":{
           const b64 = args.b64;
           if(typeof b64!=="string" || !b64) return fail("invalid-b64","b64 必填");
@@ -1137,7 +1752,14 @@ export { apply, inject, name, planPresetInstall, installCcPreset, supportsDeclar
   draftKeyPartsFrom, draftContentSummary, listDraftSlotsOnDisk, migrateDraftDecision,
   // 落盘根与 lib 层 CRUD（供回归测试直接断言「DSH_HOME 优先 + 读时回退」）
   dshHomeDir, legacyDshHomeDir, dataRoots, draftDirs, draftDir, draftPath, findDraftPath, safeDraftFile,
-  persistDraftSync, loadPersistedDraftSync, libDirs, libDir,
-  listLibraryEntries, saveLibraryEntry, loadLibraryEntry, deleteLibraryEntry, renameLibraryEntry };
+  persistDraftSync, loadPersistedDraftSync, libDirs, libDir, getDraftFor, setDraftFor, cardFingerprint, normalizeCardShape,
+  // 草稿来源 id 的 sidecar（0.5.0）：两半同构，测试直接交叉读写验证互通
+  readDraftOrigin, writeDraftOrigin, originFilePath,
+  listLibraryEntries, saveLibraryEntry, loadLibraryEntry, deleteLibraryEntry, renameLibraryEntry,
+  // 人物关系图谱（0.8.0）：纯函数 + 落盘，供 tests/relations.test.mjs 直接断言、并与工具半逐字比对同构实现
+  groupDirs, groupDir, groupPath, safeGroupId, newGroupId, normalizeGroup, validateGroupOp, applyGroupOps,
+  renderRelationsSection, spliceRelations, checkGroup, listGroups, readGroupRaw, writeGroup, deleteGroupFile,
+  groupMemberIds, libraryCardsFor, patchLibraryMeta, orphanCardNodes, syncCardNodeName, estimateTokensLite,
+  REL_TYPES, REL_TYPE_LABELS, REL_BEGIN, REL_END };