@yanglaofish/fishtools 0.2.0 → 0.4.0

package/node_modules/@mytools/core/src/engine.js

@@ -57,7 +57,7 @@ export async function runWorkflow({store,host,id,input={},signal,onEvent=()=>{},
       let output;
       if(step.action)output=await host.invoke(step.action,args,{
         ...context,signal:currentSignal,runId,stepId:step.id,callPath,workflow:w,
-        log:(message,data,meta={})=>emit({type:'log',stream:meta.stream,...base,message,data}),
+        log:(message,data,meta={})=>emit({type:'log',stream:meta.stream,...(meta.audience==='user'?{audience:'user'}:{}),...base,message,data}),
       });
       else if(step.workflow)output=await execute(store.childId(step.workflow),args,callPath,currentSignal,reportFailure);
       else if(step.branch){

package/node_modules/@mytools/core/src/environments.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import {FlowError} from '@mytools/sdk';
+import which from 'which';
 
 export const currentTarget=()=>`${process.platform}-${process.arch}${process.platform==='linux'?'-glibc':''}`;
 export function inside(root,relative){
@@ -12,10 +13,14 @@ export function environmentDeclarations(plugin,action){return {...plugin.environ
 export function resolveEnvironments(plugin,action,overrides={},target=currentTarget()){
   return Object.fromEntries(Object.entries(environmentDeclarations(plugin,action)).map(([id,declaration])=>{
     const selected=overrides[id];
-    if(selected!==undefined&&(!selected||typeof selected!=='object'||Array.isArray(selected)||typeof selected.source!=='string'||Object.keys(selected).some(k=>k!=='source')))throw new FlowError(`环境来源覆盖无效：${plugin.id}/${id}`);
+    if(selected!==undefined&&(!selected||typeof selected!=='object'||Array.isArray(selected)||Object.keys(selected).some(k=>!['source','executable'].includes(k))||selected.source!==undefined&&typeof selected.source!=='string'||selected.executable!==undefined&&(typeof selected.executable!=='string'||!selected.executable.trim())))throw new FlowError(`环境来源覆盖无效：${plugin.id}/${id}`);
     const source=selected?.source??declaration.source;
     if(!(declaration.allowedSources??[declaration.source]).includes(source))throw new FlowError(`环境 ${plugin.id}/${id} 不允许来源 ${source}`);
     const e={...declaration,source};delete e.artifacts;
+    if(selected?.executable!==undefined){
+      if(source!=='host')throw new FlowError(`只有 host 环境允许覆盖解释器：${plugin.id}/${id}`);
+      e.executable=selected.executable;
+    }
     if(source==='tool'){
       if(id!=='node')throw new FlowError(`工具尚未提供环境：${id}`);
       e.executable=process.execPath;
@@ -27,3 +32,36 @@ export function resolveEnvironments(plugin,action,overrides={},target=currentTar
     return [id,e];
   }));
 }
+
+// 打包只解析声明；真正调用时才在当前工作区选择候选，避免将开发机路径写入跨平台分发包。
+export async function prepareEnvironments(plugin,action,overrides={}, {cwd=process.cwd()}={}){
+  const resolved=resolveEnvironments(plugin,action,overrides);
+  for(const [id,environment] of Object.entries(resolved)){
+    if(environment.source!=='host'||!Array.isArray(environment.executable)&&overrides[id]?.executable===undefined)continue;
+    const candidates=Array.isArray(environment.executable)?environment.executable:[environment.executable];
+    const windows=process.platform==='win32',directory=path.resolve(cwd);
+    const searchDirectories=[...(windows?[directory]:[]),...(process.env.PATH??'').split(path.delimiter)]
+      .map(entry=>path.resolve(directory,entry.replace(/^"(.*)"$/,'$1')));
+    let found;
+    for(const candidate of candidates){
+      const direct=path.isAbsolute(candidate)||candidate.includes('/')||windows&&candidate.includes('\\');
+      // 使用绝对候选，防止 which 在 Windows 擅自优先搜索宿主启动目录。
+      const paths=direct?[path.resolve(directory,candidate)]:searchDirectories.map(base=>path.resolve(base,candidate));
+      for(const executable of paths){
+        found=await which(executable,{nothrow:true});
+        if(found)break;
+      }
+      if(found)break;
+    }
+    if(!found)throw new FlowError(`环境 ${plugin.id}/${id} 未找到程序：${candidates.join('、')}`,{code:'ENOENT',details:{plugin:plugin.id,environment:id,candidates}});
+    environment.executable=path.resolve(found);
+  }
+  return resolved;
+}
+
+export function platformWarnings(plugin,platform=process.platform,architecture=process.arch){
+  const warnings=[];
+  if(plugin.platforms&&!plugin.platforms.includes(platform))warnings.push(`插件 ${plugin.id} 的平台声明不包含当前 ${platform}，继续执行；请核实插件支持范围`);
+  if(plugin.architectures&&!plugin.architectures.includes(architecture))warnings.push(`插件 ${plugin.id} 的架构声明不包含当前 ${architecture}，继续执行；请核实插件支持范围`);
+  return warnings;
+}

package/node_modules/@mytools/core/src/host.js

@@ -3,7 +3,10 @@ import semver from 'semver';
 import { SDK_VERSION, FlowError } from '@mytools/sdk';
 import { validate, emptyObject } from './validation.js';
 import {validateDeclarations,validateCommands} from './contracts.js';
-import {resolveEnvironments} from './environments.js';
+import {prepareEnvironments,platformWarnings} from './environments.js';
+import path from 'node:path';
+import {mkdir} from 'node:fs/promises';
+import {createHash} from 'node:crypto';
 import {createRuntime} from './runtime.js';
 import {pluginError} from './diagnostics.js';
 
@@ -16,6 +19,8 @@ export async function createHost({ plugins = [], config = {}, services = {}, env
   const commandNames=new Set(),commands=new Map();
   function bindContext(context){
     const bound={...services,...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})=>{
@@ -25,6 +30,17 @@ export async function createHost({ plugins = [], config = {}, services = {}, env
     };
     return bound;
   }
+  async function pluginContext(plugin,action,context){
+    const bound=bindContext(context),application=services.application;
+    const projectDir=application?.projectDir;
+    // 固定长度摘要避免 scoped 包名分隔符、大小写碰撞及合法长包名超出文件名上限。
+    const stateDir=projectDir&&!application.project.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();
+    return {...bound,projectDir,stateDir,environments};
+  }
   for (const entry of plugins) {
     const plugin = entry.plugin ?? entry;
     validateDeclarations(plugin);validateCommands(plugin,commandNames);
@@ -78,6 +94,7 @@ export async function createHost({ plugins = [], config = {}, services = {}, env
   }
   return {
     definitions, actions,
+    warnings:[...definitions.values()].flatMap(plugin=>platformWarnings(plugin).map(message=>({plugin:plugin.id,message}))),
     hasRuntime:runtime.hasRuntime,
     runtimeStatus:()=>runtime.status(),
     commands(){return [...commands.values()].map(({run,config,...metadata})=>structuredClone(metadata));},
@@ -90,9 +107,9 @@ export async function createHost({ plugins = [], config = {}, services = {}, env
       try{
       const getService=runtime.bindServices(plugin.id);
       context.signal?.throwIfAborted();
-      const result=await command.run(validate(command.input??emptyObject,input,`/${name} 输入`),{...bindContext(context),getService,config:command.config,resourceDir:plugin.root,environments:resolveEnvironments(plugin,undefined,environmentOverrides[plugin.id])});
+      const result=await command.run(validate(command.input??emptyObject,input,`/${name} 输入`),{...await pluginContext(plugin,undefined,context),getService,config:command.config,resourceDir:plugin.root});
       context.signal?.throwIfAborted();
-      return validate(command.output,JSON.parse(JSON.stringify(result??{})),`/${name} 输出`);
+      return validate(command.output,JSON.parse(JSON.stringify(result??{})),`/${name} 输出`,{useDefaults:false});
       }catch(cause){throw pluginError(cause,{plugin:plugin.id,command:`/${name}`});}
     },
     catalog() { return [...actions.values()].map(({run,config,root,...metadata})=>structuredClone(metadata)); },
@@ -103,12 +120,12 @@ export async function createHost({ plugins = [], config = {}, services = {}, env
       try{
       const getService=runtime.bindServices(action.plugin);
       context.signal?.throwIfAborted();
-      const result = await action.run(validate(action.input ?? emptyObject,input,`${id} 输入`), {...bindContext(context),getService, config:action.config, resourceDir:action.root,environments:resolveEnvironments(definitions.get(action.plugin),action,environmentOverrides[action.plugin])});
+      const result = await action.run(validate(action.input ?? emptyObject,input,`${id} 输入`), {...await pluginContext(definitions.get(action.plugin),action,context),getService, config:action.config, resourceDir:action.root});
       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} 输出`);
+      return validate(action.output, JSON.parse(encoded),`${id} 输出`,{useDefaults:false});
       }catch(cause){throw pluginError(cause,{plugin:action.plugin,action:id});}
     },
     async service(name,options) {

package/node_modules/@mytools/core/src/markdown-log.js

@@ -32,7 +32,7 @@ export function markdownHeader(run){
 }
 
 export function markdownEvent(event){
-  let output=`### ${names[event.type]??'事件'}\n\n`;
+  let output=`### ${event.type==='log'&&event.audience==='user'?'用户输出':names[event.type]??'事件'}\n\n`;
   const lines=[`时间：${event.time}`];
   for(const [key,label] of [['callPath','调用路径'],['action','动作'],['plugin','插件'],['command','命令'],['stream','输出流'],['durationMs','耗时（毫秒）']]){
     if(event[key]!==undefined)lines.push(`${label}：${event[key]}`);

package/node_modules/@mytools/core/src/plugin-installations.js

@@ -0,0 +1,84 @@
+import path from 'node:path';
+import {mkdir,readFile,writeFile,rename,readdir,realpath,lstat,rm,unlink,rmdir} from 'node:fs/promises';
+import {randomUUID} from 'node:crypto';
+import {isDeepStrictEqual} from 'node:util';
+import {create as archive} from 'tar';
+import {FlowError} from '@mytools/sdk';
+
+async function json(file,fallback){try{return JSON.parse(await readFile(file,'utf8'));}catch(error){if(error.code==='ENOENT')return fallback;throw error;}}
+const flow=project=>path.join(project,'.flow');
+const stateFile=project=>path.join(flow(project),'plugins.json');
+export const readPluginState=project=>json(stateFile(project),{});
+
+// 所有安装/引用/回收操作共用工作区锁，防止其他 fst 进程同时切换批次。
+export async function withPluginMutation(project,callback){
+  await mkdir(flow(project),{recursive:true});const lock=path.join(flow(project),'plugin-mutation.lock');
+  try{await mkdir(lock);}catch(error){if(error.code==='EEXIST')throw new FlowError('插件状态正在被其他进程修改；若上次异常退出，请确认没有活动 fst 后移除 .flow/plugin-mutation.lock',{code:'PLUGIN_BUSY'});throw error;}
+  try{return await callback();}finally{await rmdir(lock);}
+}
+
+export async function leaseInstallation(project,root){
+  if(!root)return async()=>{};
+  const directory=path.join(flow(project),'installation-leases');await mkdir(directory,{recursive:true});
+  const file=path.join(directory,`${randomUUID()}.json`);
+  await writeFile(file,JSON.stringify({pid:process.pid,root:path.resolve(root)}));
+  return async()=>{try{await unlink(file);}catch(error){if(error.code!=='ENOENT')throw error;}};
+}
+
+export async function openPluginState(project,{readOnly=false}={}){
+  const existing=await readPluginState(project);
+  if(readOnly||!existing.root)return {state:existing,release:async()=>{}};
+  return withPluginMutation(project,async()=>{const state=await readPluginState(project);return {state,release:await leaseInstallation(project,state.root)};});
+}
+
+export async function assertPluginState(project,expected){
+  if(!isDeepStrictEqual(await readPluginState(project),expected))throw new FlowError('插件状态已被其他进程修改，请重启当前宿主后再操作',{code:'PLUGIN_STATE_CHANGED'});
+}
+
+export async function savePluginState(project,next,previous){
+  const backup=path.join(flow(project),'plugins.previous.json'),id=randomUUID();
+  await writeFile(`${backup}.${id}.tmp`,JSON.stringify(previous,null,2));await rename(`${backup}.${id}.tmp`,backup);
+  const file=stateFile(project);await writeFile(`${file}.${id}.tmp`,JSON.stringify(next,null,2));await rename(`${file}.${id}.tmp`,file);
+}
+
+export async function collectInstallations(project,{apply=false}={}){
+  // 预览仅读取，不创建锁或备份目录；执行时在锁内重新计算，不能复用旧预览。
+  const collect=async()=>{
+    const base=path.join(flow(project),'installations'),state=await readPluginState(project),previous=await json(path.join(flow(project),'plugins.previous.json'),{});
+    const protectedRoots=new Set([state.root,state.previousRoot,previous.root].filter(Boolean).map(root=>path.resolve(root)));
+    let leases=[];try{leases=await readdir(path.join(flow(project),'installation-leases'));}catch(error){if(error.code!=='ENOENT')throw error;}
+    for(const file of leases){
+      const lease=await json(path.join(flow(project),'installation-leases',file),null);if(!lease)continue;
+      // 无法确认进程已退出时宁可保留；PID 重用只会保守地多保留一个批次。
+      try{process.kill(lease.pid,0);protectedRoots.add(path.resolve(lease.root));}catch(error){if(error.code!=='ESRCH')protectedRoots.add(path.resolve(lease.root));}
+    }
+    let entries=[];try{entries=await readdir(base,{withFileTypes:true});}catch(error){if(error.code!=='ENOENT')throw error;}
+    const candidates=[],kept=[],removed=[];
+    const canonicalBase=entries.length?await realpath(base):base;
+    if(entries.length){
+      const projectRoot=await realpath(project),relative=path.relative(projectRoot,canonicalBase);
+      if(relative==='..'||relative.startsWith('..'+path.sep)||path.isAbsolute(relative)||(await lstat(base)).isSymbolicLink())throw new FlowError('安装目录越界或是目录链接，拒绝清理');
+      for(const root of [...protectedRoots]){try{protectedRoots.add(await realpath(root));}catch(error){if(error.code!=='ENOENT')throw error;}}
+    }
+    for(const entry of entries){
+      const directory=path.join(base,entry.name);
+      if(!entry.isDirectory()||!/^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/.test(entry.name)){kept.push({directory,reason:'非受管批次'});continue;}
+      const physical=await realpath(directory);
+      if(path.dirname(physical)!==canonicalBase||(await lstat(directory)).isSymbolicLink()||protectedRoots.has(physical)){kept.push({directory,reason:'当前、恢复、活动批次或链接'});continue;}
+      const pkg=await json(path.join(directory,'package.json'),{});
+      if(pkg.name!=='flow-project-plugins'){kept.push({directory,reason:'无法确认批次归属'});continue;}
+      candidates.push({directory});
+      if(apply){
+        const backups=path.join(flow(project),'installation-backups');await mkdir(backups,{recursive:true});
+        const backup=path.join(backups,`${entry.name}-${randomUUID()}.tgz`),temporary=`${backup}.tmp`;
+        await archive({cwd:canonicalBase,file:temporary,gzip:true,follow:false,portable:true},[entry.name]);
+        await rename(temporary,backup);
+        // 备份完成后再次确认真实绝对路径仍是本项目的直接子目录，才允许递归删除。
+        if(await realpath(directory)!==physical||path.dirname(physical)!==canonicalBase)throw new FlowError('安装批次路径在清理期间改变，已停止');
+        await rm(physical,{recursive:true,maxRetries:5,retryDelay:200});removed.push({directory,backup});
+      }
+    }
+    return {candidates,kept,removed};
+  };
+  return apply?withPluginMutation(project,collect):collect();
+}

package/node_modules/@mytools/core/src/plugin-tools.js

@@ -0,0 +1,133 @@
+import path from 'node:path';
+import {readFile,writeFile,mkdir,mkdtemp,rename,rm,access} from 'node:fs/promises';
+import semver from 'semver';
+import validateNpmPackageName from 'validate-npm-package-name';
+import {SDK_VERSION} from '@mytools/sdk';
+import {loadPlugin} from './plugins.js';
+import {validateDeclarations,validateCommands} from './contracts.js';
+import {assertSchema} from './validation.js';
+import {platformWarnings} from './environments.js';
+
+const validNpmName=name=>typeof name==='string'&&validateNpmPackageName(name).validForNewPackages===true;
+const hasOwn=(value,key)=>Object.hasOwn(value,key);
+
+function inspectRequired(schema,location,warning,seen=new WeakSet()){
+  if(!schema||typeof schema!=='object'||seen.has(schema))return;
+  seen.add(schema);
+  if(Array.isArray(schema.required)){
+    schema.required.forEach((name,index)=>{
+      if(typeof name==='string'&&!hasOwn(schema.properties??{},name))warning('REQUIRED_UNDECLARED',`必填字段 ${name} 未在同层 properties 声明；请检查 required 所在层级`,`${location}.required[${index}]`);
+    });
+  }
+  for(const key of ['properties','patternProperties','$defs','definitions']){
+    for(const [name,child] of Object.entries(schema[key]??{}))inspectRequired(child,`${location}.${key}.${name}`,warning,seen);
+  }
+  for(const key of ['items','additionalProperties','not','if','then','else'])inspectRequired(schema[key],`${location}.${key}`,warning,seen);
+  for(const key of ['allOf','anyOf','oneOf','prefixItems']){
+    if(Array.isArray(schema[key]))schema[key].forEach((child,index)=>inspectRequired(child,`${location}.${key}[${index}]`,warning,seen));
+  }
+}
+
+export async function validatePluginDirectory(directory){
+  const root=path.resolve(directory),diagnostics=[];
+  const report=(severity,code,message,location)=>diagnostics.push({severity,code,message,...(location?{path:location}:{})});
+  const error=(code,message,location)=>report('error',code,message,location);
+  const warning=(code,message,location)=>report('warning',code,message,location);
+  let pkg,plugin;
+  try{pkg=JSON.parse(await readFile(path.join(root,'package.json'),'utf8'));}
+  catch(cause){error('PACKAGE_READ_FAILED',`无法读取 package.json：${cause.message}`,'package.json');return {valid:false,plugin:{},diagnostics};}
+  if(!pkg||typeof pkg!=='object'||Array.isArray(pkg)){error('INVALID_PACKAGE','package.json 必须是对象','package.json');return {valid:false,plugin:{},diagnostics};}
+  if(!validNpmName(pkg.name))error('INVALID_PACKAGE_NAME','package.json 的 name 必须是合法 npm 包名','package.json.name');
+  if(!semver.valid(pkg.version))error('INVALID_PACKAGE_VERSION','package.json 的 version 必须是 semver 版本','package.json.version');
+  if(pkg.type!=='module')error('ESM_REQUIRED','插件必须声明 type: module','package.json.type');
+  try{({plugin}=await loadPlugin('.',root));}
+  catch(cause){error('PLUGIN_LOAD_FAILED',`无法导入插件：${cause.message}`,'package.json.main');return {valid:false,plugin:{},diagnostics};}
+  if(!plugin||typeof plugin!=='object'||Array.isArray(plugin)){error('INVALID_PLUGIN','默认导出必须是插件定义对象','plugin');return {valid:false,plugin:{},diagnostics};}
+  const identity={id:plugin.id,version:plugin.version};
+  if(!validNpmName(plugin.id))error('INVALID_PLUGIN_ID','插件 id 必须是合法 npm 包名','plugin.id');
+  else if(plugin.id!==pkg.name)error('PLUGIN_ID_MISMATCH',`插件 id ${plugin.id} 与包名 ${pkg.name} 不一致`,'plugin.id');
+  if(!semver.valid(plugin.version))error('INVALID_PLUGIN_VERSION','插件 version 必须是 semver 版本','plugin.version');
+  else if(plugin.version!==pkg.version)error('PLUGIN_VERSION_MISMATCH',`插件 version ${plugin.version} 与包版本 ${pkg.version} 不一致`,'plugin.version');
+  if(typeof plugin.sdk!=='string'||!semver.validRange(plugin.sdk))error('INVALID_SDK_RANGE','插件 sdk 必须明确声明有效的 semver 范围','plugin.sdk');
+  else if(!semver.satisfies(SDK_VERSION,plugin.sdk))error('SDK_INCOMPATIBLE',`插件 SDK 范围 ${plugin.sdk} 不包含当前 ${SDK_VERSION}`,'plugin.sdk');
+  for(const [key,location] of [['platforms','plugin.platforms'],['architectures','plugin.architectures']]){
+    if(plugin[key]===undefined)warning(`${key.toUpperCase()}_UNDECLARED`,`${key} 未声明，请明确插件支持范围`,location);
+  }
+  try{validateDeclarations(plugin);}catch(cause){error('INVALID_DECLARATION',cause.message,cause.details?.path??'plugin');}
+  if(['platforms','architectures'].every(key=>plugin[key]===undefined||Array.isArray(plugin[key]))) {
+    for(const message of platformWarnings(plugin))warning('PLATFORM_MISMATCH',message,message.includes('架构')?'plugin.architectures':'plugin.platforms');
+  }
+  try{validateCommands(plugin,new Set());}catch(cause){error('INVALID_COMMAND',cause.message,'plugin.commands');}
+  for(const [location,schema] of [['plugin.config',plugin.config]]){
+    if(schema!==undefined){try{assertSchema(schema,location);inspectRequired(schema,location,warning);}catch(cause){error('INVALID_SCHEMA',cause.message,location);}}
+  }
+  if(plugin.actions!==undefined&&(!plugin.actions||typeof plugin.actions!=='object'||Array.isArray(plugin.actions)))error('INVALID_ACTIONS','actions 必须是动作字典','plugin.actions');
+  for(const [name,action] of Object.entries(plugin.actions??{})){
+    const location=`plugin.actions.${name}`;
+    if(!action||typeof action!=='object'){error('INVALID_ACTION','动作必须是对象',location);continue;}
+    if(typeof action.run!=='function')error('MISSING_RUN','动作必须声明 run 函数',`${location}.run`);
+    for(const key of ['input','output']){
+      const schema=action[key],at=`${location}.${key}`;
+      if(schema===undefined){error('MISSING_SCHEMA',`动作 ${name} 必须明确声明 ${key} schema`,at);continue;}
+      try{assertSchema(schema,at);inspectRequired(schema,at,warning);}catch(cause){error('INVALID_SCHEMA',cause.message,at);}
+    }
+  }
+  if(plugin.commands!==undefined&&(!plugin.commands||typeof plugin.commands!=='object'||Array.isArray(plugin.commands)))error('INVALID_COMMANDS','commands 必须是命令字典','plugin.commands');
+  for(const [name,command] of Object.entries(plugin.commands??{})){
+    if(!command||typeof command!=='object'||command.action)continue;
+    for(const key of ['input','output']){
+      const schema=command[key],at=`plugin.commands.${name}.${key}`;
+      if(schema===undefined){error('MISSING_SCHEMA',`命令 ${name} 必须明确声明 ${key} schema`,at);continue;}
+      try{assertSchema(schema,at);inspectRequired(schema,at,warning);}catch(cause){error('INVALID_SCHEMA',cause.message,at);}
+    }
+  }
+  if(plugin.dependencies!==undefined){
+    if(!plugin.dependencies||typeof plugin.dependencies!=='object'||Array.isArray(plugin.dependencies))error('INVALID_DEPENDENCIES','dependencies 必须是插件 ID 到版本范围的字典','plugin.dependencies');
+    else for(const [name,range] of Object.entries(plugin.dependencies)){
+      if(!validNpmName(name))error('INVALID_DEPENDENCY_ID',`依赖插件 ID 无效：${name}`,`plugin.dependencies.${name}`);
+      if(typeof range!=='string'||!semver.validRange(range))error('INVALID_DEPENDENCY_RANGE',`依赖 ${name} 的版本范围无效`,`plugin.dependencies.${name}`);
+    }
+  }
+  if(plugin.runtime!==undefined){
+    const runtime=plugin.runtime;
+    if(!runtime||typeof runtime!=='object'||Array.isArray(runtime))error('INVALID_RUNTIME','runtime 必须是声明对象','plugin.runtime');
+    else{
+      if(typeof runtime.apply!=='function')error('INVALID_RUNTIME','runtime 必须提供 apply 函数','plugin.runtime.apply');
+      for(const key of ['provides','inject']){
+        const names=runtime[key]??[];
+        if(!Array.isArray(names)||names.some(name=>typeof name!=='string'||!/^\w[\w.-]*$/.test(name))||new Set(names).size!==names.length)
+          error('INVALID_RUNTIME',`runtime.${key} 必须是不重复的有效服务名数组`,`plugin.runtime.${key}`);
+      }
+      if(Array.isArray(runtime.provides)&&Array.isArray(runtime.inject)&&runtime.inject.some(name=>runtime.provides.includes(name)))
+        error('RUNTIME_SELF_DEPENDENCY','runtime.inject 不能依赖本插件提供的服务','plugin.runtime.inject');
+    }
+  }
+  return {valid:!diagnostics.some(item=>item.severity==='error'),plugin:identity,diagnostics};
+}
+
+function scaffold(name){
+  const packageJson={name,version:'1.0.0',type:'module',main:'index.js',files:['index.js','test','README.md','LICENSE'],scripts:{test:'node --test'},license:'MIT',engines:{node:'>=24.15.0'}};
+  const plugin=`// 直接导出插件定义，无需安装内部 SDK。\nexport default {\n  id:${JSON.stringify(name)},version:'1.0.0',sdk:'^0.1.0',\n  title:'嵌套输入示例',description:'演示业务结果、嵌套输入和判定预设。',\n  platforms:['win32','linux','darwin'],architectures:['x64','arm64'],\n  actions:{\n    check:{\n      title:'检查请求',description:'根据嵌套请求生成业务结果。',\n      input:{type:'object',properties:{request:{type:'object',properties:{name:{type:'string',minLength:1,title:'姓名'},enabled:{type:'boolean',title:'启用'}},required:['name','enabled'],additionalProperties:false}},required:['request'],additionalProperties:false},\n      output:{type:'object',properties:{ok:{type:'boolean'},message:{type:'string'}},required:['ok','message'],additionalProperties:false},\n      conditions:{passed:{title:'业务通过',path:'ok',op:'eq',value:true}},\n      async run({request},{signal}={}){\n        signal?.throwIfAborted?.();\n        return request.enabled?{ok:true,message:\`你好，\${request.name}\`}:{ok:false,message:'已禁用'};\n      },\n    },\n  },\n};\n`;
+  const testSource=`import test from 'node:test';\nimport assert from 'node:assert/strict';\nimport plugin from '../index.js';\n\ntest('嵌套参数和业务判定',async()=>{\n  assert.deepEqual(await plugin.actions.check.run({request:{name:'阿青',enabled:true}}),{ok:true,message:'你好，阿青'});\n  assert.deepEqual(await plugin.actions.check.run({request:{name:'阿青',enabled:false}}),{ok:false,message:'已禁用'});\n});\n`;
+  const readme=`# ${name}\n\n可独立安装的 Fishtools 插件示例，不依赖尚未公开发布的 SDK。\n\n## 使用\n\n在本目录运行 \`npm test\`，并运行 \`fst plugin validate .\` 检查声明。安装后可将 \`${name}:check\` 加入工作流。\n\n输入示例：\n\n\`\`\`json\n{"request":{"name":"阿青","enabled":true}}\n\`\`\`\n\n输出含 \`ok\` 与 \`message\`。\`ok:false\` 表示业务未通过，但动作仍正常返回；\`conditions.passed\` 可供工作流分支使用。请同步修改 package.json 和 index.js 中的名称、版本，并根据实际支持情况调整 platforms / architectures。\n`;
+  const license=`MIT License\n\nCopyright (c) ${new Date().getFullYear()} ${name}\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the "Software"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n`;
+  return {'package.json':`${JSON.stringify(packageJson,null,2)}\n`,'index.js':plugin,'README.md':readme,'LICENSE':license,'test/plugin.test.js':testSource};
+}
+
+export async function createPlugin(name,directory=path.resolve(name)){
+  if(!validNpmName(name))throw new Error('插件名称必须是合法 npm 包名（可带 @scope）');
+  const target=path.resolve(directory),parent=path.dirname(target);
+  await mkdir(parent,{recursive:true});
+  try{await access(target);throw new Error(`目标目录已存在：${target}`);}catch(cause){if(cause.code!=='ENOENT')throw cause;}
+  const staging=await mkdtemp(path.join(parent,'.plugin-create-'));
+  try{
+    for(const [file,contents] of Object.entries(scaffold(name))){
+      const destination=path.join(staging,file);
+      await mkdir(path.dirname(destination),{recursive:true});
+      await writeFile(destination,contents,{flag:'wx'});
+    }
+    try{await access(target);throw new Error(`目标目录已存在：${target}`);}catch(cause){if(cause.code!=='ENOENT')throw cause;}
+    await rename(staging,target);
+  }catch(cause){await rm(staging,{recursive:true,force:true});throw cause;}
+  return {directory:target};
+}

package/node_modules/@mytools/core/src/plugins.js

@@ -35,21 +35,31 @@ export async function npm(args,options={}) {
   return runProcess('npm',args,{timeout:180000,...options});
 }
 
-export async function installGeneration(projectDir,{add,remove,state}) {
+export async function installGeneration(projectDir,{add,remove,link,state}) {
   const root=path.join(projectDir,'.flow','installations',randomUUID());
   await mkdir(root,{recursive:true});
   const dependencies={...(state?.dependencies??{})};
-  if(remove) delete dependencies[remove];
+  const links={...(state?.links??{})};
+  if(remove){delete dependencies[remove];delete links[remove];}
+  if(link){
+    const source=path.resolve(link),pkg=await readJson(path.join(source,'package.json'));
+    const loaded=await loadPlugin(source,projectDir);
+    if(!pkg.name||pkg.name!==loaded.plugin?.id||pkg.version!==loaded.plugin?.version)throw new FlowError('开发插件的包名/版本必须与插件 id/version 一致',{code:'VALIDATION'});
+    links[pkg.name]=source;delete dependencies[pkg.name];
+  }
   await writeFile(path.join(root,'package.json'),JSON.stringify({name:'flow-project-plugins',private:true,dependencies},null,2));
   let source=add;
   if(add) {
     try {await access(path.resolve(projectDir,add));source=path.resolve(projectDir,add);} catch {}
     if(source.startsWith('-')) throw new FlowError('插件来源不能以选项符号开头',{code:'VALIDATION'});
   }
-  const result=await npm(['install',...(source?[source]:[]),'--save-exact','--ignore-scripts','--install-links','--no-audit','--no-fund'],{cwd:root});
-  if(result.exitCode!==0) throw new FlowError(`插件安装失败：${result.stderr}`,{code:'INSTALL_FAILED'});
+  if(source||Object.keys(dependencies).length){
+    const result=await npm(['install',...(source?[source]:[]),'--save-exact','--ignore-scripts','--install-links','--no-audit','--no-fund'],{cwd:root});
+    if(result.exitCode!==0) throw new FlowError(`插件安装失败：${result.stderr}`,{code:'INSTALL_FAILED'});
+  }
   const pkg=await readJson(path.join(root,'package.json'));
   const loaded=[];
-  for(const name of Object.keys(pkg.dependencies??{})) loaded.push(await loadPlugin(name,root));
-  return {state:{root,dependencies:pkg.dependencies??{}},loaded};
+  for(const name of Object.keys(pkg.dependencies??{})){delete links[name];loaded.push(await loadPlugin(name,root));}
+  for(const source of Object.values(links))loaded.push(await loadPlugin(source,projectDir));
+  return {state:{root,dependencies:pkg.dependencies??{},links,...(state?.root?{previousRoot:state.root}:{})},loaded};
 }

package/node_modules/@mytools/core/src/process.js

@@ -2,14 +2,35 @@ import { execa } from 'execa';
 import treeKill from 'tree-kill';
 import which from 'which';
 import { FlowError } from '@mytools/sdk';
-import { StringDecoder } from 'node:string_decoder';
+import path from 'node:path';
 
-export async function runProcess(file,args=[],{cwd,env,signal,timeout=30000,maxBuffer=4*1024*1024,onOutput}={}) {
+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}={}) {
+  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 {executable=await which(file,{path:env?.PATH??process.env.PATH});}
+  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});}
-  const child=execa(executable,args,{cwd,env,reject:false,windowsHide:true,maxBuffer,timeout:0,shell:false});
+  // Execa 收集原始字节；文本只在这里按同一编码解码，避免返回值被默认 UTF-8 解码。
+  const child=execa(executable,args,{cwd,env,reject:false,windowsHide:true,maxBuffer,timeout:0,shell:false,encoding:'buffer',stripFinalNewline:false});
   let reason,killing,outputError,outputFailed=false,outputWrites=Promise.resolve();
   const stop=kind=>{
     if(reason) return; reason=kind;
@@ -28,14 +49,14 @@ export async function runProcess(file,args=[],{cwd,env,signal,timeout=30000,maxB
   const flush=[];
   for(const [name,stream] of [['stdout',child.stdout],['stderr',child.stderr]]){
     let bytes=0,ended=false;
-    const decoder=new StringDecoder('utf8');
-    const finish=()=>{if(!ended){ended=true;emit(name,decoder.end());}};
+    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.write(Buffer.isBuffer(chunk)?chunk:Buffer.from(chunk)));
+      if(onOutput)emit(name,decoder.decode(chunk,{stream:true}));
     });
   }
   const timer=timeout>0 ? setTimeout(()=>stop('timeout'),timeout) : null;
@@ -54,5 +75,6 @@ export async function runProcess(file,args=[],{cwd,env,signal,timeout=30000,maxB
   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'});
-  return {exitCode:result.exitCode,stdout:result.stdout??'',stderr:result.stderr??''};
+  const decode=bytes=>stripFinalNewline(new TextDecoder(decoderEncoding).decode(outputText(bytes)));
+  return {exitCode:result.exitCode,stdout:decode(result.stdout),stderr:decode(result.stderr)};
 }

package/node_modules/@mytools/core/src/schema-path.js

@@ -0,0 +1,31 @@
+import {FlowError} from '@mytools/sdk';
+
+const forbidden=new Set(['__proto__','constructor','prototype']);
+const missing=ref=>{throw new FlowError(`引用字段不存在：${ref}`,{code:'VALIDATION'});};
+
+// 路径只用于已声明的字段；开放对象可继续引用，带类型的动态键则继续逐层检查。
+export function resolveSchemaPath(schema,fields,ref=Array.isArray(fields)?fields.join('.'):fields){
+  const parts=Array.isArray(fields)?fields:typeof fields==='string'?fields.split('.'):[];
+  if(!parts.length)return schema;
+  if(parts.some(part=>typeof part!=='string'||!part||forbidden.has(part)))missing(ref);
+  let current=schema;
+  for(const field of parts){
+    if(current===true){continue;}
+    if(current===false||!current||typeof current!=='object'||Array.isArray(current))missing(ref);
+    const types=Array.isArray(current.type)?current.type:[current.type];
+    const isArray=types.includes('array')||current.items!==undefined;
+    if(isArray){
+      if(!/^(0|[1-9]\d*)$/.test(field))missing(ref);
+      if(Array.isArray(current.items))current=current.items[Number(field)]??current.additionalItems??true;
+      else current=current.items??true;
+      continue;
+    }
+    if(current.properties&&Object.hasOwn(current.properties,field)){
+      current=current.properties[field];continue;
+    }
+    if(!types.includes('object')&&types.some(type=>type!==undefined))missing(ref);
+    current=current.additionalProperties??true;
+  }
+  if(current===false)missing(ref);
+  return current;
+}

package/node_modules/@mytools/core/src/terminal/model.js

@@ -15,7 +15,7 @@ export function parseCommand(text){
   }
   if(quote)throw new Error('文件路径的引号未闭合');
   if(started)args.push(token);
-  if(!args[0]?.startsWith('/'))throw new Error('请输入 / 选择操作，例如 /workflows 或 /run');
+  if(!args[0]?.startsWith('/'))throw Object.assign(new Error('这不是斜杠命令。输入 / 选择操作；执行工作流请用 /run 工作流ID。'),{code:'COMMAND_INPUT'});
   args[0]=args[0].slice(1);return args;
 }
 

package/node_modules/@mytools/core/src/terminal/navigation.js

@@ -0,0 +1,17 @@
+import {builtinCommands} from '../contracts.js';
+
+const visible=['workflows','run','pack','logs','plugin','config','tools','help','exit'];
+// 入口由插件 ID 推导；冲突时加前缀，不能覆盖内置或作者注册的命令。
+export function commandMenu(plugins,commands){
+  const entries=builtinCommands.filter(command=>visible.includes(command.name)).map(command=>({...command,description:`[内置] ${command.description}`}));
+  const used=new Set([...builtinCommands.map(c=>c.name),...commands.map(c=>c.name)]);
+  const groups=plugins.filter(plugin=>commands.some(c=>c.plugin===plugin.id)).sort((a,b)=>a.id.localeCompare(b.id));
+  for(const plugin of groups){
+    const leaf=plugin.id.split('/').at(-1).replace(/[^\w.-]/g,'-');
+    let name=/^[a-zA-Z]/.test(leaf)?leaf:`plugin-${leaf}`;
+    if(groups.filter(p=>p.id.split('/').at(-1)===leaf).length>1)name=plugin.id.replace(/^@/,'').replace(/[^\w.-]/g,'-');
+    while(used.has(name))name='plugin-'+name;
+    used.add(name);entries.push({name,plugin:plugin.id,description:`[插件] ${plugin.title??plugin.id} · ${plugin.id}`});
+  }
+  return entries;
+}

package/node_modules/@mytools/core/src/terminal/presentation.js

@@ -11,8 +11,8 @@ export function gettingStarted(flows,{readOnly=false}={}){
   return [
     sample?`试运行  /run ${sample.id}\n${sample.description??sample.title??'按提示填写参数，执行后查看结果。'}`:'当前工作区还没有工作流。',
     '',
-    `/workflows 工作流   /plugins 插件`,
-    `${readOnly?'只读运行包': '/new 新建'}   /runs 运行观察   /help 帮助`,
+    `/workflows ${readOnly?'浏览工作流':'管理工作流'}   /plugin 插件   /config 工具配置`,
+    `/logs 回看执行记录、输入输出与日志   /help 帮助`,
   ].join('\n');
 }
 
@@ -37,6 +37,6 @@ export function pluginDetails(plugin,actions,commands){
     '## 环境声明',
     ...[plugin,...actions].flatMap(item=>Object.entries(item.environments??{}).map(([name,e])=>`- ${item.id} / ${name}：${({host:'使用宿主机环境',bundled:'随包携带',tool:'使用 Fishtools 自带环境'})[e.source]??e.source}`)),
     '环境与平台由插件作者声明；具体执行结果请在 /logs 查看。',
-    '编排用法：/new 新建工作流 → /add 选择上述能力 → 填写参数 → /save → /run。',
+    '编排用法：/workflows 新建工作流 → 添加步骤并选择上述能力 → 填写参数 → 保存 → 运行。也可在主面板用 /run 选择已保存的工作流。',
   ].join('\n\n');
 }