dsh-maoying 0.1.13 → 0.1.14

package/README.en.md

@@ -74,8 +74,8 @@ A reply of "ok / sure / go on" counts as confirmation; the chief advances direct
 Open "**毛颖创作台**" at the bottom of the DSH sidebar — a full-page cockpit for the human eye, beyond what agents do:
 
 - **Chapters**: status filters + the writing queue; click a chapter for full-page reading — back button, outline side-by-side (Markdown rendered), read-only manuscript, five narrative-dimension fields, one-click status flow.
-- **Novel Settings**: form-based editing of project.yml — title / author / genre / planned length / language / workflow phase / co-writing mode / synopsis; saving preserves the file's existing comments.
-- **Top bar**: current version always visible; a "new version ↗" badge links to the release page when npm has a newer one; the gear opens Settings — UI language (中文/English), six font-size steps (100%–150%), all applied immediately and remembered.
+- **Novel Settings**: form-based editing of project.yml — title / author / genre / planned length / language / workflow phase / co-writing mode / synopsis; saving preserves the file's existing comments. If project.yml was changed externally after the form loaded (manual edits or an agent advancing the phase), saving is rejected with a prompt to re-edit from the latest content instead of overwriting.
+- **Top bar**: current version always visible; a "new version ↗" badge links to the release page when npm has a newer one, next to an "Upgrade now" button that installs the latest release into the current DSH profile with pnpm (profile-directory installs only; a DeepSeek restart is required to take effect); the gear opens Settings — UI language (中文/English), six font-size steps (100%–150%), all applied immediately and remembered.
 
 The panel only writes state (chapter status, project.yml, index.yml rebuilds), never prose — prose belongs to the author and the chief.
 

package/README.md

@@ -74,8 +74,8 @@ npm install -g dsh-maoying       # 或装成全局 maoying 命令
 DSH 左侧栏底部点「**毛颖创作台**」打开全页面板（改文件、跑流程之外，给肉眼看的驾驶舱）：
 
 - **章节**：状态筛选 + 按单写作清单；点章节进整页阅读——返回按钮、章纲对照（Markdown 渲染）、只读正文、五维叙事字段、一键状态流转。
-- **小说设置**：project.yml 的书名/作者/题材/篇幅/语言/工作流阶段/共创模式/简介表单化编辑，保存保留文件里原有注释。
-- **顶栏**：当前版本号常驻；npm 上有新版时亮「有新版 ↗」徽章直连发布页；齿轮打开系统设置，界面语言中文/English 可切、字号六档（100%–150%）整体缩放，均立即生效并记忆。
+- **小说设置**：project.yml 的书名/作者/题材/篇幅/语言/工作流阶段/共创模式/简介表单化编辑，保存保留文件里原有注释；表单载入后 project.yml 被外部（作者手改 / agent 推进阶段）改过时拒绝保存并提示重改，不覆盖人工改动。
+- **顶栏**：当前版本号常驻；npm 上有新版时亮「有新版 ↗」徽章直连发布页，旁边「一键升级」按钮直接用 pnpm 把最新包装进当前 DSH 档（仅支持 profile 目录安装；装完需重启 DeepSeek 才生效）；齿轮打开系统设置，界面语言中文/English 可切、字号六档（100%–150%）整体缩放，均立即生效并记忆。
 
 面板只写状态（章节状态、project.yml、index.yml 重建），不改正文——正文永远归作者与主编。
 

package/docs/creator-panel.md

@@ -39,17 +39,19 @@ webServer.register({ kind: 'prefix', path: '/api/maoying', handler: async (req,
 |---|---|---|---|
 | `client.css` | GET | — | text/css（lib/base.css 现读，no-cache） |
 | `update-check` | GET | — | `{ ok, current, latest, updateAvailable, releaseUrl, checkedAt, error, source }`——新版检测（npm registry → npmmirror → GitHub 三级源，1h 缓存 + 7 天 stale-if-error，全败静默降级为 latest=null / error 非空） |
+| `self-update` | POST | — | `{ ok, from, to, restartRequired: true }` 或 `{ ok: false, kind, error }`——面板内一键升级：安装形态/pnpm 探测通过后跑 `pnpm --dir <profileDir> add dsh-maoying@latest`（180s 超时，无 shell）。仅支持 `<dshHome>/profiles/<profile>/node_modules/dsh-maoying` 真实目录安装；symlink/dev 检出（dev-link）与非 profile 布局（unsupported-layout）、pnpm 缺失（pnpm-missing）、超时（timeout）、pnpm 非零退出（pnpm-failed）一律 200 + ok:false。**装完只换磁盘包，运行中进程仍是旧代码，restartRequired 恒 true——重启 DeepSeek 后生效** |
 | `host-debug` | GET | — | `{ ok, hostVersion, trace, shape, registry, runtime }`——现场诊断（见下节） |
 | `workspaces` | GET | — | `{ ok, workspaces: [{ path, name, hasNovel }] }`——workspaceRegistry.list() 逐根探测 `<root>/novel/project.yml` |
 | `state` | GET | `path=<root>` | 全量快照（见 §3 契约） |
+| `check` | GET | `path=<root>` | `{ ok, problems: [{ level, file, message }] }`——静态体检：与 CLI check 同源的 checkProject，读章节 frontmatter 原文（快照会把越枚举 status 归一成 pending，这里透出原始问题清单；level ∈ error/warn，可为空数组），概览「静态体检」黄条取数 |
 | `chapter` | GET | `path`, `file`（chapters/ 下文件名） | `{ ok, file, frontmatter, body, outline }`——正文全文 + 对应章纲（`{ file, words, body }`，outlines/ 无对应文件时 null），章节抽屉用 |
 | `chapter-status` | POST | `{ path, file, status }` | `{ ok }`——frontmatter status 行原地替换；status 必须 ∈ pending/writing/review/accepted |
 | `foreshadow-status` | POST | `{ path, id, status }` | `{ ok }`——foreshadows.yml 对应条目 status 行替换；∈ planted/progressing/resolved/abandoned |
 | `phase` | POST | `{ path, phase }` | `{ ok }`——project.yml phase 行替换；七态枚举 |
-| `project-save` | POST | `{ path, values }`（8 平键，title/author/genre/length/language/phase/mode/description） | `{ ok }`——mutateProject 逐键改写保行尾注释、缺键按模板补齐；phase/mode 越枚举与空书名 422 |
+| `project-save` | POST | `{ path, values, base_hash? }`（values 为 8 平键 title/author/genre/length/language/phase/mode/description；base_hash 为表单载入时的 project.yml 指纹，即快照 `project_hash`） | `{ ok, project_hash }`——mutateProject 逐键改写保行尾注释、缺键按模板补齐；phase/mode 越枚举与空书名 422；base_hash 与写入前现读原文不一致 → 409「外部修改冲突」拒写不落盘（人工改动保护：表单载入后文件被作者/agent 改过即拒绝静默覆盖；缺省 base_hash 跳过检查，兼容旧调用方）。project_hash 为写后新指纹，客户端可作下一轮基线 |
 | `rebuild-index` | POST | `{ path }` | `{ ok, chapters }`——照 CLI index 同一逻辑重建 index.yml |
 
-共 11 条。写操作全部「行级原地替换」：只在 frontmatter/目标 yml 的对应行上做字符串手术，写前读、写后校验（替换计数 ≠1 即 409 拒写并报错），不做整文件重排——把对 git diff 的扰动压到最小，也与 agent 的写法兼容。
+共 13 条。写操作全部「行级原地替换」：只在 frontmatter/目标 yml 的对应行上做字符串手术，写前读、写后校验（替换计数 ≠1 即 409 拒写并报错），不做整文件重排——把对 git diff 的扰动压到最小，也与 agent 的写法兼容。（`self-update` 是例外：它不碰小说文件，跑的是 pnpm 安装。）
 
 ### host-debug 端点（现场诊断）
 
@@ -71,13 +73,14 @@ webServer.register({ kind: 'prefix', path: '/api/maoying', handler: async (req,
   "root": "<workspace root>",
   "novelDir": "<root>/novel",
   "found": true,                          // false 时其余字段缺省，面板显示「未初始化」引导
+  "project_hash": "9f86d0…",              // sha256(project.yml 原文) hex——面板保存回传 project-save 的 base_hash 做旧版检测（人工改动保护），读不到为 null；found:false 时恒为 null
   "project": { "title","author","genre","length","language","phase","mode","description" },  // mode: ai-draft|co-write|author-draft（五期）
   "chapters": [{ "file","volume","num","title","status","words","summary",
                  "cognitive_frame","emotional_anchor","world_texture",
                  "suspense","interpersonal_tension" }],     // 按 volume,num 升序；words 为 CJK 计数
   "characters": [{ "file","name","age","gender","role","appearance","personality",
                    "background","motivation","arc","markers" }], // markers 数组，缺省 []
-  "relations": [{ "a","b","type","description","intensity","started","ended" }],
+  "relations": [{ "a","b","type","description","intensity","started","ended" }], // a/b：relations.yml 里是角色 slug，出快照时对得上角色卡的端点归一成 name（关系图按 name 找节点），对不上原样保留
   "foreshadows": [{ "id","title","status","priority","planted_chapter",
                     "expected_resolve","resolved_chapter","notes","source" }], // source: plan|backfill，缺省 plan
   "timeline": [{ "year","title","description","importance","chapter" }],
@@ -105,7 +108,7 @@ webServer.register({ kind: 'prefix', path: '/api/maoying', handler: async (req,
 
 九个 tab（顺序即默认排布，第 9 个为后续迭代新增）：
 
-1. **概览**：project 卡（书名大字 + 类型/篇幅/语言 pills + 阶段徽章 + 简介）；统计卡（总字数/章节数/状态分布条）；最近更新（chapters 按 mtime 前 5）；warnings 黄条。
+1. **概览**：project 卡（书名大字 + 类型/篇幅/语言 pills + 阶段徽章 + 简介）；统计卡（总字数/章节数/状态分布条）；最近更新（chapters 按 mtime 前 5）；warnings 黄条；静态体检黄条（check 路由问题清单，见 §4.1「人工改动保护 + 静态体检黄条」（0.1.14）条目）。
 2. **章节**：表格（卷-章/标题/状态徽章/字数/梗概），状态筛选 pills；表格上方「按单写作」区块——有章纲且 status=pending 的章按序列出（章纲节选 + 状态徽章，共创模式的主工作清单）；行点击开整页阅读视图（0.1.12 起替代原右侧抽屉——fixed 侧弹层会被 DSH 侧边栏遮挡）：返回按钮 + GET chapter 正文（只读，等宽滚动）+ 章纲对照栏（左右分栏或折叠段）+ 复制文件路径按钮 + 五维字段卡 + 状态流转按钮（当前态 → 下一态一键，pending→writing→review→accepted）。
 3. **角色**：卡墙（姓名/role 徽章四色/年龄性别/性格一句/动机一行），点击看全卡（含 arc/markers/background）。
 4. **伏笔**：四列看板（埋设/推进/已回收/弃用），卡片含 priority 色点（high 红/normal 灰/low 淡）、`source: backfill` 的「回填」小徽章（账本回填来的条目，区别于写前规划）、埋设章→预期回收章、notes 全文直显（0.1.10 去掉两行截断）；卡片按钮：推进到下一状态（planted→progressing→resolved；abandoned 只能从看板拖不动、按钮给「弃用」）。列头计数。
@@ -116,16 +119,18 @@ webServer.register({ kind: 'prefix', path: '/api/maoying', handler: async (req,
 
 状态徽章色（全局统一）：pending 灰 / writing 蓝 / review 橙 / accepted 绿；phase 七态沿用七色 pill。文案全中文、禁 emoji 图标（用 ui-primitives 图标或纯 CSS）。
 
-## 4.1 后续迭代记录（0.1.10 – 0.1.13）
+## 4.1 后续迭代记录（0.1.10 – 0.1.14）
 
 - **MaskPortal**：抽屉/弹层统一 portal 到 `document.body`——面板容器挂在宿主会话中栏，中栏 transform/overflow 会把 `position: fixed` 劫持成相对自身并连同裁剪（桌面端「点了没反应」实测病灶）；无 createPortal 的老宿主退回原地渲染。
 - **顶栏版本区**：当前版本号常驻；`update-check` 路由（模仿 dsh-paoding：npm registry → npmmirror → GitHub 三级源，1h 缓存 + 7 天 stale-if-error，全败静默）发现新版时亮「有新版 ↗」徽章。
 - **系统设置**：齿轮弹窗，字号六档（100/110/120/130/140/150%）——面板根与 portal 节点读同一 `--myt-zoom` 变量整体 zoom，localStorage 记忆。
-- **界面语言**：系统设置可选中文/English——全部 UI 文案走 `I18N` 词典（zh/en 各 209 条，`tt`/`tf` 取词 + `{x}` 插值，zh 值与历史硬编码逐字一致保证中文界面零回归），切换立即生效整树重渲并 localStorage 记忆；语言自称（中文/日本語）与侧栏入口品牌名不翻译。
+- **界面语言**：系统设置可选中文/English——全部 UI 文案走 `I18N` 词典（zh/en 各 211 条，`tt`/`tf` 取词 + `{x}` 插值，zh 值与历史硬编码逐字一致保证中文界面零回归），切换立即生效整树重渲并 localStorage 记忆；语言自称（中文/日本語）与侧栏入口品牌名不翻译。
 - **Markdown 渲染**：零依赖渲染器（先整体转义再变换），章纲对照与世界观/科学设定描述不再裸显 md 源码；正文手稿仍走 pre。
 - **章节整页阅读**：替代右侧抽屉（侧边栏遮挡问题），返回按钮 + 章纲对照 + 五维 + 状态流转原位保留；阅读态隐藏 tab 条。
 - **小说设置 tab**（第 9 个）：project.yml 平键表单化编辑，`POST project-save` → `mutateProject` 逐键改写保行尾注释、缺键按模板补齐、phase/mode 越枚举与空书名 422。
 - **字号六档改百分比**（0.1.13）：档位从中文名（小/标准/大…）改为 100/110/120/130/140/150% 直读，旧 localStorage 档位值回落 100%。
+- **人工改动保护 + 静态体检黄条**（0.1.14）：快照顶层新增 `project_hash`（project.yml 原文 sha256，读不到为 null）——小说设置保存回传 `base_hash`，表单载入后 project.yml 被作者手改或 agent（如 mutatePhase 推进 phase）动过时 `project-save` 409 拒写并报「外部修改冲突」，客户端重拉快照把表单放回磁盘真值，不再静默覆盖同名键丢人工改动；概览新增「静态体检」黄条（GET `check`，与 CLI check 同源的 checkProject，透出快照归一掩盖的越枚举等问题，含 error 级时整条转错误色）。路由 11 → 12 条；I18N zh/en 各 209 → 211 条（check.title / check.fullHint）。
+- **面板内一键升级**（0.1.14）：`POST self-update`（lib/self-update.mjs，依赖全部可注入）——顶栏新版徽章旁加「一键升级」按钮，安装形态（`<dshHome>/profiles/<profile>/node_modules/dsh-maoying` 真实目录，symlink/dev 检出一票否决）与 pnpm 可执行性（PATH → homebrew/pnpm 官方安装位候选）双闸通过后跑 `pnpm --dir <profileDir> add dsh-maoying@latest`（180s 超时、无 shell、模块级 in-flight 去重），成功后失效版本检测缓存并提示「已安装 {to}，重启 DeepSeek 后生效」——**装完只换磁盘包，重启才生效，UI 文案照实说**；安装中按钮禁用（前端该请求超时放宽到 200s），「已安装，待重启」后徽章收起。路由 12 → 13 条；I18N zh/en 各 211 → 219 条（header.upgrade* / toast.selfUpdate.*）。
 
 ## 5. 验收基线
 

package/index.mjs

@@ -55,6 +55,7 @@ import { closeSync, copyFileSync, existsSync, mkdirSync, openSync, readdirSync,
 import { createHash } from 'node:crypto'
 import { pathToFileURL } from 'node:url'
 import { getVersionInfo } from './lib/version.mjs'
+import { selfUpdate } from './lib/self-update.mjs'
 import { readFile } from 'node:fs/promises'
 import { createRequire } from 'node:module'
 import os from 'node:os'
@@ -72,6 +73,8 @@ import {
   rebuildIndex,
   resolveNovelRoot,
 } from './lib/panel-core.mjs'
+// 静态体检（check 路由）与 CLI check 同源：直接复用 novel-parse 的检查器。
+import { checkProject } from './lib/novel-parse.mjs'
 import { loadYamlLib, resolveDshHome } from './lib/yaml-loader.mjs'
 
 // loadYamlLib / resolveDshHome 已迁至 lib/yaml-loader.mjs（创作台业务层与
@@ -937,7 +940,7 @@ export async function registerPrefixRouteWithRetry(webServer, route, { attempts
 }
 
 /**
- * 注册创作台全部路由（docs/creator-panel.md §2 的 11 条）。返回宿主 disposer；
+ * 注册创作台全部路由（docs/creator-panel.md §2 的 13 条）。返回宿主 disposer；
  * webServer 缺席（非 web 部署）时抛错，由 apply 侧统一降级为 warn。
  */
 export async function registerCreatorRoutes(ctx) {
@@ -990,6 +993,23 @@ export async function registerCreatorRoutes(ctx) {
           return
         }
 
+        if (route === 'self-update' && req.method === 'POST') {
+          // 面板内一键升级：形态/pnpm 检查 + `pnpm --dir <profileDir> add
+          // dsh-maoying@latest`（细节与安全边界见 lib/self-update.mjs）。可
+          // 预期的失败（dev-link / unsupported-layout / pnpm-missing / 超时 /
+          // pnpm 非零退出）统一 HTTP 200 + ok:false，kind 给客户端分流、
+          // message 经 sanitizeMessage 脱敏后透出；成功也带 restartRequired:
+          // true——装完的只是磁盘上的新包，运行中的进程仍是旧代码，必须重启
+          // DeepSeek 才生效，客户端文案必须照实转述。
+          const r = await selfUpdate({ logger: ctx.logger })
+          if (r.ok) {
+            json(res, 200, { ok: true, from: r.from ?? null, to: r.to ?? null, restartRequired: true })
+          } else {
+            json(res, 200, { ok: false, kind: r.kind, error: sanitizeMessage(r.message ?? r.kind) })
+          }
+          return
+        }
+
         if (route === 'host-debug' && req.method === 'GET') {
           // 现场诊断：宿主版本五级探针轨迹 + 形状判定。与 client.css 同级信任
           // 围栏（loopback + 可信 Host 才放行），只暴露版本与路径类信息。
@@ -1057,6 +1077,17 @@ export async function registerCreatorRoutes(ctx) {
           return
         }
 
+        if (route === 'check' && req.method === 'GET') {
+          // 静态体检：checkProject 读章节 frontmatter 原文——快照会把越枚举
+          // status 归一成 pending（人工改坏在面板里看不出来），这里原样透出
+          // 问题清单，概览「静态体检」黄条取数。checkProject 自带的 ok 是
+          // 「无 error」语义、summary 是 CLI 退出码原料，都不进面板契约
+          // （§2 出参就是 { ok, problems }），客户端自己按 level 计数。
+          const novelDir = resolveNovelRoot(url.searchParams.get('path'), ctx.workspaceRegistry)
+          json(res, 200, { ok: true, problems: checkProject(novelDir).problems })
+          return
+        }
+
         if (route === 'chapter' && req.method === 'GET') {
           // 章节正文全文（抽屉用）：file 只认 chapters/ 下纯文件名；响应组装
           // 直传 readChapter 结果（五期起含对应章纲 outline 字段，无章纲为
@@ -1090,7 +1121,9 @@ export async function registerCreatorRoutes(ctx) {
         if (route === 'project-save' && req.method === 'POST') {
           const body = await readBody(req, res)
           const novelDir = resolveNovelRoot(body.path, ctx.workspaceRegistry)
-          json(res, 200, mutateProject(novelDir, body.values))
+          // base_hash = 面板表单载入时的 project.yml 指纹：外部改过 → 409 拒写
+          // （人工改动保护）；旧客户端不带该字段 → undefined，跳过检查。
+          json(res, 200, mutateProject(novelDir, body.values, { baseHash: body.base_hash }))
           return
         }
 

package/lib/base.css

@@ -294,6 +294,13 @@ html[data-dsh-maoying-active]:not([data-dsh-mnemon-active]):not([data-dsh-taskbo
 .myt-stripIcon { display: inline-flex; flex: none; }
 .myt-stripText { min-width: 0; overflow-wrap: anywhere; }
 .myt-stripWarn { border-color: color-mix(in srgb, var(--dsw-alias-state-warn-primary) 40%, transparent); background: color-mix(in srgb, var(--dsw-alias-state-warn-primary) 10%, transparent); color: var(--dsw-alias-state-warn-primary);}
+/* 静态体检黄条的错误强调（叠加在 myt-stripWarn 上）：含 error 级问题时整条
+   转错误色——纯警告（0 错误）保持黄色不动，一眼分清「有错」和「仅提醒」。 */
+.myt-stripCheckErr {
+  border-color: color-mix(in srgb, var(--dsw-alias-state-error-primary) 40%, transparent);
+  background: color-mix(in srgb, var(--dsw-alias-state-error-primary) 10%, transparent);
+  color: var(--dsw-alias-state-error-primary);
+}
 .myt-stripError {
   border-color: color-mix(in srgb, var(--dsw-alias-state-error-primary) 40%, transparent);
   background: color-mix(in srgb, var(--dsw-alias-state-error-primary) 10%, transparent);
@@ -705,6 +712,24 @@ html[data-dsh-maoying-active]:not([data-dsh-mnemon-active]):not([data-dsh-taskbo
 }
 .myt-verBadge:hover { background: color-mix(in srgb, var(--dsw-alias-state-business-primary) 22%, transparent); }
 
+/* 一键升级按钮：与版本徽章同形（描边胶囊），装完/安装中禁用降透明度 */
+.myt-verUpgrade {
+  margin-left: 6px;
+  padding: 2px 10px;
+  border: 1px solid color-mix(in srgb, var(--dsw-alias-state-business-primary) 45%, transparent);
+  border-radius: 999px;
+  background: transparent;
+  color: var(--dsw-alias-state-business-primary);
+  font-size: 11px;
+  line-height: 16px;
+  font-weight: 500;
+  vertical-align: middle;
+  white-space: nowrap;
+  cursor: pointer;
+}
+.myt-verUpgrade:hover:not(:disabled) { background: color-mix(in srgb, var(--dsw-alias-state-business-primary) 12%, transparent); }
+.myt-verUpgrade:disabled { opacity: 0.6; cursor: default; }
+
 /* ── 版本号 + 系统设置（字号五档，面板整体 zoom）────────────────────────── */
 .myt-verTag {
   display: inline-block;

package/lib/client.js

@@ -53,13 +53,19 @@ window.__ModuleLoader__.load({
     var CSS_KEY = "maoying-creator/base";
     var WS_STORAGE_KEY = "maoying.workspace";
     var API_TIMEOUT_MS = 60000;
+    // 一键升级单独放宽：服务端 pnpm add 超时上限 180s，统一 60s 会先掐断，
+    // 故 self-update 请求走 200s（留 20s 余量），其余请求仍用 API_TIMEOUT_MS。
+    var SELF_UPDATE_TIMEOUT_MS = 200000;
 
     var STATUS_FLOW = ["pending", "writing", "review", "accepted"];
     var FS_ORDER = ["planted", "progressing", "resolved", "abandoned"];
     var FS_FLOW = { planted: "progressing", progressing: "resolved" };
     var PHASES = ["idea", "setting", "outline", "writing", "review", "consistency", "export"];
-    // snake→camel 键表：clue.* 词典键用小驼峰，数据里的 kind 是 snake_case。
-    var CLUE_KIND_KEYS = { clue: "clue", red_herring: "redHerring", inference: "inference", question: "question" };
+    // clue.* 词典键是小驼峰，数据里的 kind 按契约（templates/novel/README.md、
+    // docs/spec.md）是 clue|red-herring|deduction|question——此前键表误按
+    // snake_case + inference 写，红鲱鱼/推理两组永远查不中、只能裸显英文原值。
+    // 尾两个旧键是历史手写数据的容错别名，契约值优先。
+    var CLUE_KIND_KEYS = { clue: "clue", "red-herring": "redHerring", deduction: "inference", question: "question", red_herring: "redHerring", inference: "inference" };
     var TABS = [
       ["overview", "tabs.overview"], ["chapters", "tabs.chapters"], ["characters", "tabs.characters"],
       ["foreshadows", "tabs.foreshadows"], ["relations", "tabs.relations"], ["timeline", "tabs.timeline"],
@@ -156,7 +162,9 @@ window.__ModuleLoader__.load({
 
     // ── 服务端 API 助手（同源 /api/maoying/*，非 2xx 抛错）─────────────────
     // 错误统一 toast（读路由调用方另留卡内错误态）；总超时防按钮永久转圈。
-    function maoyingApi(path, body) {
+    function maoyingApi(path, body, timeoutMs) {
+      // timeoutMs 缺省用统一 60s；一键升级单独放宽到 200s（见常量处注释）。
+      var limit = typeof timeoutMs === "number" && timeoutMs > 0 ? timeoutMs : API_TIMEOUT_MS;
       var opts = body === undefined ? {} : {
         method: "POST",
         headers: { "content-type": "application/json" },
@@ -166,19 +174,25 @@ window.__ModuleLoader__.load({
       var timer = null;
       if (ctrl) {
         opts.signal = ctrl.signal;
-        timer = setTimeout(function () { ctrl.abort(); }, API_TIMEOUT_MS);
+        timer = setTimeout(function () { ctrl.abort(); }, limit);
       }
       return fetch(API_BASE + path, opts).then(function (r) {
         // 先取全文再 JSON.parse：代理错误页 / 空体不再抛 SyntaxError。
         return r.text().then(function (raw) {
           var d = null;
           try { d = raw ? JSON.parse(raw) : null; } catch (err) { d = null; }
-          if (!r.ok) throw new Error((d && d.error) || ("HTTP " + r.status));
+          if (!r.ok) {
+            // 错误对象带状态码：调用方按码分流（如设置保存只在 409 外部改动
+            // 冲突时重置表单，其余失败保留用户正在编辑的内容）。
+            var e = new Error((d && d.error) || ("HTTP " + r.status));
+            e.status = r.status;
+            throw e;
+          }
           if (!d) throw new Error(tf("api.notJson", { code: r.status }));
           return d;
         });
       }).catch(function (err) {
-        if (ctrl && err && err.name === "AbortError") throw new Error(tf("api.timeout", { s: API_TIMEOUT_MS / 1000 }));
+        if (ctrl && err && err.name === "AbortError") throw new Error(tf("api.timeout", { s: Math.round(limit / 1000) }));
         throw err;
       }).finally(function () {
         if (timer !== null) clearTimeout(timer);
@@ -601,6 +615,35 @@ window.__ModuleLoader__.load({
           if (d && d.current) setVer(d); // 常态也显示当前版本号；有新版再亮徽章
         }).catch(function () {});
       }, []);
+      // 一键升级状态机：""（可点）→ "installing"（安装中，按钮禁用）→
+      // "installed"（已装完待重启，按钮永久禁用、新版徽章收起）。可预期失败
+      // （dev-link / pnpm-missing / pnpm 出错）回落 "" 允许重试。
+      var _up = useState(""), upState = _up[0], setUpState = _up[1];
+      function runSelfUpdate() {
+        if (upState !== "") return;
+        setUpState("installing");
+        // 不走 apiPost：成功提示要带新版本号、失败按 kind 分流文案，且超时
+        // 单独放宽（服务端 pnpm 最长 180s，统一 60s 会先掐断，见常量处注释）。
+        maoyingApi("self-update", {}, SELF_UPDATE_TIMEOUT_MS).then(function (d) {
+          if (d && d.ok) {
+            setUpState("installed");
+            // 硬约束照实说：装完只是磁盘换新，运行中的进程仍是旧代码。
+            toast.ok(tf("toast.selfUpdate.ok", { ver: (d && d.to) || "?" }));
+          } else if (d && d.kind === "dev-link") {
+            setUpState("");
+            toast.warn(tt("toast.selfUpdate.devLink"));
+          } else if (d && d.kind === "pnpm-missing") {
+            setUpState("");
+            toast.warn(tt("toast.selfUpdate.pnpmMissing"));
+          } else {
+            setUpState("");
+            toast.err(tf("toast.prefix", { msg: (d && d.error) || tt("common.unknownErr") }));
+          }
+        }).catch(function (err) {
+          setUpState("");
+          toast.err(tf("toast.prefix", { msg: err.message }));
+        });
+      }
       useEffect(function () { loadWorkspaces(); }, [loadWorkspaces]);
       useEffect(function () { loadState(effectiveWs); }, [effectiveWs, loadState]);
       // 校正后的选择回写记忆（首次打开 / 记忆失效时自动落位）。
@@ -659,8 +702,22 @@ window.__ModuleLoader__.load({
             h("h1", { className: "myt-title" }, "毛颖创作台",
               ver && ver.current ? h("span", { className: "myt-verTag", title: tt("header.curVerTitle") }, ver.current) : null,
               ver && ver.updateAvailable
-                ? h("a", { className: "myt-verBadge", href: ver.releaseUrl || "#", target: "_blank", rel: "noreferrer", title: tf("header.upgradeTip", { cur: ver.current }) },
-                    tf("header.newVersion", { ver: ver.latest }))
+                ? [
+                    // 徽章（跳发布页）+「一键升级」按钮双元素；装完（installed）
+                    // 徽章收起——磁盘已是新版，别再引导去发布页——按钮变
+                    // 「已安装，待重启」保持禁用，重启 DeepSeek 换新进程后才消失。
+                    upState !== "installed"
+                      ? h("a", { key: "b", className: "myt-verBadge", href: ver.releaseUrl || "#", target: "_blank", rel: "noreferrer", title: tf("header.upgradeTip", { cur: ver.current }) },
+                          tf("header.newVersion", { ver: ver.latest }))
+                      : null,
+                    h("button", {
+                      key: "u", type: "button", className: "myt-verUpgrade",
+                      disabled: upState !== "",
+                      title: upState === "installed" ? tt("header.upgradedTitle") : tt("header.upgradeTitle"),
+                      onClick: runSelfUpdate,
+                    },
+                      upState === "installing" ? tt("header.upgrading") : upState === "installed" ? tt("header.upgraded") : tt("header.upgradeBtn")),
+                  ]
                 : null),
             h("p", { className: "myt-subtitle" }, tt("header.subtitle"))),
           h("div", { className: "myt-headActions" },
@@ -700,17 +757,50 @@ window.__ModuleLoader__.load({
           warnings.map(function (w, i) { return h("div", { key: i }, "· " + String(w)); })));
     }
 
+    // 静态体检黄条：checkProject 的原始问题清单（快照侧会把越枚举 status
+    // 归一成 pending，人工改坏在快照里看不出来，这里照 CLI check 同源透出）。
+    // 含 error 级问题时叠加强调 class（纯 CSS，见 base.css）。
+    function CheckStrip(problems) {
+      var errs = 0;
+      for (var i = 0; i < problems.length; i++) { if (problems[i] && problems[i].level === "error") errs++; }
+      return h("div", { className: "myt-strip myt-stripWarn" + (errs > 0 ? " myt-stripCheckErr" : "") },
+        h("span", { className: "myt-stripIcon" }, ic("IconWarningOutlineRegular", 14)),
+        h("span", { className: "myt-stripText" },
+          h("div", null, h("strong", null, tf("check.title", { n: fmtNum(problems.length), err: fmtNum(errs), warn: fmtNum(problems.length - errs) }))),
+          problems.slice(0, 8).map(function (p, i) {
+            return h("div", { key: i }, "· [" + String((p && p.level) || "") + "] " + String((p && p.file) || "") + ": " + String((p && p.message) || ""));
+          }),
+          h("div", null, tt("check.fullHint"))));
+    }
+
     // ── 概览 tab：project 卡 + 统计卡 + 最近更新 ───────────────────────────
     function OverviewTab(props) {
       var snap = props.snap;
       var reload = props.reload;
       var gotoTab = props.gotoTab;
+      var wsPath = props.wsPath;
       var project = snap.project || {};
       var totals = snap.totals || {};
       var byStatus = totals.byStatus || {};
       var _b = useState(false), phaseBusy = _b[0], setPhaseBusy = _b[1];
       var phaseIdx = PHASES.indexOf(project.phase);
       var nextPhase = phaseIdx !== -1 && phaseIdx < PHASES.length - 1 ? PHASES[phaseIdx + 1] : null;
+      // 静态体检黄条：仅 found 时拉 check 路由（未初始化没有可查的东西）。
+      // 工作区切换与每次 reload 都换新 snap → effect 重跑即重查；请求序号防
+      // 过期响应（快速切工作区时在途旧响应不得落进新工作区的黄条）。
+      var _ck = useState(null), checkProblems = _ck[0], setCheckProblems = _ck[1];
+      var checkSeqRef = useRef(0);
+      useEffect(function () {
+        if (!snap || !snap.found || !wsPath) { setCheckProblems(null); return; }
+        var seq = ++checkSeqRef.current; // 先自增再发请求；早退分支也作废在途旧响应
+        apiGet("check", { path: wsPath }).then(function (d) {
+          if (seq !== checkSeqRef.current) return; // 过期响应：已有更新的请求在途，丢弃
+          setCheckProblems(d && d.ok && Array.isArray(d.problems) ? d.problems : []);
+        }).catch(function () {
+          if (seq !== checkSeqRef.current) return;
+          setCheckProblems(null); // 拉取失败不显示黄条（toast 已由 apiGet 统一提示）
+        });
+      }, [snap, wsPath]);
       function advancePhase() {
         if (!nextPhase || phaseBusy) return;
         setPhaseBusy(true);
@@ -718,6 +808,7 @@ window.__ModuleLoader__.load({
       }
       var recent = (snap.chapters || []).slice().sort(function (a, b) { return (b.num || 0) - (a.num || 0); }).slice(0, 5);
       return h("div", { className: "myt-stack" },
+        checkProblems && checkProblems.length ? CheckStrip(checkProblems) : null,
         h("div", { className: "myt-card myt-hero" },
           h("div", { className: "myt-heroMeta" },
             project.author ? h("span", { className: "myt-muted" }, tf("overview.author", { name: project.author })) : null,
@@ -876,6 +967,11 @@ window.__ModuleLoader__.load({
       zh: {
         "shell.title": "毛颖创作台", "header.subtitle": "网文项目可视化与状态流转 · 只读正文，写状态",
         "header.curVerTitle": "当前版本", "header.upgradeTip": "当前 {cur}，点击打开新版发布页", "header.newVersion": "有新版 {ver} ↗",
+        "header.upgradeBtn": "一键升级", "header.upgrading": "安装中…", "header.upgraded": "已安装，待重启",
+        "header.upgradeTitle": "用 pnpm 安装 npm 最新版（最长约 3 分钟），装完需重启 DeepSeek 生效",
+        "header.upgradedTitle": "已安装新版，重启 DeepSeek 后生效",
+        "toast.selfUpdate.ok": "已安装 {ver}，重启 DeepSeek 后生效",
+        "toast.selfUpdate.devLink": "开发目录安装，请 git pull 更新", "toast.selfUpdate.pnpmMissing": "未找到 pnpm，请手动安装",
         "header.workspace": "工作区", "header.wsAria": "选择工作区", "header.noNovel": "（无 novel）", "header.untitled": "未命名",
         "header.settings": "系统设置", "header.refresh": "重新拉取", "header.closeAria": "关闭创作台", "header.closeTitle": "关闭",
         "tabs.aria": "创作台分区",
@@ -906,6 +1002,7 @@ window.__ModuleLoader__.load({
         "clue.clue": "线索", "clue.redHerring": "红鲱鱼", "clue.inference": "推理", "clue.question": "疑问",
         "sci.known": "已确证", "sci.extrapolation": "推演", "sci.hypothesis": "假说", "world.unlabeled": "未标级",
         "warnings.title": "部分文件解析异常（已跳过）：",
+        "check.title": "静态体检：{n} 项（错误 {err} / 警告 {warn}）", "check.fullHint": "全量结果请在终端运行 maoying check 查看",
         "index.title": "索引板（clue-board / memories）", "index.rebuild": "重建索引", "index.rebuilding": "重建中…",
         "index.rebuildTip": "按 CLI index 同一逻辑重建 index.yml", "index.clueBoard": "线索板", "index.clueEmpty": "clue-board.yml 还没有条目",
         "index.memBoard": "记忆板", "index.memEmpty": "memories.yml 还没有条目", "index.promise": "承诺线",
@@ -949,6 +1046,11 @@ window.__ModuleLoader__.load({
       en: {
         "shell.title": "Maoying Studio", "header.subtitle": "Web-novel project dashboard & status flow · read-only text, writable status",
         "header.curVerTitle": "Current version", "header.upgradeTip": "Current {cur} — click to open the release page", "header.newVersion": "New version {ver} ↗",
+        "header.upgradeBtn": "Upgrade now", "header.upgrading": "Installing…", "header.upgraded": "Installed — restart pending",
+        "header.upgradeTitle": "Install the latest npm release with pnpm (up to ~3 min); takes effect after restarting DeepSeek",
+        "header.upgradedTitle": "New version installed — takes effect after restarting DeepSeek",
+        "toast.selfUpdate.ok": "Installed {ver} — takes effect after restarting DeepSeek",
+        "toast.selfUpdate.devLink": "Installed from a dev directory — update with git pull", "toast.selfUpdate.pnpmMissing": "pnpm not found — install it manually",
         "header.workspace": "Workspace", "header.wsAria": "Select workspace", "header.noNovel": "(no novel)", "header.untitled": "Untitled",
         "header.settings": "Settings", "header.refresh": "Refresh", "header.closeAria": "Close Maoying Studio", "header.closeTitle": "Close",
         "tabs.aria": "Studio sections",
@@ -979,6 +1081,7 @@ window.__ModuleLoader__.load({
         "clue.clue": "Clue", "clue.redHerring": "Red herring", "clue.inference": "Inference", "clue.question": "Question",
         "sci.known": "Confirmed", "sci.extrapolation": "Extrapolation", "sci.hypothesis": "Hypothesis", "world.unlabeled": "Unrated",
         "warnings.title": "Some files failed to parse (skipped):",
+        "check.title": "Static check: {n} issue(s) ({err} errors / {warn} warnings)", "check.fullHint": "Run maoying check in a terminal for the full report",
         "index.title": "Index Board (clue-board / memories)", "index.rebuild": "Rebuild index", "index.rebuilding": "Rebuilding…",
         "index.rebuildTip": "Rebuild index.yml with the same logic as the CLI index command", "index.clueBoard": "Clue board", "index.clueEmpty": "No entries in clue-board.yml yet",
         "index.memBoard": "Memory board", "index.memEmpty": "No entries in memories.yml yet", "index.promise": "Promise thread",
@@ -1151,20 +1254,51 @@ window.__ModuleLoader__.load({
     // ── 小说设置 tab：可视化 project.yml 平键并保存。mode/phase 走枚举
     // 下拉，自由文本走输入框；保存走 project-save 路由（服务端校验 + 保
     // 注释改写），成功后重拉快照让概览同步。 ──
+    // 表单初值（与磁盘真值同源）：首次载入与 409 重置共用同一形状。
+    function settingsFormOf(project) {
+      project = project || {};
+      return {
+        title: project.title || "", author: project.author || "", genre: project.genre || "",
+        length: project.length || "", language: project.language || "zh",
+        phase: PHASES.indexOf(project.phase) !== -1 ? project.phase : "idea",
+        mode: project.mode || "ai-draft",
+        description: project.description || "",
+      };
+    }
+    // 快照 root 与工作区 path 同源但形态可能有差（尾斜杠等），比对前归一。
+    function normRoot(s) { return String(s || "").replace(/[\\/]+$/, ""); }
     function SettingsTab(props) {
       var snap = props.snap;
       var wsPath = props.wsPath;
       var reload = props.reload;
       var project = snap.project || {};
-      var _f = useState(function () {
-        return {
-          title: project.title || "", author: project.author || "", genre: project.genre || "",
-          length: project.length || "", language: project.language || "zh",
-          phase: PHASES.indexOf(project.phase) !== -1 ? project.phase : "idea",
-          mode: project.mode || "ai-draft",
-          description: project.description || "",
-        };
-      }), form = _f[0], setForm = _f[1];
+      var _f = useState(function () { return settingsFormOf(project); }), form = _f[0], setForm = _f[1];
+      // 保存基线：表单载入时的 project.yml 指纹（snap.project_hash）。服务端
+      // 拿它检测表单载入后的外部改动（作者手改 / agent 推进 phase），命中即
+      // 409 拒写——没有它，保存会静默覆盖同名键、丢掉人工改动。
+      var baseHashRef = useRef(snap && typeof snap.project_hash === "string" ? snap.project_hash : null);
+      // 409 后的一次性重置标记：reload 带回新快照时把表单与基线放回磁盘真值。
+      // 只在保存失败路径置位——顶栏刷新等其他 reload 不碰正在编辑的表单。
+      var pendingResetRef = useRef(false);
+      useEffect(function () {
+        var hash = snap && typeof snap.project_hash === "string" ? snap.project_hash : null;
+        if (pendingResetRef.current) {
+          pendingResetRef.current = false;
+          setForm(settingsFormOf(snap && snap.project));
+          baseHashRef.current = hash;
+          return;
+        }
+        // 空闲跟随：快照确属当前工作区（root 对得上，跨工作区切换的在途旧
+        // 快照不认）且表单未被用户动过（与磁盘逐键同值）时，把基线对齐本快照
+        // ——本组件不随工作区切换重挂，基线若还攥着旧工作区的 hash，保存必被
+        // 自家 409 拦住（假冲突）。用户已编辑则不打扰，外部改动由保存 409 兜底。
+        if (!snap || !snap.found || normRoot(snap.root) !== normRoot(wsPath)) return;
+        var disk = settingsFormOf(snap.project);
+        for (var k in disk) {
+          if (String(form[k]) !== String(disk[k])) return;
+        }
+        baseHashRef.current = hash;
+      }, [snap, wsPath]);
       var _b = useState(false), busy = _b[0], setBusy = _b[1];
       var _e = useState(""), saveErr = _e[0], setSaveErr = _e[1];
       function set(k, v) { setForm(Object.assign({}, form, (function () { var o = {}; o[k] = v; return o; })())); }
@@ -1174,10 +1308,20 @@ window.__ModuleLoader__.load({
         setBusy(true); setSaveErr("");
         // 成败提示统一走 apiPost 的 toast 通道（这里不再另弹，避免双 toast）；
         // 卡内 saveErr 只承担表单旁的错误态。
-        apiPost("project-save", { path: wsPath, values: form }).then(function () {
+        apiPost("project-save", { path: wsPath, values: form, base_hash: baseHashRef.current }).then(function (res) {
+          // 写后指纹即下一轮基线：不等 reload 快照就先接住——连续两次保存时
+          // 第二次若还回传载入时的旧指纹，会被自家 409 拦住（假冲突）。
+          if (res && typeof res.project_hash === "string") baseHashRef.current = res.project_hash;
           return reload();
         }).catch(function (err) {
           setSaveErr(err.message);
+          // 409 = project.yml 在表单载入后被外部改过：重拉快照并一次性把表单
+          // 放回磁盘真值，别让用户在过期基线上继续盲改。其他失败（网络抖动
+          // 等）不动表单，保留正在编辑的内容。
+          if (err && err.status === 409) {
+            pendingResetRef.current = true;
+            reload();
+          }
         }).finally(function () { setBusy(false); });
       }
       function field(label, key, placeholder, textarea) {

package/lib/panel-core.mjs

@@ -11,6 +11,8 @@
  *                                  （五期起含 outlines 章纲清单）
  *     readChapter(novelDir, file)  章节正文全文（抽屉用；五期起带对应章纲
  *                                  outline 字段）
+ *     projectFileHash(novelDir)    project.yml 原文 sha256 hex（快照
+ *                                  project_hash / 保存旧版检测共用基线）
  *
  *   写入面（全部「读原文 → 行级字符串手术 → 写后校验替换计数 === 1」；
  *   计数不符或目标行缺失一律 409 拒写不落盘，把对 git diff 的扰动压到最小）
@@ -28,6 +30,7 @@
  * 绝不让它炸掉整个快照。
  */
 
+import { createHash } from 'node:crypto'
 import { existsSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 
@@ -397,6 +400,27 @@ function readProject(novelDir, yamlLib, warnings) {
   }
 }
 
+/** sha256 hex（小写）：文本 → 指纹。 */
+function sha256Hex(text) {
+  return createHash('sha256').update(text, 'utf8').digest('hex')
+}
+
+/**
+ * project.yml 原文指纹（sha256 hex）：面板「人工改动保护」的基线。快照带出
+ * project_hash，保存时回传 base_hash 比对——表单载入后文件被外部（作者手改
+ * / agent 推进 phase）动过就能查觉，拒绝静默覆盖。读不到/读失败返回 null
+ * （与「无 project.yml」同口径，不炸快照）。
+ */
+export function projectFileHash(novelDir) {
+  let text = null
+  try {
+    text = readFileSync(path.join(path.resolve(novelDir), 'project.yml'), 'utf8')
+  } catch {
+    return null
+  }
+  return sha256Hex(text)
+}
+
 /**
  * 全量快照（docs/creator-panel.md §3，字段名冻结）。novelDir 为工作区的
  * novel 目录；project.yml 不在 = 未初始化（found: false，其余字段缺省）。
@@ -409,10 +433,13 @@ export function parseStateSnapshot(novelDir, options = {}) {
   const warnings = []
 
   if (!existsSync(path.join(dir, 'project.yml'))) {
-    return { ok: true, root, novelDir: dir, found: false, warnings }
+    return { ok: true, root, novelDir: dir, found: false, project_hash: null, warnings }
   }
 
   const project = readProject(dir, yamlLib, warnings)
+  // 人工改动保护基线：快照顶层带 project.yml 原文指纹，客户端保存时原样回传
+  // （project-save 的 base_hash）；读不到为 null（不影响快照其余字段）。
+  const projectHash = projectFileHash(dir)
 
   const chaptersRaw = (() => {
     try {
@@ -451,6 +478,15 @@ export function parseStateSnapshot(novelDir, options = {}) {
     markers: strArray(meta.markers),
   }))
 
+  // 关系端点归一：契约规定 relations.yml 的 a/b 是角色 slug（characters/ 目录名），
+  // 而关系图客户端按角色 name（卡 frontmatter name，缺省回落 slug）找节点——不出
+  // 快照侧归一，带中文名的角色卡必然端点对不上、一条边都画不出。对得上角色卡的
+  // 端点改写成 name；对不上的（已死亡/未建档角色，或历史条目直接写了 name）原样
+  // 保留。novel-parse 侧（protagonistCards、relations 校验）仍按 slug 契约，不动。
+  const nameBySlug = Object.fromEntries(
+    characters.map((c) => [String(c.file ?? '').replace(/\.md$/i, ''), c.name])
+  )
+
   const relations = collectArrayYml(dir, 'relations.yml', yamlLib, warnings).map((r) => ({
     a: strOrNull(r.a),
     b: strOrNull(r.b),
@@ -459,7 +495,7 @@ export function parseStateSnapshot(novelDir, options = {}) {
     intensity: intOrNull(r.intensity),
     started: strOrNull(r.started),
     ended: strOrNull(r.ended),
-  }))
+  })).map((r) => ({ ...r, a: nameBySlug[r.a] ?? r.a, b: nameBySlug[r.b] ?? r.b }))
 
   const foreshadows = collectArrayYml(dir, 'foreshadows.yml', yamlLib, warnings).map((f) => ({
     id: strOrNull(f.id),
@@ -531,6 +567,7 @@ export function parseStateSnapshot(novelDir, options = {}) {
     root,
     novelDir: dir,
     found: true,
+    project_hash: projectHash,
     project,
     chapters,
     characters,
@@ -683,8 +720,14 @@ const PROJECT_MODE_KEYS = ['ai-draft', 'co-write', 'author-draft']
  * 「单行值替换、行尾注释原样保留」（与 mutatePhase 同一保注释刀法）；文件里
  * 没有的键按模板顺序补在末尾（带模板注释）。校验：phase/mode 越枚举 422、
  * title 空白 422。值统一经 yamlScalar 规范成可回读的 YAML 标量。
+ *
+ * 人工改动保护：options.baseHash 是面板表单载入时的 project.yml 原文指纹
+ * （快照 project_hash）。与写入前现读原文不一致 → 表单基线已过期（作者或
+ * agent 在载入后改过文件），409 拒写——静默覆盖会丢人工改动。未传 baseHash
+ * 跳过检查（旧调用方兼容）。返回值带写后新指纹 project_hash，客户端 reload
+ * 前即可拿到下一轮基线。
  */
-export function mutateProject(novelDir, values) {
+export function mutateProject(novelDir, values, options = {}) {
   if (values === null || typeof values !== 'object' || Array.isArray(values)) {
     fail(422, 'values 必须是键值对象')
   }
@@ -701,6 +744,12 @@ export function mutateProject(novelDir, values) {
 
   const target = path.join(novelDir, 'project.yml')
   const text = readTarget(target, 'project.yml')
+  // 旧版检测在读原文之后、落笔之前：指纹不一致就地 409，一个字节都不动。
+  // 客户端指纹归一到小写再比（指纹本身 hex，大小写宽容不构成安全口子）。
+  const baseHash = typeof options.baseHash === 'string' ? options.baseHash.trim().toLowerCase() : ''
+  if (baseHash !== '' && baseHash !== sha256Hex(text)) {
+    fail(409, 'project.yml 已被外部修改，请刷新面板后基于最新内容重改再存')
+  }
   const lines = text.split(/\r?\n/)
   const pending = new Map(Object.entries(next))
   for (let i = 0; i < lines.length; i++) {
@@ -724,8 +773,10 @@ export function mutateProject(novelDir, values) {
       lines.splice(insertAt, 0, ...missing)
     }
   }
-  writeAtomic(target, joinLines(lines, text))
-  return { ok: true }
+  const nextText = joinLines(lines, text)
+  writeAtomic(target, nextText)
+  // 返回写后指纹：客户端下一轮保存的 base_hash 直接取它，不必再等一次快照。
+  return { ok: true, project_hash: sha256Hex(nextText) }
 }
 
 /** YAML 平标量：安全字符裸写，含特殊字符（冒号空格/井号/引号/首尾空格等）

package/lib/self-update.mjs

@@ -0,0 +1,263 @@
+/**
+ * 面板内一键升级 —— 直接跑 pnpm 把本包装到当前 DSH profile（创作台面板用）。
+ *
+ * 背景：desktop 档的真实安装形态是 <dshHome>/profiles/<profile>/node_modules/
+ * dsh-maoying（真实目录，非 symlink），宿主 dsh CLI 拒绝管理 desktop 档，唯一
+ * 可行的升级命令是直接 pnpm：`pnpm --dir <profileDir> add dsh-maoying@latest`。
+ *
+ * 安全边界（缺一不可，全不满足绝不执行安装）：
+ *   1) 安装形态判定——插件包自身目录先 realpathSync 取真路径，真路径 ≠ 常规
+ *      路径即 link/symlink 安装（如 web 档指向 dev repo）→ 拒绝（dev-link，
+ *      请在开发目录 git pull）；真路径不匹配 <dshHome>/profiles/<profile>/
+ *      node_modules/dsh-maoying 结构 → 拒绝（unsupported-layout）。dshHome /
+ *      profile 取 env.DSH_HOME / DSH_PROFILE（~ 前缀手动展开），缺失时回退从
+ *      真路径的 profiles 祖先推导，推导不出同样拒绝。
+ *   2) pnpm 解析——按候选路径逐个 existsSync + accessSync(X_OK)（PATH 各目录
+ *      在前，homebrew / pnpm 官方安装位在后），一个都不可执行 → 拒绝
+ *      （pnpm-missing）。绝不用 shell:true，无注入面。
+ *   3) 超时 180 秒——超时 kill 子进程收敛为 timeout，不挂死面板请求。
+ *
+ * 所有失败路径都不抛错，一律收敛为 { ok: false, kind, message } 结果对象；
+ * 成功返回 { ok: true, kind: 'installed', from, to, restartRequired: true }。
+ * 硬约束：装完后运行中的进程仍是旧代码，必须重启 DeepSeek 才生效——restart-
+ * Required 恒 true，UI 文案必须明说，不得暗示装完即生效。依赖全部可注入
+ * （spawnImpl / realpathImpl / existsImpl / readImpl …），对齐 lib/version.mjs
+ * 的 fetchImpl 模式，方便测试。
+ */
+import { spawn as nodeSpawn } from 'node:child_process'
+import { accessSync, constants as fsConstants, existsSync, realpathSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { invalidateVersionCache } from './version.mjs'
+
+/** 安装超时：pnpm 冷缓存 + 国内网络最坏留足 3 分钟。 */
+export const SELF_UPDATE_TIMEOUT_MS = 180 * 1000
+/** 失败信息里保留的子进程输出尾部字节数（stdout / stderr 各一份）。 */
+const OUTPUT_TAIL_BYTES = 2048
+
+/**
+ * 插件包自身目录（package.json 所在目录）。抽成函数便于测试注入假安装位。
+ */
+function defaultPkgDir() {
+  return path.dirname(fileURLToPath(new URL('../package.json', import.meta.url)))
+}
+
+/**
+ * PATH 里 pnpm 之后的候选兜底（macOS 常见安装位；GUI 进程 PATH 常缺 pnpm，
+ * 宿主进程又不经过 shell，PATH 找不到时按固定路径逐个试）。
+ */
+function extraPnpmCandidates(env) {
+  const home = typeof env.HOME === 'string' && env.HOME.trim() !== '' ? env.HOME.trim() : os.homedir()
+  return [
+    '/opt/homebrew/bin/pnpm',
+    '/usr/local/bin/pnpm',
+    path.join(home, '.local', 'share', 'pnpm', 'pnpm'),
+    path.join(home, 'Library', 'pnpm', 'pnpm'),
+  ]
+}
+
+/** 解析 pnpm 可执行文件：PATH 各目录在前、常见安装位兜底，去重后逐个可执行性检查。 */
+function resolvePnpm(env, { existsImpl, accessImpl }) {
+  const pathEnv = typeof env.PATH === 'string' ? env.PATH : ''
+  const fromPath = pathEnv.split(path.delimiter).filter((d) => d !== '').map((d) => path.join(d, 'pnpm'))
+  const candidates = [...new Set([...fromPath, ...extraPnpmCandidates(env)])]
+  for (const candidate of candidates) {
+    try {
+      if (!existsImpl(candidate)) continue
+      accessImpl(candidate, fsConstants.X_OK)
+      return candidate
+    } catch {
+      /* 存在但不可执行（或探测异常）：换下一个候选 */
+    }
+  }
+  return null
+}
+
+/**
+ * 从真路径的 profiles 祖先推导 { home, profile }：真路径必须形如
+ * <dshHome>/profiles/<profile>/node_modules/dsh-maoying，其余形态返回 null。
+ */
+function deriveLayoutFromPath(realDir) {
+  const pkgName = path.basename(realDir)
+  const nmDir = path.dirname(realDir)
+  if (pkgName !== 'dsh-maoying' || path.basename(nmDir) !== 'node_modules') return null
+  const profile = path.basename(path.dirname(nmDir))
+  const profilesDir = path.dirname(path.dirname(nmDir))
+  if (path.basename(profilesDir) !== 'profiles') return null
+  return { home: path.dirname(profilesDir), profile }
+}
+
+/** env 里的 dsh home（~ 前缀手动展开，环境变量不经过 shell 展开）。 */
+function dshHomeFromEnv(env) {
+  const raw = typeof env.DSH_HOME === 'string' ? env.DSH_HOME.trim() : ''
+  if (raw === '') return null
+  if (raw === '~' || raw.startsWith('~/')) return path.join(os.homedir(), raw.slice(1))
+  return raw
+}
+
+/**
+ * 读安装目录 package.json 的 version；读不到（缺失 / 解析失败 / 字段异常）
+ * 返回 null——from 缺失不拦安装（pnpm 退出码才是成败信号），to 缺失照常
+ * ok:true（version 显示为 null，前端兜底显示）。
+ */
+async function readPkgVersion(pkgJsonPath, readImpl) {
+  try {
+    const raw = await readImpl(pkgJsonPath)
+    const pkg = JSON.parse(raw)
+    return typeof pkg?.version === 'string' && pkg.version !== '' ? pkg.version : null
+  } catch {
+    return null
+  }
+}
+
+/** 组装最小注入面：缺省走真实 Node 实现，测试逐项替换。 */
+function normalizeDeps(opts) {
+  const env = opts.env ?? process.env
+  return {
+    env,
+    spawnImpl: opts.spawnImpl ?? nodeSpawn,
+    pkgDirImpl: opts.pkgDirImpl ?? defaultPkgDir,
+    realpathImpl: opts.realpathImpl ?? ((p) => realpathSync(p)),
+    existsImpl: opts.existsImpl ?? ((p) => existsSync(p)),
+    accessImpl: opts.accessImpl ?? ((p, mode) => accessSync(p, mode)),
+    readImpl:
+      opts.readImpl ??
+      ((p) => readFile(p, 'utf8')),
+    logger: opts.logger ?? console,
+    timeoutMs:
+      typeof opts.timeoutMs === 'number' && opts.timeoutMs > 0 ? opts.timeoutMs : SELF_UPDATE_TIMEOUT_MS,
+  }
+}
+
+/**
+ * selfUpdate 主体（永不 reject；concurrency 去重与兜底 try/catch 在外层）。
+ * @returns {Promise<{ok: boolean, kind: string, from?: string|null, to?: string|null,
+ *           restartRequired?: boolean, message?: string}>}
+ */
+async function runSelfUpdate(opts = {}) {
+  const { spawnImpl, pkgDirImpl, realpathImpl, existsImpl, accessImpl, readImpl, env, logger, timeoutMs } =
+    normalizeDeps(opts)
+
+  // ── a) 安装形态判定 ──────────────────────────────────────────────────────
+  const pkgDir = pkgDirImpl()
+  let realDir
+  try {
+    realDir = path.resolve(realpathImpl(pkgDir))
+  } catch (err) {
+    return { ok: false, kind: 'unsupported-layout', message: `安装目录读取失败: ${err?.message ?? err}` }
+  }
+  if (realDir !== path.resolve(pkgDir)) {
+    return {
+      ok: false,
+      kind: 'dev-link',
+      message: '当前安装指向开发目录（symlink/link 安装），请到开发目录 git pull 更新，这里不代装',
+    }
+  }
+  const derived = deriveLayoutFromPath(realDir)
+  const home = dshHomeFromEnv(env) ?? derived?.home ?? null
+  const profileRaw = typeof env.DSH_PROFILE === 'string' ? env.DSH_PROFILE.trim() : ''
+  const profile = profileRaw !== '' ? profileRaw : derived?.profile ?? null
+  const profileDir = home && profile ? path.join(home, 'profiles', profile) : null
+  if (!derived || !profileDir || realDir !== path.resolve(path.join(profileDir, 'node_modules', 'dsh-maoying'))) {
+    return {
+      ok: false,
+      kind: 'unsupported-layout',
+      message: '当前安装形态不受面板内升级支持（不是 <dshHome>/profiles/<profile>/node_modules/dsh-maoying 目录安装），请用命令行升级',
+    }
+  }
+
+  // ── b) 解析 pnpm ────────────────────────────────────────────────────────
+  const pnpmPath = resolvePnpm(env, { existsImpl, accessImpl })
+  if (!pnpmPath) {
+    return {
+      ok: false,
+      kind: 'pnpm-missing',
+      message: '未找到 pnpm 可执行文件（PATH 与常见安装路径都没有），请先安装 pnpm 后重试',
+    }
+  }
+
+  const pkgJsonPath = path.join(realDir, 'package.json')
+  const from = await readPkgVersion(pkgJsonPath, readImpl)
+
+  // ── c) 执行安装（绝不用 shell:true，无注入面）────────────────────────────
+  const exitInfo = await new Promise((resolve) => {
+    let child
+    try {
+      child = spawnImpl(pnpmPath, ['--dir', profileDir, 'add', 'dsh-maoying@latest'], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+      })
+    } catch (err) {
+      resolve({ failed: true, kind: 'spawn-error', message: `pnpm 启动失败: ${err?.message ?? err}` })
+      return
+    }
+    let out = Buffer.alloc(0)
+    let errBuf = Buffer.alloc(0)
+    const keepTail = (buf, chunk) => Buffer.concat([buf, Buffer.from(chunk)]).subarray(-OUTPUT_TAIL_BYTES)
+    child.stdout?.on?.('data', (chunk) => { out = keepTail(out, chunk) })
+    child.stderr?.on?.('data', (chunk) => { errBuf = keepTail(errBuf, chunk) })
+    // 定时器只在进程仍存活时触发；exit 先到则清掉，不留挂起句柄。
+    const timer = setTimeout(() => {
+      try { child.kill() } catch { /* 已退出：忽略 */ }
+      resolve({
+        failed: true,
+        kind: 'timeout',
+        message: `pnpm 安装超时（${Math.round(timeoutMs / 1000)} 秒）已中止，请检查网络后重试`,
+      })
+    }, timeoutMs)
+    const onExit = (code, signal) => {
+      clearTimeout(timer)
+      if (code === 0) {
+        resolve({ failed: false })
+        return
+      }
+      const tailText = `${out.toString('utf8')}\n${errBuf.toString('utf8')}`.trim()
+      resolve({
+        failed: true,
+        kind: 'pnpm-failed',
+        message: `pnpm add 失败（${signal != null ? `signal ${signal}` : `exit ${code}`}）：${tailText !== '' ? tailText : '无输出'}`,
+      })
+    }
+    child.on?.('exit', onExit)
+    child.on?.('error', (err) => {
+      clearTimeout(timer)
+      resolve({ failed: true, kind: 'spawn-error', message: `pnpm 启动失败: ${err?.message ?? err}` })
+    })
+  })
+  if (exitInfo.failed) {
+    logger?.warn?.(`maoying 创作台: self-update 失败(${exitInfo.kind}): ${exitInfo.message}`)
+    return { ok: false, kind: exitInfo.kind, message: exitInfo.message }
+  }
+
+  // ── d) 成功后重读新版本 + 版本缓存失效 ───────────────────────────────────
+  const to = await readPkgVersion(pkgJsonPath, readImpl)
+  // 装的是磁盘上的新包，进程内 update-check 的 1h 缓存已是旧结论，立刻失效，
+  // 下次打开面板（重启后）按磁盘新版本重算 updateAvailable。
+  invalidateVersionCache()
+  logger?.info?.(`maoying 创作台: self-update 完成 ${from ?? '?'} → ${to ?? '?'}（重启 DeepSeek 后生效）`)
+  return { ok: true, kind: 'installed', from, to, restartRequired: true }
+}
+
+// in-flight 去重：并发的 selfUpdate（连点按钮 / 双面板）复用同一次安装
+// promise，pnpm add 绝不并发跑两份；promise 落定即清空。resetSelfUpdateInflight
+// 仅供测试隔离模块级状态。
+let inflight = null
+
+/** 测试专用：清空模块级 in-flight 状态（生产勿用）。 */
+export function resetSelfUpdateInflight() {
+  inflight = null
+}
+
+/**
+ * 面板一键升级入口（并发去重）。
+ * @returns {Promise<{ok: boolean, kind: string, ...}>} 永不 reject
+ */
+export async function selfUpdate(opts = {}) {
+  if (inflight) return inflight
+  inflight = runSelfUpdate(opts).finally(() => {
+    inflight = null
+  })
+  return inflight
+}

package/lib/version.mjs

@@ -310,6 +310,17 @@ async function detectLatest({ fetchImpl, timeoutMs, nowMs }) {
 // 注意并发窗口内各调用共享第一次调用注入的 now 语义（checkedAt 取先到者）。
 let inflight = null
 
+/**
+ * 版本缓存失效（面板一键升级专用，lib/self-update.mjs 调用）：pnpm 把磁盘
+ * 上的包装到新版本后，进程内这份缓存（含 1h TTL 与 7 天 lastGood 窗口里的
+ * 旧结论）整体作废——下次 getVersionInfo 按磁盘新版本重算 updateAvailable。
+ * 只重置缓存与 in-flight，不改任何检测行为。
+ */
+export function invalidateVersionCache() {
+  cache = { at: 0, info: null }
+  inflight = null
+}
+
 /**
  * 组合结果（面板路由专用）：带 1 小时内存缓存，过期才重新请求；请求失败时
  * 若上次成功结果在 lastGood 窗口（7 天，见 LASTGOOD_TTL_MS）内则原样复用

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-maoying",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "毛颖 — DSH 网文创作辅助插件：主编 + 五帮手编排（大纲/写手/审校/设定/考据），novel/ 结构化文件为数据库",
   "type": "module",
   "license": "MIT",