@gavinc-cn/touchstone-dsh 0.3.0 → 0.4.0

package/backend/server.js

@@ -53,6 +53,7 @@ import { setMediaFetcher } from './lib/sessparse.js';
 import { pidAlive } from './lib/proc.js';
 import { respondError, respondUnsupportedMethod, sendRedirect } from './lib/http.js';
 import { acquireSingleInstance, resolveDbPath } from './lib/lock.js';
+import { seedHint } from './lib/seed_hint.js';
 import {
   Runner, reconcileUnits, setBoardFinishHook, setBoardSelfcheckHooks, setInstance,
   setLivenessProbe, setUnitHandlers, startUnitSelfcheck,
@@ -272,11 +273,9 @@ async function main() {
     const executedSteps = boot.executed.length + (again ? again.executed.length : 0);
     db = openDb(dbPath);
     purgeExpiredSessions(db);
-    const hint = !boot.seeded ? ''
-      : boot.seedPassword
-        ? `  （首次启动已创建默认账号 admin，一次性初始口令：${boot.seedPassword}`
-          + '，首次登录须修改；仅本次显示，请立即记录）'
-        : '  （首次启动已创建默认账号 admin，初始口令取自 TS_ADMIN_PASSWORD，请尽快登录修改）';
+    // 横幅文案：三档与 seedAdmin 的口令来源一一对应（见 lib/seed_hint.js；
+    // 2026-10-16 前空口令档误落「初始口令取自 TS_ADMIN_PASSWORD」文案）
+    const hint = seedHint(boot);
     // 文案只报「检查了几步」而不说「执行了几步」（M3 评审 D5）：声明式迁移在**已迁移完**的库上
     // 逐步 no-op（实测同一份快照库起停两次，表行数与文件 sha256 完全不变），旧文案
     // 「本次执行迁移 N 步」读起来像「又迁移了一遍」，排障时会误导。
@@ -312,20 +311,28 @@ async function main() {
   setBoardSelfcheckHooks({ unitManaged: board.unitManaged, refreshExtRows: board.refreshExtRows });
   const runnerInstance = new Runner(true, { dbPath });
   setInstance(runnerInstance);
-  // ---- M6.5 接线：单元执行体（`setUnitHandlers`）-----------------------------------
-  // `t:` 与 `c:` 两路**接真**：`processTask`（轮次执行体：script_retest / 复压 / retest_bug /
-  // fix / pipeline / 轮次循环）与 `processCard`（看板卡片起跑）。接线前这两路一律抛具名错误
-  // `UNIT_HANDLER_MISSING`（「任务单元轮次执行体未移植（M6）」）⇒ 实例级判据
+  // ---- M6.5/M10 接线：单元执行体（`setUnitHandlers`）--------------------------------
+  // 三路**接真**：`t:` → `processTask`（轮次执行体：script_retest / 复压 / retest_bug /
+  // fix / pipeline / 轮次循环）、`c:` → `processCard`（看板卡片起跑）、
+  // `a:` → `board.deliverAnswerUnit`（答案送达；`runner.py:1087` → `board._deliver_answer_unit`）。
+  // 接线前三路一律抛具名错误 `UNIT_HANDLER_MISSING` ⇒ 实例级判据
   // `cases-http/m6_5_runner.json` 接线前是**红**的（rounds 缺行 + error 文案不同），接线后才绿。
   //
-  // **只接两路**：`a:`（答案送达，`board._deliver_answer_unit`）仍留空缝 ⇒ 命中即抛
-  // `UnitHandlerMissing`（响亮，不静默）。这是 M5-2 划归「作答/归档族」的口，属 M7。
+  // **`a:` 是 2026-10-16 补接的（M10）**：M6.5 只接了 `t:`/`c:` 并把 `a:` 注明「属 M7」，
+  // 但 M7/M7.5/M8/M9 都没接 ⇒ 平台侧作答（TS 会话窗 / 飞书入站；「立即送达」以外的自动路径）
+  // 一律「入队成功、永远送不出去」：`runPickedUnit` 的 a: except 分支是「放回等待重投」，
+  // 于是**热旋**——真机实测后端 50% CPU、日志 5.5KB/s 涨到 3.9MB（几十万行同一句
+  // 「答案送达体未移植（M5）」，而实现体 M5 就在 `board.js` 里，缺的只是这张注册表）。
+  // 用户可见现象：在 TS 里答了没反应、答案永远停在「排队中」。与 `routes/sessions.js`
+  // 误用 M3 占位桩同属「已实现但没接线」类缺陷（判据缺口也相同：函数级单测照不到接线）。
   //
   // 位置：`setInstance` 之后、`recover()` 之前 —— 执行体在闸后（`releaseBootGate`）才可能被
   // 调用，此处注册只保证「任何一条被拾取的单元都有执行体」，不引入新的启动序。
   setUnitHandlers({
     processTask: (taskId) => runnerInstance.processTask(taskId),
     processCard: (cardId) => runnerInstance.processCard(cardId),
+    // `options` 与同段其它 board 口同款：显式传本轮解析出的 `dbPath`（缺省库口径见 db.js）
+    deliverAnswerUnit: (cardId) => board.deliverAnswerUnit(cardId, { dbPath }),
   });
   await runnerInstance.recover();
   await board.recover({ dbPath });        // ③ 硬顺序：runner.recover → board.recover → 对账

package/board.py

@@ -1557,6 +1557,11 @@ _runs_lock = threading.Lock()
 # 单卡片 prompt 长度上限（与 chat.MESSAGE_MAX 对齐）
 PROMPT_MAX = 20000
 
+# 平台任务提示词的段标（`build_task_prompt` 的首段）。除拼提示词外还用作**判据**：
+# 会话首问以它开头 ⇒ 这个会话是平台按某张卡片的内容拼提示词启动的（2026-10-16 起，
+# 这类卡的标题/描述也跟随 DSH，见 `_is_platform_task_session`）。
+TASK_PROMPT_TAG = "【任务描述】"
+
 
 def build_task_prompt(project, card, extra=""):
     """全量任务提示词：任务描述（卡片标题并入描述）+ 工作目录 + 附加段。
@@ -1580,7 +1585,7 @@ def build_task_prompt(project, card, extra=""):
     desc = (card["description"] or "").strip()
     body = "\n\n".join(seg for seg in (title, desc) if seg) or "（无）"
     workspace = card_workspace(project, card)
-    p = (f"【任务描述】{body}\n"
+    p = (f"{TASK_PROMPT_TAG}{body}\n"
          f"【工作目录】{workspace}")
     wt = (_card_opt(card, "worktree") or "").strip()
     if wt:
@@ -2304,6 +2309,17 @@ def compact_session(project, card, sid):
     外部会话的 agent 已在宿主 store 注册，`/session` resume 必撞
     `agent "…" is already registered` ⇒ 500（C 批 T1 实测）。
 
+    **会话存活前置（2026-10-17 修卡 907「TS 侧 /compact 对已结束会话必失败」）**：
+    上面那条「不能先接管」只对**宿主里仍活着**的会话成立；对宿主里**根本没有活 agent**
+    的会话（dsh web 重启、插件重载、久未接续的旧卡——用户报障卡 907 就是 9 天前的
+    平台自建卡），驱动 `/compact` 必 404「会话已结束（宿主无活动 agent）」，上面两跳
+    再怎么补声明也救不回来。而 dsh GUI 自己的 `/compact` 对冷会话是**按需 resume 再执行
+    命令**（`dsh-api-session-controller.resolve` → `agents.resume`），故这里与投递腿
+    `_deliver_now` 同款：先 `_ensure_card_session` 接回（判据/边界同它——中枢未对齐按
+    「未知」不动、sync 卡不收养、回滚阀 `TS_HOST_SESSION_REVIVE=0` 时不动，均为零请求），
+    再走下面的压缩两跳。接不回**不在此收口**：照旧走两跳，由驱动 404 文案兜底（与修复前
+    完全一致）。
+
     sid 必须属于该卡片（sessions 清单或主 session_id），不支持的族抛
     RuntimeError（server 转 400）。
     """
@@ -2314,6 +2330,8 @@ def compact_session(project, card, sid):
         # 单族化：非 dsh 即退场族项目（migrate_p7b 改写后不再出现），
         # 给「改绑 dsh 插件」的明确提示（B0 防呆口径）
         raise RuntimeError(agents.RETIRED_MSG)
+    # 会话存活前置：宿主已失去该会话 ⇒ 先按 resume 语义接回，再压缩（与投递同款）
+    _ensure_card_session(project, card, sid)
     # 路线 A P3（2026-10-03）：走驱动 `/compact`（插件侧执行宿主 `/compact`
     # 命令；`ctx.compaction` 服务在插件 ctx 不可注入，命令路径是 P0 探针的结论）。
     # 触发即返回——压缩在 dsh 进程内异步进行（要过一次模型），失败落宿主日志。
@@ -3450,6 +3468,9 @@ SYNC_BUSY_MTIME_S = 120
 # 用户改名后，同步节拍跟着改卡标题）、描述 = 主会话第一次用户提问**全文**。
 # 旧口径（2026-10-07~10-10：「首问首行进标题、其余行进描述」）已退场，存量卡由
 # `_sync_card_follow` 在首个同步拍回填（详见 board spec §48）。
+# 2026-10-16 扩面（用户诉求「卡面标题/正文与 DSH 保持一致」）：同一口径从
+# `origin='sync'` 卡扩到**平台从看板启动过会话的卡**（判据 = 会话首问是平台拼的
+# 任务提示词，见 `_is_platform_task_session`）；列语义与存量收口仍只服务 sync 卡。
 SYNC_TITLE_MAX = 200   # 标题上限（沿用建卡既有截断：insert_board_card 调用处 [:200]）
 SYNC_DESC_MAX = 2000   # 描述上限（防一次长提问把看板负载撑大）
 
@@ -3611,19 +3632,45 @@ def _auto_title_forms(item, sid):
     return forms
 
 
+def _in_first_prompt(text, item):
+    """卡面字段是否仍是「平台按卡片内容拼进首问」的**原文形态**（判自动写入用）。
+
+    平台起会话时把卡片标题/描述原样拼进首问（`build_task_prompt`：标题并入
+    【任务描述】段、与描述空行分隔）⇒ 卡面字段只要没被用户改过，就必然能在首问
+    原文里原样找到。用户后来改写过的文本通常不在（⇒ 不覆盖，尊重用户编辑）。
+    空/纯空白一律 False（空标题由 `_auto_title_forms` 那一档负责）。
+    """
+    t = (text or "").strip()
+    return bool(t) and t in (item.get("first_prompt") or "")
+
+
+def _is_platform_task_session(item):
+    """该会话是否「平台按某张卡片的内容拼提示词启动的」（判据 = 首问以段标开头）。
+
+    卡片启动腿（`enter_doing` → `build_task_prompt`）拼的首问以 `TASK_PROMPT_TAG`
+    开头；用户在 dsh GUI 里直跑的会话首问是用户原文、续跑腿是「继续」，都不会命中。
+    用于把正向同步（DSH 标题/首问 → 卡面）从 sync 卡扩到**平台从看板启动过会话的卡**
+    （2026-10-16 用户诉求：卡面标题/正文与 DSH 保持一致；见 spec/board §48）。
+    """
+    return (item.get("first_prompt") or "").lstrip().startswith(TASK_PROMPT_TAG)
+
+
 def _sync_card_follow(card, item, sid):
-    """存量 sync 卡按「DSH 当前标题 + 首问全文」补齐的字段 dict（无变化返回 {}）。
+    """卡面按「DSH 当前标题 + 首问全文」补齐的字段 dict（无变化返回 {}）。
 
     只认「主会话」：遍历到的会话不是卡的主会话（多会话并集里的子会话）时不动。
-    只在卡仍由平台自动写入时动（卡标题 ∈ `_auto_title_forms`：空 / sid 短码 / 任一枚
-    会话标题事件 / 旧口径的首问首行）——用户在卡面行内改过标题就整张卡不再自动覆盖
-    （描述也不动）。描述仅在为空、或仍是**旧口径自动写入**（首问除首行）时改成首问
-    全文；用户写过的描述不覆盖。
+    只在卡仍由平台自动写入时动——卡标题 ∈ `_auto_title_forms`（空 / sid 短码 / 任一枚
+    会话标题事件 / 旧口径的首问首行）**或** 仍是平台拼进首问的原文（`_in_first_prompt`，
+    2026-10-16 增：服务「平台从看板启动过会话的卡」——它的标题是用户在卡里敲的原文，
+    不在任何标题事件里）；用户在卡面行内改过标题就整张卡不再自动覆盖（描述也不动）。
+    描述仅在为空、仍是**旧口径自动写入**（首问除首行）、或仍是平台拼进首问的原文时
+    改成首问全文；用户写过的描述不覆盖。
     """
     if (card["session_id"] or sid) != sid:
         return {}
     cur_title = (card["title"] or "").strip()
-    if cur_title not in _auto_title_forms(item, sid):
+    if (cur_title not in _auto_title_forms(item, sid)
+            and not _in_first_prompt(cur_title, item)):
         return {}
     title, desc = _sync_card_fields(item, sid)
     out = {}
@@ -3631,7 +3678,8 @@ def _sync_card_follow(card, item, sid):
         out["title"] = title
     cur_desc = (card["description"] or "").strip()
     legacy_desc = _split_first_prompt(item.get("first_prompt") or "")[1]
-    if desc and cur_desc != desc and cur_desc in ("", legacy_desc):
+    if (desc and cur_desc != desc
+            and (cur_desc in ("", legacy_desc) or _in_first_prompt(cur_desc, item))):
         out["description"] = desc
     return out
 
@@ -3653,6 +3701,10 @@ def sync_sessions(project):
     todo/blocked/done 后不再自动搬）；会话存储被删的 sync 卡自动进 done；绑子代理
     会话的存量 sync 卡收口进回收站（每项目一轮）；上述两类误建卡的存量也按同款
     口径收口（每项目一轮，见函数尾注释）。
+    **平台从看板启动过会话的卡**（用户建卡 → 开始/回车启动，首问 = 平台拼的任务提示词，
+    见 `_is_platform_task_session`）同样按上面同一口径补齐卡面——但**列语义不动**：
+    归档/取消归档的列映射与各类存量收口仍只服务 `origin='sync'` 卡（用户自己的卡，
+    平台只同步标题/描述，不替用户搬列、不软删）。用户改过卡名 ⇒ 整卡不动（含描述）。
     sync 卡不占 runner 项目占用（外部会话平台控制不了，防堵死统一队列）。
     """
     if not settings_of(project["id"]).get("sync_sessions", True):
@@ -3699,13 +3751,15 @@ def sync_sessions(project):
             db.update_board_card(cid, session_id=sid, sessions=json.dumps([sid]),
                                  column_key=col, origin="sync")
             created.append(cid)
-        elif c["origin"] == "sync":
-            # 首问补齐（2026-10-07）：标题/描述仍是平台自动写入形态时按首问覆盖
-            # （覆盖「建卡时提问还没到」的竞态与旧口径的存量卡；用户改过名不动）
+        elif c["origin"] == "sync" or _is_platform_task_session(it):
+            # 卡面补齐（2026-10-07 起服务 sync 卡；2026-10-16 起扩到「平台从看板启动过
+            # 会话的卡」，见 `_sync_card_follow`）：标题/描述仍是平台自动写入形态时按
+            # DSH 当前标题 + 首问全文覆盖（用户改过名整卡不动）
             fields = _sync_card_follow(c, it, sid)
             if fields:
                 db.update_board_card(c["id"], **fields)
-            if c["column_key"] in ("doing", "review") and not _has_active_run(c["id"]):
+            if (c["origin"] == "sync" and c["column_key"] in ("doing", "review")
+                    and not _has_active_run(c["id"])):
                 # dsh 的 busy/空闲 列映射已移交调和器（事件驱动，异常不搬列）；
                 # 此处保留归档→done（archived 来源=list_sessions 的宿主归档集文件读，
                 # 与调和器读驱动帧是两条独立通道：文件读不依赖驱动链路，重启/断连时

package/chat.py

@@ -399,6 +399,39 @@ def cancel_queued(sid=None, card_id=None):
     return sum(1 for r in rows if cancel(r["id"]))
 
 
+def cancel_queued_detail(sid=None, card_id=None, msg_id=None):
+    """取消排队中的消息**并回带原文**（`mode=cancel_queue` 端点的实现；用户点「取消排队」）。
+
+    与 `cancel_queued` 的差别只有「回带」：后者是停止入口共用的计数壳。用户显式取消排队时，
+    前端要把消息原文放回输入框，而 `msgs_of_sid` 下发给前端的展示文本被截到 120 字——
+    回填必须由服务端给**全量原文**，否则长消息被静默截断。
+
+    逐行只在 `cancel()` 真命中（chat_msgs 的 queued→cancelled 原子守卫是仲裁点，R12）
+    时才收进结果：与 worker claim 竞态下已被抢走执行的消息既不会被取消、也不会回带，
+    前端不会把仍在执行的消息错放回输入框。返回按入队顺序（msg_rows 的 created_at,id）。
+
+    `msg_id` 非空 ⇒ 只取消该条（归属校验由端点层做，本函数只管状态）。
+    返回 `{"cancelled": n, "msgs": [{"id", "text"}]}`；空过滤返回空（不误伤全库）。
+    """
+    if not sid and not card_id and not msg_id:
+        return {"cancelled": 0, "msgs": []}
+    if msg_id:
+        row = waitq.msg_get(msg_id)
+        if row is None or row["state"] != STATE_QUEUED:
+            return {"cancelled": 0, "msgs": []}
+        rows = [row]
+    else:
+        rows = waitq.msg_rows(sid=sid, card_id=card_id, states=(STATE_QUEUED,))
+    msgs = []
+    for r in rows:
+        # 先取原文再取消：取消是终态迁移，但仍按「命中才回带」的次序写，读一次即用一次
+        text = r["message"] if r["message"] is not None else ""
+        if not cancel(r["id"]):
+            continue
+        msgs.append({"id": r["id"], "text": str(text)})
+    return {"cancelled": len(msgs), "msgs": msgs}
+
+
 def msgs_of_sid(sid):
     """本会话消息的展示视图（排队/执行中 + 近期失败）：{id,text,state,error,created_at}。
 

package/dsh-plugin/lib/client.bundle.js

@@ -279,10 +279,117 @@ function panelEntry() {
   return '/touchstone/app';
 }
 
-// 全屏面板: 无顶栏(iframe 吃满全屏) + 关闭按钮悬浮在左下角(位置与 dsh 侧栏入口一致)
+// ── 窗口装饰区让位(2026-10-17, 卡 987 方案 A) ─────────────────────────────────
+// 血案: 面板是全窗口浮层(position:fixed; inset:0), 而桌面版窗口的顶带(Windows 的最小化/
+// 最大化/关闭、macOS 的红绿灯)由桌面壳画在网页之上 —— 浮层顶部那行按钮正好落在它底下,
+// 在 dsh desktop 里整块被盖住、点不到(现象与取证见
+// doc_ai/debug_runtime/202610/20261017_0600_零项目首屏无可点建项目入口… .md)。
+// 修法: 让整个浮层从窗口顶边**下移**「壳实际绘制的窗口 chrome 高度」—— 顶带完整露给壳
+// (标题文字/拖拽区/窗口按钮都还在原位), 面板内容从它下面开始。等价于 dsh 自己主面板与
+// 弹窗的处理口径(layout 发布 --dsh-frame-top-clearance / --dsh-frame-chrome-top),
+// 而且**不需要 SPA 侧改任何代码**: iframe 拿到的视口自己就变矮了。
+// 高度来源(优先级从高到低; 全部读不到 ⇒ 0 ⇒ 独立浏览器形态, 行为与今天完全一致):
+//   ① dsh 桌面壳发布在 <html> 上的约定量(见 @deepseek-ai/dsh-client-ui-layout 的
+//      README「窗口 chrome 顶带」; 普通浏览器文档不发布这些值):
+//        --dsh-frame-chrome-top     壳当前**实际绘制**的顶带高(全屏时归 0)
+//        --dsh-frame-top-clearance  顶带之下的固定下沉量(Windows = 标题栏高, macOS = 48px)
+//      **取两者较大**: 全屏时 chrome-top 归零, 但 dsh 的 Frame 仍按 titlebar 高度让位,
+//      取 max 才能和主面板同口径、不会在全屏时又把窗口按钮盖回去。
+//   ② WCO 原生接口 navigator.windowControlsOverlay(Chromium/Electron; 旧桌面壳只开了
+//      overlay 但没发布 ① 的量时兜底): getTitlebarAreaRect() 的 y + height = 顶带高。
+//   ③ CSS env(titlebar-area-height) 探针(同一能力的老式访问面, 只支持 env 的壳兜底)。
+// 仍读不到(普通浏览器/不支持窗口浮层的壳) ⇒ 0 ⇒ 现状(独立形态本来就没有窗口装饰)。
+const CHROME_MAX_PX = 200; // 合法上限: 再大必然是脏值(标题栏不可能 200px), 一口拒绝
+
+/** 读 <html> 上某个 CSS 自定义属性的像素值。空串/无法解析/越界 ⇒ null（0px 是合法值）。 */
+function readChromePx(name) {
+  try {
+    if (typeof document === 'undefined' || !document.documentElement) return null;
+    const cs = window.getComputedStyle ? window.getComputedStyle(document.documentElement) : null;
+    if (!cs) return null;
+    const raw = cs.getPropertyValue(name);
+    if (!raw) return null;
+    const n = parseFloat(raw);
+    if (!Number.isFinite(n) || n < 0 || n > CHROME_MAX_PX) return null;
+    return n;
+  } catch { return null; } // 读样式异常绝不能拖垮面板本体
+}
+
+/** WCO 原生接口量顶带高(标题栏区域 rect 的 y + height); 不可见/不可用 ⇒ null。 */
+function wcoChromePx() {
+  try {
+    const nav = window.navigator;
+    const wco = nav && nav.windowControlsOverlay;
+    if (!wco || !wco.visible) return null;
+    const rect = wco.getTitlebarAreaRect ? wco.getTitlebarAreaRect() : null;
+    if (!rect) return null;
+    const n = (rect.y || 0) + rect.height;
+    if (!Number.isFinite(n) || n <= 0 || n > CHROME_MAX_PX) return null;
+    return n;
+  } catch { return null; }
+}
+
+/** env(titlebar-area-height) 探针: 挂一个 0 宽、高度取 env 的隐形探针量出来; 不支持 ⇒ null。
+ *  探针始终会被摘掉(成功/失败都摘), 不往宿主 DOM 里留垃圾。 */
+function envChromePx() {
+  try {
+    if (typeof document === 'undefined' || !document.body
+        || typeof document.createElement !== 'function'
+        || typeof document.body.appendChild !== 'function') return null;
+    const probe = document.createElement('div');
+    probe.style.cssText = 'position:fixed;left:0;top:0;width:0;'
+      + 'height:env(titlebar-area-height,0px);visibility:hidden;pointer-events:none';
+    document.body.appendChild(probe);
+    let h = 0;
+    try {
+      h = probe.getBoundingClientRect ? probe.getBoundingClientRect().height : 0;
+    } finally {
+      if (typeof probe.remove === 'function') probe.remove();
+      else if (typeof document.body.removeChild === 'function') document.body.removeChild(probe);
+    }
+    if (!Number.isFinite(h) || h <= 0 || h > CHROME_MAX_PX) return null;
+    return h;
+  } catch { return null; }
+}
+
+/** 窗口 chrome 顶带高(px): 面板浮层从窗口顶边下移这么多。0 = 没有桌面窗口装饰。 */
+function windowChromeTop() {
+  // ① dsh 桌面壳的约定量(两者取大, 口径见本节头注释)
+  const chrome = readChromePx('--dsh-frame-chrome-top');
+  const clearance = readChromePx('--dsh-frame-top-clearance');
+  if (chrome !== null || clearance !== null) {
+    return Math.max(chrome || 0, clearance || 0);
+  }
+  // ②③ 旧壳/其它壳兜底: WCO 原生接口 → env() 探针
+  return wcoChromePx() || envChromePx() || 0;
+}
+
+/** chrome 顶带高的响应式读取: 渲染期现读(首帧就带真值, 不闪一帧顶格),
+ *  壳换档(resize/进出全屏/窗口几何变化)时自增重渲染。 */
+function useWindowChromeTop() {
+  const [, setRevision] = React.useState(0);
+  React.useEffect(() => {
+    const bump = () => setRevision((n) => n + 1);
+    window.addEventListener('resize', bump);
+    document.addEventListener('fullscreenchange', bump);
+    // WCO 几何变化不是 DOM 事件(壳侧全屏/标题栏变高/贴边), 只能由原生接口通知
+    const wco = window.navigator && window.navigator.windowControlsOverlay;
+    if (wco && typeof wco.addEventListener === 'function') wco.addEventListener('geometrychange', bump);
+    return () => {
+      window.removeEventListener('resize', bump);
+      document.removeEventListener('fullscreenchange', bump);
+      if (wco && typeof wco.removeEventListener === 'function') wco.removeEventListener('geometrychange', bump);
+    };
+  }, []);
+  return windowChromeTop();
+}
+
+// 全屏面板: 浮层从窗口 chrome 顶带之下开始(没有桌面壳时 = 0 = 吃满全屏) +
+// 关闭按钮悬浮在左下角(位置与 dsh 侧栏入口一致)
 // iframe 同源, /touchstone/app 经薄壳反代到 server.py 的插件版 SPA
 function Panel() {
   const isOpen = useOpen();
+  const chromeTop = useWindowChromeTop(); // 窗口装饰顶带高: Windows 标题栏/macOS 红绿灯
   // 保活(2026-10-07): 打开过就在 DOM 里常驻, 关闭只把容器 display:none —— iframe 一旦
   // 从 DOM 摘掉, 内嵌 SPA 整篇文档就没了, 再打开是全新加载(路由/弹窗/滚动/未提交输入全丢)。
   // mounted 由「打开过」与「当前打开」合成: 首次打开的那一次渲染就带上 iframe(不等 effect
@@ -389,7 +496,9 @@ function Panel() {
   const visible = !zoneOk || shown; // 自动隐藏不可用时(zoneOk=false)保持常显
   return h('div', {
     style: {
-      position: 'fixed', inset: 0, zIndex: 9999,
+      // 顶边让出窗口装饰带(见 useWindowChromeTop): 桌面壳里 = 标题栏/红绿灯的高度,
+      // 普通浏览器里 = 0(与旧版 inset:0 完全一致)。其余三边照旧贴边。
+      position: 'fixed', top: chromeTop, left: 0, right: 0, bottom: 0, zIndex: 9999,
       background: 'var(--dsw-alias-bg-base, #161617)',
       display: isOpen ? 'block' : 'none', // 关闭 = 只隐藏: iframe 与内嵌 SPA 常驻(保活)
     },

package/dsh-plugin/lib/index.js

@@ -480,9 +480,32 @@ function renderNodeRuntimeHint({ execPath, version, detail, logPath }) {
  * 为什么需要：「入口缺失」只是新开关失败的一种；更常见的是入口在、跑不起来
  * （宿主 Node 版本不认 `--disable-warning`、`dist-plugin` 缺失、被执行策略拦、脚本自身报错）。
  * 那时 `backendPort` 一直是 0，proxy 只会回通用 503 JSON —— 面板里显示一段 JSON 原文，
- * 用户既不知道发生了什么、也不知道去哪看。提示页给三件事：失败原因、日志路径、怎么回退。
+ * 用户既不知道发生了什么、也不知道去哪看。提示页给四件事：失败原因、**后端最后几行输出**、
+ * 日志路径、怎么回退。
+ *
+ * 2026-10-17 桌面端真机事故的教训：提示页原先只教用户自己 `tail` 日志文件（Windows 用户得先
+ * 找到库目录、开终端），而失败原因（「同一数据库已有运行中的实例：pid=…」）就一行字。现改为
+ * 把**内存里收到的最后几行**直接内联（见 apply 里的 `crashTail`），并对 `code=3` 给出单实例锁
+ * 的专项提示 —— 提示页要能自解释，而不是把排障转嫁给用户。
  */
-function renderBackendCrashHint({ entryPath, logPath, code, signal }) {
+function renderBackendCrashHint({ entryPath, logPath, code, signal, tailLines }) {
+  const logPathText = escapeHtml(logPath || '<库目录>/plugin-backend.log');
+  const tail = (Array.isArray(tailLines) ? tailLines : [])
+    .map((line) => String(line)).filter((line) => line.trim()).slice(-10);
+  const tailBlock = tail.length
+    ? '<p>后端进程最后输出（内存缓冲；启动失败原因通常就在最后几行）：</p>'
+      + '<pre style="background:#0d0f12;border:1px solid #2a2f36;border-radius:6px;'
+      + `padding:.8rem 1rem;overflow:auto">${escapeHtml(tail.join('\n'))}</pre>`
+    : '';
+  // code=3 在**两版后端**里都是「同库单实例锁没拿到」（server.py 与 backend/server.js 的
+  // exit 3 同义，见 spec §十九.7）。把排障动作写进页面，别让用户对着 generic 文案猜。
+  const lockHint = String(code) === '3'
+    ? '<p><b>code=3 = 同库单实例锁没拿到</b>：可能另有 Touchstone 后端占着同一个库，'
+      + '或锁文件/归属记录残留。先确认没有实例在跑（任务管理器里找带 '
+      + '<code>backend/server.js</code> / <code>server.py</code> 的 node/python 进程），'
+      + '再停用→启用本插件重试；仍失败再把库目录下的 '
+      + '<code>*.lock</code> / <code>*.pid</code> 移走后重试。</p>'
+    : '';
   return '<!doctype html><html lang="zh"><head><meta charset="utf-8">'
     + '<title>Touchstone 后端未启动</title></head>'
     + '<body style="margin:0;padding:2rem;font:14px/1.75 ui-monospace,Menlo,Consolas,monospace;'
@@ -490,10 +513,13 @@ function renderBackendCrashHint({ entryPath, logPath, code, signal }) {
     + '<h2 style="color:#ffb454;margin:0 0 .9rem">Touchstone 后端未启动：Node 后端进程退出</h2>'
     + `<p>入口 <code>${escapeHtml(entryPath)}</code> 起来了但没有报出监听端口就退出`
     + `（code=${escapeHtml(String(code))}${signal ? `, signal=${escapeHtml(String(signal))}` : ''}）。</p>`
-    + '<p>下一步：看后端日志里的最后几行（启动失败原因就在那里）——</p>'
+    + tailBlock
+    + lockHint
+    + '<p>下一步：看完整后端日志里的最后几行（启动失败原因就在那里）——</p>'
     + `<pre style="background:#0d0f12;border:1px solid #2a2f36;border-radius:6px;padding:.8rem 1rem;`
-    + `overflow:auto">tail -n 40 ${escapeHtml(logPath || '<库目录>/plugin-backend.log')}</pre>`
-    + '<p>常见原因：<code>dist-plugin</code> 构建产物缺失、被执行策略拦下、入口脚本自身报错。'
+    + `overflow:auto">tail -n 40 ${logPathText}</pre>`
+    + '<p>常见原因：<code>dist-plugin</code> 构建产物缺失、被执行策略拦下、入口脚本自身报错、'
+    + '同库单实例锁被占/残留（<code>code=3</code>）。'
     + '若日志里是 <code>node:sqlite</code> / <code>ERR_UNKNOWN_BUILTIN_MODULE</code> 一类，'
     + '那是宿主 Node 太老 —— 升级到 22.19+ 或改回 <code>backend: python</code>。'
     + '改完把本插件<b>停用再启用</b>即会重试。</p>'
@@ -809,8 +835,18 @@ export async function apply(ctx, config = {}) {
       try { myLog.write(line + '\n'); } catch { /* 流已坏：忽略，绝不打断读取 */ }
     };
     let sawListen = false;   // 是否报出过监听端口（判「起来就崩」用，见 renderBackendCrashHint）
+    // 崩溃提示页要内联「最后几行输出」：从管道现收一份内存环形缓冲。为什么不读日志文件——
+    // 日志是 append 写流（异步落盘），退出的那一刻盘上可能还差最后几行；只有这里保存的是
+    // pumpLines **已经交付**的完整行（2026-10-17 桌面端真机事故：失败原因就一行，但用户拿不到）。
+    const CRASH_TAIL_LINES = 12;
+    const crashTail = [];
+    const keepLine = (line) => {
+      crashTail.push(line);
+      if (crashTail.length > CRASH_TAIL_LINES) crashTail.shift();
+    };
     pumpLines(myChild.stdout, (line) => {
       writeLog(line);
+      keepLine(line);
       const m = line.match(/^TOUCHSTONE_LISTEN (\d+)/);
       if (m) {
         sawListen = true;
@@ -820,6 +856,7 @@ export async function apply(ctx, config = {}) {
     });
     pumpLines(myChild.stderr, (line) => {
       writeLog(line);
+      keepLine(line);
       if (line.trim()) logger.warn(`touchstone[${backend === BACKEND_NODE ? 'node' : 'py'}]: ${line.trim()}`);
     });
     // 「起来就崩」不再只留一行 dsh 日志：Node 分支给面板一个可读提示页（Python 分支行为不动）。
@@ -827,6 +864,7 @@ export async function apply(ctx, config = {}) {
       if (sawListen || backend !== BACKEND_NODE) return;   // 只在 Node 分支、且从未就绪时给提示页
       backendHint = renderBackendCrashHint({
         entryPath, logPath: backendLogPath(extraEnv), code, signal: sig,
+        tailLines: crashTail.slice(),
       });
     };
     myChild.on('exit', (code, sig) => {
@@ -834,6 +872,9 @@ export async function apply(ctx, config = {}) {
       logger.warn(`touchstone: 后端退出 code=${code} sig=${sig}`);
       crashed(code, sig);
     });
+    // `exit` 可能先于 stdio 最后几个 chunk 交付（Node 文档：exit 后仍可能收到 data），
+    // `close` 才是「stdio 全部读空」。补渲染一次，让提示页里的最后几行是完整的。
+    myChild.on('close', (code, sig) => crashed(code, sig));
     myChild.on('error', (err) => {
       writeLog(`[touchstone] 后端拉起失败: ${err.message}`);
       logger.warn(`touchstone: 后端拉起失败: ${err.message}`);

package/dsh-plugin/src/client.js

@@ -272,10 +272,117 @@ function panelEntry() {
   return '/touchstone/app';
 }
 
-// 全屏面板: 无顶栏(iframe 吃满全屏) + 关闭按钮悬浮在左下角(位置与 dsh 侧栏入口一致)
+// ── 窗口装饰区让位(2026-10-17, 卡 987 方案 A) ─────────────────────────────────
+// 血案: 面板是全窗口浮层(position:fixed; inset:0), 而桌面版窗口的顶带(Windows 的最小化/
+// 最大化/关闭、macOS 的红绿灯)由桌面壳画在网页之上 —— 浮层顶部那行按钮正好落在它底下,
+// 在 dsh desktop 里整块被盖住、点不到(现象与取证见
+// doc_ai/debug_runtime/202610/20261017_0600_零项目首屏无可点建项目入口… .md)。
+// 修法: 让整个浮层从窗口顶边**下移**「壳实际绘制的窗口 chrome 高度」—— 顶带完整露给壳
+// (标题文字/拖拽区/窗口按钮都还在原位), 面板内容从它下面开始。等价于 dsh 自己主面板与
+// 弹窗的处理口径(layout 发布 --dsh-frame-top-clearance / --dsh-frame-chrome-top),
+// 而且**不需要 SPA 侧改任何代码**: iframe 拿到的视口自己就变矮了。
+// 高度来源(优先级从高到低; 全部读不到 ⇒ 0 ⇒ 独立浏览器形态, 行为与今天完全一致):
+//   ① dsh 桌面壳发布在 <html> 上的约定量(见 @deepseek-ai/dsh-client-ui-layout 的
+//      README「窗口 chrome 顶带」; 普通浏览器文档不发布这些值):
+//        --dsh-frame-chrome-top     壳当前**实际绘制**的顶带高(全屏时归 0)
+//        --dsh-frame-top-clearance  顶带之下的固定下沉量(Windows = 标题栏高, macOS = 48px)
+//      **取两者较大**: 全屏时 chrome-top 归零, 但 dsh 的 Frame 仍按 titlebar 高度让位,
+//      取 max 才能和主面板同口径、不会在全屏时又把窗口按钮盖回去。
+//   ② WCO 原生接口 navigator.windowControlsOverlay(Chromium/Electron; 旧桌面壳只开了
+//      overlay 但没发布 ① 的量时兜底): getTitlebarAreaRect() 的 y + height = 顶带高。
+//   ③ CSS env(titlebar-area-height) 探针(同一能力的老式访问面, 只支持 env 的壳兜底)。
+// 仍读不到(普通浏览器/不支持窗口浮层的壳) ⇒ 0 ⇒ 现状(独立形态本来就没有窗口装饰)。
+const CHROME_MAX_PX = 200; // 合法上限: 再大必然是脏值(标题栏不可能 200px), 一口拒绝
+
+/** 读 <html> 上某个 CSS 自定义属性的像素值。空串/无法解析/越界 ⇒ null（0px 是合法值）。 */
+function readChromePx(name) {
+  try {
+    if (typeof document === 'undefined' || !document.documentElement) return null;
+    const cs = window.getComputedStyle ? window.getComputedStyle(document.documentElement) : null;
+    if (!cs) return null;
+    const raw = cs.getPropertyValue(name);
+    if (!raw) return null;
+    const n = parseFloat(raw);
+    if (!Number.isFinite(n) || n < 0 || n > CHROME_MAX_PX) return null;
+    return n;
+  } catch { return null; } // 读样式异常绝不能拖垮面板本体
+}
+
+/** WCO 原生接口量顶带高(标题栏区域 rect 的 y + height); 不可见/不可用 ⇒ null。 */
+function wcoChromePx() {
+  try {
+    const nav = window.navigator;
+    const wco = nav && nav.windowControlsOverlay;
+    if (!wco || !wco.visible) return null;
+    const rect = wco.getTitlebarAreaRect ? wco.getTitlebarAreaRect() : null;
+    if (!rect) return null;
+    const n = (rect.y || 0) + rect.height;
+    if (!Number.isFinite(n) || n <= 0 || n > CHROME_MAX_PX) return null;
+    return n;
+  } catch { return null; }
+}
+
+/** env(titlebar-area-height) 探针: 挂一个 0 宽、高度取 env 的隐形探针量出来; 不支持 ⇒ null。
+ *  探针始终会被摘掉(成功/失败都摘), 不往宿主 DOM 里留垃圾。 */
+function envChromePx() {
+  try {
+    if (typeof document === 'undefined' || !document.body
+        || typeof document.createElement !== 'function'
+        || typeof document.body.appendChild !== 'function') return null;
+    const probe = document.createElement('div');
+    probe.style.cssText = 'position:fixed;left:0;top:0;width:0;'
+      + 'height:env(titlebar-area-height,0px);visibility:hidden;pointer-events:none';
+    document.body.appendChild(probe);
+    let h = 0;
+    try {
+      h = probe.getBoundingClientRect ? probe.getBoundingClientRect().height : 0;
+    } finally {
+      if (typeof probe.remove === 'function') probe.remove();
+      else if (typeof document.body.removeChild === 'function') document.body.removeChild(probe);
+    }
+    if (!Number.isFinite(h) || h <= 0 || h > CHROME_MAX_PX) return null;
+    return h;
+  } catch { return null; }
+}
+
+/** 窗口 chrome 顶带高(px): 面板浮层从窗口顶边下移这么多。0 = 没有桌面窗口装饰。 */
+function windowChromeTop() {
+  // ① dsh 桌面壳的约定量(两者取大, 口径见本节头注释)
+  const chrome = readChromePx('--dsh-frame-chrome-top');
+  const clearance = readChromePx('--dsh-frame-top-clearance');
+  if (chrome !== null || clearance !== null) {
+    return Math.max(chrome || 0, clearance || 0);
+  }
+  // ②③ 旧壳/其它壳兜底: WCO 原生接口 → env() 探针
+  return wcoChromePx() || envChromePx() || 0;
+}
+
+/** chrome 顶带高的响应式读取: 渲染期现读(首帧就带真值, 不闪一帧顶格),
+ *  壳换档(resize/进出全屏/窗口几何变化)时自增重渲染。 */
+function useWindowChromeTop() {
+  const [, setRevision] = React.useState(0);
+  React.useEffect(() => {
+    const bump = () => setRevision((n) => n + 1);
+    window.addEventListener('resize', bump);
+    document.addEventListener('fullscreenchange', bump);
+    // WCO 几何变化不是 DOM 事件(壳侧全屏/标题栏变高/贴边), 只能由原生接口通知
+    const wco = window.navigator && window.navigator.windowControlsOverlay;
+    if (wco && typeof wco.addEventListener === 'function') wco.addEventListener('geometrychange', bump);
+    return () => {
+      window.removeEventListener('resize', bump);
+      document.removeEventListener('fullscreenchange', bump);
+      if (wco && typeof wco.removeEventListener === 'function') wco.removeEventListener('geometrychange', bump);
+    };
+  }, []);
+  return windowChromeTop();
+}
+
+// 全屏面板: 浮层从窗口 chrome 顶带之下开始(没有桌面壳时 = 0 = 吃满全屏) +
+// 关闭按钮悬浮在左下角(位置与 dsh 侧栏入口一致)
 // iframe 同源, /touchstone/app 经薄壳反代到 server.py 的插件版 SPA
 function Panel() {
   const isOpen = useOpen();
+  const chromeTop = useWindowChromeTop(); // 窗口装饰顶带高: Windows 标题栏/macOS 红绿灯
   // 保活(2026-10-07): 打开过就在 DOM 里常驻, 关闭只把容器 display:none —— iframe 一旦
   // 从 DOM 摘掉, 内嵌 SPA 整篇文档就没了, 再打开是全新加载(路由/弹窗/滚动/未提交输入全丢)。
   // mounted 由「打开过」与「当前打开」合成: 首次打开的那一次渲染就带上 iframe(不等 effect
@@ -382,7 +489,9 @@ function Panel() {
   const visible = !zoneOk || shown; // 自动隐藏不可用时(zoneOk=false)保持常显
   return h('div', {
     style: {
-      position: 'fixed', inset: 0, zIndex: 9999,
+      // 顶边让出窗口装饰带(见 useWindowChromeTop): 桌面壳里 = 标题栏/红绿灯的高度,
+      // 普通浏览器里 = 0(与旧版 inset:0 完全一致)。其余三边照旧贴边。
+      position: 'fixed', top: chromeTop, left: 0, right: 0, bottom: 0, zIndex: 9999,
       background: 'var(--dsw-alias-bg-base, #161617)',
       display: isOpen ? 'block' : 'none', // 关闭 = 只隐藏: iframe 与内嵌 SPA 常驻(保活)
     },