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

package/lib/index.js

@@ -384,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(){
@@ -610,6 +931,9 @@ function makeLibraryEntryMeta(draft, existingMeta, id){
     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,
   };
@@ -669,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 是失败」的既有语义）。
@@ -1079,7 +1469,10 @@ function apply(ctx, config){
           // 允许保存未完全校验的草稿，但至少需要 name？不强制，meta 会兜底“未命名角色”
           const res = await saveLibraryEntry(draft, { id: targetId || undefined, name: args.name });
           writeDraftOrigin(k, res.id, res.meta.name);
-          return ok({ id: res.id, meta: res.meta, action: targetId ? "updated" : "created" });
+          // 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;
@@ -1100,8 +1493,10 @@ function apply(ctx, config){
           await deleteLibraryEntry(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 });
+          return ok({ id, remaining: entries.length, originCleared: wasOrigin, groupsTouched });
         }
         case "cc_setOrigin":{
           // 前端显式设/清「当前草稿的来源 id」：id 传 null/空 = 清（清空草稿、另存为新时用）
@@ -1116,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, syncedDraftName: true });
+          // 0.8.0：图谱节点名跟着改（按 cardId 匹配）——否则卡改名后关系里还挂着旧名
+          const groupsTouched = await syncCardNodeName(id, newName);
+          return ok({ meta, syncedDraftName: true, groupsTouched });
         }
         case "cc_getLibraryEntry":{
           const id = args.id;
@@ -1124,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 必填");
@@ -1245,6 +1755,11 @@ export { apply, inject, name, planPresetInstall, installCcPreset, supportsDeclar
   persistDraftSync, loadPersistedDraftSync, libDirs, libDir, getDraftFor, setDraftFor, cardFingerprint, normalizeCardShape,
   // 草稿来源 id 的 sidecar（0.5.0）：两半同构，测试直接交叉读写验证互通
   readDraftOrigin, writeDraftOrigin, originFilePath,
-  listLibraryEntries, saveLibraryEntry, loadLibraryEntry, deleteLibraryEntry, renameLibraryEntry };
+  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 };
 
 

package/package.json

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