@yanglaofish/fishtools 0.3.0 → 0.4.0

package/manual/packages/core/src/application.js

@@ -14,8 +14,9 @@ import {createResources} from './resources.js';
 import {errorRecord} from './diagnostics.js';
 import {markdownHeader,markdownEvent,markdownResult} from './markdown-log.js';
 import {createRunLogs,validateKeepRuns} from './run-logs.js';
+import {openPluginState,withPluginMutation,assertPluginState,savePluginState,leaseInstallation} from './plugin-installations.js';
 
-export async function createApplication({projectDir=process.cwd(),workspace,outputDir,plugins,config={},maintenance=false}={}) {
+export async function createApplication({projectDir=process.cwd(),workspace,outputDir,plugins,config={},maintenance=false,omitInstalledPlugin}={}) {
   projectDir=await prepareBundleWorkspace(path.resolve(projectDir),workspace);
   const project=await readJson(path.join(projectDir,'flow.project.json'),{plugins:[]});
   const output=path.resolve(outputDir??process.env.FLOW_OUTPUT_DIR??(project.readOnly?path.join(process.cwd(),'flow-results'):path.join(projectDir,'.flow','runs')));
@@ -24,13 +25,14 @@ export async function createApplication({projectDir=process.cwd(),workspace,outp
   const resources=createResources(),operations=new Set();let closing,launching=0;
   const runLogs=createRunLogs(output,{projectDir,allowLegacy:output===path.join(projectDir,'.flow','runs')}),writingRuns=new Set();
   validateKeepRuns(project.logs?.keepRuns??null);
-  let host,state=await readJson(path.join(projectDir,'.flow','plugins.json'),{}),busy=false;
+  const opened=await openPluginState(projectDir,{readOnly:project.readOnly});
+  let host,state=opened.state,releaseInstallation=opened.release,busy=false;
   const app={
     projectDir,project,outputDir:output,store,
     get host(){return host;},
     get maintenance(){return maintenance;},
     catalog:()=>host.catalog(),
-    listPlugins:()=>[...host.definitions.values()].map(p=>({id:p.id,version:p.version,title:p.title,description:p.description,platforms:p.platforms,architectures:p.architectures,environments:p.environments,config:p.config,runtime:host.runtimeStatus().find(r=>r.id===p.id),removable:!!state.dependencies?.[p.id]})),
+    listPlugins:()=>[...host.definitions.values()].map(p=>({id:p.id,version:p.version,title:p.title,description:p.description,platforms:p.platforms,architectures:p.architectures,environments:p.environments,config:p.config,runtime:host.runtimeStatus().find(r=>r.id===p.id),removable:!!(state.dependencies?.[p.id]||state.links?.[p.id]),development:!!state.links?.[p.id],warnings:host.warnings.filter(item=>item.plugin===p.id).map(item=>item.message)})),
     listCommands:()=>host.commands(),
     listWorkflows:()=>store.list(),
     async saveWorkflow(w){if(project.readOnly)throw new FlowError('此分发包仅用于运行；请在开发项目中编辑');return store.save(w);},
@@ -114,14 +116,20 @@ export async function createApplication({projectDir=process.cwd(),workspace,outp
       if(busy)throw new FlowError('项目正在更新，请稍后修改日志设置');
       busy=true;
       try{
-        const logs={...project.logs,keepRuns},file=path.join(projectDir,'flow.project.json'),temp=`${file}.${randomUUID()}.tmp`;
-        await mkdir(projectDir,{recursive:true});await writeFile(temp,JSON.stringify({...project,logs},null,2));await rename(temp,file);project.logs=logs;
-        await pruneLogs();
+        await withPluginMutation(projectDir,async()=>{
+          const file=path.join(projectDir,'flow.project.json'),latest=await readJson(file,project);
+          if(latest.readOnly)throw new FlowError('只读运行包不能保存日志设置');
+          const nextProject={...latest,logs:{...latest.logs,keepRuns}},temp=`${file}.${randomUUID()}.tmp`;
+          await writeFile(temp,JSON.stringify(nextProject,null,2));await rename(temp,file);
+          for(const key of Object.keys(project))delete project[key];Object.assign(project,nextProject);
+          await pruneLogs();
+        });
       }finally{busy=false;}
     },
     cancelRun(id){const r=runs.get(id);if(r?.status==='running')r.controller.abort();return !!r;},
     async installPlugin(source){return change({add:source});},
-    async removePlugin(name){if(resources.active(name))throw new FlowError('请先停止此插件提供的 Web');if(!state.dependencies?.[name])throw new FlowError('此插件来自发行配置，不能在此移除');return change({remove:name});},
+    async linkPlugin(source){return change({link:path.resolve(projectDir,source)});},
+    async removePlugin(name){if(resources.active(name))throw new FlowError('请先停止此插件提供的 Web');if(!state.dependencies?.[name]&&!state.links?.[name])throw new FlowError('此插件来自发行配置，不能在此移除');return change({remove:name});},
     async pack(options){const {packApplication}=await import('@mytools/pack');return packApplication(app,options);},
     async packPlan(options){const {planApplication}=await import('@mytools/pack');return planApplication(app,options);},
     async configurePlugin(id,value){
@@ -133,11 +141,18 @@ export async function createApplication({projectDir=process.cwd(),workspace,outp
       value=validate(host.definitions.get(id).config,value,`${id} 配置`);
       busy=true;let nextHost;
       try{
-        const nextConfig={...project.config,[id]:value};
-        nextHost=await createHost({plugins:[...host.definitions.values()].map(p=>({plugin:p,root:p.root})),config:{...nextConfig,...config},services,environmentOverrides:project.environments,runtimeEnabled:!maintenance});
-        const nextProject={...project,config:nextConfig},file=path.join(projectDir,'flow.project.json'),temp=`${file}.${randomUUID()}.tmp`;
+        await withPluginMutation(projectDir,async()=>{
+        await assertPluginState(projectDir,state);
+        const file=path.join(projectDir,'flow.project.json'),latest=await readJson(file,project);
+        if(latest.readOnly)throw new FlowError('只读项目不能保存配置');
+        const nextConfig={...latest.config,[id]:value};
+        nextHost=await createHost({plugins:[...host.definitions.values()].map(p=>({plugin:p,root:p.root})),config:{...nextConfig,...config},services,environmentOverrides:latest.environments,runtimeEnabled:!maintenance});
+        const nextProject={...latest,config:nextConfig},temp=`${file}.${randomUUID()}.tmp`;
         await writeFile(temp,JSON.stringify(nextProject,null,2));await rename(temp,file);
-        const old=host;host=nextHost;nextHost=null;project.config=nextConfig;await old.close();
+        const old=host;host=nextHost;nextHost=null;
+        for(const key of Object.keys(project))delete project[key];Object.assign(project,nextProject);
+        await old.close();
+        });
       }finally{try{if(nextHost)await nextHost.close();}finally{busy=false;}}
     },
     async setMaintenance(enabled){
@@ -167,17 +182,22 @@ export async function createApplication({projectDir=process.cwd(),workspace,outp
         const errors=[];
         try{await resources.close();}catch(error){errors.push(error);}
         try{await host.close();}catch(error){errors.push(error);}
+        try{await releaseInstallation();}catch(error){errors.push(error);}
         if(errors.length)throw new AggregateError(errors,`应用关闭失败：${errors.map(e=>e.message).join('；')}`);
       });return closing;
     },
   };
-  const initial=plugins??await Promise.all((project.plugins??[]).map(spec=>loadPlugin(spec,project.baseBundle?.root??projectDir)));
+  let initial;
   const services={application:app,runProcess};
   const build=extra=>createHost({plugins:[...initial,...extra],config:{...project.config,...config},services,environmentOverrides:project.environments,runtimeEnabled:!maintenance});
-  const external=[];
-  for(const name of Object.keys(state.dependencies??{}))external.push(await loadPlugin(name,state.root));
-  host=await build(external);
-  for(const name of ['startRun','startCommand','startWeb','saveWorkflow','removeWorkflow','installPlugin','removePlugin','configurePlugin','configureLogs','setMaintenance','pack']){
+  try{
+    initial=plugins??await Promise.all((project.plugins??[]).map(spec=>loadPlugin(spec,project.baseBundle?.root??projectDir)));
+    const external=[];
+    for(const name of Object.keys(state.dependencies??{}))if(!maintenance||name!==omitInstalledPlugin)external.push(await loadPlugin(name,state.root));
+    for(const [name,source] of Object.entries(state.links??{}))if(!maintenance||name!==omitInstalledPlugin)external.push(await loadPlugin(source,projectDir));
+    host=await build(external);
+  }catch(error){await releaseInstallation();throw error;}
+  for(const name of ['startRun','startCommand','startWeb','saveWorkflow','removeWorkflow','installPlugin','linkPlugin','removePlugin','configurePlugin','configureLogs','setMaintenance','pack']){
     const original=app[name],isRun=['startRun','startCommand'].includes(name);
     app[name]=async(...args)=>{
       if(closing)throw new FlowError('应用已关闭');
@@ -193,19 +213,23 @@ export async function createApplication({projectDir=process.cwd(),workspace,outp
     if(project.readOnly)throw new FlowError('运行包不支持安装或移除插件');
     assertMutable();
     if(busy || launching || [...runs.values()].some(r=>r.status==='running'))throw new FlowError('请等待当前运行或安装结束');
-    busy=true;let nextHost;
+    busy=true;let nextHost,nextRelease;
     try {
+      return await withPluginMutation(projectDir,async()=>{
+      await assertPluginState(projectDir,state);
       const next=await installGeneration(projectDir,{...operation,state});
       for(const p of host.definitions.values())if(resources.active(p.id)){
         const candidate=[...initial,...next.loaded].find(e=>(e.plugin??e).id===p.id);
         if(!candidate||candidate.root!==p.root||(candidate.plugin??candidate).version!==p.version)throw new FlowError('请先停止活动 Web，再替换其提供者');
       }
       nextHost=await build(next.loaded);
-      const file=path.join(projectDir,'.flow','plugins.json'),temp=`${file}.tmp`;
-      await writeFile(temp,JSON.stringify(next.state,null,2));await rename(temp,file);
-      const old=host;host=nextHost;nextHost=null;state=next.state;await old.close();
+      nextRelease=await leaseInstallation(projectDir,next.state.root);
+      await savePluginState(projectDir,next.state,state);
+      const old=host,oldRelease=releaseInstallation;host=nextHost;nextHost=null;state=next.state;releaseInstallation=nextRelease;nextRelease=null;
+      try{await old.close();}finally{await oldRelease();}
       return app.listPlugins();
-    } finally {try{if(nextHost)await nextHost.close();}finally{busy=false;}}
+      });
+    } finally {try{if(nextHost)await nextHost.close();}finally{try{if(nextRelease)await nextRelease();}finally{busy=false;}}}
   }
   return app;
 }

package/manual/packages/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';
 
@@ -27,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);
@@ -80,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));},
@@ -92,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)); },
@@ -105,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/bin/fst.js

@@ -8,12 +8,15 @@ import { resolveProject, initializeProject } from '../src/project.js';
 import {waitForCliRun,cliRunResult} from '../src/cli-run.js';
 import {VERSION} from '../src/version.js';
 import {listDocumentation,readDocumentation,findDocumentationRoot,exportDocumentation} from '../src/documentation.js';
+import {collectInstallations} from '../src/plugin-installations.js';
+import {prepareBundleWorkspace} from '../src/bundle-workspace.js';
+import {readJson} from '../src/plugins.js';
 
 const program=new Command().name('fst').description('Fishtools · 插件式工作流工作台').version(VERSION);
 program.option('--maintenance','维护模式：不启动有状态服务插件');
 program.option('--project <directory>','项目目录（默认当前项目或用户工作区）').option('--workspace <directory>','便携包的可写工作区').option('--output <directory>','日志与结果目录').option('--config <file>','插件配置覆盖文件').option('--host <host>','Web 监听地址','127.0.0.1').option('--port <port>','Web 监听端口','8765');
-async function app(){const o=program.opts();return createApplication({projectDir:await resolveProject(o.project,o.workspace),outputDir:o.output,maintenance:!!o.maintenance,config:o.config?JSON.parse(await readFile(o.config,'utf8')):{}});}
-async function use(fn){const a=await app();try{return await fn(a);}finally{await a.close();}}
+async function app({management=false,removeInstalled}={}){const o=program.opts();return createApplication({projectDir:await resolveProject(o.project,o.workspace),outputDir:o.output,maintenance:management||!!o.maintenance,omitInstalledPlugin:removeInstalled,config:o.config?JSON.parse(await readFile(o.config,'utf8')):{}});}
+async function use(fn,options){const a=await app(options);try{for(const warning of a.host.warnings)console.error(`警告：${warning.message}`);return await fn(a);}finally{await a.close();}}
 program.command('init [directory]').description('创建项目，保留已有配置与工作流').action(async directory=>console.log(`Fishtools 项目：${await initializeProject(path.resolve(directory??process.cwd()))}`));
 program.command('docs [topic]').description('阅读或导出随安装提供的离线文档').option('--path','只打印文档路径').option('--export <directory>','导出完整资料到新目录').action(async(topic,options)=>{
   if(options.export){if(topic||options.path)throw new Error('--export 不可与文档主题或 --path 同用');console.log(await exportDocumentation(options.export));return;}
@@ -32,8 +35,27 @@ program.command('run <id>').option('--input <file>','JSON 输入文件').action(
 }));
 const plugin=program.command('plugin').description('管理插件');
 plugin.command('list').action(()=>use(a=>console.log(JSON.stringify(a.listPlugins(),null,2))));
-plugin.command('add <source>').action(source=>use(async a=>console.log(JSON.stringify(await a.installPlugin(source),null,2))));
-plugin.command('remove <name>').action(name=>use(async a=>console.log(JSON.stringify(await a.removePlugin(name),null,2))));
+plugin.command('add <source>').action(source=>use(async a=>console.log(JSON.stringify(await a.installPlugin(source),null,2)),{management:true}));
+plugin.command('link <directory>').description('引用本地开发源码，修改后重启 fst 生效').action(directory=>use(async a=>console.log(JSON.stringify(await a.linkPlugin(path.resolve(directory)),null,2)),{management:true}));
+plugin.command('remove <name>').action(name=>use(async a=>console.log(JSON.stringify(await a.removePlugin(name),null,2)),{management:true,removeInstalled:name}));
+plugin.command('validate <directory>').description('检查可信插件声明，不执行动作或运行时服务').option('--json','输出结构化报告').action(async(directory,options)=>{
+  const {validatePluginDirectory}=await import('../src/plugin-tools.js');const report=await validatePluginDirectory(path.resolve(directory));
+  if(options.json)console.log(JSON.stringify(report,null,2));else{
+    console.log(`${report.valid?'检查通过':'检查未通过'}：${report.plugin?.id??directory}`);
+    for(const item of report.diagnostics)console.log(`${item.severity==='error'?'错误':'警告'} [${item.code}] ${item.path??''} ${item.message}`);
+  }
+  if(!report.valid)process.exitCode=1;
+});
+plugin.command('create <name> [directory]').description('创建可独立安装的插件骨架').action(async(name,directory)=>{
+  const {createPlugin}=await import('../src/plugin-tools.js');const result=await createPlugin(name,path.resolve(directory??name));
+  console.log(`插件已创建：${result.directory}\n运行 fst plugin validate "${result.directory}" 检查；使用 fst plugin link "${result.directory}" 开发`);
+});
+plugin.command('gc').description('预览未引用安装批次；--apply 先备份再清理').option('--apply','压缩备份后清理安全批次').action(async options=>{
+  const settings=program.opts(),projectDir=await prepareBundleWorkspace(await resolveProject(settings.project,settings.workspace),settings.workspace);
+  const project=await readJson(path.join(projectDir,'flow.project.json'),{});
+  if(project.readOnly)throw new Error('只读项目不能清理插件批次');
+  console.log(JSON.stringify(await collectInstallations(projectDir,{apply:!!options.apply}),null,2));
+});
 const packOptions=command=>command.requiredOption('--target <target>','win32-x64 或 linux-x64-glibc').option('--out <directory>','导出目录','dist').option('--read-only','导出只读精简运行包').option('--environments <file>','环境来源覆盖 JSON').option('--plan','只查看打包资源计划');
 async function pack(a,entries,o,portable=false){
   const options={entries,target:o.target,outDir:o.out,includeWeb:!!o.web,readOnly:!!o.readOnly,portable,environments:o.environments?JSON.parse(await readFile(o.environments,'utf8')):{}};
@@ -46,7 +68,7 @@ program.command('command [name]').description('列出插件命令或执行动作
   const run=await a.startCommand(name,o.input?JSON.parse(await readFile(o.input,'utf8')):{});
   const result=cliRunResult(await waitForCliRun(a,run));console.log(JSON.stringify(result.value,null,2));process.exitCode=result.exitCode;
 }));
-program.command('configure <plugin> <file>').description('从 JSON 保存插件配置').action((id,file)=>use(async a=>{await a.configurePlugin(id,JSON.parse(await readFile(file,'utf8')));console.log('插件配置已保存');}));
+program.command('configure <plugin> <file>').description('从 JSON 保存插件配置').action((id,file)=>use(async a=>{await a.configurePlugin(id,JSON.parse(await readFile(file,'utf8')));console.log('插件配置已保存');},{management:true}));
 async function web(o){
   const a=await app();let server;
   try{server=await a.startWeb({host:o.host,port:Number(o.port)});}catch(error){await a.close();throw error;}

package/node_modules/@mytools/core/package.json

@@ -29,7 +29,9 @@
     "cordis": "3.18.1",
     "execa": "10.1.0",
     "semver": "7.7.4",
+    "tar": "7.5.22",
     "tree-kill": "1.2.2",
+    "validate-npm-package-name": "8.0.0",
     "which": "7.0.0",
     "yaml": "2.9.1"
   }

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

@@ -14,8 +14,9 @@ import {createResources} from './resources.js';
 import {errorRecord} from './diagnostics.js';
 import {markdownHeader,markdownEvent,markdownResult} from './markdown-log.js';
 import {createRunLogs,validateKeepRuns} from './run-logs.js';
+import {openPluginState,withPluginMutation,assertPluginState,savePluginState,leaseInstallation} from './plugin-installations.js';
 
-export async function createApplication({projectDir=process.cwd(),workspace,outputDir,plugins,config={},maintenance=false}={}) {
+export async function createApplication({projectDir=process.cwd(),workspace,outputDir,plugins,config={},maintenance=false,omitInstalledPlugin}={}) {
   projectDir=await prepareBundleWorkspace(path.resolve(projectDir),workspace);
   const project=await readJson(path.join(projectDir,'flow.project.json'),{plugins:[]});
   const output=path.resolve(outputDir??process.env.FLOW_OUTPUT_DIR??(project.readOnly?path.join(process.cwd(),'flow-results'):path.join(projectDir,'.flow','runs')));
@@ -24,13 +25,14 @@ export async function createApplication({projectDir=process.cwd(),workspace,outp
   const resources=createResources(),operations=new Set();let closing,launching=0;
   const runLogs=createRunLogs(output,{projectDir,allowLegacy:output===path.join(projectDir,'.flow','runs')}),writingRuns=new Set();
   validateKeepRuns(project.logs?.keepRuns??null);
-  let host,state=await readJson(path.join(projectDir,'.flow','plugins.json'),{}),busy=false;
+  const opened=await openPluginState(projectDir,{readOnly:project.readOnly});
+  let host,state=opened.state,releaseInstallation=opened.release,busy=false;
   const app={
     projectDir,project,outputDir:output,store,
     get host(){return host;},
     get maintenance(){return maintenance;},
     catalog:()=>host.catalog(),
-    listPlugins:()=>[...host.definitions.values()].map(p=>({id:p.id,version:p.version,title:p.title,description:p.description,platforms:p.platforms,architectures:p.architectures,environments:p.environments,config:p.config,runtime:host.runtimeStatus().find(r=>r.id===p.id),removable:!!state.dependencies?.[p.id]})),
+    listPlugins:()=>[...host.definitions.values()].map(p=>({id:p.id,version:p.version,title:p.title,description:p.description,platforms:p.platforms,architectures:p.architectures,environments:p.environments,config:p.config,runtime:host.runtimeStatus().find(r=>r.id===p.id),removable:!!(state.dependencies?.[p.id]||state.links?.[p.id]),development:!!state.links?.[p.id],warnings:host.warnings.filter(item=>item.plugin===p.id).map(item=>item.message)})),
     listCommands:()=>host.commands(),
     listWorkflows:()=>store.list(),
     async saveWorkflow(w){if(project.readOnly)throw new FlowError('此分发包仅用于运行；请在开发项目中编辑');return store.save(w);},
@@ -114,14 +116,20 @@ export async function createApplication({projectDir=process.cwd(),workspace,outp
       if(busy)throw new FlowError('项目正在更新，请稍后修改日志设置');
       busy=true;
       try{
-        const logs={...project.logs,keepRuns},file=path.join(projectDir,'flow.project.json'),temp=`${file}.${randomUUID()}.tmp`;
-        await mkdir(projectDir,{recursive:true});await writeFile(temp,JSON.stringify({...project,logs},null,2));await rename(temp,file);project.logs=logs;
-        await pruneLogs();
+        await withPluginMutation(projectDir,async()=>{
+          const file=path.join(projectDir,'flow.project.json'),latest=await readJson(file,project);
+          if(latest.readOnly)throw new FlowError('只读运行包不能保存日志设置');
+          const nextProject={...latest,logs:{...latest.logs,keepRuns}},temp=`${file}.${randomUUID()}.tmp`;
+          await writeFile(temp,JSON.stringify(nextProject,null,2));await rename(temp,file);
+          for(const key of Object.keys(project))delete project[key];Object.assign(project,nextProject);
+          await pruneLogs();
+        });
       }finally{busy=false;}
     },
     cancelRun(id){const r=runs.get(id);if(r?.status==='running')r.controller.abort();return !!r;},
     async installPlugin(source){return change({add:source});},
-    async removePlugin(name){if(resources.active(name))throw new FlowError('请先停止此插件提供的 Web');if(!state.dependencies?.[name])throw new FlowError('此插件来自发行配置，不能在此移除');return change({remove:name});},
+    async linkPlugin(source){return change({link:path.resolve(projectDir,source)});},
+    async removePlugin(name){if(resources.active(name))throw new FlowError('请先停止此插件提供的 Web');if(!state.dependencies?.[name]&&!state.links?.[name])throw new FlowError('此插件来自发行配置，不能在此移除');return change({remove:name});},
     async pack(options){const {packApplication}=await import('@mytools/pack');return packApplication(app,options);},
     async packPlan(options){const {planApplication}=await import('@mytools/pack');return planApplication(app,options);},
     async configurePlugin(id,value){
@@ -133,11 +141,18 @@ export async function createApplication({projectDir=process.cwd(),workspace,outp
       value=validate(host.definitions.get(id).config,value,`${id} 配置`);
       busy=true;let nextHost;
       try{
-        const nextConfig={...project.config,[id]:value};
-        nextHost=await createHost({plugins:[...host.definitions.values()].map(p=>({plugin:p,root:p.root})),config:{...nextConfig,...config},services,environmentOverrides:project.environments,runtimeEnabled:!maintenance});
-        const nextProject={...project,config:nextConfig},file=path.join(projectDir,'flow.project.json'),temp=`${file}.${randomUUID()}.tmp`;
+        await withPluginMutation(projectDir,async()=>{
+        await assertPluginState(projectDir,state);
+        const file=path.join(projectDir,'flow.project.json'),latest=await readJson(file,project);
+        if(latest.readOnly)throw new FlowError('只读项目不能保存配置');
+        const nextConfig={...latest.config,[id]:value};
+        nextHost=await createHost({plugins:[...host.definitions.values()].map(p=>({plugin:p,root:p.root})),config:{...nextConfig,...config},services,environmentOverrides:latest.environments,runtimeEnabled:!maintenance});
+        const nextProject={...latest,config:nextConfig},temp=`${file}.${randomUUID()}.tmp`;
         await writeFile(temp,JSON.stringify(nextProject,null,2));await rename(temp,file);
-        const old=host;host=nextHost;nextHost=null;project.config=nextConfig;await old.close();
+        const old=host;host=nextHost;nextHost=null;
+        for(const key of Object.keys(project))delete project[key];Object.assign(project,nextProject);
+        await old.close();
+        });
       }finally{try{if(nextHost)await nextHost.close();}finally{busy=false;}}
     },
     async setMaintenance(enabled){
@@ -167,17 +182,22 @@ export async function createApplication({projectDir=process.cwd(),workspace,outp
         const errors=[];
         try{await resources.close();}catch(error){errors.push(error);}
         try{await host.close();}catch(error){errors.push(error);}
+        try{await releaseInstallation();}catch(error){errors.push(error);}
         if(errors.length)throw new AggregateError(errors,`应用关闭失败：${errors.map(e=>e.message).join('；')}`);
       });return closing;
     },
   };
-  const initial=plugins??await Promise.all((project.plugins??[]).map(spec=>loadPlugin(spec,project.baseBundle?.root??projectDir)));
+  let initial;
   const services={application:app,runProcess};
   const build=extra=>createHost({plugins:[...initial,...extra],config:{...project.config,...config},services,environmentOverrides:project.environments,runtimeEnabled:!maintenance});
-  const external=[];
-  for(const name of Object.keys(state.dependencies??{}))external.push(await loadPlugin(name,state.root));
-  host=await build(external);
-  for(const name of ['startRun','startCommand','startWeb','saveWorkflow','removeWorkflow','installPlugin','removePlugin','configurePlugin','configureLogs','setMaintenance','pack']){
+  try{
+    initial=plugins??await Promise.all((project.plugins??[]).map(spec=>loadPlugin(spec,project.baseBundle?.root??projectDir)));
+    const external=[];
+    for(const name of Object.keys(state.dependencies??{}))if(!maintenance||name!==omitInstalledPlugin)external.push(await loadPlugin(name,state.root));
+    for(const [name,source] of Object.entries(state.links??{}))if(!maintenance||name!==omitInstalledPlugin)external.push(await loadPlugin(source,projectDir));
+    host=await build(external);
+  }catch(error){await releaseInstallation();throw error;}
+  for(const name of ['startRun','startCommand','startWeb','saveWorkflow','removeWorkflow','installPlugin','linkPlugin','removePlugin','configurePlugin','configureLogs','setMaintenance','pack']){
     const original=app[name],isRun=['startRun','startCommand'].includes(name);
     app[name]=async(...args)=>{
       if(closing)throw new FlowError('应用已关闭');
@@ -193,19 +213,23 @@ export async function createApplication({projectDir=process.cwd(),workspace,outp
     if(project.readOnly)throw new FlowError('运行包不支持安装或移除插件');
     assertMutable();
     if(busy || launching || [...runs.values()].some(r=>r.status==='running'))throw new FlowError('请等待当前运行或安装结束');
-    busy=true;let nextHost;
+    busy=true;let nextHost,nextRelease;
     try {
+      return await withPluginMutation(projectDir,async()=>{
+      await assertPluginState(projectDir,state);
       const next=await installGeneration(projectDir,{...operation,state});
       for(const p of host.definitions.values())if(resources.active(p.id)){
         const candidate=[...initial,...next.loaded].find(e=>(e.plugin??e).id===p.id);
         if(!candidate||candidate.root!==p.root||(candidate.plugin??candidate).version!==p.version)throw new FlowError('请先停止活动 Web，再替换其提供者');
       }
       nextHost=await build(next.loaded);
-      const file=path.join(projectDir,'.flow','plugins.json'),temp=`${file}.tmp`;
-      await writeFile(temp,JSON.stringify(next.state,null,2));await rename(temp,file);
-      const old=host;host=nextHost;nextHost=null;state=next.state;await old.close();
+      nextRelease=await leaseInstallation(projectDir,next.state.root);
+      await savePluginState(projectDir,next.state,state);
+      const old=host,oldRelease=releaseInstallation;host=nextHost;nextHost=null;state=next.state;releaseInstallation=nextRelease;nextRelease=null;
+      try{await old.close();}finally{await oldRelease();}
       return app.listPlugins();
-    } finally {try{if(nextHost)await nextHost.close();}finally{busy=false;}}
+      });
+    } finally {try{if(nextHost)await nextHost.close();}finally{try{if(nextRelease)await nextRelease();}finally{busy=false;}}}
   }
   return app;
 }

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

@@ -1,5 +1,8 @@
 import {FlowError} from '@mytools/sdk';
 import {conditionOperators} from './control.js';
+import {resolveSchemaPath} from './schema-path.js';
+import {inside} from './environments.js';
+import path from 'node:path';
 
 export const builtinCommands=[
   ['workflows','选择已有工作流'],['new','新建工作流'],['add','添加插件能力或子工作流'],
@@ -10,23 +13,38 @@ export const builtinCommands=[
 
 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'});
-      let schema=action.output;
-      for(const part of preset.path.split('.')){
-        if(schema?.properties&&Object.hasOwn(schema.properties,part))schema=schema.properties[part];
-        else if(schema?.type==='array'&&/^\d+$/.test(part))schema=schema.items;
-        else throw new FlowError(`判定预设 ${key} 引用了未声明的输出字段 ${preset.path}`,{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].every(x=>typeof x==='string'&&x)))throw new FlowError(`${plugin.id} 的 ${key} 必须是字符串数组`);
-  for(const declarations of [plugin.environments,...Object.values(plugin.actions??{}).map(a=>a.environments)]){
+  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'});
+  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} 的程序路径必须是包内相对路径`);}
+        }
+      }
     }
   }
 }

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';
 
@@ -27,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);
@@ -80,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));},
@@ -92,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)); },
@@ -105,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) {