@yanglaofish/fishtools 0.3.0 → 0.5.0

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,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,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"
+  }
+}

package/node_modules/@mytools/fst-plugin/src/contracts.js

@@ -0,0 +1,86 @@
+import {FlowError} from '@mytools/sdk';
+import {conditionOperators} from '@mytools/sdk/conditions';
+import {resolveSchemaPath} from '@mytools/sdk/schema-path';
+import {inside} from '@mytools/fst-platform/environments';
+import path from 'node:path';
+
+export const builtinCommands=[
+  ['workflows','选择已有工作流'],['new','新建工作流'],['add','添加插件能力或子工作流'],
+  ['steps','设置步骤参数、排序或删除'],['outputs','设置最终输出'],['save','保存工作流'],
+  ['run','运行工作流，可附带 @参数.json'],['runs','运行记录：选择任意一次执行，查看进度、结果和日志'],['logs','查看运行日志'],['plugin','管理插件'],['plugins','管理插件（兼容旧入口）'],['config','配置 Fishtools'],['tools','Web 与离线文档'],
+  ['pack','选择工作流打包'],['web','启动 Web 工作台'],['docs','阅读离线开发与使用文档'],['help','查看操作说明'],['exit','退出终端工作台'],
+].map(([name,description])=>({name,description}));
+
+function validatePrivilegeDeclarations(plugin){
+  const validObject=value=>Boolean(value)&&typeof value==='object'&&!Array.isArray(value);
+  const invalid=(path,message)=>{throw new FlowError(message,{code:'VALIDATION',details:{path}});};
+  const entries=[['plugin',plugin,undefined],...Object.entries(plugin.actions??{}).map(([name,action])=>[`plugin.actions.${name}`,action,plugin])];
+  for(const [location,owner,parent] of entries){
+    if(owner.preflight!==undefined&&typeof owner.preflight!=='function')invalid(`${location}.preflight`,`${location} 的 preflight 必须为函数`);
+    if(owner.requirements===undefined)continue;
+    if(!validObject(owner.requirements))invalid(`${location}.requirements`,`${location} 的 requirements 必须为对象`);
+    const privilege=owner.requirements.privilege;
+    if(privilege===undefined)continue;
+    if(!validObject(privilege))invalid(`${location}.requirements.privilege`,`${location} 的 privilege 必须为对象`);
+    for(const [platform,requirement] of Object.entries(privilege)){
+      const at=`${location}.requirements.privilege.${platform}`;
+      if(!['linux','win32'].includes(platform))invalid(at,`不支持的权限声明平台：${platform}`);
+      if(!validObject(requirement))invalid(at,`${at} 必须为对象`);
+      const levels=platform==='linux'?['user','root','resource']:['user','administrator','resource'];
+      if(!levels.includes(requirement.level))invalid(`${at}.level`,`${at}.level 无效`);
+      for(const field of ['reason','remediation']){
+        if((requirement.level!=='user'||requirement[field]!==undefined)&&(typeof requirement[field]!=='string'||!requirement[field].trim()))invalid(`${at}.${field}`,`${at}.${field} 必须为非空字符串`);
+      }
+      if((requirement.level==='resource'||requirement.level==='administrator')&&typeof (owner.preflight??parent?.preflight)!=='function')invalid(at,`${at} 必须配套 preflight`);
+    }
+  }
+}
+
+export function validateDeclarations(plugin){
+  for(const [name,action] of Object.entries(plugin.actions??{})){
+    if(!action||typeof action!=='object'||Array.isArray(action))throw new FlowError(`动作 ${name} 的声明必须为对象`,{code:'VALIDATION'});
+    if(action.conditions!==undefined&&(!action.conditions||typeof action.conditions!=='object'||Array.isArray(action.conditions)))throw new FlowError(`动作 ${name} 的 conditions 必须为对象`,{code:'VALIDATION'});
+    for(const [key,preset] of Object.entries(action.conditions??{})){
+      if(!preset||typeof preset.title!=='string'||!preset.title.trim()||typeof preset.path!=='string'||!preset.path||preset.path.split('.').some(p=>!p||['__proto__','constructor','prototype'].includes(p))||!conditionOperators.includes(preset.op)||(preset.op!=='exists'&&!Object.hasOwn(preset,'value')))throw new FlowError(`动作 ${name} 的判定预设 ${key} 无效`,{code:'VALIDATION'});
+      try{resolveSchemaPath(action.output,preset.path);}
+      catch{throw new FlowError(`判定预设 ${key} 引用了未声明的输出字段 ${preset.path}`,{code:'VALIDATION'});}
+    }
+  }
+  for(const key of ['platforms','architectures'])if(plugin[key]!==undefined&&(!Array.isArray(plugin[key])||!plugin[key].length||!plugin[key].every(x=>typeof x==='string'&&x.trim())||new Set(plugin[key]).size!==plugin[key].length))throw new FlowError(`${plugin.id} 的 ${key} 必须是非空且不重复的字符串数组`,{code:'VALIDATION'});
+  validatePrivilegeDeclarations(plugin);
+  if(plugin.runtime?.updatePolicy!==undefined&&!['automatic','maintenance'].includes(plugin.runtime.updatePolicy))throw new FlowError('运行时 updatePolicy 必须为 automatic 或 maintenance',{code:'VALIDATION',details:{path:'plugin.runtime.updatePolicy'}});
+  for(const [owner,location,declarations] of [['插件','plugin.environments',plugin.environments],...Object.entries(plugin.actions??{}).map(([name,action])=>[`动作 ${name}`,`plugin.actions.${name}.environments`,action.environments])]){
+    if(declarations!==undefined&&(!declarations||typeof declarations!=='object'||Array.isArray(declarations)))throw new FlowError(`${owner} 的 environments 必须为对象`,{code:'VALIDATION'});
+    for(const [id,e] of Object.entries(declarations??{})){
+      const at=`${location}.${id}`;
+      const invalid=(field,message)=>{throw new FlowError(message,{code:'VALIDATION',details:{path:`${at}.${field}`}});};
+      if(!/^[\w-]+$/.test(id)||!e||!['host','bundled','tool'].includes(e.source))throw new FlowError(`环境声明无效：${plugin.id}/${id}`);
+      const validString=value=>typeof value==='string'&&Boolean(value.trim());
+      if((e.source==='host'||e.executable!==undefined)&&!(e.source==='host'?(validString(e.executable)||Array.isArray(e.executable)&&e.executable.length>0&&e.executable.every(validString)&&new Set(e.executable).size===e.executable.length):validString(e.executable)))throw new FlowError(`环境 executable 声明无效：${plugin.id}/${id}`,{code:'VALIDATION'});
+      if(e.allowedSources&&(!Array.isArray(e.allowedSources)||!e.allowedSources.includes(e.source)||!e.allowedSources.every(x=>['host','bundled','tool'].includes(x))))throw new FlowError(`环境来源范围无效：${id}`);
+      if(e.source==='tool'&&id!=='node')throw new FlowError(`工具尚未提供环境：${id}`);
+      if(e.source==='bundled'||e.artifacts!==undefined){
+        const artifacts=e.artifacts;
+        if(!artifacts||typeof artifacts!=='object'||Array.isArray(artifacts)||e.source==='bundled'&&!Object.keys(artifacts).length)invalid('artifacts',`环境 ${plugin.id}/${id} 的 artifacts 必须为非空目标字典`);
+        for(const [target,artifact] of Object.entries(artifacts)){
+          if(!target.trim()||!artifact||typeof artifact!=='object'||Array.isArray(artifact))invalid(`artifacts.${target}`,`环境 ${plugin.id}/${id} 的目标资源无效：${target}`);
+          // 与运行时使用同一包内路径规则；此处只查声明，不读取目标平台文件。
+          let directory;
+          try{if(typeof artifact.directory!=='string'||!artifact.directory.trim())throw new Error();directory=inside(process.cwd(),artifact.directory);}
+          catch{invalid(`artifacts.${target}.directory`,`环境 ${plugin.id}/${id} 的资源目录必须是包内相对路径`);}
+          try{if(typeof artifact.executable!=='string'||!artifact.executable.trim()||path.normalize(artifact.executable)==='.')throw new Error();inside(directory,artifact.executable);}
+          catch{invalid(`artifacts.${target}.executable`,`环境 ${plugin.id}/${id} 的程序路径必须是包内相对路径`);}
+        }
+      }
+    }
+  }
+}
+
+export function validateCommands(plugin,registered){
+  for(const [name,c] of Object.entries(plugin.commands??{})){
+    if(!/^[a-zA-Z][\w.-]*$/.test(name)||builtinCommands.some(x=>x.name===name)||registered.has(name))throw new FlowError(`命令名称无效或冲突：/${name}`);
+    if(!c||Boolean(c.action)===Boolean(c.run)||c.run&&typeof c.run!=='function')throw new FlowError(`命令 /${name} 必须声明 action 或 run`);
+    if(c.action&&!plugin.actions?.[c.action])throw new FlowError(`命令 /${name} 指向不存在的动作：${c.action}`);
+    registered.add(name);
+  }
+}