helixlife-v5-cli 1.2.8 → 1.2.9

package/lib/visual.js

@@ -1,66 +1,185 @@
-'use strict';
+"use strict";
 
-const fs = require('node:fs');
-const path = require('node:path');
+const fs = require("node:fs");
+const path = require("node:path");
 
-const INIT_SCRIPT_PATH = path.join(__dirname, 'automation-overlay.init.js');
-const GENERATED_CONFIG_PATH = path.join(__dirname, '.cli.runtime.generated.json');
+const { wrapRunCodeTokens } = require("./visual-page-wrap");
+const { applyNativeBrowserOverrides } = require("./runtime-config");
+const { runUploadCommandWithGuard } = require("./automation-file-chooser-guard");
+
+const INIT_SCRIPT_PATH = path.join(__dirname, "automation-overlay.init.js");
+const INIT_PAGE_MAXIMIZE_PATH = path.join(
+  __dirname,
+  "browser-window-maximize.init-page.js",
+);
+const INIT_PAGE_CSS_GUARD_PATH = path.join(
+  __dirname,
+  "browser-css-cache-guard.init-page.js",
+);
+const GENERATED_CONFIG_PATH = path.join(
+  __dirname,
+  ".cli.runtime.generated.json",
+);
 
 /** 默认开启页面内视觉反馈；HELIX_VISUAL=0 可全局关闭 */
-const DEFAULT_VISUAL_ENABLED = process.env.HELIX_VISUAL !== '0';
+const DEFAULT_VISUAL_ENABLED = process.env.HELIX_VISUAL !== "0";
+/** 反馈层常驻不消失；HELIX_VISUAL_PERSIST=1 或 --visual-persist */
+const DEFAULT_VISUAL_PERSIST = process.env.HELIX_VISUAL_PERSIST === "1";
 
 const VISUAL_COMMANDS = {
-  click: { pending: '正在点击', success: '已点击', pendingTone: 'pending', successTone: 'success' },
-  dblclick: { pending: '正在双击', success: '已双击', pendingTone: 'pending', successTone: 'success' },
-  fill: { pending: '正在填写', success: '已填写', pendingTone: 'pending', successTone: 'success' },
-  hover: { pending: '正在悬停', success: '已悬停', pendingTone: 'info', successTone: 'info' },
-  check: { pending: '正在勾选', success: '已勾选', pendingTone: 'pending', successTone: 'success' },
-  uncheck: { pending: '正在取消勾选', success: '已取消勾选', pendingTone: 'pending', successTone: 'info' },
-  select: { pending: '正在选择', success: '已选择', pendingTone: 'pending', successTone: 'success' },
-  drag: { pending: '正在拖拽', success: '已拖拽', pendingTone: 'pending', successTone: 'success' },
-  drop: { pending: '正在放置', success: '已放置', pendingTone: 'pending', successTone: 'success' },
-  upload: { hudOnly: true, pending: '正在上传', success: '已上传', pendingTone: 'pending', successTone: 'success' },
-  press: { hudOnly: true, pending: '按键', success: '按键完成', pendingTone: 'info', successTone: 'success' },
-  type: { hudOnly: true, pending: '正在输入', success: '输入完成', pendingTone: 'pending', successTone: 'success' },
+  click: {
+    pending: "正在点击",
+    success: "已点击",
+    pendingTone: "pending",
+    successTone: "success",
+  },
+  dblclick: {
+    pending: "正在双击",
+    success: "已双击",
+    pendingTone: "pending",
+    successTone: "success",
+  },
+  fill: {
+    pending: "正在填写",
+    success: "已填写",
+    pendingTone: "pending",
+    successTone: "success",
+  },
+  hover: {
+    pending: "正在悬停",
+    success: "已悬停",
+    pendingTone: "info",
+    successTone: "info",
+  },
+  check: {
+    pending: "正在勾选",
+    success: "已勾选",
+    pendingTone: "pending",
+    successTone: "success",
+  },
+  uncheck: {
+    pending: "正在取消勾选",
+    success: "已取消勾选",
+    pendingTone: "pending",
+    successTone: "info",
+  },
+  select: {
+    pending: "正在选择",
+    success: "已选择",
+    pendingTone: "pending",
+    successTone: "success",
+  },
+  drag: {
+    pending: "正在拖拽",
+    success: "已拖拽",
+    pendingTone: "pending",
+    successTone: "success",
+  },
+  drop: {
+    pending: "正在放置",
+    success: "已放置",
+    pendingTone: "pending",
+    successTone: "success",
+  },
+  upload: {
+    hudOnly: true,
+    pending: "正在上传",
+    success: "已上传",
+    pendingTone: "pending",
+    successTone: "success",
+  },
+  press: {
+    hudOnly: true,
+    pending: "按键",
+    success: "按键完成",
+    pendingTone: "info",
+    successTone: "success",
+  },
+  type: {
+    hudOnly: true,
+    pending: "正在输入",
+    success: "输入完成",
+    pendingTone: "pending",
+    successTone: "success",
+  },
+  "run-code": {
+    hudOnly: true,
+    pending: "脚本执行中",
+    success: "脚本完成",
+    pendingTone: "pending",
+    successTone: "success",
+  },
 };
 
-const SESSION_START_COMMANDS = new Set(['open', 'attach']);
+const SESSION_START_COMMANDS = new Set(["open", "attach"]);
 
 function readInitScriptSource() {
-  return fs.readFileSync(INIT_SCRIPT_PATH, 'utf8');
+  return fs.readFileSync(INIT_SCRIPT_PATH, "utf8");
 }
 
-function resolveGeneratedConfigPath() {
-  const payload = {
-    browser: {
-      initScript: [INIT_SCRIPT_PATH.replace(/\\/g, '/')],
-    },
-  };
-  fs.writeFileSync(GENERATED_CONFIG_PATH, JSON.stringify(payload, null, 2), 'utf8');
+function isHeadedOpen(tokens) {
+  return tokens.some((t) => t === "--headed" || t.startsWith("--headed="));
+}
+
+function buildRuntimeBrowserConfig(visualEnabled, tokens) {
+  let browser = {};
+  const cmd = resolveCommandName(tokens);
+  if (cmd === "open" && isHeadedOpen(tokens)) {
+    browser.launchOptions = { args: ["--start-maximized"] };
+    browser.initPage = [
+      INIT_PAGE_MAXIMIZE_PATH.replace(/\\/g, "/"),
+      INIT_PAGE_CSS_GUARD_PATH.replace(/\\/g, "/"),
+    ];
+  }
+  if (visualEnabled) {
+    browser.initScript = [INIT_SCRIPT_PATH.replace(/\\/g, "/")];
+  }
+  // 合并原生交互模式 overrides（acceptDownloads / chromiumSandbox / downloadsPath）。
+  // applyNativeBrowserOverrides 不会覆盖已显式设值的字段。
+  browser = applyNativeBrowserOverrides(browser);
+  return browser;
+}
+
+function resolveGeneratedConfigPath(
+  visualEnabled = DEFAULT_VISUAL_ENABLED,
+  tokens = [],
+) {
+  const browser = buildRuntimeBrowserConfig(visualEnabled, tokens);
+  const payload = Object.keys(browser).length > 0 ? { browser } : {};
+  fs.writeFileSync(
+    GENERATED_CONFIG_PATH,
+    JSON.stringify(payload, null, 2),
+    "utf8",
+  );
   return GENERATED_CONFIG_PATH;
 }
 
 /**
  * 从 argv 中提取并剥离 --visual / --no-visual / --visual-ms。
- * @returns {{ tokens: string[], visual: { enabled: boolean, durationMs: number | null } }}
+ * @returns {{ tokens: string[], visual: { enabled: boolean, durationMs: number | null, persist?: boolean } }}
  */
 function parseVisualFlags(tokens) {
   const visual = {
     enabled: DEFAULT_VISUAL_ENABLED,
     durationMs: null,
   };
+  if (DEFAULT_VISUAL_PERSIST) visual.persist = true;
   const out = [];
   for (let i = 0; i < tokens.length; i += 1) {
     const t = tokens[i];
-    if (t === '--visual') {
+    if (t === "--visual") {
       visual.enabled = true;
-    } else if (t === '--no-visual') {
+    } else if (t === "--no-visual") {
       visual.enabled = false;
-    } else if (t === '--visual-ms') {
+    } else if (t === "--visual-persist") {
+      visual.persist = true;
+    } else if (t === "--no-visual-persist") {
+      visual.persist = false;
+    } else if (t === "--visual-ms") {
       visual.durationMs = tokens[i + 1];
       i += 1;
-    } else if (t.startsWith('--visual-ms=')) {
-      visual.durationMs = t.slice('--visual-ms='.length);
+    } else if (t.startsWith("--visual-ms=")) {
+      visual.durationMs = t.slice("--visual-ms=".length);
     } else {
       out.push(t);
     }
@@ -68,7 +187,12 @@ function parseVisualFlags(tokens) {
   if (visual.durationMs != null) {
     const n = Number(visual.durationMs);
     if (!Number.isFinite(n) || n <= 0) {
-      throw Object.assign(new Error(`--visual-ms 需要正数，收到 ${JSON.stringify(visual.durationMs)}`), { code: 'E_BAD_ARG' });
+      throw Object.assign(
+        new Error(
+          `--visual-ms 需要正数，收到 ${JSON.stringify(visual.durationMs)}`,
+        ),
+        { code: "E_BAD_ARG" },
+      );
     }
     visual.durationMs = Math.round(n);
   }
@@ -76,36 +200,35 @@ function parseVisualFlags(tokens) {
 }
 
 function hasConfigFlag(tokens) {
-  return tokens.some((t) => t === '--config' || t.startsWith('--config='));
+  return tokens.some((t) => t === "--config" || t.startsWith("--config="));
 }
 
 /**
- * open / attach 时自动注入 initScript 配置，使新页面预装视觉层。
+ * open / attach 时注入运行时配置：有头 open 最大化窗口；visual 开启时预装视觉层 initScript。
  */
 function injectVisualConfig(tokens, visual) {
-  if (!visual.enabled) return tokens;
   const cmd = resolveCommandName(tokens);
   if (!SESSION_START_COMMANDS.has(cmd) || hasConfigFlag(tokens)) {
     return tokens;
   }
-  const configPath = resolveGeneratedConfigPath();
+  const configPath = resolveGeneratedConfigPath(visual.enabled, tokens);
   return [...tokens, `--config=${configPath}`];
 }
 
 function resolveCommandName(tokens) {
   let i = 0;
-  if (tokens[i] === '--raw') i += 1;
-  if (tokens[i] === '--json') i += 1;
-  if (tokens[i] && tokens[i].startsWith('-s=')) i += 1;
-  return tokens[i] || '';
+  if (tokens[i] === "--raw") i += 1;
+  if (tokens[i] === "--json") i += 1;
+  if (tokens[i] && tokens[i].startsWith("-s=")) i += 1;
+  return tokens[i] || "";
 }
 
 function isElementRef(token) {
-  if (!token || token.startsWith('-')) return false;
+  if (!token || token.startsWith("-")) return false;
   if (/^e\d+$/.test(token)) return true;
   if (token.startsWith('"') || token.startsWith("'")) return true;
-  if (token.startsWith('#') || token.startsWith('.')) return true;
-  if (token.startsWith('getBy')) return true;
+  if (token.startsWith("#") || token.startsWith(".")) return true;
+  if (token.startsWith("getBy")) return true;
   return false;
 }
 
@@ -119,29 +242,33 @@ function extractElementTarget(tokens) {
   if (def.hudOnly) return null;
 
   let i = 0;
-  if (tokens[i] === '--raw') i += 1;
-  if (tokens[i] === '--json') i += 1;
-  if (tokens[i] && tokens[i].startsWith('-s=')) i += 1;
+  if (tokens[i] === "--raw") i += 1;
+  if (tokens[i] === "--json") i += 1;
+  if (tokens[i] && tokens[i].startsWith("-s=")) i += 1;
   i += 1; // skip command name
 
   const positional = [];
   for (; i < tokens.length; i += 1) {
     const t = tokens[i];
-    if (t.startsWith('--')) {
-      if (t.includes('=')) continue;
+    if (t.startsWith("--")) {
+      if (t.includes("=")) continue;
       const next = tokens[i + 1];
-      if (next !== undefined && !next.startsWith('-')) i += 1;
+      if (next !== undefined && !next.startsWith("-")) i += 1;
       continue;
     }
     positional.push(t);
   }
 
-  if (cmd === 'drag' && positional.length >= 1) return positional[0];
-  if (cmd === 'fill' && positional.length >= 1) return positional[0];
-  if (cmd === 'select' && positional.length >= 1) return positional[0];
-  if (cmd === 'drop' && positional.length >= 1) return positional[0];
-  if (positional.length >= 1 && isElementRef(positional[0])) return positional[0];
-  if (positional.length >= 2 && isElementRef(positional[positional.length - 1])) {
+  if (cmd === "drag" && positional.length >= 1) return positional[0];
+  if (cmd === "fill" && positional.length >= 1) return positional[0];
+  if (cmd === "select" && positional.length >= 1) return positional[0];
+  if (cmd === "drop" && positional.length >= 1) return positional[0];
+  if (positional.length >= 1 && isElementRef(positional[0]))
+    return positional[0];
+  if (
+    positional.length >= 2 &&
+    isElementRef(positional[positional.length - 1])
+  ) {
     return positional[positional.length - 1];
   }
   return null;
@@ -150,7 +277,7 @@ function extractElementTarget(tokens) {
 function buildFlashEval(target, options) {
   const optsLit = JSON.stringify(options);
   return [
-    'eval',
+    "eval",
     `el => { const v = window.__helix_visual__; if (!v) return false; return v.flash(el, ${optsLit}); }`,
     target,
   ];
@@ -158,24 +285,32 @@ function buildFlashEval(target, options) {
 
 function buildHudEval(options) {
   const optsLit = JSON.stringify(options);
-  return ['eval', `() => { const v = window.__helix_visual__; if (!v) return false; return v.showHud(${optsLit}); }`];
+  return [
+    "eval",
+    `() => { const v = window.__helix_visual__; if (!v) return false; return v.showHud(${optsLit}); }`,
+  ];
 }
 
 function buildSetOptionsEval(visual) {
-  const payload = JSON.stringify({
+  const payload = {
     enabled: visual.enabled,
     durationMs: visual.durationMs,
-  });
-  return ['eval', `() => { const v = window.__helix_visual__; if (!v) return null; return v.setVisualOptions(${payload}); }`];
+  };
+  if (typeof visual.persist === "boolean") payload.persist = visual.persist;
+  const payloadLit = JSON.stringify(payload);
+  return [
+    "eval",
+    `() => { const v = window.__helix_visual__; if (!v) return null; return v.setVisualOptions(${payloadLit}); }`,
+  ];
 }
 
 function buildInstallEval() {
   const src = readInitScriptSource();
-  return ['eval', src];
+  return ["eval", src];
 }
 
 function buildBridgeCheckEval() {
-  return ['eval', '--raw', 'Boolean(window.__helix_visual__)'];
+  return ["eval", "--raw", "Boolean(window.__helix_visual__)"];
 }
 
 function shouldWrapWithVisual(tokens, visual) {
@@ -193,56 +328,90 @@ function shouldWrapWithVisual(tokens, visual) {
 async function runWithVisualFeedback(tokens, visual, runPassthrough) {
   const cmd = resolveCommandName(tokens);
   const def = VISUAL_COMMANDS[cmd];
-  const target = extractElementTarget(tokens);
 
   const runCapture = (args) => runPassthrough(args, { capture: true });
 
   const check = runCapture(buildBridgeCheckEval());
-  if (String(check.stdout || '').trim() !== 'true') {
+  if (String(check.stdout || "").trim() !== "true") {
     runCapture(buildInstallEval());
   }
+
+  if (cmd === "run-code") {
+    runCapture(
+      buildSetOptionsEval({
+        enabled: visual.enabled,
+        durationMs: visual.durationMs,
+      }),
+    );
+    let wrappedTokens;
+    try {
+      wrappedTokens = wrapRunCodeTokens(tokens, readInitScriptSource());
+    } catch (e) {
+      console.error(`[helixlife-v5-cli] run-code 视觉包装失败: ${e.message}`);
+      return runPassthrough(tokens);
+    }
+    return runPassthrough(wrappedTokens);
+  }
+
+  const target = extractElementTarget(tokens);
   runCapture(buildSetOptionsEval(visual));
 
-  const hudBase = { action: cmd, target: target || '', status: 'pending' };
+  const hudBase = { action: cmd, target: target || "", status: "pending" };
   runCapture(buildHudEval({ ...hudBase, detail: def.pending }));
 
   if (target) {
-    runCapture(buildFlashEval(target, {
-      tone: def.pendingTone || 'pending',
-      label: def.pending,
-      durationMs: visual.durationMs,
-    }));
+    runCapture(
+      buildFlashEval(target, {
+        tone: def.pendingTone || "pending",
+        label: def.pending,
+        durationMs: visual.durationMs,
+      }),
+    );
   }
 
-  const code = runPassthrough(tokens);
+  const nativeFileChooser =
+    process.env.HELIX_NATIVE_FILE_CHOOSER === undefined ||
+    process.env.HELIX_NATIVE_FILE_CHOOSER === "1";
+
+  const code =
+    nativeFileChooser && (cmd === "upload" || cmd === "drop")
+      ? runUploadCommandWithGuard(tokens, runPassthrough)
+      : runPassthrough(tokens);
 
-  const successTone = code === 0 ? (def.successTone || 'success') : 'danger';
-  const successLabel = code === 0 ? def.success : '操作失败';
+  const successTone = code === 0 ? def.successTone || "success" : "danger";
+  const successLabel = code === 0 ? def.success : "错误";
   runCapture(buildSetOptionsEval(visual));
   if (target) {
-    runCapture(buildFlashEval(target, {
-      tone: successTone,
-      label: successLabel,
-      durationMs: visual.durationMs,
-    }));
+    runCapture(
+      buildFlashEval(target, {
+        tone: successTone,
+        label: successLabel,
+        durationMs: visual.durationMs,
+      }),
+    );
   }
-  runCapture(buildHudEval({
-    action: cmd,
-    target: target || '',
-    status: code === 0 ? 'success' : 'danger',
-    detail: successLabel,
-  }));
+  runCapture(
+    buildHudEval({
+      action: cmd,
+      target: target || "",
+      status: code === 0 ? "success" : "danger",
+      detail: successLabel,
+    }),
+  );
 
   return code;
 }
 
 module.exports = {
   INIT_SCRIPT_PATH,
+  INIT_PAGE_MAXIMIZE_PATH,
   VISUAL_COMMANDS,
   DEFAULT_VISUAL_ENABLED,
+  DEFAULT_VISUAL_PERSIST,
   parseVisualFlags,
   injectVisualConfig,
   shouldWrapWithVisual,
   runWithVisualFeedback,
+  resolveCommandName,
   resolveGeneratedConfigPath,
 };

package/package.json

@@ -1,34 +1,22 @@
 {
   "name": "helixlife-v5-cli",
-  "version": "1.2.8",
-  "description": "Helix（vip.helixlife.cn）精细化浏览器自动化命令行工具。",
-  "main": "helix-cli.js",
+  "version": "1.2.9",
+  "description": "Helix site (vip.helixlife.cn) browser automation CLI",
   "bin": {
     "helixlife-v5-cli": "helix-cli.js"
   },
+  "files": [
+    "helix-cli.js",
+    "lib/",
+    "scripts/"
+  ],
   "engines": {
     "node": ">=18"
   },
-  "keywords": [
-    "helixlife",
-    "cli",
-    "playwright",
-    "cdp"
-  ],
-  "author": "",
-  "license": "ISC",
-  "type": "commonjs",
   "scripts": {
-    "start": "node ./helix-cli.js helix doctor"
+    "postinstall": "node lib/postinstall.js"
   },
-  "files": [
-    "references",
-    "scripts",
-    "helix-cli.js",
-    "lib",
-    "README.md"
-  ],
   "dependencies": {
-    "@playwright/cli": "^0.1.9"
+    "@playwright/cli": "0.1.14"
   }
 }

package/scripts/README.md

@@ -0,0 +1,81 @@
+# Helix 可复用 `run-code` 脚本目录
+
+> 均通过 `helixlife-v5-cli run-code --filename="<CLI_PKG_ROOT>/scripts/<模块>/<脚本>"` 调用。  
+> `<CLI_PKG_ROOT>` 为全局安装的 npm 包根目录（见 Skill 仓库 `SKILL.md` 路径解析）。
+
+**Agent 选用规则**：勿扫描本目录猜脚本。先 `Read` Skill 仓库 `references/vip.helixlife.cn.site-ops.md` → 定向读目标模块 `references/*.md` → 按模块文档内的脚本表调用；本文件仅为总索引。
+
+## 目录结构
+
+| 目录 | 对应 references 模块 | 说明 |
+| --- | --- | --- |
+| [`common/`](./common/) | `vip.helixlife.cn.common.md` | 跨模块通用脚本（当前为空，预留） |
+| [`edu/`](./edu/) | `vip.helixlife.cn.edu.md` | 学习中心 · 课件 PDF、搜索卡片 hover |
+| [`analysis/`](./analysis/) | `analysis/browser.md` | 数据分析 · 浏览器通道：工具详情上传、拼图工具（后台 CLI 见 `references/analysis/backend-cli.md`） |
+| [`workbench/jova/`](./workbench/jova/) | `workbench/jova/MODULE.md` | 综述工作台全流程 |
+
+## 脚本清单
+
+### `common/`
+
+（暂无）
+
+### `edu/`
+
+| 脚本 | 作用 |
+| --- | --- |
+| `chrome-pdf-goto-page.js` | PDF 页码跳转（改 `target`） |
+| `chrome-pdf-zoom-out.js` | PDF 缩小 |
+| `chrome-pdf-enumerate-a11y.js` | 枚举 PDF 阅读器 `aria-label`（排障） |
+| `hover-partial-chapter-match.js` | 搜索结果「部分章节匹配」hover |
+
+### `analysis/`（仅浏览器通道 · 后台 CLI 勿用）
+
+> 细则见 `references/analysis/browser.md`。后台 `xt` 任务见 `references/analysis/backend-cli.md`，**禁止**调用本目录脚本。
+
+| 脚本 | 作用 |
+| --- | --- |
+| `detail-upload-file.js` | 工具详情 · 单参数上传（filechooser） |
+| `detail-upload-both.js` | 工具详情 · 多参数顺序上传（setInputFiles） |
+| `jigsaw-verify-drag-tool.js` | 拼图 · 拖图并验收下载解禁 |
+| `jigsaw-verify-enumerate.js` | 拼图 · ABC 字段枚举 |
+| `jigsaw-verify-reference-lines.js` | 拼图 · 参考线操作 |
+| `jigsaw-verify-bio-tools.js` | 拼图 · 生信工具枚举 |
+| `jigsaw-inspect-dom.js` | 拼图 · DOM 排障 |
+
+### `workbench/jova/`
+
+| 脚本 | 作用 |
+| --- | --- |
+| `outline-ops.js` | 提纲树标准操作（含节点重新生成，CONFIG） |
+| `outline-edit-root-title.js` | 编辑根标题 |
+| `outline-keyword-edit.js` | 关键词编辑 |
+| `outline-probe-hover.js` | 节点 hover 探测（排障） |
+| `proofread-ops.js` | 校对页标准操作（含单段确认校对，CONFIG） |
+| `proofread-ai-rewrite-section.js` | 单段 AI 改写 / 段落重写面板 |
+| `writing-ops.js` | 精修页标准操作（含右侧功能面板，CONFIG） |
+| `writing-proofread-abstract.js` | 摘要段校对/精修 |
+
+完整说明见 [`references/workbench/jova/MODULE.md`](../references/workbench/jova/MODULE.md) 末尾表格。
+
+#### 计划提供（`workbench/jova/` · 暂未落地）
+
+| 计划脚本 | 作用 | 当前临时替代 |
+| --- | --- | --- |
+| `outline-regenerate-node.js` | 节点级「重新生成」 | `outline-ops.js` CONFIG |
+| `proofread-section.js` | 单段确认校对 | `proofread-ops.js` CONFIG |
+| `writing-tool.js` | 右侧功能面板单脚本 | `writing-ops.js` CONFIG |
+
+磁盘暂无上述文件，**勿调用**；落地后移入上表「已提供」并删本小节。
+
+## 维护者专用（Agent 勿用）
+
+| 路径 | 说明 |
+| --- | --- |
+| `maintainer/strip-extra-skills.ps1` | 打包时剔除 `node_modules` 内多余 `SKILL.md`，非站点自动化 |
+
+## 扩展约定
+
+- 新增脚本放入对应模块目录；跨模块复用放 `common/`。
+- AI 工作台其他子工作台（sci / nsfc / clinical）后续脚本放 `workbench/<slug>/`。
+- 文件名去掉模块前缀（目录已表达归属），例如 `outline-ops.js` 而非 `workbench-jova-outline-ops.js`。

package/scripts/{analysis-detail-upload-file.js → analysis/detail-upload-file.js}

@@ -6,7 +6,7 @@
  * 3) 弹窗内 button「确认」
  *
  * 修改 filePath / paramLabel 后执行：
- *   helixlife-v5-cli run-code --filename=scripts/analysis-detail-upload-file.js
+ *   helixlife-v5-cli run-code --filename=scripts/analysis/detail-upload-file.js
  */
 async page => {
   const filePath = 'C:/Users/zouyh/Desktop/helix-test-upload.csv';

package/scripts/{jigsaw-inspect-dom.js → analysis/jigsaw-inspect-dom.js}

@@ -1,15 +1,15 @@
-async page => {
-  return page.evaluate(() => {
-    const root = document.querySelector('.jigsaw');
-    if (!root) return null;
-    const walk = (el, depth = 0) => {
-      if (depth > 4) return null;
-      return {
-        tag: el.tagName,
-        cls: (el.className || '').toString().slice(0, 80),
-        ch: [...el.children].slice(0, 8).map(c => walk(c, depth + 1)),
-      };
-    };
-    return [...root.children].map(c => walk(c, 0));
-  });
-}
+async page => {
+  return page.evaluate(() => {
+    const root = document.querySelector('.jigsaw');
+    if (!root) return null;
+    const walk = (el, depth = 0) => {
+      if (depth > 4) return null;
+      return {
+        tag: el.tagName,
+        cls: (el.className || '').toString().slice(0, 80),
+        ch: [...el.children].slice(0, 8).map(c => walk(c, depth + 1)),
+      };
+    };
+    return [...root.children].map(c => walk(c, 0));
+  });
+}

package/scripts/{jigsaw-verify-enumerate.js → analysis/jigsaw-verify-enumerate.js}

@@ -1,4 +1,4 @@
-/** 拼图工具页 · 非破坏性枚举。helixlife-v5-cli run-code --filename=scripts/jigsaw-verify-enumerate.js */
+/** 拼图工具页 · 非破坏性枚举。helixlife-v5-cli run-code --filename=scripts/analysis/jigsaw-verify-enumerate.js */
 async page => {
   const main = page.locator('main');
   const out = {

package/scripts/{chrome-pdf-enumerate-a11y.js → edu/chrome-pdf-enumerate-a11y.js}

@@ -1,6 +1,6 @@
 /**
  * 枚举当前 PDF 阅读器帧内带 aria-label 的节点（排障 / 对照 site-ops 控件表）。
- * 运行：helixlife-v5-cli run-code --filename=scripts/chrome-pdf-enumerate-a11y.js
+ * 运行：helixlife-v5-cli run-code --filename=scripts/edu/chrome-pdf-enumerate-a11y.js
  */
 async page => {
   const PDF_VIEWER_PREFIX = 'chrome-extension://mhjfbmdgcfjbbpaeojofohoefgiehjai';