@gavinc-cn/touchstone-dsh 0.2.0 → 0.4.0

package/backend/lib/seed_hint.js

@@ -0,0 +1,40 @@
+/**
+ * 启动横幅的默认账号提示（`server.py:5457-5472 _seed_hint` 的对应物，2026-10-16 补）。
+ *
+ * ── 三档与 `db.js:seedAdmin()` 的口令来源一一对应（逐条对齐 Python） ──────────────
+ *   ① 随机一次性口令（`seedPassword` 非空）→ 打印口令本身 + 首登须改密（读后即清）
+ *   ② `TS_ADMIN_PASSWORD` 非空          → 只指向变量名，**绝不回显口令值**
+ *   ③ 都没有（`TS_ADMIN_PASSWORDLESS=1`，插件形态）→ 空口令，提示可在设置页设密码
+ *
+ * ── 为什么单列第 ③ 档（2026-10-16 修） ────────────────────────────────────────
+ * 第 ③ 档此前**落进第 ② 档的文案**：插件形态（薄壳默认下发 `TS_ADMIN_PASSWORDLESS=1`）
+ * 首启横幅写的是「初始口令取自 TS_ADMIN_PASSWORD」，可那个变量根本没设、账号实际是空口令
+ * ——首装排障按这句话去找变量会白找。Python 侧同一分支的旧文案是「其一次性口令已在上一次
+ * 启动时打印，本次不再显示」，同样对不上：该分支**结构上不可达**于「口令已被取走」——
+ * `seeded=false` 时 `_seed_hint` 直接返回空串，而 `seeded=true` 且 `initial_pw` 为空只可能
+ * 是空口令种子。两版现在给同一句、且逐字节相同（`tests/test_seed_admin.py` 与
+ * `test/seed-hint.test.mjs` 各钉一半）。
+ *
+ * 纯函数：不读全局、无副作用（`env` 由调用方传入）⇒ 与 Python 一样可函数级单测，
+ * 不必真起进程。
+ */
+
+/**
+ * 组装本次种子后的横幅片段。
+ * @param {{seeded?: boolean, seedPassword?: string, env?: NodeJS.ProcessEnv}} [boot]
+ *   `seeded`/`seedPassword` 取自 `initDb()` 的返回值；`env` 缺省 `process.env`
+ *   ——种子用的就是它，横幅判断与种子判断必须同源
+ * @returns {string} 本次实际种子时返回横幅片段（含前导两空格）；日常启动返回空串
+ */
+export function seedHint({ seeded = false, seedPassword = '', env = process.env } = {}) {
+  if (!seeded) return '';
+  if (seedPassword) {
+    return `  （首次启动已创建默认账号 admin，一次性初始口令：${seedPassword}`
+      + '，首次登录须修改；仅本次显示，请立即记录）';
+  }
+  if (env.TS_ADMIN_PASSWORD) {
+    return '  （首次启动已创建默认账号 admin，初始口令取自 TS_ADMIN_PASSWORD，请尽快登录修改）';
+  }
+  return '  （首次启动已创建默认账号 admin，空口令（插件形态免登）'
+    + '；如需口令登录请在设置页设置密码）';
+}

package/backend/lib/servercaps.js

@@ -0,0 +1,182 @@
+/**
+ * `server.py` 顶部那组「会话元信息派生」函数的 Node 对应物（M3 读路径）：
+ * 能力声明、会话解析族归一、默认模型、有效模型、权限档反查、会话归属三态。
+ *
+ * 为什么单独一个文件而不是塞进路由：看板族（`routes/board.js`）与会话族
+ * （`routes/sessions.js`）**都要**用它们（`_api_get_board` 下发 family/capabilities，
+ * `_session_payload` 下发 model/capabilities/owned…），而这两族由不同的人写。
+ * 放在 Lead 名下的小文件里，两边都 import 同一份，不会出现「两处各写一份 capability 表」。
+ *
+ * 白名单常量（权限档/思考等级/反查表）**复用 `dshdriver.js` 的导出**，不另抄一份：
+ * Python 侧同样是 `DSH_PERMISSION_PRESETS = dshdriver.PERMISSION_PRESETS` 的别名。
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+
+import * as dbmod from './db.js';
+import * as dshevents from './dshevents.js';
+import * as dshdriver from './dshdriver.js';
+
+/** 思考等级白名单（`dshdriver.EFFORT_LEVELS`，与 Python 同源） */
+export const DSH_EFFORT_LEVELS = dshdriver.EFFORT_LEVELS;
+/** 平台三档 → 宿主 preset（`server.py:84`） */
+export const DSH_PERMISSION_PRESETS = dshdriver.PERMISSION_PRESETS;
+/** 宿主 preset → 平台三档近似反查（`server.py:88`） */
+export const DSH_PRESET_MODES = dshdriver.PRESET_MODES;
+
+/** `~/.dsh/settings.yaml` 的 agent-default-model 段：provider 行后的 model 行 */
+const DSH_DEFAULT_MODEL_RE =
+  /^agent-default-model:[ \t]*$\n^[ \t]+provider:[ \t]*\S+[ \t]*$\n^[ \t]+model:[ \t]*([^\n#]+)/m;
+
+/**
+ * Python `value or ""`：**按 Python 真值**判空（`0` / `False` / `''` / 空容器 → `""`）。
+ *
+ * 别写成 `String(value ?? '')`：那会把 `0` 归一成 `"0"`、把 `{}` 归一成 `"[object Object]"`
+ * ——`normalize_*` 的下一步是白名单检查，`"0"` 不在白名单 ⇒ 白白把一个「不指定」判成 400。
+ * （M5-4 实装 `POST /board/sessions/<sid>/profile` 时核出：Python 侧两个 normalize 都是
+ * `str(value or "")`，Node 侧原写法在 `0/False/{}` 三种入参上有分歧。）
+ */
+function pyOrEmpty(value) {
+  if (value === null || value === undefined || value === false || value === 0) return '';
+  if (typeof value === 'string') return value;
+  if (Array.isArray(value)) return value.length ? value : '';
+  if (typeof value === 'object') return Object.keys(value).length ? value : '';
+  return value;                          // 数字（含 NaN，Python 里为真）/ true
+}
+
+/**
+ * `normalize_effort`：''=不指定；白名单内原样；**非法返回 null**（调用方报 400，不静默丢弃）。
+ * 返回 `null` 与返回 `''` 语义不同，别用 `|| ''` 抹平。
+ */
+export function normalizeEffort(value) {
+  const v = String(pyOrEmpty(value)).trim();
+  if (!v) return '';
+  return DSH_EFFORT_LEVELS.includes(v) ? v : null;
+}
+
+/** `normalize_permission_mode`：''=不指定；manual/yolo/auto 原样；非法返回 null */
+export function normalizePermissionMode(value) {
+  const v = String(pyOrEmpty(value)).trim();
+  if (!v) return '';
+  return Object.prototype.hasOwnProperty.call(DSH_PERMISSION_PRESETS, v) ? v : null;
+}
+
+/** `_dsh_default_model`：读 `~/.dsh/settings.yaml` 的默认模型，任何失败返回 ''（不抛） */
+export function dshDefaultModel() {
+  try {
+    const conf = `${os.homedir()}/.dsh/settings.yaml`;
+    if (fs.existsSync(conf)) {
+      const m = DSH_DEFAULT_MODEL_RE.exec(fs.readFileSync(conf, 'utf8'));
+      if (m && m[1].trim()) return m[1].trim().replace(/^["']|["']$/g, '');
+    }
+  } catch {
+    // 读不到/解析不了都按「无法判定」——与 Python 的 try/except pass 同口径
+  }
+  return '';
+}
+
+/**
+ * `effective_model`：任务实际使用的模型名。
+ * ① 任务显式指定；② 首轮日志 `### CMD ` 行里的 `-m/--model`（存量 CLI 轮次日志）；
+ * ③ dsh 部署默认模型。返回 '' = 完全无法判定（前端显示「默认」回退文案）。
+ *
+ * 注意 Python 的两处 `break`：**只看第一条有 log_path 且文件存在的轮次**，且该文件里
+ * 只看第一个 `### CMD ` 行（避免多次读文件）——这里逐点照抄，包括「文件不存在就跳到下一条」。
+ */
+export function effectiveModel(taskId, model, { db } = {}) {
+  const explicit = String(model ?? '').trim();
+  if (explicit) return explicit;
+  try {
+    for (const round of dbmod.listRounds(taskId, { db })) {
+      const logPath = round.log_path;
+      if (!logPath || !fs.existsSync(logPath) || !fs.statSync(logPath).isFile()) continue;
+      const text = fs.readFileSync(logPath, 'utf8');
+      for (const line of text.split('\n')) {
+        if (line.startsWith('### CMD ')) {
+          const m = /(?:-m|--model)\s+(\S+)/.exec(line);
+          if (m) return m[1];
+          break;                                  // 首个 CMD 行没带模型：不再往下找
+        }
+      }
+      break;                                      // 只看第一条可读轮次（与 Python 同）
+    }
+  } catch {
+    // 日志读失败不阻断展示（Python 同为 except Exception: pass）
+  }
+  return dshDefaultModel();
+}
+
+/** `_sess_family`：dsh_plugin 的会话就是 dsh 宿主的会话，按 `dsh` 解析族读取 */
+export function sessFamily(family) {
+  return family === 'dsh_plugin' ? 'dsh' : family;
+}
+
+/** `family_capabilities`：会话窗口能力声明（dsh_plugin 全开；退场族全 False） */
+export function familyCapabilities(family) {
+  if (family === 'dsh_plugin') {
+    return {
+      stream: true, chat: true, queue: true, steer: true, abort: true,
+      compact: true, fork: true, rewind: true, profile: true, permission: true,
+      events: true,
+    };
+  }
+  return {
+    stream: false, chat: false, queue: false, steer: false, abort: false,
+    compact: false, fork: false, rewind: false, profile: false, permission: false,
+    events: false,
+  };
+}
+
+/**
+ * `_session_permission_mode`：会话级权限档。
+ * ① 平台记下的 `mode`（唯一能区分 yolo/auto 的来源）；② 反查宿主 `preset`（老插件/外部改过）。
+ * 两者都无 → `''`（调用方**不下发** `permission`，前端保持置灰：不猜）。
+ */
+export function sessionPermissionMode(state) {
+  const perm = (state || {}).permission || {};
+  const mode = String(perm.mode || '');
+  if (mode) return mode;
+  return DSH_PRESET_MODES[String(perm.preset || '')] || '';
+}
+
+/**
+ * `_session_owned`：会话归属**三态**。
+ * - `true`  = 平台自持（驱动池内）；
+ * - `false` = 外部会话（用户在 dsh GUI 直跑/接管，平台停不了 ⇒ 前端置灰「停止」）；
+ * - `null`  = 注册表未知（未连接/热对齐中/没见过该 sid）⇒ 前端按「池内」渲染。
+ *
+ * 为什么不是 `Boolean(...)`：外部会话上报的也是 `false`，与「未知」的兜底值撞车，
+ * 会把断连窗口里的池内会话误判成外部（误出提示条 + 误停用停止按钮）。**未知 ≠ 外部**。
+ */
+export function sessionOwned(sid) {
+  const st = dshevents.get(sid);
+  if (st === null || st === undefined || !dshevents.aligned()) return null;
+  return Boolean(st.owned);
+}
+
+/**
+ * `_dsh_live_sid`：dsh 插件族「运行中会话」精确探测（零 mtime 启发式）。
+ * 判据＝驱动池自持（owned）+ cwd 匹配 + 最近创建；驱动不可用返回 ''（交调用方兜底）。
+ *
+ * **形态差异（有意）**：Node 的 `dshdriver.live()` 是 async（M2 的调用约定：
+ * 毫秒 + opts 对象 + async），故本函数也是 async；Python 侧是同步函数。
+ * 调用方（`_session_payload` 的 Node 对应物）本来就是 async，多一个 await 无碍。
+ */
+export async function dshLiveSid(cwd) {
+  let rows;
+  try {
+    rows = await dshdriver.live();
+  } catch {
+    return '';
+  }
+  const want = String(cwd || '').replace(/\/+$/, '');
+  let best = '';
+  let bestTs = -1;
+  for (const row of rows || []) {
+    if (!row.owned) continue;
+    if (want && String(row.cwd || '').replace(/\/+$/, '') !== want) continue;
+    const ts = Number.parseInt(row.started_at, 10) || 0;
+    if (ts > bestTs) { best = row.session_id || ''; bestTs = ts; }
+  }
+  return best;
+}

package/backend/lib/serverstate.js

@@ -0,0 +1,227 @@
+/**
+ * `server.py` 顶层「会话/队列派生」helper 的 Node 对应物（M3 读路径 · 会话族）。
+ *
+ * 归属函数（Python 源在括号里）：
+ *   - `projectBusy`           （`_project_busy`:319）
+ *   - `unitState`             （`_unit_state`:336，含 `c:` → `a:` 改键规则）
+ *   - `boardSessionRunning`   （`_board_session_running`:368）
+ *   - `sessionQueueState`     （`_session_queue_state`:428，八枚举判定序）
+ *   - `boardOwnsSid`          （`_board_owns_sid`:2765）
+ *   - `boardOwned`            （`_board_owned`:2748 的只读版）
+ *   - `taskSince`             （`_task_since`:4747）
+ *
+ * 命名口径：**函数 camelCase、返回字段沿用 Python 的 snake_case**（字段直接进 JSON
+ * 响应，改名就是改契约）。`{state,pos,total}` / `{pending,kind,…}` 这类形状逐字同 Python。
+ *
+ * ## M3 的边界（方案 §四，逐条在这里落地并注明）
+ * ① `board.runningMap()` / `chat.state` 的进程内登记表在 M3 恒空 ⇒ `boardSessionRunning`
+ *    的「平台在管」分支恒 false（与「刚起的 Python 实例」等价），实况 busy 分支照常走
+ *    `dshevents`；真驱动下的非空分支由 M4/M5 接线后自然生效。
+ * ② 原先这里还有一个 `interactionOfSid` 占位（「调和器缓存属 M5 ⇒ 恒 null」）——M5 已把
+ *    调和器搬进 `board.js`，该占位成了**同名的错误实现**：路由误 import 它 ⇒ Node 后端下
+ *    会话窗永远拿不到待答提问/审批（用户报障卡 980）。2026-10-16 删除，读口只用
+ *    `board.interactionOfSid`（缓存为空/无等待时自然为 null，键仍在 payload 里）。
+ *
+ * 数据层调用口径：M3 约定「自由函数 + 末位可选 `{db, dbPath, env}`」，本文件一律把
+ * `options` 原样透传给 `runner`/`board`/`db` 的读口（路由层传 `{db: ctx.db}`）。
+ */
+import * as board from './board.js';
+import * as dbmod from './db.js';
+import * as runner from './runner.js';
+
+/** Python `int(s)` 的**严格**形态（`s` 是数字串才给值，其余 null） */
+function pyIntOrNull(text) {
+  return /^[+-]?\d+$/.test(String(text)) ? Number.parseInt(text, 10) : null;
+}
+
+/**
+ * `_project_busy(project_id)`：项目是否已有单元在跑（统一队列视角）。
+ *
+ * Python 在 `runner.INSTANCE is None`（单测/独立脚本）或异常时按 False；Node 侧
+ * `runner.unitBusy` 是自由函数（总是可读 wait_items），**没有「实例缺位」这一态**，
+ * 但对假值 projectId 与异常同样返回 False（调用方不因展示字段失败）。
+ *
+ * @param {number} projectId
+ * @param {{db?: object, dbPath?: string, env?: NodeJS.ProcessEnv}} [options]
+ * @returns {boolean}
+ */
+export function projectBusy(projectId, options = {}) {
+  if (!projectId) return false;
+  try {
+    return Boolean(runner.unitBusy(projectId, options));
+  } catch (error) {
+    console.error(`[serverstate] projectBusy 降级为 false：${(error && error.message) || error}`);
+    return false;
+  }
+}
+
+/**
+ * `_unit_state(project_id, key)`：单元在统一队列中的态（会话窗「队列」徽标）。
+ *
+ * 任务会话传 `t:<task_id>`、看板卡片会话传 `c:<card_id>`；
+ * **已作答·待送达的卡片改按 `a:<cid>` 键求值**（P6 解冻：answer 等待项才有真实
+ * 位次；形状 `{state,pos,total}` 不变）。runner 异常 → `null`（前端按「未下发」不渲染）。
+ *
+ * 注意改键判定的位置与 Python 一致：`board.isAnswerPending` 的调用**不在** try 内
+ * （它自己有兜底），try 只包 `inst.unit_state`（Node：`runner.unitState`）。
+ *
+ * @param {number} projectId
+ * @param {string} key `t:<id>` / `c:<id>` / `a:<id>` / `m:<id>`
+ * @param {{db?: object, dbPath?: string, env?: NodeJS.ProcessEnv}} [options]
+ * @returns {{state:string,pos:number,total:number}|null}
+ */
+export function unitState(projectId, key, options = {}) {
+  if (!projectId) return null;
+  let resolved = String(key === null || key === undefined ? '' : key);
+  if (resolved.startsWith('c:')) {
+    const cid = pyIntOrNull(resolved.slice(2));
+    if (cid !== null && board.isAnswerPending(cid, options)) resolved = `a:${cid}`;
+  }
+  try {
+    return runner.unitState(resolved, projectId, options);
+  } catch (error) {
+    console.error(`[serverstate] unitState 降级为 null：${(error && error.message) || error}`);
+    return null;
+  }
+}
+
+/**
+ * `_board_session_running(owner_cid, proj, sid)`：看板会话运行态（meta.running）。
+ *
+ * 判定序与 Python 逐点同：无卡 → false；**已作答·待送达 → false**（平台已收下答案、
+ * 等空闲送达；会话实况仍 busy 但不算运行）；平台在管（`board.runningMap()`）→ true；
+ * 否则会话实况 busy（含用户在 dsh 侧直跑的外部会话）。
+ *
+ * @param {number} ownerCid
+ * @param {object} proj 项目行
+ * @param {string} sid
+ * @param {{db?: object, dbPath?: string, env?: NodeJS.ProcessEnv}} [options]
+ * @returns {boolean}
+ */
+export function boardSessionRunning(ownerCid, proj, sid, options = {}) {
+  if (!ownerCid) return false;
+  if (board.isAnswerPending(ownerCid, options)) return false;
+  // `board.runningMap()` 是 **plain object**（Python dict 的对应物，M3 恒空），不是 Map
+  const running = board.runningMap();
+  const key = String(ownerCid);
+  if (Object.prototype.hasOwnProperty.call(running, key) && running[key]) return true;
+  return board.webSessionBusy(proj, sid);
+}
+
+/**
+ * `_session_queue_state(...)`：session meta 的 `queue_state` 派生（八枚举，枚举值见
+ * `board.QS_*`）。
+ *
+ * 判定序（高→低）：`answer_pending` > `server_queued` > `interaction_pending` >
+ * `running` > `starting` > `queued_serial`/`foreign_busy` > `idle`。
+ * 三个「pending」仅看板卡片会话在场（任务会话恒 false）；`unit_state=running` 同样判
+ * running（**行口径**：本单元有运行中行）；`queued` 分叉按项目是否有活跃 `ext:` 行
+ * （外部会话在跑）分 `foreign_busy`/`queued_serial`。
+ *
+ * @param {number} projectId
+ * @param {{state:string,pos:number,total:number}|null|undefined} unitStateValue
+ * @param {{running?:boolean, answerPending?:boolean, serverQueued?:boolean,
+ *          starting?:boolean, interactionPending?:boolean}} [flags]
+ * @param {{db?: object, dbPath?: string, env?: NodeJS.ProcessEnv}} [options]
+ * @returns {string} `board.QS_*`
+ */
+export function sessionQueueState(projectId, unitStateValue, flags = {}, options = {}) {
+  const {
+    running = false, answerPending = false, serverQueued = false,
+    starting = false, interactionPending = false,
+  } = flags;
+  if (answerPending) return board.QS_ANSWER;
+  if (serverQueued) return board.QS_SERVER;
+  if (interactionPending) return board.QS_INTERACTION;
+  const st = (unitStateValue || {}).state;
+  if (running) return board.QS_RUNNING;
+  if (starting) return board.QS_STARTING;
+  if (st === 'running') return board.QS_RUNNING;
+  if (st === 'queued') {
+    if (projectId && board.extActive(projectId, options)) return board.QS_FOREIGN;
+    return board.QS_QUEUED;
+  }
+  return board.QS_IDLE;
+}
+
+/** `sessions` 列（JSON 数组文本）→ 字符串数组；坏 JSON 按空数组（Python 会抛，见文件头） */
+function cardSessions(row) {
+  try {
+    const parsed = JSON.parse(row.sessions || '[]');
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * `_board_owns_sid(row, sid)`：sid 是否归属本项目卡片的会话并集
+ * （每卡 `sessions ∪ {session_id}`）。返回**归属卡片行**（调用方可读
+ * `id`/`column_key`/`worktree`/`block_kind` 等）；不归属返回 `null`
+ * ——会话端点据此 404，防经会话端点读任意会话（跨项目读的红线）。
+ *
+ * @param {object} projectRow
+ * @param {string} sid
+ * @param {{db?: object, dbPath?: string, env?: NodeJS.ProcessEnv}} [options]
+ * @returns {object|null}
+ */
+export function boardOwnsSid(projectRow, sid, options = {}) {
+  if (!projectRow || !sid) return null;
+  for (const c of dbmod.listBoardCards(projectRow.id, options)) {
+    if (cardSessions(c).includes(sid)) return c;
+    if (c.session_id && sid === c.session_id) return c;
+  }
+  return null;
+}
+
+/**
+ * `_board_owned(project_id, card_id)` 的**只读版**：项目 + 卡片联合归属校验。
+ *
+ * 与 Python 的差异：Python 直接 `self._respond(404, …)`（有副作用），本函数只返回行，
+ * 由调用方决定回哪条 404——路由层已有 `ctx.ownedProject`（会回 `project not found`），
+ * 卡片缺失时调用方回 `card not found`，状态码/正文与 Python 一致。
+ *
+ * @param {number} projectId
+ * @param {number|null} [cardId] 不传＝只校验项目
+ * @param {{db?: object, dbPath?: string, env?: NodeJS.ProcessEnv}} [options]
+ * @returns {{project: object|null, card: object|null}}
+ */
+export function boardOwned(projectId, cardId = null, options = {}) {
+  const project = dbmod.getProject(projectId, options);
+  if (project === null || project === undefined) return { project: null, card: null };
+  if (cardId === null || cardId === undefined) return { project, card: null };
+  const card = dbmod.getBoardCard(cardId, options);
+  if (card === null || card === undefined || card.project_id !== project.id) {
+    return { project, card: null };
+  }
+  return { project, card };
+}
+
+/**
+ * `_task_since(task)`：任务起始时间（epoch **秒**，本地时区，运行中会话探测的时间下界）。
+ * `started_at` 优先，回退 `created_at`；格式异常返回 `0`（探测据此直接放弃）。
+ *
+ * 与 Python `time.mktime(time.strptime(val, "%Y-%m-%d %H:%M:%S"))` 同口径：按**本地时区**
+ * 解释（两侧跑在同一台机器、同一 TZ）。
+ *
+ * @param {object} task 任务行
+ * @returns {number}
+ */
+export function taskSince(task) {
+  for (const key of ['started_at', 'created_at']) {
+    const val = task ? task[key] : '';
+    const ms = parseLocalSeconds(val);
+    if (ms !== null) return ms;
+  }
+  return 0.0;
+}
+
+/** `%Y-%m-%d %H:%M:%S`（允许 1-2 位月/日/时分秒与两端空白）→ 本地时区 epoch 秒；不符 → null */
+function parseLocalSeconds(val) {
+  const m = /^\s*(\d{4})-(\d{1,2})-(\d{1,2})[ T](\d{1,2}):(\d{1,2}):(\d{1,2})\s*$/.exec(String(val ?? ''));
+  if (!m) return null;
+  const [, y, mo, d, h, mi, s] = m.map(Number);
+  const date = new Date(y, mo - 1, d, h, mi, s, 0);
+  const ms = date.getTime();
+  return Number.isNaN(ms) ? null : ms / 1000;
+}