@xia-sc/dsh-cc-studio 0.10.3 → 0.11.1

package/lib/draft-lock.js

@@ -0,0 +1,98 @@
+/**
+ * 草稿锁（LLM 创作保护 / 读写分离）—— 纯函数与常量，零 IO，**宿主半与预设半共用这一份**。
+ *
+ * 背景（0.11.0）：LLM 正在工坊草稿里创作 A 卡时，用户点「载入」B 卡，`cc_loadFromLibrary`
+ * 直接把同一会话槽的草稿整份替换 —— LLM 已写入但未保存的内容被覆盖，只能从历史对话里捞。
+ * 现在 LLM 每次写草稿都会建立一把**创作锁**；锁 active 期间用户侧（浏览器 RPC）的写草稿动作
+ * 一律被拦，载入/导入只进入只读预览。权限完全由 LLM 控制：它调用 `cc_release_draft` 交还，
+ * 或锁超过 TTL 无写入自动失效（防 LLM 崩溃后永久锁死的安全阀）。
+ *
+ * 为什么判定放在这里而不是两半各写一份（同 lib/group-layer.js 的教训）：
+ * 「锁算不算 active / 超时算不算过期 / 能不能写」是同一套语义，两半各写一份必然漂移 ——
+ * 一边说锁住了、另一边照写，比没有锁更危险。IO 仍由两半各持一份（各自的 dataRoots），
+ * 那是真正需要两份的东西。
+ *
+ * 锁文件：<主根>/cc-drafts/<safeDraftFile(key) 去掉 .json>.lock.json（与 .origin.json 同模式）。
+ * 锁**不写进草稿 JSON**：用户只读/LLM 交还不重写草稿，草稿的 `rev` 仍然只反映内容变化。
+ */
+
+/** 目前唯一的锁持有者。用户侧没有「接管锁」这种状态 —— 权限由 LLM 持有或释放。 */
+export const LOCK_OWNER_LLM = "llm";
+/** 锁多久没有刷新算超时（秒）。LLM 每次写草稿都会续期；超时视为 LLM 已停止创作。 */
+export const LOCK_TTL_SEC = 30 * 60;
+/** 锁文件后缀（草稿文件是 .json，来源 sidecar 是 .origin.json，锁是 .lock.json）。 */
+export const LOCK_FILE_SUFFIX = ".lock.json";
+
+function nowOf(nowSec){
+  const n = Number(nowSec);
+  return Number.isFinite(n) && n > 0 ? Math.round(n) : Math.floor(Date.now() / 1000);
+}
+
+/**
+ * 把磁盘上的锁对象归一成内部形状；任何不合法的输入一律返回 null（= 没有锁）。
+ *
+ * 降级方向必须是「无锁」：锁文件损坏、被手工改坏、或 key 对不上时，宁可放弃保护也不能
+ * 让用户永远编辑不了草稿。真正需要「锁得住」的是 LLM 自己刚写下的那份（写入即合法）。
+ */
+export function normalizeLock(obj, key){
+  const src = (obj && typeof obj === "object") ? obj : null;
+  if(!src) return null;
+  if(src.owner !== LOCK_OWNER_LLM && String(src.owner == null ? "" : src.owner) !== LOCK_OWNER_LLM) return null;
+  const k = (key == null) ? "" : String(key);
+  // key 不匹配 = 这不是这把槽的锁（防 hash 碰撞 / 手工拷贝 / 改名后的残文件）
+  if(k && src.key != null && String(src.key) !== k) return null;
+  const updatedAt = Math.max(0, Math.round(Number(src.updatedAt) || 0));
+  if(updatedAt <= 0) return null;
+  const since = Math.max(0, Math.round(Number(src.since) || 0)) || updatedAt;
+  const rev = Math.max(0, Math.round(Number(src.rev) || 0));
+  return {
+    key: k || (src.key == null ? "" : String(src.key)),
+    owner: LOCK_OWNER_LLM,
+    since,
+    updatedAt,
+    rev,
+    cardName: String(src.cardName == null ? "" : src.cardName).slice(0, 120),
+  };
+}
+
+/** 锁是否已超时（TTL 内没有刷新）。无锁恒为 false。 */
+export function isLockStale(lock, nowSec){
+  if(!lock) return false;
+  return (nowOf(nowSec) - lock.updatedAt) > LOCK_TTL_SEC;
+}
+
+/**
+ * 给界面 / 工具返回用的锁摘要。`stale` 不是「锁失效了但还挡着」—— 语义是
+ * 「LLM 已经很久没写了，视为可编辑；它若再写会自动重新上锁」。
+ * 无锁返回 null（工具返回里必须是显式 null，不能漏成 undefined，见 B1 的 lossless-JSON 教训）。
+ */
+export function lockSummary(lock, nowSec){
+  if(!lock) return null;
+  const now = nowOf(nowSec);
+  const ageSec = Math.max(0, now - lock.updatedAt);
+  const stale = ageSec > LOCK_TTL_SEC;
+  return {
+    owner: lock.owner,
+    cardName: lock.cardName,
+    since: lock.since,
+    updatedAt: lock.updatedAt,
+    ageSec,
+    ttlSec: LOCK_TTL_SEC,
+    stale,
+    active: !stale,
+  };
+}
+
+/**
+ * 用户侧写草稿之前问一句「现在能不能写」。
+ * - `force:true`：设置页把「LLM 创作保护」关掉时客户端会带上它 —— 等价于旧行为。
+ * - 无锁 / 已超时：放行（超时是安全阀，不是用户抢权）。
+ * - 锁 active：拦下，reason 给上层拼错误码与提示。
+ */
+export function lockBlocksDraftWrite(lock, nowSec, force){
+  if(force === true) return { blocked:false, reason:"force", stale: isLockStale(lock, nowSec) };
+  if(!lock) return { blocked:false, reason:"none", stale:false };
+  const stale = isLockStale(lock, nowSec);
+  if(stale) return { blocked:false, reason:"stale", stale:true };
+  return { blocked:true, reason:"llm-locked", stale:false };
+}

package/lib/index.js

@@ -14,6 +14,10 @@ import { inflateSync as zlibInflateSync } from "node:zlib";
 import { REL_TYPES, REL_TYPE_LABELS, REL_BEGIN, REL_END,
   estimateTokens, contentKeyOf, scanSharedEntries,
   assembleScope, groupMetrics, runGroupChecks } from "./group-layer.js";
+// 草稿锁（0.11.0）：锁「算不算 active / 算不算超时 / 现在能不能写」只有一份实现，与预设半共用。
+// 两半各写一份判定必然漂移 —— 一边说锁着、另一边照写，比没有锁更危险（同 lib/group-layer.js 的教训）。
+// 这里只 import 判定；锁文件 IO 仍由两半各持一份（它们各自解析 DSH_HOME，那才是真正需要两份的东西）。
+import { normalizeLock, lockSummary, lockBlocksDraftWrite } from "./draft-lock.js";
 
 const name = "dsh-cc-studio";
 // dsh >= 0.1.5-rc.1: this package owns its HTTP route outright.
@@ -190,6 +194,62 @@ function writeDraftOrigin(key, libraryId, name){
     writeFileSync(originFilePath(key), JSON.stringify({ key: String(key), libraryId: String(libraryId), name: String(name||""), savedAt: nowSec() }, null, 2), "utf8");
   }catch(e){ try{ console.error("[dsh-cc-studio] persist draft origin failed:", (e && e.message) || e); }catch{} }
 }
+// —— 草稿锁的 IO（0.11.0，与 lib/agent.js 同构）——
+// 锁文件 = <主根>/cc-drafts/<safe 去掉 .json>.lock.json（与 .origin.json 同模式；锁**不写进草稿 JSON**，
+// 用户只读/LLM 交还不重写草稿，草稿的 rev 仍然只反映内容变化）。
+// 路径规则与工具半必须逐字同构：同一个会话 key 两边必须算出同一个锁文件，否则 LLM 锁一把、用户写另一把。
+//   · 写只写主根（dataRoots()[0]）；
+//   · 读回退旧根（升级后 LLM 写在旧根目录的锁仍然有效）；
+//   · 清两个根都删（否则回退读会把刚交还的锁「复活」—— 与 deleteLibraryEntry 同一教训）。
+function draftLockPath(key){ return join(draftDir(), safeDraftFile(key).replace(/\.json$/, ".lock.json")); }
+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;
+      // 与工具半逐字同构：主根有锁就只认主根那份；坏文件/key 不符 → null（= 无锁，降级方向必须是放行）
+      return normalizeLock(JSON.parse(readFileSync(p, "utf8")), String(key));
+    }catch{}
+  }
+  return null;
+}
+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; }
+}
+function clearDraftLockSync(key){
+  const file = safeDraftFile(key).replace(/\.json$/, ".lock.json");
+  let removed = 0;
+  for(const dir of draftDirs()){
+    try{ unlinkSync(join(dir, file)); removed += 1; }catch{}
+  }
+  return removed > 0;
+}
+/** 给界面/返回值用的锁摘要：无锁显式 null（B1：不能漏成 undefined）。 */
+function draftLockSummaryFor(key){ return lockSummary(readDraftLockSync(key), nowSec()); }
+/**
+ * 「用户侧现在能不能写这把草稿槽」的唯一入口：锁 active 且没带 force 时给出拦截信息，
+ * 否则返回 null。判定委托 lib/draft-lock.js 的 lockBlocksDraftWrite（无锁/超时/force 都放行）。
+ * `action` 只用来拼中文提示（「载入」「导入」「本次修改」…）。
+ */
+function draftLockBlockFor(key, args, action){
+  const lock = readDraftLockSync(key);
+  const verdict = lockBlocksDraftWrite(lock, nowSec(), args && args.force === true);
+  if(!verdict.blocked) return null;
+  const summary = lockSummary(lock, nowSec());
+  const who = (summary && summary.cardName) ? ("「" + summary.cardName + "」") : "这张卡";
+  const ageMin = Math.max(1, Math.round(((summary && summary.ageSec) || 0) / 60));
+  return {
+    lock: summary,
+    message: "LLM 正在创作" + who + "（最后写入约 " + ageMin + " 分钟前），" + (action || "本次修改") +
+      "未写入：工坊对这张草稿只读。等 LLM 创作完成、调用 cc_release_draft 释放草稿锁后再试；" +
+      "若确认放弃它这一轮的草稿，可带 force:true 直接覆盖。",
+  };
+}
 function findDraftPath(key){
   const file = safeDraftFile(key);
   for(const dir of draftDirs()){
@@ -241,7 +301,9 @@ function draftStatusFor(key, draft){
   const m = draftMeta(key);
   // B1（0.7.1）：缺 `creation_date` 的外部导入卡不能再漏出 `undefined`（工具侧会因此整次调用失败，
   // 前端也会把 undefined 渲染成字面量）。
-  return { isNew: !!m.isNew, recovered: !!m.recovered, creation_date: (draft && draft.data && draft.data.creation_date !== undefined) ? draft.data.creation_date : null, key: String(key) };
+  // 0.11.0：把锁摘要塞进 draftStatus —— 前端只认这一条路径（cc_getDraft 不另开顶层 lock 字段），
+  // 无锁时显式 null（不是「省略字段」），否则客户端要分 undefined / null 两种没锁。
+  return { isNew: !!m.isNew, recovered: !!m.recovered, creation_date: (draft && draft.data && draft.data.creation_date !== undefined) ? draft.data.creation_date : null, key: String(key), lock: draftLockSummaryFor(key) };
 }
 /**
  * 解析「这次调用读写哪把草稿槽」，并把来源一并带出来（诊断用）。
@@ -289,6 +351,91 @@ function draftContentSummary(draft){
   if(entries) filled += 1;
   return { name: String(d.name==null ? "" : d.name), entries: entries, filled: filled };
 }
+// —— 覆盖型动作前的草稿备份（0.11.0）——
+// 为什么备份不放进草稿锁的判定层：锁保护的是「LLM 正在写的这一轮」，而备份保护的是
+// 「用户/LLM 谁覆盖谁都别丢内容」—— 载入 B 卡、导入、force 覆盖都会整份替换同一把槽的草稿。
+// 备份放在 <draftDir>/backups/ 子目录：listDraftSlotsOnDisk 只扫顶层，不会把备份误当成草稿槽。
+// 文件名 `<safe 去 .json>-<毫秒时间戳>.json`；同一把槽最多留 20 份，空壳与「和最近一份内容相同」不备份
+// （否则每次载入同一张卡都白写一份，备份目录很快就全是重复内容）。
+const DRAFT_BACKUP_KEEP = 20;
+function draftBackupDir(){ return join(draftDir(), "backups"); }
+/** 盘上草稿当前的 rev（备份里记一份，方便知道备份对应哪个版本）；没有文件 → 0。 */
+function draftRevOnDisk(key){
+  try{
+    const p = findDraftPath(key);
+    if(!p) return 0;
+    const obj = JSON.parse(readFileSync(p, "utf8"));
+    const rev = Number(obj && obj.rev);
+    return Number.isFinite(rev) && rev > 0 ? Math.round(rev) : 0;
+  }catch{ return 0; }
+}
+/** 同槽备份文件名（不含目录）→ 时间戳；不是这把槽的备份返回 null。 */
+function draftBackupStamp(file, base){
+  const prefix = base + "-";
+  if(String(file).indexOf(prefix) !== 0) return null;
+  const tail = String(file).slice(prefix.length);
+  if(!/^\d+\.json$/.test(tail)) return null;
+  return Number(tail.slice(0, -5));
+}
+/** 最近一份同槽备份的内容对象（解析失败当作没有）；没有备份返回 null。 */
+function latestDraftBackup(base){
+  const dir = draftBackupDir();
+  let names = [];
+  try{ names = readdirSync(dir); }catch{ return null; }
+  let latest = null;
+  for(const f of names){
+    const ts = draftBackupStamp(f, base);
+    if(ts === null) continue;
+    if(latest === null || ts > latest.ts) latest = { file: String(f), ts };
+  }
+  if(!latest) return null;
+  try{ return JSON.parse(readFileSync(join(dir, latest.file), "utf8")); }catch{ return null; }
+}
+/** 同槽备份只留最近 20 份（超过的按时间从旧到新删）。失败不抛。 */
+function pruneDraftBackups(base){
+  const dir = draftBackupDir();
+  let names = [];
+  try{ names = readdirSync(dir); }catch{ return; }
+  const rows = [];
+  for(const f of names){
+    const ts = draftBackupStamp(f, base);
+    if(ts === null) continue;
+    rows.push({ file: String(f), ts });
+  }
+  rows.sort(function(a, b){ return b.ts - a.ts; });
+  for(let i = DRAFT_BACKUP_KEEP; i < rows.length; i++){
+    try{ unlinkSync(join(dir, rows[i].file)); }catch{}
+  }
+}
+/**
+ * 覆盖前把当前草稿留一份到 <draftDir>/backups/。返回 `{file, path, at}`；没备份返回 null。
+ * 不备份的三种情况：① 当前是空壳（盖掉也没损失，别制造噪音）；② 与最近一份备份内容指纹相同
+ * （cardFingerprint 忽略 modification_date，同内容重复载入不会叠出十几份）；③ 写失败（吞掉，
+ * 备份只是保险丝，绝不能因为备份写不进去而让用户连编辑都做不了）。
+ */
+function backupDraftSync(key, reason){
+  const k = key || "default";
+  try{
+    const draft = globalThis.__CC_DRAFTS__.has(k) ? globalThis.__CC_DRAFTS__.get(k) : loadPersistedDraftSync(k);
+    if(!draft || typeof draft !== "object") return null;
+    if(draftContentSummary(draft).filled === 0) return null;
+    const base = safeDraftFile(k).replace(/\.json$/, "");
+    const prev = latestDraftBackup(base);
+    if(prev && prev.draft && typeof prev.draft === "object" && cardFingerprint(prev.draft) === cardFingerprint(draft)) return null;
+    const dir = draftBackupDir();
+    mkdirSync(dir, { recursive: true });
+    // 时间戳用毫秒：同一秒内连续两次覆盖（脚本/测试）不会互相盖掉同一份文件名
+    const atMs = Date.now();
+    const file = base + "-" + atMs + ".json";
+    const path = join(dir, file);
+    writeFileSync(path, JSON.stringify({ key: k, updatedAt: nowSec(), rev: draftRevOnDisk(k), reason: String(reason || ""), draft }, null, 2), "utf8");
+    pruneDraftBackups(base);
+    return { file: file, path: path, at: Math.floor(atMs / 1000) };
+  }catch(e){
+    try{ console.error("[dsh-cc-studio] backup draft failed:", (e && e.message) || e); }catch{}
+    return null;
+  }
+}
 /**
  * 盘上还有哪些草稿槽（按写入时间倒序）。只用于「当前槽是空壳」时的救回提示 ——
  * 这是 issue #5 里用户唯一能自救的入口：内容没丢，只是被写进了另一把 key。
@@ -1573,24 +1720,40 @@ function apply(ctx, config){
           const toParts = draftKeyPartsFrom(ctx, { sessionId: (typeof args.to==="string" && args.to) ? args.to : (args.sessionId||null) });
           const to = toParts.key;
           if(from === to) return fail("same-slot", "源槽与目标槽相同（" + from + "），无需迁移");
+          // 0.11.0：被锁的是**目标槽**（迁移会整份覆盖它）；锁 active 时先别读源槽，整次动作都不做。
+          const locked = draftLockBlockFor(to, args, "槽迁移");
+          if(locked) return fail("draft-locked", locked.message, { lock: locked.lock });
           const src = loadPersistedDraftSync(from) || (globalThis.__CC_DRAFTS__.has(from) ? globalThis.__CC_DRAFTS__.get(from) : null);
           const tgt = loadPersistedDraftSync(to) || (globalThis.__CC_DRAFTS__.has(to) ? globalThis.__CC_DRAFTS__.get(to) : null);
           const decision = migrateDraftDecision(src, tgt, args.overwrite===true);
           if(!decision.ok) return fail(decision.code, decision.message, decision.details||{});
+          // force = 用户明确抢走目标槽：先清锁，再把目标槽**将被覆盖的草稿**备份一份（LLM 那一轮的内容还能捞）
+          if(args.force === true){
+            clearDraftLockSync(to);
+            backupDraftSync(to, "migrate");
+          }
           setDraftFor(to, decision.draft);
           return ok({ draft: decision.draft, key: to, from: from, moved: decision.summary, draftStatus: draftStatusFor(to, decision.draft) });
         }
         case "cc_setDraft":{
           const k = draftKeyFrom(ctx, args);
           const draft = args.draft;
+          // 0.11.0：锁 active 时工坊的写草稿动作一律拦下（参数校验之前 —— 锁定期间连一次写尝试都不落盘）。
+          const locked = draftLockBlockFor(k, args, "本次修改");
+          if(locked) return fail("draft-locked", locked.message, { lock: locked.lock });
           if(!draft || typeof draft!=="object") return fail("invalid-draft","draft 必须为对象");
           const v = validateCard(draft);
           if(!v.valid) return fail("invalid-card","校验未通过: "+v.errors.join("; "), {errors:v.errors});
+          // force 放行并不备份：这是「用户明确选择覆盖 LLM 的草稿」，与载入/导入那种「换一张卡」不同，
+          // 备份只服务于后者（见 backupDraftSync 的注释）。
+          if(args.force === true) clearDraftLockSync(k);
           setDraftFor(k, draft);
           return ok({ draft, key:k, draftStatus: draftStatusFor(k, draft) });
         }
         case "cc_patchDraft":{
           const k = draftKeyFrom(ctx, args);
+          const locked = draftLockBlockFor(k, args, "本次修改");
+          if(locked) return fail("draft-locked", locked.message, { lock: locked.lock });
           const patch = args.patch && typeof args.patch==="object" ? args.patch : {};
           const cur = JSON.parse(JSON.stringify(getDraftFor(k)));
           if(patch.name!==undefined) cur.data.name = String(patch.name).slice(0,120);
@@ -1644,6 +1807,7 @@ function apply(ctx, config){
               cur.data.character_book.entries.push(entry);
             });
           }
+          if(args.force === true) clearDraftLockSync(k);   // 同 cc_setDraft：force 才是用户明确抢权
           setDraftFor(k, cur);
           return ok({ draft: cur, key:k, draftStatus: draftStatusFor(k, cur) });
         }
@@ -1683,11 +1847,21 @@ function apply(ctx, config){
           const id = args.id;
           if(typeof id!=="string" || !id) return fail("invalid-id","id 必填");
           const obj = await loadLibraryEntry(id);
-          // 载入到当前会话草稿，并记下来源 id（sidecar）：之后不传 id 保存就是更新这一张
           const k = draftKeyFrom(ctx, args);
+          // 0.11.0：锁 active 时**只读预览** —— 不写草稿、不写 origin。否则用户只是点了一下「载入」，
+          // LLM 这一轮写进草稿的内容和「保存时该更新哪张卡」都会被一起改掉。
+          // 这里刻意回 ok 帧（不是 fail）：预览是正常交互，前端按 `locked:true` 切只读。
+          const locked = draftLockBlockFor(k, args, "载入");
+          if(locked) return ok({ locked: true, lock: locked.lock, preview: { id: obj.id, draft: obj.draft, meta: obj.meta }, key: k });
+          // 覆盖前备份当前草稿（空壳 / 与最近一份同内容会自动跳过）
+          const backup = backupDraftSync(k, "load");
+          clearDraftLockSync(k);
+          // 载入到当前会话草稿，并记下来源 id（sidecar）：之后不传 id 保存就是更新这一张
           setDraftFor(k, JSON.parse(JSON.stringify(obj.draft)));
           writeDraftOrigin(k, obj.id, obj.meta ? obj.meta.name : "");
-          return ok({ draft: obj.draft, meta: obj.meta, key: k, originId: obj.id, draftStatus: draftStatusFor(k, obj.draft) });
+          const out = { draft: obj.draft, meta: obj.meta, key: k, originId: obj.id, draftStatus: draftStatusFor(k, obj.draft) };
+          if(backup) out.backup = backup;   // 没备份就别回一个 null 字段（前端/测试都按「有就是有」读）
+          return ok(out);
         }
         case "cc_deleteFromLibrary":{
           const id = args.id;
@@ -1706,7 +1880,11 @@ function apply(ctx, config){
         case "cc_setOrigin":{
           // 前端显式设/清「当前草稿的来源 id」：id 传 null/空 = 清（清空草稿、另存为新时用）
           const k = draftKeyFrom(ctx, args);
+          // 0.11.0：锁 active 时不许改来源 —— 它决定 LLM 下一次保存更新哪张卡（错卡的后果比覆盖草稿还重）
+          const locked = draftLockBlockFor(k, args, "修改草稿关联");
+          if(locked) return fail("draft-locked", locked.message, { lock: locked.lock });
           const id = (typeof args.id === "string" && args.id) ? args.id : null;
+          if(args.force === true) clearDraftLockSync(k);
           writeDraftOrigin(k, id, args.name);
           return ok({ key: k, originId: id });
         }
@@ -1833,6 +2011,10 @@ function apply(ctx, config){
         case "cc_renderRelations":{
           // 渲染进**当前草稿**（与工具半共用同一份草稿文件）；要落库仍需再存一次
           const k = draftKeyFrom(ctx, args);
+          // 0.11.0：这是写草稿 description 的显式动作，锁 active 时整次拦下（dryRun 预览也一并拦，
+          // 因为预览里看到的是 LLM 正在写的草稿，让用户以为能写反而更糟）。
+          const locked = draftLockBlockFor(k, args, "渲染关系");
+          if(locked) return fail("draft-locked", locked.message, { lock: locked.lock });
           const origin = readDraftOrigin(k);
           const cardId = args.cardId ? String(args.cardId) : ((origin && origin.libraryId) || "");
           if(!cardId) return fail("no-card", "这张草稿还没入库（没有来源卡 id）：先在工坊「保存当前」或显式传 cardId");
@@ -1851,6 +2033,11 @@ function apply(ctx, config){
           const changed = before !== after;
           if(args.dryRun === true) return ok({ changed, preview: after, section, groupId: g.id, rev: g.rev });
           if(changed){
+            // 这段之前有 await（读库/读分组）：LLM 可能刚在这期间重新上锁，写入前再问一次，别让锁漏在竞态里。
+            const recheck = draftLockBlockFor(k, args, "渲染关系");
+            if(recheck) return fail("draft-locked", recheck.message, { lock: recheck.lock });
+            // force 只在**确实要写入**时才清锁：dryRun / 无变化的调用不该把 LLM 的锁带走。
+            if(args.force === true) clearDraftLockSync(k);
             const copy = JSON.parse(JSON.stringify(draft));
             copy.data.description = after;
             setDraftFor(k, copy);
@@ -2006,8 +2193,15 @@ function apply(ctx, config){
             draft = normalizeDraft(draft);
           }catch(e){ return fail("parse-failed", String(e.message)); }
           const k = draftKeyFrom(ctx, args);
+          // 0.11.0：解析可以先做（纯只读），但锁 active 时**不写草稿** —— 回 locked + preview 让界面进只读预览。
+          const locked = draftLockBlockFor(k, args, "导入");
+          if(locked) return ok({ locked: true, lock: locked.lock, preview: { draft, upgradedFrom }, key: k });
+          const backup = backupDraftSync(k, "import");
+          clearDraftLockSync(k);
           setDraftFor(k, draft);
-          return ok({ draft, key:k, draftStatus: draftStatusFor(k, draft), upgradedFrom });
+          const out = { draft, key:k, draftStatus: draftStatusFor(k, draft), upgradedFrom };
+          if(backup) out.backup = backup;
+          return ok(out);
         }
         case "cc_importFromJson":{
           // 工坊拖进来的 .json 走这里（0.9.1，B2）：V2/V1 卡**升级**成 CCv3，而不是让界面报「spec 不符」。
@@ -2025,8 +2219,14 @@ function apply(ctx, config){
             draft = normalizeDraft(obj);
           }catch(e){ return fail("invalid-card", String(e.message)); }
           const k = draftKeyFrom(ctx, args);
+          const locked = draftLockBlockFor(k, args, "导入");
+          if(locked) return ok({ locked: true, lock: locked.lock, preview: { draft, upgradedFrom }, key: k });
+          const backup = backupDraftSync(k, "import");
+          clearDraftLockSync(k);
           setDraftFor(k, draft);
-          return ok({ draft, key:k, draftStatus: draftStatusFor(k, draft), upgradedFrom });
+          const out = { draft, key:k, draftStatus: draftStatusFor(k, draft), upgradedFrom };
+          if(backup) out.backup = backup;
+          return ok(out);
         }
         case "cc_exportPng":{
           const k = draftKeyFrom(ctx, args);
@@ -2066,8 +2266,14 @@ function apply(ctx, config){
             draft = normalizeDraft(obj);
           }catch(e){ return fail("parse-failed", String(e.message)); }
           const k = draftKeyFrom(ctx, args);
+          const locked = draftLockBlockFor(k, args, "导入");
+          if(locked) return ok({ locked: true, lock: locked.lock, preview: { draft, upgradedFrom }, key: k });
+          const backup = backupDraftSync(k, "import");
+          clearDraftLockSync(k);
           setDraftFor(k, draft);
-          return ok({ draft, key:k, draftStatus: draftStatusFor(k, draft), upgradedFrom });
+          const out = { draft, key:k, draftStatus: draftStatusFor(k, draft), upgradedFrom };
+          if(backup) out.backup = backup;
+          return ok(out);
         }
         case "cc_exportCharx":{
           const k = draftKeyFrom(ctx, args);
@@ -2335,6 +2541,9 @@ export { apply, inject, name, planPresetInstall, installCcPreset, supportsDeclar
   persistDraftSync, loadPersistedDraftSync, libDirs, libDir, getDraftFor, setDraftFor, cardFingerprint, normalizeCardShape,
   // 草稿来源 id 的 sidecar（0.5.0）：两半同构，测试直接交叉读写验证互通
   readDraftOrigin, writeDraftOrigin, originFilePath,
+  // 草稿锁（0.11.0）：判定在 lib/draft-lock.js（两半共用），这里导出 IO / 备份供回归测试直接断言落盘
+  draftLockPath, readDraftLockSync, writeDraftLockSync, clearDraftLockSync, draftLockSummaryFor, draftLockBlockFor,
+  draftBackupDir, backupDraftSync, DRAFT_BACKUP_KEEP,
   listLibraryEntries, saveLibraryEntry, loadLibraryEntry, deleteLibraryEntry, renameLibraryEntry,
   // 人物关系图谱（0.8.0）：纯函数 + 落盘，供 tests/relations.test.mjs 直接断言、并与工具半逐字比对同构实现
   groupDirs, groupDir, groupPath, safeGroupId, newGroupId, normalizeGroup, validateGroupOp, applyGroupOps,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xia-sc/dsh-cc-studio",
-  "version": "0.10.3",
+  "version": "0.11.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/relations.test.mjs && node tests/relations-view.test.mjs && node tests/shared-book.test.mjs && node tests/shared-book-st-export.test.mjs && node tests/st-compat.test.mjs && node tests/promote-draft-sync.test.mjs && node tests/group-scope.test.mjs && node tests/group-metrics.test.mjs && node tests/group-checks.test.mjs && node tests/group-consistency.test.mjs && node tests/group-layer-guard.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/draft-lock-client.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/draft-lock.test.mjs && node tests/relations.test.mjs && node tests/relations-view.test.mjs && node tests/shared-book.test.mjs && node tests/shared-book-st-export.test.mjs && node tests/st-compat.test.mjs && node tests/promote-draft-sync.test.mjs && node tests/group-scope.test.mjs && node tests/group-metrics.test.mjs && node tests/group-checks.test.mjs && node tests/group-consistency.test.mjs && node tests/group-layer-guard.test.mjs && node tests/data-root.test.mjs",
     "prepublishOnly": "npm test"
   },
   "dsh": {
@@ -65,7 +65,8 @@
         "0.1.6-alpha.2": "compatible",
         "0.1.7-alpha.1": "compatible",
         "0.1.7-rc.1": "compatible",
-        "0.2.0-rc.2": "compatible"
+        "0.2.0-rc.2": "compatible",
+        "0.2.1-rc.2": "compatible"
       }
     }
   },

package/presets/cc/agent.cordis.yml

@@ -41,11 +41,11 @@
       3) cc_patch_world — 补五维 timeline/factions/geo/power/daily，至少填 3 项，autoLorebook=true 自动生成带 @@decorator 的基础条目；**同时给 loreKeys**（每一维自报用户真会说的实体名，如 {geo:["旧校舍","广播室","天台"]}）—— 不给的话自动条目的 keys 只有维度名，真实对话永远命中不了
       4) cc_add_lorebook_entries — 再补到至少 5 条，且**至少 1 条是你与用户共创的**（纯 autoLorebook 自动条目不算完成），覆盖年表/势力/地理/力量/日常各 1，至少 1 条 constant，content 头部写 @@position/@@depth/@@activate 等，支持 CBS 占位符（双花括号的 char / random / roll 形式）；写完用 cc_simulate_trigger 拿一句用户会说的话验一下命中
       5) cc_patch_greetings — 补 first_mes、alternate_greetings(≥2)、group_only_greetings(≥1 必填)、mes_example
-      6) cc_validate — 必须调且 valid=true 才算完成，否则按返回的 errors/warnings 继续补；通过后提醒用户在工坊左下角「校验导出」入口打开导出页选 JSON / PNG / CHARX，或点「★ 保存当前」落盘 ~/.dsh/cc-library
+      6) cc_validate — 必须调且 valid=true 才算完成，否则按返回的 errors/warnings 继续补；**通过后必须立刻调用 cc_release_draft 交还草稿编辑权**（不调用的话工坊一直只读、用户无法微调），然后再提醒用户在工坊左下角「校验导出」入口打开导出页选 JSON / PNG / CHARX，或点「★ 保存当前」落盘 ~/.dsh/cc-library
 
       辅助工具（按需，不必每步都调）：cc_patch_book_meta（世界书命名 / scan_depth / token_budget）、cc_lint_lorebook（世界书静态体检）、cc_simulate_trigger（验触发词命中）、cc_preview_export（导出前干跑）、cc_new_card（重置草稿，**必须先经用户同意**再带 confirm:true）、cc_update_lorebook_entry / cc_delete_lorebook_entries（改删单条）、已存库 cc_list_library / cc_save_to_library / cc_load_from_library / cc_rename_in_library / cc_delete_from_library / cc_get_library_entry（载入后直接保存会更新原卡，不会新建重复卡）。
 
-      规则：每次对话只追问 1-2 个薄弱点，问完立刻调工具写入；用户说“随便/跳过”也要你合理推断补全，不能留空；严禁跳过 3/4 步直接做问候语；每调一次工具要简要总结“已写入 X，下一步 Y”，并让胶囊实时同步；结束前必须 cc_validate。工具返回里只有一份 workflow.next（下一步该做什么）与 workflow.hint（进度摘要），照它走即可；用户还没回答就别抢跑。
+      规则：每次对话只追问 1-2 个薄弱点，问完立刻调工具写入；用户说“随便/跳过”也要你合理推断补全，不能留空；严禁跳过 3/4 步直接做问候语；每调一次工具要简要总结“已写入 X，下一步 Y”，并让胶囊实时同步；结束前必须 cc_validate；**cc_validate 通过 = 创作完成，必须调用 cc_release_draft 交还草稿锁收口**（不调就算没做完；之后用户要改，你再写会自动重新上锁）。工具返回里只有一份 workflow.next（下一步该做什么）与 workflow.hint（进度摘要），照它走即可；用户还没回答就别抢跑。
 
       **工具参数必须是严格合法的 JSON**：最后一个字段 / 数组元素后不要写逗号，不要用 ```json 代码块包裹，不要注释、不要单引号；字符串里的换行写成 \n、双引号写成 \"。一次只传 1-3 个字段，长字段（description/personality/scenario）分多次调用写；tags / loreKeys 这类数组或对象字段单独一次调用，不要和长文本同批。参数 JSON 非法时 provider 会在调用前直接判本轮失败（用户只看到「本轮运行失败」），所以宁可分多次小调用。
 
@@ -54,6 +54,12 @@
   config:
     maxBytes: 65536
 
+# 0.2.1 对齐：time-context 从 host 层挪进预设行（dsh 0.2.1-rc.2 的内置 standard 有这一行）。
+# 包 @deepseek-ai/dsh-time-context 在 dsh 0.1.6-alpha.2 的依赖里也存在，
+# 且那一代 host 层没有挂它，所以旧版目录形态上补这一行不会重复注册、不会 broken。
+- id: time-context
+  name: '@deepseek-ai/dsh-time-context'
+
 # ── shell ───────────────────────────────────────────────────────────────────
 
 # `shell-env` stays in the HOST composition: `apps/cli/src/web.ts` injects it to
@@ -104,11 +110,9 @@
 # carries whatever the deployment registered globally (repository plugins).
 - id: skill-filesystem
   name: '@deepseek-ai/dsh-skill-filesystem'
-  disabled: true
 
 - id: tool-skill
   name: '@deepseek-ai/dsh-tool-skill'
-  disabled: true
 
 # 0.3.7 补回：内置 `standard` 自 0.1.6-alpha.2 起就带这一行，本预设初次拷贝时整行漏掉了
 # （与 0.3.4 补回的 `present` 同类：不报错、不判 broken，只是少了能力）。
@@ -143,7 +147,7 @@
       name: '@deepseek-ai/dsh-plan-mode'
       config:
         section: |
-              You are in plan mode. Stay in plan mode until exit_plan_mode succeeds or the user switches the session mode. Imperative language to implement changes means plan the implementation, not execute it. A user's conversational agreement — including an answer confirming something you asked — approves nothing and does not end plan mode; fold the confirmed decision into the plan and submit it through exit_plan_mode.
+              You are in plan mode. Stay in plan mode until the user approves your plan through exit_plan_mode or switches the session mode. Imperative language to implement changes means plan the implementation, not execute it. A user's conversational agreement — including an answer confirming something you asked — approves nothing and does not end plan mode; fold the confirmed decision into the plan and submit it through exit_plan_mode.
 
               Explore first. Use non-mutating reads, searches, static analysis, and checks to ground the plan in the actual repository. Do not edit or write files, change configuration, run formatters or code generation that rewrites tracked files, commit, or otherwise carry out the plan. Prefer existing functions and patterns over new machinery.
 
@@ -225,36 +229,12 @@
         provider: spawn
         toolName: subagent
         modelSelectionSettings: true
-        backgroundMode: continuable
 
     - id: tool-subagent-fork
       name: '@deepseek-ai/dsh-tool-subagent'
       config:
         provider: fork
         toolName: subagent_fork
-        backgroundMode: continuable
-
-    # Production dsh does not install these optional providers. Install the
-    # matching Bundle in this Profile and restart the Host, then copy this
-    # preset and remove `disabled` from the matching tool row. Host availability
-    # alone grants no tool.
-    - id: tool-subagent-codex
-      name: '@deepseek-ai/dsh-tool-subagent'
-      disabled: true
-      config:
-        provider: codex
-        toolName: subagent_codex
-        backgroundMode: one-shot
-        maxDepth: provider-managed
-
-    - id: tool-subagent-claude-code
-      name: '@deepseek-ai/dsh-tool-subagent'
-      disabled: true
-      config:
-        provider: claude-code
-        toolName: subagent_claude_code
-        backgroundMode: one-shot
-        maxDepth: provider-managed
 
     # dsh 0.1.6-alpha.1: `dsh-workflow-worker-thread` is gone from the release;
     # the workflow engine is now `dsh-workflow-ptc` (sandboxed Node PTC runtime,
@@ -270,12 +250,6 @@
     - id: tool-workflow
       name: '@deepseek-ai/dsh-tool-workflow'
 
-    - id: tool-ralph
-      name: '@deepseek-ai/dsh-tool-ralph'
-      config:
-        subagentProvider: spawn
-        maxRounds: 64
-
 # ── remaining model-facing rows ─────────────────────────────────────────────
 
 - id: tool-ask-user
@@ -291,7 +265,7 @@
 - id: tool-web
   name: '@deepseek-ai/dsh-tool-web'
   config:
-    fetch: false
+    fetch: true
     searchTimeoutMs: 60000
 
 # 0.3.4 补回：`present` 是 standard 一直有的行，本预设此前整行漏抄。
@@ -309,6 +283,16 @@
   name: '@deepseek-ai/dsh-plugin-manager/tools'
   disabled: true
 
+# ── 与 dsh 0.2.1-rc.2 内置 standard 的**有意差异**（下次升级 diff 别当成漏抄）──
+# · `tool-schedule`：0.2.1 standard 有，但 `@deepseek-ai/dsh-tool-schedule` 在
+#   dsh ≤ 0.1.6-alpha.2 的依赖里不存在，而这份清单同时喂给目录形态（旧版）；
+#   非 disabled 行解析不到包会让**整个预设 broken**（unresolvableRows），
+#   所以为兼容旧版不带这一行。CC 模式也不需要定时任务工具。
+# · `tool-plugin-market`：0.2.1 standard 里是 disabled，但 0.1.6 没有
+#   `@deepseek-ai/dsh-plugin-market` 这个包；按家规「不拿 disabled 遮掩
+#   一个已经不存在的包」，同样不带。
+# 其余行与 standard 逐行对齐；本预设只保留 persona 定制与末尾的 cc-agent 行。
+
 # ── CC 角色卡工坊（CC 模式专用） ───────────────────────────────────
 - id: cc-agent
   name: '@xia-sc/dsh-cc-studio/agent'