@yanglaofish/fishtools 0.3.0 → 0.5.0

package/node_modules/@mytools/fst-workspace/src/bundle-workspace.js

@@ -0,0 +1,39 @@
+import path from 'node:path';
+import os from 'node:os';
+import {mkdir,readFile,readdir,writeFile,copyFile,rename,rmdir} from 'node:fs/promises';
+import {constants} from 'node:fs';
+import {randomUUID} from 'node:crypto';
+import {setTimeout} from 'node:timers/promises';
+import {FlowError} from '@mytools/sdk';
+import {readJson} from '@mytools/fst-platform/json';
+
+export async function prepareBundleWorkspace(bundleRoot,requested){
+  bundleRoot=path.resolve(bundleRoot);
+  const bundle=await readJson(path.join(bundleRoot,'bundle.json'),null);
+  if(!bundle?.editable)return bundleRoot;
+  if(!/^[\w-]+$/.test(bundle.id))throw new FlowError('运行包 ID 无效');
+  const workspace=path.resolve(requested??process.env.FISHTOOLS_WORKSPACE??path.join(process.env.FISHTOOLS_HOME??path.join(os.homedir(),'.fishtools'),'workspaces',bundle.id));
+  if(workspace===bundleRoot||workspace.startsWith(bundleRoot+path.sep))throw new FlowError('可写工作区必须位于分发包目录之外');
+  await mkdir(workspace,{recursive:true});
+  const lock=path.join(workspace,'.fst-init-lock');let locked=false;
+  for(let attempt=0;attempt<100;attempt++){
+    try{await mkdir(lock);locked=true;break;}catch(e){if(e.code!=='EEXIST')throw e;await setTimeout(100);}
+  }
+  if(!locked)throw new FlowError('工作区正在初始化，请稍后重试；若进程意外终止，请检查 .fst-init-lock');
+  try{
+    const file=path.join(workspace,'flow.project.json');
+    let project=await readJson(file,null);
+    if(project&&project.baseBundle?.id!==bundle.id)throw new FlowError('指定工作区已属于其他项目或分发包');
+    if(!project){
+      project=JSON.parse(await readFile(path.join(bundleRoot,'flow.project.json'),'utf8'));
+      await mkdir(path.join(workspace,'workflows'),{recursive:true});
+      for(const name of await readdir(path.join(bundleRoot,'workflows'))){
+        if(!name.endsWith('.yaml'))continue;
+        try{await copyFile(path.join(bundleRoot,'workflows',name),path.join(workspace,'workflows',name),constants.COPYFILE_EXCL);}catch(e){if(e.code!=='EEXIST')throw e;}
+      }
+    }
+    project.readOnly=false;project.baseBundle={id:bundle.id,root:bundleRoot};
+    const temp=`${file}.${randomUUID()}.tmp`;await writeFile(temp,JSON.stringify(project,null,2));await rename(temp,file);
+    return workspace;
+  }finally{await rmdir(lock);}
+}

package/node_modules/@mytools/fst-workspace/src/index.js

@@ -0,0 +1,3 @@
+export {WorkflowStore} from './workflows.js';
+export {initializeProject,resolveProject} from './project.js';
+export {prepareBundleWorkspace} from './bundle-workspace.js';

package/node_modules/@mytools/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/node_modules/@mytools/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/fst-workspace/src/project.js

@@ -0,0 +1,29 @@
+import { mkdir, copyFile, writeFile, access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import {prepareBundleWorkspace} from './bundle-workspace.js';
+
+const templates=fileURLToPath(new URL('../templates/',import.meta.url));
+async function exists(file){try{await access(file);return true;}catch(error){if(error.code==='ENOENT')return false;throw error;}}
+
+export async function initializeProject(directory){
+  directory=path.resolve(directory);
+  if(await exists(path.join(directory,'flow.project.json')))return directory;
+  await mkdir(path.join(directory,'workflows'),{recursive:true});
+  for(const name of ['hello','system-check','python-check','control-demo']){
+    try{await copyFile(path.join(templates,`${name}.yaml`),path.join(directory,'workflows',`${name}.yaml`),constants.COPYFILE_EXCL);}
+    catch(error){if(error.code!=='EEXIST')throw error;}
+  }
+  // npm 全局安装目录只保存程序，用户数据始终写入独立项目。
+  try{await writeFile(path.join(directory,'flow.project.json'),JSON.stringify({plugins:['@mytools/environment','@mytools/examples','@mytools/web'],config:{}},null,2),{flag:'wx'});}
+  catch(error){if(error.code!=='EEXIST')throw error;}
+  return directory;
+}
+
+export async function resolveProject(explicit,workspace){
+  if(explicit)return prepareBundleWorkspace(path.resolve(explicit),workspace);
+  if(await exists(path.join(process.cwd(),'flow.project.json')))return prepareBundleWorkspace(process.cwd(),workspace);
+  return initializeProject(process.env.FISHTOOLS_HOME??path.join(os.homedir(),'.fishtools'));
+}

package/node_modules/@mytools/fst-workspace/src/workflows.js

@@ -0,0 +1,150 @@
+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 '@mytools/sdk/schema';
+import {resolveSchemaPath} from '@mytools/sdk/schema-path';
+import {validateCondition,validateStepList} from '@mytools/fst-workflow/control';
+
+export class WorkflowStore {
+  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);
+    const physical=await realpath(file);
+    const root=await realpath(this.root);
+    if (!physical.startsWith(root+path.sep)) throw new FlowError('工作流越界，必须位于工作流目录内',{code:'VALIDATION'});
+    const definition=YAML.parse(await readFile(file,'utf8'));
+    if (definition?.id !== id) throw new FlowError(`工作流 ID 与文件名不一致：${id}`,{code:'VALIDATION'});
+    return this.validateShape(definition);
+  }
+  validateShape(w) {
+    assertId(w?.id);
+    if (w.schemaVersion!==1 || !Array.isArray(w.steps)) throw new FlowError('工作流格式错误：需要 schemaVersion: 1 与 steps 列表',{code:'VALIDATION'});
+    validateStepList(w.steps,assertId);
+    return structuredClone(w);
+  }
+  async save(definition) {
+    const w=this.validateShape(definition);
+    await mkdir(this.root,{recursive:true});
+    const file=this.file(w.id), temporary=`${file}.${randomUUID()}.tmp`;
+    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);
+    return Promise.all(files.filter(f=>f.endsWith('.yaml')).sort().map(f=>this.get(f.slice(0,-5))));
+  }
+  async remove(id){
+    await this.get(id);
+    const refers=steps=>steps.some(step=>step.workflow&&this.childId(step.workflow)===id||step.branch&&(refers(step.branch.then)||refers(step.branch.else??[]))||step.parallel&&refers(step.parallel.steps));
+    const dependents=(await this.list()).filter(flow=>flow.id!==id&&refers(flow.steps));
+    if(dependents.length)throw new FlowError(`工作流仍被引用：${dependents.map(flow=>flow.title??flow.id).join('、')}`);
+    const directory=path.join(path.dirname(this.root),'.flow','deleted-workflows');
+    await mkdir(directory,{recursive:true});
+    const backup=path.join(directory,`${id}-${randomUUID()}.yaml`);
+    // 同项目内原子移动，备份保留完整原文；复制回原文件名即可恢复。
+    await rename(this.file(id),backup);return backup;
+  }
+  childId(reference) {
+    if(typeof reference!=='string' || !/^(\.\/)?[A-Za-z0-9][A-Za-z0-9_-]*\.yaml$/.test(reference)) throw new FlowError(`子流程必须位于工作流目录内：${reference}`,{code:'VALIDATION'});
+    return reference.replace(/^\.\//,'').slice(0,-5);
+  }
+  async resolve(entries,host) {
+    const workflows=new Map(), outputs=new Map(), plugins=new Set(), visiting=new Set();
+    const visit=async id=>{
+      if(visiting.has(id)) throw new FlowError(`工作流循环引用：${[...visiting,id].join(' → ')}`,{code:'VALIDATION'});
+      if(workflows.has(id)) return;
+      visiting.add(id);
+      const w=await this.get(id);
+      const checker=previous=>ref=>{
+        const p=referenceParts(ref);
+        if(p[0]==='steps' && !previous.has(p[1])) throw new FlowError(`${id} 引用必须指向前序步骤：${ref}`,{code:'VALIDATION'});
+        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={};
+        for(const s of steps){
+          const check=checker(parallel?inherited:previous);
+          if(s.when)validateCondition(s.when,check);
+          let output;
+          if(s.action){
+            references(s.with??{},check);
+            const action=host.actions.get(s.action);
+            if(!action)throw new FlowError(`${id} → ${s.id} 缺少插件动作 ${s.action}`,{code:'VALIDATION'});
+            if(action.input===undefined||action.output===undefined)throw new FlowError(`可编排动作 ${s.action} 必须声明 input 和 output schema`,{code:'VALIDATION'});
+            assertSchema(action.input,`${s.action} input schema`);assertSchema(action.output,`${s.action} output schema`);
+            plugins.add(action.plugin);output=action.output;
+          }else if(s.workflow){references(s.with??{},check);const child=this.childId(s.workflow);await visit(child);output=outputs.get(child);}
+          else if(s.branch){
+            validateCondition(s.branch.condition,check);
+            const left=await resolveList(s.branch.then,parallel?inherited:previous),right=await resolveList(s.branch.else??[],parallel?inherited:previous);
+            output={type:'object',additionalProperties:false,properties:{...left.own,...right.own}};
+          }else if(s.parallel){const group=await resolveList(s.parallel.steps,parallel?inherited:previous,true);output={type:'object',additionalProperties:false,properties:group.own};}
+          else output=emptyObject;
+          previous.set(s.id,output);own[s.id]=output;
+        }
+        return {previous,own};
+      };
+      const {previous}=await resolveList(w.steps),check=checker(previous);
+      references(w.outputs??{},check);
+      const infer=value=>{
+        if(value?.$ref)return check(value.$ref);
+        if(Array.isArray(value))return {type:'array'};
+        if(value&&typeof value==='object')return {type:'object',additionalProperties:false,properties:Object.fromEntries(Object.entries(value).map(([key,v])=>[key,infer(v)]))};
+        return {type:value===null?'null':typeof value};
+      };
+      outputs.set(id,infer(w.outputs??{}));
+      workflows.set(id,w); visiting.delete(id);
+    };
+    for(const id of entries) await visit(id);
+    const resolved=new Set(), visitingPlugins=new Set();
+    const addPlugin=id=>{
+      if(visitingPlugins.has(id)) throw new FlowError(`插件循环依赖：${id}`,{code:'VALIDATION'});
+      if(resolved.has(id)) return;
+      const p=host.definitions.get(id);
+      if(!p) throw new FlowError(`插件依赖缺失：${id}`,{code:'VALIDATION'});
+      visitingPlugins.add(id);
+      Object.keys(p.dependencies??{}).forEach(addPlugin);
+      visitingPlugins.delete(id); resolved.add(id);
+    };
+    plugins.forEach(addPlugin);
+    return {workflows:[...workflows.values()],plugins:[...resolved]};
+  }
+}

package/node_modules/@mytools/fst-workspace/templates/control-demo.yaml

@@ -0,0 +1,47 @@
+schemaVersion: 1
+id: control-demo
+title: 条件与并行入门
+description: 检查系统后，根据你的选择继续或提前结束；继续时并行处理两段文本。运行中可切换步骤和查看日志。
+inputs:
+  type: object
+  properties:
+    proceed:
+      type: boolean
+      title: 继续执行文本处理
+      default: true
+  required: [proceed]
+steps:
+  - id: environment
+    action: "@mytools/environment:report"
+    with: {}
+  - id: guard
+    when:
+      left: {$ref: steps.environment.output.ok}
+      op: eq
+      right: false
+    stop:
+      reason: 环境检查未通过，已停止后续步骤。
+  - id: choose
+    branch:
+      condition:
+        left: {$ref: inputs.proceed}
+        op: eq
+        right: true
+      then:
+        - id: batch
+          parallel:
+            concurrency: 2
+            steps:
+              - id: first
+                action: "@mytools/examples:uppercase"
+                with: {text: "Hello, Fishtools!"}
+              - id: second
+                action: "@mytools/examples:uppercase"
+                with: {text: Parallel workflow}
+      else:
+        - id: finish
+          stop:
+            reason: 本次选择提前结束，没有执行文本处理。
+outputs:
+  first: {$ref: steps.choose.output.batch.first.text}
+  second: {$ref: steps.choose.output.batch.second.text}

package/node_modules/@mytools/fst-workspace/templates/hello.yaml

@@ -0,0 +1,35 @@
+schemaVersion: 1
+id: hello
+title: 我的第一个工作流
+description: 将输入文本转为大写，追加完成标记，再保存到文件。所有步骤都可在界面中调整。
+inputs:
+  type: object
+  required:
+    - text
+  properties:
+    text:
+      type: string
+      title: 输入文本
+      default: Hello, workflow!
+steps:
+  - id: uppercase
+    action: "@mytools/examples:uppercase"
+    with:
+      text:
+        $ref: inputs.text
+  - id: append
+    action: "@mytools/examples:append"
+    with:
+      text:
+        $ref: steps.uppercase.output.text
+      suffix: " ✓"
+  - id: save
+    action: "@mytools/examples:save"
+    with:
+      text:
+        $ref: steps.append.output.text
+outputs:
+  text:
+    $ref: steps.append.output.text
+  file:
+    $ref: steps.save.output.path

package/node_modules/@mytools/fst-workspace/templates/python-check.yaml

@@ -0,0 +1,26 @@
+schemaVersion: 1
+id: python-check
+title: 检查 Python 并执行脚本
+description: 检查指定的目标 Python，再用同一个解释器运行插件提供的脚本。检查失败会停止。
+inputs:
+  type: object
+  required: [executable, text]
+  properties:
+    executable: { type: string, title: 目标 Python 解释器路径 }
+    text: { type: string, title: 输入文本, default: Hello Python }
+steps:
+  - id: check
+    action: '@mytools/environment:check'
+    with:
+      python:
+        executable: { $ref: inputs.executable }
+        version: '>=3.9'
+        pip: false
+  - id: python
+    action: '@mytools/examples:pythonEcho'
+    with:
+      executable: { $ref: steps.check.output.python.executable }
+      text: { $ref: inputs.text }
+outputs:
+  text: { $ref: steps.python.output.text }
+  executable: { $ref: steps.python.output.executable }

package/node_modules/@mytools/fst-workspace/templates/system-check.yaml

@@ -0,0 +1,11 @@
+schemaVersion: 1
+id: system-check
+title: 查看系统环境
+description: 通过官方环境检查插件查看目标机器的操作系统、架构和内核，无需安装 Python。
+inputs: { type: object, properties: {} }
+steps:
+  - id: check
+    action: '@mytools/environment:check'
+    with: {}
+outputs:
+  system: { $ref: steps.check.output.system }

package/node_modules/@mytools/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/node_modules/@mytools/pack/dependencies.js

@@ -4,7 +4,7 @@ import { access, copyFile, mkdir, writeFile, realpath,stat,chmod } from 'node:fs
 import path from 'node:path';
 import { FlowError } from '@mytools/sdk';
 
-export async function collectPackages(roots) {
+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;
@@ -24,7 +24,12 @@ export async function collectPackages(roots) {
     }
     if(!trees.has(base))trees.set(base,await new Arborist({path:base}).loadActual());
     const tree=trees.get(base);
-    const found=[...tree.inventory.values()].find(n=>n.realpath===root && !n.isLink);
+    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;
   }
@@ -34,6 +39,7 @@ export async function collectPackages(roots) {
     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);
@@ -44,9 +50,12 @@ export async function collectPackages(roots) {
 }
 
 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))top.set(edge.name,edge.to.isLink?edge.to.target:edge.to);
+  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){
@@ -66,6 +75,8 @@ export async function copyPackages(nodes,destination,target,{filters=new Map()}=
     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 大小写、短路径和目录联接。
@@ -80,6 +91,7 @@ export async function copyPackages(nodes,destination,target,{filters=new Map()}=
     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]);

package/node_modules/@mytools/pack/environments.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import {realpath,readdir,stat} from 'node:fs/promises';
-import {inside,resolveEnvironments,environmentDeclarations} from '@mytools/core/environments';
+import {inside,resolveEnvironments,environmentDeclarations} from '@mytools/fst-platform/environments';
 import {FlowError} from '@mytools/sdk';
 
 // 只核对被声明的资源能否完整收集；版本和业务兼容性由作者负责。