@gavinc-cn/touchstone-dsh 0.1.1 → 0.2.0

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

@@ -112,20 +112,103 @@ function toggleByKey(e) {
 /** 宿主页 keydown 监听体(capture 阶段; 函数引用稳定, 便于 dispose 时精确解绑)。 */
 function onHostKey(e) { toggleByKey(e); }
 
+// ── 侧栏入口按钮的配色与几何(2026-10-09 修) ──────────────────────────────────
+// 血案: 原先写 color:'var(--dsw-alias-text-l1, #e8e8e8)' —— dsh **没有** text-l1 这族
+// token(真实族是 --dsw-alias-label-primary/secondary/tertiary/caption/dimmed), var() 取不到
+// 就一直吃 fallback: 浅色档在 #f9fafb 的侧栏底上画 #e8e8e8 的字(实测对比度 1.17, 同排的
+// 「插件」「设置」是 18.08), 只有深色档碰巧能看。教训: 引用宿主 token 一律先核实名字。
+// 现行口径(明暗两档都跟宿主走):
+//   · 颜色**只取 dsh 语义 token 且不写死 fallback** —— token 缺席时该声明失效并回落到继承
+//     (侧栏根 .hHd-Xa_root 已设 label-primary), 而不是钉死一个只对某一档成立的灰;
+//   · 尺寸/圆角/gap/行高逐条对齐 dsh 自己的 .SidebarRoot_panelRow(min-height 36 / 内边距
+//     7px 8px / margin 0 2px / gap 8 / line-height 22 / --dsw-radius-md), 收起态对齐
+//     .hHd-Xa_collapsed .panelRow(36x36 居中);
+//   · 图标盒 16x16 —— 与 dsh 侧栏 SVG 图标同尺寸; 文字继承侧栏根的 14px。
+const ENTRY_TITLE = 'Touchstone 测试平台（Alt+T 开关）';
+const ENTRY_GLYPH_STYLE = {
+  flex: '0 0 16px', width: 16, height: 16, display: 'inline-flex',
+  alignItems: 'center', justifyContent: 'center', fontSize: 16, lineHeight: '16px',
+};
+const ENTRY_LABEL_STYLE = {
+  minWidth: 0, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap',
+};
+
+// 交互态样式(悬停/开合/键盘聚焦环): 伪类没法写在 inline style 里, 落一张最小样式表。
+// 取值逐条对齐 dsh 侧栏行(.hHd-Xa_panelRow:hover 与 :focus-visible)。
+const ENTRY_CSS = [
+  '.ts-sb-entry{background:transparent}',
+  '.ts-sb-entry:hover,.ts-sb-entry.ts-sb-on{background:'
+    + 'var(--dsw-alias-interactive-bg-hover,color-mix(in srgb,currentColor 8%,transparent))}',
+  '.ts-sb-entry:focus-visible{outline-width:var(--dsw-focus-ring-width,2px);outline-style:solid;'
+    + 'outline-color:var(--dsw-focus-ring-color,var(--dsw-alias-state-business-primary));'
+    + 'outline-offset:-2px}',
+].join('');
+const ENTRY_CSS_ID = 'touchstone/sidebar-entry.css';
+
+/** 幂等挂上入口行交互态样式表(形态与 dsh 插件自身的注入方式一致)。
+ *  **失败一律吞掉**: 挂不上只是少了悬停/聚焦环的观感, 绝不能让侧栏入口或面板受影响
+ *  (桩 DOM 自检环境里 document 面本就不全, 真机异常同理)。
+ * @returns 摘除函数(插件卸载时调用; 已存在/挂不上时返回空操作)。 */
+function mountEntryStyle() {
+  try {
+    if (typeof document === 'undefined' || !document.head
+        || typeof document.createElement !== 'function'
+        || typeof document.querySelector !== 'function') {
+      return () => {};
+    }
+    if (document.querySelector('style[data-plugin-css=' + JSON.stringify(ENTRY_CSS_ID) + ']')) {
+      return () => {};
+    }
+    const tag = document.createElement('style');
+    tag.dataset.plugin = 'touchstone';
+    tag.dataset.pluginCss = ENTRY_CSS_ID;
+    tag.textContent = ENTRY_CSS;
+    document.head.appendChild(tag);
+    return () => tag.remove();
+  } catch (error) {
+    console.warn('[touchstone] 侧栏入口样式注入失败（只影响悬停/聚焦观感）:', error);
+    return () => {};
+  }
+}
+
 // 侧栏入口按钮(footer.action 槽; wide=侧栏展开态显示文字)
 function Toggle(props) {
-  const wide = props && props.wide;
+  const wide = !!(props && props.wide);
   const isOpen = useOpen();
+  const style = {
+    boxSizing: 'border-box', display: 'flex', alignItems: 'center',
+    border: 'none', cursor: 'pointer', textAlign: 'left',
+    color: 'var(--dsw-alias-label-primary)', // 无 fallback: 取不到即回落继承(见上注)
+    borderRadius: 'var(--dsw-radius-md, 8px)',
+    fontSize: 'inherit', // 侧栏根是 14px, 不再自带 13px
+  };
+  if (wide) {
+    style.gap = 8;
+    style.margin = '0 2px';
+    style.padding = '7px 8px';
+    style.minHeight = 36;
+    style.lineHeight = '22px';
+    style.flex = '1 1 auto';
+    style.minWidth = 0;
+  } else {
+    style.width = 36;
+    style.height = 36;
+    style.margin = 0;
+    style.padding = 0;
+    style.flex = 'none';
+    style.justifyContent = 'center';
+  }
   return h('button', {
-    style: {
-      display: 'flex', alignItems: 'center', gap: 6, width: '100%', boxSizing: 'border-box',
-      padding: '6px 12px', margin: '2px 0', borderRadius: 8, cursor: 'pointer', border: 'none',
-      color: 'var(--dsw-alias-text-l1, #e8e8e8)', fontSize: 13, textAlign: 'left',
-      background: 'transparent',
-    },
-    title: 'Touchstone 测试平台（Alt+T 开关）',
+    type: 'button',
+    className: 'ts-sb-entry' + (isOpen ? ' ts-sb-on' : ''),
+    style,
+    title: ENTRY_TITLE,
+    'aria-label': ENTRY_TITLE,
+    'aria-expanded': isOpen,
     onClick: () => setOpen(!isOpen),
-  }, wide ? (isOpen ? '🧪 关闭 Touchstone' : '🧪 Touchstone') : '🧪');
+  },
+  h('span', { style: ENTRY_GLYPH_STYLE, 'aria-hidden': 'true' }, '🧪'),
+  wide ? h('span', { style: ENTRY_LABEL_STYLE }, isOpen ? '关闭 Touchstone' : 'Touchstone') : null);
 }
 
 // 关闭按钮自动隐藏(2026-10-03): 常显会盖住被嵌 SPA 侧栏底部的用户名, 所以平时完全隐藏,
@@ -337,6 +420,8 @@ function Panel() {
 
 // cordis 客户端插件入口: 等 slots 服务就位后注册两个 UI 槽, 再挂快捷键
 function apply(ctx) {
+  // 侧栏入口的交互态样式表(悬停/开合/聚焦环), 与本插件同生命周期
+  ctx.effect(() => mountEntryStyle(), 'touchstone: 侧栏入口样式');
   const slots = ctx.get('slots');
   if (!slots) return;
   slots.inject('sidebar.footer.action', () => slots.register(

package/dsh-plugin/lib/index.js

@@ -22,9 +22,11 @@
  *   两条与正常 dispose 共用同一个幂等 `teardown()`, 因此正常路径行为不变。
  */
 import { spawn } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
+import { createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync }
+  from 'node:fs';
 import http from 'node:http';
-import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { AgentDriver, loadUserMessageFactory, loadModelSelectionInstaller }
   from './agent-driver.js';
@@ -45,6 +47,10 @@ const BACKEND_EXIT_GRACE_MS = 5000;
 /** 掉线自检节拍（ms）：热重载把本条目换下却不 dispose 时的兜底发现窗口 */
 const UNMOUNT_WATCH_MS = 2000;
 
+/** 插件形态后端日志（2026-10-08）：与库同目录追加写；启动时超过该体积先轮转一份 `.1` */
+const BACKEND_LOG_NAME = 'plugin-backend.log';
+const BACKEND_LOG_MAX_BYTES = 5 * 1024 * 1024;
+
 /** 进程级存活壳注册表键（同一 dsh 进程内只允许一份有效壳） */
 const LIVE_KEY = Symbol.for('touchstone.live');
 
@@ -62,6 +68,30 @@ const LIVE_KEY = Symbol.for('touchstone.live');
 const FATAL_PY_MODULES = ['zstandard', 'requests'];
 const PREFLIGHT_TIMEOUT_MS = 10000;
 
+/**
+ * 缺省解释器探测顺序（未配置 config.pythonPath 时）: `python` → `python3`。
+ *
+ * 为什么 `python` 排第一（2026-10-11 用户裁定「兜底应该用 python, 不要用 python3」）:
+ *  - **Windows 上没有 `python3` 这个名字**（官方安装器只装 `python.exe` / `py.exe`）,
+ *    桌面端零配置安装下, 写死 `python3` 会让 `spawn` 直接 `ENOENT` —— 比「找到解释器但
+ *    缺依赖」更糟：预检连跑都跑不起来, 只能走 `skip()` 放行, 然后后端在导入期崩掉,
+ *    用户既看不到缺什么、也拿不到可复制的修复命令。
+ *  - Linux 上两者都在（本机用户 shell 的 `python`/`python3` 同为 conda my_pyenv）,
+ *    顺序换成 `python` 优先不改变命中结果。
+ *  - 用 `python3` 当第二档是为了兜住「只有 python3、没有 python」的环境
+ *    （部分精简发行版/容器镜像如此）, 比单点写死更稳。
+ *  探测方式 = 真 spawn 一次 `-c pass`（受 PATH 解析、能识破 Microsoft Store 的
+ *  `python3.exe` 占位别名——它是 GUI 应用, 跑起来不会正常退出）, 而不是查文件表。
+ */
+const PYTHON_CANDIDATES = ['python', 'python3'];
+const PYTHON_PROBE_TIMEOUT_MS = 5000;
+/**
+ * 探测用的命令。带一个可识别的标记：测试里的假解释器要能把「探测调用」与
+ * 「依赖预检调用」区分开（两者都是 `-c`），否则探测会污染预检的调用记录。
+ * 标记写成 Python 注释, 对真解释器没有任何语义影响。
+ */
+const PYTHON_PROBE_CODE = 'pass  # touchstone-python-probe';
+
 /** 子进程句柄与解析出的后端端口（每 profile 一个插件实例, 模块级单例即可） */
 let child = null;
 let backendPort = 0;
@@ -78,6 +108,51 @@ function escapeHtml(text) {
     (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
 }
 
+/**
+ * 探一个候选解释器能不能真跑起来（`-c pass`, 5s 超时）。
+ *
+ * 为什么不是「查文件在不在」: spawn 走 PATH 解析, 而 Windows 的 Microsoft Store
+ * 别名会在 PATH 上放一个 `python3.exe` 占位（是 GUI 应用, 跑起来不返回）——
+ * 只有真跑一次才知道它是不是能用的解释器。任何异常（ENOENT/超时）都算不可用。
+ * `env` 由调用方传（用 `{...process.env, ...extraEnv}`）: profile 的 extraEnv 可能改 PATH,
+ * 探测必须与随后真正 spawn 后端的环境一致, 否则会出现「探测到 A、实际跑 B」。
+ */
+function canRunPython(name, env) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (ok) => {
+      if (settled) return;
+      settled = true;
+      resolve(ok);
+    };
+    let proc = null;
+    try {
+      proc = spawn(name, ['-c', PYTHON_PROBE_CODE], { stdio: 'ignore', env });
+    } catch {
+      done(false);
+      return;
+    }
+    const timer = setTimeout(() => {
+      try { proc.kill('SIGKILL'); } catch { /* 已退出：忽略 */ }
+      done(false);
+    }, PYTHON_PROBE_TIMEOUT_MS);
+    if (timer.unref) timer.unref();
+    proc.on('error', () => { clearTimeout(timer); done(false); });
+    proc.on('close', (code) => { clearTimeout(timer); done(code === 0); });
+  });
+}
+
+/**
+ * 解析未配置 pythonPath 时该用哪个解释器: 按 PYTHON_CANDIDATES 顺序探测, 返回第一个能跑的。
+ * 全都跑不起来（或本平台一个都没有）时返回 null, 由调用方给明确的配置指引。
+ */
+async function resolveDefaultPython(env = process.env) {
+  for (const name of PYTHON_CANDIDATES) {
+    if (await canRunPython(name, env)) return name;
+  }
+  return null;
+}
+
 /**
  * 读 requirements.txt 的发行名清单（注释/空行/选项行跳过, 剥掉版本与 extras 约束）。
  * 读不到就返回空数组 —— 预检降级为「只验硬依赖」, 不影响启动。
@@ -101,7 +176,7 @@ function readRequirementNames(repoDir) {
  *   advisory —— requirements.txt 里缺失的可选依赖（只影响对应功能）
  *   skipped  —— 预检本身没跑成（解释器缺失/超时/输出不可解析）⇒ 调用方照常启动
  */
-function preflightDeps(pythonPath, repoDir, logger) {
+function preflightDeps(pythonPath, repoDir, logger, env) {
   const advisory = readRequirementNames(repoDir)
     .filter((name) => !FATAL_PY_MODULES.includes(name.toLowerCase()));
   const script = [
@@ -130,7 +205,9 @@ function preflightDeps(pythonPath, repoDir, logger) {
       logger.warn(`touchstone: 依赖预检未完成（${why}）, 照常启动后端`);
       settle({ fatal: [], advisory: [], skipped: true });
     };
-    const proc = spawn(pythonPath, argv, { cwd: repoDir, stdio: ['ignore', 'pipe', 'pipe'] });
+    // env 必须显式传（与探测/启动后端同一份）: profile 的 extraEnv 可能改 PATH,
+    // 不传就出现「探测用 A、预检用 B」的分裂（2026-10-11 自检抓到的真 bug）。
+    const proc = spawn(pythonPath, argv, { cwd: repoDir, env, stdio: ['ignore', 'pipe', 'pipe'] });
     let stdout = '';
     const timer = setTimeout(() => {
       skip(`超过 ${PREFLIGHT_TIMEOUT_MS}ms`);
@@ -171,8 +248,11 @@ function preflightDeps(pythonPath, repoDir, logger) {
 /**
  * 依赖缺失时的面板提示页（代替 503 JSON）: 缺什么 + 一条可直接复制的修复命令
  * + 修完怎么让插件重来（停用再启用即会重跑 apply, 按 spec §8.8 不必重启 dsh web）。
+ *
+ * `viaDefault` = 这个解释器是缺省兜底探到的（用户没配 `pythonPath`）, 页面上要说明一句 ——
+ * 否则用户修完命令仍可能指错解释器, 且不知道该往哪里配。
  */
-function renderDepHint(pythonPath, repoDir, missing) {
+function renderDepHint(pythonPath, repoDir, missing, viaDefault) {
   const cmd = `${pythonPath} -m pip install -r ${join(repoDir, 'requirements.txt')}`;
   return '<!doctype html><html lang="zh"><head><meta charset="utf-8">'
     + '<title>Touchstone 后端未启动</title></head>'
@@ -184,11 +264,93 @@ function renderDepHint(pythonPath, repoDir, missing) {
     + '<pre style="background:#0d0f12;border:1px solid #2a2f36;border-radius:6px;'
     + `padding:.8rem 1rem;overflow:auto">${escapeHtml(cmd)}</pre>`
     + '<p>装完把本插件<b>停用再启用</b>（Plugins 面板里那一行的开关）即会重试，不必重启 dsh web。</p>'
-    + '<p style="color:#8b949e">若这个解释器不对，可在 profile patch 的 touchstone 条目里配置 '
-    + '<code>pythonPath</code> 指向含这些依赖的解释器。</p>'
+    + (viaDefault
+      ? '<p style="color:#8b949e">上面这个解释器是<b>缺省探测</b>得到的（未配置 '
+        + '<code>pythonPath</code>：依次试 <code>python</code>、<code>python3</code>）。'
+        + '若它不是你机器上装了依赖的那个，直接在它里面装依赖最省事（上面这条命令就是）；'
+        + '也可以改用另一个解释器 —— 在 profile patch 的 <code>touchstone-dsh</code> 条目里写 '
+        + '<code>pythonPath</code> 指向它。</p>'
+      : '<p style="color:#8b949e">若这个解释器不对，可在 profile patch 的 <code>touchstone-dsh</code> 条目里配置 '
+        + '<code>pythonPath</code> 指向含这些依赖的解释器。</p>')
+    + '</body></html>';
+}
+
+/**
+ * 缺省解释器一个都跑不起来时的提示页: 这不是「缺依赖」而是「找不到 Python」,
+ * 要给的是安装/配置指引, 不是 pip 命令（此时 pip 也没得跑）。
+ */
+function renderNoPythonHint() {
+  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;'
+    + 'background:#14161a;color:#e6e6e6">'
+    + '<h2 style="color:#ffb454;margin:0 0 .9rem">Touchstone 后端未启动：找不到 Python 解释器</h2>'
+    + '<p>依次探测 <code>python</code>、<code>python3</code> 都没能跑起来（未配置 '
+    + '<code>pythonPath</code>）。</p>'
+    + '<p>请先安装 Python 3.12+（<code>python.org</code>，Windows 上安装时勾选 '
+    + '<code>Add python.exe to PATH</code>），然后在 profile patch 的 '
+    + '<code>touchstone-dsh</code> 条目里写 <code>pythonPath</code> 指向它；'
+    + '若解释器已装好只是不在 PATH 上，也要靠这个配置项指过去。</p>'
+    + '<p style="color:#8b949e">配置后把本插件<b>停用再启用</b>即会重试，不必重启 dsh web。</p>'
     + '</body></html>';
 }
 
+/**
+ * 插件形态后端日志路径：与子进程用的**同一个库**同目录（`<库目录>/plugin-backend.log`）。
+ * 不落 node_modules 下的 .run：装机目录可能只读、重装即清，而且日志跟着库走才对得上
+ * 首启口令与运行审计。库路径优先级与 server.py 侧一致：extraEnv（profile 显式配置）
+ * > 宿主环境 > 缺省 `~/.touchstone/touchstone.db`。
+ */
+function backendLogPath(extraEnv) {
+  const dbPath = resolve(extraEnv.TOUCHSTONE_DB || process.env.TOUCHSTONE_DB
+    || join(homedir(), '.touchstone', 'touchstone.db'));
+  return join(dirname(dbPath), BACKEND_LOG_NAME);
+}
+
+/**
+ * 打开后端日志追加流（必要时先把超限的旧日志轮转成 `.1`）。任何失败都只 warn 并返回
+ * null —— 日志不可用**绝不阻断后端启动**，调用方退化为只走 dsh 日志。
+ */
+function openBackendLog(logPath, logger) {
+  try {
+    mkdirSync(dirname(logPath), { recursive: true, mode: 0o700 });
+    if (existsSync(logPath) && statSync(logPath).size > BACKEND_LOG_MAX_BYTES) {
+      try {
+        rmSync(logPath + '.1', { force: true });   // Windows 不允许改名覆盖已存在文件
+        renameSync(logPath, logPath + '.1');
+      } catch { /* 轮转失败照样追加：不因轮转挡启动 */ }
+    }
+    const stream = createWriteStream(logPath, { flags: 'a', mode: 0o600 });
+    let broken = false;
+    stream.on('error', (error) => {
+      if (broken) return;                          // 只报一次，避免刷屏
+      broken = true;
+      logger.warn(`touchstone: 后端日志写入失败（${error && error.message}）, 后续只走 dsh 日志`);
+    });
+    return stream;
+  } catch (error) {
+    logger.warn(`touchstone: 后端日志不可用（${error && error.message}）, 输出只走 dsh 日志: ${logPath}`);
+    return null;
+  }
+}
+
+/**
+ * 行缓冲转发子进程输出。为什么不直接 `split('\n')`：data 事件按 chunk 到达，**行可能
+ * 被切开**——`TOUCHSTONE_LISTEN` 被切成两段就永远匹配不上，端口解析不到、面板固定 503
+ * （2026-10-08 缺陷定位时一并修）。每个流各持一段 carry，拼齐整行才交给 onLine。
+ */
+function pumpLines(stream, onLine) {
+  let carry = '';
+  stream.setEncoding('utf8');        // 内部 StringDecoder：多字节字符跨 chunk 不截断乱码
+  stream.on('data', (chunk) => {
+    carry += chunk;
+    const lines = carry.split('\n');
+    carry = lines.pop();             // 末段不完整，留到下一 chunk
+    for (const line of lines) onLine(line);
+  });
+  stream.on('end', () => { if (carry) onLine(carry); });
+}
+
 /**
  * 反代 /touchstone/* 到本机 server.py 子进程: 剥掉 /touchstone 前缀后原样转发
  * （路径/查询串原样; Node http 管道流式转发不缓冲, SSE 事件实时透传）。
@@ -272,7 +434,8 @@ function stopChild(proc, logger, why) {
 /**
  * cordis 插件入口。config 来自 profile patch insert 条目（install.sh 写入）:
  *   repoDir    Touchstone 平台根（可选; 缺省 = 包自身目录, 因为包是自包含的）
- *   pythonPath Python 解释器（默认 python3; 本机应指含 zstandard 的 conda env）
+ *   pythonPath Python 解释器（可选; 缺省按 `python` → `python3` 顺序真跑一次探一个,
+ *              本机该指含 zstandard 的 conda env 或已 pip 装过依赖的那支）
  *   extraEnv   透传子进程的额外环境变量（如 TOUCHSTONE_DB 指向隔离实例库）
  * 返回组合 disposer（注销路由 + 断开驱动 + SIGTERM 子进程），dsh 停用插件时调用；
  * 另有「启用即回收上一份壳」与「掉线自检」两条自愈路径（见文件头注释）。
@@ -324,6 +487,14 @@ export async function apply(ctx, config = {}) {
     '--parent-watch',                             // 父死感知: dsh 退出/崩溃时后端自主退出
   ];
   const extraEnv = { ...(config.extraEnv || {}) };
+  // 插件形态默认「空口令 admin」（2026-10-08 用户口径）：面板本来就是免登 admin，
+  // 而随机一次性口令只印在启动横幅里、用户拿不到 —— 首装必被「强制改密门」锁死
+  // （横幅+门+薄壳丢 stdout 三者叠加，见 bug_report/20261008_1856）。这里下发开关：
+  // db.seed_admin 种子时存空口令、不置 must_change_pw；用户在设置页设了密码就按设置的来。
+  // 部署方显式配了 TS_ADMIN_PASSWORD 时无需让位（db 侧以该变量优先）。
+  if (!('TS_ADMIN_PASSWORDLESS' in extraEnv)) {
+    extraEnv.TS_ADMIN_PASSWORDLESS = '1';
+  }
   if (driverUrl) {
     // 驱动契约经环境变量下发（不写配置文件）: 重启 server.py 即重新握手, 无陈旧状态
     extraEnv.TS_AGENT_DRIVER_URL = driverUrl;
@@ -333,11 +504,25 @@ export async function apply(ctx, config = {}) {
   // 依赖预检（2026-10-07）: 缺硬依赖时**不 spawn** —— spawn 了也必然在导入期退出,
   // 日志里只留一行 traceback。改为把「缺什么 + 一条可复制的修复命令」同时送进
   // 日志与面板（backendHint 由 proxy 渲染）, 让 npm 安装真正做到「装完就知道缺什么」。
-  const pythonPath = config.pythonPath || 'python3';
-  const deps = await preflightDeps(pythonPath, repoDir, logger);
+  // 解释器（2026-10-11 改）: 配置优先; 没配就按 `python` → `python3` 真探一次
+  // （Windows 上没有 python3 这个名字, 写死它会直接 ENOENT——那样连缺依赖都报不出来）。
+  // 探测用「与随后 spawn 后端同一份 env」, extraEnv 里改过 PATH 时两者才一致。
+  const childEnv = { ...process.env, ...extraEnv };
+  const pythonPath = config.pythonPath || await resolveDefaultPython(childEnv);
+  if (!pythonPath) {
+    backendHint = renderNoPythonHint();
+    logger.warn(`touchstone: 找不到 Python 解释器（依次试过 ${PYTHON_CANDIDATES.join(', ')}）, 插件不启动后端`);
+    logger.warn('touchstone: 请安装 Python 3.12+ 或在本插件 config 里配 pythonPath, 然后停用再启用');
+    return;
+  }
+  const viaDefault = !config.pythonPath;
+  if (viaDefault) logger.info(`touchstone: 未配置 pythonPath, 缺省探到解释器: ${pythonPath}`);
+  const deps = await preflightDeps(pythonPath, repoDir, logger, childEnv);
   let myChild = null;
+  /** 本次壳的开的后端日志流（teardown 关闭；null = 不可用/未启动） */
+  let myLog = null;
   if (deps.fatal.length) {
-    backendHint = renderDepHint(pythonPath, repoDir, deps.fatal);
+    backendHint = renderDepHint(pythonPath, repoDir, deps.fatal, viaDefault);
     logger.warn(`touchstone: 后端未启动 —— Python 运行依赖缺失: ${deps.fatal.join(', ')}`);
     logger.warn(`touchstone: 修复: ${pythonPath} -m pip install -r ${join(repoDir, 'requirements.txt')}`);
     logger.warn('touchstone: 装完把本插件停用再启用即会重试（不必重启 dsh web）');
@@ -352,22 +537,38 @@ export async function apply(ctx, config = {}) {
     // EOF 即自主退出（实测父 kill -9 后 1.94s 退出）。改成 'ignore' 会让该通道失效。
     myChild = spawn(pythonPath, args, {
       cwd: repoDir,
-      env: { ...process.env, ...extraEnv },
+      env: childEnv,
       stdio: ['pipe', 'pipe', 'pipe'],
     });
     child = myChild;
-    myChild.stdout.on('data', (buf) => {
-      for (const line of String(buf).split('\n')) {
-        const m = line.match(/^TOUCHSTONE_LISTEN (\d+)/);
-        if (m) {
-          backendPort = Number(m[1]);
-          logger.info(`touchstone: 后端就绪 127.0.0.1:${backendPort}`);
-        }
+    // 子进程输出落盘（2026-10-08）：stdout 此前只用来解析 marker，**其余行全部丢弃**——
+    // 首启一次性口令横幅（设计上唯一出口，见 server._seed_hint）与 [board]/[waitq]/[runner]
+    // 运行诊断都在这些行里。现在 stdout/stderr 都逐行追加到 <库目录>/plugin-backend.log。
+    myLog = openBackendLog(backendLogPath(extraEnv), logger);
+    const writeLog = (line) => {
+      if (!myLog) return;
+      try { myLog.write(line + '\n'); } catch { /* 流已坏：忽略，绝不打断读取 */ }
+    };
+    pumpLines(myChild.stdout, (line) => {
+      writeLog(line);
+      const m = line.match(/^TOUCHSTONE_LISTEN (\d+)/);
+      if (m) {
+        backendPort = Number(m[1]);
+        logger.info(`touchstone: 后端就绪 127.0.0.1:${backendPort}`);
       }
     });
-    myChild.stderr.on('data', (buf) => logger.warn(`touchstone[py]: ${String(buf).trim()}`));
-    myChild.on('exit', (code, sig) => logger.warn(`touchstone: 后端退出 code=${code} sig=${sig}`));
-    myChild.on('error', (err) => logger.warn(`touchstone: 后端拉起失败: ${err.message}`));
+    pumpLines(myChild.stderr, (line) => {
+      writeLog(line);
+      if (line.trim()) logger.warn(`touchstone[py]: ${line.trim()}`);
+    });
+    myChild.on('exit', (code, sig) => {
+      writeLog(`[touchstone] 后端退出 code=${code} sig=${sig}`);
+      logger.warn(`touchstone: 后端退出 code=${code} sig=${sig}`);
+    });
+    myChild.on('error', (err) => {
+      writeLog(`[touchstone] 后端拉起失败: ${err.message}`);
+      logger.warn(`touchstone: 后端拉起失败: ${err.message}`);
+    });
   }
 
   let disposeRoute = null;
@@ -399,6 +600,10 @@ export async function apply(ctx, config = {}) {
       logger.warn(`touchstone: 驱动释放失败（忽略）: ${error && error.message}`);
     }
     await stopChild(myChild, logger, why);
+    if (myLog) {                    // 子进程停稳后再收日志流：最后几行不丢
+      try { myLog.end(); } catch { /* 已关闭：忽略 */ }
+      myLog = null;
+    }
     logger.info(`touchstone: 壳已停（${why}）`);
   };
 
@@ -441,3 +646,18 @@ export async function apply(ctx, config = {}) {
 // 注意: agents 服务**不在这里声明**——本插件的反代职责不应因「某 profile 没有 agent loop」
 // 而整包不加载; agent 驱动改用 ctx.inject(['agents'], ...) 延迟注入（见 agent-driver.js）。
 export const inject = ['webServer'];
+
+// 自检入口（2026-10-11）: `node lib/index.js --resolve-python` 打印缺省解释器解析结果
+// —— 给 scripts/dev-check-python.mjs 用真 PATH 驱动「python → python3」探测顺序的判决,
+// 也方便排障时在用户机器上一条命令看到「本机探到哪支」。命中输出名字、退出码 0;
+// 一个都探不到输出一行错误、退出码 1。被 dsh import 时 process.argv[1] 不是本文件, 不触发。
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+    && process.argv.includes('--resolve-python')) {
+  const found = await resolveDefaultPython();
+  if (found) {
+    console.log(found);
+    process.exit(0);
+  }
+  console.error(`no python interpreter found (tried: ${PYTHON_CANDIDATES.join(', ')})`);
+  process.exit(1);
+}

package/dsh-plugin/src/client.js

@@ -105,20 +105,103 @@ function toggleByKey(e) {
 /** 宿主页 keydown 监听体(capture 阶段; 函数引用稳定, 便于 dispose 时精确解绑)。 */
 function onHostKey(e) { toggleByKey(e); }
 
+// ── 侧栏入口按钮的配色与几何(2026-10-09 修) ──────────────────────────────────
+// 血案: 原先写 color:'var(--dsw-alias-text-l1, #e8e8e8)' —— dsh **没有** text-l1 这族
+// token(真实族是 --dsw-alias-label-primary/secondary/tertiary/caption/dimmed), var() 取不到
+// 就一直吃 fallback: 浅色档在 #f9fafb 的侧栏底上画 #e8e8e8 的字(实测对比度 1.17, 同排的
+// 「插件」「设置」是 18.08), 只有深色档碰巧能看。教训: 引用宿主 token 一律先核实名字。
+// 现行口径(明暗两档都跟宿主走):
+//   · 颜色**只取 dsh 语义 token 且不写死 fallback** —— token 缺席时该声明失效并回落到继承
+//     (侧栏根 .hHd-Xa_root 已设 label-primary), 而不是钉死一个只对某一档成立的灰;
+//   · 尺寸/圆角/gap/行高逐条对齐 dsh 自己的 .SidebarRoot_panelRow(min-height 36 / 内边距
+//     7px 8px / margin 0 2px / gap 8 / line-height 22 / --dsw-radius-md), 收起态对齐
+//     .hHd-Xa_collapsed .panelRow(36x36 居中);
+//   · 图标盒 16x16 —— 与 dsh 侧栏 SVG 图标同尺寸; 文字继承侧栏根的 14px。
+const ENTRY_TITLE = 'Touchstone 测试平台（Alt+T 开关）';
+const ENTRY_GLYPH_STYLE = {
+  flex: '0 0 16px', width: 16, height: 16, display: 'inline-flex',
+  alignItems: 'center', justifyContent: 'center', fontSize: 16, lineHeight: '16px',
+};
+const ENTRY_LABEL_STYLE = {
+  minWidth: 0, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap',
+};
+
+// 交互态样式(悬停/开合/键盘聚焦环): 伪类没法写在 inline style 里, 落一张最小样式表。
+// 取值逐条对齐 dsh 侧栏行(.hHd-Xa_panelRow:hover 与 :focus-visible)。
+const ENTRY_CSS = [
+  '.ts-sb-entry{background:transparent}',
+  '.ts-sb-entry:hover,.ts-sb-entry.ts-sb-on{background:'
+    + 'var(--dsw-alias-interactive-bg-hover,color-mix(in srgb,currentColor 8%,transparent))}',
+  '.ts-sb-entry:focus-visible{outline-width:var(--dsw-focus-ring-width,2px);outline-style:solid;'
+    + 'outline-color:var(--dsw-focus-ring-color,var(--dsw-alias-state-business-primary));'
+    + 'outline-offset:-2px}',
+].join('');
+const ENTRY_CSS_ID = 'touchstone/sidebar-entry.css';
+
+/** 幂等挂上入口行交互态样式表(形态与 dsh 插件自身的注入方式一致)。
+ *  **失败一律吞掉**: 挂不上只是少了悬停/聚焦环的观感, 绝不能让侧栏入口或面板受影响
+ *  (桩 DOM 自检环境里 document 面本就不全, 真机异常同理)。
+ * @returns 摘除函数(插件卸载时调用; 已存在/挂不上时返回空操作)。 */
+function mountEntryStyle() {
+  try {
+    if (typeof document === 'undefined' || !document.head
+        || typeof document.createElement !== 'function'
+        || typeof document.querySelector !== 'function') {
+      return () => {};
+    }
+    if (document.querySelector('style[data-plugin-css=' + JSON.stringify(ENTRY_CSS_ID) + ']')) {
+      return () => {};
+    }
+    const tag = document.createElement('style');
+    tag.dataset.plugin = 'touchstone';
+    tag.dataset.pluginCss = ENTRY_CSS_ID;
+    tag.textContent = ENTRY_CSS;
+    document.head.appendChild(tag);
+    return () => tag.remove();
+  } catch (error) {
+    console.warn('[touchstone] 侧栏入口样式注入失败（只影响悬停/聚焦观感）:', error);
+    return () => {};
+  }
+}
+
 // 侧栏入口按钮(footer.action 槽; wide=侧栏展开态显示文字)
 function Toggle(props) {
-  const wide = props && props.wide;
+  const wide = !!(props && props.wide);
   const isOpen = useOpen();
+  const style = {
+    boxSizing: 'border-box', display: 'flex', alignItems: 'center',
+    border: 'none', cursor: 'pointer', textAlign: 'left',
+    color: 'var(--dsw-alias-label-primary)', // 无 fallback: 取不到即回落继承(见上注)
+    borderRadius: 'var(--dsw-radius-md, 8px)',
+    fontSize: 'inherit', // 侧栏根是 14px, 不再自带 13px
+  };
+  if (wide) {
+    style.gap = 8;
+    style.margin = '0 2px';
+    style.padding = '7px 8px';
+    style.minHeight = 36;
+    style.lineHeight = '22px';
+    style.flex = '1 1 auto';
+    style.minWidth = 0;
+  } else {
+    style.width = 36;
+    style.height = 36;
+    style.margin = 0;
+    style.padding = 0;
+    style.flex = 'none';
+    style.justifyContent = 'center';
+  }
   return h('button', {
-    style: {
-      display: 'flex', alignItems: 'center', gap: 6, width: '100%', boxSizing: 'border-box',
-      padding: '6px 12px', margin: '2px 0', borderRadius: 8, cursor: 'pointer', border: 'none',
-      color: 'var(--dsw-alias-text-l1, #e8e8e8)', fontSize: 13, textAlign: 'left',
-      background: 'transparent',
-    },
-    title: 'Touchstone 测试平台（Alt+T 开关）',
+    type: 'button',
+    className: 'ts-sb-entry' + (isOpen ? ' ts-sb-on' : ''),
+    style,
+    title: ENTRY_TITLE,
+    'aria-label': ENTRY_TITLE,
+    'aria-expanded': isOpen,
     onClick: () => setOpen(!isOpen),
-  }, wide ? (isOpen ? '🧪 关闭 Touchstone' : '🧪 Touchstone') : '🧪');
+  },
+  h('span', { style: ENTRY_GLYPH_STYLE, 'aria-hidden': 'true' }, '🧪'),
+  wide ? h('span', { style: ENTRY_LABEL_STYLE }, isOpen ? '关闭 Touchstone' : 'Touchstone') : null);
 }
 
 // 关闭按钮自动隐藏(2026-10-03): 常显会盖住被嵌 SPA 侧栏底部的用户名, 所以平时完全隐藏,
@@ -330,6 +413,8 @@ function Panel() {
 
 // cordis 客户端插件入口: 等 slots 服务就位后注册两个 UI 槽, 再挂快捷键
 function apply(ctx) {
+  // 侧栏入口的交互态样式表(悬停/开合/聚焦环), 与本插件同生命周期
+  ctx.effect(() => mountEntryStyle(), 'touchstone: 侧栏入口样式');
   const slots = ctx.get('slots');
   if (!slots) return;
   slots.inject('sidebar.footer.action', () => slots.register(