@dsh-fly/dsh-plugin-fly-mode 0.1.7 → 0.1.9

package/README.md

@@ -11,8 +11,8 @@
   - **Fly 标准模式** `preset-fly-standard`（行表 = **上游 `standard` 的行表** + 一行 smart，33 行）——
     由生成器从**引擎自己的组合结果**里取上游行表（不手抄），所以引擎升级后行表跟着走、漂了 `--check` 会红。
   其中
-  **7 个 Fly 工具**（binary / reverse / pwn / diag / recon / blackbox / guard）的源码**内联在包内
-  `tools/`**，行表用**本包子路径**引用它们 —— 装这个包**不会**在 npm 上再拉这 7 个包；
+  **8 个 Fly 工具**（binary / reverse / pwn / diag / recon / blackbox / artifact / guard）的源码**内联在包内
+  `tools/`**，行表用**本包子路径**引用它们 —— 装这个包**不会**在 npm 上再拉这 8 个包；
   **`fly-smart` 单独一个 plugin**：它是本包 `dependencies` 里**唯一**一项，行表保持裸名，
   由 npm 装进 profile 的 `node_modules`（它变化最快，且与工作台面板是一个整体，不适合内联）。
 - **不是**：不带 `dsh.client`（模式是 agent 平面，没有浏览器半边）；不带 Fly 工作台
@@ -76,7 +76,7 @@ dsh plugin --profile=web add @dsh-fly/dsh-plugin-fly-mode@0.1.3 --registry=https
 
 ## 仓库状态（2026-10-11）
 
-- 形状定稿：一条 `- insert:` 声明 + 包内 `tools/`（7 个工具内联，行表用本包子路径引用）+
+- 形状定稿：一条 `- insert:` 声明 + 包内 `tools/`（8 个工具内联，行表用本包子路径引用）+
   `dsh-plugin-fly-smart` 作为**唯一** npm 依赖。声明由 `dsh-fly` 仓的
   `scripts/build-fly-mode-bundle.mjs` 生成，门禁用 `--check` 断漂移（含多出来的文件）。
 - `.github/workflows/{ci,release}.yml` **已适配本仓**（纯声明包：不装依赖、直接跑

package/cordis.patch.yml

@@ -5,7 +5,6 @@
 # 是同一条）；8 个工具的行名被改写成**本包的子路径**（tools/**，随包一起发布）。
 # 门禁用 --check 断言本文件与 tools/** 都 == 生成器输出。
 # 不含三模型路由（用户机器状态）、不写 registry default（默认归上游 standard）。
-- insert:
 - insert:
     - id: preset-fly
       name: '@deepseek-ai/dsh-agent-preset'
@@ -177,12 +176,10 @@
 
                         When ready, call exit_plan_mode with the complete plan markdown, starting with a # title. Make exit_plan_mode the only and final tool call in that assistant response: it presents the plan for approval, and implementation begins only in a later step after approval. Do not paste the final plan as a plain reply or ask "should I proceed?" through prose or ask_user_question. If review rejects it, incorporate the feedback and present again. If the review channel is unavailable or aborted, stay in plan mode and ask the user to switch modes manually; do not proceed with implementation.
 
-              # 评审姿态（docs/fly-review-mode-plan.md）：`/review` 开关一段只读引导（先讲阻塞问题、
               # 每条结论带 path:line 证据），收口工具 `exit_review_mode` 把判词交用户裁决。
               # 形状与上面的 plan-mode 同族：姿态的效果就是一段引导 ⇒ 进/出只改提示词段、不改工具目录；
               # 状态记会话日志 ⇒ resume / fork 不丢。**只读是引导、不是强制**（沙箱与审批策略独立执行）。
               # 行保持**裸名**（内联形状的契约）：生成器认这个裸名，再把它改写成模式包内的
-              # `dsh-plugin-fly-mode/tools/dsh-plugin-fly-review/index.js`（同那 8 个内联工具行）；
               # 包内的源码布局则是 `tools/index.js`（内联器照这个路径拷贝）。
           # ── compaction ──────────────────────────────────────────────────────────────
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dsh-fly/dsh-plugin-fly-mode",
-  "version": "0.1.7",
-  "description": "Fly 模式作为一个可安装的包：**两个 preset** —— Fly 安全模式（preset-fly，7 个安全工具内联 + smart）与 Fly 标准模式（preset-fly-standard，上游 standard 的行表 + smart，无安全工具）；依赖单独发布的 dsh-plugin-fly-smart。",
+  "version": "0.1.9",
+  "description": "Fly 模式作为一个可安装的包：**两个 preset** —— Fly 安全模式（preset-fly，8 个安全工具内联 + smart）与 Fly 标准模式（preset-fly-standard，上游 standard 的行表 + smart，无安全工具）；依赖单独发布的 dsh-plugin-fly-smart。",
   "type": "module",
   "license": "MIT",
   "repository": {

package/tools/dsh-plugin-fly-artifact/index.js

@@ -39,6 +39,12 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
  *
  * 两个入口都在 P1 的"结论要能回指源码位置"那条要求下：清单的每条成员给**相对路径**，
  * 边界的每条命中给 **file:line**。
+ *
+ * **起因**（为什么这个包存在）：`morluto/rea` 那边有 APK/JADX、固件/Binwalk、.NET、**JS/ASAR 与 HAR**
+ * 这些"看得懂打包产物"的能力，而 fly 这边此前只有原生二进制三件套 —— 一个 Electron 应用的
+ * 150MB `app.asar` 摆在面前，只能靠 `bin_strings` 碰运气。安全模式的定位是客户端黑盒排查，
+ * 所以这一面必须在拆仓之前补上（规划 §3.2）：先把"清单 + 字面量边界"两层做出来，
+ * 再谈 AST 与 CDP（P2）。**不抄代码，只在设计上对齐**（分层、覆盖率、bounds 三件）。
  */
 
 export const name = 'fly-artifact'
@@ -59,6 +65,19 @@ function shq(value) {
  * version. `scripts/verify-security-tools.mjs` now fails loudly if a call site
  * names a seam method the executor does not have.
  */
+/**
+ * 路径参数规范化：以 `-` 开头的路径加 `./` 前缀（2026-10-13）。
+ *
+ * 为什么不插 `--`：实测本机（macOS，发布目标平台）**objdump（-h/-d/-T）/ base64 -i / otool -hv 都不支持
+ * `--`**，插进去直接失败；而 `file -b --version` 会打印 `file-5.41`、`nm -u --version` 会打印
+ * `llvm-nm, …`，两者都 **exit 0** ⇒ 工具会把版本串当**数据**返回。加 `./` 之后它就是一个普通相对路径：
+ * 不存在就正常报错，存在就是那个文件。
+ */
+function safePath(value) {
+  const text = String(value ?? '')
+  return text.startsWith('-') ? './' + text : text
+}
+
 async function runCmd(shell, argv, exec, opts = {}) {
   const result = await (await shell.execute(shell.resolve({
     command: argv.map(shq).join(' '),
@@ -632,7 +651,7 @@ export function apply(ctx) {
     },
     output: stringOutput,
     async execute(args, exec) {
-      const path = typeof args.path === 'string' ? args.path.trim() : ''
+      const path = safePath(typeof args.path === 'string' ? args.path.trim() : '')
       if (path === '') throw new Error('artifact_asar_inventory 需要 path（.asar 的路径）')
       const top = readTop(args.top, 'artifact_asar_inventory')
 
@@ -770,7 +789,7 @@ export function apply(ctx) {
     },
     output: stringOutput,
     async execute(args, exec) {
-      const path = typeof args.path === 'string' ? args.path.trim() : ''
+      const path = safePath(typeof args.path === 'string' ? args.path.trim() : '')
       if (path === '') throw new Error('artifact_js_boundaries 需要 path（.asar 的路径，或解包后的 JS 目录）')
       const top = readTop(args.top, 'artifact_js_boundaries')
       const scope = args.scope === undefined ? 'app' : args.scope

package/tools/dsh-plugin-fly-binary/index.js

@@ -5,6 +5,14 @@ import { defineTool } from '@deepseek-ai/dsh-tools'
  * Registers model-facing analysis tools on ctx.tools. All command execution
  * goes through the host `shell` capability seam so the sandbox confines it;
  * a tool never shells out via node:child_process directly.
+ *
+ * **失败面的口径是"大声"**（Q5）：缺 `readelf`/`objdump`/`strings`/`file`/`wc` 时**不静默降级** ——
+ *   · 能在仓库内补的就补：没有 GNU readelf 就用**仓库内置的原生解析器**算头部/段/动态（并在
+ *     结果的 `limitations` 里明说"这是内置解析器算的，不是 readelf 的输出"）；
+ *   · 补不了的就**抛**：`requireOk` 让缺命令以 `CommandError` 报出来（历史教训：`pwn_checksec`
+ *     曾在缺工具时静默回退，对**任何**二进制都报 `pie=no`）；
+ *   · "没有"要**说成没有**：`bin_strings` 一条都没匹配时返回"no printable strings matching …"，
+ *     绝不返回空串（空串会被读成"这个文件没有字符串"）；节表读不到时同理。
  */
 export const name = 'fly-binary'
 export const inject = ['tools', 'shell']
@@ -24,6 +32,19 @@ function shq(value) {
  * version. `scripts/verify-security-tools.mjs` now fails loudly if a call site
  * names a seam method the executor does not have.
  */
+/**
+ * 路径参数规范化：以 `-` 开头的路径加 `./` 前缀（2026-10-13）。
+ *
+ * 为什么不插 `--`：实测本机（macOS，发布目标平台）**objdump（-h/-d/-T）/ base64 -i / otool -hv 都不支持
+ * `--`**，插进去直接失败；而 `file -b --version` 会打印 `file-5.41`、`nm -u --version` 会打印
+ * `llvm-nm, …`，两者都 **exit 0** ⇒ 工具会把版本串当**数据**返回（`bin_sections { path: '--version' }`
+ * 真发生过）。加 `./` 之后它就是一个普通相对路径：不存在就正常报错，存在就是那个文件。
+ */
+function safePath(value) {
+  const text = String(value ?? '')
+  return text.startsWith('-') ? './' + text : text
+}
+
 async function runCmd(shell, argv, exec, opts = {}) {
   const result = await (await shell.execute(shell.resolve({
     command: argv.map(shq).join(' '),
@@ -54,9 +75,19 @@ async function runCmd(shell, argv, exec, opts = {}) {
  */
 function requireOk(run, what) {
   if (run.exitCode === 0) return run.stdout
-  const detail = run.stderr.trim().split('\n').map(line => line.trim()).filter(Boolean).slice(0, 3).join(' | ')
-  const missing = run.exitCode === 127 || /command not found/iu.test(run.stderr) ? ' — the command is not installed on this host' : ''
-  const error = new Error(`${what} failed (exit ${run.exitCode})${missing}: ${run.command}${detail === '' ? '' : `\n${detail}`}`)
+  // 沙箱拒绝的形状是**结果正文里的标记**（`[sandbox: file access denied under <mode> mode]`，
+  // 抄自 @deepseek-ai/dsh-sandbox/index.js:65）—— 它落在 stdout 上；只读 stderr 就会把它丢掉，
+  // 于是模型读到的是「命令失败」，而不是「你没有被授权」。所以标记必须原样带进错误文案。
+  const sandboxMark = /^\[sandbox: .*\]$/mu.exec(run.stdout)
+  const detail = [sandboxMark?.[0], ...run.stderr.trim().split('\n').map(line => line.trim()).filter(Boolean)].slice(0, 3).join(' | ')
+  const notInstalled = run.exitCode === 127 || /command not found/iu.test(run.stderr)
+  const missing = notInstalled ? ' — the command is not installed on this host' : ''
+  // 失败文案要对**读它的模型**可行动（Q6）：不是裸 stderr，但也不许臆断原因 ——
+  // 只给「这条 exit 属于哪一类」与「下一步可以试什么」，具体判断仍留给读的人。
+  const next = notInstalled
+    ? 'next: this host lacks that command — look for a built-in fallback in this package, or read the file another way'
+    : 'next: check the path, and that the file is what this tool expects (bin_file shows what it is); the line above is the command own reason'
+  const error = new Error(`${what} failed (exit ${run.exitCode})${missing}: ${run.command}${detail === '' ? '' : `\n${detail}\n${next}`}`)
   error.name = 'CommandError'
   throw error
 }
@@ -432,10 +463,23 @@ export function apply(ctx) {
       render: (_args, value) => [{ type: 'text', text: value }],
     },
     async execute(args, exec) {
-      const wc = await runCmd(shell, ['wc', '-c', args.path], exec)
+      const path = safePath(args.path)
+      const wc = await runCmd(shell, ['wc', '-c', path], exec)
       const size = requireOk(wc, 'wc -c').trim().split(/\s+/)[0] ?? '0'
-      const identify = await runCmd(shell, ['file', '-b', args.path], exec)
-      return `size=${size}\n${requireOk(identify, 'file -b').trim()}`
+      const identify = await runCmd(shell, ['file', '-b', path], exec)
+      // 证据形状（规划 §5.1）：信封 JSON，原文本原样进 observed.dump。
+      const text = `size=${size}\n${requireOk(identify, 'file -b').trim()}`
+      return JSON.stringify({
+        tool: 'bin_file',
+        target: args.path,
+        operation: 'one wc -c + one file -b (no parsing of the file content)',
+        observed: { bytes: Number(size), dump: text },
+        confidence: 'observed',
+        limitations: [
+          '只报 wc -c 的字节数与 file(1) 的判断：**不解析文件内部**（要字段另用 bin_readelf / bin_sections）',
+          'file(1) 的判断来自魔数与片段匹配：损坏或被裁剪的文件也可能被认成某种格式',
+        ],
+      }, null, 2)
     },
   }))
 
@@ -453,18 +497,39 @@ export function apply(ctx) {
     },
     async execute(args, exec) {
       const min = String(args.min ?? 4)
-      const run = await runCmd(shell, ['strings', '-n', min, args.path], exec, { stdoutMaxBytes: 1048576 })
+      const path = safePath(args.path)
+      const run = await runCmd(shell, ['strings', '-n', min, path], exec, { stdoutMaxBytes: 1048576 })
       let lines = requireOk(run, `strings -n ${min}`).split('\n').filter(Boolean)
       if (args.grep) {
         const g = args.grep.toLowerCase()
         lines = lines.filter((l) => l.toLowerCase().includes(g))
       }
       if (lines.length === 0) {
-        return args.grep === undefined
-          ? `no printable strings of length ${min} or more in ${args.path}`
-          : `no printable strings matching ${JSON.stringify(args.grep)} (min length ${min}) in ${args.path}`
+        return JSON.stringify({
+          tool: 'bin_strings',
+          target: args.path,
+          operation: `strings -n ${min}` + (args.grep === undefined ? '' : ` filtered by ${JSON.stringify(args.grep)}`),
+          observed: { matched: 0, min: Number(min), grep: args.grep ?? null, dump: args.grep === undefined
+            ? `no printable strings of length ${min} or more in ${args.path}`
+            : `no printable strings matching ${JSON.stringify(args.grep)} (min length ${min}) in ${args.path}` },
+          confidence: 'observed',
+          limitations: [
+            '一条都没匹配上 ⇒ 这是「没有这样的字符串」，不是「这个文件里没有字符串」',
+            'strings(1) 只看可打印字节序列：加密/压缩/UTF-16 里的字符串它看不到',
+          ],
+        }, null, 2)
       }
-      return lines.slice(0, 400).join('\n')
+      return JSON.stringify({
+        tool: 'bin_strings',
+        target: args.path,
+        operation: `strings -n ${min}` + (args.grep === undefined ? '' : ` filtered by ${JSON.stringify(args.grep)}`),
+        observed: { matched: lines.length, shown: Math.min(lines.length, 400), min: Number(min), grep: args.grep ?? null, dump: lines.slice(0, 400).join('\n') },
+        confidence: 'observed',
+        limitations: [
+          lines.length > 400 ? '只给前 400 条（observed.matched 是匹配总数）：要更多就加 grep 缩小范围' : '这次没有截断（匹配数 ≤ 400）',
+          'strings(1) 只看可打印字节序列：加密/压缩/UTF-16 里的字符串它看不到',
+        ],
+      }, null, 2)
     },
   }))
 
@@ -480,26 +545,48 @@ export function apply(ctx) {
       render: (_args, value) => [{ type: 'text', text: value }],
     },
     async execute(args, exec) {
+      // 证据形状（规划 §5.1）：四个分支都产出同一个信封；两条方法（GNU readelf / 仓库内置解析器）
+      // 必须写进 limitations，否则"本机没有 readelf"会被读成"这份 ELF 就是这样"。
+      const envelope = (observed, limitations) => JSON.stringify({
+        tool: 'bin_readelf',
+        target: args.path,
+        operation: `read ELF ${mode} (${flag}) and report it verbatim or via the built-in reader)`,
+        observed,
+        confidence: 'observed',
+        limitations,
+      }, null, 2)
       const mode = args.mode === 'segments' || args.mode === 'dynamic' ? args.mode : 'headers'
       const flag = mode === 'segments' ? '-l' : mode === 'dynamic' ? '-d' : '-h'
       // GNU binutils is not part of macOS. When readelf is absent (or refuses the
       // file) the ELF is parsed here instead: the previous revision threw
       // "command not found" on every Mac, which made four of the five binary
       // tools useless on the platform this app ships for.
-      const real = await runCmd(shell, ['readelf', flag, args.path], exec)
-      if (real.exitCode === 0 && real.stdout.trim() !== '') return real.stdout
-      const elf = await elfProbe(rawRun(shell, exec), args.path)
+      const path = safePath(args.path)
+      const real = await runCmd(shell, ['readelf', flag, path], exec)
+      if (real.exitCode === 0 && real.stdout.trim() !== '') {
+        return envelope({ method: 'readelf', dump: real.stdout }, [
+          'GNU readelf 的输出原样返回，本工具不改写它',
+        ])
+      }
+      const elf = await elfProbe(rawRun(shell, exec), path)
       if (elf === null) {
-        const kind = requireOk(await runCmd(shell, ['file', '-b', args.path], exec), 'file -b').trim()
-        return [
+        const kind = requireOk(await runCmd(shell, ['file', '-b', path], exec), 'file -b').trim()
+        return envelope({ method: null, dump: [
           `readelf ${flag} is unavailable on this host (${real.exitCode === 127 ? 'not installed' : `exit ${real.exitCode}`})`,
           `${args.path} is not ELF, so a native ELF reader has nothing to report either — file(1) says: ${kind}`,
           'for Mach-O use rev_disasm / rev_imports (objdump, otool and nm ship with macOS)',
-        ].join('\n')
+        ].join('\n') }, [
+          '本机没有可用的 readelf，而这个文件也不是 ELF ⇒ 两条路都给不出读数（observed.dump 里是原因）',
+        ])
       }
-      if (mode === 'segments') return renderElfSegments(elf)
-      if (mode === 'dynamic') return await renderElfDynamic(elf)
-      return renderElfHeader(elf)
+      // 本机没有 GNU readelf ⇒ 下面三支都是**仓库内置解析器**算的，limitations 要说清。
+      const native = [
+        '本机没有 GNU readelf（macOS 不带 binutils）⇒ 这份读数是仓库内置原生解析器算的，不是 readelf 的输出',
+        '内置解析器只覆盖本工具声明的字段；readelf 的其它开关（--notes/--relocs 等）它不做',
+      ]
+      if (mode === 'segments') return envelope({ method: 'native', dump: renderElfSegments(elf) }, native)
+      if (mode === 'dynamic') return envelope({ method: 'native', dump: await renderElfDynamic(elf) }, native)
+      return envelope({ method: 'native', dump: renderElfHeader(elf) }, native)
     },
   }))
 
@@ -517,11 +604,12 @@ export function apply(ctx) {
       // 证据形状（规划 §5.1 的第一个试点）：返回值是**信封 JSON**，不再是裸表格文本。
       // 真值判据不变（observed.dump 里是 objdump 原文），新增 confidence 与 limitations ——
       // 逼这个工具回答"这个结论看不见什么"（本仓最贵的那条教训）。
-      const run = await runCmd(shell, ['objdump', '-h', args.path], exec)
+      const path = safePath(args.path)
+      const run = await runCmd(shell, ['objdump', '-h', path], exec)
       const ok = run.exitCode === 0 && run.stdout.trim() !== ''
       // GNU binutils is not part of macOS. Instead of an opaque "command not found",
       // say which method failed and what to use instead (same shape as bin_readelf).
-      const kind = ok ? null : await runCmd(shell, ['file', '-b', args.path], exec)
+      const kind = ok ? null : await runCmd(shell, ['file', '-b', path], exec)
       return JSON.stringify({
         tool: 'bin_sections',
         target: args.path,

package/tools/dsh-plugin-fly-blackbox/index.js

@@ -306,6 +306,19 @@ function assertNotPrivileged(command) {
  * 这一点（本仓既有五个插件的 `runCmd` 正是这个写法；门禁桩现在按真接缝的形状发布
  * `result()`，所以这类"桩和真接缝不同形"的假绿会在这一层被抓住）。
  */
+/**
+ * 路径参数规范化：以 `-` 开头的路径加 `./` 前缀（2026-10-13）。
+ *
+ * 为什么不插 `--`：实测本机（macOS，发布目标平台）**objdump（-h/-d/-T）/ base64 -i / otool -hv 都不支持
+ * `--`**，插进去直接失败；而 `file -b --version` 会打印 `file-5.41`、`nm -u --version` 会打印
+ * `llvm-nm, …`，两者都 **exit 0** ⇒ 工具会把版本串当**数据**返回。加 `./` 之后它就是一个普通相对路径：
+ * 不存在就正常报错，存在就是那个文件。
+ */
+function safePath(value) {
+  const text = String(value ?? '')
+  return text.startsWith('-') ? './' + text : text
+}
+
 async function runCmd(shell, argv, exec, opts = {}) {
   const command = typeof argv === 'string' ? argv : argv.map(shq).join(' ')
   assertNotPrivileged(command)
@@ -968,11 +981,17 @@ export function readHarDocument(buffer, path) {
   try {
     parsed = JSON.parse(payload.toString('utf8').replace(/^\uFEFF/u, ''))
   } catch (error) {
-    throw new Error(`${path} 不是合法 JSON${gzip ? '（已按 gzip magic 解压）' : ''}：${error.message}`)
+    // Q6（2026-10-13）：失败文案要对读它的模型可行动 —— what + why + **what to try next**，
+    // 且不臆断具体原因（写错的「为什么」比没有更糟）。
+    throw new Error(`${path} 不是合法 JSON${gzip ? '（已按 gzip magic 解压）' : ''}：${error.message}`
+      + ' —— 修法：确认这是 HAR 导出（浏览器 DevTools 的 Save all as HAR，或 mitmproxy 的硬拷贝转 HAR）；' 
+      + '只做普通 JSON 校验的话，先看它是不是别的格式。')
   }
   const entries = parsed?.log?.entries
   if (!Array.isArray(entries)) {
-    throw new Error(`${path} 不像 HAR：log.entries 不是数组（HAR 1.2 的条目都在 log.entries 下）。`)
+    throw new Error(`${path} 不像 HAR：log.entries 不是数组（HAR 1.2 的条目都在 log.entries 下）。`
+      + ' —— 修法：重新导出一份 HAR，或确认导出的是 HAR 而不是本仓自己的 mitmproxy dump' 
+      + '（`.mitm` 那种用 bx_flows 读）。')
   }
   const creator = parsed.log.creator
   return {
@@ -1696,7 +1715,7 @@ export function apply(ctx) {
       const root = workspaceRoot(exec)
       const state = readState(root)
       const action = String(args.action ?? '')
-      const dump = args.path ?? state?.dump ?? join(root, '.fly-blackbox', 'flows.mitm')
+      const dump = safePath(args.path ?? state?.dump ?? join(root, '.fly-blackbox', 'flows.mitm'))
 
       const size = await statSizeVia(shell, exec, dump, 'dump')
       if (size > 32 * 1024 * 1024) {
@@ -1773,7 +1792,7 @@ export function apply(ctx) {
     },
     output: stringOutput,
     async execute(args, exec) {
-      const path = typeof args.path === 'string' ? args.path.trim() : ''
+      const path = safePath(typeof args.path === 'string' ? args.path.trim() : '')
       if (path === '') throw new Error('bx_har 需要 path（.har 或 .har.gz 的路径）')
       const groupBy = args.groupBy ?? 'host'
       if (!HAR_GROUPINGS.includes(groupBy)) {