zen-gitsync 2.17.8 → 2.17.10

package/src/ui/server/routes/workbench/taskRunner.toolcalls.test.js

@@ -0,0 +1,307 @@
+// Copyright 2026 xz333221
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+// 工具调用（tool_use）采集的回归测试（2026-09-22）。
+//
+// 背景：两个事件处理器原本把 tool_use 整段丢掉，执行流里只剩「思考 + 正文」，
+// 模型闷头跑的几分钟完全看不出它在干什么。现在归一成 job.toolCalls。
+//
+// 钉住的口径：
+//   1. claude：assistant 的 tool_use 块建条目，user 事件里的 tool_result 回填结果
+//   2. claude：user 事件里"用户自己那条 prompt"（content 是字符串）不能误判成工具结果
+//   3. claude：is_error 的 tool_result → status error + error 文案
+//   4. opencode：同一个 part 的 running → completed 只更新一条，不重复建
+//   5. 参数 / 结果都截断（jobs.json 不能被一次长跑撑爆）
+//   6. 超上限后丢弃新调用但保留已有条目
+//   7. flush 只在有增量时发事件；seal 把没收尾的调用收口成终态
+//
+// 隔离策略同 taskRunner.opencode.test.js：import taskRunner.js 之前把
+// USERPROFILE/HOME 指向 mkdtemp 沙箱（taskRunner → jobStore import 时就会 hydrate）。
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+import os from 'node:os';
+import { mkdtempSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = path.resolve(__dirname, '../../../../..');
+
+// ---- 环境隔离:必须在 import taskRunner.js 之前完成 ----
+const sandbox = mkdtempSync(path.join(os.tmpdir(), 'zen-toolcalls-test-'));
+process.env.USERPROFILE = sandbox;
+process.env.HOME = sandbox;
+delete process.env.HOMEDRIVE;
+delete process.env.HOMEPATH;
+
+const {
+  createClaudeEventHandler,
+  createOpencodeEventHandler,
+  createToolCallTracker,
+  MAX_TOOL_CALLS,
+} = await import(
+  pathToFileURL(path.join(projectRoot, 'src/ui/server/routes/workbench/taskRunner.js')).href
+);
+
+function makeSink() {
+  const sink = { output: [], thinking: [] };
+  sink.appendOutput = (t) => { if (t) sink.output.push(t); };
+  sink.appendThinking = (t) => { if (t) sink.thinking.push(t); };
+  return sink;
+}
+
+/** 建一个带推送记录的 tracker（onUpdates 收集每一批） */
+function makeTracker(job) {
+  const batches = [];
+  const tracker = createToolCallTracker(job, (updates) => batches.push(updates));
+  return { tracker, batches };
+}
+
+test('claude：tool_use 建条目，user 事件里的 tool_result 回填结果', () => {
+  const job = {};
+  const sink = makeSink();
+  const handle = createClaudeEventHandler(job, sink.appendOutput, sink.appendThinking);
+
+  handle({
+    type: 'assistant',
+    message: {
+      content: [
+        { type: 'thinking', thinking: '先看看文件' },
+        { type: 'tool_use', id: 'toolu_1', name: 'Bash', input: { command: 'npm test', description: '跑测试' } },
+      ],
+    },
+  });
+  assert.equal(job.toolCalls.length, 1);
+  assert.equal(job.toolCalls[0].id, 'toolu_1');
+  assert.equal(job.toolCalls[0].name, 'Bash');
+  assert.equal(job.toolCalls[0].status, 'running');
+  // 摘要优先取 command（不是退化成整段 JSON）
+  assert.equal(job.toolCalls[0].argsPreview, 'npm test');
+  assert.equal(job.toolCalls[0].arguments, '{"command":"npm test","description":"跑测试"}');
+  // 思考照旧落 thinking，不受影响
+  assert.deepEqual(sink.thinking, ['先看看文件']);
+
+  handle({
+    type: 'user',
+    message: { content: [{ type: 'tool_result', tool_use_id: 'toolu_1', content: 'all tests pass' }] },
+  });
+  assert.equal(job.toolCalls.length, 1);
+  assert.equal(job.toolCalls[0].status, 'done');
+  assert.equal(job.toolCalls[0].result, 'all tests pass');
+  // 工具结果不能被当成"模型说的话"塞进正文
+  assert.deepEqual(sink.output, []);
+});
+
+test('claude：user 事件里的普通 prompt（content 是字符串）不产生工具调用', () => {
+  const job = {};
+  const sink = makeSink();
+  const handle = createClaudeEventHandler(job, sink.appendOutput, sink.appendThinking);
+
+  handle({ type: 'user', message: { role: 'user', content: '帮我改个 bug' } });
+  handle({ type: 'user', message: { content: [{ type: 'text', text: '普通文本块' }] } });
+
+  assert.deepEqual(job.toolCalls, []);
+  assert.deepEqual(sink.output, []);
+});
+
+test('claude：tool_result 的 content 是块数组 / is_error 时分别抽取与标错', () => {
+  const job = {};
+  const sink = makeSink();
+  const handle = createClaudeEventHandler(job, sink.appendOutput, sink.appendThinking);
+
+  handle({
+    type: 'assistant',
+    message: {
+      content: [
+        { type: 'tool_use', id: 'ok_1', name: 'Read', input: { file_path: 'src/a.js' } },
+        { type: 'tool_use', id: 'bad_1', name: 'Edit', input: { file_path: 'src/b.js' } },
+      ],
+    },
+  });
+  handle({
+    type: 'user',
+    message: {
+      content: [
+        { type: 'tool_result', tool_use_id: 'ok_1', content: [{ type: 'text', text: '第一行' }, { type: 'text', text: '第二行' }] },
+        { type: 'tool_result', tool_use_id: 'bad_1', is_error: true, content: 'File has not been read yet' },
+      ],
+    },
+  });
+
+  assert.equal(job.toolCalls.length, 2);
+  assert.equal(job.toolCalls[0].status, 'done');
+  assert.equal(job.toolCalls[0].result, '第一行\n第二行');
+  assert.equal(job.toolCalls[0].argsPreview, 'src/a.js');
+  assert.equal(job.toolCalls[1].status, 'error');
+  assert.equal(job.toolCalls[1].error, 'File has not been read yet');
+  assert.equal(job.toolCalls[1].result, 'File has not been read yet');
+});
+
+test('opencode：同一个 part 的 running → completed 只更新一条', () => {
+  const job = {};
+  const sink = makeSink();
+  const handle = createOpencodeEventHandler(job, sink.appendOutput, sink.appendThinking);
+
+  const part = (state) => ({
+    type: 'tool_use',
+    sessionID: 'ses_1',
+    part: { id: 'prt_1', callID: 'call_1', type: 'tool', tool: 'bash', state },
+  });
+
+  handle(part({ status: 'running', input: { command: 'ls -la' } }));
+  assert.equal(job.toolCalls.length, 1);
+  assert.equal(job.toolCalls[0].id, 'call_1');
+  assert.equal(job.toolCalls[0].name, 'bash');
+  assert.equal(job.toolCalls[0].status, 'running');
+  assert.equal(job.toolCalls[0].argsPreview, 'ls -la');
+
+  handle(part({ status: 'completed', input: { command: 'ls -la' }, output: 'a.js\nb.js' }));
+  assert.equal(job.toolCalls.length, 1, '同一 part 不能重复建条目');
+  assert.equal(job.toolCalls[0].status, 'done');
+  assert.equal(job.toolCalls[0].result, 'a.js\nb.js');
+
+  // completed → error（opencode 的错误形态：state.error 是对象）
+  handle(part({ status: 'error', error: { message: '命令不存在' } }));
+  assert.equal(job.toolCalls.length, 1);
+  assert.equal(job.toolCalls[0].status, 'error');
+  assert.equal(job.toolCalls[0].error, '命令不存在');
+});
+
+test('opencode：part.type 不是 tool 时忽略（不制造空条目）', () => {
+  const job = {};
+  const sink = makeSink();
+  const handle = createOpencodeEventHandler(job, sink.appendOutput, sink.appendThinking);
+
+  handle({ type: 'tool_use', sessionID: 'ses_2', part: { id: 'p1', type: 'text', text: 'hi' } });
+  assert.deepEqual(job.toolCalls, []);
+});
+
+test('参数与结果都按上限截断', () => {
+  const job = {};
+  const sink = makeSink();
+  const handle = createClaudeEventHandler(job, sink.appendOutput, sink.appendThinking);
+
+  handle({
+    type: 'assistant',
+    message: { content: [{ type: 'tool_use', id: 'big', name: 'Bash', input: { command: 'x'.repeat(9000) } }] },
+  });
+  assert.ok(job.toolCalls[0].arguments.length < 2100, '参数应被截断');
+  assert.ok(job.toolCalls[0].arguments.includes('已截断'));
+  assert.ok(job.toolCalls[0].argsPreview.length <= 200, '摘要不超过 200 字');
+
+  handle({
+    type: 'user',
+    message: { content: [{ type: 'tool_result', tool_use_id: 'big', content: 'y'.repeat(9000) }] },
+  });
+  assert.ok(job.toolCalls[0].result.length < 4100, '结果应被截断');
+  assert.ok(job.toolCalls[0].result.includes('已截断'));
+});
+
+test('超过 MAX_TOOL_CALLS 后丢弃新调用，已有条目仍可更新', () => {
+  const job = {};
+  const sink = makeSink();
+  const handle = createClaudeEventHandler(job, sink.appendOutput, sink.appendThinking);
+
+  for (let i = 0; i < MAX_TOOL_CALLS + 5; i++) {
+    handle({
+      type: 'assistant',
+      message: { content: [{ type: 'tool_use', id: `t${i}`, name: 'Bash', input: { command: `cmd-${i}` } }] },
+    });
+  }
+  assert.equal(job.toolCalls.length, MAX_TOOL_CALLS);
+
+  // 已被记下的那条还能收到结果（超限之后不能变成"半截"）
+  handle({
+    type: 'user',
+    message: { content: [{ type: 'tool_result', tool_use_id: 't0', content: 'ok' }] },
+  });
+  assert.equal(job.toolCalls[0].status, 'done');
+  assert.equal(job.toolCalls[0].result, 'ok');
+});
+
+test('tracker：flush 只在有增量时推送，且推的是快照', () => {
+  const job = {};
+  const { tracker, batches } = makeTracker(job);
+
+  tracker.flush();
+  assert.deepEqual(batches, [], '没有增量时不该发空事件');
+
+  tracker.record({ id: 'a', name: 'Read', input: { file_path: 'a.js' }, status: 'running' });
+  assert.equal(batches.length, 0, 'record 只入队，不立即推送');
+
+  tracker.flush();
+  assert.equal(batches.length, 1);
+  assert.equal(batches[0].length, 1);
+  assert.deepEqual(batches[0][0], {
+    id: 'a',
+    name: 'Read',
+    argsPreview: 'a.js',
+    arguments: '{"file_path":"a.js"}',
+    result: '',
+    status: 'running',
+    error: undefined,
+  });
+
+  // 推出去的是快照：后续状态变更不会改掉已经 emit 的那一份
+  tracker.record({ id: 'a', name: 'Read', status: 'done', output: '文件内容' });
+  tracker.flush();
+  assert.equal(batches[0][0].status, 'running');
+  assert.equal(batches[1][0].status, 'done');
+  assert.equal(batches[1][0].result, '文件内容');
+});
+
+test('tracker：seal 把没收尾的调用收口成终态', () => {
+  const done = {};
+  const t1 = makeTracker(done);
+  t1.tracker.record({ id: 'a', name: 'Read', status: 'running' });
+  t1.tracker.flush();
+  t1.tracker.seal('done');
+  assert.equal(done.toolCalls[0].status, 'done');
+  assert.equal(t1.batches.length, 2, 'seal 要把终态也推给前端');
+
+  const cancelled = {};
+  const t2 = makeTracker(cancelled);
+  t2.tracker.record({ id: 'a', name: 'Read', status: 'running' });
+  t2.tracker.seal('cancelled');
+  assert.equal(cancelled.toolCalls[0].status, 'error');
+  assert.equal(cancelled.toolCalls[0].error, '未返回结果（执行已停止）');
+
+  const errored = {};
+  const t3 = makeTracker(errored);
+  t3.tracker.record({ id: 'a', name: 'Read', status: 'running' });
+  t3.tracker.seal('error');
+  assert.equal(errored.toolCalls[0].status, 'error');
+  assert.equal(errored.toolCalls[0].error, '未返回结果（执行出错）');
+
+  // 已经收尾的条目不被 seal 改写
+  const mixed = {};
+  const t4 = makeTracker(mixed);
+  t4.tracker.record({ id: 'a', name: 'Read', status: 'done', output: 'ok' });
+  t4.tracker.flush();
+  const before = t4.batches.length;
+  t4.tracker.seal('cancelled');
+  assert.equal(mixed.toolCalls[0].status, 'done');
+  assert.equal(t4.batches.length, before, '没有需要收口的条目时 seal 不该推空事件');
+});
+
+test('tracker：没有 id 的事件按序号兜底，不会互相覆盖', () => {
+  const job = {};
+  const { tracker } = makeTracker(job);
+  tracker.record({ name: 'Unknown' });
+  tracker.record({ name: 'Unknown' });
+  assert.equal(job.toolCalls.length, 2);
+  assert.notEqual(job.toolCalls[0].id, job.toolCalls[1].id);
+});

package/src/ui/server/socket/registerUiSocketHandlers.js

@@ -14,6 +14,7 @@
 //
 import logger from '../utils/logger.js'
 import { ensureWithinCwd } from '../utils/pathGuard.js'
+import { augmentEnvPath } from '../../../utils/shellPath.js'
 
 // ─────────────────────────────────────────────────────────────────────────────
 // exec_interactive 修复(SEC-INJ-1)
@@ -73,16 +74,22 @@ function resolveBinAndArgs(command) {
   return { bin: head, args: tokens.slice(1) };
 }
 
-const INTERACTIVE_ENV = {
-  ...process.env,
-  GIT_CONFIG_PARAMETERS: "'color.ui=always' 'color.status=always' 'core.quotepath=false'",
-  FORCE_COLOR: '3',
-  NPM_CONFIG_COLOR: 'always',
-  TERM: 'xterm-256color',
-  COLORTERM: 'truecolor',
-  CLICOLOR_FORCE: '1',
-  PYTHONUNBUFFERED: '1',
-};
+// 交互式子进程的 env。PATH 交给 augmentEnvPath 补一次注册表最新值 ——
+// 服务端进程的环境块是**启动快照**，用户在这个进程活着期间装的 CLI 不在里面，
+// 表现是"GUI 里能探测到、执行却报 '不是内部或外部命令'"（2026-09-22 实测 gh）。
+// 因为要读注册表，这里必须是函数而不是模块级常量（常量会在 import 时定死）。
+async function buildInteractiveEnv() {
+  return augmentEnvPath({
+    ...process.env,
+    GIT_CONFIG_PARAMETERS: "'color.ui=always' 'color.status=always' 'core.quotepath=false'",
+    FORCE_COLOR: '3',
+    NPM_CONFIG_COLOR: 'always',
+    TERM: 'xterm-256color',
+    COLORTERM: 'truecolor',
+    CLICOLOR_FORCE: '1',
+    PYTHONUNBUFFERED: '1',
+  });
+}
 
 function isWindowsBuiltin(command) {
   if (process.platform !== 'win32') return false;
@@ -180,7 +187,7 @@ export function registerUiSocketHandlers({
 
       const childProcess = spawn(bin, args, {
         cwd: execDirectory,
-        env: INTERACTIVE_ENV,
+        env: await buildInteractiveEnv(),
         windowsHide: true,
       });
 

package/src/utils/shellPath.js

@@ -0,0 +1,253 @@
+// Copyright 2026 xz333221
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// ─────────────────────────────────────────────────────────────────────────────
+// Windows 上「进程 PATH 快照过期」的统一修补层。
+//
+// 问题：安装器（winget / MSI / brew 等）改的是**注册表里的 PATH**，而已经跑起来的
+// node 进程持有的是启动那一刻的环境块快照 —— 它不会自己更新。典型表现（2026-09-22 实测）：
+// 用户在 GUI 里一键装完 gh，探测侧能找到（因为探测会读注册表兜底），但真去执行
+// `cmd /c gh auth login` 时照样报「'gh' 不是内部或外部命令」。
+//
+// 当时先打的补丁是「登录接口显式传 pathDirs」—— 那只救了一个入口。同样的病在
+// run_command（智能体）、/api/exec-stream、socket 交互式执行、以及"另起一个终端窗口"
+// 这些地方全都存在。所以统一收在这里：**把注册表 Machine + User 的 PATH 里
+// 「当前进程没有的目录」补到子进程的 PATH 上**，语义等价于"这个进程是现在才启动的"。
+//
+// 为什么补在**末尾**而不是像 pathDirs 那样前置：
+//   PATH 的语义是「先命中先赢」。注册表 PATH 是当前进程 PATH 的**超集** ——
+//   进程启动后新装的目录在注册表里有、进程里没有；反过来进程里多出来的是启动后
+//   被卸载的目录。只把缺的补在末尾，原有目录的优先级顺序一个都没动，等于把快照
+//   更新到最新；若前置，反而会改掉用户既有的解析顺序（让某个兜底目录抢在正主前面）。
+//   fileOpen.launchCommandInTerminal 的 pathDirs 前置是对的，因为那是另一种语义：
+//   "我已经知道要跑的就是这个绝对路径，把它优先"。
+//
+// 为什么每次都重新比对、而不是"补一次就完"：
+//   用户可能在同一个进程会话里接着装第二个 CLI，而修补只作用于子进程的 env。
+//   这里刻意**不改动 process.env**，避免影响其它模块（进程级副作用最难排查）。
+//   注册表读取有 TTL 缓存，正常路径零额外开销；tools.js 在"命令找不到"时会
+//   force 刷一次缓存重试，覆盖"刚装完、缓存还没过期"的那个窗口。
+//
+// 平台：仅 win32 生效。POSIX 侧的 PATH 由启动它的 shell 决定，没有"安装器改注册表"
+// 这套机制，终端新装的 CLI 一般也落在已有 PATH 目录里 —— 所以那边原样返回。
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import path from 'node:path';
+
+const execFileAsync = promisify(execFile);
+
+/** 注册表里两个 PATH 的宿主。缺一个都会漏装到相应作用域的 CLI：
+ *  winget / MSI 默认写 Machine（HKLM），npm -g / 用户级安装器写 User（HKCU）。 */
+const REG_KEY_MACHINE = 'HKLM\\SYSTEM\\CurrentControlSet\\Control\\Session Manager\\Environment';
+const REG_KEY_USER = 'HKCU\\Environment';
+
+/** PATH 键名在 Windows 上大小写不定（`Path` / `PATH` 都见过，取决于父进程怎么给的）。
+ *  回写时若按错大小写，环境块里会出现**两个** PATH 键，子进程取哪个是未定义的 ——
+ *  于是就有了"明明前置了却没生效"的补丁。所以一律按实际存在的那个键名回写。 */
+const PATH_KEY_RE = /^path$/i;
+
+/** 注册表目录列表的缓存时长。取值考虑：短到"装完 CLI 基本立刻可用"，
+ *  长到"不会每条命令都去 spawn 一次 reg.exe"（那是同步阻塞，会卡事件循环）。 */
+const DEFAULT_TTL_MS = 15000;
+
+/** @type {{ at: number, dirs: string[] }} */
+let cache = { at: 0, dirs: [] };
+
+// ── 纯函数区（都可单测，不碰进程状态） ──────────────────────────────────────
+
+/** 找出 env 里 PATH 的实际键名；没有则返回 null。 */
+export function findPathKey(env) {
+  return Object.keys(env).find((key) => PATH_KEY_RE.test(key)) || null;
+}
+
+/**
+ * 大小写安全地把 PATH 写回 env：只保留**一个** PATH 键（沿用原来那个键名）。
+ * 返回新对象，不改入参。
+ */
+export function withPathValue(env, value) {
+  const key = findPathKey(env) || 'PATH';
+  const next = {};
+  for (const k of Object.keys(env)) { if (!PATH_KEY_RE.test(k)) next[k] = env[k]; }
+  next[key] = value;
+  return next;
+}
+
+/** 同步取出 env 里的 PATH 值。 */
+export function pathValueOf(env) {
+  const key = findPathKey(env);
+  return key ? String(env[key] ?? '') : '';
+}
+
+/** PATH 字符串 → 目录数组（去空白、丢空段）。分隔符按当前平台，注册表值在
+ *  win32 下就是 `;`。 */
+export function splitPathList(value, { delimiter = path.delimiter } = {}) {
+  return String(value ?? '')
+    .split(delimiter)
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+/** 比较用的归一形式：忽略大小写与结尾分隔符（`C:\Tools\` 与 `c:\tools` 是同一个）。
+ *  Windows 路径这两点都必须归一 —— 只按字符串比对会把同一个目录当成新目录，
+ *  于是每次修补都往 PATH 里再塞一遍。 */
+function normalizeDir(dir) {
+  return String(dir ?? '').trim().replace(/[\\/]+$/, '').toLowerCase();
+}
+
+/**
+ * 找出 dirs 里 currentValue 还没有的目录，保持原顺序。
+ * dirs 内部也去重（Machine 与 User 的 PATH 常有重叠）。
+ */
+export function missingPathDirs(currentValue, dirs, options) {
+  const seen = new Set(splitPathList(currentValue, options).map(normalizeDir));
+  const out = [];
+  for (const dir of dirs) {
+    const key = normalizeDir(dir);
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    out.push(String(dir).trim());
+  }
+  return out;
+}
+
+/** 按环境块大小写不敏感地查一个变量（%SystemRoot% 与 %systemroot% 都该命中）。
+ *  展开不出来就原样保留 —— 宁可在子进程里报"路径不存在"，也不要静默删掉一段 PATH。 */
+function lookupVar(env, name) {
+  if (Object.prototype.hasOwnProperty.call(env, name)) return env[name];
+  const hit = Object.keys(env).find((k) => k.toLowerCase() === String(name).toLowerCase());
+  return hit ? env[hit] : undefined;
+}
+
+/** 注册表 Path 里的 %USERPROFILE% / %SystemRoot% 这类变量不展开就写进子进程会失效。 */
+export function expandVars(raw, env = process.env) {
+  return String(raw ?? '').replace(/%([^%]+)%/g, (whole, name) => {
+    const value = lookupVar(env, name);
+    return value === undefined ? whole : String(value);
+  });
+}
+
+/**
+ * 解析 `reg query <key> /v Path` 的输出，取出 Path 的值；没有该值时返回 null。
+ *
+ * 输出形如（值名与类型之间是连续空白，`REG_EXPAND_SZ` 与 `REG_SZ` 都可能）：
+ *     Path    REG_EXPAND_SZ    %SystemRoot%\system32;%SystemRoot%;...
+ */
+export function parseRegQueryPath(stdout) {
+  const line = String(stdout ?? '')
+    .split(/\r?\n/)
+    .find((l) => /\sPath\s+REG_(?:EXPAND_)?SZ\s+/i.test(l));
+  if (!line) return null;
+  return line.replace(/^.*?REG_(?:EXPAND_)?SZ\s+/i, '').trim();
+}
+
+/**
+ * 判断一段命令输出是否属于「这条命令本身找不到」。
+ *
+ * 刻意**不收** POSIX 的 "No such file or directory"：那条既可能指"命令不存在"，
+ * 也可能只是 `type missing.txt` 这类**参数**文件缺失。调用方（tools.js）会据此
+ * 重试一次命令，而重试对"参数缺失"是白跑、对有副作用的命令更是危险 ——
+ * 所以只认能确定"整条命令没被执行过"的几种说法。
+ */
+export function isCommandNotFound(...parts) {
+  const text = parts.filter(Boolean).join('\n');
+  if (!text) return false;
+  return [
+    /不是内部或外部命令/,                                          // 中文 Windows cmd
+    /is not recognized as an internal or external command/i,       // 英文 cmd
+    /command not found/i,                                         // POSIX sh / bash
+    /\bENOENT\b/,                                                 // node spawn 找不到可执行文件
+  ].some((re) => re.test(text));
+}
+
+// ── 读注册表 ────────────────────────────────────────────────────────────────
+
+async function readRegPath(regKey, { execFileFn = execFileAsync } = {}) {
+  try {
+    const { stdout } = await execFileFn('reg.exe', ['query', regKey, '/v', 'Path'], {
+      encoding: 'utf8',
+      windowsHide: true,
+    });
+    return parseRegQueryPath(stdout);
+  } catch {
+    // 键或值不存在（reg.exe 退出码 1）、被策略拦下、reg.exe 本身缺失 —— 都不该让
+    // 调用方失败，按"这项没有"处理即可
+    return null;
+  }
+}
+
+/** 清空缓存。装了新 CLI 想立刻生效、或测试之间需要隔离时调用。 */
+export function invalidatePathCache() {
+  cache = { at: 0, dirs: [] };
+}
+
+/**
+ * 读注册表 Machine + User 的 PATH，展开变量后返回目录数组（Machine 在前，与
+ * Windows 自身的 PATH 拼接顺序一致）。
+ *
+ * `ttlMs: 0` 表示禁用缓存（每次都真读）；`force: true` 忽略现有缓存。
+ */
+export async function readRegistryPathDirs({
+  platform = process.platform,
+  execFileFn,
+  env = process.env,
+  ttlMs = DEFAULT_TTL_MS,
+  force = false,
+} = {}) {
+  if (platform !== 'win32') return [];
+  const now = Date.now();
+  if (!force && ttlMs > 0 && cache.at && now - cache.at < ttlMs) return cache.dirs;
+
+  const [machine, user] = await Promise.all([
+    readRegPath(REG_KEY_MACHINE, { execFileFn }),
+    readRegPath(REG_KEY_USER, { execFileFn }),
+  ]);
+
+  const dirs = [];
+  const seen = new Set();
+  for (const raw of [machine, user]) {
+    if (!raw) continue;
+    for (const dir of splitPathList(expandVars(raw, env))) {
+      const key = normalizeDir(dir);
+      if (!key || seen.has(key)) continue;
+      seen.add(key);
+      dirs.push(dir);
+    }
+  }
+
+  cache = { at: now, dirs };
+  return dirs;
+}
+
+// ── 主入口 ──────────────────────────────────────────────────────────────────
+
+/**
+ * 返回一份**补过 PATH** 的 env（新对象），语义为"这个子进程是现在才启动的"。
+ *
+ * 已经是超集时原样返回入参（连引用都不换），调用方无需判断，直接丢给 spawn 即可。
+ * 非 win32 一律原样返回。
+ */
+export async function augmentEnvPath(env = process.env, options = {}) {
+  const { platform = process.platform } = options;
+  if (platform !== 'win32') return env;
+
+  const current = pathValueOf(env);
+  const dirs = await readRegistryPathDirs({ ...options, env });
+  const missing = missingPathDirs(current, dirs, options);
+  if (!missing.length) return env;
+
+  const merged = [...splitPathList(current, options), ...missing].join(path.delimiter);
+  return withPathValue(env, merged);
+}