@yanglaofish/fishtools 0.4.0 → 0.5.1

package/node_modules/@mytools/fst-workflow/src/control.js

@@ -0,0 +1,64 @@
+import {isDeepStrictEqual} from 'node:util';
+import {FlowError} from '@mytools/sdk';
+import {bind,references} from '@mytools/sdk/schema';
+
+import {conditionOperators} from '@mytools/sdk/conditions';
+export {conditionOperators};
+const invalid=message=>{throw new FlowError(message,{code:'VALIDATION'});};
+export function validateCondition(condition,visit=()=>{},depth=0){
+  if(depth>32||!condition||typeof condition!=='object'||Array.isArray(condition))invalid('条件必须是有限深度的结构化对象');
+  const groups=['all','any','not'].filter(key=>Object.hasOwn(condition,key));
+  if(groups.length){
+    if(groups.length!==1||Object.keys(condition).length!==1)invalid('组合条件只能包含 all、any 或 not 中的一种');
+    const key=groups[0],children=key==='not'?[condition.not]:condition[key];
+    if(!Array.isArray(children)||!children.length)invalid('组合条件不能为空');
+    children.forEach(child=>validateCondition(child,visit,depth+1));return;
+  }
+  if(!conditionOperators.includes(condition.op)||!Object.hasOwn(condition,'left')||(condition.op!=='exists'&&!Object.hasOwn(condition,'right'))||Object.keys(condition).some(k=>!['left','op','right'].includes(k)))invalid('条件比较格式错误');
+  references(condition.left,visit);if(condition.op!=='exists')references(condition.right,visit);
+}
+
+export function evaluateCondition(condition,state){
+  if(condition.all)return condition.all.every(c=>evaluateCondition(c,state));
+  if(condition.any)return condition.any.some(c=>evaluateCondition(c,state));
+  if(condition.not)return !evaluateCondition(condition.not,state);
+  let left,right;
+  try{left=bind(condition.left,state);if(condition.op!=='exists')right=bind(condition.right,state);}
+  catch(error){if(error.code==='MISSING_REFERENCE')return false;throw error;}
+  switch(condition.op){
+    case 'exists':return left!==undefined;
+    case 'eq':return isDeepStrictEqual(left,right);
+    case 'ne':return !isDeepStrictEqual(left,right);
+    case 'contains':return typeof left==='string'&&typeof right==='string'?left.includes(right):Array.isArray(left)&&left.some(v=>isDeepStrictEqual(v,right));
+    default:
+      if(typeof left!=='number'||typeof right!=='number'||!Number.isFinite(left)||!Number.isFinite(right))return false;
+      return {gt:()=>left>right,gte:()=>left>=right,lt:()=>left<right,lte:()=>left<=right}[condition.op]();
+  }
+}
+
+export function childLists(step){
+  if(step.branch)return [step.branch.then??[],step.branch.else??[]];
+  if(step.parallel)return [step.parallel.steps];
+  return [];
+}
+
+export function validateStepList(steps,assertId,ids=new Set(),depth=0){
+  if(depth>32||!Array.isArray(steps))invalid('步骤列表必须是数组，嵌套深度不得超过 32');
+  for(const step of steps){
+    assertId(step?.id);if(ids.has(step.id))invalid(`步骤 ID 重复：${step.id}`);ids.add(step.id);
+    if(['constructor','prototype'].includes(step.id))invalid(`步骤 ID 不能使用保留名称：${step.id}`);
+    const kinds=['action','workflow','branch','parallel','stop'].filter(k=>Object.hasOwn(step,k));
+    if(kinds.length!==1)invalid(`${step.id} 必须选择一个动作、子工作流或控制节点`);
+    if(step.when!==undefined)validateCondition(step.when);
+    if(kinds[0]==='action'||kinds[0]==='workflow'){
+      if(typeof step[kinds[0]]!=='string'||!step[kinds[0]])invalid(`${step.id} 的目标必须为字符串`);
+    }else{
+      const value=step[kinds[0]];
+      if(!value||typeof value!=='object'||Array.isArray(value))invalid(`${step.id} 控制节点格式错误`);
+      if(step.branch){validateCondition(value.condition);if(!Array.isArray(value.then)||value.else!==undefined&&!Array.isArray(value.else))invalid('分支需要 then/else 步骤数组');}
+      if(step.parallel){const n=value.concurrency??4;if(!Number.isInteger(n)||n<1||n>32)invalid('并发数必须是 1 到 32 的整数');}
+      if(step.stop&&(typeof value.reason!=='string'||!value.reason.trim()))invalid('提前结束必须填写原因');
+    }
+    for(const list of childLists(step))validateStepList(list,assertId,ids,depth+1);
+  }
+}

package/node_modules/@mytools/{core → fst-workflow}/src/engine.js

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { FlowError } from '@mytools/sdk';
-import { bind, validate, emptyObject } from './validation.js';
-import {errorRecord} from './diagnostics.js';
+import { bind, validate, emptyObject } from '@mytools/sdk/schema';
+import {errorRecord} from '@mytools/sdk/diagnostics';
 import {evaluateCondition,childLists} from './control.js';
 
 export async function runWorkflow({store,host,id,input={},signal,onEvent=()=>{},runId=randomUUID(),context={}}) {

package/node_modules/@mytools/fst-workspace/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mytools contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/@mytools/fst-workspace/README.md

@@ -0,0 +1,32 @@
+# 工作区模块
+
+包名：`@mytools/fst-workspace`。内部 workspace 包，随 `@yanglaofish/fishtools` 统一交付。
+
+## 职责与边界
+
+项目初始化、模板、工作流文件、插件安装批次、租约、开发引用及便携工作区。插件执行由 plugin 负责，系统调用由 platform 负责。
+
+内部依赖：`@mytools/sdk`、`@mytools/fst-platform`、`@mytools/fst-plugin`、`@mytools/fst-workflow`。
+## 公开入口
+
+| 导入路径 | 实现位置 |
+| --- | --- |
+| `@mytools/fst-workspace` | `./src/index.js` |
+| `@mytools/fst-workspace/workflows` | `./src/workflows.js` |
+| `@mytools/fst-workspace/project` | `./src/project.js` |
+| `@mytools/fst-workspace/plugins` | `./src/plugins.js` |
+| `@mytools/fst-workspace/installations` | `./src/plugin-installations.js` |
+| `@mytools/fst-workspace/bundles` | `./src/bundle-workspace.js` |
+| `@mytools/fst-workspace/package.json` | `./package.json` |
+
+仅依赖 exports 声明的入口，禁止消费者跨包读取 src/bin 私有文件。入口路径由本模块维护，修改协议时同步消费方回归。
+
+## 维护与验证
+
+本模块负责上述职责的实现、文档与回归；跨模块接口调整需要同时检查生产者与消费者。具体维护人员尚未指定。
+
+在仓库根目录执行：
+
+```sh
+node --test tests/modules.test.js tests/bundle-workspace.test.js tests/plugin-development-cycle.test.js tests/project-config-concurrency.test.js
+```

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

@@ -0,0 +1,34 @@
+{
+  "name": "@mytools/fst-workspace",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./workflows": "./src/workflows.js",
+    "./project": "./src/project.js",
+    "./plugins": "./src/plugins.js",
+    "./installations": "./src/plugin-installations.js",
+    "./bundles": "./src/bundle-workspace.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "dependencies": {
+    "@mytools/sdk": "0.1.0",
+    "@mytools/fst-platform": "0.1.0",
+    "@mytools/fst-plugin": "0.1.0",
+    "@mytools/fst-workflow": "0.1.0",
+    "tar": "7.5.22",
+    "yaml": "2.9.1"
+  }
+}

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 }