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

package/lib/agent.js

@@ -14,15 +14,46 @@ import { REL_TYPES, REL_TYPE_LABELS, REL_BEGIN, REL_END,
   WORLD_DIMS, AUTO_NAMES, isAutoEntry, looksLikeLegacyAuto,
   estimateTokens, lorebookTokens, contentKeyOf, scanSharedEntries,
   assembleScope, groupMetrics, lorebookMetrics, metricsBrief, auditLoreEntries, runGroupChecks } from "./group-layer.js";
+// 草稿锁的判定与常量（0.11.0）：两半共用 lib/draft-lock.js —— 「锁算不算 active / 超时算不算过期」只有一份实现。
+// 与 group-layer.js 同一个教训：两半各写一份判定必然漂移，一边说锁住了、另一边照写，比没有锁更危险。
+// 这里只 import 工具半真正用到的：上锁时写 owner、读回时归一、返回时给摘要。
+import { LOCK_OWNER_LLM, normalizeLock, lockSummary } from "./draft-lock.js";
 const name = "dsh-cc-studio-agent";
 // 版本标识（0.7.1）：每次工具返回都带 `build`。
 // 由来：第五轮实测里测试者第一遍跑出「四项全无变化」，其实只是**没重启 dsh** —— LLM 侧完全无法
 // 分辨「代码没改」和「改了但没加载」。有了这个字段，任何一次调用都能先确认自己测的是哪一版。
 // 发版时与 package.json 的 version 同步。
-const BUILD = "0.10.0";
+const BUILD = "0.11.0";
 const inject = ["tools", "agents"];
 
 function nowSec(){ return Math.floor(Date.now()/1000); }
+
+// ── 字面转义解码（0.10.3，用户实机报告 P1）──────────────────────────────────────────
+// 模型在 tool call 的 JSON 里经常把换行写成**字面** `\n`（JSON 层多转义一层：`"A\\nB"`），
+// JSON.parse 之后字符串里就是「反斜杠 + n」两个字符。以前这些工具原样落盘，导出的卡在
+// SillyTavern 里就显示「说完这句话。\n\n下一段」——同一张卡里有的字段正常、有的不正常
+// （模型这次写对了），肉眼极难发现（用户实测 18 次调用里 6 次中招）。
+// 卡内文本没有「字面反斜杠 n」的正当用途，所以写类工具统一把字面 `\n` / `\r` / `\t` 解成
+// 真字符；多层转义（`A\\\\nB`）逐层收敛（最多 4 轮）。只作用于**模型输入的工具参数**，
+// 不动工坊保存与导入路径（那两条链路本来就是真换行）。
+function decodeEscapedText(v){
+  if(typeof v !== "string" || v.indexOf("\\") < 0) return v;
+  var s = v;
+  for(var round = 0; round < 4; round++){
+    var next = s
+      .replace(/\\\\/g, "\u0000")   // 成对反斜杠先占位，避免被下面的 \n 规则重复匹配
+      .replace(/\\n/g, "\n")
+      .replace(/\\r/g, "\r")
+      .replace(/\\t/g, "\t")
+      .replace(/\u0000/g, "\\");
+    if(next === s) break;
+    s = next;
+  }
+  return s;
+}
+/** 工具参数里的文本字段：先解码字面转义，再按旧规则 String()。 */
+function textArg(v){ return decodeEscapedText(String(v == null ? "" : v)); }
+
 function draftsMap(){ if(!globalThis.__CC_DRAFTS__) globalThis.__CC_DRAFTS__ = new Map(); return globalThis.__CC_DRAFTS__; }
 // —— 落盘根（0.3.6 起统一，与 lib/index.js 是同一套）：DSH_HOME 优先，homedir()/.dsh 兜底 ——
 // 草稿与角色库都必须与宿主半算出**同一个路径**，否则又会退化成 issue #5 那种「两边互相看不见」。
@@ -119,6 +150,66 @@ function writeOriginSync(key, libraryId, name){
     writeFileSync(originPath(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{} }
 }
+// —— 草稿锁的 IO（0.11.0）——
+// 背景：LLM 正在工坊草稿里创作 A 卡时，用户点「载入」B 卡会把同一会话槽的草稿整份替换，
+// LLM 已写入但未保存的内容只能从历史对话里捞。现在工具半**每次写草稿**都给这把槽上一把创作锁，
+// 用户侧（宿主 RPC）看到 active 锁就只读 / 进预览；交还由 LLM 调 `cc_release_draft` 完成，
+// 另有 TTL 兜底（防 LLM 崩溃后把工坊永久锁死）。
+//
+// 判定（active / stale / 能不能写）全在 lib/draft-lock.js，两半共用 —— 这里只负责落盘，
+// 与 .origin.json 同模式：<safeDraftFile 去 .json>.lock.json。**不写进草稿 JSON**：
+// 用户只读与 LLM 交还都不重写草稿，草稿的 `rev` 仍然只反映内容变化。
+function draftLockPath(key){ return join(draftDir(), safeDraftFile(key).replace(/\.json$/, ".lock.json")); }
+/** 读锁：主根没有就回退旧根（与草稿/来源 sidecar 同一套规则）。损坏 / key 不符一律当「无锁」（见 normalizeLock）。 */
+function readDraftLockSync(key){
+  const file = safeDraftFile(key).replace(/\.json$/, ".lock.json");
+  for(const dir of draftDirs()){
+    const p = join(dir, file);
+    try{
+      if(!existsSync(p)) continue;
+      return normalizeLock(JSON.parse(readFileSync(p, "utf8")), String(key));
+    }catch(e){}
+  }
+  return null;
+}
+/** 写锁：失败只 console.error 不抛 —— 锁是保护用户数据的附加层，写锁失败不能反过来弄坏一次正常的工具调用。 */
+function writeDraftLockSync(key, lock){
+  try{
+    mkdirSync(draftDir(), { recursive: true });
+    writeFileSync(draftLockPath(key), JSON.stringify(lock, null, 2), "utf8");
+    return true;
+  }catch(e){ try{ console.error("[dsh-cc-studio] persist draft lock failed:", (e && e.message) || e); }catch{} return false; }
+}
+/** 清锁：两个根都删 —— 旧根若残留同一把锁，回退读会把它当成本槽的锁，LLM 的「交还」就不算数了。 */
+function clearDraftLockSync(key){
+  const file = safeDraftFile(key).replace(/\.json$/, ".lock.json");
+  for(const dir of draftDirs()){
+    try{ unlinkSync(join(dir, file)); }catch(e){}
+  }
+}
+function draftLockSummaryFor(key){ return lockSummary(readDraftLockSync(key), nowSec()); }
+/**
+ * 上锁 / 续期：LLM 每次写草稿（含「内容无变化」的空写）都调这里。
+ * `since` 只在第一次上锁时记下来 —— 它回答「从什么时候开始创作」，每次写都重置就没有意义了。
+ * `rev` 取本次落盘后的版本（空写时取内存里记着 / 盘上实际那个），**绝不留 undefined**
+ * （B1 的 lossless-JSON 教训：一个 undefined 就让整次工具调用报错）。
+ */
+function refreshDraftLock(key, draft, rev){
+  const k = String(key);
+  const prev = readDraftLockSync(k);
+  const now = nowSec();
+  const cardName = (draft && draft.data && String(draft.data.name || "").trim()) || "";
+  const lock = {
+    key: k,
+    owner: LOCK_OWNER_LLM,
+    since: (prev && prev.since > 0) ? prev.since : now,
+    updatedAt: now,
+    rev: (typeof rev === "number" && rev > 0) ? rev : ((prev && prev.rev) || 0),
+    cardName: cardName.slice(0, 120),
+  };
+  writeDraftLockSync(k, lock);
+  return lock;
+}
 function draftMeta(key){
   const k = String(key || "default");
   if(!globalThis.__CC_DRAFT_META__.has(k)) globalThis.__CC_DRAFT_META__.set(k, { isNew: false, recovered: false, rev: null, pendingFresh: null });
@@ -144,6 +235,10 @@ function draftStatusFor(key, draft){
     cardId: (origin && origin.libraryId) || null,
     cardName: (draft && draft.data && String(draft.data.name||"").trim()) || "",
     rev: (typeof m.rev === "number") ? m.rev : null,
+    // 草稿锁摘要（0.11.0）：active=true 表示 LLM 正在创作，工坊只读 / 载入只预览。
+    // 无锁时**显式 null**（不是省略）—— 客户端与测试都按「有值 = 摘要、null = 无锁」判断，
+    // 而 undefined 还会踩 lossless-JSON（B1）。
+    lock: draftLockSummaryFor(k),
     // watchedRev 由 tool() 包装在调用前捕获后注入：它 = 「本次调用开始前工具半记着的盘上版本」。
     watchedRev: null,
   };
@@ -219,7 +314,7 @@ function makeEmptyCard(){
       first_mes:"", alternate_greetings:[], group_only_greetings:[], mes_example:"",
       creator_notes:"", creator_notes_multilingual:{}, source:[], assets:[{type:"icon",uri:"ccdefault:",name:"main",ext:"png"}],
       creation_date: nowSec(), modification_date: nowSec(),
-      character_book:{ name:"", description:"", scan_depth:4, token_budget:1200, recursive_scanning:false, extensions:{}, entries:[] }
+      character_book:{ name:"", description:"", scan_depth:4, token_budget:2400, recursive_scanning:false, extensions:{}, entries:[] }
     }
   };
 }
@@ -310,17 +405,31 @@ function getDraft(ctx, exec){
 function setDraft(ctx, draft, exec){
   const m = draftsMap();
   const k = keyFor(ctx, exec);
+  const meta = draftMeta(k);
   const prev = m.get(k);
   // N4（0.7.0）：**内容一字未变时不落盘、不递增 rev**。空改动（传了不生效的参数、同值覆盖、
   // 删 0 条条目…）原来也会把 rev 推进一格，于是持有旧 rev 的调用方会无辜失败一次
   // （第四轮实测：`changed: []` 让 rev 7 → 8）。modification_date 也要跟着不动，否则指纹永远不等。
-  if(prev && cardFingerprint(prev) === cardFingerprint(draft)) return draft;
+  if(prev && cardFingerprint(prev) === cardFingerprint(draft)){
+    // 但「内容没变」不代表 LLM 停手了：锁必须**续期**。updatedAt 是「还在创作」的心跳，
+    // 不是「内容变了」的记号 —— 否则 LLM 连着几轮只讨论不改稿，锁会提前超时，
+    // 用户又能趁它还在创作时载入别的卡。rev 优先用内存里记着的（上次自己写下的），
+    // 再退盘上实际那个，绝不留 undefined（B1）。
+    const idleRev = (typeof meta.rev === "number" && meta.rev > 0) ? meta.rev : (draftRevOnDisk(k) || 0);
+    refreshDraftLock(k, draft, idleRev);
+    return draft;
+  }
   draft.data.modification_date = nowSec();
   m.set(k, draft);
   // pendingFresh 刻意不在这里清：新草稿提示由 tool() 包装在**调用之后**统一发，这里清掉就发不出来了。
-  const meta = draftMeta(k); meta.isNew = false; meta.recovered = false;
+  meta.isNew = false; meta.recovered = false;
   const rev = persistDraftSync(k, draft);
-  if(typeof rev === "number") meta.rev = rev;   // 自己写的这一次不算「外部修改」
+  if(typeof rev === "number"){
+    meta.rev = rev;   // 自己写的这一次不算「外部修改」
+    // 写盘成功后上锁 / 续期（0.11.0）：从这一刻起，用户侧对这份草稿的写入一律被拦，
+    // 载入/导入只进只读预览 —— 直到 LLM 自己调 cc_release_draft 或锁超时。
+    refreshDraftLock(k, draft, rev);
+  }
   return draft;
 }
 
@@ -601,7 +710,7 @@ async function libraryCardsFor(ids){
       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,
+      tokenBudget: Number(d.character_book && d.character_book.token_budget) || 2400,
     });
   }
   return out;
@@ -989,7 +1098,7 @@ function progressHint(step, state, worldFilled, loreCount, manualLoreCount, done
     + " " + mark(state.world) + "五维(" + worldFilled + "/5)"
     + " " + mark(state.lore) + "世界书(" + loreCount + (sharedLoreCount ? "+" + sharedLoreCount : "") + (manualLoreCount > 0 ? ",共创" + manualLoreCount : "") + ")"
     + " " + mark(state.greetings) + "问候语"
-    + (done ? " · 已完成，可导出/保存" : "");
+    + (done ? " · 已完成，可导出/保存；记得调用 cc_release_draft 交还编辑权" : "");
 }
 // —— 世界书口径与体检的实现都在 lib/group-layer.js（0.10.0）——
 // estimateTokens / lorebookTokens / lorebookMetrics / auditLoreEntries / worstCaseTrigger 等
@@ -1018,6 +1127,10 @@ function apply(ctx){
       const meta = draftMeta(k);
       const expected = (args && typeof args.expectedRev === "number") ? args.expectedRev : null;
       const beforeRev = draftRevOnDisk(k);
+      // 0.11.0 流程引导：记下本次调用前有没有锁。第一次建立锁时给模型一条明确提示 ——
+      // 只靠 cc_validate 终态的 next 提醒，弱模型经常「写完直接总结」而不调 cc_release_draft，
+      // 工坊就一直只读。让它第一次写草稿时就知道「完成时必须交还」。
+      const lockBefore = readDraftLockSync(k);
       // S1 补充（0.7.1）：把「本次调用开始前工具半记着的盘上版本」捕下来，返回里一并报出 ——
       // 模型可以随时对账：`watchedRev ≠ rev` 就说明这两次调用之间有别人写过。第五轮实测里，
       // 测试者想验证「不传 expectedRev 也能发现漂移」，却在工具序列内造不出漂移（自己写的 rev
@@ -1066,6 +1179,17 @@ function apply(ctx){
               res.warnings = (Array.isArray(res.warnings) ? res.warnings : []).concat([note]);
             }
           }
+          // 首次上锁的流程引导（见函数开头 lockBefore 的注释）：只在「无锁 → 有锁」这一次出现，
+          // 之后每次写只是续期，不再刷屏。
+          if(!lockBefore){
+            const lockAfter = readDraftLockSync(k);
+            if(lockAfter){
+              const lockNote = "🔒 已为当前草稿建立创作锁（工坊在此期间只读、用户载入只进预览）。创作完成时（cc_validate 通过后）**必须调用 cc_release_draft 交还草稿编辑权**，否则用户无法在工坊微调；你继续写会自动续期，不会重复锁。";
+              if(!(Array.isArray(res.warnings) && res.warnings.indexOf(lockNote) >= 0)){
+                res.warnings = (Array.isArray(res.warnings) ? res.warnings : []).concat([lockNote]);
+              }
+            }
+          }
         }
       }catch(e){}
       // B1 的第二道防线：无论各工具返回什么，出门前统一过一遍 JSON 往返，绝不把 `undefined`
@@ -1104,7 +1228,7 @@ function apply(ctx){
 
   tool({
     name: "cc_patch_character",
-    description: "【工作流第2步·共创】写入角色基础（name/nickname/description/personality/scenario/system_prompt/tags）。调用前必须已与用户讨论：至少问 1 个开放问题（如想要的气质/性别/年龄/与你的关系张力/禁忌），拿到用户偏好后再填；禁止仅凭世界观自行推断一次性填满。必须在 cc_get_card 之后、五维之前调用，之后下一步是 cc_patch_world。",
+    description: "【工作流第2步·共创】写入角色基础（name/nickname/description/personality/scenario/system_prompt/tags）。调用前必须已与用户讨论：至少问 1 个开放问题（如想要的气质/性别/年龄/与你的关系张力/禁忌），拿到用户偏好后再填；禁止仅凭世界观自行推断一次性填满。必须在 cc_get_card 之后、五维之前调用，之后下一步是 cc_patch_world。一次只传 1-3 个字段（长字段分多次调用写）；tags 等数组字段单独一次调用。参数必须是严格合法的 JSON（最后一个字段/数组元素后不写逗号，不要 ```json 代码块包裹，不要注释与单引号；字符串内换行要转义）。",
     parameters: {
       type:"object",
       properties:{
@@ -1135,16 +1259,16 @@ function apply(ctx){
       const changed = [];
       // B2（0.7.1）：`changed` 与 `rev` 用同一套判据 —— 只有值真的变了才记改动，否则会出现
       // 「返回说改了 creator、rev 却纹丝不动」这种自相矛盾（第五轮实测 B2）。
-      if(args.name!==undefined) assignIfChanged(cur.data, "name", String(args.name).slice(0,120), changed);
-      if(args.nickname!==undefined) assignIfChanged(cur.data, "nickname", String(args.nickname).slice(0,120), changed);
-      if(args.description!==undefined) assignIfChanged(cur.data, "description", String(args.description).slice(0,5000), changed);
-      if(args.personality!==undefined) assignIfChanged(cur.data, "personality", String(args.personality).slice(0,5000), changed);
-      if(args.scenario!==undefined) assignIfChanged(cur.data, "scenario", String(args.scenario).slice(0,5000), changed);
-      if(args.system_prompt!==undefined) assignIfChanged(cur.data, "system_prompt", String(args.system_prompt).slice(0,3000), changed);
-      if(args.post_history_instructions!==undefined) assignIfChanged(cur.data, "post_history_instructions", String(args.post_history_instructions).slice(0,3000), changed);
-      if(Array.isArray(args.tags)) assignIfChanged(cur.data, "tags", args.tags.map(String).slice(0,12), changed);
-      if(args.creator_notes!==undefined) assignIfChanged(cur.data, "creator_notes", String(args.creator_notes).slice(0,3000), changed);
-      if(args.creator!==undefined) assignIfChanged(cur.data, "creator", String(args.creator).slice(0,120), changed);
+      if(args.name!==undefined) assignIfChanged(cur.data, "name", textArg(args.name).slice(0,120), changed);
+      if(args.nickname!==undefined) assignIfChanged(cur.data, "nickname", textArg(args.nickname).slice(0,120), changed);
+      if(args.description!==undefined) assignIfChanged(cur.data, "description", textArg(args.description).slice(0,5000), changed);
+      if(args.personality!==undefined) assignIfChanged(cur.data, "personality", textArg(args.personality).slice(0,5000), changed);
+      if(args.scenario!==undefined) assignIfChanged(cur.data, "scenario", textArg(args.scenario).slice(0,5000), changed);
+      if(args.system_prompt!==undefined) assignIfChanged(cur.data, "system_prompt", textArg(args.system_prompt).slice(0,3000), changed);
+      if(args.post_history_instructions!==undefined) assignIfChanged(cur.data, "post_history_instructions", textArg(args.post_history_instructions).slice(0,3000), changed);
+      if(Array.isArray(args.tags)) assignIfChanged(cur.data, "tags", args.tags.map(textArg).slice(0,12), changed);
+      if(args.creator_notes!==undefined) assignIfChanged(cur.data, "creator_notes", textArg(args.creator_notes).slice(0,3000), changed);
+      if(args.creator!==undefined) assignIfChanged(cur.data, "creator", textArg(args.creator).slice(0,120), changed);
       setDraft(ctx, cur, exec);
       const wf = await workflowFor(ctx, exec, cur);
       const warnings = [];
@@ -1161,7 +1285,7 @@ function apply(ctx){
 
   tool({
     name: "cc_patch_world",
-    description: "【工作流第3步·共创·必调】写入 5 维世界观（timeline/factions/geo/power/daily 至少 3 项）。若用户已提供世界观文档，先用 2-3 句归纳你理解的 5 维，再问用户“哪几维最想展开？有无私设要加？”；若世界观薄弱，则与用户讨论 1-2 个薄弱点后再填。严禁未与用户讨论就直接照搬文档填满 5 维。⚠️ 若本卡已在**有共享世界书**的分组里，本工具默认**不再**往卡内抄五维骨架（那些共同设定属于共享书，卡内副本会与它双重插入）—— 要卡内副本才显式传 autoLorebook:true。调后下一步是 cc_add_lorebook_entries。",
+    description: "【工作流第3步·共创·必调】写入 5 维世界观（timeline/factions/geo/power/daily 至少 3 项）。若用户已提供世界观文档，先用 2-3 句归纳你理解的 5 维，再问用户“哪几维最想展开？有无私设要加？”；若世界观薄弱，则与用户讨论 1-2 个薄弱点后再填。严禁未与用户讨论就直接照搬文档填满 5 维。⚠️ 若本卡已在**有共享世界书**的分组里，本工具默认**不再**往卡内抄五维骨架（那些共同设定属于共享书，卡内副本会与它双重插入）—— 要卡内副本才显式传 autoLorebook:true。调后下一步是 cc_add_lorebook_entries。loreKeys 这类对象字段建议单独一次调用；参数必须是严格合法的 JSON（最后一个字段/数组元素后不写逗号，不要 ```json 代码块包裹，不要注释与单引号）。",
     parameters: {
       type:"object",
       properties:{
@@ -1188,11 +1312,11 @@ function apply(ctx){
       const recNote = recoveredNotice(k, cur);
       cur.data.extensions = cur.data.extensions || {};
       const w = cur.data.extensions.cc_world || {};
-      if(args.timeline!==undefined) w.timeline = String(args.timeline).slice(0,1000);
-      if(args.factions!==undefined) w.factions = String(args.factions).slice(0,1000);
-      if(args.geo!==undefined) w.geo = String(args.geo).slice(0,1000);
-      if(args.power!==undefined) w.power = String(args.power).slice(0,1000);
-      if(args.daily!==undefined) w.daily = String(args.daily).slice(0,1000);
+      if(args.timeline!==undefined) w.timeline = textArg(args.timeline).slice(0,1000);
+      if(args.factions!==undefined) w.factions = textArg(args.factions).slice(0,1000);
+      if(args.geo!==undefined) w.geo = textArg(args.geo).slice(0,1000);
+      if(args.power!==undefined) w.power = textArg(args.power).slice(0,1000);
+      if(args.daily!==undefined) w.daily = textArg(args.daily).slice(0,1000);
       cur.data.extensions.cc_world = w;
       // 0.10.0：默认值必须看得见「组里已经有什么」——
       // 没显式传 autoLorebook 时，若本卡所属分组的共享书已覆盖这些维度，就**不在卡内生成副本**：
@@ -1247,7 +1371,7 @@ function apply(ctx){
         if(w.timeline) push("timeline", "@@position after_desc\n"+w.timeline, 10);
         if(w.factions) push("factions", "@@depth 4\n"+w.factions, 9);
         if(w.geo) push("geo", "@@position scenario\n"+w.geo, 8);
-        if(w.power) push("power", "@@activate\n"+w.power, 9, true);
+        if(w.power) push("power", "@@activate 100\n"+w.power, 9, true);
         if(w.daily) push("daily", "@@depth 5\n"+w.daily, 7);
       }
       setDraft(ctx, cur, exec);
@@ -1309,7 +1433,7 @@ function apply(ctx){
 
   tool({
     name: "cc_add_lorebook_entries",
-    description: "【工作流第4步·共创·必调】添加 1-5 条 Lorebook，补到至少 5 条（年表/势力/地理/力量/日常各 1，至少 1 条 constant，@@decorator）。调用前应与用户讨论：问用户想要哪些触发词/常驻条目/要藏什么彩蛋，拿到偏好后再生成。必须在五维之后、问候语之前调用，禁止一次性无讨论批量生成。",
+    description: "【工作流第4步·共创·必调】添加 1-5 条 Lorebook，补到至少 5 条（年表/势力/地理/力量/日常各 1，至少 1 条 constant，@@decorator）。调用前应与用户讨论：问用户想要哪些触发词/常驻条目/要藏什么彩蛋，拿到偏好后再生成。必须在五维之后、问候语之前调用，禁止一次性无讨论批量生成。条目较多时分成多次调用（一次 1-2 条）；参数必须是严格合法的 JSON（数组元素之间不写尾逗号，最后一个元素后不写逗号，不要 ```json 代码块包裹，不要注释与单引号）。",
     parameters: {
       type:"object",
       properties:{
@@ -1341,14 +1465,14 @@ function apply(ctx){
       const recNote = recoveredNotice(k, cur);
       args.entries.forEach(function(e){
         cur.data.character_book.entries.push({
-          keys: Array.isArray(e.keys)? e.keys.map(String): [],
-          content: String(e.content).slice(0,5000),
+          keys: Array.isArray(e.keys)? e.keys.map(textArg): [],
+          content: textArg(e.content).slice(0,5000),
           enabled:true,
           insertion_order: cur.data.character_book.entries.length,
           case_sensitive:false,
           use_regex: !!e.use_regex,
           constant: !!e.constant,
-          name: String(e.name||"未命名").slice(0,60),
+          name: textArg(e.name||"未命名").slice(0,60),
           priority: typeof e.priority==="number"? e.priority: 5,
           id: Date.now()+Math.floor(Math.random()*10000)
         });
@@ -1430,9 +1554,9 @@ function apply(ctx){
       const e = cur.data.character_book.entries.find(x=> x.id===args.id);
       if(!e) return { ok:false, error:"未找到 id="+args.id };
       const changed = [];
-      if(args.name!==undefined) assignIfChanged(e, "name", String(args.name).slice(0,60), changed);
-      if(Array.isArray(args.keys)) assignIfChanged(e, "keys", args.keys.map(String), changed);
-      if(args.content!==undefined) assignIfChanged(e, "content", String(args.content).slice(0,5000), changed);
+      if(args.name!==undefined) assignIfChanged(e, "name", textArg(args.name).slice(0,60), changed);
+      if(Array.isArray(args.keys)) assignIfChanged(e, "keys", args.keys.map(textArg), changed);
+      if(args.content!==undefined) assignIfChanged(e, "content", textArg(args.content).slice(0,5000), changed);
       if(args.enabled!==undefined) assignIfChanged(e, "enabled", !!args.enabled, changed);
       if(args.constant!==undefined) assignIfChanged(e, "constant", !!args.constant, changed);
       if(args.use_regex!==undefined) assignIfChanged(e, "use_regex", !!args.use_regex, changed);
@@ -1451,7 +1575,7 @@ function apply(ctx){
 
   tool({
     name: "cc_patch_greetings",
-    description: "【工作流第5步·共创】写入开场与示例（first_mes / alternate_greetings≥2 / group_only_greetings≥1 / mes_example）。调用前必须问用户偏好的开场场景/关系阶段/群聊与私聊区分，拿到偏好后再写；禁止未与用户讨论就自行编造全部问候语。必须在角色+五维+世界书(≥5)后调用。",
+    description: "【工作流第5步·共创】写入开场与示例（first_mes / alternate_greetings≥2 / group_only_greetings≥1 / mes_example）。调用前必须问用户偏好的开场场景/关系阶段/群聊与私聊区分，拿到偏好后再写；禁止未与用户讨论就自行编造全部问候语。必须在角色+五维+世界书(≥5)后调用。一次只传 1-2 个字段（长问候语分多次调用写）；alternate_greetings / group_only_greetings 这类数组字段单独一次调用。参数必须是严格合法的 JSON（最后一个字段/数组元素后不写逗号，不要 ```json 代码块包裹，不要注释与单引号）。",
     parameters: {
       type:"object",
       properties:{
@@ -1469,10 +1593,10 @@ function apply(ctx){
       const k = keyFor(ctx, exec);
       const cur = JSON.parse(JSON.stringify(getDraft(ctx, exec)));
       const recNote = recoveredNotice(k, cur);
-      if(args.first_mes!==undefined) cur.data.first_mes = String(args.first_mes).slice(0,5000);
-      if(Array.isArray(args.alternate_greetings)) cur.data.alternate_greetings = args.alternate_greetings.map(String).slice(0,10);
-      if(Array.isArray(args.group_only_greetings)) cur.data.group_only_greetings = args.group_only_greetings.map(String).slice(0,10);
-      if(args.mes_example!==undefined) cur.data.mes_example = String(args.mes_example).slice(0,5000);
+      if(args.first_mes!==undefined) cur.data.first_mes = textArg(args.first_mes).slice(0,5000);
+      if(Array.isArray(args.alternate_greetings)) cur.data.alternate_greetings = args.alternate_greetings.map(textArg).slice(0,10);
+      if(Array.isArray(args.group_only_greetings)) cur.data.group_only_greetings = args.group_only_greetings.map(textArg).slice(0,10);
+      if(args.mes_example!==undefined) cur.data.mes_example = textArg(args.mes_example).slice(0,5000);
       setDraft(ctx, cur, exec);
       const wf = await workflowFor(ctx, exec, cur);
       // 若世界书/五维未齐，警告但仍写入，让 validate 卡住
@@ -1625,7 +1749,7 @@ function apply(ctx){
   // 【世界书元信息】此前 name/description/scan_depth/token_budget/recursive_scanning 一个都改不了
   tool({
     name: "cc_patch_book_meta",
-    description: "【世界书·元信息】改 character_book 的顶层参数：name / description / scan_depth / token_budget / recursive_scanning。这些字段此前没有任何工具能改，导致导出的世界书永远是无名书、预算也调不了。合并式更新，只改传入的字段。",
+    description: "【世界书·元信息】改 character_book 的顶层参数：name / description / scan_depth / token_budget / recursive_scanning。这些字段此前没有任何工具能改，导致导出的世界书永远是无名书、预算也调不了。合并式更新，只改传入的字段。参数必须是严格合法的 JSON（不要尾逗号、不要注释、不要单引号）。",
     parameters: {
       type:"object",
       properties:{
@@ -1645,8 +1769,8 @@ function apply(ctx){
       cur.data.character_book = cur.data.character_book || {};
       const book = cur.data.character_book;
       const changed = [];
-      if(args.name!==undefined) assignIfChanged(book, "name", String(args.name).slice(0,120), changed);
-      if(args.description!==undefined) assignIfChanged(book, "description", String(args.description).slice(0,500), changed);
+      if(args.name!==undefined) assignIfChanged(book, "name", textArg(args.name).slice(0,120), changed);
+      if(args.description!==undefined) assignIfChanged(book, "description", textArg(args.description).slice(0,500), changed);
       if(typeof args.scan_depth==="number") assignIfChanged(book, "scan_depth", Math.max(1, Math.min(50, Math.round(args.scan_depth))), changed);
       if(typeof args.token_budget==="number") assignIfChanged(book, "token_budget", Math.max(0, Math.round(args.token_budget)), changed);
       if(args.recursive_scanning!==undefined) assignIfChanged(book, "recursive_scanning", !!args.recursive_scanning, changed);
@@ -2438,7 +2562,7 @@ function apply(ctx){
 
   tool({
     name: "cc_validate",
-    description: "【工作流第6步·收口必调】校验 CC 角色卡（SPEC_V3 + 角色四件套/五维≥3/世界书≥5/问候语齐）。valid=false 按 errors 与用户讨论继续补；valid=true 时总结成果并邀请用户在工坊微调后“导出 JSON”或“★ 保存到侧边栏”。全程强调共创：多问用户、多给草案供挑选。",
+    description: "【工作流第6步·收口必调】校验 CC 角色卡（SPEC_V3 + 角色四件套/五维≥3/世界书≥5/问候语齐）。valid=false 按 errors 与用户讨论继续补；**valid=true 即创作完成，必须立刻调用 cc_release_draft 交还草稿编辑权**（不交还的话工坊一直只读，用户无法微调），然后邀请用户在工坊微调后“导出 JSON”或“★ 保存到侧边栏”。全程强调共创：多问用户、多给草案供挑选。",
     parameters: { type:"object", properties:{}, additionalProperties:false },
     output: out({ type:"object", additionalProperties:true }),
     async execute(args, exec){
@@ -2486,14 +2610,19 @@ function apply(ctx){
       if(budget>0 && used > budget) warnings.push("世界书内容估算约 "+used+" token，已超出 token_budget="+budget+"，建议调大预算或精简条目（cc_patch_book_meta）");
       // —— 终态：校验通过后 next 不再指向 cc_validate（P0-3：那正是弱模型死循环的诱因）——
       const valid = errors.length===0;
+      // 0.11.0：终态要主动提醒交还草稿锁 —— 不交还时工坊一直是只读的，用户只能预览、无法微调，
+      // 而「校验通过」正是「创作告一段落」的唯一信号。保留「校验导出」「保存当前」两个既有指引入口
+      //（工坊左下角入口名与 0.4.1 的 UI 一致；tools-contract ②i 依赖这两处字样）。
       const next = valid
-        ? "校验通过 ✓ 工作流已完成（step 7/7）。请在工坊左下角「校验导出」入口打开导出页选 JSON / PNG / CHARX，或点「★ 保存当前」落盘到 ~/.dsh/cc-library；还想打磨就直接说改哪里。"
+        ? "校验通过 ✓ 工作流已完成（step 7/7）。**下一步必须调用 cc_release_draft 交还草稿编辑权**（否则工坊保持只读，用户只能在预览里看、无法微调）；交还后引导用户在工坊左下角「校验导出」入口打开导出页选 JSON / PNG / CHARX，或点「★ 保存当前」落盘到 ~/.dsh/cc-library。还想打磨就直接说改哪里（你继续写会自动重新上锁）。"
         : "校验未通过，按 errors 逐项补齐（严禁跳步），第一项：" + errors[0];
       // R1（0.6.0）：终态的 `hint` 必须与 `next` 同源 —— 否则会出现「next 说工作流已完成、hint 说下一步必须去校验」
       // 这种自相矛盾（弱模型会读信息最全的 hint，于是反复调 cc_validate）。半修的状态机比没修更危险。
       const wfDone = Object.assign({}, wf, {
         step: valid ? 7 : wf.step,
         done: valid,
+        // 模型可见的显式收口信号：valid=true 时 releaseRequired=true，提示它这一步还没做完。
+        releaseRequired: valid,
         readyToValidate: !valid && wf.readyToValidate,
         next,
         hint: progressHint(valid ? 7 : wf.step, wf.state, wf.worldFilled, wf.loreCount, wf.manualLoreCount, valid, wf.sharedLoreCount),
@@ -2517,10 +2646,40 @@ function apply(ctx){
         message: valid
           ? "校验通过 ✓ 工作流完成（世界书 " + wf.loreTotal + " 条"
             + (wf.sharedLoreCount ? " = 卡内 " + wf.loreCount + " + 共享书 " + wf.sharedLoreCount : "")
-            + " / 估算 " + (used + sharedUsed) + " token）。"
+            + " / 估算 " + (used + sharedUsed) + " token）。下一步：调用 cc_release_draft 交还草稿锁，用户才能在工坊微调/导出。"
           : "校验未通过：" + errors.length + " 项待补。" };
     }
   });
+
+  // 【交还草稿锁】0.11.0：权限完全由 LLM 掌握 —— 它说创作完了、或用户明确要求强制释放时才放开。
+  // 为什么不做成自动释放：工具半无法判断「这一轮对话是否真的结束」，误放一次，
+  // 用户接着载入别的卡就会把 LLM 还没保存的内容覆盖掉 —— 正是 0.11.0 要修的那个事故。
+  tool({
+    name: "cc_release_draft",
+    description: "【收口·交还草稿】**cc_validate 通过（valid=true）= 创作完成，必须立刻调用本工具**，否则工坊一直只读、用户无法微调（这是工作流的最后一步）。释放当前会话的草稿创作锁，把工坊还给用户编辑。调用前先向用户说明当前卡名与进度（释放后用户就能在工坊里直接改这张卡）。用户明确要求强制释放时也调用；释放后若你再次写草稿，会自动重新锁定；当前没有锁时调用也安全（幂等成功，released:false）。",
+    parameters: { type:"object", properties:{}, additionalProperties:false },
+    output: out({ type:"object", additionalProperties:true }),
+    async execute(args, exec){
+      const k = keyFor(ctx, exec);
+      const lock = readDraftLockSync(k);
+      const st = draftStatusFor(k, getDraft(ctx, exec));
+      const released = !!lock;
+      clearDraftLockSync(k);
+      // 卡名优先用锁里记下的那个：锁可能是草稿还叫旧名时建的，交还时要说清「交还的是哪张卡」。
+      const cardName = (lock && String(lock.cardName || "").trim()) || String(st.cardName || "").trim();
+      const rev = (typeof st.rev === "number" && st.rev > 0) ? st.rev : ((lock && lock.rev) || null);
+      return {
+        ok: true,
+        released,
+        sessionKey: k,
+        cardName: cardName || null,
+        rev,
+        message: released
+          ? "已释放草稿锁「" + (cardName || "未命名") + "」：工坊恢复可编辑，用户现在可以载入/导入别的卡，不会覆盖你的草稿。若你继续写草稿，会自动重新锁定。"
+          : "当前没有草稿锁（可能已释放过，或已超时自动失效），无需重复释放。如果你继续写草稿，会自动重新锁定。",
+      };
+    }
+  });
 }
 
 // ——————————————————————————————————————————————————————————————
@@ -2704,8 +2863,8 @@ async function patchSharedBook(groupId, args){
       error: "共享世界书已被外部修改（期望 rev=" + args.expectedBookRev + "，实际 rev=" + bookRevOf(cur) + "）—— 先 cc_get_shared_book 重新读一遍再改。" };
   }
   const applied = [], rejected = [];
-  if(args.name !== undefined) cur.data.name = String(args.name).slice(0, 80);
-  if(args.description !== undefined) cur.data.description = String(args.description).slice(0, 300);
+  if(args.name !== undefined) cur.data.name = textArg(args.name).slice(0, 80);
+  if(args.description !== undefined) cur.data.description = textArg(args.description).slice(0, 300);
   if(args.scan_depth !== undefined) cur.data.scan_depth = Math.max(1, Math.round(Number(args.scan_depth) || 4));
   if(args.token_budget !== undefined) cur.data.token_budget = Math.max(100, Math.round(Number(args.token_budget) || 2000));
   if(args.recursive_scanning !== undefined) cur.data.recursive_scanning = args.recursive_scanning === true;
@@ -2713,7 +2872,12 @@ async function patchSharedBook(groupId, args){
   (Array.isArray(args.ops) ? args.ops : []).forEach(op => {
     const kind = String((op && op.op) || "");
     if(kind === "addEntry"){
-      const e = makeBookEntry(op.entry);
+      // 0.10.3：模型可能把换行写成字面 \n —— 共享书条目也是卡内文本，先解码再归一化。
+      const rawEntry = Object.assign({}, op.entry);
+      if(rawEntry.content !== undefined) rawEntry.content = textArg(rawEntry.content);
+      if(rawEntry.name !== undefined) rawEntry.name = textArg(rawEntry.name);
+      if(Array.isArray(rawEntry.keys)) rawEntry.keys = rawEntry.keys.map(textArg);
+      const e = makeBookEntry(rawEntry);
       if(!e.content.trim()){ rejected.push({ op, error: "content 不能为空" }); return; }
       if(cur.data.entries.some(x => contentKeyOf(x) === contentKeyOf(e))){ rejected.push({ op, error: "同内容的条目已存在" }); return; }
       if(cur.data.entries.length >= BOOK_MAX_ENTRIES){ rejected.push({ op, error: "条目数已达上限 " + BOOK_MAX_ENTRIES }); return; }
@@ -2722,7 +2886,11 @@ async function patchSharedBook(groupId, args){
     } else if(kind === "updateEntry"){
       const idx = cur.data.entries.findIndex(x => contentKeyOf(x) === String(op.contentKey || ""));
       if(idx < 0){ rejected.push({ op, error: "找不到条目（contentKey 不匹配）" }); return; }
-      cur.data.entries[idx] = makeBookEntry(Object.assign({}, cur.data.entries[idx], (op.patch && typeof op.patch === "object") ? op.patch : {}));
+      const rawPatch = Object.assign({}, (op.patch && typeof op.patch === "object") ? op.patch : {});
+      if(rawPatch.content !== undefined) rawPatch.content = textArg(rawPatch.content);
+      if(rawPatch.name !== undefined) rawPatch.name = textArg(rawPatch.name);
+      if(Array.isArray(rawPatch.keys)) rawPatch.keys = rawPatch.keys.map(textArg);
+      cur.data.entries[idx] = makeBookEntry(Object.assign({}, cur.data.entries[idx], rawPatch));
       applied.push({ op: kind, key: contentKeyOf(cur.data.entries[idx]) });
     } else if(kind === "removeEntry"){
       // 支持两种定位：`index`（工坊列表直接用它）或 `contentKey`（模型读到的签名）
@@ -2945,6 +3113,8 @@ async function sharedBookCoversDims(ctx, exec){
 }
 
 export { apply, inject, name, safeDraftFile, draftDirs, libDirs, dataRoots, originPath, readOriginSync, writeOriginSync,
+  // 草稿锁（0.11.0）：与宿主半同构的落盘与摘要 —— 测试直接比对两半路径与行为
+  draftLockPath, readDraftLockSync, writeDraftLockSync, clearDraftLockSync, draftLockSummaryFor,
   // 卡组层（0.10.0）：卡库快照 + 卡组作用域 —— 卡组数据的唯一入口，两半共用 lib/group-layer.js 的纯组装
   readLibrarySnapshot, groupScope,
   // 人物关系图谱（0.8.0）：导出纯函数与落盘根，供 tests/relations.test.mjs 与宿主半逐字比对同构实现