@yanglaofish/fishtools 0.4.0 → 0.5.1

package/node_modules/@mytools/fst-platform/src/file-probe-engine.js

@@ -0,0 +1,183 @@
+import { fork } from 'node:child_process';
+
+const workerPath = new URL('./file-probe-worker.js', import.meta.url);
+const MAX_DIRECTORY_ENTRIES = 10000;
+
+function integer(value, name, minimum = 1, maximum = 2147483647) {
+  if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+    throw new TypeError(`${name} 必须是 ${minimum} 到 ${maximum} 的整数`);
+  }
+  return value;
+}
+
+function failure(status, reason, error) {
+  return { status, incomplete: true, reason, ...(error ? { error: { code: error.code || 'PROBE_ERROR', message: error.message || String(error) } } : {}) };
+}
+
+function isRemotePath(value) {
+  const normalized = value.replaceAll('/', '\\');
+  // Windows 扩展本地路径仍可探测；显式 UNC 和网络设备路径默认跳过。
+  if (/^\\\\[?.]\\/u.test(normalized)) {
+    return /^\\\\[?.]\\UNC(?:\\|$)/iu.test(normalized)
+      || /^\\\\[?.]\\GLOBALROOT\\Device\\(?:Mup|LanmanRedirector|WebDavRedirector)(?:\\|$)/iu.test(normalized);
+  }
+  return /^\\\\/u.test(normalized)
+    || /^\\(?:\?\?\\UNC|Device\\(?:Mup|LanmanRedirector|WebDavRedirector))(?:\\|$)/iu.test(normalized);
+}
+
+/** 私有运行时边界：测试可使用真实阻塞 worker 和模拟操作系统终止失败。 */
+export function createFileProbeEngine(options = {}, runtime = {}) {
+  const timeout = integer(options.timeout ?? 2000, 'timeout');
+  const maxConcurrent = integer(options.maxConcurrent ?? 2, 'maxConcurrent');
+  const maxPending = integer(options.maxPending ?? 16, 'maxPending', 0);
+  const allowRemote = options.allowRemote ?? false;
+  if (typeof allowRemote !== 'boolean') throw new TypeError('allowRemote 必须为布尔值');
+  const closeTimeout = runtime.closeTimeout ?? 250;
+  const terminate = runtime.terminate ?? (child => child.kill('SIGKILL'));
+  const active = new Set();
+  const pending = [];
+  const closeWaiters = new Set();
+  let closed = false;
+  let closing;
+
+  function status() {
+    return { closed, active: active.size, pending: pending.length,
+      unreaped: [...active].filter(record => record.unreaped).length, maxConcurrent, maxPending };
+  }
+
+  function finish(request, result) {
+    if (request.finished) return;
+    request.finished = true;
+    clearTimeout(request.timer);
+    request.signal?.removeEventListener('abort', request.onAbort);
+    const index = pending.indexOf(request);
+    if (index !== -1) pending.splice(index, 1);
+    request.resolve(result);
+  }
+
+  function stop(record) {
+    if (!active.has(record)) return;
+    record.unreaped = true;
+    try { terminate(record.child); } catch { /* 退出事件到达前继续占预算。 */ }
+  }
+
+  function drain() {
+    while (!closed && active.size < maxConcurrent && pending.length) {
+      start(pending.shift());
+    }
+  }
+
+  function release(record) {
+    if (!active.delete(record)) return;
+    if (!record.request.finished) {
+      finish(record.request, failure('error', 'workerExited', { code: 'PROBE_WORKER_EXIT', message: '文件探测进程未返回结果即退出' }));
+    }
+    drain();
+    if (closed && active.size === 0) for (const notify of closeWaiters) notify();
+  }
+
+  function start(request) {
+    if (request.finished) return;
+    let child;
+    try {
+      child = fork(runtime.workerPath ?? workerPath, [], {
+        execPath: runtime.execPath ?? process.execPath,
+        execArgv: [], windowsHide: true,
+        stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+      });
+    } catch (error) {
+      finish(request, failure('error', 'workerStartFailed', error));
+      drain();
+      return;
+    }
+    const record = { child, request, unreaped: false };
+    request.record = record;
+    active.add(record);
+    child.once('exit', () => release(record));
+    child.once('close', () => release(record));
+    child.on('error', error => {
+      finish(request, failure('error', 'workerStartFailed', error));
+      if (child.pid) stop(record);
+      else release(record);
+    });
+    child.once('message', result => {
+      if (request.finished) return;
+      if (!result || !['ok', 'missing', 'error'].includes(result.status) || typeof result.incomplete !== 'boolean') {
+        finish(request, failure('error', 'workerProtocol', { code: 'PROBE_PROTOCOL', message: '文件探测进程返回非法结果' }));
+        stop(record);
+        return;
+      }
+      finish(request, result);
+      // 结果已到达也必须收到 exit 后才释放预算，避免新旧进程短暂重叠。
+    });
+    child.send({ operation: request.operation, path: request.path, limit: request.limit }, error => {
+      if (!error || request.finished) return;
+      finish(request, failure('error', 'workerStartFailed', error));
+      stop(record);
+    });
+  }
+
+  function submit(operation, path, requestOptions = {}) {
+    if (closed) return Promise.resolve(failure('cancelled', 'closed'));
+    let requestTimeout, limit, signal;
+    try {
+      if (typeof path !== 'string' || !path.length || path.includes('\0')) {
+        throw Object.assign(new TypeError('path 必须是非空且不含空字符的字符串'), { code: 'INVALID_PATH' });
+      }
+      requestTimeout = integer(requestOptions.timeout ?? timeout, 'timeout');
+      limit = operation === 'readDirectory' ? integer(requestOptions.limit ?? 1000, 'limit', 1, MAX_DIRECTORY_ENTRIES) : undefined;
+      signal = requestOptions.signal;
+      if (signal && (typeof signal.addEventListener !== 'function' || typeof signal.removeEventListener !== 'function' || typeof signal.aborted !== 'boolean')) {
+        throw new TypeError('signal 必须是 AbortSignal');
+      }
+    } catch (error) {
+      return Promise.resolve(failure('error', 'invalidOptions', error));
+    }
+    if (signal?.aborted) return Promise.resolve(failure('cancelled', 'signal'));
+    if (!allowRemote && isRemotePath(path)) return Promise.resolve(failure('skipped', 'remotePath'));
+    if (active.size >= maxConcurrent && pending.length >= maxPending) {
+      return Promise.resolve(failure('error', 'queueFull', { code: 'PROBE_BUSY', message: '文件探测并发和排队预算已满' }));
+    }
+    return new Promise(resolve => {
+      const request = { operation, path, limit, signal, resolve, finished: false };
+      function cancel(result) {
+        finish(request, result);
+        if (request.record) stop(request.record);
+      }
+      request.onAbort = () => cancel(failure('cancelled', 'signal'));
+      request.timer = setTimeout(() => cancel(failure('timedOut', 'timeout')), requestTimeout);
+      signal?.addEventListener('abort', request.onAbort, { once: true });
+      if (active.size < maxConcurrent) start(request);
+      else pending.push(request);
+    });
+  }
+
+  function close() {
+    if (closing) return closing;
+    closed = true;
+    for (const request of [...pending]) finish(request, failure('cancelled', 'closed'));
+    for (const record of active) {
+      finish(record.request, failure('cancelled', 'closed'));
+      stop(record);
+    }
+    closing = new Promise(resolve => {
+      let timer;
+      function done() {
+        clearTimeout(timer);
+        closeWaiters.delete(done);
+        // 不能立即退出的底层 I/O 仍被记录，但不会让宿主关闭无限等待。
+        for (const record of active) {
+          record.child.unref();
+          record.child.channel?.unref();
+        }
+        resolve({ closed: true, incomplete: active.size > 0, unreaped: active.size });
+      }
+      if (!active.size) done();
+      else { closeWaiters.add(done); timer = setTimeout(done, closeTimeout); }
+    });
+    return closing;
+  }
+
+  return { stat: (path, options) => submit('stat', path, options),
+    readDirectory: (path, options) => submit('readDirectory', path, options), close, status };
+}

package/node_modules/@mytools/fst-platform/src/file-probe-worker.js

@@ -0,0 +1,43 @@
+import { lstat, opendir } from 'node:fs/promises';
+
+function type(value) {
+  return value.isSymbolicLink() ? 'symlink' : value.isDirectory() ? 'directory' : value.isFile() ? 'file' : 'other';
+}
+
+async function probe(request) {
+  if (request.operation === 'stat') {
+    const value = await lstat(request.path);
+    return { status: 'ok', incomplete: false, value: {
+      type: type(value), size: value.size, mtimeMs: value.mtimeMs,
+      ctimeMs: value.ctimeMs, birthtimeMs: value.birthtimeMs, mode: value.mode,
+    } };
+  }
+  if (request.operation !== 'readDirectory') throw new TypeError('未知文件探测操作');
+  const directory = await opendir(request.path, { bufferSize: Math.min(32, request.limit) });
+  const value = [];
+  let incomplete = false;
+  try {
+    // 不递归，也不读取文件正文；多读一个条目确认是否被上限截断。
+    for (let index = 0; index <= request.limit; index++) {
+      const entry = await directory.read();
+      if (!entry) break;
+      if (index === request.limit) { incomplete = true; break; }
+      value.push({ name: entry.name, type: type(entry) });
+    }
+  } finally {
+    await directory.close();
+  }
+  return { status: 'ok', incomplete, value, limit: request.limit, ...(incomplete ? { reason: 'entryLimit' } : {}) };
+}
+
+process.once('message', async request => {
+  let result;
+  try { result = await probe(request); }
+  catch (error) {
+    result = { status: error.code === 'ENOENT' ? 'missing' : 'error', incomplete: true,
+      reason: error.code === 'ENOENT' ? 'notFound' : 'filesystemError',
+      error: { code: error.code || 'PROBE_ERROR', message: error.message } };
+  }
+  if (!process.connected) return;
+  process.send(result, () => { process.disconnect(); });
+});

package/node_modules/@mytools/fst-platform/src/file-probe.js

@@ -0,0 +1,6 @@
+import { createFileProbeEngine } from './file-probe-engine.js';
+
+/** 建立只读文件探测器，实际文件操作由独立子进程完成。 */
+export function createFileProbe(options = {}) {
+  return createFileProbeEngine(options);
+}

package/node_modules/@mytools/fst-platform/src/json.js

@@ -0,0 +1,5 @@
+import {readFile} from 'node:fs/promises';
+export async function readJson(file,fallback) {
+  try { return JSON.parse(await readFile(file,'utf8')); }
+  catch(e) { if(e.code==='ENOENT' && fallback!==undefined) return fallback; throw e; }
+}

package/node_modules/@mytools/fst-platform/src/network.js

@@ -0,0 +1,199 @@
+import {Agent,EnvHttpProxyAgent,fetch as undiciFetch} from 'undici';
+
+const privateProxy=new WeakMap();
+const profileNamePattern=/^[A-Za-z][A-Za-z0-9._-]*$/;
+const pluginIdPattern=/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+const actionIdPattern=/^[A-Za-z][A-Za-z0-9._-]*$/;
+const envNamePattern=/^[A-Za-z_][A-Za-z0-9_]*$/;
+
+function object(value,label){
+  if(value===null||typeof value!=='object'||Array.isArray(value))throw new TypeError(`${label} 必须是对象`);
+}
+
+function keys(value,allowed,label){
+  for(const key of Object.keys(value))if(!allowed.includes(key))throw new TypeError(`${label} 包含无效字段；请检查字段名称`);
+}
+
+function proxyUrl(value,label,{allowCredentials=false}={}){
+  let url;
+  try{url=new URL(value);}catch{throw new TypeError(`${label} 无效；请提供 http 或 https 代理地址`);}
+  if(typeof value!=='string'||!['http:','https:'].includes(url.protocol)||!url.hostname)throw new TypeError(`${label} 无效；请提供 http 或 https 代理地址`);
+  if(!allowCredentials&&(url.username||url.password))throw new TypeError(`${label} 无效；含凭据的代理地址请改用环境变量引用`);
+  return value;
+}
+
+function profileConfig(name,profile){
+  const label=`代理配置 ${name}`;
+  object(profile,label);
+  keys(profile,['httpUrl','httpEnv','httpsUrl','httpsEnv','noProxy','noProxyEnv'],label);
+  for(const [direct,reference] of [['httpUrl','httpEnv'],['httpsUrl','httpsEnv'],['noProxy','noProxyEnv']]){
+    if(profile[direct]!==undefined&&profile[reference]!==undefined)throw new TypeError(`${label} 的 ${direct} 和 ${reference} 不能同时设置；请只选一种来源`);
+    if(profile[reference]!==undefined&&(!envNamePattern.test(profile[reference])||typeof profile[reference]!=='string'))throw new TypeError(`${label} 的 ${reference} 无效；请使用环境变量名称`);
+    if(profile[direct]!==undefined){
+      if(typeof profile[direct]!=='string'||!profile[direct])throw new TypeError(`${label} 的 ${direct} 无效；请提供非空值`);
+      if(direct==='noProxy')continue;
+      proxyUrl(profile[direct],`${label} 的 ${direct}`);
+    }
+  }
+  if(profile.httpUrl===undefined&&profile.httpEnv===undefined&&profile.httpsUrl===undefined&&profile.httpsEnv===undefined)throw new TypeError(`${label} 缺少 HTTP 或 HTTPS 代理；请配置至少一个地址或环境变量引用`);
+}
+
+function ruleConfig(rule,label,profiles){
+  object(rule,label);
+  keys(rule,['mode','profile'],label);
+  if(!['inherit','direct','profile'].includes(rule.mode))throw new TypeError(`${label} 模式无效；请选择 inherit、direct 或 profile`);
+  if(rule.mode==='profile'){
+    if(typeof rule.profile!=='string'||!Object.hasOwn(profiles,rule.profile))throw new TypeError(`${label} 引用的代理配置不存在；请先创建配置`);
+  }else if(rule.profile!==undefined)throw new TypeError(`${label} 的配置引用无效；仅 profile 模式可引用配置`);
+}
+
+export function validateNetworkPolicy(network){
+  if(network===undefined)return {};
+  object(network,'network');
+  keys(network,['default','profiles','plugins'],'network');
+  const profiles=network.profiles??{};
+  object(profiles,'profiles');
+  for(const [name,profile] of Object.entries(profiles)){
+    if(!profileNamePattern.test(name))throw new TypeError('代理配置名称无效；请使用字母开头的标识');
+    profileConfig(name,profile);
+  }
+  if(network.default!==undefined)ruleConfig(network.default,'工作区默认规则',profiles);
+  const plugins=network.plugins??{};
+  object(plugins,'plugins');
+  for(const [pluginId,plugin] of Object.entries(plugins)){
+    if(!pluginIdPattern.test(pluginId))throw new TypeError('插件标识无效；请使用合法包名');
+    object(plugin,`插件 ${pluginId}`);
+    keys(plugin,['default','actions'],`插件 ${pluginId}`);
+    if(plugin.default!==undefined)ruleConfig(plugin.default,`插件 ${pluginId} 默认规则`,profiles);
+    const actions=plugin.actions??{};
+    object(actions,`插件 ${pluginId} 动作规则`);
+    for(const [actionId,rule] of Object.entries(actions)){
+      if(!actionIdPattern.test(actionId))throw new TypeError(`插件 ${pluginId} 的动作标识无效；请使用合法标识`);
+      ruleConfig(rule,`动作 ${pluginId}:${actionId}`,profiles);
+    }
+  }
+  return network;
+}
+
+function source(profile,profileName,field,env){
+  const label=`代理配置 ${profileName}`;
+  const direct=field==='noProxy'?'noProxy':`${field}Url`;
+  const reference=`${field}Env`;
+  if(profile[direct]!==undefined)return profile[direct];
+  if(profile[reference]===undefined)return undefined;
+  const value=env?.[profile[reference]];
+  if(typeof value!=='string'||(field!=='noProxy'&&!value))throw new TypeError(`${label} 缺少环境变量 ${profile[reference]}；请在运行环境中设置它`);
+  if(field!=='noProxy')proxyUrl(value,`${label} 的环境变量 ${profile[reference]}`,{allowCredentials:true});
+  return value;
+}
+
+function inheritedProxy(env){
+  const get=name=>env?.[name.toLowerCase()]??env?.[name];
+  const allProxy=get('ALL_PROXY');
+  const httpProxy=get('HTTP_PROXY')??allProxy??'';
+  const httpsProxy=get('HTTPS_PROXY')??get('HTTP_PROXY')??allProxy??'';
+  return {httpProxy,httpsProxy,noProxy:get('NO_PROXY')??''};
+}
+
+function selectRule(selected,pluginId,actionId){
+  const plugin=selected.plugins?.[pluginId];
+  if(actionId!==undefined&&plugin?.actions?.[actionId])return {rule:plugin.actions[actionId],source:'action'};
+  if(plugin?.default)return {rule:plugin.default,source:'plugin'};
+  if(selected.default)return {rule:selected.default,source:'workspace'};
+  return {rule:{mode:'inherit'},source:'system'};
+}
+
+export function inspectNetworkPolicy(network,{plugins=[],actions=[]}={}){
+  const selected=validateNetworkPolicy(network);
+  const installed=new Set(plugins),available=new Set(actions);
+  const entry=(id,pluginId,actionId)=>{
+    const {rule,source}=selectRule(selected,pluginId,actionId);
+    return {id,mode:rule.mode,source,...(rule.profile?{profile:rule.profile}:{})};
+  };
+  const entries=[];
+  for(const pluginId of [...installed].sort()){
+    entries.push(entry(pluginId,pluginId));
+    for(const actionId of [...available].filter(id=>id.startsWith(`${pluginId}:`)).sort())entries.push(entry(actionId,pluginId,actionId.slice(pluginId.length+1)));
+  }
+  const stalePlugins=Object.keys(selected.plugins??{}).filter(id=>!installed.has(id)).sort();
+  const staleActions=[];
+  for(const [pluginId,rule] of Object.entries(selected.plugins??{}))if(installed.has(pluginId)){
+    for(const actionId of Object.keys(rule.actions??{}))if(!available.has(`${pluginId}:${actionId}`))staleActions.push(`${pluginId}:${actionId}`);
+  }
+  staleActions.sort();
+  return {entries,stalePlugins,staleActions};
+}
+
+export function resolveNetworkPolicy(network,{pluginId,actionId,env=process.env}={}){
+  const selected=validateNetworkPolicy(network);
+  const {rule}=selectRule(selected,pluginId,actionId);
+  const resolved=rule.mode==='profile'?{mode:'profile',profile:rule.profile}:{mode:rule.mode};
+  if(rule.mode==='profile'){
+    const profile=selected.profiles[rule.profile];
+    const httpProxy=source(profile,rule.profile,'http',env)??'';
+    privateProxy.set(resolved,{
+      httpProxy,
+      httpsProxy:source(profile,rule.profile,'https',env)??httpProxy,
+      noProxy:source(profile,rule.profile,'noProxy',env)??'',
+    });
+  }else if(rule.mode==='inherit')privateProxy.set(resolved,inheritedProxy(env));
+  else privateProxy.set(resolved,{});
+  return resolved;
+}
+
+const proxyVariableNames=new Set(['http_proxy','https_proxy','all_proxy','no_proxy']);
+
+export function buildProcessEnv(resolved,{baseEnv=process.env,overrides={}}={}){
+  if(!privateProxy.has(resolved))throw new TypeError('网络策略尚未解析；请先调用 resolveNetworkPolicy');
+  const result={...baseEnv,...overrides};
+  if(resolved.mode==='inherit')return result;
+  for(const name of Object.keys(result))if(proxyVariableNames.has(name.toLowerCase()))delete result[name];
+  if(resolved.mode==='direct')return result;
+  const {httpProxy,httpsProxy,noProxy}=privateProxy.get(resolved);
+  if(httpProxy)result.HTTP_PROXY=httpProxy;
+  if(httpsProxy)result.HTTPS_PROXY=httpsProxy;
+  result.NO_PROXY=noProxy;
+  result.NODE_USE_ENV_PROXY='1';
+  return result;
+}
+
+export function createHttpClient(resolved,{signal,timeoutMs=30000}={}){
+  if(!privateProxy.has(resolved))throw new TypeError('网络策略尚未解析；请先调用 resolveNetworkPolicy');
+  const proxy=privateProxy.get(resolved);
+  let dispatcher;
+  const getDispatcher=()=>{
+    if(dispatcher)return dispatcher;
+    try{
+      dispatcher=resolved.mode==='direct'?new Agent():new EnvHttpProxyAgent({
+        httpProxy:proxy.httpProxy??'',
+        httpsProxy:proxy.httpsProxy??'',
+        noProxy:proxy.noProxy??'',
+      });
+      return dispatcher;
+    }catch{
+      const label=resolved.mode==='profile'?`配置 ${resolved.profile}`:'继承的代理环境';
+      throw new TypeError(`${label} 无效；请检查 HTTP_PROXY 和 HTTPS_PROXY`);
+    }
+  };
+  let closed=false;
+  return {
+    async fetch(input,options={}){
+      if(closed)throw new TypeError('HTTP 客户端已关闭');
+      const {timeout,timeoutMs:requestTimeoutMs,signal:requestSignal,dispatcher:ignored,...init}=options;
+      const requestTimeout=timeout??requestTimeoutMs??timeoutMs;
+      if(!Number.isSafeInteger(requestTimeout)||requestTimeout<=0)throw new TypeError('HTTP 请求超时必须是正整数毫秒数');
+      const combined=AbortSignal.any([signal,requestSignal,AbortSignal.timeout(requestTimeout)].filter(Boolean));
+      try{return await undiciFetch(input,{...init,signal:combined,dispatcher:getDispatcher()});}
+      catch(error){
+        if(combined.aborted)throw error;
+        const label=resolved.mode==='profile'?`（配置 ${resolved.profile}）`:'';
+        throw new TypeError(`HTTP 请求失败${label}；请检查目标地址或代理连接`);
+      }
+    },
+    async close(){
+      if(closed)return;
+      closed=true;
+      if(dispatcher)await dispatcher.destroy();
+    },
+  };
+}

package/node_modules/@mytools/fst-platform/src/npm.js

@@ -0,0 +1,11 @@
+import path from 'node:path';
+import {access} from 'node:fs/promises';
+import {runProcess} from './process.js';
+export async function npm(args,options={}) {
+  const candidates=[path.join(path.dirname(process.execPath),'node_modules/npm/bin/npm-cli.js'),process.env.npm_execpath].filter(Boolean);
+  for(const cli of candidates) {
+    try {await access(cli);} catch {continue;}
+    return runProcess(process.execPath,[cli,...args],{timeout:180000,...options});
+  }
+  return runProcess('npm',args,{timeout:180000,...options});
+}

package/node_modules/@mytools/fst-platform/src/process.js

@@ -0,0 +1,110 @@
+import { execa } from 'execa';
+import treeKill from 'tree-kill';
+import which from 'which';
+import { FlowError } from '@mytools/sdk';
+import path from 'node:path';
+
+const outputText=bytes=>bytes??new Uint8Array();
+const stripFinalNewline=text=>text.endsWith('\r\n')?text.slice(0,-2):text.endsWith('\n')?text.slice(0,-1):text;
+
+export async function runProcess(file,args=[],{cwd,env,extendEnv=true,signal,timeout=30000,maxBuffer=4*1024*1024,encoding='utf8',onOutput,outputMode='buffer',summaryBytes=65536}={}) {
+  if(!['buffer','stream'].includes(outputMode))throw new TypeError('outputMode 必须为 buffer 或 stream');
+  const streaming=outputMode==='stream';
+  if(streaming&&typeof onOutput!=='function')throw new TypeError('stream 模式必须提供 onOutput 消费输出');
+  if(!Number.isSafeInteger(summaryBytes)||summaryBytes<0||summaryBytes>1024*1024)throw new TypeError('summaryBytes 必须为 0 到 1048576 的整数');
+  if(typeof encoding!=='string')throw new TypeError(`不支持的程序输出编码：${String(encoding)}`);
+  const label=/^(utf16le|ucs2|ucs-2)$/i.test(encoding)?'utf-16le':encoding;
+  let decoderEncoding;
+  try {decoderEncoding=new TextDecoder(label).encoding;}
+  catch {throw new TypeError(`不支持的程序输出编码：${encoding}`);}
+  if(signal?.aborted) throw new FlowError('操作已取消',{code:'CANCELLED'});
+  let executable;
+  try {
+    // 不改变宿主 cwd；程序路径和 PATH 中相对目录都以子进程 cwd 为基准。
+    const directory=path.resolve(cwd??process.cwd()),windows=process.platform==='win32';
+    const hasPath=path.isAbsolute(file)||file.includes('/')||(windows&&file.includes('\\'));
+    const search=hasPath?[path.resolve(directory,file)]:[
+      ...(windows?[directory]:[]),...(env?.PATH??(windows?env?.Path:undefined)??process.env.PATH??'').split(path.delimiter),
+    ].map(entry=>path.resolve(directory,entry.replace(/^"(.*)"$/,'$1'),file));
+    for(const candidate of search){
+      executable=await which(candidate,{nothrow:true,pathExt:env?.PATHEXT??process.env.PATHEXT});
+      if(executable)break;
+    }
+    if(!executable)throw Object.assign(new Error(`not found: ${file}`),{code:'ENOENT'});
+  }
+  catch(cause){throw new FlowError(`未找到程序：${file}`,{code:'ENOENT',details:{executable:file},cause});}
+  // Execa 收集原始字节；文本只在这里按同一编码解码，避免返回值被默认 UTF-8 解码。
+  const child=execa(executable,args,{cwd,env,extendEnv,reject:false,windowsHide:true,maxBuffer,buffer:!streaming,timeout:0,shell:false,encoding:'buffer',stripFinalNewline:false});
+  let reason,killing,outputError,outputFailed=false,outputWrites=Promise.resolve();
+  let markStopped;const stopped=new Promise(resolve=>{markStopped=resolve;});
+  const outputBytes={stdout:0,stderr:0},tails={stdout:'',stderr:''};let outputTruncated=false;
+  const remember=(name,message)=>{
+    const bytes=Buffer.from(tails[name]+message);let start=Math.max(0,bytes.length-summaryBytes);
+    if(start){outputTruncated=true;while(start<bytes.length&&(bytes[start]&0xc0)===0x80)start++;}
+    tails[name]=bytes.subarray(start).toString('utf8');
+  };
+  const stop=kind=>{
+    if(reason) return; reason=kind;
+    markStopped();
+    killing=new Promise(resolve=>child.pid&&child.exitCode==null&&child.signalCode==null ? treeKill(child.pid,'SIGKILL',()=>resolve()) : resolve());
+  };
+  const cancel=()=>stop('cancelled');
+  signal?.addEventListener('abort',cancel,{once:true});
+  if(signal?.aborted)cancel();
+  const emit=(stream,message)=>{
+    if(!onOutput||!message)return;
+    // 立即挂接拒绝处理，不能让事件回调中的异步落盘变成未处理拒绝。
+    outputWrites=outputWrites.then(async()=>{if(!outputFailed)await onOutput({stream,message});}).catch(error=>{
+      if(!outputFailed){outputFailed=true;outputError=error;stop('output-callback');}
+    });
+    return outputWrites;
+  };
+  const flush=[],readers=[];
+  for(const [name,stream] of [['stdout',child.stdout],['stderr',child.stderr]]){
+    if(streaming){
+      // 每条流最多挂起一个块，两条流共用消费顺序；慢消费者让管道自然背压。
+      readers.push((async()=>{
+        const decoder=new TextDecoder(decoderEncoding);
+        try{
+          for await(const chunk of stream){
+            if(reason)break;outputBytes[name]+=chunk.byteLength;
+            const message=decoder.decode(chunk,{stream:true});remember(name,message);
+            await Promise.race([emit(name,message),stopped]);
+          }
+          if(!reason){const message=decoder.decode();remember(name,message);await Promise.race([emit(name,message),stopped]);}
+        }catch(error){if(!reason){outputError=error;stop('output-callback');}}
+      })());
+      continue;
+    }
+    let bytes=0,ended=false;
+    const decoder=new TextDecoder(decoderEncoding);
+    const finish=()=>{if(!ended){ended=true;emit(name,decoder.decode());}};
+    flush.push(finish);stream?.once('end',finish);
+    stream?.on('data',chunk=>{
+      bytes+=Buffer.byteLength(chunk);
+      // 流量超限时立即回收整棵进程树，不继续扩张待落盘的日志队列。
+      if(bytes>maxBuffer){stop('output-limit');return;}
+      if(onOutput)emit(name,decoder.decode(chunk,{stream:true}));
+    });
+  }
+  const timer=timeout>0 ? setTimeout(()=>stop('timeout'),timeout) : null;
+  let result;
+  try {
+    result=await child;
+  } finally {
+    for(const finish of flush)finish();
+    await Promise.all(readers);
+    await (streaming?Promise.race([outputWrites,stopped]):outputWrites);
+    clearTimeout(timer);
+    if(killing)await killing;
+    signal?.removeEventListener('abort',cancel);
+  }
+  if(reason==='output-callback')throw outputError;
+  if(reason==='output-limit')throw new FlowError('程序输出超过上限',{code:'OUTPUT_LIMIT'});
+  if(reason)throw new FlowError(reason==='cancelled'?'操作已取消':'程序运行超时',{code:reason==='cancelled'?'CANCELLED':'TIMEOUT'});
+  if(result.isMaxBuffer)throw new FlowError('程序输出超过上限',{code:'OUTPUT_LIMIT'});
+  if(result.exitCode===undefined&&result.failed)throw new FlowError(`无法启动程序 ${file}：${result.shortMessage??result.message}`,{code:result.code??'SPAWN_FAILED'});
+  const decode=bytes=>stripFinalNewline(new TextDecoder(decoderEncoding).decode(outputText(bytes)));
+  if(streaming)return {exitCode:result.exitCode,stdout:stripFinalNewline(tails.stdout),stderr:stripFinalNewline(tails.stderr),outputMode,outputTruncated,outputBytes};
+  return {exitCode:result.exitCode,stdout:decode(result.stdout),stderr:decode(result.stderr)};
+}

package/node_modules/@mytools/fst-plugin/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mytools contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/@mytools/fst-plugin/README.md

@@ -0,0 +1,29 @@
+# 插件模块
+
+包名：`@mytools/fst-plugin`。内部 workspace 包，随 `@yanglaofish/fishtools` 统一交付。
+
+## 职责与边界
+
+插件装载、契约校验、动作宿主和服务生命周期。安装批次由 workspace 负责，开发检查由 devtools 负责。
+
+内部依赖：`@mytools/sdk`、`@mytools/fst-platform`。
+## 公开入口
+
+| 导入路径 | 实现位置 |
+| --- | --- |
+| `@mytools/fst-plugin` | `./src/host.js` |
+| `@mytools/fst-plugin/loader` | `./src/loader.js` |
+| `@mytools/fst-plugin/contracts` | `./src/contracts.js` |
+| `@mytools/fst-plugin/package.json` | `./package.json` |
+
+仅依赖 exports 声明的入口，禁止消费者跨包读取 src/bin 私有文件。入口路径由本模块维护，修改协议时同步消费方回归。
+
+## 维护与验证
+
+本模块负责上述职责的实现、文档与回归；跨模块接口调整需要同时检查生产者与消费者。具体维护人员尚未指定。
+
+在仓库根目录执行：
+
+```sh
+node --test tests/modules.test.js tests/plugin-contract.test.js tests/runtime.test.js tests/plugin-host-context.test.js
+```

package/node_modules/@mytools/fst-plugin/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@mytools/fst-plugin",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/host.js",
+  "exports": {
+    ".": "./src/host.js",
+    "./loader": "./src/loader.js",
+    "./contracts": "./src/contracts.js",
+    "./privileges": "./src/privileges.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "dependencies": {
+    "@mytools/sdk": "0.1.0",
+    "@mytools/fst-platform": "0.1.0",
+    "cordis": "3.18.1",
+    "semver": "7.7.4"
+  }
+}