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

package/README.md

@@ -14,7 +14,7 @@ DSH（DeepSeek Harness）插件：输入框上方的胶囊 → 全屏融合工
 
 | 项目 | 值 |
 | --- | --- |
-| 包名 / 版本 | `@xia-sc/dsh-cc-studio` `0.7.1` |
+| 包名 / 版本 | `@xia-sc/dsh-cc-studio` `0.8.1` |
 | 兼容 | DSH `>=0.1.5-rc.1`（含**桌面版**）、Node `>=22`、**零运行依赖**；逐版本实测见 [兼容与权限](#兼容与权限) |
 | 落盘位置 | `<DSH_HOME>/cc-library/`（角色卡）、`<DSH_HOME>/cc-drafts/`（会话草稿）；`DSH_HOME` 默认 `~/.dsh`，旧位置仍读得到 |
 | 文档 | 用户文档＝本文件；改代码前必读 [AGENTS.md](./AGENTS.md)；完整历史 [CHANGELOG.md](./CHANGELOG.md) |
@@ -117,7 +117,7 @@ dsh plugin --profile web remove @xia-sc/dsh-cc-studio       # 卸载（同时移
 - **导入导出**：`⬆ 导入 JSON/PNG/CHARX` 自动识别容器；`⬇ JSON`、`⬇ PNG`（1×1 占位图）、`⬆ 写入 PNG`（写入你上传的任意 PNG，自动剥离旧 `ccv3/chara` 块并重算 CRC32）、`⬇ CHARX`（打包 `card.json`）。
 - **中英双语 + 深浅色**：完整 `zh / en` 词表，跟随 `设置 → 通用 → 语言` 实时切换；配色走 `var(--dsw-alias-*)`，主操作固定品牌紫 `#7c5cff`。
 
-### CC 模式（模型侧 19 个 Tool）
+### CC 模式（模型侧 23 个 Tool）
 
 **6 步工作流 + 共创约束**：每步前必须先问偏好，严禁无讨论就一次性填满；世界书的完成态是「**≥5 条且至少 1 条共创**」（纯自动条目不算完成）。每次返回只有一份 `workflow.next`（下一步）+ `workflow.state`（四项三态进度）+ `message`（给用户的一句话），另有 `build` 标明插件版本。
 
@@ -127,6 +127,7 @@ dsh plugin --profile web remove @xia-sc/dsh-cc-studio       # 卸载（同时移
 | 世界书质量 | `cc_simulate_trigger`（拿一句用户会说的话验命中）/ `cc_lint_lorebook`（静态体检，含**最坏情况单次触发量**）/ `cc_patch_book_meta`（命名 / `scan_depth` / `token_budget` / 递归扫描） |
 | 条目管理 | `cc_update_lorebook_entry` / `cc_delete_lorebook_entries` |
 | 导出与起点 | `cc_preview_export`（体积、估算 token、字段清单、重复内容量）/ `cc_new_card`（破坏性，须用户同意后带 `confirm:true`） |
+| 人物关系（0.8.0） | `cc_get_relations` / `cc_patch_relations` / `cc_render_relations` / `cc_group_check` |
 | 已存库 CRUD | `cc_list_library` / `cc_save_to_library` / `cc_load_from_library` / `cc_delete_from_library` / `cc_rename_in_library` / `cc_get_library_entry` |
 
 几条值得知道的约定：
@@ -136,6 +137,13 @@ dsh plugin --profile web remove @xia-sc/dsh-cc-studio       # 卸载（同时移
 - 写类工具支持 **`expectedRev` 乐观锁**；不传也会在返回里给 `revDrift` 与 `draftStatus.watchedRev`，多端同时改卡时不会静默覆盖。
 - 工具返回的 `build` 与 `package.json` 的 `version` 同步 —— 能一眼确认当前跑的是哪一版代码。
 
+### 群聊与人物关系（0.8.0）
+
+做一批「互相有关系的卡」时，CCv3 没有关系字段 —— 硬造会污染导出、别的客户端也不认。所以分成两层：
+
+- **插件层图谱是真源**：在工坊右侧「已存角色」里新建**分组**，把同一世界观的角色拉进去，再用分组旁的「关系」按钮打开**关系视图**维护关系 —— 三维 = **方向（A→B 与 B→A 可以不同）× 类型（师徒 / 恋慕 / 敌对…10 类）× 强度（1-5）**。节点有两类：有独立卡的角色，以及**卡内 NPC**（如「柳长老」，没有自己的卡）—— 所以同一张图谱既能服务多卡群聊，也能让单卡「立体」。数据落在 `<DSH_HOME>/cc-groups/`，**不写进卡的任何 CCv3 字段**。
+- **渲染让卡自包含**：「渲染到当前卡」会把「我的关系」写进 `description` 的固定标记区（`<!-- cc-relations:begin --> … <!-- cc-relations:end -->`），分享出去的卡别人拿到就能用；重复渲染是**替换**，不会越写越长。模型侧对应 `cc_render_relations`（支持 `dryRun` 预览）。
+- **跨卡体检**（关系视图的「体检」/ `cc_group_check`）会报：孤儿节点（卡已删）、悬空关系、重名节点、未渲染或已过期的关系段，以及**群聊每轮固定开销**（成员卡常驻条目之和 vs 预算）—— 群聊的开销是「乘法」：5 张卡各带一条常驻，每轮就是 5 份。
 ### 校验与导出
 
 - 宿主实时校验：`spec: chara_card_v3` / `spec_version: 3.0` / `group_only_greetings` 必填、主图标唯一、正则合法；`cc_validate` 另给逐项 errors 与 warnings（缺字段、keys 质量问题、预算等）。
@@ -163,8 +171,8 @@ dsh plugin --profile web remove @xia-sc/dsh-cc-studio       # 卸载（同时移
 ## 开发与测试
 
 ```bash
-npm test                                    # 11 个文件、464 项断言，全绿才算过
-node tests/tools-contract.test.mjs          # 只跑 CC 工具链契约（84 项）
+npm test                                    # 12 个文件、512 项断言，全绿才算过
+node tests/tools-contract.test.mjs          # 只跑 CC 工具链契约（88 项）
 ```
 
 - 改 `lib/client.js`：刷新页面即可；改 `lib/index.js` / 预设：**重启 dsh**。
@@ -174,6 +182,7 @@ node tests/tools-contract.test.mjs          # 只跑 CC 工具链契约（84 项
 
 完整历史见 [CHANGELOG.md](./CHANGELOG.md)。最近三版都是「另一个 LLM 以工具使用者身份跑回归」挖出来的问题：
 
+- `0.8.0` **人物关系图谱与群聊分组**：CCv3 没有关系字段 → 插件层图谱（`<DSH_HOME>/cc-groups/`）做真源，三维（方向 × 类型 × 强度），节点分「有独立卡的角色」与「卡内 NPC」；`cc_render_relations` 把关系渲染进 `description` 的固定标记区让卡自包含（幂等、可 `dryRun`、空图谱 = 清空）。新增 4 个工具（19 → 23）与工坊侧的**分组选择器 + 关系视图**（`s.cur === 4`，不进左侧导航）。另修 `cc_save_to_library` 的 `action` 谎报（传库里不存在的 id 派生新卡时报 updated）与 `cc_render_relations` 漏赋值（`changed:true` 却没写进卡）。测试 464 → 509 项。**需重启 dsh（桌面版重启应用）**。- `0.8.1` 修 0.8.0 关系/分组 UI 的三个「点了没反应」：**「＋ 组」依赖 `window.prompt`**（内嵌 webview 拦掉原生对话框 → 静默返回）→ 改内联输入框，关系视图的「＋ NPC」同改；**面板打开时从没拉过分组列表** → 卡片上的归组下拉只有「未分组」、新建的组不出现，现已补上；**「关系」按钮在「全部/未分组」下静默禁用** → 改为可点并有提示。另外宿主半没重启时会明确提示「请重启 dsh」。**客户端改动刷新页面即可；宿主端点需重启过 dsh**。
 - `0.7.1` 修 **B1**：dsh 重启后第一次 `cc_get_card` 报 `value is not lossless JSON` —— DSH 对返回值做 lossless-JSON 校验，**任何嵌套 `undefined` 都会让整次调用失败**，而外部导入的卡（PNG / CHARX）可能整个缺 `spec_version` / `creation_date`。三层修法：加载即补齐（`normalizeCardShape`）、`creation_date` 兜底 `null`、返回前统一 `sanitizeJson()`。另加 `build` 版本标识与 `watchedRev`，`changed` 与 `rev` 改用同一套判据。
 - `0.7.0` 修 **N2**：长五维 + autoLorebook 原文照搬会让**一句话**吃满整份世界书预算（实测 1139 token / 预算 1200），而调大 `token_budget` 还能把告警一并消掉 → `cc_lint_lorebook` 新增**最坏情况单次触发量**。另修：`creator` 此前**没有写入路径**（validate 却一直催）、主动重置不再被误报「内容可能已丢失」、不传 `expectedRev` 也会提示 `revDrift`、空改动不再消耗 `rev`。
 - `0.6.0` 修 **P0-6**：草稿被外部（工坊 / host 恢复）换掉时模型完全无感知，实测因此误伤过另一张卡 → 每个返回都带 `cardName` / `cardId` / `rev`，`getDraft()` 以盘为准重载，写类工具支持 `expectedRev` 乐观锁。

package/lib/agent.js

@@ -12,7 +12,7 @@ const name = "dsh-cc-studio-agent";
 // 由来：第五轮实测里测试者第一遍跑出「四项全无变化」，其实只是**没重启 dsh** —— LLM 侧完全无法
 // 分辨「代码没改」和「改了但没加载」。有了这个字段，任何一次调用都能先确认自己测的是哪一版。
 // 发版时与 package.json 的 version 同步。
-const BUILD = "0.7.1";
+const BUILD = "0.8.1";
 const inject = ["tools", "agents"];
 
 function nowSec(){ return Math.floor(Date.now()/1000); }
@@ -317,6 +317,323 @@ function setDraft(ctx, draft, exec){
   return draft;
 }
 
+// ——————————————————————————————————————————————————————————————
+// 人物关系图谱（0.8.0）：分组文件 + 三维关系（方向 × 类型 × 强度）
+//
+// 与 lib/index.js **同构实现**（与 dataRoots / safeDraftFile 同模式）：同样的常量、同样的纯函数、
+// 同样的落盘规则（写主根、读回退旧根）。tests/relations.test.mjs 会逐字比对两半渲染输出 ——
+// 改这里必须同步改 lib/index.js，反之亦然。
+//
+// 「卡属于哪个组」记在库条目 meta.groupId（单一真源），分组文件里刻意**不存成员列表**。
+// 关系只活在插件侧；要让分享出去的卡自包含，用 cc_render_relations 渲染进 description 的固定标记区。
+// ——————————————————————————————————————————————————————————————
+const REL_TYPES = ["family","romance","mentor","friend","colleague","rival","enemy","debt","superior","other"];
+const REL_TYPE_LABELS = { family:"亲属", romance:"恋慕", mentor:"师徒", friend:"挚友", colleague:"同门", rival:"竞争", enemy:"敌对", debt:"恩义", superior:"上下级", other:"其他" };
+const REL_BEGIN = "<!-- cc-relations:begin";
+const REL_END = "<!-- cc-relations:end -->";
+
+function groupDirs(){ return dataRoots("cc-groups"); }
+function groupDir(){ return groupDirs()[0]; }
+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{} }
+/** 与 lib/index.js 同构：那边叫 estimateTokensLite（宿主半没有 token 估算），这里复用本半已有的 estimateTokens。 */
+function estimateTokensLite(text){ return estimateTokens(text); }
+function relTypeOf(t){ const s = String(t == null ? "" : t); return REL_TYPES.indexOf(s) >= 0 ? s : "other"; }
+function relLabel(edge){ return (edge && edge.label && String(edge.label).trim()) ? String(edge.label).trim() : (REL_TYPE_LABELS[(edge && edge.type) || "other"] || "其他"); }
+function nameOfNode(nodes, id){ const n = (Array.isArray(nodes) ? nodes : []).find(x => x.id === id); return n ? (n.name || "未命名") : "（未知）"; }
+
+/** 结构兜底。⚠️ 不丢弃端点不存在的边（那是用户数据），体检报 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);
+  });
+}
+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;
+}
+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 };
+}
+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");
+}
+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();
+}
+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);
+  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{ seen.set(id, normalizeGroup(JSON.parse(await readFile(join(dir, f), "utf8")))); }catch{}
+    }
+  }
+  return [...seen.values()].sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0));
+}
+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;
+}
+async function groupMemberIds(groupId){
+  const gid = safeGroupId(groupId);
+  const entries = await listLibraryEntries();
+  return entries.filter(e => String(e.groupId || "") === gid).map(e => e.id);
+}
+/** 体检 / 渲染需要的卡片摘要（卡不在库里就跳过）。 */
+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;
+}
+/** 解析「这次操作哪个分组」：显式 groupId 优先，否则用当前卡（来源 id → 库 meta.groupId）所属组。 */
+async function resolveGroupFor(ctx, exec, explicitGroupId){
+  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;
+  const groupId = explicitGroupId ? safeGroupId(explicitGroupId) : ((mine && mine.groupId) ? String(mine.groupId) : "");
+  const memberCount = {};
+  entries.forEach(e => { const gid = String(e.groupId || ""); if(gid) memberCount[gid] = (memberCount[gid] || 0) + 1; });
+  const groups = (await listGroups()).map(g => ({ id: g.id, name: g.name, nodeCount: g.nodes.length, edgeCount: g.edges.length, memberCount: memberCount[g.id] || 0 }));
+  if(!groupId) return { ok: false, cardId: cardId || null, groupId: "", groups };
+  const found = await readGroupRaw(groupId);
+  if(!found) return { ok: false, cardId: cardId || null, groupId, groups, error: "分组不存在：" + groupId };
+  const g = normalizeGroup(found.obj);
+  const myNode = cardId ? (g.nodes.find(n => n.kind === "card" && n.cardId === cardId) || null) : null;
+  return { ok: true, cardId, groupId, group: g, myNode, groups };
+}
+
 // —— 已存角色库：<主根>/cc-library/<id>.json（读盘回退 0.3.6 之前的 homedir()/.dsh）——
 function libDirs(){ return dataRoots("cc-library"); }
 function libDir(){ return libDirs()[0]; }
@@ -1055,8 +1372,12 @@ function apply(ctx){
       const res=await saveLibraryEntry(draft, { id: targetId || undefined, name: args.name });
       // 记来源：下次不传 id 时沿用同一张（cc_new_card / 工坊清空草稿会清掉它）
       writeOriginSync(k, res.id, res.meta.name);
-      return { ok:true, action: targetId ? "updated" : "created", id:res.id, meta:res.meta, loreCount:res.meta.loreCount,
-        message: (targetId ? "已更新已存卡「" : "已新建已存卡「") + res.meta.name + "」（id " + res.id + "）。" + (targetId ? "" : "下次保存（不传 id）会更新这一张。") };
+      // 0.8.0 修：action 与文案都用 saveLibraryEntry 的**实测判定**（它按「该 id 的文件是否已存在」算）。
+      // 旧写法 `targetId ? "updated" : "created"` 在「传一个库里不存在的新 id」时会谎报 updated ——
+      // 而那正是群聊场景「从母卡派生出多张角色卡」的唯一路径，模型会以为自己覆盖了别人、不敢继续。
+      const created = res.action === "created";
+      return { ok:true, action: res.action, id:res.id, meta:res.meta, loreCount:res.meta.loreCount,
+        message: (created ? "已新建已存卡「" : "已更新已存卡「") + res.meta.name + "」（id " + res.id + "）。" + (created ? "下次保存（不传 id）会更新这一张。" : "") };
     }
   });
   tool({
@@ -1295,6 +1616,185 @@ function apply(ctx){
     }
   });
 
+  // ——————————————————————————————————————————————————————————————
+  // 0.8.0 新增工具：人物关系图谱（4 个）
+  // 关系数据活在插件侧（<DSH_HOME>/cc-groups/），**不写进 CCv3 任何字段**；要让分享出去的卡
+  // 自包含，就用 cc_render_relations 把关系渲染进 description 的固定标记区。
+  // 分组本身由用户在工坊右侧「已存角色」里创建与维护（「同一世界观拉进同一组」），工具侧只读写关系。
+  // ——————————————————————————————————————————————————————————————
+
+  tool({
+    name: "cc_get_relations",
+    description: "【关系·读】查看当前卡所在分组的人物关系网（三维：方向 from→to / 类型 type / 强度 strength 1-5）。默认只回与当前卡相关的边（省上下文）。关系存在插件侧、不写进卡；卡还没入库或没入组时会明确告知并列出现有分组 —— 别硬猜分组 id。改关系用 cc_patch_relations，写进卡里用 cc_render_relations。",
+    parameters: {
+      type:"object",
+      properties:{
+        groupId:{ type:"string", description:"可选：显式指定分组 id（默认用当前卡所属分组）" },
+        scope:{ type:"string", enum:["mine","all"], description:"mine（默认）= 只回与当前卡相关的边；all = 回整组节点与边" },
+        includeNodes:{ 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: (r.cardId ? "这张卡（" + r.cardId + "）还没有加入任何分组。" : "当前草稿还没有关联已存卡（没有来源 id）。")
+            + "关系网按分组组织：请让用户在工坊右侧「已存角色」里新建分组、把同一世界观的卡拉进同一组，然后重试。现有分组："
+            + (r.groups.length ? r.groups.map(g => g.name + "（" + g.id + "，" + g.memberCount + " 卡 / " + g.edgeCount + " 关系）").join("；") : "（暂无）") };
+      }
+      const g = r.group, myNode = r.myNode;
+      const scope = (args.scope === "all") ? "all" : "mine";
+      const edges = (scope === "all" || !myNode) ? g.edges.slice() : g.edges.filter(e => e.from === myNode.id || e.to === myNode.id);
+      const needIds = new Set();
+      edges.forEach(e => { needIds.add(e.from); needIds.add(e.to); });
+      if(myNode) needIds.add(myNode.id);
+      const nodes = g.nodes.filter(n => scope === "all" || needIds.has(n.id) || n.kind === "card");
+      const res = { ok:true,
+        group: { id: g.id, name: g.name, rev: g.rev },
+        cardId: r.cardId || null, myNodeId: myNode ? myNode.id : null, scope,
+        edges: edges.map(e => ({
+          id: e.id, from: e.from, to: e.to,
+          fromName: nameOfNode(g.nodes, e.from), toName: nameOfNode(g.nodes, e.to),
+          type: e.type, typeLabel: REL_TYPE_LABELS[e.type] || e.type, label: e.label || "",
+          strength: e.strength, direction: e.direction, note: e.note,
+          mine: myNode ? (e.from === myNode.id ? "out" : (e.to === myNode.id ? "in" : null)) : null,
+        })),
+        groups: r.groups,
+        message: "分组「" + g.name + "」共 " + g.nodes.length + " 个节点 / " + g.edges.length + " 条关系"
+          + (scope === "mine" ? "；与当前卡相关 " + edges.length + " 条。" : "。") };
+      if(args.includeNodes !== false) res.nodes = nodes.map(n => ({ id:n.id, kind:n.kind, cardId:n.cardId, name:n.name, aliases:n.aliases, orphan: n.kind === "card" && !n.cardId }));
+      return res;
+    }
+  });
+
+  tool({
+    name: "cc_patch_relations",
+    description: "【关系·改】增删改人物关系（三维：方向 from→to / 类型 type / 强度 strength）。ops 是动作数组：{op:\"addNode\",kind:\"npc\"|\"card\",cardId?,name,aliases?} / {op:\"updateNode\",nodeId,name?,aliases?} / {op:\"removeNode\",nodeId,removeEdges?} / {op:\"addEdge\",from,to,type,strength,direction,note?} / {op:\"updateEdge\",edgeId,同 addEdge 的字段} / {op:\"removeEdge\",edgeId}。type 取值 family/romance/mentor/friend/colleague/rival/enemy/debt/superior/other；direction：mutual=对等（一条边即可）｜one-way=不对称（A→B 与 B→A 可以不同，这正是「三维」的价值）。**只改插件侧图谱**，要进卡请再调 cc_render_relations。删节点/删边是破坏性操作，先与用户确认。",
+    parameters: {
+      type:"object",
+      properties:{
+        groupId:{ type:"string", description:"可选：默认用当前卡所属分组" },
+        ops:{ type:"array", items:{ type:"object", additionalProperties:true }, description:"动作数组，逐项见工具说明" },
+        expectedGroupRev:{ type:"number", description:"可选乐观锁：传上次 cc_get_relations 返回的 group.rev。**注意与 expectedRev 不同** —— expectedRev 是草稿的版本号（包装层统一校验），这里校验的是**分组图谱**的版本" },
+      },
+      required:["ops"],
+      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 g = r.group;
+      // ⚠️ 分组 rev 与草稿 rev 是两件事：expectedGroupRev 校验**图谱**，expectedRev（包装层）校验**草稿**。
+      // 曾经两者同名，结果传分组 rev 会被包装层当成草稿 rev 拒掉（且错误文案说「草稿已被外部修改」，极具误导性）。
+      if(typeof args.expectedGroupRev === "number" && args.expectedGroupRev !== g.rev){
+        return { ok:false, staleRev:true, expectedGroupRev: args.expectedGroupRev, actualRev: g.rev,
+          group: { id: g.id, name: g.name, rev: g.rev },
+          error: "分组「" + g.name + "」已被外部修改（期望 rev=" + args.expectedGroupRev + "，实际 rev=" + g.rev + "）—— 先 cc_get_relations 重新读一遍再改。" };
+      }
+      const applied = applyGroupOps(g, args.ops);
+      if(!applied.applied.length){
+        return { ok:false, error:"没有任何 op 生效（原因见 rejected）", rejected: applied.rejected, group: { id: g.id, name: g.name, rev: g.rev } };
+      }
+      const saved = await writeGroup(applied.group);
+      return { ok:true, applied: applied.applied, rejected: applied.rejected,
+        group: { id: saved.id, name: saved.name, rev: saved.rev },
+        nodes: saved.nodes.map(n => ({ id:n.id, kind:n.kind, name:n.name, cardId:n.cardId, aliases:n.aliases })),
+        edges: saved.edges.map(e => ({ id:e.id, from:e.from, to:e.to, type:e.type, strength:e.strength, direction:e.direction, note:e.note })),
+        message: "已改 " + applied.applied.length + " 项"
+          + (applied.rejected.length ? "（" + applied.rejected.length + " 项被拒：" + applied.rejected.map(x => x.error).join("；") + "）" : "")
+          + "。图谱 rev=" + saved.rev + "；把关系写进卡里请再调 cc_render_relations，并 cc_save_to_library 落库。" };
+    }
+  });
+
+  tool({
+    name: "cc_render_relations",
+    description: "【关系·渲染】把当前卡在图谱里的关系渲染进 description 的固定标记区（<!-- cc-relations:begin --> … <!-- cc-relations:end -->），让**导出的卡自包含** —— 别人拿到卡就能看到这些关系，不依赖插件数据。默认只写「我对别人的看法」（出边）；includeIncoming:true 时追加一节「他们眼中的我」。dryRun:true 只回预览不改动。渲染后要 cc_save_to_library 才落库；重复渲染是**替换**，不会越写越长。",
+    parameters: {
+      type:"object",
+      properties:{
+        groupId:{ type:"string", description:"可选：默认用当前卡所属分组" },
+        includeIncoming:{ type:"boolean", description:"是否额外渲染「他们眼中的我」（默认 false）" },
+        dryRun:{ type:"boolean", description:"true = 只回预览、不改草稿" },
+        expectedGroupRev:{ type:"number", description:"可选乐观锁：**分组** rev 不符则拒绝（与草稿的 expectedRev 不同）" },
+      },
+      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 g = r.group;
+      if(!r.myNode){
+        return { ok:false, error:"分组「" + g.name + "」里没有这张卡的节点：先在工坊关系视图里把它加入分组（或用 cc_patch_relations 加一个 kind:\"card\" 的节点）。" };
+      }
+      if(typeof args.expectedGroupRev === "number" && args.expectedGroupRev !== g.rev){
+        return { ok:false, staleRev:true, expectedGroupRev: args.expectedGroupRev, actualRev: g.rev,
+          error:"分组「" + g.name + "」已被外部修改（期望 rev=" + args.expectedGroupRev + "，实际 rev=" + g.rev + "）—— 先 cc_get_relations 重读再渲染。" };
+      }
+      const section = renderRelationsSection(r.myNode.id, g.nodes, g.edges, { includeIncoming: args.includeIncoming === true });
+      const cur = JSON.parse(JSON.stringify(getDraft(ctx, exec)));
+      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;
+      if(args.dryRun === true){
+        return { ok:true, dryRun:true, changed, outgoing, section, preview: after,
+          group: { id: g.id, name: g.name, rev: g.rev },
+          message: "预览：将写入 " + outgoing + " 条关系（" + (changed ? "description 会变化" : "与现状一致，无需重写") + "）。" };
+      }
+      if(changed){
+        // ⚠️ 这一行曾经漏掉：changed 算出来了、setDraft 也调了，但 description 还是旧值 —— 表现是
+        // 「返回 changed:true 而卡里什么都没变」，而且不好看出来（rev 照样递增）。
+        cur.data.description = after;
+        setDraft(ctx, cur, exec);
+      }
+      return { ok:true, changed, changedFields: changed ? ["description"] : [], outgoing, description: after,
+        group: { id: g.id, name: g.name, rev: g.rev }, workflow: workflowStatus(cur),
+        message: (changed ? "已把 " + outgoing + " 条关系写进 description 的【关系】段" : "description 里已经是最新关系，无需改动")
+          + "。注意：这只改了**当前草稿**，要落库请再调 cc_save_to_library（或让用户在工坊点「保存当前」）。" };
+    }
+  });
+
+  tool({
+    name: "cc_group_check",
+    description: "【关系·体检】跨卡检查一个分组：孤儿节点（卡已删除）、悬空关系、重名节点（渲染会指向同一个人）、未渲染/已过期的【关系】段，以及**群聊每轮固定开销**（所有成员卡 constant 条目之和 vs 最小预算 —— 群聊时卡越多这块钱越贵，一张卡的单卡体检看不出来）。做完一批群聊卡后调一次。",
+    parameters: {
+      type:"object",
+      properties:{ groupId:{ type:"string", description:"可选：默认用当前卡所属分组" } },
+      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 g = r.group;
+      const memberIds = await groupMemberIds(g.id);
+      const cards = await libraryCardsFor(memberIds);
+      const res = checkGroup(g, memberIds, cards);
+      const errorCount = res.issues.filter(i => i.level === "error").length;
+      return { ok:true,
+        group: { id: g.id, name: g.name, rev: g.rev },
+        issues: res.issues, stats: res.stats,
+        errorCount, warningCount: res.issues.length - errorCount,
+        members: cards.map(c => ({ id: c.id, name: c.name })),
+        message: res.issues.length
+          ? "分组「" + g.name + "」发现 " + res.issues.length + " 个问题（" + errorCount + " 个会真的不工作）：" + res.issues.map(i => i.message).join("；")
+          : "分组「" + g.name + "」体检通过：" + res.stats.members + " 张成员卡 / " + res.stats.edges + " 条关系，没有结构性问题。" };
+    }
+  });
+
   // 【导出干跑】补上「五维到底导不导出」这个此前没人能回答的问题
   tool({
     name: "cc_preview_export",
@@ -1393,4 +1893,8 @@ function apply(ctx){
   });
 }
 
-export { apply, inject, name, safeDraftFile, draftDirs, libDirs, dataRoots, originPath, readOriginSync, writeOriginSync };
+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,
+  REL_TYPES, REL_TYPE_LABELS, REL_BEGIN, REL_END };