@gavinc-cn/touchstone-dsh 0.2.0 → 0.3.0

package/README.md

@@ -31,8 +31,10 @@ remembers what it already tried. A unified queue keeps exactly one writer per pr
 editing the same checkout at once), and the whole thing is observable — live round logs, a rendered
 session window, and an SSE-backed board.
 
-Touchstone runs **locally**. It is a Python web site with a SQLite database and a file-system workspace;
-no data leaves your machine except for the model calls your `dsh` host makes.
+Touchstone runs **locally**. Standalone mode is a Python web site; plugin mode defaults to the bundled Node
+backend (since 2026-10-15, with `backend: python` as the one-line fallback). Either way it is a SQLite
+database plus a file-system workspace, and no data leaves your machine except for the model calls your
+`dsh` host makes.
 
 ## Highlights
 
@@ -56,8 +58,9 @@ no data leaves your machine except for the model calls your `dsh` host makes.
   drives the load itself, N runs per task, with per-run metrics, charts, and Markdown/JSON reports.
 - **Optional integrations.** Feishu (Lark) push notifications with two-way answering from chat cards, and
   RAG-based semantic search over the case library.
-- **Self-contained stack.** Backend: Python standard library plus four small dependencies. Frontend: React
-  + Vite. Storage: SQLite + plain files. Runs on Linux and Windows.
+- **Self-contained stack.** Backend: the bundled Node backend (plugin-mode default, needs Node 22.19+) or
+  the Python standard library plus four small dependencies (standalone mode / `backend: python`).
+  Frontend: React + Vite. Storage: SQLite + plain files. Runs on Linux and Windows.
 
 ## Screenshots
 
@@ -133,8 +136,8 @@ flowchart LR
 
 | Requirement | Version | Needed for |
 |-------------|---------|------------|
-| Python | 3.12+ | The server (verified on 3.12) |
-| Node.js | 22.19+ or 24+ | Running the `dsh` host (the front-end build alone needs Node 18+) |
+| Node.js | 22.19+ or 24+ | The `dsh` host **and the plugin-mode backend** (default; the front-end build alone needs Node 18+) |
+| Python | 3.12+ | Standalone mode (`./touchstone.sh start`) and plugin mode with `backend: python` (verified on 3.12) |
 | DeepSeek Harness (`dsh`) | current release | Agent execution — required for plugin mode |
 
 ### 1. Clone and install
@@ -142,7 +145,7 @@ flowchart LR
 ```bash
 git clone https://github.com/gavinc-cn/touchstone-dsh.git
 cd touchstone-dsh
-python3 -m pip install -r requirements.txt
+python3 -m pip install -r requirements.txt   # needed for standalone mode / plugin mode with backend: python
 ```
 
 ### 2. Start the site (standalone mode)
@@ -192,25 +195,30 @@ node ~/.dsh/profiles/web/node_modules/@gavinc-cn/touchstone-dsh/dsh-plugin/scrip
 # 4) restart the dsh web UI, open http://127.0.0.1:3080, use the Touchstone entry (Alt+T toggles the panel)
 ```
 
-The platform's own Python dependencies are installed with pip, not npm:
+**Plugin mode needs no Python by default.** Since 2026-10-15 the plugin shell starts the bundled Node
+backend (it probes the host Node for `node:sqlite` first; if the host is too old it shows a hint page with
+the two ways out). Python is used only for the Python backend — standalone mode, or `backend: python` in the
+plugin config, which is the one-line fallback during the observation window (deleting the key no longer
+reverts anything: the default *is* `node` now). For that Python backend, the platform's own dependencies are
+installed with pip, not npm:
 
 ```bash
 pip install -r ~/.dsh/profiles/web/node_modules/@gavinc-cn/touchstone-dsh/requirements.txt
 # Windows: python -m pip install ...   (the official installer ships python.exe, not python3)
 ```
 
-The plugin resolves the interpreter itself when you do not configure one: it probes `python` first, then
-`python3` (the same order as `touchstone.cmd`), and uses the first one that actually runs. If that is not the
-interpreter where you installed the dependencies, the missing-dependency page prints the exact command for the
-interpreter it picked; to pin another one, set `pythonPath` in the profile patch:
+With the Python backend, the plugin resolves the interpreter itself when you do not configure one: it probes
+`python` first, then `python3` (the same order as `touchstone.cmd`), and uses the first one that actually
+runs. If that is not the interpreter where you installed the dependencies, the missing-dependency page prints
+the exact command for the interpreter it picked; to pin another one, set `pythonPath` in the profile patch:
 
 ```yaml
 - id: touchstone-dsh
-  config: { pythonPath: /path/to/python }
+  config: { backend: python, pythonPath: /path/to/python }
 ```
 
-No `repoDir` is needed: the package carries `server.py` and `webui/dist-plugin`, so the plugin falls back to
-its own directory.
+No `repoDir` is needed: the package carries `server.py`, `backend/` (the Node backend) and
+`webui/dist-plugin`, so the plugin falls back to its own directory.
 
 **Option B — from a checkout (development):**
 

package/README.zh.md

@@ -30,8 +30,9 @@ Touchstone 把「我们真该多测一点」变成一条持续转动的流水线
 一个写者（不会有两个 agent 同时改同一份检出），并且全流程可观测——逐轮实时日志、可渲染的会话窗口、
 以及基于 SSE 的看板。
 
-Touchstone 是**本地运行**的：Python 站点 + SQLite + 文件系统工作区。除了你的 `dsh` 宿主发起的模型
-调用之外，数据不出本机。
+Touchstone 是**本地运行**的：独立形态是 Python 站点；插件形态自 2026-10-15 起缺省走包内 Node 后端
+（要回 Python 就在插件 config 里显式写 `backend: python`）。两种形态都是 SQLite + 文件系统工作区，
+除了你的 `dsh` 宿主发起的模型调用之外，数据不出本机。
 
 ## 主要特性
 
@@ -50,8 +51,8 @@ Touchstone 是**本地运行**的：Python 站点 + SQLite + 文件系统工作
 - **内置压测**。压测任务先让 agent 产出场景与脚本，之后由平台自己发压，一个任务可跑 N 次，每次都有
   指标、图表与 Markdown/JSON 报告。
 - **可选集成**。飞书（Lark）推送通知与卡片双向作答；案例库的可选语义检索（RAG）。
-- **自包含技术栈**。后端：Python 标准库 + 4 个小依赖；前端：React + Vite；存储：SQLite + 普通文件。
-  Linux 与 Windows 均可运行。
+- **自包含技术栈**。后端：包内 Node 后端（插件形态缺省，需 Node 22.19+）或 Python 标准库 + 4 个小依赖
+  （独立形态 / `backend: python`）；前端：React + Vite；存储：SQLite + 普通文件。Linux 与 Windows 均可运行。
 
 ## 界面截图
 
@@ -123,8 +124,8 @@ flowchart LR
 
 | 依赖 | 版本 | 用途 |
 |------|------|------|
-| Python | 3.12+ | 运行站点（实测 3.12） |
-| Node.js | 22.19+ 或 24+ | 运行 `dsh` 宿主（仅构建前端时 Node 18+ 即可） |
+| Node.js | 22.19+ 或 24+ | 运行 `dsh` 宿主**与插件形态的后端**（缺省；仅构建前端时 Node 18+ 即可） |
+| Python | 3.12+ | 独立形态（`./touchstone.sh start`）与插件形态的 `backend: python`（实测 3.12） |
 | DeepSeek Harness（`dsh`） | 当前版本 | agent 执行——插件形态必需 |
 
 ### 1. 克隆并安装
@@ -132,7 +133,7 @@ flowchart LR
 ```bash
 git clone https://github.com/gavinc-cn/touchstone-dsh.git
 cd touchstone-dsh
-python3 -m pip install -r requirements.txt
+python3 -m pip install -r requirements.txt   # 独立形态 / 插件形态配了 backend: python 才需要
 ```
 
 ### 2. 启动站点（独立形态）
@@ -174,23 +175,27 @@ node ~/.dsh/profiles/web/node_modules/@gavinc-cn/touchstone-dsh/dsh-plugin/scrip
 # 4) 重启 dsh web，打开 http://127.0.0.1:3080，用侧栏里的 Touchstone 入口（Alt+T 开关面板）
 ```
 
-平台自身的 Python 依赖走 pip，npm 不管：
+**插件形态缺省不需要 Python。** 自 2026-10-15 起薄壳拉起的是包内 Node 后端（先探宿主 Node 的
+`node:sqlite`，过旧则给提示页并列出两条出路）。只有用 Python 后端时才需要 Python —— 即独立形态，
+或在插件 config 里显式写 `backend: python`（观测期的一行回滚；**删掉该键不再有任何回退效果**，
+缺省就是 `node`）。走 Python 后端时，平台自身的依赖走 pip，npm 不管：
 
 ```bash
 pip install -r ~/.dsh/profiles/web/node_modules/@gavinc-cn/touchstone-dsh/requirements.txt
 # Windows 用 python -m pip install ...（官方安装器只装 python.exe，没有 python3）
 ```
 
-解释器不用配也行：插件自己探——先试 `python`、再试 `python3`（与 `touchstone.cmd` 同序），
-用第一个真能跑起来的那个。如果探到的不是你装依赖的那支，缺依赖提示页里给的就是**它探到的那支**
+配了 Python 后端且未指定解释器时，插件自己探——先试 `python`、再试 `python3`（与 `touchstone.cmd`
+同序），用第一个真能跑起来的那个。如果探到的不是你装依赖的那支，缺依赖提示页里给的就是**它探到的那支**
 的解释器命令；想指定别支，在 profile patch 里写 `pythonPath`：
 
 ```yaml
 - id: touchstone-dsh
-  config: { pythonPath: /path/to/python }
+  config: { backend: python, pythonPath: /path/to/python }
 ```
 
-**不需要配 `repoDir`**：包里带着 `server.py` 与 `webui/dist-plugin`，插件缺省就用包自身目录。
+**不需要配 `repoDir`**：包里带着 `server.py`、`backend/`（Node 后端）与 `webui/dist-plugin`，
+插件缺省就用包自身目录。
 
 **方式 B —— 从检出安装（开发用）:**
 

package/backend/lib/access.js

@@ -0,0 +1,44 @@
+/**
+ * 请求访问门禁（`server.py` 里挂在 Handler 上的那几道**纯判据**，M4.5）。
+ *
+ * 为什么单独一个文件：`server.js` 是入口脚本——模块顶层就 `await main()`（进程契约要求
+ * 「被 import 即启动」不成立，而 Node 22.19 没有 `import.meta.main`，用它做守卫会在旧版
+ * 上静默不启动）。因此门禁判据留在 `server.js` 里就**不可被单测 import**，只能靠实例级
+ * 对拍覆盖。抽成纯函数（零 IO、零 import）后，`backend/test/write-base.test.mjs` 能逐条
+ * 钉死边界，而 `server.js` 只负责「在正确的时机调它」。
+ *
+ * 与 Python 的对齐点（`server.py`）：
+ *   - `MUST_CHANGE_PW_ALLOW`(487)：白名单三端点；
+ *   - `_must_change_pw_blocked`(5203)：`must_change_pw` 为假 ⇒ 放行；信任头 ⇒ 放行；
+ *     在白名单里 ⇒ 放行；否则 403 `{"error":"请先修改初始口令"}`；
+ *   - **`do_GET`(1023) 与 `do_POST`(1040) 都调它**，且都在各自的 `if path.startswith("/api/")`
+ *     之内；`do_PATCH`(1227) / `do_DELETE`(1266) 没有这道闸。
+ *     ⚠ 2026-10-14 订正：本文件此前写的是「只有 `do_POST`(1040) 调它」，**与源码不符**——
+ *     `server.js` 曾照这句错注释实现，于是持一次性口令的账号在 Node 侧能 GET 全部 `/api/*`
+ *     读端点（oracle 一律 403）。M7-R3 车道用隔离实例真跑 `server.py` 量出来的。
+ */
+
+/** 强制改密闸白名单（`server.py:MUST_CHANGE_PW_ALLOW`）：持一次性口令的账号只能走这三个端点 */
+export const MUST_CHANGE_PW_ALLOW = Object.freeze([
+  '/api/auth/me', '/api/auth/change_password', '/api/auth/logout',
+]);
+
+/**
+ * `server.py:_must_change_pw_blocked` 的纯判据。
+ *
+ * 返回 `true` = 调用方应回 **403 紧凑体** `{"error":"请先修改初始口令"}`。
+ *
+ * `user` 为空（未登录）不算「被闸挡住」——那种情况该走 401，且 Python 里
+ * `if not user or not user["must_change_pw"]: return False` 也是放行（401 由更早的检查发）。
+ *
+ * @param {object|null|undefined} user 当前用户行（`must_change_pw` 为 0/1 或布尔）
+ * @param {string} path 不含查询串的请求路径
+ * @param {{trusted?: boolean}} [options] `trusted` = 反代注入免登信任头（`_trusted_admin_request`）
+ * @returns {boolean}
+ */
+export function mustChangePwBlocked(user, path, { trusted = false } = {}) {
+  if (!user || !user.must_change_pw) return false;
+  if (trusted) return false;
+  if (MUST_CHANGE_PW_ALLOW.includes(path)) return false;
+  return true;
+}

package/backend/lib/agents.js

@@ -0,0 +1,341 @@
+/**
+ * `agents.py` 的 Node 对应物（M3 交付归族读口；M6-2 补齐扫描口）。
+ *
+ * M3（读路径）里几乎所有端点都要按项目的 `agent_path` 归族（`_api_get_board` 下发
+ * family/capabilities、`_api_board_session_messages` 归一 sessparse 解析族、
+ * `board.web_busy_map` 判「是不是 dsh 族」…），而归族判据是纯字符串规则、零 IO，故先落。
+ * M6-2 把模块的另一大半（`scan_agents` / `scan_skills` / `_probe_version` /
+ * `_search_extra` / `_parse_skill_md` / `_scan_skill_dir` 与四张常量表）按 `agents.py` 补齐。
+ *
+ * 归族返回值与 Python 逐字一致（`"dsh_plugin"` / `"retired"`），判据见 `agents.py:134-162`：
+ *   ① `dsh-plugin:` 前缀（必须先于 basename 判——它不是有效可执行路径）；
+ *   ② `kimi-web:` / `opencode-web:` 两个旧虚拟前缀；
+ *   ③ basename 含 kimi/opencode/claude/hermes/deepseek 的旧 CLI 族；
+ *   ④ basename == `dsh`（裸 dsh CLI，`--profile headless` 形态已退场）；
+ *   ⑤ **其余一律 `dsh_plugin`**（空 `agent_path` 与未知可执行名的默认族）。
+ *
+ * 第 ⑤ 条是最容易写反的一条：默认族不是「未知就报错」，而是「收敛到唯一产品入口」。
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+/** dsh 插件驱动前缀（`agents.py:DSH_PLUGIN_PREFIX`）：后跟任意提示串，平台不使用 */
+export const DSH_PLUGIN_PREFIX = 'dsh-plugin:';
+
+/** 退场族标记（`agents.py:RETIRED_FAMILY`）：起跑处据此返回 `RETIRED_MSG` */
+export const RETIRED_FAMILY = 'retired';
+
+/** 退场族提示文案（`agents.py:RETIRED_MSG`，逐字照抄——它直接展示给用户） */
+export const RETIRED_MSG = '该智能体族已下线，请在项目设置里改绑 dsh 插件';
+
+/** 「插件·进程内」条目展示名（`agents.py:PLUGIN_ENTRY_NAME`，M6 的 scan 会用） */
+export const PLUGIN_ENTRY_NAME = 'dsh（插件·进程内）';
+
+/** 退场族的旧虚拟条目前缀（`agents.py:LEGACY_WEB_PREFIXES`） */
+export const LEGACY_WEB_PREFIXES = ['kimi-web:', 'opencode-web:'];
+
+/** 旧 CLI 族可执行名关键词（`agents.py:152` 的判定同源） */
+const RETIRED_NAME_HINTS = ['kimi', 'opencode', 'claude', 'hermes', 'deepseek'];
+
+/**
+ * 归族：只可能返回 `"dsh_plugin"`（可跑）或 `RETIRED_FAMILY`（退场族）。
+ *
+ * Python 用 `ap.strip()` 后判前缀、再用 `os.path.basename(ap).lower()` 判名字；
+ * Node 侧 `path.basename` 在 POSIX 上等价（Windows 反斜杠路径在 Linux 版上本来就
+ * 不是有效路径，与 Python 同——两版都跑在同一个平台上，不比跨平台行为）。
+ */
+export function agentFamily(agentPath) {
+  const ap = String(agentPath ?? '').trim();
+  if (ap.startsWith(DSH_PLUGIN_PREFIX)) return 'dsh_plugin';
+  if (LEGACY_WEB_PREFIXES.some((prefix) => ap.startsWith(prefix))) return RETIRED_FAMILY;
+  const name = path.basename(ap).toLowerCase();
+  if (RETIRED_NAME_HINTS.some((hint) => name.includes(hint))) return RETIRED_FAMILY;
+  if (name === 'dsh') return RETIRED_FAMILY;     // 裸 dsh CLI（headless 形态）已退场
+  return 'dsh_plugin';                           // 空串/未知名的默认族（见文件头 ⑤）
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// M6-2：扫描口（`agents.py:45-247`）
+//
+// 与 Python 的形态差异（两条，都是「Node 没有 stdlib 对应物」）：
+//   ① `shutil.which` → 本地 `whichSync`：POSIX 语义（名字含 `/` 直接判，否则遍历 `PATH`
+//      各段取第一个「文件且可执行」者）。Windows 的 PATHEXT 分支不在本轮范围（本机 POSIX）。
+//   ② `glob.glob` → 本地 `globDirs`：只支持本文件用到的那一种模式（`<base>/*/<suffix>`，
+//      单个 `*` 整段通配），按 `sorted()` 返回——与 `sorted(glob.glob(pat))` 同序。
+// 另注：`_probe_version` 的 `text[0][:120]` 在 Python 按**码点**切，这里用 `[...str]` 同口径
+// （`String.prototype.slice` 会切在 UTF-16 码元上）。
+// ══════════════════════════════════════════════════════════════════════════
+
+/** 支持的 agent 清单（`agents.py:AGENT_DEFS`；展示名仅作文档，实际用于定位 dsh 可执行） */
+export const AGENT_DEFS = [['dsh（DeepSeek Harness）', ['dsh']]];
+
+/** PATH 之外常见的安装目录（`agents.py:EXTRA_DIRS`，顺序即查找顺序） */
+export const EXTRA_DIRS = [
+  '/usr/local/bin',
+  path.join(os.homedir(), '.local/bin'),
+  '/bin/versions/node',
+  path.join(os.homedir(), '.npm-global/bin'),
+];
+if (process.platform === 'win32' && process.env.APPDATA) {
+  EXTRA_DIRS.push(path.join(process.env.APPDATA, 'npm'));
+}
+
+/** 递归进 versions 下各 node 版本的 bin/（`agents.py:VERSIONS_BIN_GLOB`） */
+export const VERSIONS_BIN_GLOB = '/bin/versions/node';
+
+/** conda/mamba 各虚拟环境的 bin 目录（`agents.py:CONDA_ENV_BIN_GLOBS`，glob 模式） */
+export const CONDA_ENV_BIN_GLOBS = [
+  '/opt/miniconda3/envs/*/bin',
+  '/opt/anaconda3/envs/*/bin',
+  path.join(os.homedir(), 'miniconda3/envs/*/bin'),
+  path.join(os.homedir(), 'anaconda3/envs/*/bin'),
+];
+
+/** skill 目录约定（`agents.py:SKILL_DIRS_BY_FAMILY`）：族 → [用户级元组, 项目级元组] */
+export const SKILL_DIRS_BY_FAMILY = {
+  dsh_plugin: [['~/.dsh/skills', '~/.agents/skills'], ['.dsh/skills', '.agents/skills']],
+};
+
+/** SKILL.md 相对扫描根的最大目录深度（`agents.py:SKILL_WALK_MAX_DEPTH`） */
+export const SKILL_WALK_MAX_DEPTH = 2;
+
+/** `_SKILL_FRONT_RE`：`\A---\s*\n(.*?)\n---`（DOTALL） */
+const SKILL_FRONT_RE = /^---\s*\n([\s\S]*?)\n---/;
+/** `_SKILL_NAME_RE` / `_SKILL_DESC_RE`：多行模式下 `^name:` / `^description:`（行首锚定） */
+const SKILL_NAME_RE = /^name:[ \t]*(.+)$/m;
+const SKILL_DESC_RE = /^description:[ \t]*(.+)$/m;
+
+/** description 截断长度（`agents.py:_SKILL_DESC_LIMIT`） */
+export const SKILL_DESC_LIMIT = 200;
+
+/** 文本拆行（照 Python `str.splitlines()` 的边界集合） */
+function splitLines(text) {
+  return String(text ?? '').split(/\r\n|\r|\n|\u2028|\u2029/);
+}
+
+/** 文件是否「存在且可执行」（Python `os.path.isfile(p) and os.access(p, os.X_OK)`） */
+function isExecutableFile(p) {
+  try {
+    const st = fs.statSync(p);
+    if (!st.isFile()) return false;
+    fs.accessSync(p, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** `os.path.isdir`（不存在/权限不足一律 false） */
+function isDir(p) {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** `os.path.expanduser('~/x')`：只处理开头的 `~`（POSIX 下用 HOME） */
+function expandUser(p) {
+  const s = String(p ?? '');
+  if (s === '~') return os.homedir();
+  if (s.startsWith('~/')) return path.join(os.homedir(), s.slice(2));
+  return s;
+}
+
+/** `shutil.which` 的 POSIX 子集（见文件头差异①） */
+export function whichSync(name) {
+  const n = String(name ?? '');
+  if (!n) return null;
+  if (n.includes('/')) return isExecutableFile(n) ? n : null;
+  for (const dir of String(process.env.PATH ?? '').split(path.delimiter)) {
+    if (!dir) continue;
+    const candidate = path.join(dir, n);
+    if (isExecutableFile(candidate)) return candidate;
+  }
+  return null;
+}
+
+/** `glob.glob` 的单 `*` 整段通配子集（见文件头差异②），返回 `sorted()` 序 */
+function globDirs(pattern) {
+  const star = pattern.indexOf('*');
+  if (star < 0) return [pattern];
+  const base = pattern.slice(0, pattern.lastIndexOf('/', star));
+  const rest = pattern.slice(pattern.indexOf('/', star));
+  let names;
+  try {
+    names = fs.readdirSync(base);
+  } catch {
+    return [];
+  }
+  return names.slice().sort().map((n) => `${base}/${n}${rest}`);
+}
+
+/**
+ * `agents._search_extra`：在扩展目录中查找 name 可执行文件，返回路径或 null。
+ *
+ * 命中判据是「文件 + 可执行位」（`agents.py:82/88`）；`VERSIONS_BIN_GLOB` 那一项要**再下钻
+ * 一层**到 `<d>/<版本>/bin/<name>`；conda 那组是 glob 展开后逐个匹配。
+ */
+export function searchExtra(name) {
+  const candidates = [];
+  for (const d of EXTRA_DIRS) {
+    if (!isDir(d)) continue;
+    if (d === VERSIONS_BIN_GLOB) {
+      let versions;
+      try {
+        versions = fs.readdirSync(d);
+      } catch {
+        versions = [];
+      }
+      for (const ver of versions) candidates.push(path.join(d, ver, 'bin', name));
+    } else {
+      candidates.push(path.join(d, name));
+    }
+  }
+  for (const p of candidates) {
+    if (isExecutableFile(p)) return p;
+  }
+  for (const pat of CONDA_ENV_BIN_GLOBS) {
+    for (const bindir of globDirs(pat)) {
+      const p = path.join(bindir, name);
+      if (isExecutableFile(p)) return p;
+    }
+  }
+  return null;
+}
+
+/**
+ * `agents._probe_version`：跑 `--version`（2s 超时），失败返回空串。
+ *
+ * Python 的 `except (OSError, TimeoutExpired)` 对应 Node 的 `error`（ENOENT/EACCES）与
+ * 「被信号杀死」（spawnSync 超时 ⇒ `status === null`）；**非 0 退出不算失败**
+ * （Python `subprocess.run` 同样不抛），照旧读它写出来的 stdout/stderr，
+ * 取首行（`splitlines()` 口径）并按码点截 120。
+ */
+export function probeVersion(exePath) {
+  const p = spawnSync(exePath, ['--version'], {
+    encoding: 'utf8',
+    timeout: 2000,
+    cwd: os.tmpdir(),
+    maxBuffer: 4 * 1024 * 1024,
+  });
+  if (p.error || p.status === null) return '';
+  const text = splitLines(String(p.stdout || p.stderr || '').trim());
+  return text.length ? [...text[0]].slice(0, 120).join('') : '';
+}
+
+/**
+ * `agents.scan_agents`：扫描本机 dsh 可执行，返回**产品入口单条目**（恒 1 条）。
+ *
+ * 未找到时同样返回一条 `found=false`（前端显示「未找到」），保持「下拉里有且只有这一条」
+ * 的读侧不变量。**裸 dsh CLI 行不返回**（它属退场族，列出来是误选陷阱）。
+ */
+export function scanAgents() {
+  let found = '';
+  for (const [, bins] of AGENT_DEFS) {
+    for (const b of bins) {
+      found = whichSync(b) || searchExtra(b) || '';
+      if (found) break;
+    }
+    if (found) break;
+  }
+  return [{
+    name: PLUGIN_ENTRY_NAME,
+    path: found ? DSH_PLUGIN_PREFIX + found : '',
+    version: found ? probeVersion(found) : '',
+    found: Boolean(found),
+  }];
+}
+
+/**
+ * `agents._parse_skill_md`：解析 SKILL.md 的 frontmatter，返回 `[name, description]`。
+ *
+ * 只读前 **4096 字节**（照 `f.read(4096)`，按 UTF-8 解码后的字符数）；读失败返回 null。
+ * name 缺省用所在目录名；description 缺省空串并截断到 200（Python `[:200]` 按码点）。
+ */
+export function parseSkillMd(filePath, fallbackName) {
+  let head;
+  try {
+    const fd = fs.openSync(filePath, 'r');
+    try {
+      const buf = Buffer.alloc(4096);
+      const read = fs.readSync(fd, buf, 0, 4096, 0);
+      head = new TextDecoder('utf-8').decode(buf.subarray(0, read));
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return null;
+  }
+  const m = SKILL_FRONT_RE.exec(head);
+  const body = m ? m[1] : head;               // 无 frontmatter 时退化为头部全文（容错）
+  const nm = SKILL_NAME_RE.exec(body);
+  const dm = SKILL_DESC_RE.exec(body);
+  const name = nm ? nm[1].trim() : fallbackName;
+  const desc = dm ? [...dm[1].trim()].slice(0, SKILL_DESC_LIMIT).join('') : '';
+  return [name, desc];
+}
+
+/**
+ * `agents._scan_skill_dir`：扫一个 skill 根（深度受限），返回 `[{name,description,source}]`。
+ *
+ * 深度按「相对根的目录层数」算：只在 `rel < SKILL_WALK_MAX_DEPTH` 时继续下钻，
+ * 故 `SKILL.md` 最深允许出现在第 2 层（`<类>/<名>/SKILL.md`）。命中目录先收自身再下钻，
+ * 与 `os.walk` 的自顶向下序一致。
+ */
+export function scanSkillDir(root, source) {
+  const skills = [];
+  const base = String(root ?? '').replace(/[/\\]+$/, '');
+  if (!base || !isDir(base)) return skills;
+  const baseDepth = base.split(path.sep).length - 1;
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    if (entries.some((e) => e.name === 'SKILL.md')) {
+      const parsed = parseSkillMd(path.join(dir, 'SKILL.md'),
+        path.basename(dir.replace(/[/\\]+$/, '')));
+      if (parsed) skills.push({ name: parsed[0], description: parsed[1], source });
+    }
+    const rel = dir.split(path.sep).length - 1 - baseDepth;
+    if (rel >= SKILL_WALK_MAX_DEPTH) return;
+    for (const ent of entries) {
+      if (ent.isDirectory()) walk(path.join(dir, ent.name));
+    }
+  };
+  walk(base);
+  return skills;
+}
+
+/**
+ * `agents.scan_skills`：列出 agent 可用的 skill（用户级 + 项目级），按 name 排序。
+ *
+ * 同名时项目级**覆盖**用户级；用户级内部先命中者保留（`setdefault` 语义）；`agent_path`
+ * 为空返回空列表；无目录约定的族返回空。
+ */
+export function scanSkills(agentPath, projectDir = '') {
+  const ap = String(agentPath ?? '').trim();
+  if (!ap) return [];
+  const family = agentFamily(ap);
+  const [userDirs, projDirs] = SKILL_DIRS_BY_FAMILY[family] || [[], []];
+  const found = new Map();
+  for (const d of userDirs) {
+    for (const s of scanSkillDir(expandUser(d), 'user')) {
+      if (!found.has(s.name)) found.set(s.name, s);
+    }
+  }
+  const pd = String(projectDir ?? '').trim();
+  if (pd) {
+    for (const d of projDirs) {
+      for (const s of scanSkillDir(path.join(pd, d), 'project')) {
+        found.set(s.name, s);           // 项目级覆盖用户级
+      }
+    }
+  }
+  return [...found.values()].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}

package/backend/lib/args.js

@@ -0,0 +1,94 @@
+/**
+ * Node 后端命令行契约解析（backend/server.js 的入口参数）。
+ *
+ * 为什么单独一个模块：薄壳（dsh-plugin/lib/index.js）用**同一份 argv** 拉起 Python 与 Node
+ * 两个后端（方案 §3.2），这份 argv 就是两版之间的接口；把它抽出来单独测，才能在不起进程的
+ * 情况下钉死「默认值与 Python 侧 argparse 逐项一致」。
+ *
+ * 与 Python 侧的对应关系（server.py:_build_arg_parser，2026-10-11 复核）：
+ *   --host        缺省 127.0.0.1（安全默认：仅本机）
+ *   --port        缺省 4601（薄壳恒传 0 = 随机端口）
+ *   --web-dir     缺省 `<仓库根>/webui/dist`，可被 TS_WEB_DIR 覆盖
+ *   --trust-internal-user / --parent-watch  布尔开关
+ *   --allow-shared-db  同库单实例闸的逃生口（M1 起解析：语义已由 backend/lib/lock.js 落地，
+ *                      见 server.js 的取锁段；M0 曾**故意不解析**它——解析一个语义未实现的
+ *                      开关等于静默说谎，现在实现到位，这个理由不再成立）
+ */
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+
+/**
+ * 仓库根 = 本文件上溯三级（<根>/backend/lib/args.js）。
+ * 静态页缺省目录由它派生，与 Python 侧 `BASE_DIR/webui/dist` 同口径。
+ */
+export const REPO_ROOT = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+
+/** 与 Python argparse 对齐的缺省监听地址与端口 */
+export const DEFAULT_HOST = '127.0.0.1';
+export const DEFAULT_PORT = 4601;
+
+/** 把 node:util parseArgs 的英文错误码翻成可操作的中文提示（终端里直接能看懂） */
+function describeParseError(error) {
+  const code = error && error.code;
+  if (code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION') {
+    return new Error(`未知参数: ${error.message.replace(/^Unknown option\s*/, '')}`);
+  }
+  if (code === 'ERR_PARSE_ARGS_INVALID_OPTION_VALUE') {
+    return new Error(`参数缺少取值: ${error.message}`);
+  }
+  return new Error(`参数错误: ${(error && error.message) || error}`);
+}
+
+/**
+ * 解析入口 argv（不含 node 可执行文件与脚本路径）。
+ * 非法输入一律抛错：这个进程由薄壳拉起，静默兜底只会把「参数写错」变成「后端行为诡异」。
+ */
+export function parseBackendArgs(argv = process.argv.slice(2)) {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      strict: true,
+      allowPositionals: false,
+      options: {
+        host: { type: 'string' },
+        port: { type: 'string' },
+        'web-dir': { type: 'string' },
+        'trust-internal-user': { type: 'boolean' },
+        'parent-watch': { type: 'boolean' },
+        'allow-shared-db': { type: 'boolean' },
+      },
+    });
+  } catch (error) {
+    throw describeParseError(error);
+  }
+  const values = parsed.values;
+  let port = DEFAULT_PORT;
+  if (values.port !== undefined) {
+    // parseArgs 没有数字类型，端口在这里显式校验（`abc` / `1.5` / 负数都要挡在启动之前）
+    if (!/^\d+$/.test(values.port)) throw new Error(`端口必须是整数: ${values.port}`);
+    port = Number(values.port);
+    if (port > 65535) throw new Error(`端口越界(0-65535): ${values.port}`);
+  }
+  return {
+    host: values.host === undefined ? DEFAULT_HOST : values.host,
+    port,
+    webDir: values['web-dir'] === undefined ? null : values['web-dir'],
+    trustInternalUser: values['trust-internal-user'] === true,
+    parentWatch: values['parent-watch'] === true,
+    // 与 Python 的 `--allow-shared-db`（action="store_true"）同语义：缺省 false
+    allowSharedDb: values['allow-shared-db'] === true,
+  };
+}
+
+/**
+ * 静态页目录解析：显式 --web-dir > 环境变量 TS_WEB_DIR > `<仓库根>/webui/dist`。
+ * 优先级与 Python 侧一致（`WEB_DIR = os.environ.get("TS_WEB_DIR") or BASE_DIR/webui/dist`，
+ * 显式参数在 main() 里覆盖它）。
+ */
+export function resolveWebDir(args, { env = process.env, repoRoot = REPO_ROOT } = {}) {
+  if (args && args.webDir) return args.webDir;
+  if (env && env.TS_WEB_DIR) return env.TS_WEB_DIR;
+  return join(repoRoot, 'webui', 'dist');
+}