@yanglaofish/fishtools 0.3.0 → 0.5.0

package/manual/packages/fst-workspace/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/manual/packages/fst-workspace/src/plugins.js

@@ -0,0 +1,35 @@
+import path from 'node:path';
+import {mkdir,writeFile,access} from 'node:fs/promises';
+import {randomUUID} from 'node:crypto';
+import {FlowError} from '@mytools/sdk';
+import {readJson} from '@mytools/fst-platform/json';
+import {npm} from '@mytools/fst-platform/npm';
+import {loadPlugin} from '@mytools/fst-plugin/loader';
+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??{})};
+  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'});
+  }
+  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??{})){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 → manual/packages/fst-workspace}/src/workflows.js

@@ -1,27 +1,14 @@
-import { mkdir, readFile, readdir, realpath, writeFile, rename } from 'node:fs/promises';
+import { mkdir, readFile, readdir, realpath, writeFile, rename, open, unlink } from 'node:fs/promises';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import YAML from 'yaml';
 import { FlowError } from '@mytools/sdk';
-import { assertId, assertSchema, references, referenceParts, emptyObject } from './validation.js';
-import {validateCondition,validateStepList} from './control.js';
-
-function fieldSchema(schema,fields,ref){
-  let current=schema;
-  for(const field of fields){
-    if(!current||current===true)return {};
-    if(current.properties&&Object.hasOwn(current.properties,field)){current=current.properties[field];continue;}
-    if(current.type==='array'&&/^\d+$/.test(field)){current=current.items;continue;}
-    if(current.additionalProperties===false||current===false||(current.type&&!['object','array'].includes(current.type))){
-      throw new FlowError(`引用字段不存在：${ref}`,{code:'VALIDATION'});
-    }
-    return {};
-  }
-  return current??{};
-}
+import { assertId, assertSchema, references, referenceParts, emptyObject } from '@mytools/sdk/schema';
+import {resolveSchemaPath} from '@mytools/sdk/schema-path';
+import {validateCondition,validateStepList} from '@mytools/fst-workflow/control';
 
 export class WorkflowStore {
-  constructor(root) { this.root = path.resolve(root); }
+  constructor(root,{openFile=open}={}) { this.root = path.resolve(root);this.openFile=openFile; }
   file(id) { assertId(id); return path.join(this.root,`${id}.yaml`); }
   async get(id) {
     const file=this.file(id);
@@ -42,10 +29,43 @@ export class WorkflowStore {
     const w=this.validateShape(definition);
     await mkdir(this.root,{recursive:true});
     const file=this.file(w.id), temporary=`${file}.${randomUUID()}.tmp`;
-    await writeFile(temporary,YAML.stringify(w),'utf8');
-    await rename(temporary,file);
+    let previous;
+    try{
+      const physical=await realpath(file),root=await realpath(this.root);
+      if(!physical.startsWith(root+path.sep))throw new FlowError('工作流越界，不能覆盖工作流目录之外的文件',{code:'VALIDATION'});
+      previous=await readFile(file,'utf8');
+    }catch(error){if(error.code!=='ENOENT')throw error;}
+    if(previous!==undefined){
+      const directory=path.join(path.dirname(this.root),'.flow','workflow-backups');
+      await mkdir(directory,{recursive:true,mode:0o700});
+      await writeFile(path.join(directory,`${w.id}-${randomUUID()}.yaml`),previous,{flag:'wx',mode:0o600});
+    }
+    try{await writeFile(temporary,YAML.stringify(w),'utf8');await rename(temporary,file);}
+    catch(error){try{await unlink(temporary);}catch(cleanup){if(cleanup.code!=='ENOENT')throw new AggregateError([error,cleanup],`工作流保存失败且临时文件无法清理：${temporary}`);}throw error;}
     return w;
   }
+  async duplicate(definition,{id,title}={}) {
+    const source=this.validateShape(definition);
+    const copy=this.validateShape({...source,id:id??`flow-${randomUUID()}`,title:title??`${source.title??source.id} 副本`});
+    const file=this.file(copy.id),content=YAML.stringify(copy);
+    if(typeof copy.title!=='string'||!copy.title.trim())throw new FlowError('工作流名称不能为空',{code:'VALIDATION'});
+    await mkdir(this.root,{recursive:true});
+    let handle;
+    try{
+      // 排他创建保证并发请求也不能覆盖同名工作流。
+      handle=await this.openFile(file,'wx');
+      await handle.writeFile(content,'utf8');
+      await handle.close();handle=null;
+      return {definition:copy,path:file};
+    }catch(error){
+      if(handle){
+        try{await handle.close();}catch{}
+        try{await unlink(file);}catch(cleanupError){if(cleanupError.code!=='ENOENT')throw new AggregateError([error,cleanupError],`复制失败且无法清理新文件：${file}`);}
+      }
+      if(error.code==='EEXIST')throw new FlowError(`工作流已存在：${copy.id}`,{code:'VALIDATION',cause:error});
+      throw error;
+    }
+  }
   async list() {
     await mkdir(this.root,{recursive:true});
     const files=await readdir(this.root);
@@ -76,7 +96,7 @@ export class WorkflowStore {
       const checker=previous=>ref=>{
         const p=referenceParts(ref);
         if(p[0]==='steps' && !previous.has(p[1])) throw new FlowError(`${id} 引用必须指向前序步骤：${ref}`,{code:'VALIDATION'});
-        return fieldSchema(p[0]==='inputs'?(w.inputs??emptyObject):previous.get(p[1]),p.slice(p[0]==='inputs'?1:3),ref);
+        return resolveSchemaPath(p[0]==='inputs'?(w.inputs??emptyObject):previous.get(p[1]),p.slice(p[0]==='inputs'?1:3),ref);
       };
       const resolveList=async(steps,inherited=new Map(),parallel=false)=>{
         const previous=new Map(inherited),own={};

package/manual/packages/pack/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/manual/packages/pack/README.md

@@ -0,0 +1,31 @@
+# 分发模块
+
+包名：`@mytools/pack`。内部 workspace 包，随 `@yanglaofish/fishtools` 统一交付。
+
+## 职责与边界
+
+根据声明快照规划环境、收集生产依赖、复制运行时、生成清单和归档。不读取活动宿主或工作流存储；CLI 根目录作为发行载荷路径传入。
+
+内部依赖：`@mytools/sdk`、`@mytools/fst-platform`、`@mytools/fst-devtools`。
+## 公开入口
+
+| 导入路径 | 实现位置 |
+| --- | --- |
+| `@mytools/pack` | `./index.js` |
+| `@mytools/pack/dependencies` | `./dependencies.js` |
+| `@mytools/pack/runtime` | `./runtime.js` |
+| `@mytools/pack/environments` | `./environments.js` |
+| `@mytools/pack/archive` | `./archive.js` |
+| `@mytools/pack/package.json` | `./package.json` |
+
+仅依赖 exports 声明的入口，禁止消费者跨包读取 src/bin 私有文件。入口路径由本模块维护，修改协议时同步消费方回归。
+
+## 维护与验证
+
+本模块负责上述职责的实现、文档与回归；跨模块接口调整需要同时检查生产者与消费者。具体维护人员尚未指定。
+
+在仓库根目录执行：
+
+```sh
+node --test tests/modules.test.js tests/pack.test.js tests/dependencies.test.js tests/npm-dist.test.js
+```

package/manual/packages/pack/archive.js

@@ -0,0 +1,15 @@
+import path from 'node:path';
+import {createWriteStream} from 'node:fs';
+import {ZipArchive,TarArchive} from 'archiver';
+
+export async function archiveDirectory(directory,target,executablePaths=new Set()){
+  const name=path.basename(directory),archive=`${directory}.${target==='win32-x64'?'zip':'tar.gz'}`;
+  const stream=createWriteStream(archive),zip=target==='win32-x64'?new ZipArchive({zlib:{level:6}}):new TarArchive({gzip:true,gzipOptions:{level:6}});
+  await new Promise((resolve,reject)=>{
+    stream.on('close',resolve);stream.on('error',reject);zip.on('error',reject);zip.pipe(stream);
+    // Archiver 的回调给出源相对路径，顶层归档目录由库随后添加。
+    zip.directory(directory,name,data=>/\.sh$/.test(data.name)||executablePaths.has(data.name)?{...data,mode:0o755}:data);
+    zip.finalize().catch(reject);
+  });
+  return archive;
+}

package/manual/packages/pack/dependencies.js

@@ -0,0 +1,105 @@
+import Arborist from '@npmcli/arborist';
+import packlist from 'npm-packlist';
+import { access, copyFile, mkdir, writeFile, realpath,stat,chmod } from 'node:fs/promises';
+import path from 'node:path';
+import { FlowError } from '@mytools/sdk';
+
+export async function collectPackages(roots,{omitOptionalPeers=[]}={}) {
+  const trees=new Map(), nodes=new Map();
+  async function locate(root){
+    root=await realpath(root);let base=root,installedRoot;
+    for(let current=root;current!==path.dirname(current);current=path.dirname(current)){
+      if(path.basename(current)==='node_modules'){
+        const owner=path.dirname(current);
+        try{await access(path.join(owner,'package.json'));installedRoot=owner;}catch{}
+      }
+    }
+    // 使用拥有这条 node_modules 链的最外层包，既保留提升依赖，也避开无关用户目录的锁文件。
+    if(installedRoot)base=installedRoot;
+    else{
+      while(base!==path.dirname(base)){
+        try{await access(path.join(base,'package-lock.json'));break;}catch{base=path.dirname(base);}
+      }
+      if(base===path.dirname(base))base=root;
+    }
+    if(!trees.has(base))trees.set(base,await new Arborist({path:base}).loadActual());
+    const tree=trees.get(base);
+    let found=[...tree.inventory.values()].find(n=>path.relative(n.realpath,root)==='' && !n.isLink);
+    // 开发引用可能嵌套在无关项目下，其上层 lock 不代表当前插件属于该依赖树。
+    if(!found&&base!==root){
+      if(!trees.has(root))trees.set(root,await new Arborist({path:root}).loadActual());
+      found=[...trees.get(root).inventory.values()].find(n=>path.relative(n.realpath,root)===''&&!n.isLink);
+    }
+    if(!found)throw new FlowError(`无法解析包的生产依赖：${root}`);
+    return found;
+  }
+  function visit(raw){
+    const node=raw.isLink?raw.target:raw;
+    if(nodes.has(node.realpath))return;
+    nodes.set(node.realpath,node);
+    for(const edge of node.edgesOut.values()){
+      if(edge.type==='dev')continue;
+      if(edge.type==='peerOptional'&&omitOptionalPeers.includes(edge.name))continue;
+      if(!edge.to){if(edge.optional)continue;throw new FlowError(`${node.name} 缺少依赖 ${edge.name}`);}
+      if(!edge.valid)throw new FlowError(`${node.name} 的依赖不兼容：${edge.name}`);
+      visit(edge.to);
+    }
+  }
+  for(const root of roots)visit(await locate(root));
+  return [...nodes.values()];
+}
+
+export async function copyPackages(nodes,destination,target,{filters=new Map()}={}){
+  const included=new Set(nodes.map(n=>n.realpath));
+  const top=new Map();
+  for(const n of nodes)if(!top.has(n.package.name))top.set(n.package.name,n);
+  for(const n of nodes)for(const edge of n.edgesOut.values())if(edge.type!=='dev'&&edge.to&&!top.has(edge.name)){
+    const child=edge.to.isLink?edge.to.target:edge.to;if(included.has(child.realpath))top.set(edge.name,child);
+  }
+  const copied=new Set(),summary=[];
+  const placements=new Map([...top].map(([name,node])=>[path.join(destination,'node_modules',name),node]));
+  function resolvedAt(from,name){
+    let current=from;
+    while(current.startsWith(destination+path.sep)||current===destination){
+      const placed=placements.get(path.join(current,'node_modules',name));
+      if(placed)return placed;
+      if(current===destination)break;
+      current=path.dirname(current);
+    }
+  }
+  async function copy(node,dest){
+    if(copied.has(dest))return;
+    copied.add(dest);await mkdir(dest,{recursive:true});
+    // packlist 对项目根只应用发布规则；依赖节点会额外收集依赖，所以单独读取包根。
+    const packageRoot=await realpath(node.realpath);
+    const filter=filters.get(packageRoot);
+    const files=[...new Set([...await packlist(await new Arborist({path:packageRoot}).loadActual()),...(filter?.extraFiles??[])])];
+    for(const file of files){
+      // 项目可以与开发插件共用根目录；宿主私有状态和安装批次永远不进入插件快照。
+      if(file.split(/[\\/]/)[0]==='.flow')continue;
+      if(filter&&!filter.include(file))continue;
+      const source=path.resolve(packageRoot,file),physical=await realpath(source);
+      // 两端先解析实际路径，再按系统规则比较，兼容 Windows 大小写、短路径和目录联接。
+      const relative=path.relative(packageRoot,physical);
+      if(!relative||relative==='..'||relative.startsWith(`..${path.sep}`)||path.isAbsolute(relative))throw new FlowError(`包包含外部资源链接：${node.name}/${file}`);
+      const output=path.join(dest,file);await mkdir(path.dirname(output),{recursive:true});await copyFile(source,output);
+      await chmod(output,(await stat(source)).mode);
+    }
+    summary.push({name:node.package.name,version:node.version,path:path.relative(destination,dest).split(path.sep).join('/'),license:node.package.license??'UNSPECIFIED'});
+    const nested=[];
+    // 先预留全部直接依赖的位置，再递归；兄弟依赖也会遮蔽其子包的查找路径。
+    for(const edge of node.edgesOut.values()){
+      if(edge.type==='dev'||!edge.to)continue;
+      const child=edge.to.isLink?edge.to.target:edge.to;
+      if(!included.has(child.realpath))continue;
+      if(resolvedAt(dest,edge.name)?.realpath===child.realpath)continue;
+      const childDest=path.join(dest,'node_modules',edge.name);
+      placements.set(childDest,child);nested.push([child,childDest]);
+    }
+    for(const [child,childDest] of nested)await copy(child,childDest);
+  }
+  for(const [name,node] of top)await copy(node,path.join(destination,'node_modules',name));
+  // 明确应用层安装根，让便携包在离线再次导出时可重建生产依赖树。
+  await writeFile(path.join(destination,'package.json'),JSON.stringify({name:'fishtools-bundle-app',private:true,dependencies:Object.fromEntries([...top].map(([name,node])=>[name,node.version]))},null,2));
+  return summary;
+}

package/manual/packages/pack/environments.js

@@ -0,0 +1,50 @@
+import path from 'node:path';
+import {realpath,readdir,stat} from 'node:fs/promises';
+import {inside,resolveEnvironments,environmentDeclarations} from '@mytools/fst-platform/environments';
+import {FlowError} from '@mytools/sdk';
+
+// 只核对被声明的资源能否完整收集；版本和业务兼容性由作者负责。
+export async function planEnvironments(plugins,target,overrides={}){
+  const entries=[],filters=new Map(),warnings=[],allFiles=new Map();
+  const platform=target.split('-')[0],architecture=target.split('-')[1];
+  for(const plugin of plugins){
+    if(plugin.platforms&&!plugin.platforms.includes(platform)||plugin.architectures&&!plugin.architectures.includes(architecture))warnings.push(`${plugin.id} 的作者声明未包含 ${target}，仍按所选目标打包`);
+    const root=await realpath(plugin.root),excluded=new Set(),selected=new Set(),extraFiles=new Set();
+    for(const [actionName,action] of [['',undefined],...Object.entries(plugin.actions??{})]){
+      const declarations=environmentDeclarations(plugin,action);
+      const resolved=resolveEnvironments({...plugin,root},action,overrides[plugin.id],target);
+      for(const [id,declaration] of Object.entries(declarations)){
+        const e=resolved[id];
+        for(const artifact of Object.values(declaration.artifacts??{})){
+          const directory=inside(root,artifact.directory);if(directory===root)throw new FlowError('环境资源目录不能是插件根目录');
+          excluded.add(directory);
+        }
+        let bytes=0;
+        if(e.source==='bundled'){
+          selected.add(e.root);
+          const seen=new Set();
+          const scan=async dir=>{
+            const physical=await realpath(dir),relative=path.relative(root,physical);
+            if(relative==='..'||relative.startsWith('..'+path.sep)||path.isAbsolute(relative))throw new FlowError(`环境资源越界：${dir}`);
+            const info=await stat(dir);
+            if(info.isDirectory()){
+              if(seen.has(physical))throw new FlowError(`环境目录循环：${dir}`);seen.add(physical);
+              for(const name of await readdir(dir))await scan(path.join(dir,name));
+              seen.delete(physical);
+            }
+            else if(info.isFile()){bytes+=info.size;extraFiles.add(path.relative(root,dir));allFiles.set(dir,info.size);}
+            else throw new FlowError(`环境资源不是普通文件：${dir}`);
+          };
+          await scan(e.root);
+          if(!(await stat(e.executable)).isFile())throw new FlowError(`环境入口不是文件：${e.executable}`);
+        }
+        const key=`${plugin.id}/${actionName||'*'}/${id}`;
+        entries.push({key,plugin:plugin.id,action:actionName||undefined,id,source:e.source,version:e.version,packages:e.packages,allowedSources:declaration.allowedSources??[declaration.source],bytes,executable:e.source==='bundled'?path.relative(root,e.executable).split(path.sep).join('/'):e.executable});
+      }
+    }
+    const within=(file,dir)=>file===dir||file.startsWith(dir+path.sep);
+    filters.set(root,{extraFiles:[...extraFiles],include:file=>{const full=path.resolve(root,file);return [...selected].some(dir=>within(full,dir))||![...excluded].some(dir=>within(full,dir));}});
+  }
+  for(const [plugin,values] of Object.entries(overrides))for(const id of Object.keys(values))if(!entries.some(e=>e.plugin===plugin&&e.id===id))throw new FlowError(`环境覆盖未匹配声明：${plugin}/${id}`);
+  return {entries,filters,warnings,bytes:[...allFiles.values()].reduce((sum,bytes)=>sum+bytes,0)};
+}

package/manual/packages/pack/index.js

@@ -0,0 +1,103 @@
+import { mkdir, writeFile, readFile, readdir, chmod,cp } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { collectPackages, copyPackages } from './dependencies.js';
+import { copyRuntime, digest } from './runtime.js';
+import { FlowError } from '@mytools/sdk';
+import YAML from 'yaml';
+import { verifyBundle } from '@mytools/fst-platform/bundle';
+import {planEnvironments} from './environments.js';
+import {archiveDirectory} from './archive.js';
+import {copyDocumentation} from '@mytools/fst-devtools/documentation';
+export {verifyBundle};
+
+async function hashes(root,dir=root,result={}){
+  for(const entry of await readdir(dir,{withFileTypes:true})){
+    const file=path.join(dir,entry.name);
+    if(entry.isDirectory())await hashes(root,file,result);
+    else if(entry.isFile())result[path.relative(root,file).split(path.sep).join('/')]=digest(await readFile(file));
+    else throw new FlowError(`分发目录包含未处理链接：${file}`);
+  }
+  return result;
+}
+function declaredPrivileges(closure,plugins){
+  const used=new Set();
+  const scan=steps=>{for(const step of steps??[]){
+    if(step.action)used.add(step.action);
+    if(step.branch){scan(step.branch.then);scan(step.branch.else);}
+    if(step.parallel)scan(step.parallel.steps);
+  }};
+  for(const workflow of closure.workflows)scan(workflow.steps);
+  const report=[];
+  for(const plugin of plugins){
+    if(plugin.requirements?.privilege)report.push({plugin:plugin.id,scope:'plugin',privilege:plugin.requirements.privilege});
+    for(const [name,action] of Object.entries(plugin.actions??{}))if(used.has(`${plugin.id}:${name}`)&&action.requirements?.privilege)report.push({plugin:plugin.id,action:name,scope:'action',privilege:action.requirements.privilege});
+  }
+  return report;
+}
+async function prepare(source,{entries,target,includeWeb=false,portable=false,environments={}}){
+  // 兼容既有 packApplication(app) 调用，但只使用明确的快照 Interface。
+  const snapshot=typeof source.exportSnapshot==='function'?await source.exportSnapshot({entries,includeWeb,portable}):source;
+  const {closure,plugins}=snapshot;entries=snapshot.entries;
+  if(!portable&&!entries?.length)throw new FlowError('请至少选择一个工作流');
+  if(!['win32-x64','linux-x64-glibc'].includes(target))throw new FlowError('请选择支持的目标平台');
+  const ids=new Set(plugins.map(p=>p.id));
+  if(plugins.some(p=>!p.root))throw new FlowError('内存中临时定义的插件不能打包，请先安装为标准包');
+  const overrides=structuredClone(snapshot.project.environments??{});
+  for(const [id,value] of Object.entries(environments))overrides[id]={...overrides[id],...value};
+  // 未选中的插件配置不进入导出，但显式拼错的覆盖项应报错。
+  for(const id of Object.keys(overrides))if(!ids.has(id)&&!Object.hasOwn(environments,id))delete overrides[id];
+  const environmentPlan=await planEnvironments(plugins,target,overrides);
+  return {closure,plugins,environmentPlan,overrides,entries,snapshot};
+}
+export async function planApplication(app,options={}){
+  const {plugins,closure,environmentPlan,entries,snapshot}=await prepare(app,options);
+  return {target:options.target,entries,plugins:plugins.map(p=>({id:p.id,platforms:p.platforms,architectures:p.architectures})),network:snapshot.project.network,privileges:declaredPrivileges(closure,plugins),environments:environmentPlan.entries,environmentBytes:environmentPlan.bytes,warnings:environmentPlan.warnings};
+}
+export async function packApplication(app,{entries,target,outDir='dist',includeWeb=false,runtimePath,cacheDir=path.resolve('.cache','runtimes'),readOnly=false,portable=false,environments={}}={}){
+  const prepared=await prepare(app,{entries,target,includeWeb,portable,environments});
+  const {closure,plugins,environmentPlan,overrides,snapshot}=prepared;entries=prepared.entries;
+  const nodes=await collectPackages([snapshot.toolRoot,...plugins.map(p=>p.root)],{omitOptionalPeers:readOnly?['@mytools/pack']:[]});
+  const name=`fishtools-${target}-${Date.now()}-${randomUUID().slice(0,6)}`;
+  const directory=path.resolve(outDir,name);await mkdir(directory,{recursive:true});
+  const packages=await copyPackages(nodes,path.join(directory,'app'),target,{filters:environmentPlan.filters});
+  let runtime;
+  const base=snapshot.project.baseBundle?.root;
+  if(base){
+    const previous=JSON.parse(await readFile(path.join(base,'manifest.json'),'utf8'));
+    if(previous.target===target&&(readOnly||previous.runtime.npm)){
+      if(!(await verifyBundle(base)).ok)throw new FlowError('原分发包完整性校验失败，不能复用运行时');
+      await cp(path.join(base,'runtime'),path.join(directory,'runtime'),{recursive:true,dereference:true});
+      await cp(path.join(base,'licenses'),path.join(directory,'licenses'),{recursive:true});runtime=previous.runtime;
+    }
+  }
+  runtime??=await copyRuntime({target,directory,cacheDir,runtimePath,includeNpm:!readOnly});
+  runtime={...runtime,npm:!readOnly||!!runtime.npm};
+  const workflowDir=path.join(directory,'workflows');await mkdir(workflowDir,{recursive:true});
+  // 保存来源文件，保持子流程相对引用；不打包未选中的流程。
+  for(const w of closure.workflows)await writeFile(path.join(workflowDir,`${w.id}.yaml`),YAML.stringify(w));
+  const config={};
+  for(const p of plugins)if(p.defaultConfig)config[p.id]=p.defaultConfig;
+  await writeFile(path.join(directory,'flow.project.json'),JSON.stringify({readOnly,plugins:plugins.map(p=>`./app/node_modules/${p.id}`),config,entries,environments:overrides,network:snapshot.project.network,logs:snapshot.project.logs},null,2));
+  const bundleId=randomUUID();
+  await writeFile(path.join(directory,'bundle.json'),JSON.stringify({format:2,id:bundleId,editable:!readOnly}));
+  await writeFile(path.join(directory,'package.json'),JSON.stringify({private:true,type:'module'},null,2));
+  const launch=target==='win32-x64'
+    ? '@echo off\r\n"%~dp0runtime\\node.exe" "%~dp0app\\node_modules\\@mytools\\fst-cli\\bin\\fst.js" --project "%~dp0." %*\r\n'
+    : '#!/bin/sh\nROOT=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)\nexec "$ROOT/runtime/node" "$ROOT/app/node_modules/@mytools/fst-cli/bin/fst.js" --project "$ROOT" "$@"\n';
+  const launcher=path.join(directory,target==='win32-x64'?'run.cmd':'run.sh');await writeFile(launcher,launch);await chmod(launcher,0o755);
+  const fst=path.join(directory,target==='win32-x64'?'fst.cmd':'fst');await writeFile(fst,launch);await chmod(fst,0o755);
+  await mkdir(path.join(directory,'bin'),{recursive:true});
+  const binLaunch=target==='win32-x64'?'@echo off\r\ncall "%~dp0..\\fst.cmd" %*\r\n':'#!/bin/sh\nexec "$(dirname -- "$0")/../fst" "$@"\n';
+  await writeFile(path.join(directory,'bin',target==='win32-x64'?'fst.cmd':'fst'),binLaunch);
+  if(includeWeb){const web=target==='win32-x64'?'@echo off\r\ncall "%~dp0run.cmd" web %*\r\n':'#!/bin/sh\nexec "$(dirname -- "$0")/run.sh" web "$@"\n';const f=path.join(directory,target==='win32-x64'?'web.cmd':'web.sh');await writeFile(f,web);await chmod(f,0o755);}
+  const executablePaths=new Set(['runtime/node','fst','bin/fst']);
+  for(const e of environmentPlan.entries.filter(e=>e.source==='bundled'))for(const p of packages.filter(p=>p.name===e.plugin)){
+    const file=['app',p.path,e.executable].join('/');executablePaths.add(file);await chmod(path.join(directory,file),0o755);
+  }
+  await copyDocumentation(path.join(directory,'manual'));
+  const manifest={format:2,bundleId,editable:!readOnly,createdAt:new Date().toISOString(),target,runtime,entries,workflows:closure.workflows.map(w=>w.id),plugins:plugins.map(p=>({id:p.id,version:p.version,platforms:p.platforms,architectures:p.architectures})),network:snapshot.project.network,privileges:declaredPrivileges(closure,plugins),environments:environmentPlan.entries,warnings:environmentPlan.warnings,packages,files:await hashes(directory)};
+  await writeFile(path.join(directory,'manifest.json'),JSON.stringify(manifest,null,2));
+  const archive=await archiveDirectory(directory,target,executablePaths);
+  return {directory,archive,manifest};
+}

package/manual/packages/pack/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@mytools/pack",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "index.js",
+  "files": [
+    "*.js"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@mytools/sdk": "0.1.0",
+    "@npmcli/arborist": "10.0.3",
+    "archiver": "8.0.0",
+    "make-fetch-happen": "16.0.1",
+    "npm-packlist": "11.3.0",
+    "tar": "7.5.22",
+    "yaml": "2.9.1",
+    "@mytools/fst-platform": "0.1.0",
+    "@mytools/fst-devtools": "0.1.0"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./dependencies": "./dependencies.js",
+    "./runtime": "./runtime.js",
+    "./environments": "./environments.js",
+    "./archive": "./archive.js",
+    "./package.json": "./package.json"
+  }
+}

package/manual/packages/pack/runtime.js

@@ -0,0 +1,61 @@
+import { mkdir, readFile, writeFile, copyFile, chmod,cp } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import * as tar from 'tar';
+import fetch from 'make-fetch-happen';
+import { FlowError } from '@mytools/sdk';
+
+export const NODE_VERSION='24.15.0';
+const hashes={
+  'win32-x64':'3331e1ffe19874215472217c5e94f5a0c6d8e18c4ac7111d3937aa0ad5e9b4a5',
+  'linux-x64-glibc':'44836872d9aec49f1e6b52a9a922872db9a2b02d235a616a5681b6a85fec8d89',
+};
+export const digest=data=>createHash('sha256').update(data).digest('hex');
+async function download(url){const response=await fetch(url,{timeout:120000,retry:{retries:2}});if(!response.ok)throw new FlowError(`下载失败 ${response.status}：${url}`);return Buffer.from(await response.arrayBuffer());}
+
+export async function copyRuntime({target,directory,cacheDir,runtimePath,includeNpm=false}){
+  if(!hashes[target])throw new FlowError(`尚不支持目标：${target}`);
+  await mkdir(path.join(directory,'runtime'),{recursive:true});
+  await mkdir(cacheDir,{recursive:true});
+  const win=target==='win32-x64';
+  const file=win?'win-x64/node.exe':`node-v${NODE_VERSION}-linux-x64.tar.gz`;
+  const cache=path.join(cacheDir,file.replaceAll('/','-'));
+  let bytes;
+  if(runtimePath){
+    if(!win)throw new FlowError('自定义 runtimePath 首版只接受已验证的 Windows Node.js 文件');
+    bytes=await readFile(runtimePath);
+  }else{
+    try{bytes=await readFile(cache);}catch{
+      bytes=await download(`https://nodejs.org/download/release/v${NODE_VERSION}/${file}`);
+    }
+  }
+  if(digest(bytes)!==hashes[target])throw new FlowError('Node.js 运行时校验失败，请检查缓存或指定文件');
+  await writeFile(cache,bytes);
+  if(win)await writeFile(path.join(directory,'runtime','node.exe'),bytes);
+  else{
+    const extraction=path.join(cacheDir,'linux-extracted');await mkdir(extraction,{recursive:true});
+    await tar.x({file:cache,cwd:extraction,filter:name=>name.endsWith('/bin/node')||name.endsWith('/LICENSE')});
+    await copyFile(path.join(extraction,`node-v${NODE_VERSION}-linux-x64/bin/node`),path.join(directory,'runtime','node'));
+    await chmod(path.join(directory,'runtime','node'),0o755);
+  }
+  const licenseCache=path.join(cacheDir,'NODE_LICENSE');
+  let license;
+  try{license=await readFile(licenseCache);}catch{
+    try{if(process.versions.node!==NODE_VERSION)throw new Error('版本不同');license=await readFile(path.join(path.dirname(process.execPath),'LICENSE'));}
+    catch{license=await download(`https://raw.githubusercontent.com/nodejs/node/v${NODE_VERSION}/LICENSE`);}
+    await writeFile(licenseCache,license);
+  }
+  await mkdir(path.join(directory,'licenses'),{recursive:true});await writeFile(path.join(directory,'licenses','NODE_LICENSE'),license);
+  if(includeNpm){
+    // npm 是平台无关的 JS，直接复用已固定校验的官方 Linux 分发中的完整 npm 目录。
+    const npmArchive=path.join(cacheDir,`node-v${NODE_VERSION}-linux-x64.tar.gz`);
+    let npmBytes;
+    try{npmBytes=await readFile(npmArchive);}catch{npmBytes=await download(`https://nodejs.org/download/release/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.gz`);}
+    if(digest(npmBytes)!==hashes['linux-x64-glibc'])throw new FlowError('npm 来源的 Node.js 归档校验失败');
+    await writeFile(npmArchive,npmBytes);
+    const extraction=path.join(cacheDir,'npm-extracted');await mkdir(extraction,{recursive:true});
+    await tar.x({file:npmArchive,cwd:extraction,filter:name=>name.includes('/lib/node_modules/npm/')});
+    await cp(path.join(extraction,`node-v${NODE_VERSION}-linux-x64/lib/node_modules/npm`),path.join(directory,'runtime/node_modules/npm'),{recursive:true,dereference:true});
+  }
+  return {version:NODE_VERSION,source:`https://nodejs.org/download/release/v${NODE_VERSION}/${file}`,sha256:hashes[target]};
+}