@yanglaofish/fishtools 0.4.0 → 0.5.1

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);
+  }
+}

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

@@ -0,0 +1,235 @@
+import { Context } from 'cordis';
+import semver from 'semver';
+import { SDK_VERSION, FlowError } from '@mytools/sdk';
+import { validate, emptyObject } from '@mytools/sdk/schema';
+import {validateDeclarations,validateCommands} from './contracts.js';
+import {prepareEnvironments,platformWarnings} from '@mytools/fst-platform/environments';
+import path from 'node:path';
+import {mkdir} from 'node:fs/promises';
+import {createHash} from 'node:crypto';
+import {createRuntime} from './runtime.js';
+import {pluginError} from '@mytools/sdk/diagnostics';
+import {validateNetworkPolicy,resolveNetworkPolicy,createHttpClient,buildProcessEnv} from '@mytools/fst-platform/network';
+import {resolvePrivilegeRequirement,resolvePrivilegePreflight,checkStaticPrivilege,runPrivilegePreflight} from './privileges.js';
+
+export async function createHost({ plugins = [], config = {}, services = {}, project,network,environmentOverrides={},runtimeEnabled=true,allowUnknownPrivileges=false } = {}) {
+  const currentNetwork=()=>typeof network==='function'?network():network;
+  validateNetworkPolicy(currentNetwork());
+  const ctx = new Context();
+  const actions = new Map();
+  const definitions = new Map();
+  const extensions = new Map();
+  const serviceNames = new Set();
+  const commandNames=new Set(),commands=new Map();
+  function bindContext(context){
+    const {application:ignored,...capabilities}=services;
+    const bound={...capabilities,...context},execute=bound.runProcess;
+    // 面向用户的输出与诊断日志共用持久化通道，只区分默认可见性。
+    bound.print=(message,data)=>Promise.resolve(bound.log?.(message,data,{audience:'user'}));
+    if(typeof execute==='function')bound.runProcess=(file,args,options={})=>{
+      const signal=context.signal&&options.signal?AbortSignal.any([context.signal,options.signal]):context.signal??options.signal;
+      return execute(file,args,{...options,signal,onOutput:async({stream,message})=>{
+        await bound.log?.(message,undefined,{stream});
+        await options.onOutput?.({stream,message});
+      }});
+    };
+    return bound;
+  }
+  async function pluginContext(plugin,action,context){
+    const bound=bindContext(context);
+    const projectDir=project?.directory??services.application?.projectDir;
+    if(bound.fs){
+      const probe=bound.fs,resolve=file=>typeof file==='string'&&!/^[/\\]{2}/.test(file)?path.resolve(projectDir??process.cwd(),file):file;
+      const options=value=>({...value,signal:context.signal&&value?.signal?AbortSignal.any([context.signal,value.signal]):context.signal??value?.signal});
+      bound.fs={stat:(file,value)=>probe.stat(resolve(file),options(value)),readDirectory:(file,value)=>probe.readDirectory(resolve(file),options(value))};
+    }
+    // 固定长度摘要避免 scoped 包名分隔符、大小写碰撞及合法长包名超出文件名上限。
+    const readOnly=project?.readOnly??services.application?.project?.readOnly;
+    const stateDir=projectDir&&!readOnly?path.join(projectDir,'.flow','plugin-state',createHash('sha256').update(plugin.id).digest('hex')):undefined;
+    if(stateDir)await mkdir(stateDir,{recursive:true});
+    for(const message of platformWarnings(plugin))await bound.log?.(message,{code:'PLATFORM_MISMATCH'},{audience:'user'});
+    const environments=await prepareEnvironments(plugin,action,environmentOverrides[plugin.id],{cwd:projectDir??process.cwd()});
+    context.signal?.throwIfAborted();
+    const policy=context.networkPolicy??currentNetwork();
+    const actionName=action?.id?.slice(plugin.id.length+1);
+    const resolved=resolveNetworkPolicy(policy,{pluginId:plugin.id,actionId:actionName});
+    if(policy?.default||policy?.plugins?.[plugin.id])await bound.log?.('网络代理规则',{mode:resolved.mode,...(resolved.profile?{profile:resolved.profile}:{})});
+    const http=createHttpClient(resolved,{signal:context.signal});
+    if(typeof bound.runProcess==='function'){
+      const execute=bound.runProcess;
+      // 已构造完整环境；禁止进程层再次合并宿主代理，恢复被策略移除的变量。
+      bound.runProcess=(file,args,options={})=>execute(file,args,{...options,env:buildProcessEnv(resolved,{overrides:options.env}),extendEnv:false});
+    }
+    bound.http={fetch:(input,options)=>http.fetch(input,options)};
+    return {capabilities:{...bound,projectDir,stateDir,environments},close:()=>http.close()};
+  }
+  async function checkPrivilege(plugin,actionName,input,context,fs){
+    const requirement=resolvePrivilegeRequirement(plugin,actionName);
+    if(!requirement.declared)return requirement;
+    const staticResult=checkStaticPrivilege(requirement);
+    let result=staticResult;
+    if(staticResult.status==='unknown')result=await runPrivilegePreflight(resolvePrivilegePreflight(plugin,actionName),input,{signal:context.signal,fs});
+    context.signal?.throwIfAborted();
+    if(result.status==='blocked')throw new FlowError(`权限不足：${result.reason??requirement.reason??plugin.id}`,{code:'INSUFFICIENT_PRIVILEGE',details:{plugin:plugin.id,action:actionName,requirement,result}});
+    if(result.status==='unknown'&&!context.allowUnknownPrivileges)throw new FlowError(`权限尚未确认：${result.reason??requirement.reason??plugin.id}`,{code:'PRIVILEGE_UNVERIFIED',details:{plugin:plugin.id,action:actionName,requirement,result}});
+    if(result.status==='unknown')await context.log?.('权限状态未确认，按本次选择继续运行',{plugin:plugin.id,action:actionName,reason:result.reason},{audience:'user'});
+    return requirement;
+  }
+  for (const entry of plugins) {
+    const plugin = entry.plugin ?? entry;
+    validateDeclarations(plugin);validateCommands(plugin,commandNames);
+    if (!plugin.id || definitions.has(plugin.id)) throw new FlowError(`插件标识缺失或重复：${plugin.id}`, {code:'VALIDATION'});
+    if (!semver.satisfies(SDK_VERSION, plugin.sdk ?? '^0.1.0')) throw new FlowError(`插件 ${plugin.id} 与 SDK ${SDK_VERSION} 不兼容`, {code:'VALIDATION'});
+    for(const [name,action] of Object.entries(plugin.actions??{})){
+      if(typeof action?.run!=='function')throw new FlowError(`动作 ${plugin.id}:${name} 缺少执行函数`);
+    }
+    for(const [name,extension] of Object.entries(plugin.services??{})){
+      if(serviceNames.has(name))throw new FlowError(`服务重复：${name}`);
+      if(typeof extension!=='function')throw new FlowError(`服务 ${name} 缺少执行函数`);
+      serviceNames.add(name);
+    }
+    definitions.set(plugin.id, {...plugin, root:entry.root});
+  }
+  const settingsById=new Map();
+  for (const plugin of definitions.values()) {
+    for (const [id, range] of Object.entries(plugin.dependencies ?? {})) {
+      if (!definitions.has(id) || !semver.satisfies(definitions.get(id).version,range)) throw new FlowError(`插件 ${plugin.id} 缺少兼容依赖 ${id}@${range}`,{code:'VALIDATION'});
+    }
+    const settings = validate(plugin.config, config[plugin.id] ?? {}, `${plugin.id} 配置`);
+    settingsById.set(plugin.id,settings);
+  }
+  const runtime=createRuntime(ctx,definitions,{enabled:runtimeEnabled});
+  let unusable=false;
+  const assertReadable=()=>{
+    if(unusable)throw new FlowError('插件运行状态无法确认，请重启应用',{code:'PLUGIN_RUNTIME_UNUSABLE'});
+  };
+  const assertHealthy=()=>{runtime.assertOpen();assertReadable();};
+  function registerPlugin(plugin,settings){
+    const registered=plugin.runtime?{...plugin,runtime:{...plugin.runtime,apply:async(scope,value)=>{
+      await checkPrivilege(plugin,undefined,{}, {allowUnknownPrivileges},services.fs);
+      return plugin.runtime.apply(scope,value);
+    }}}:plugin;
+    runtime.register(registered,settings,scope=>{
+    for(const [name,command] of Object.entries(plugin.commands??{})){
+      const action=command.action?plugin.actions[command.action]:command;
+      commands.set(name,{...command,name,plugin:plugin.id,input:action.input,output:action.output,description:command.description??action.description??action.title??name,config:settings});
+      scope.on('dispose',()=>commands.delete(name));
+    }
+      for (const [name, action] of Object.entries(plugin.actions ?? {})) {
+        const id = `${plugin.id}:${name}`;
+        if (typeof action.run !== 'function') throw new FlowError(`动作 ${id} 缺少执行函数`);
+        actions.set(id, {...action, id, plugin:plugin.id, config:settings, root:plugin.root});
+        scope.on('dispose', () => actions.delete(id));
+      }
+      for (const [name, extension] of Object.entries(plugin.services ?? {})) {
+        if (extensions.has(name)) throw new FlowError(`服务重复：${name}`);
+        extensions.set(name, {run:extension,plugin:plugin.id});
+        scope.on('dispose',()=>extensions.delete(name));
+      }
+    });
+  }
+  try{
+  for (const plugin of definitions.values())registerPlugin(plugin,settingsById.get(plugin.id));
+  await runtime.start();
+  }catch(error){
+    try{await runtime.close();}catch(cleanup){if(cleanup.message!==error.message)throw new AggregateError([error,cleanup],`${error.message}；${cleanup.message}`);}
+    throw error;
+  }
+  return {
+    definitions, actions,
+    assertHealthy,
+    invalidate(){unusable=true;},
+    get warnings(){return [...definitions.values()].flatMap(plugin=>platformWarnings(plugin).map(message=>({plugin:plugin.id,message})));},
+    get hasRuntime(){return runtime.hasRuntime;},
+    runtimeStatus:()=>runtime.status(),
+    async replace({plugins:nextEntries,config:nextConfig={},affected=[]}){
+      assertHealthy();
+      const selected=new Set(affected);
+      // 候选宿主只做声明、依赖、配置和服务图校验，不激活候选 runtime。
+      const candidate=await createHost({plugins:nextEntries,config:nextConfig,services,project,network,environmentOverrides,runtimeEnabled:false,allowUnknownPrivileges});
+      const next=new Map(candidate.definitions);
+      await candidate.close();
+      const oldDefinitions=new Map([...definitions].filter(([id])=>selected.has(id)));
+      const oldSettings=new Map([...settingsById].filter(([id])=>selected.has(id)));
+      const switchDefinitions=async(targets,settings)=>{
+        try{await runtime.remove(selected);}
+        catch(error){unusable=true;throw error;}
+        for(const id of selected){definitions.delete(id);settingsById.delete(id);}
+        for(const [id,plugin] of targets)if(selected.has(id)){
+          definitions.set(id,plugin);
+          settingsById.set(id,settings.get(id));
+        }
+        runtime.reindex();
+        for(const [id,plugin] of definitions)if(selected.has(id))registerPlugin(plugin,settingsById.get(id));
+        await runtime.ready();
+      };
+      const nextSettings=new Map();
+      for(const [id,plugin] of next)if(selected.has(id))nextSettings.set(id,validate(plugin.config,nextConfig[id]??{},`${id} 配置`));
+      try{await switchDefinitions(next,nextSettings);}
+      catch(error){
+        if(unusable)throw error;
+        try{
+          runtime.clearActivationErrors();
+          await switchDefinitions(oldDefinitions,oldSettings);
+        }catch(recovery){unusable=true;throw new AggregateError([error,recovery],`插件更新失败且恢复失败：${error.message}；${recovery.message}`);}
+        throw error;
+      }
+    },
+    commands(){assertReadable();return [...commands.values()].map(({run,preflight,config,...metadata})=>structuredClone(metadata));},
+    async invokeCommand(name,input,context={}){
+      assertHealthy();
+      const command=commands.get(name);if(!command)throw new FlowError(`命令不存在：/${name}`);
+      if(command.action)return this.invoke(`${command.plugin}:${command.action}`,input,context);
+      if(!context.ui)throw new FlowError(`交互命令 /${name} 需要在 TUI 中调用`);
+      const plugin=definitions.get(command.plugin);
+      try{
+      const getService=runtime.bindServices(plugin.id);
+      context.signal?.throwIfAborted();
+      const checked=validate(command.input??emptyObject,input,`/${name} 输入`);
+      const bound=await pluginContext(plugin,undefined,context);
+      let result;
+      try{
+        await checkPrivilege(plugin,undefined,checked,context,bound.capabilities.fs);
+        result=await command.run(checked,{...bound.capabilities,getService,config:command.config,resourceDir:plugin.root});
+      }finally{await bound.close();}
+      context.signal?.throwIfAborted();
+      return validate(command.output,JSON.parse(JSON.stringify(result??{})),`/${name} 输出`,{useDefaults:false});
+      }catch(cause){throw pluginError(cause,{plugin:plugin.id,command:`/${name}`});}
+    },
+    catalog() { assertReadable();return [...actions.values()].map(({run,preflight,config,root,...metadata})=>structuredClone(metadata)); },
+    async invoke(id, input, context = {}) {
+      assertHealthy();
+      const action = actions.get(id);
+      if (!action) throw new FlowError(`动作不存在：${id}`, {code:'VALIDATION'});
+      try{
+      const getService=runtime.bindServices(action.plugin);
+      context.signal?.throwIfAborted();
+      const checked=validate(action.input ?? emptyObject,input,`${id} 输入`);
+      const plugin=definitions.get(action.plugin),bound=await pluginContext(plugin,action,context);
+      let result;
+      try{
+        await checkPrivilege(plugin,id.slice(plugin.id.length+1),checked,context,bound.capabilities.fs);
+        result=await action.run(checked,{...bound.capabilities,getService, config:action.config, resourceDir:action.root});
+      }finally{await bound.close();}
+      context.signal?.throwIfAborted();
+      // 通过 JSON 边界验证返回值，避免函数、循环引用等进入工作流状态。
+      const encoded = JSON.stringify(result);
+      if (encoded === undefined) throw new FlowError(`${id} 输出必须可 JSON 序列化`);
+      return validate(action.output, JSON.parse(encoded),`${id} 输出`,{useDefaults:false});
+      }catch(cause){throw pluginError(cause,{plugin:action.plugin,action:id});}
+    },
+    async service(name,options) {
+      assertHealthy();
+      if (!extensions.has(name)) throw new FlowError(`未安装提供 ${name} 的插件`);
+      const extension=extensions.get(name);runtime.assertActive(extension.plugin);
+      const plugin=definitions.get(extension.plugin),bound=await pluginContext(plugin,undefined,{});
+      try{
+        await checkPrivilege(plugin,undefined,{}, {allowUnknownPrivileges},bound.capabilities.fs);
+        const result=await extension.run({...services,...bound.capabilities,application:services.application},options);
+        if(typeof result?.close!=='function'){await bound.close();return result;}
+        return {...result,close:async()=>{try{await result.close();}finally{await bound.close();}}};
+      }catch(error){await bound.close();throw error;}
+    },
+    close:()=>runtime.close(),
+  };
+}

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

@@ -0,0 +1,21 @@
+import {createRequire} from 'node:module';
+import {pathToFileURL} from 'node:url';
+import {access} from 'node:fs/promises';
+import path from 'node:path';
+import {readJson} from '@mytools/fst-platform/json';
+export async function loadPlugin(spec,base) {
+  const req=createRequire(path.join(base,'package.json'));
+  let entry;
+  if(path.isAbsolute(spec) || spec.startsWith('.')) {
+    const root=path.resolve(base,spec), pkg=await readJson(path.join(root,'package.json'));
+    entry=path.resolve(root,pkg.main??'index.js');
+  } else {
+    try {entry=req.resolve(spec);} catch {entry=createRequire(import.meta.url).resolve(spec);}
+  }
+  let root=path.dirname(entry);
+  while(root!==path.dirname(root)) {
+    try {await access(path.join(root,'package.json'));break;} catch {root=path.dirname(root);}
+  }
+  const module=await import(pathToFileURL(entry).href);
+  return {plugin:module.default,root};
+}

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

@@ -0,0 +1,91 @@
+// 权限声明按平台逐项覆盖；返回纯数据，避免把插件函数带入元数据。
+export function resolvePrivilegeRequirement(plugin,actionName,platform=process.platform){
+  const action=actionName===undefined?undefined:plugin.actions?.[actionName];
+  const actionRequirement=action?.requirements?.privilege?.[platform];
+  const pluginRequirement=plugin.requirements?.privilege?.[platform];
+  const requirement=actionRequirement??pluginRequirement;
+  if(!requirement)return {declared:false,platform,source:null,level:null};
+  const result={declared:true,platform,source:actionRequirement?'action':'plugin',level:requirement.level};
+  if(requirement.reason!==undefined)result.reason=requirement.reason;
+  if(requirement.remediation!==undefined)result.remediation=requirement.remediation;
+  return result;
+}
+
+// 动作探针优先，插件探针可为动作提供默认实现。
+export function resolvePrivilegePreflight(plugin,actionName){
+  return (actionName===undefined?undefined:plugin.actions?.[actionName]?.preflight)??plugin.preflight;
+}
+
+export function checkStaticPrivilege(requirement,options={}){
+  if(!requirement?.declared)return {status:'unknown',reason:'未声明权限要求'};
+  if(requirement.level==='user')return {status:'ok'};
+  if(requirement.level==='root'&&requirement.platform==='linux'){
+    const uid=Object.hasOwn(options,'uid')?options.uid:process.getuid?.();
+    if(uid===0)return {status:'ok'};
+    if(Number.isInteger(uid)&&uid>0)return {status:'blocked',reason:requirement.reason,remediation:requirement.remediation};
+  }
+  if(requirement.level==='administrator'&&requirement.platform==='win32'){
+    if(options.isAdministrator===true)return {status:'ok'};
+    if(options.isAdministrator===false)return {status:'blocked',reason:requirement.reason,remediation:requirement.remediation};
+  }
+  return {status:'unknown',reason:requirement.reason,remediation:requirement.remediation};
+}
+
+function normalizeResult(result){
+  if(!result||typeof result!=='object'||Array.isArray(result)||!['ok','blocked','unknown'].includes(result.status))return {status:'unknown',reason:'权限预检返回无效结果'};
+  const normalized={status:result.status};
+  for(const field of ['reason','remediation']){
+    if(result[field]===undefined)continue;
+    if(typeof result[field]!=='string'||!result[field].trim())return {status:'unknown',reason:'权限预检返回无效结果'};
+    normalized[field]=result[field];
+  }
+  return normalized;
+}
+
+function readOnlyProbe(fs,signal){
+  if(!fs)return undefined;
+  const result={};
+  for(const name of ['stat','readDirectory']){
+    if(typeof fs[name]!=='function')continue;
+    result[name]=(file,options={})=>{
+      const combined=options?.signal?AbortSignal.any([signal,options.signal]):signal;
+      return fs[name](file,{...options,signal:combined});
+    };
+  }
+  return Object.freeze(result);
+}
+
+function preflightFailure(error){
+  let detail;
+  try{detail=String(error?.message??error);}catch{detail='未知错误';}
+  return {status:'unknown',reason:`权限预检失败：${detail}`};
+}
+
+// 探针错误与超时都收敛为待确认；同步死循环无法由计时器强制中断。
+export async function runPrivilegePreflight(preflight,input,{platform=process.platform,signal,fs,timeoutMs=5000}={}){
+  if(typeof preflight!=='function')return {status:'unknown',reason:'未提供权限预检'};
+  if(signal?.aborted)return {status:'unknown',reason:'权限预检已取消'};
+  const controller=new AbortController();
+  const duration=Number.isFinite(timeoutMs)&&timeoutMs>0?timeoutMs:5000;
+  let timer,abortHandler;
+  const interrupted=new Promise(resolve=>{
+    timer=setTimeout(()=>{
+      controller.abort(new Error('权限预检超时'));
+      resolve({status:'unknown',reason:'权限预检超时'});
+    },duration);
+    if(signal){
+      abortHandler=()=>{
+        controller.abort(signal.reason);
+        resolve({status:'unknown',reason:'权限预检已取消'});
+      };
+      signal.addEventListener('abort',abortHandler,{once:true});
+      if(signal.aborted)abortHandler();
+    }
+  });
+  const work=Promise.resolve().then(()=>preflight(input,{platform,signal:controller.signal,fs:readOnlyProbe(fs,controller.signal)})).then(normalizeResult).catch(preflightFailure);
+  try{return await Promise.race([work,interrupted]);}
+  finally{
+    clearTimeout(timer);
+    if(signal&&abortHandler)signal.removeEventListener('abort',abortHandler);
+  }
+}

package/{manual/packages/core → node_modules/@mytools/fst-plugin}/src/runtime.js

@@ -32,13 +32,15 @@ export function validateRuntimes(definitions,ctx){
 }
 
 export function createRuntime(ctx,definitions,{enabled=true}={}){
-  const {providers,ordered}=validateRuntimes(definitions,ctx);
+  // 动态更新时 ctx 已含运行服务；声明检查始终以 Cordis 原生名称为准。
+  const reservedContext=new ctx.constructor();
+  let graph=validateRuntimes(definitions,reservedContext);
   const forks=new Map(),scopes=new Map(),errors=[],pending=new Set();let closing;
-  const record=(id,error)=>errors.push({plugin:id,message:error?.message??String(error)});
+  const record=(id,error,phase='activation')=>errors.push({plugin:id,phase,message:error?.message??String(error)});
   const track=(id,callback)=>{
     // 同步撤销注册，只有异步尾部进入等待集合，避免服务重激活时旧清理删掉新注册。
-    let result;try{result=callback();}catch(error){record(id,error);return;}
-    const task=Promise.resolve(result).catch(e=>record(id,e)).finally(()=>pending.delete(task));
+    let result;try{result=callback();}catch(error){record(id,error,'dispose');return;}
+    const task=Promise.resolve(result).catch(e=>record(id,e,'dispose')).finally(()=>pending.delete(task));
     pending.add(task);return task;
   };
   // 3.18.1 的 reset 会调用 dispose，但不等待 Promise；此适配只补齐等待和错误传播。
@@ -52,7 +54,7 @@ export function createRuntime(ctx,definitions,{enabled=true}={}){
   const drain=async()=>{while(pending.size)await Promise.all([...pending]);};
   const failure=()=>new FlowError(`插件生命周期失败：${errors.map(e=>`${e.plugin}: ${e.message}`).join('；')}`,{code:'PLUGIN_RUNTIME',details:{errors:structuredClone(errors)}});
   const runtime={
-    hasRuntime:[...definitions.values()].some(p=>p.runtime),
+    get hasRuntime(){return [...definitions.values()].some(p=>p.runtime);},
     register(plugin,settings,register){
       if(!enabled&&plugin.runtime)return;
       const fork=ctx.plugin({name:plugin.id,inject:plugin.runtime?.inject??[],apply(scope){
@@ -70,7 +72,7 @@ export function createRuntime(ctx,definitions,{enabled=true}={}){
             // 初始化可能仍在取得资源；先等其结束，再执行本次激活登记的清理。
             while(activation.tasks.size)await Promise.allSettled([...activation.tasks]);
             for(const dispose of activation.disposers.splice(0)){
-              try{await dispose();}catch(error){record(plugin.id,error);}
+              try{await dispose();}catch(error){record(plugin.id,error,'dispose');}
             }
           })();
         });
@@ -95,10 +97,27 @@ export function createRuntime(ctx,definitions,{enabled=true}={}){
       forks.set(plugin.id,fork);
     },
     async start(){
+      await ctx.start();await runtime.ready();
+    },
+    reindex(){graph=validateRuntimes(definitions,reservedContext);},
+    clearActivationErrors(){
+      // 启动失败可以在清理成功后恢复；清理失败必须保留，不能假定资源已释放。
+      for(let index=errors.length-1;index>=0;index--)if(errors[index].phase!=='dispose')errors.splice(index,1);
+    },
+    async remove(ids){
+      // 先撤销消费者再撤销提供者；旧作用域清理结束后才能注册新作用域。
+      const selected=new Set(ids);
+      for(const id of [...graph.ordered].reverse())if(selected.has(id)){
+        forks.get(id)?.dispose();forks.delete(id);await drain();
+      }
+      if(errors.length)throw failure();
+    },
+    async ready(){
+      // 动态注册后的 ready 监听尚未消费；Cordis start 会取出新监听并等待任务。
       await ctx.start();await drain();
       if(errors.length)throw failure();
       if(!enabled)return;
-      for(const [name,id] of providers)if(ctx.get(name)==null)throw new FlowError(`${id} 未提供声明的服务：${name}`,{code:'PLUGIN_RUNTIME'});
+      for(const [name,id] of graph.providers)if(ctx.get(name)==null)throw new FlowError(`${id} 未提供声明的服务：${name}`,{code:'PLUGIN_RUNTIME'});
       for(const p of runtime.status())if(p.status!=='ready')throw new FlowError(`${p.id} 服务尚未就绪：${p.missing.join(', ')}`,{code:'PLUGIN_RUNTIME'});
     },
     status(){return [...definitions.values()].map(p=>{
@@ -127,7 +146,7 @@ export function createRuntime(ctx,definitions,{enabled=true}={}){
     close(){
       closing??=Promise.resolve().then(async()=>{
         // 消费者先关闭，等待其使用完服务；注册撤销和依赖停用由 Cordis 执行。
-        for(const id of [...ordered].reverse()){forks.get(id)?.dispose();await drain();}
+        for(const id of [...graph.ordered].reverse()){forks.get(id)?.dispose();await drain();}
         await ctx.stop();await drain();if(errors.length)throw failure();
       });return closing;
     },

package/node_modules/@mytools/fst-workflow/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-workflow/README.md

@@ -0,0 +1,28 @@
+# 工作流模块
+
+包名：`@mytools/fst-workflow`。内部 workspace 包，随 `@yanglaofish/fishtools` 统一交付。
+
+## 职责与边界
+
+步骤执行、控制流和条件语义。工作流文件和闭包解析由 workspace 负责，运行管理由 core 负责。
+
+内部依赖：`@mytools/sdk`。
+## 公开入口
+
+| 导入路径 | 实现位置 |
+| --- | --- |
+| `@mytools/fst-workflow` | `./src/engine.js` |
+| `@mytools/fst-workflow/control` | `./src/control.js` |
+| `@mytools/fst-workflow/package.json` | `./package.json` |
+
+仅依赖 exports 声明的入口，禁止消费者跨包读取 src/bin 私有文件。入口路径由本模块维护，修改协议时同步消费方回归。
+
+## 维护与验证
+
+本模块负责上述职责的实现、文档与回归；跨模块接口调整需要同时检查生产者与消费者。具体维护人员尚未指定。
+
+在仓库根目录执行：
+
+```sh
+node --test tests/modules.test.js tests/workflows.test.js tests/control-flow.test.js
+```

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

@@ -0,0 +1,24 @@
+{
+  "name": "@mytools/fst-workflow",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/engine.js",
+  "exports": {
+    ".": "./src/engine.js",
+    "./control": "./src/control.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "dependencies": {
+    "@mytools/sdk": "0.1.0"
+  }
+}