@mrrisega/dsh-remote 0.6.11 → 0.6.13

package/packages/dsh-remote-web/test/diag-report.test.mjs

@@ -0,0 +1,236 @@
+// 故障上报（用户主动）＋「让 DeepSeek 帮我修」的用例（0.6.12）。
+//
+// 产品原则（2026-09-23 定的，本文件把它锁死）：
+//   ① **绝不**后台自动上传日志 —— 只有用户在面板里点「确认上报」才会发；
+//   ② 发之前必须能把**将要发送的每一个字**摊给用户看（预览），并且日志可取消附带；
+//   ③ 走**既有反馈通道**（企业端 /api/feedback），不需要服务端部署：正文 1 条 +
+//      日志/报告作为**同一条反馈的回复**分片（服务端 content 硬限 2000 字）；
+//   ④ 手机号/令牌/密码一律先脱敏再出机器；
+//   ⑤ 「让 DeepSeek 帮我修」= 给用户提示词 + 让用户把结论报告贴回来（我们发版前就能自救）。
+import assert from "node:assert/strict";
+import http from "node:http";
+import { readFileSync, rmSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { apply } from "../lib/index.js";
+
+const HERE = path.dirname(new URL(import.meta.url).pathname);
+const readOrEmpty = async (p) => { try { return await readFile(p, "utf8"); } catch { return ""; } };
+
+/** 假反馈服务：只收 /api/feedback 与 /api/feedback/:id/replies（与企业端契约同构）。 */
+function startFakeFeedback() {
+  const seen = [];
+  let nextId = 0;
+  const srv = http.createServer(async (req, res) => {
+    const url = new URL(req.url, "http://x");
+    const chunks = [];
+    for await (const c of req) chunks.push(c);
+    let body = null;
+    try { body = JSON.parse(Buffer.concat(chunks).toString("utf8") || "null"); } catch { body = null; }
+    seen.push({ method: req.method, path: url.pathname, body, headers: req.headers });
+    const send = (code, obj) => { res.writeHead(code, { "content-type": "application/json" }); res.end(JSON.stringify(obj)); };
+    if (req.method === "POST" && url.pathname === "/api/feedback") {
+      nextId += 1;
+      return send(201, { ok: true, feedback: { id: `fb_test_${nextId}`, kind: body?.kind }, thread_token: `tt_${nextId}` });
+    }
+    if (req.method === "POST" && /^\/api\/feedback\/[^/]+\/replies$/.test(url.pathname)) {
+      return send(201, { ok: true });
+    }
+    return send(404, { error: { code: "not_found" } });
+  });
+  return new Promise((resolve) => srv.listen(0, "127.0.0.1", () => resolve({
+    srv,
+    seen,
+    port: srv.address().port,
+    creates: () => seen.filter((s) => s.method === "POST" && s.path === "/api/feedback"),
+    replies: () => seen.filter((s) => /replies$/.test(s.path)),
+  })));
+}
+
+async function makeEnv({ feedbackPort }) {
+  const root = await mkdtemp(path.join(os.tmpdir(), "dsh-diag-"));
+  const relayDir = path.join(root, "relay");
+  await mkdir(relayDir, { recursive: true });
+  // 一个"能加载"的运行环境（入口 + 它点名的文件都在），避免半装判定把用例带偏
+  await writeFile(path.join(relayDir, "dsh-setup.mjs"), "// runtime stub\n");
+  await writeFile(path.join(relayDir, ".dsh-config.json"), JSON.stringify({
+    phone: "13800000000", password: "pw", device_id: "dev-diag",
+    api_url: `http://127.0.0.1:${feedbackPort}`, feedback_url: `http://127.0.0.1:${feedbackPort}`,
+  }));
+  const saved = {};
+  for (const k of ["DSH_RELAY_SKIP_SERVICE", "DSH_RELAY_PLATFORM", "DSH_REMOTE_TELEMETRY",
+    "DSH_RELAY_DEFAULT_API", "DSH_RELAY_BUNDLED_RUNTIME", "DSH_RELAY_WEDGE_MS"]) saved[k] = process.env[k];
+  process.env.DSH_RELAY_SKIP_SERVICE = "1";       // 隔离：用例不碰任何真实服务
+  process.env.DSH_RELAY_PLATFORM = "win32";       // 现场是 Windows
+  process.env.DSH_REMOTE_TELEMETRY = "0";
+  process.env.DSH_RELAY_DEFAULT_API = "http://127.0.0.1:1";
+  delete process.env.DSH_RELAY_BUNDLED_RUNTIME;
+  delete process.env.DSH_RELAY_WEDGE_MS;
+  return {
+    relayDir,
+    async restore() {
+      for (const [k, v] of Object.entries(saved)) {
+        if (v === undefined) delete process.env[k]; else process.env[k] = v;
+      }
+      rmSync(root, { recursive: true, force: true });
+    },
+  };
+}
+
+function boot(relayDir) {
+  const routes = new Map();
+  const disposers = [];
+  apply({
+    webServer: { register(route) { routes.set(route.path, route.handler); return () => {}; } },
+    effect(register) { const d = register(); if (typeof d === "function") disposers.push(d); return d; },
+    logger: { info() {}, warn() {} },
+  }, { relayDir });
+  routes.dispose = () => { for (const d of disposers) { try { d(); } catch { /* 忽略 */ } } };
+  return routes;
+}
+
+async function serve(routes) {
+  const host = http.createServer((req, res) => {
+    const handler = routes.get(new URL(req.url, "http://x").pathname);
+    (handler || ((_r, rs) => { rs.writeHead(404); rs.end(); }))(req, res);
+  });
+  await new Promise((resolve) => host.listen(0, "127.0.0.1", resolve));
+  return { host, base: `http://127.0.0.1:${host.address().port}` };
+}
+
+const getJson = async (url) => (await fetch(url)).json();
+const postJson = async (url, body) => {
+  const r = await fetch(url, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+  return { status: r.status, body: await r.json().catch(() => null) };
+};
+
+test("预览：把「将要发送的每一个字」摊开，且不含手机号（脱敏后再出机器）", async () => {
+  const fb = await startFakeFeedback();
+  const env = await makeEnv({ feedbackPort: fb.port });
+  const routes = boot(env.relayDir);
+  const { host, base } = await serve(routes);
+  try {
+    // 日志里塞进手机号 / 令牌 / 崩溃栈：预览必须脱敏，且**保留**真实崩溃原因（那才是能定位的东西）
+    await writeFile(path.join(env.relayDir, ".dsh-bridge.log"),
+      "[bridge] 用账号 13800000000 登录换取 JWT...\nAuthorization: Bearer eyJhbGciOiJIUzI1NiJ9.abcdefghijklmnop\nError: Cannot find module 'ws'\n");
+    await writeFile(path.join(env.relayDir, ".dsh-setup-install.log"),
+      "[dsh-remote-web] 自动启动 bridge 未成功(not-installed): 运行环境入口脚本不存在\n");
+
+    const b = await getJson(`${base}/dsh-remote/diag/bundle`);
+    assert.equal(b.ok, true);
+    assert.match(b.title, /\[诊断\]/);
+    assert.match(b.title, /0\.6\./, "标题要带插件版本，便于后台按版本分桶");
+    const all = b.summary + "\n" + b.parts.join("\n");
+    for (const need of ["【阶段】", "【bridge】", "【上游】", "【配置目录】", env.relayDir]) {
+      assert.ok(all.includes(need), `预览必须包含 ${need}（这些正是 2026-09-23 那次反馈里缺失的证据）`);
+    }
+    assert.match(all, /守护=/, "守护进程态必须可见（旧版诊断里它是隐身的）");
+    assert.equal(b.parts.length, 2, "默认附带两个日志各一份分片");
+    assert.ok(!all.includes("13800000000"), "手机号绝不能出现在将发送的内容里");
+    assert.match(all, /138\*\*\*\*0000/, "日志里的手机号要被掩码");
+    assert.match(all, /Bearer <已隐去>/, "令牌必须隐去");
+    assert.match(all, /Cannot find module/, "真实崩溃原因必须保留（否则还是查不出来）");
+    assert.match(all, /已登录/, "只说「已登录」，不把手机号外发（服务端据登录态已知是谁）");
+    assert.equal(b.noteMax > 0, true, "要告诉前端备注上限");
+  } finally { host.close(); routes.dispose(); await env.restore(); fb.srv.close(); }
+});
+
+test("上报：正文 1 条 + 日志分片作为同一条反馈的回复；不点就不发（零自动上报）", async () => {
+  const fb = await startFakeFeedback();
+  const env = await makeEnv({ feedbackPort: fb.port });
+  const routes = boot(env.relayDir);
+  const { host, base } = await serve(routes);
+  try {
+    await writeFile(path.join(env.relayDir, ".dsh-bridge.log"), "line-1\nline-2\n");
+    await writeFile(path.join(env.relayDir, ".dsh-setup-install.log"), "install-line-1\n");
+    // ① 只打开面板、不点上报 → 反馈服务**一次都不该被打到**
+    await getJson(`${base}/dsh-remote/diag/bundle`);
+    assert.equal(fb.creates().length + fb.replies().length, 0,
+      "预览阶段绝不允许提交任何反馈（隐私红线；插件装载时的装机上报走的是别的端点，不算）");
+
+    // ② 用户点「确认上报」→ 正文（含他的描述）+ 分片
+    const r = await postJson(`${base}/dsh-remote/diag/report`, { note: "手机一直显示没有绑定任何电脑", attachLogs: true });
+    assert.equal(r.status, 200);
+    assert.equal(r.body.ok, true);
+    assert.match(String(r.body.id), /^fb_test_/);
+    const creates = fb.creates();
+    assert.equal(creates.length, 1, "正文只能是一条反馈");
+    assert.equal(creates[0].body.kind, "feedback");
+    assert.equal(creates[0].body.category, "bug");
+    assert.match(String(creates[0].body.content), /手机一直显示没有绑定任何电脑/, "用户描述必须在正文里");
+    assert.match(String(creates[0].body.content), /【阶段】/);
+    assert.ok(!String(creates[0].body.content).includes("13800000000"), "正文同样不得带手机号");
+    const replies = fb.replies();
+    assert.equal(replies.length, 2, "两个日志各一条分片回复（服务端正文 2000 字上限的绕行方案）");
+    assert.ok(replies.some((x) => String(x.body.content).includes("line-1")), "bridge 日志必须在分片里");
+    assert.equal(creates[0].headers["x-dsh-device"], "dev-diag", "要带上设备身份（服务端据此关联机器）");
+
+    // ③ 用户取消「附带日志」→ 只有正文
+    const r2 = await postJson(`${base}/dsh-remote/diag/report`, { note: "只发正文", attachLogs: false });
+    assert.equal(r2.body.parts, 0);
+    assert.equal(fb.creates().length, 2);
+    assert.equal(fb.replies().length, 2, "取消附带的这一条不产生新的分片");
+
+    // ④ 回传「结论报告」：作为分片进同一条反馈
+    const r3 = await postJson(`${base}/dsh-remote/diag/report`, { note: "来自让 DeepSeek 帮我修", attachLogs: false, report: "=== dsh-remote 诊断结论 ===\n机制判定: ②守护活着没起作用" });
+    assert.equal(r3.body.parts, 1);
+    assert.match(String(fb.replies().at(-1).body.content), /机制判定/, "用户回传的报告必须到达");
+  } finally { host.close(); routes.dispose(); await env.restore(); fb.srv.close(); }
+});
+
+test("上报：坏 JSON 与超大 body 都要给人话，且绝不打挂宿主", async () => {
+  const fb = await startFakeFeedback();
+  const env = await makeEnv({ feedbackPort: fb.port });
+  const routes = boot(env.relayDir);
+  const { host, base } = await serve(routes);
+  try {
+    const bad = await fetch(`${base}/dsh-remote/diag/report`, {
+      method: "POST", headers: { "content-type": "application/json" }, body: "{不是 JSON",
+    });
+    assert.equal(bad.status, 400);
+    assert.match(String((await bad.json()).error), /JSON/);
+
+    const huge = await fetch(`${base}/dsh-remote/diag/report`, {
+      method: "POST", headers: { "content-type": "application/json" },
+      body: JSON.stringify({ note: "x", report: "y".repeat(300 * 1024) }),
+    });
+    assert.equal(huge.status, 413, "超大 body 必须被挡下（保护宿主内存）");
+    assert.equal(fb.creates().length, 0, "被挡下的请求不得提交到反馈服务");
+  } finally { host.close(); routes.dispose(); await env.restore(); fb.srv.close(); }
+});
+
+test("修复提示词：带当前故障上下文（目录/上游/版本），便于用户本机 DSH 直接照做", async () => {
+  const fb = await startFakeFeedback();
+  const env = await makeEnv({ feedbackPort: fb.port });
+  const routes = boot(env.relayDir);
+  const { host, base } = await serve(routes);
+  try {
+    const b = await getJson(`${base}/dsh-remote/diag/fix-prompt`);
+    assert.equal(b.ok, true);
+    assert.match(b.prompt, new RegExp(env.relayDir.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")), "提示词要带上本机配置目录");
+    assert.match(b.prompt, /127\.0\.0\.1:3080/, "提示词要带上上游地址（端口错配是本次事故的最大嫌疑）");
+    assert.match(b.prompt, /\.dsh-bridge\.log/);
+    assert.match(b.prompt, /\.dsh-setup-install\.log/);
+    assert.match(b.reportTitle, /dsh-remote 诊断结论/, "报告格式要有固定首行，便于后台机器解析");
+    assert.ok(Array.isArray(b.reportKeys) && b.reportKeys.includes("机制判定") && b.reportKeys.includes("修复结果"));
+  } finally { host.close(); routes.dispose(); await env.restore(); fb.srv.close(); }
+});
+
+test("前端契约：两个入口都在连接卡上；上报只在用户点击后发生（源码级）", () => {
+  const client = readFileSync(path.join(HERE, "..", "lib", "client.js"), "utf8");
+  assert.match(client, /上报故障给开发者/, "面板必须有「上报故障给开发者」入口");
+  assert.match(client, /让 DeepSeek 帮我修/, "面板必须有「让 DeepSeek 帮我修」入口");
+  assert.match(client, /将要发送/, "上报前必须明确告诉用户「将要发送」的是什么");
+  assert.match(client, /复制提示词/, "修复提示词必须可一键复制");
+  assert.match(client, /回传结论报告/, "用户要能把 DSH 的结论报告回传给我们");
+  // 只在用户点击后调用：这两个接口各只有**一个**调用点，且都在对应的事件处理函数里
+  assert.equal((client.match(/dsh-remote\/diag\/report/g) || []).length, 1,
+    "上报接口只能有一个调用点（防止有人在渲染/挂载时就发）");
+  assert.equal((client.match(/dsh-remote\/diag\/bundle/g) || []).length, 1);
+  assert.equal((client.match(/dsh-remote\/diag\/fix-prompt/g) || []).length, 1);
+  const openFn = client.slice(client.indexOf("var openDiagReport = function"), client.indexOf("var openFixPrompt = function"));
+  assert.match(openFn, /diag\/bundle/, "预览只在用户打开上报时才拉取");
+  assert.ok(!/useEffect/.test(openFn), "预览不得挂在 useEffect 里自动触发");
+});

package/packages/dsh-remote-web/test/fix-prompt.test.mjs

@@ -0,0 +1,170 @@
+/**
+ * 「连接卡住 → 一键修复提示词 + 结论报告」契约测试（node:test，零框架）。
+ *
+ * 背景（真实事故，2026-09-23，Windows 用户）：
+ *   插件面板卡在「连接阶段: starting（正在启动 Bridge…）」，手机端看不到任何设备，反复修都没用。
+ *   事后定位到三种机制（半装运行环境 / 守护活着没起作用 / bridge 起来就崩），它们在面板上长得一模一样，
+ *   面板侧诊断分不开；只能由用户本机的 agent 在自己电脑上取证。
+ *   所以面板给用户一段可一键复制的中文提示词，并要求回传一份**固定格式**的报告。
+ *
+ * 这份用例锁死提示词的**可执行性与边界**，而不是文风：
+ *   ① 六步齐备且顺序正确（第一步读日志、最后一步出报告），每步都有「验证」；
+ *   ② 三条判据各自依赖的关键路径/命令都要出现在文案里（日志、lifecycle.mjs、ws、端口、守护、状态文件）；
+ *   ③ 隐私红线：脱敏示例、禁止贴手机号/密码/token、禁止删除 ~/.dsh-remote；
+ *   ④ 报告格式固定：模板首行就是标题，六个字段齐全，「修复结果」只允许已修复/未修复；
+ *   ⑤ buildFixPrompt() 无参不崩、任何情况下不出现 undefined，传入 ctx 的值真的进了文案。
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  BRIDGE_LOG_FILE,
+  BRIDGE_STATE_FILE,
+  DEFAULT_RELAY_DIR,
+  DEFAULT_UPSTREAM_PORT,
+  FIX_PROMPT,
+  INSTALL_LOG_FILE,
+  REPORT_FORMAT,
+  REPORT_KEYS,
+  REPORT_TITLE,
+  UPSTREAM_FILE,
+  buildFixPrompt,
+} from "../lib/fix-prompt.js";
+
+/** 默认 ctx 渲染出来的提示词（无参调用的结果）。 */
+const DEFAULT_PROMPT = buildFixPrompt();
+
+test("提示词覆盖两份日志：既有默认值，也支持面板传入的绝对路径", () => {
+  // 默认值（占位符之外必须写明默认位置，否则用户找不到日志）
+  assert.ok(FIX_PROMPT.includes(`~/.dsh-remote/${BRIDGE_LOG_FILE}`), "模板里应写明 bridge 日志的默认位置");
+  assert.ok(FIX_PROMPT.includes(`~/.dsh-remote/${INSTALL_LOG_FILE}`), "模板里应写明安装日志的默认位置");
+  assert.ok(DEFAULT_PROMPT.includes(`~/.dsh-remote/${BRIDGE_LOG_FILE}`), "无参渲染后应含 bridge 日志默认路径");
+  assert.ok(DEFAULT_PROMPT.includes(`~/.dsh-remote/${INSTALL_LOG_FILE}`), "无参渲染后应含安装日志默认路径");
+  // 面板上报的真实路径（Windows 形态）必须原样出现，且不能再留占位符
+  const prompt = buildFixPrompt({
+    bridgeLogPath: "C:\\Users\\u\\.dsh-remote\\.dsh-bridge.log",
+    installLogPath: "C:\\Users\\u\\.dsh-remote\\.dsh-setup-install.log",
+  });
+  assert.ok(prompt.includes("C:\\Users\\u\\.dsh-remote\\.dsh-bridge.log"), "传入的 bridge 日志路径应出现在提示词里");
+  assert.ok(prompt.includes("C:\\Users\\u\\.dsh-remote\\.dsh-setup-install.log"), "传入的安装日志路径应出现在提示词里");
+  assert.ok(!prompt.includes("{{"), `渲染后不应残留占位符: ${prompt.match(/\{\{[^}]*\}\}/g)}`);
+});
+
+test("六步齐备且顺序正确，每一步都要求 agent 自己验证", () => {
+  // 用「第 N 步 ·」定位标题（正文里会出现「需按第 3 步核实」这类交叉引用，不能只匹配「第 N 步」）
+  const marks = ["第 1 步 ·", "第 2 步 ·", "第 3 步 ·", "第 4 步 ·", "第 5 步 ·", "第 6 步 ·"];
+  let last = -1;
+  for (const m of marks) {
+    const at = DEFAULT_PROMPT.indexOf(m);
+    assert.ok(at > last, `${m} 应存在且顺序在 ${marks[marks.indexOf(m) - 1] || "开头"} 之后`);
+    last = at;
+  }
+  // 每步都要有「验证:」小节（6 步各自验证，而不是最后统一看一眼）
+  const checks = DEFAULT_PROMPT.match(/验证[:：]/g) || [];
+  assert.ok(checks.length >= 6, `每一步都应自带验证要求（实际 ${checks.length} 处）`);
+  // 第 1 步必须是读日志，第 6 步必须是出报告
+  assert.match(DEFAULT_PROMPT.slice(DEFAULT_PROMPT.indexOf("第 1 步 ·"), DEFAULT_PROMPT.indexOf("第 2 步 ·")), /日志/);
+  assert.match(DEFAULT_PROMPT.slice(DEFAULT_PROMPT.indexOf("第 6 步 ·")), /报告/);
+});
+
+test("第 2 步：运行环境完整性清单（lifecycle.mjs / dsh-bridge.mjs / ws）与重新补装命令", () => {
+  assert.ok(DEFAULT_PROMPT.includes("clients/dsh-remote/src/lifecycle.mjs"), "必须点名 lifecycle.mjs（① 号机制缺的就是它）");
+  assert.ok(DEFAULT_PROMPT.includes("clients/dsh-remote/dsh-bridge.mjs"), "必须点名 dsh-bridge.mjs");
+  assert.ok(DEFAULT_PROMPT.includes("node_modules/ws"), "必须点名 node_modules/ws（缺 ws = bridge 起来就崩）");
+  assert.ok(/dsh-setup\.mjs/.test(DEFAULT_PROMPT), "必须点名 dsh-setup.mjs 是否在（半装的判据）");
+  assert.ok(DEFAULT_PROMPT.includes("Cannot find module"), "应给出半装的典型报错原文，便于对号入座");
+  assert.ok(DEFAULT_PROMPT.includes("npx @mrrisega/dsh-remote"), "缺失时应指导用一键安装器补装");
+  assert.ok(/node --check/.test(DEFAULT_PROMPT), "补装后要求自己做语法/加载验证");
+});
+
+test("第 3 步：核对 dsh web 实际监听端口（netstat / --port / .dsh-upstream / 3080）", () => {
+  assert.ok(DEFAULT_PROMPT.includes("netstat -ano | findstr LISTENING"), "Windows 要给出 netstat 查监听端口");
+  assert.ok(DEFAULT_PROMPT.includes("--port"), "要提示看 dsh web 启动命令里的 --port");
+  assert.ok(DEFAULT_PROMPT.includes(`~/.dsh-remote/${UPSTREAM_FILE}`) || DEFAULT_PROMPT.includes(UPSTREAM_FILE), "要读 .dsh-upstream 端口文件");
+  assert.ok(DEFAULT_PROMPT.includes(String(DEFAULT_UPSTREAM_PORT)), "要写明默认端口 3080 只是回退值");
+  assert.ok(DEFAULT_PROMPT.includes("DSH_BRIDGE_UPSTREAM"), "端口不一致时应给出显式覆盖上游地址的手段");
+  // 端口不一致 → 按实际端口修正并重启 bridge
+  assert.match(DEFAULT_PROMPT, /不一致[^]{0,200}重启 bridge/);
+});
+
+test("第 4 步：能识别「守护活着但没起作用」，并结束卡死守护后重新拉起", () => {
+  assert.ok(DEFAULT_PROMPT.includes("dsh-setup.mjs run"), "要给出守护进程的命令行形态");
+  assert.ok(DEFAULT_PROMPT.includes("活着但没起作用"), "要显式命名②号机制的现场特征");
+  assert.ok(DEFAULT_PROMPT.includes("taskkill /PID <pid> /T /F"), "Windows 要用 taskkill 连子进程一起收");
+  assert.ok(/\bkill <pid>/.test(DEFAULT_PROMPT), "macOS/Linux 要给出 kill（并有 kill -9 兜底）");
+  assert.ok(DEFAULT_PROMPT.includes("kill -9"), "不退出时的兜底信号应写明");
+  assert.match(DEFAULT_PROMPT, /taskkill[\s\S]{0,400}\bkill <pid>/, "两种平台的结束方式应写在一起（用户不一定在哪个系统上）");
+});
+
+test("第 5 步：以 .dsh-bridge-state.json 的 device_id + phase=online 收口，并要求如实回报", () => {
+  assert.ok(DEFAULT_PROMPT.includes(`~/.dsh-remote/${BRIDGE_STATE_FILE}`), "状态文件的默认路径必须出现");
+  assert.ok(DEFAULT_PROMPT.includes("device_id"), "要看 device_id（设备身份是否落盘）");
+  assert.ok(DEFAULT_PROMPT.includes("online"), "phase=online 是唯一成功判据");
+  assert.ok(DEFAULT_PROMPT.includes("last_error"), "没通时要摘 last_error 原文");
+  assert.match(DEFAULT_PROMPT, /没修好也要照实写/, "必须允许并鼓励如实报告失败");
+});
+
+test("隐私红线：脱敏示例、禁止凭据/贴文件内容、禁止删 ~/.dsh-remote", () => {
+  assert.ok(DEFAULT_PROMPT.includes("138****0000"), "必须给出手机号掩码示例");
+  assert.match(DEFAULT_PROMPT, /不得[\s\S]{0,80}(手机号|密码|token)/, "必须明文禁止把凭据写进报告");
+  assert.ok(/密码/.test(DEFAULT_PROMPT) && /token/i.test(DEFAULT_PROMPT) && /bridge_secret/.test(DEFAULT_PROMPT), "手机号/密码/token/bridge_secret 都要点名");
+  assert.ok(DEFAULT_PROMPT.includes("JWT") && /cookie/i.test(DEFAULT_PROMPT), "JWT 与 cookie 也要点名");
+  assert.match(DEFAULT_PROMPT, /不要删除/, "必须明确不要删除运行环境目录");
+  assert.match(DEFAULT_PROMPT, /不要删除[^]{0,60}账号与设备身份/, "要给出「删了就丢账号/设备身份」的理由");
+  assert.match(DEFAULT_PROMPT, /不要把用户的文件内容、会话内容/, "禁止把用户文件/会话内容贴进报告");
+  assert.ok(/已隐去/.test(DEFAULT_PROMPT), "token/密钥应统一写成 <已隐去>");
+  // 反向：提示词不得示范真实凭据形态
+  assert.ok(!/Bearer\s+[A-Za-z0-9._-]{8,}/.test(DEFAULT_PROMPT), "提示词本身不得出现形似真实 token 的串");
+});
+
+test("报告格式：REPORT_KEYS 六个字段齐全，REPORT_FORMAT 首行即固定标题", () => {
+  for (const key of ["症状", "机制判定", "关键证据", "已做的修复", "修复结果", "仍需人工处理"]) {
+    assert.ok(REPORT_KEYS.includes(key), `REPORT_KEYS 应覆盖「${key}」`);
+  }
+  assert.equal(REPORT_KEYS.length, 6, "REPORT_KEYS 就是这六项（多了会让解析口径漂移）");
+  assert.equal(REPORT_FORMAT.split("\n")[0], REPORT_TITLE, "报告模板首行必须是固定标题");
+  assert.equal(REPORT_TITLE, "=== dsh-remote 诊断结论 ===");
+  // 六项在模板里都要有对应行，且顺序与 REPORT_KEYS 一致
+  const positions = REPORT_KEYS.map((k) => REPORT_FORMAT.indexOf(k + ":"));
+  assert.ok(positions.every((p) => p >= 0), "六项都要在模板里有 <字段>: 行");
+  assert.deepEqual([...positions].sort((a, b) => a - b), positions, "模板字段顺序应与 REPORT_KEYS 一致");
+  // 机制判定四选一 + 修复结果二选一（机器解析靠这两个枚举）
+  assert.match(REPORT_FORMAT, /①半装运行环境[\s\S]*②守护活着没起作用[\s\S]*③bridge 起来就崩[\s\S]*其它/);
+  assert.match(REPORT_FORMAT, /修复结果: 已修复 \| 未修复/);
+  // 报告模板本身也要进提示词，并要求放进围栏里、标题在围栏内第一行
+  assert.ok(DEFAULT_PROMPT.includes(REPORT_FORMAT), "提示词里应内嵌完整报告模板");
+  assert.match(DEFAULT_PROMPT, /```[\s\S]*=== dsh-remote 诊断结论 ===/, "模板应被要求放进 ``` 围栏且标题是围栏内第一行");
+});
+
+test("buildFixPrompt() 无参不崩、任何字段缺省都不出现 undefined；传入 ctx 的值真的进文案", () => {
+  assert.equal(typeof DEFAULT_PROMPT, "string");
+  assert.ok(DEFAULT_PROMPT.length > 1000, "应是一段完整可执行的提示词");
+  assert.ok(!DEFAULT_PROMPT.includes("undefined"), "缺省时不得出现 undefined");
+  assert.ok(!DEFAULT_PROMPT.includes("null"), "缺省时不得出现 null");
+  assert.ok(!DEFAULT_PROMPT.includes("{{"), "缺省时不得残留占位符");
+  // 默认值本身要可读（而不是空白或 "unknown"）
+  assert.ok(DEFAULT_PROMPT.includes(DEFAULT_RELAY_DIR), "应回退到默认运行环境目录");
+  assert.ok(DEFAULT_PROMPT.includes("starting（正在启动 Bridge…）"), "应回退到面板的 starting 阶段文案");
+  assert.ok(DEFAULT_PROMPT.includes(`http://127.0.0.1:${DEFAULT_UPSTREAM_PORT}`), "应回退到默认上游地址");
+  assert.ok(/未知/.test(DEFAULT_PROMPT), "版本缺失时应写「未知」而不是留空");
+
+  // 显式 ctx：每个字段都要在文本里出现，且日志路径能由 relayDir 推导
+  const prompt = buildFixPrompt({
+    relayDir: "/home/u/.dsh-remote",
+    pluginVersion: "0.6.12",
+    runtimeVersion: "0.6.12",
+    upstreamUrl: "http://127.0.0.1:8090",
+    phaseText: "connecting",
+  });
+  for (const value of ["/home/u/.dsh-remote", "0.6.12", "http://127.0.0.1:8090", "connecting"]) {
+    assert.ok(prompt.includes(value), `ctx 值应出现在提示词里: ${value}`);
+  }
+  assert.ok(prompt.includes(`/home/u/.dsh-remote/${BRIDGE_LOG_FILE}`), "relayDir 应能推导出 bridge 日志路径");
+  assert.ok(prompt.includes(`/home/u/.dsh-remote/${INSTALL_LOG_FILE}`), "relayDir 应能推导出安装日志路径");
+  assert.ok(prompt.includes(`/home/u/.dsh-remote/${BRIDGE_STATE_FILE}`), "relayDir 应能推导出状态文件路径");
+  assert.ok(!prompt.includes("undefined"));
+  // 尾部斜杠 / 全空白 / 非字符串 都要优雅降级，不能拼出 "//" 或 undefined
+  const sloppy = buildFixPrompt({ relayDir: "/home/u/.dsh-remote/", pluginVersion: "   ", runtimeVersion: null, upstreamUrl: undefined, phaseText: 42 });
+  assert.ok(!sloppy.includes("undefined") && !sloppy.includes("//" + BRIDGE_LOG_FILE), "非法/空白 ctx 必须降级，不得拼出坏路径");
+  assert.ok(sloppy.includes(`/home/u/.dsh-remote/${BRIDGE_LOG_FILE}`), "带尾斜杠的 relayDir 应被规整");
+  assert.equal(buildFixPrompt(null), DEFAULT_PROMPT, "ctx 为 null 时与无参调用等价");
+});

package/packages/dsh-remote-web/test/runtime-bundle.test.mjs

@@ -0,0 +1,198 @@
+// 运行环境随插件分发（0.6.12）的用例。
+//
+// 背景（2026-09-23 生产取证）：Windows 上「装插件 → 后台 npx 装运行环境」是最大的流失源 ——
+// 近 14 天 427 台 win32 里 138 台 install_failed（32%）；v0.6.6 的 95 台里 73 台装机失败，
+// 其中 48 台点过「一键更新」却一台都没救回来（Node ≥20.12 上 spawn npx.cmd 不带 shell 抛 EINVAL）。
+// 现在插件包自带 runtime/（scripts/bundle-runtime.mjs 打进 npm 包与 GitHub Release 资产），
+// 补装退化为**本地拷贝**：零网络、零 npx、零控制台代码页，且运行环境版本恒等于插件版本。
+//
+// 本文件锁死三条不变量：
+//   ① 打包产物完整（入口 + 入口点名的 clients 文件 + ws），且**不含** test/ 这类垃圾；
+//   ② 半装运行环境（入口在、依赖不在）→ 用自带运行环境**整份补齐**，全程不碰 npx；
+//   ③ 自带运行环境本身不完整/不存在 → 老实回落到 npx（绝不假装成功）。
+import assert from "node:assert/strict";
+import http from "node:http";
+import { spawnSync } from "node:child_process";
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { apply } from "../lib/index.js";
+
+const HERE = path.dirname(new URL(import.meta.url).pathname);
+const ROOT = path.join(HERE, "..", "..", "..");
+const BUNDLER = path.join(ROOT, "scripts", "bundle-runtime.mjs");
+const PKG_JSON = path.join(ROOT, "packages", "dsh-remote-web", "package.json");
+
+const readOrEmpty = async (p) => { try { return await readFile(p, "utf8"); } catch { return ""; } };
+async function waitFor(fn, { timeout = 5000, step = 25 } = {}) {
+  const deadline = Date.now() + timeout;
+  for (;;) {
+    if (await fn()) return true;
+    if (Date.now() > deadline) return false;
+    await new Promise((r) => setTimeout(r, step));
+  }
+}
+
+/** 假 npx：只记参数（用例必须证明「该走本地拷贝时一次 npx 都不调」）。 */
+const FAKE_NPX = `#!/bin/sh
+printf '%s\\n' "$*" >> "$DSH_TEST_NPX_LOG"
+exit 0
+`;
+
+async function makeEnv() {
+  const root = await mkdtemp(path.join(os.tmpdir(), "dsh-rtbundle-"));
+  const fakeBin = path.join(root, "bin");
+  const relayDir = path.join(root, "relay");
+  const fakeHome = path.join(root, "home");           // 必须伪造 HOME（见 setup-output.test.mjs 的静态护栏）
+  await mkdir(fakeBin, { recursive: true });
+  await mkdir(relayDir, { recursive: true });
+  await mkdir(fakeHome, { recursive: true });
+  const npxLog = path.join(root, "npx.log");
+  await writeFile(npxLog, "");
+  for (const name of ["npx", "npx.cmd"]) {
+    await writeFile(path.join(fakeBin, name), FAKE_NPX);
+    await chmodSync(path.join(fakeBin, name), 0o755);
+  }
+  const saved = {};
+  for (const k of ["HOME", "PATH", "DSH_TEST_NPX_LOG", "DSH_SETUP_NPX_DIR", "DSH_RELAY_SKIP_SERVICE",
+    "DSH_RELAY_PLATFORM", "DSH_REMOTE_TELEMETRY", "DSH_RELAY_DEFAULT_API", "DSH_RELAY_BUNDLED_RUNTIME"]) {
+    saved[k] = process.env[k];
+  }
+  process.env.HOME = fakeHome;
+  process.env.PATH = `${fakeBin}:${saved.PATH || ""}`;
+  process.env.DSH_TEST_NPX_LOG = npxLog;
+  process.env.DSH_SETUP_NPX_DIR = fakeBin;
+  process.env.DSH_RELAY_PLATFORM = "win32";        // 反馈来自 Windows；win32 分支不碰 launchctl
+  process.env.DSH_REMOTE_TELEMETRY = "0";
+  process.env.DSH_RELAY_DEFAULT_API = "http://127.0.0.1:1";
+  delete process.env.DSH_RELAY_SKIP_SERVICE;       // 走真实分支（npx 是假的）
+  // 默认指向不存在的目录：本机跑过 npm pack / npm publish 后 packages/dsh-remote-web/runtime 会存在，
+  // 那会让"没有自带运行环境"的用例前提失效（实测：全量套件里这条因此变红）。
+  process.env.DSH_RELAY_BUNDLED_RUNTIME = "/nonexistent-dsh-bundled";
+  return {
+    root, relayDir, npxLog,
+    async restore() {
+      for (const [k, v] of Object.entries(saved)) {
+        if (v === undefined) delete process.env[k]; else process.env[k] = v;
+      }
+      rmSync(root, { recursive: true, force: true });
+    },
+  };
+}
+
+function boot(relayDir) {
+  const routes = new Map();
+  const disposers = [];
+  apply({
+    webServer: { register(route) { routes.set(route.path, route.handler); return () => {}; } },
+    effect(register) { const d = register(); if (typeof d === "function") disposers.push(d); return d; },
+    logger: { info() {}, warn() {} },
+  }, { relayDir });
+  routes.dispose = () => { for (const d of disposers) { try { d(); } catch { /* 忽略 */ } } };
+  return routes;
+}
+
+async function serve(routes) {
+  const host = http.createServer((req, res) => {
+    const handler = routes.get(new URL(req.url, "http://x").pathname);
+    (handler || ((_r, rs) => { rs.writeHead(404); rs.end(); }))(req, res);
+  });
+  await new Promise((resolve) => host.listen(0, "127.0.0.1", resolve));
+  return { host, base: `http://127.0.0.1:${host.address().port}` };
+}
+
+/** 半装运行环境：入口在，且它**点名**的文件不在（这正是用户卡死的现场）。 */
+const HALF_INSTALL_ENTRY = `import { childStopped } from "./clients/dsh-remote/src/lifecycle.mjs";
+export const bridge = new URL("./clients/dsh-remote/dsh-bridge.mjs", import.meta.url);
+export { childStopped };
+`;
+
+test("打包脚本：产物完整（入口 + 点名文件 + ws）、不含 test/，且自检通过", async () => {
+  const out = await mkdtemp(path.join(os.tmpdir(), "dsh-runtime-out-"));
+  try {
+    const r = spawnSync(process.execPath, [BUNDLER, "--out", out], { encoding: "utf8" });
+    assert.equal(r.status, 0, `打包脚本必须成功：${r.stdout}${r.stderr}`);
+    for (const rel of [
+      "dsh-setup.mjs",
+      "clients/dsh-remote/dsh-bridge.mjs",
+      "clients/dsh-remote/src/lifecycle.mjs",
+      "node_modules/ws/package.json",
+    ]) {
+      assert.ok(existsSync(path.join(out, rel)), `产物缺 ${rel} —— 半装运行环境就是用户卡死的直接原因`);
+    }
+    assert.ok(!existsSync(path.join(out, "clients", "dsh-remote", "test")), "测试目录不该进运行时产物（体积）");
+    // 自检模式：发布门禁会用它
+    const chk = spawnSync(process.execPath, [BUNDLER, "--check", "--out", out], { encoding: "utf8" });
+    assert.equal(chk.status, 0, `自检必须通过：${chk.stdout}${chk.stderr}`);
+
+    // 反例：产物不完整时自检必须**失败**（宁可发布失败，也不发一个半装运行环境出去）
+    rmSync(path.join(out, "clients", "dsh-remote", "src", "lifecycle.mjs"));
+    const bad = spawnSync(process.execPath, [BUNDLER, "--check", "--out", out], { encoding: "utf8" });
+    assert.notEqual(bad.status, 0, "缺文件时自检必须非 0");
+    assert.match(String(bad.stderr || bad.stdout), /不完整/);
+  } finally { rmSync(out, { recursive: true, force: true }); }
+});
+
+test("打包契约：插件 package.json 声明了 runtime 与 prepack，且 runtime/ 不入库", () => {
+  const pkg = JSON.parse(readFileSync(PKG_JSON, "utf8"));
+  assert.ok(Array.isArray(pkg.files) && pkg.files.includes("runtime"),
+    "files 必须含 runtime，否则 npm pack / GitHub Release 资产里没有运行环境");
+  assert.match(String(pkg.scripts && pkg.scripts.prepack || ""), /bundle-runtime\.mjs/,
+    "prepack 必须在打包前生成 runtime/（发布流程依赖它）");
+  const gi = readFileSync(path.join(ROOT, ".gitignore"), "utf8");
+  assert.match(gi, /packages\/dsh-remote-web\/runtime\//,
+    "runtime/ 是构建产物：必须 gitignore，否则 dsh-setup.mjs/clients 会有两份互相漂移的副本");
+});
+
+test("半装运行环境 → 用插件自带的运行环境整份补齐，全程不碰 npx（Windows 装机失败类的根治）", async () => {
+  const out = await mkdtemp(path.join(os.tmpdir(), "dsh-runtime-src-"));
+  spawnSync(process.execPath, [BUNDLER, "--out", out], { encoding: "utf8" });
+  const env = await makeEnv();
+  process.env.DSH_RELAY_BUNDLED_RUNTIME = out;   // 必须早于 boot：apply() 里就会用自带运行环境补装
+  const routes = boot(env.relayDir);
+  const { host, base } = await serve(routes);
+  try {
+    // 半装：入口在、依赖不在 —— 旧实现会报「运行环境: 已就绪」，然后插起来的守护秒退
+    await writeFile(path.join(env.relayDir, "dsh-setup.mjs"), HALF_INSTALL_ENTRY);
+    await writeFile(path.join(env.relayDir, ".dsh-config.json"),
+      JSON.stringify({ phone: "13800000000", password: "pw", api_url: "http://127.0.0.1:1" }));
+    const r = await (await fetch(`${base}/dsh-remote/bridge-status`)).json();
+    assert.equal(r.connect.runtimeReady, true, "自带运行环境补齐后必须报就绪");
+    assert.deepEqual(r.connect.runtimeMissing, [], "补齐后不得再缺文件");
+    assert.ok(existsSync(path.join(env.relayDir, "clients", "dsh-remote", "src", "lifecycle.mjs")),
+      "入口点名的 lifecycle.mjs 必须被补齐（这正是半装运行环境缺的那个文件）");
+    assert.ok(existsSync(path.join(env.relayDir, "node_modules", "ws", "package.json")), "依赖 ws 必须一起就位");
+    assert.equal((await readOrEmpty(path.join(env.relayDir, ".dsh-setup-version"))).trim(),
+      JSON.parse(readFileSync(PKG_JSON, "utf8")).version, "运行时版本标记必须等于插件版本（不再出现版本错配）");
+    assert.equal((await readOrEmpty(env.npxLog)).trim(), "",
+      "该走本地拷贝时**一次 npx 都不该调**（npx 正是 Windows 上的失败源）");
+    assert.match(await readOrEmpty(path.join(env.relayDir, ".dsh-setup-install.log")), /自带的运行环境就地补齐/);
+  } finally {
+    host.close(); routes.dispose(); await env.restore();
+    rmSync(out, { recursive: true, force: true });
+  }
+});
+
+test("自带运行环境本身不完整 → 老实回落到 npx（绝不假装补齐成功）", async () => {
+  const broken = await mkdtemp(path.join(os.tmpdir(), "dsh-runtime-broken-"));
+  const env = await makeEnv();
+  process.env.DSH_RELAY_BUNDLED_RUNTIME = broken; // 同上：apply() 先试自带、失败再落 npx
+  const routes = boot(env.relayDir);
+  const { host, base } = await serve(routes);
+  try {
+    // 「自带」目录只放入口、不放依赖 → 拷贝后自检必然失败
+    await writeFile(path.join(broken, "dsh-setup.mjs"), HALF_INSTALL_ENTRY);
+    await writeFile(path.join(env.relayDir, "dsh-setup.mjs"), HALF_INSTALL_ENTRY);
+    await writeFile(path.join(env.relayDir, ".dsh-config.json"),
+      JSON.stringify({ phone: "13800000000", password: "pw", api_url: "http://127.0.0.1:1" }));
+    await fetch(`${base}/dsh-remote/bridge-status`);
+    assert.ok(await waitFor(async () => (await readOrEmpty(env.npxLog)).includes("@mrrisega/dsh-remote")),
+      "自带运行环境不完整时必须回落 npx 补装，实际 npx 日志：" + (await readOrEmpty(env.npxLog)));
+    assert.match(await readOrEmpty(path.join(env.relayDir, ".dsh-setup-install.log")), /仍不完整/);
+  } finally {
+    host.close(); routes.dispose(); await env.restore();
+    rmSync(broken, { recursive: true, force: true });
+  }
+});