@gavinc-cn/touchstone-dsh 0.2.0 → 0.4.0

package/lifecycle.py

@@ -20,8 +20,14 @@ Python 后端是 dsh 宿主进程 spawn 的子进程。宿主退出/崩溃/被 `
      父还活着（例如 stdin 不是管道、或管道被无关方关闭）只记日志不自杀。
 
 2. **同库单实例** `SingleInstance`
-   - `<db>.lock` 排它锁（`platcompat.lock_fd`）+ `<db>.pid` 记录
-     `{pid, ppid, repo_dir, parent_watch, started_at}`。
+   - `<db>.lock` 上**两道锁**：`flock` 排它（`platcompat.lock_fd`）+ 同一文件上的
+     **SQLite 排它锁**（`locking_mode=EXCLUSIVE` + 一次写事务，持锁到进程结束）；
+     再写 `<db>.pid` 记录 `{pid, ppid, repo_dir, parent_watch, started_at}`。
+     - 为什么要两道（2026-10-11，Node 后端 M1）：flock 只有 Python 侧有（Node 无
+       stdlib flock），Node 版改用 SQLite 自身的排它锁，两种锁**互不相干**
+       ⇒ 只靠 flock 挡不住 Node 版实例（实测：Node 持锁时 Python 的 flock 照样
+       成功）。两边都取 SQLite 锁后，同语言与跨语言互斥都成立，且 `kill -9` 后
+       由内核/文件锁自动释放，无需清理残留。
    - 锁被占时：读 pid 记录——若记录进程**由父死感知托管**（`parent_watch=true`）
      且其父已死 ⇒ 判定为**存量孤儿**（升级前的强杀残留），SIGTERM 后重试拿锁；
      否则视为真·另一实例，明确报错退出（防双写同库）。
@@ -39,6 +45,7 @@ Python 后端是 dsh 宿主进程 spawn 的子进程。宿主退出/崩溃/被 `
 import json
 import os
 import signal
+import sqlite3
 import sys
 import threading
 import time
@@ -225,6 +232,8 @@ class SingleInstance:
         self.reason = ""
         self.reaped_pid = 0
         self._fd = None
+        # SQLite 排它锁的连接（第二道闸，M1）；持锁期间常驻，release 时关闭
+        self._lock_conn = None
 
     # ---------- 记录读写 ----------
 
@@ -259,17 +268,21 @@ class SingleInstance:
 
     @staticmethod
     def _looks_like_server(pid):
-        """粗校验 pid 是否是 touchstone 的 server.py（防 PID 复用误杀）。
+        """粗校验 pid 是否是 touchstone 的后端（防 PID 复用误杀）。
 
+        两版后端的命令行都要认：Python 是 `server.py`，Node 是 `backend/server.js`
+        （2026-10-11 M1 起 Node 版也走同一套 `.pid` 记录与孤儿收口）。
         读不到命令行时返回 True（宁可不杀——见 acquire 的调用点：仅在
         「pid 记录声明 parent_watch 且其父已死」时才走到这里）。
         """
         try:
             if sys.platform.startswith("linux"):
                 with open(f"/proc/{int(pid)}/cmdline", "rb") as f:
-                    return b"server.py" in f.read()
+                    cmdline = f.read()
+                return b"server.py" in cmdline or b"server.js" in cmdline
             import psutil
-            return any("server.py" in str(a) for a in psutil.Process(int(pid)).cmdline())
+            argv = [str(a) for a in psutil.Process(int(pid)).cmdline()]
+            return any("server.py" in a or "server.js" in a for a in argv)
         except Exception:                        # noqa: BLE001
             return True
 
@@ -308,12 +321,93 @@ class SingleInstance:
 
     # ---------- 加锁 ----------
 
+    def _acquire_sqlite_lock(self):
+        """第二道闸：同一锁文件上的 SQLite 排它锁（M1，2026-10-11）。
+
+        Node 版没有 stdlib `flock`，改用 SQLite 自身的排它锁：在 `<db>.lock` 上
+        `PRAGMA locking_mode=EXCLUSIVE` + 一次写事务，锁持有到进程/连接结束
+        （`kill -9` 由内核释放，无残留文件要清理）。两种锁机制**互不相干**，所以
+        两边都要取这一道，跨语言互斥才成立（实测：Node 持锁时 Python 的 flock
+        照样能拿到）。
+
+        返回 `(状态, 文案)`：
+          - `("ok", "")`      拿到（连接挂在 `self._lock_conn`）
+          - `("busy", "")`    被占用（调用方报「另一实例」并退出）
+          - `("unusable", 文案)` 锁文件本身不可用（损坏/是目录/打不开）——
+            **不再降级放行**（2026-10-11 评审 P1）：降级等于互斥无声消失，
+            实测「先起 Python 再起 Node」双方都能就绪 ⇒ 同库双写。
+        """
+        try:
+            conn = sqlite3.connect(self.lock_path, timeout=0)
+        except sqlite3.Error as e:
+            return "unusable", self._unusable_reason(e)
+        try:
+            conn.execute("PRAGMA busy_timeout=0")
+            conn.execute("PRAGMA locking_mode=EXCLUSIVE")
+            # 必须真写一次：EXCLUSIVE 模式在首个写事务时取锁并一直持有
+            conn.execute("CREATE TABLE IF NOT EXISTS lock_holder ("
+                         " id INTEGER PRIMARY KEY CHECK (id = 1),"
+                         " pid INTEGER NOT NULL, started_at INTEGER NOT NULL)")
+            conn.execute("INSERT OR REPLACE INTO lock_holder(id, pid, started_at)"
+                         " VALUES(1, ?, ?)", (os.getpid(), int(time.time())))
+            conn.commit()
+        except sqlite3.Error as e:
+            try:
+                conn.close()
+            except sqlite3.Error:
+                pass
+            if "locked" in str(e) or "busy" in str(e):
+                return "busy", ""
+            return "unusable", self._unusable_reason(e)
+        self._lock_conn = conn
+        return "ok", ""
+
+    def _unusable_reason(self, error):
+        """锁文件不可用的报错文案（与 Node `lock.js:unusableLockReason` 同义）。"""
+        return (f"单实例锁文件不可用：{self.lock_path}（库 {self.db_file}）。原因：{error}。"
+                f"该文件应为 SQLite 库或 0 字节空文件；内容损坏/被换成目录时无法建立互斥，"
+                f"继续启动会与另一版后端同库双写（任务重复执行、队列行被抢）。"
+                f"修复：确认没有实例在跑之后把它移走再启动"
+                f"（mv {self.lock_path} {self.lock_path}.broken）；"
+                f"或显式 --allow-shared-db 自担双写风险。")
+
+    def _release_sqlite_lock(self):
+        """释放 SQLite 排它锁（幂等）。"""
+        conn, self._lock_conn = self._lock_conn, None
+        if conn is None:
+            return
+        try:
+            conn.close()
+        except sqlite3.Error:
+            pass
+
+    def _try_take_locks(self):
+        """两道锁的状态：`("ok"|"busy"|"unusable", 文案)`。
+
+        flock 拿到但 SQLite 被占/不可用时**回退 flock**：留着不放会挡住下一个 Python
+        实例去走「孤儿收口 → 重试」的路径（它只看到 flock 被占），把可恢复的孤儿变成死锁。
+        """
+        if not platcompat.lock_fd(self._fd, blocking=False):
+            return "busy", ""
+        state, detail = self._acquire_sqlite_lock()
+        if state == "ok":
+            return "ok", ""
+        try:
+            platcompat.unlock_fd(self._fd)
+        except OSError:
+            pass
+        return state, detail
+
     def acquire(self):
-        """拿同库单实例锁。True=拿到（已写 pid 记录）；False=被真·另一实例占用。
+        """拿同库单实例锁。True=拿到（已写 pid 记录）；False=不能独占（`reason` 说明原因）。
 
         非阻塞试锁 + 存量孤儿收口：拿到即写记录返回；拿不到先读 pid 记录——
         若记录进程由父死感知托管且其父已死，判为存量孤儿，SIGTERM 后在
         `stale_wait` 内重试；否则立即返回 False 并给出可执行的报错文案。
+
+        **不再有「降级为无锁运行」分支**（2026-10-11 评审 P1）：锁文件打不开/损坏时
+        返回 False（调用方 exit 3）并给修复步骤——静默降级会让互斥无声消失、同库双写，
+        那比「启动被拒」严重得多。
         """
         os.makedirs(os.path.dirname(self.lock_path), exist_ok=True)
         if self.allow_shared:
@@ -322,15 +416,18 @@ class SingleInstance:
         try:
             fd = os.open(self.lock_path, os.O_RDWR | os.O_CREAT, 0o644)
         except OSError as e:
-            self.log(f"[lifecycle] 锁文件打开失败（降级为无锁运行）: {e}")
-            return True
+            self.reason = self._unusable_reason(e)
+            return False
         self._fd = fd
-        deadline = time.time() + max(self.stale_wait, 0.5) + 1.0
         reaped = False
         while True:
-            if platcompat.lock_fd(fd, blocking=False):
+            state, detail = self._try_take_locks()
+            if state == "ok":
                 self._write_record(os.getpid())
                 return True
+            if state == "unusable":
+                self.reason = detail
+                return False
             rec = self._read_record()
             if rec and not reaped and self._reap_stale(rec):
                 reaped = True                   # 孤儿已收口：其锁随进程退出释放，再试
@@ -343,9 +440,14 @@ class SingleInstance:
                     f"（TOUCHSTONE_DB / 插件 extraEnv.TOUCHSTONE_DB），"
                     f"或显式 --allow-shared-db 自担双写风险。")
             else:
-                self.reason = (f"锁文件被占用且无归属记录：{self.lock_path}"
-                               f"（库 {self.db_file}）。若确认无实例在跑，"
-                               f"删除该锁文件后重试。")
+                # 无归属记录时**不要**教用户删锁文件：删掉后新实例会在新 inode 上取锁，
+                # 与仍在运行的占用者双写（flock 与 SQLite 锁同理）。给安全的两个出口。
+                self.reason = (
+                    f"锁文件被占用且无归属记录：{self.lock_path}"
+                    f"（库 {self.db_file}）。占用者可能是另一版后端的异常窗口"
+                    f"（Node 版取锁后、写 .pid 前被杀）或残留的第三方进程；"
+                    f"如需并行请用独立库（TOUCHSTONE_DB / 插件 extraEnv.TOUCHSTONE_DB），"
+                    f"或显式 --allow-shared-db 自担双写风险。")
             return False
         # 不可达：while True 内所有分支都 return（保静态检查可读性）
 
@@ -354,6 +456,7 @@ class SingleInstance:
         rec = self._read_record()
         if rec and int(rec.get("pid") or 0) == os.getpid():
             self._remove_record()
+        self._release_sqlite_lock()
         if self._fd is not None:
             platcompat.unlock_fd(self._fd)
             try:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gavinc-cn/touchstone-dsh",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "AI-agent-driven automated testing platform for DeepSeek Harness (dsh): Markdown case library, bug reports, per-project serial queue, development board and built-in load testing.",
   "license": "MIT",
   "author": "Touchstone contributors",
@@ -27,6 +27,10 @@
   "files": [
     "*.py",
     "requirements.txt",
+    "backend/server.js",
+    "backend/lib",
+    "backend/routes",
+    "backend/schema",
     "builtin_prompts",
     "extensions",
     "dsh-plugin/cordis.patch.yml",
@@ -55,6 +59,7 @@
   },
   "scripts": {
     "build:client": "node dsh-plugin/scripts/build.mjs",
+    "test:backend": "node --test \"backend/test/**/*.test.mjs\"",
     "prepack": "node dsh-plugin/scripts/prepack-check.mjs"
   },
   "repository": {

package/server.py

@@ -852,6 +852,20 @@ def fs_roots():
 FILE_PREVIEW_MAX = 256 * 1024
 FILE_RAW_MAX = 32 * 1024 * 1024
 
+# `file?inline=1` 的内联白名单（2026-10-16）：**只放行浏览器可直接渲染的位图**。
+# 与 raw=1「一律 text/plain 或附件下载」的红线配套——按扩展名把 agent 在工作区写的内容
+# 内联下发，等于让同源页面按该类型解释它；`html`/`svg`/`js` 这类可执行/可带脚本的类型
+# 一律不给，只给位图（`<img>` 里不会执行任何东西）。扩展名口径与 `os.path.splitext` 一致，
+# 大小写不敏感（见 `_send_project_file_inline`）。
+PROJECT_INLINE_IMAGE_TYPES = {
+    "png": "image/png",
+    "jpg": "image/jpeg",
+    "jpeg": "image/jpeg",
+    "gif": "image/gif",
+    "webp": "image/webp",
+    "bmp": "image/bmp",
+}
+
 
 def _within_root(path, root):
     """path 是否等于 root 或位于 root 之内（调用前双方均须 realpath 规范化）。"""
@@ -1068,6 +1082,10 @@ class Handler(BaseHTTPRequestHandler):
         if path == "/api/me/feishu/doctor":
             self._api_me_feishu_doctor(body)
             return
+        if path == "/api/me/feishu/reconnect":
+            # 设置页「重连入站」按钮（M11.1）：进程内停旧长连接 → 用当前库里凭据起新
+            self._api_me_feishu_reconnect()
+            return
         if path == "/api/me/feishu-hook/apply":
             # 项目推送绑定批量应用（设置页「同时应用到我的全部项目」，2026-10-10）
             self._api_me_feishu_hook_apply(body)
@@ -1220,7 +1238,7 @@ class Handler(BaseHTTPRequestHandler):
             return
         m = re.match(r"^/api/tasks/(\d+)/session/chat/stop$", path)
         if m:
-            self._api_session_chat_stop(int(m.group(1)))
+            self._api_session_chat_stop(int(m.group(1)), body)
             return
         self._respond(404, b'{"error":"not found"}', "application/json; charset=utf-8")
 
@@ -1805,6 +1823,29 @@ class Handler(BaseHTTPRequestHandler):
         self._respond(200, json.dumps(out, ensure_ascii=False).encode("utf-8"),
                       "application/json; charset=utf-8")
 
+    def _api_me_feishu_reconnect(self):
+        """重连本人入站长连接（M11.1 设置页面板「重连入站」按钮的写口）。
+
+        停旧连接 → 用**当前库里**的凭据起新（`feishu.restart_inbound_for`，M11 已落地）。
+        响应 `{"ok": true, "started": bool, "inbound": {...}}`，键序与 `json.dumps` 分隔符是
+        对外契约（逐字节判据：`tests/test_feishu_reconnect_api.py` + 对拍
+        `cases-http/m11_feishu_reconnect.json`）：
+
+        - `ok` 恒 true：动作已执行，**不用 HTTP 错误码**表达连接成败（与 slash/provision
+          族「200 + ok/error 字段」同一口径；真正的故障原因看 `started`/`inbound`/日志）；
+        - `started` = 是否起了**新**连接（未配置凭据、旧线程没停下来 ⇒ false，语义照抄
+          `restart_inbound_for` 的返回值）——面板据此区分「没配置」「旧连接没停下」「起来了」；
+        - `inbound` = 与 `GET /api/me/feishu-cfg` 的 `inbound` **同形两键**
+          （`configured`/`thread`；`inbound_status` 的形状契约见其 docstring）。
+
+        不读体（`do_POST` 已在分派前统一读掉 body；本函数不碰它）。"""
+        user = self._current_user()
+        started = feishu.restart_inbound_for(user["id"])
+        self._respond(200, json.dumps(
+            {"ok": True, "started": bool(started),
+             "inbound": feishu.inbound_status(user["id"])},
+            ensure_ascii=False).encode("utf-8"), "application/json; charset=utf-8")
+
     def _api_me_feishu_outbox(self):
         """当前用户的最近投递记录（target 打码——URL 本身含 token 即凭据）。"""
         user = self._current_user()
@@ -2370,10 +2411,14 @@ class Handler(BaseHTTPRequestHandler):
         """读取项目范围内的文件内容供会话页预览（只读，多用户隔离）。
 
         query: path=相对/绝对路径（相对按 项目目录 → 工作目录 解析）；
-               raw=1 直接返回原文（前端「新标签打开」用）。
+               raw=1 直接返回原文（前端「新标签打开」用）；
+               inline=1 把项目范围内的**位图**按原图内联下发（会话页渲染 agent 写的
+               截图/示意图用，见 `_send_project_file_inline`；两参数都给时 inline 优先）。
         安全：路径须落在本项目「项目目录/工作目录」之内（realpath 包含判定，
         防目录穿越与越权读他人文件）；raw 一律 text/plain + nosniff——这些文件是
-        agent 在工作区写的内容，按扩展名猜类型内联下发会让同源页面执行其中脚本。
+        agent 在工作区写的内容，按扩展名猜类型内联下发会让同源页面执行其中脚本；
+        inline=1 是这条红线上的**收窄例外**：只放行 `PROJECT_INLINE_IMAGE_TYPES`
+        里的位图扩展名（附件目录里的 fid 文件同样适用，不必先上传成卡片附件）。
         """
         row = self._owned_project(project_id)
         if row is None:
@@ -2392,6 +2437,9 @@ class Handler(BaseHTTPRequestHandler):
             self._respond(code, json.dumps({"error": msg}, ensure_ascii=False).encode("utf-8"),
                           "application/json; charset=utf-8")
             return
+        if parsed.get("inline", ["0"])[0] in ("1", "true", "yes"):
+            self._send_project_file_inline(path)
+            return
         if parsed.get("raw", ["0"])[0] in ("1", "true", "yes"):
             self._send_project_file_raw(path)
             return
@@ -2459,6 +2507,50 @@ class Handler(BaseHTTPRequestHandler):
         except (BrokenPipeError, ConnectionResetError, OSError):
             pass  # 客户端提前断开属常态，静默处理
 
+    def _send_project_file_inline(self, path):
+        """`inline=1`：项目范围内的位图按原图内联下发（会话页渲染 agent 写的截图）。
+
+        与 `_send_project_file_raw` 只差两处：Content-Type 按扩展名给真图片类型、
+        不带 `Content-Disposition: attachment`（浏览器才肯在 `<img>` 里渲染）。
+        仍带 nosniff（不许嗅探成可执行类型）与 no-store（工作区文件随时被 agent 改写，
+        缓存住会看到旧图）。扩展名不在 `PROJECT_INLINE_IMAGE_TYPES` 里 ⇒ 400（白名单，
+        不是「不支持就按 raw 下发」——那正是 raw 红线要防的事）；超 FILE_RAW_MAX ⇒ 413。
+        """
+        ext = os.path.splitext(path)[1].lstrip(".").lower()
+        ctype = PROJECT_INLINE_IMAGE_TYPES.get(ext)
+        if ctype is None:
+            self._respond(400, json.dumps({"error": "该类型不支持内联显示"},
+                                          ensure_ascii=False).encode("utf-8"),
+                          "application/json; charset=utf-8")
+            return
+        try:
+            size = os.path.getsize(path)
+        except OSError:
+            self._respond(404, json.dumps({"error": "文件不存在或不可读"},
+                                          ensure_ascii=False).encode("utf-8"),
+                          "application/json; charset=utf-8")
+            return
+        if size > FILE_RAW_MAX:
+            self._respond(413, json.dumps({"error": "文件过大，无法内联显示"},
+                                          ensure_ascii=False).encode("utf-8"),
+                          "application/json; charset=utf-8")
+            return
+        self.send_response(200)
+        self.send_header("Content-Type", ctype)
+        self.send_header("Content-Length", str(size))
+        self.send_header("Cache-Control", "no-store")
+        self.send_header("X-Content-Type-Options", "nosniff")
+        self.end_headers()
+        try:
+            with open(path, "rb") as f:
+                while True:
+                    chunk = f.read(64 * 1024)
+                    if not chunk:
+                        break
+                    self.wfile.write(chunk)
+        except (BrokenPipeError, ConnectionResetError, OSError):
+            pass  # 客户端提前断开属常态，静默处理
+
     def _api_archive_project(self, project_id, archived):
         """归档/恢复项目：仅切换 archived 标记，不删数据、不影响运行中任务。
 
@@ -3093,6 +3185,11 @@ class Handler(BaseHTTPRequestHandler):
         if row is None:
             return
         if action == "stop":
+            # mode=cancel_queue（2026-10-17）：会话窗「取消排队」——纯平台侧取消排队消息、
+            # 不碰轮次；缺省/其它值 ⇒ 原样停止（旧前端不带体，响应体一字不变）。
+            if (body.get("mode") or "") == "cancel_queue":
+                self._api_cancel_queue(body, card_id=card_id)
+                return
             hit = board.stop_card(card_id)
             self._respond(200, json.dumps({"ok": True, "stopped": hit}).encode("utf-8"),
                           "application/json; charset=utf-8")
@@ -4991,16 +5088,58 @@ class Handler(BaseHTTPRequestHandler):
              "prompt_id": rec.get("prompt_id") or ""},
             ensure_ascii=False).encode("utf-8"), "application/json; charset=utf-8")
 
-    def _api_session_chat_stop(self, task_id):
-        """停止进行中的对话进程（同时取消该会话排队中的消息）。"""
+    def _api_session_chat_stop(self, task_id, body=None):
+        """停止进行中的对话进程（同时取消该会话排队中的消息）。
+
+        `mode=cancel_queue`（2026-10-17）⇒ 只取消排队消息、**不碰轮次**（会话窗「取消排队」
+        按钮）；缺省/其它值 ⇒ 原样停止（旧前端不带体，行为与响应体一字不变）。
+        """
         task, _project, _family = self._session_context(task_id)
         if task is None:
             self._respond(404, b'{"error":"task not found"}',
                           "application/json; charset=utf-8")
             return
-        chat.stop(task["session_id"] or "")
+        sid = task["session_id"] or ""
+        if ((body or {}).get("mode") or "") == "cancel_queue":
+            self._api_cancel_queue(body or {}, sid=sid, task_id=task_id)
+            return
+        chat.stop(sid)
         self._respond(200, b'{"ok":true}', "application/json; charset=utf-8")
 
+    def _api_cancel_queue(self, body, sid="", card_id=None, task_id=None, project_id=None):
+        """`mode=cancel_queue` 的共用实现（任务/看板两路）：**只取消平台排队消息，不碰轮次**。
+
+        这是会话窗「取消排队」按钮的服务端落点，与「停止」是两件事（用户 2026-10-16 裁定
+        U4：停止只打断当前轮；取消排队是另一个显式动作）。**纯平台侧**：删的是 chat_msgs
+        排队行与 m: 等待项行，不经过驱动 ⇒ 池外会话（dsh GUI 直跑/看管未接回）同样有效。
+
+        响应回带被取消消息的 {id,text}（**全文**，见 chat.cancel_queued_detail）：前端要把
+        原文放回输入框，而下发给前端的排队行文本被截到 120 字。cancelled=0 不是错误（消息
+        可能已被 worker 抢走执行，或已被别的路径取消）。
+
+        body.msg_id 非空 ⇒ 只取消该条（排队行的行内「取消」按钮）；归属判定照 _inject_msg
+        的双/三重口径，不命中同一个 404 文案（不细分，避免暴露他人消息是否存在）。
+        与 Node 半 routes/sessions.js:cancelQueueAction 同形。
+        """
+        msg_id = str(body.get("msg_id") or "")
+        if msg_id:
+            info = chat.msg_info(msg_id)
+            if (info is None
+                    or (sid and info.get("sid") != sid)
+                    or (project_id is not None and info.get("project_id") != project_id)
+                    or (card_id is not None and info.get("card_id") != card_id)
+                    or (task_id is not None and info.get("task_id") != task_id)):
+                self._respond(404, json.dumps({"error": "消息不存在或不在该会话下"},
+                                              ensure_ascii=False).encode("utf-8"),
+                              "application/json; charset=utf-8")
+                return
+        out = chat.cancel_queued_detail(sid=sid or None, card_id=card_id,
+                                        msg_id=msg_id or None)
+        self._respond(200, json.dumps({"ok": True, "cancelled": out["cancelled"],
+                                       "msgs": out["msgs"]},
+                                      ensure_ascii=False).encode("utf-8"),
+                      "application/json; charset=utf-8")
+
     # ---------- 监控 state / stream ----------
 
     def _resolve_project(self, parsed):
@@ -5392,10 +5531,14 @@ def _build_arg_parser():
 def _seed_hint(seeded, initial_pw=""):
     """启动横幅的默认账号提示：仅本次实际种子时返回文案，日常启动为空串。
 
-    2026-10-02 起默认口令不再是固定值：未设 TS_ADMIN_PASSWORD 时随机生成一次性
-    初始口令（initial_pw，由 db.take_seed_password() 取走），横幅打印这一次即清，
-    且该账号带 must_change_pw=1，首次登录必须先改密；设了 TS_ADMIN_PASSWORD 时
-    只提示变量名、不回显口令值。
+    三档与 `db.seed_admin` 的口令来源一一对应：
+      - initial_pw 非空（随机一次性口令）：打印口令本身，首登须改密；
+      - `TS_ADMIN_PASSWORD` 非空：只提示变量名、不回显口令值；
+      - 都没有（`TS_ADMIN_PASSWORDLESS=1`，插件形态）：**空口令**——2026-10-16 起单列，
+        此前落进第二档文案（凭空指向一个没设的变量）或「已在上一次打印」文案（该分支
+        结构上不可达于那种情形：seeded=False 时直接返回空串，seeded=True 且 initial_pw
+        为空只可能是空口令种子）。两版后端的这一档文案逐字节相同，见
+        `backend/lib/seed_hint.js`。
     """
     if not seeded:
         return ""
@@ -5404,7 +5547,8 @@ def _seed_hint(seeded, initial_pw=""):
                 "，首次登录须修改；仅本次显示，请立即记录）")
     if os.environ.get("TS_ADMIN_PASSWORD"):
         return "  （首次启动已创建默认账号 admin，初始口令取自 TS_ADMIN_PASSWORD，请尽快登录修改）"
-    return "  （首次启动已创建默认账号 admin，其一次性口令已在上一次启动时打印，本次不再显示）"
+    return ("  （首次启动已创建默认账号 admin，空口令（插件形态免登）"
+            "；如需口令登录请在设置页设置密码）")
 
 
 def main():