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

package/README.md

@@ -10,13 +10,13 @@
 
 > 从一句话点子到可导入 SillyTavern / Risu 的 `chara_card_v3`。专治「只有点子，世界观薄弱」。
 
-DSH（DeepSeek Harness）插件：输入框上方的胶囊 → 全屏融合工坊，配合 `CC 模式` 预设让 LLM 通过 32 个 Tool **先问再填**、与你共创角色卡，最后一键导出 `JSON / PNG / CHARX`。
+DSH（DeepSeek Harness）插件：输入框上方的胶囊 → 全屏融合工坊，配合 `CC 模式` 预设让 LLM 通过 33 个 Tool **先问再填**、与你共创角色卡，最后一键导出 `JSON / PNG / CHARX`。
 
 | 项目 | 值 |
 | --- | --- |
-| 包名 / 版本 | `@xia-sc/dsh-cc-studio` `0.10.3` |
+| 包名 / 版本 | `@xia-sc/dsh-cc-studio` `0.11.1` |
 | 兼容 | DSH `>=0.4.5-rc.4`（含**桌面版**）、Node `>=22`、**零运行依赖**；逐版本实测见 [兼容与权限](#兼容与权限) |
-| 落盘位置 | `<DSH_HOME>/cc-library/`（角色卡）、`<DSH_HOME>/cc-drafts/`（会话草稿）；`DSH_HOME` 默认 `~/.dsh`，旧位置仍读得到 |
+| 落盘位置 | `<DSH_HOME>/cc-library/`（角色卡）、`<DSH_HOME>/cc-drafts/`（会话草稿；LLM 创作锁 `.lock.json` 与覆盖前备份 `backups/` 也在这里）；`DSH_HOME` 默认 `~/.dsh`，旧位置仍读得到 |
 | 文档 | 用户文档＝本文件；改代码前必读 [AGENTS.md](./AGENTS.md)；完整历史 [CHANGELOG.md](./CHANGELOG.md) |
 
 ---
@@ -42,7 +42,7 @@ DSH（DeepSeek Harness）插件：输入框上方的胶囊 → 全屏融合工
    dsh --profile <profile> --dump-config
    期望在 `# == @xia-sc/dsh-cc-studio` 那一层下看到两行：`id: dsh-cc-studio`（宿主行）与 `id: preset-cc`（CC 预设行）。
 4. 告诉用户重启：宿主行只在启动时组合 —— CLI 重启 `dsh web`，桌面版退出并重新打开应用。
-5. 重启后可选自检：在「CC 模式」会话里调任意一个 cc_* 工具，返回里带 "build": "0.10.3" 即说明新代码已加载
+5. 重启后可选自检：在「CC 模式」会话里调任意一个 cc_* 工具，返回里带 "build": "0.11.1" 即说明新代码已加载
    （这也是判断「改了但没重启」的唯一可靠依据）。
 6. 不要做的事：
    - 不要手工把 presets/ 拷进 ~/.dsh/.agent-presets/（dsh >= 0.4.7-alpha.4 已不读该目录，拷了也不生效）；
@@ -58,9 +58,9 @@ DSH（DeepSeek Harness）插件：输入框上方的胶囊 → 全屏融合工
 ```bash
 # 从 npm 安装（推荐）
 dsh plugin --profile web add @xia-sc/dsh-cc-studio
-dsh plugin --profile web add @xia-sc/dsh-cc-studio@0.10.3    # 锁定版本
+dsh plugin --profile web add @xia-sc/dsh-cc-studio@0.11.1    # 锁定版本
 
-# 从 GitHub 源安装（可加 #v0.10.3 / #master 指定 tag / 分支）
+# 从 GitHub 源安装（可加 #v0.11.1 / #master 指定 tag / 分支）
 dsh plugin --profile web add github:xia-sc/dsh-cc-studio
 
 # 从本地仓库安装（开发 / 调试）：装出来是 link:，改 lib/*.js 重启即生效
@@ -94,6 +94,7 @@ dsh plugin --profile web remove @xia-sc/dsh-cc-studio       # 卸载（同时移
 | 改完代码没变化 | 分三层看：改 `lib/client.js` → 刷新页面；改 `lib/index.js`（宿主）或预设 → **重启 dsh（桌面版重启应用）**；先看一眼工具返回里的 `build` 是不是你以为的版本 |
 | 偶发「本轮运行失败 `tool input is invalid JSON`」 | 模型生成的工具参数 JSON 有语法错误（最常见是尾逗号），DSH provider 严格 `JSON.parse` 后判 `MALFORMED_RESPONSE`，且默认不重试。0.10.2 已在 persona 与五个写类工具描述里要求「严格 JSON + 分小步写（数组字段单独一批）」，**重启 dsh 让新文本生效**；仍偶发就重发同一句话（模型会重新生成），或在 profile 的 `cordis.patch.yml` 给 `llm-deepseek-account` 加 `retryPolicy`（`retryableCodes` 要**写全默认 5 码 + `MALFORMED_RESPONSE`** —— 补丁层对 config 是整条替换、不做深合并），完整片段见 CHANGELOG 0.10.2 |
 | 卡里的换行显示成字面 `\n`（如「说完这句话。\n\n下一段」） | 模型在 tool call 里把换行写成了字面 `\n`（JSON 多转义一层），旧版工具原样落盘。0.10.3 起写类工具统一解码字面 `\n` / `\r` / `\t`（含多层转义），**重启 dsh 生效**。⚠️ 已存卡里已经被写坏的字段不会自动修复 —— 重新调一次对应工具写入那几个字段，或在工坊里手动改回真换行 |
+| LLM 正在创作时，点「载入」另一张卡没反应/只出预览，工坊变只读 | 这是 0.11.0 的**草稿锁**（LLM 创作保护）：LLM 写草稿后自动锁住，载入/导入只进只读预览，不会覆盖 LLM 未保存的草稿。让 LLM 调 `cc_release_draft` 交还、或等锁超过 **30 分钟**无写入自动失效，工坊即恢复可编辑；也可以在 设置 →「角色卡工坊」→ 工坊默认行为里关掉「**LLM 创作保护（草稿锁）**」（等价旧行为）。被覆盖前的草稿都在 `<DSH_HOME>/cc-drafts/backups/`（同槽最多 20 份） |
 
 ---
 
@@ -101,9 +102,9 @@ dsh plugin --profile web remove @xia-sc/dsh-cc-studio       # 卸载（同时移
 
 4. 新建会话，会话模式选 **CC 模式** —— 胶囊随即出现在输入框上方，后台会把 CC 预设挂上。
 2. 直接说需求，例如「我想做雨城记忆典当行老板娘，世界观很薄」。
-3. 模型按 **6 步**推进，每步先用 4-2 个开放问题问你的偏好，再落笔；每次调用 Tool，胶囊与工坊实时刷新：
-   `cc_get_card`（总结进度 + 提问）→ `cc_patch_character`（气质/关系 → 四件套）→ `cc_patch_world`（世界侧重 → ≥3 维 + `autoLorebook`）→ `cc_add_lorebook_entries`（触发词 → ≥5 条，至少 4 条 `constant`）→ `cc_patch_greetings`（开场场景 → 问候语）→ `cc_validate`。
-4. 随时点胶囊进工坊手改。校验通过后：侧栏 `★ 保存当前`（已载入 ID 时原地覆盖，否则新建）、`＋ 另存为新`，或导出 `JSON / PNG / CHARX`；也可以直接对模型说「帮我载入 ID xxxx」。
+3. 模型按 **6 步**推进（第 6 步校验通过后再调用 `cc_release_draft` 交还编辑权），每步先用 4-2 个开放问题问你的偏好，再落笔；每次调用 Tool，胶囊与工坊实时刷新：
+   `cc_get_card`（总结进度 + 提问）→ `cc_patch_character`（气质/关系 → 四件套）→ `cc_patch_world`（世界侧重 → ≥3 维 + `autoLorebook`）→ `cc_add_lorebook_entries`（触发词 → ≥5 条，至少 4 条 `constant`）→ `cc_patch_greetings`（开场场景 → 问候语）→ `cc_validate`（校验通过）→ `cc_release_draft`（交还草稿编辑权）。
+4. 随时点胶囊进工坊看进度。**LLM 写作期间工坊是只读的**（它持有草稿锁，你载入别的卡只会进入只读预览，不会覆盖它正在写的草稿）；校验通过、你确认创作完成后，让 LLM 交还编辑权限（`cc_release_draft`），或等锁 30 分钟无写入自动失效，再在工坊里微调。之后：侧栏 `★ 保存当前`（已载入 ID 时原地覆盖，否则新建）、`＋ 另存为新`，或导出 `JSON / PNG / CHARX`；也可以直接对模型说「帮我载入 ID xxxx」。
 
 ---
 
@@ -116,16 +117,18 @@ dsh plugin --profile web remove @xia-sc/dsh-cc-studio       # 卸载（同时移
 - **文档式阅读排版**：字段是无边框 textarea、按内容自动撑高，点进去即可改；长文点「⛶」开 720px 大框（带打开时快照，「取消」真回滚）。写作是主线，手动编辑是次要入口。
 - **5 维世界观**：年表 / 势力 / 地理 / 力量体系 / 日常 → `autoLorebook` 自动生成带 `@@position / @@depth / @@activate` 的条目（至少 4 条 `constant`；再次调用覆盖旧自动条目、保留手工条目）。
 - **ID 化 CRUD**：`★ 保存当前`（已载入时原地覆盖）/ `＋ 另存为新` / `✎ 重命名` / `＋ 新建` / 载入 / 删除，搜索、高亮当前卡，落盘 `<DSH_HOME>/cc-library/<id>.json`。
+- **LLM 创作保护（草稿锁，0.11.0）**：LLM 每次写草稿都会上锁（`<DSH_HOME>/cc-drafts/<槽>.lock.json`），锁 active 期间工坊只读、载入/导入只进**只读预览**（草稿与来源 id 都不写），退出预览即回到 LLM 的草稿；LLM 调 `cc_release_draft` 交还、或锁 30 分钟无写入自动失效后恢复编辑。设置页可关掉该保护（关闭 = 旧行为）。任何覆盖型动作（载入/导入/迁移/force 覆盖）前都会把当前草稿备份到 `<DSH_HOME>/cc-drafts/backups/`（同槽最多 20 份，空壳与同内容不重复备份）
 - **导入导出**：`⬆ 导入 JSON/PNG/CHARX` 自动识别容器；`⬇ JSON`、`⬇ PNG`（4×4 占位图）、`⬆ 写入 PNG`（写入你上传的任意 PNG，自动剥离旧 `ccv3/chara` 块并重算 CRC32）、`⬇ CHARX`（打包 `card.json`）。
 - **中英双语 + 深浅色**：完整 `zh / en` 词表，跟随 `设置 → 通用 → 语言` 实时切换；配色走 `var(--dsw-alias-*)`，主操作固定品牌紫 `#7c5cff`。
 
-### CC 模式（模型侧 32 个 Tool）
+### CC 模式（模型侧 33 个 Tool）
 
 **6 步工作流 + 共创约束**：每步前必须先问偏好，严禁无讨论就一次性填满；世界书的完成态是「**≥5 条且至少 4 条共创**」（纯自动条目不算完成）。每次返回只有一份 `workflow.next`（下一步）+ `workflow.state`（四项三态进度）+ `message`（给用户的一句话），另有 `build` 标明插件版本。
 
 | 分类 | 工具 |
 | --- | --- |
 | 工作流（必调） | `cc_get_card` / `cc_patch_character` / `cc_patch_world` / `cc_add_lorebook_entries` / `cc_patch_greetings` / `cc_validate` |
+| 创作收口（0.11.0） | `cc_release_draft` —— **`cc_validate` 通过（valid=true）= 创作完成，必须立刻调用**，把草稿编辑权交还用户（释放锁，工坊恢复可编辑）。不释放时工坊保持只读，用户只能预览；persona、`cc_validate` 终态与首次上锁提示都会反复引导模型调用它 |
 | 世界书质量 | `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`） |
@@ -139,6 +142,7 @@ dsh plugin --profile web remove @xia-sc/dsh-cc-studio       # 卸载（同时移
 - `cc_patch_world` 的 **`loreKeys`**：为每一维自报触发词（真实对话里用户会说的实体名）。不给的话自动条目只能用维度名当 key，**真实对话永远命中不了**。同一实体被分给多个维度时会当场警告。
 - **载入后直接保存会更新原卡**（草稿旁记着来源 id），不会再莫名多出一张同名重复卡；改名同时改列表名与卡内 `data.name`。
 - 写类工具支持 **`expectedRev` 乐观锁**；不传也会在返回里给 `revDrift` 与 `draftStatus.watchedRev`，多端同时改卡时不会静默覆盖。
+- **草稿锁（0.11.0）**：模型每次写草稿都会自动上锁（`draftStatus.lock` 能随时看到自己是否持有），工坊随即只读、用户载入只进只读预览；创作完成调用 `cc_release_draft` 交还。锁超过 30 分钟无写入会自动失效（防模型崩溃后把工坊永久锁死），模型再写会自动重新上锁。
 - 工具返回的 `build` 与 `package.json` 的 `version` 同步 —— 能一眼确认当前跑的是哪一版代码。
 - **分组的增删改查模型侧也能做**（0.8.0 补）：`cc_create_group` 建组、`cc_set_card_group` 把卡放进/换/移出（`cardId` 省略 = 当前草稿的来源卡，**不传 `groupId` = 移出**）、`cc_delete_group` 是破坏性操作须显式 `confirm:true`。**移出分组不删节点与关系**（挪回来关系还在），**删组不删卡**（只清成员卡的 `meta.groupId`）。
 
@@ -176,8 +180,8 @@ dsh plugin --profile web remove @xia-sc/dsh-cc-studio       # 卸载（同时移
 ## 开发与测试
 
 ```bash
-npm test                                    # 22 个文件、864 项断言，全绿才算过
-node tests/tools-contract.test.mjs          # 只跑 CC 工具链契约（104 项）
+npm test                                    # 24 个文件、987 项断言，全绿才算过
+node tests/tools-contract.test.mjs          # 只跑 CC 工具链契约（125 项）
 node tests/group-layer-guard.test.mjs       # 只跑卡组层的耦合守卫（16 项）
 ```
 
@@ -188,6 +192,10 @@ node tests/group-layer-guard.test.mjs       # 只跑卡组层的耦合守卫（1
 
 完整历史见 [CHANGELOG.md](./CHANGELOG.md)。最近几版大多是「另一个 LLM 以工具使用者身份跑回归」挖出来的问题：
 
+- `0.11.1` **CC 预设对齐 dsh `0.2.1-rc.2` 内置 `standard`**：修掉 `tool-ralph` 漏抄 `disabled`（CC 模式一直多挂一个实验性长循环工具）、`skill-filesystem` / `tool-skill` 被误关（模型没有技能目录与加载器）、以及 `backgroundMode` 等已下线的配置键；补 `time-context`、`tool-web` 的 `fetch` 改回 `true`。`dshReleases` 补 `0.2.1-rc.2`（npm `dsh web` 隔离环境实测）。测试补 CHARX 导入全链路与「按 id 改世界书条目」的回归 → **987 项**。**重启 dsh（桌面端重启应用）生效**。
+
+- `0.11.0` **新增 LLM 草稿锁（读写分离）**：LLM 创作期间工坊只读、载入/导入只进只读预览，不再覆盖未保存草稿；`cc_release_draft` 交还编辑权，锁 30 分钟无写入自动失效，设置页可关闭。**修复**：角色卡完成后主动交还锁（persona / `cc_validate` / 首次上锁三处引导）、客户端草稿来源 id 恢复失效；覆盖型载入/导入前自动备份到 `cc-drafts/backups/`。测试 864 → **959 项**。详细见 [CHANGELOG](./CHANGELOG.md)。
+
 - `0.10.3` **多行文本被写成字面 `\n`**：用户实机报告（六步全链路 `valid: true`）发现经 `cc_patch_character` / `cc_patch_greetings` / `cc_patch_world` 写入的字符串，换行全部落盘成字面 `\` + `n`，导进 SillyTavern 显示成「说完这句话。\n\n下一段」。取证推翻了「工具多转义」的猜测：工具层往返测试证明真换行原样保留；会话日志里模型 18 次调用有 6 次在 JSON 里把换行写成 `\\n`（多转义一层），而 `alternate_greetings` / lorebook 却写对了 —— 是**模型输出不一致**。修法：写类工具统一 `textArg()` 解码字面 `\n` / `\r` / `\t`（多层转义最多 4 轮收敛），覆盖角色 / 问候语 / 世界书条目 / 书级元信息 / 共享书；工坊保存与导入路径不动。顺带修报告 P2（卡内 `token_budget` 默认 1200 → **2400**）与 P4（autoLorebook 的「力量体系」条目裸 `@@activate` → `@@activate 100`）。测试 858 → **864 项**。**重启 dsh 生效**；已存卡里已写坏的字段需重写。
 
 - `0.10.2` **模型偶发一个 JSON 尾逗号，整轮就没了**：报错是 `本轮运行失败 DeepSeek Messages stream: tool input is invalid JSON`。会话日志解帧取证：模型调 `cc_patch_character` 时生成的 arguments 末尾是 `..."tags":[...],}`（尾逗号）。根因在 provider：`@deepseek-ai/dsh-llm-deepseek` 在流结束时对 tool input 严格 `JSON.parse`，失败即 `MALFORMED_RESPONSE`，而默认 `retryableCodes` 不含它 → 不自动重试；工具从未执行、卡片数据没坏。插件能施加影响的只有模型可见文本，所以给 persona 加「工具参数必须是严格合法 JSON（禁尾逗号/注释/单引号/未转义换行），一次只传 1-3 个字段、长字段分多次写」，五个写类工具的 description 同步这句规则，并用测试钉住（preset-install + tools-contract 各 +1 项）。用户侧可选兜底：在 profile `cordis.patch.yml` 给 `llm-deepseek-account` 配 `retryPolicy.retryableCodes` 含 `MALFORMED_RESPONSE`（详见 CHANGELOG 0.10.2）。测试 856 → **858 项**。**重启 dsh（桌面版重启应用）生效**。

package/lib/agent.js

@@ -14,12 +14,16 @@ 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.3";
+const BUILD = "0.11.1";
 const inject = ["tools", "agents"];
 
 function nowSec(){ return Math.floor(Date.now()/1000); }
@@ -146,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 });
@@ -171,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,
   };
@@ -337,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;
 }
 
@@ -1016,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 等
@@ -1045,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
@@ -1093,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`
@@ -2465,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){
@@ -2513,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),
@@ -2544,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 || "未命名") + "」：工坊恢复可编辑，用户现在可以载入/导入别的卡，不会覆盖你的草稿。若你继续写草稿，会自动重新锁定。"
+          : "当前没有草稿锁（可能已释放过，或已超时自动失效），无需重复释放。如果你继续写草稿，会自动重新锁定。",
+      };
+    }
+  });
 }
 
 // ——————————————————————————————————————————————————————————————
@@ -2981,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 与宿主半逐字比对同构实现