@yanglaofish/fishtools 0.1.4 → 0.2.0

package/node_modules/@mytools/core/bin/fst.js

@@ -5,8 +5,9 @@ import path from 'node:path';
 import { createApplication } from '../src/application.js';
 import { verifyBundle } from '../src/bundle.js';
 import { resolveProject, initializeProject } from '../src/project.js';
-import {waitForCliRun} from '../src/cli-run.js';
+import {waitForCliRun,cliRunResult} from '../src/cli-run.js';
 import {VERSION} from '../src/version.js';
+import {listDocumentation,readDocumentation,findDocumentationRoot,exportDocumentation} from '../src/documentation.js';
 
 const program=new Command().name('fst').description('Fishtools · 插件式工作流工作台').version(VERSION);
 program.option('--maintenance','维护模式：不启动有状态服务插件');
@@ -14,13 +15,20 @@ program.option('--project <directory>','项目目录（默认当前项目或用
 async function app(){const o=program.opts();return createApplication({projectDir:await resolveProject(o.project,o.workspace),outputDir:o.output,maintenance:!!o.maintenance,config:o.config?JSON.parse(await readFile(o.config,'utf8')):{}});}
 async function use(fn){const a=await app();try{return await fn(a);}finally{await a.close();}}
 program.command('init [directory]').description('创建项目，保留已有配置与工作流').action(async directory=>console.log(`Fishtools 项目：${await initializeProject(path.resolve(directory??process.cwd()))}`));
+program.command('docs [topic]').description('阅读或导出随安装提供的离线文档').option('--path','只打印文档路径').option('--export <directory>','导出完整资料到新目录').action(async(topic,options)=>{
+  if(options.export){if(topic||options.path)throw new Error('--export 不可与文档主题或 --path 同用');console.log(await exportDocumentation(options.export));return;}
+  if(topic){const document=await readDocumentation(topic);console.log(options.path?document.path:document.text);return;}
+  if(options.path){console.log(await findDocumentationRoot());return;}
+  console.log((await listDocumentation()).map(document=>`${document.id}\t${document.title}`).join('\n'));
+  console.log('\nfst docs <主题> 阅读正文；fst docs <主题> --path 查看路径；fst docs --export <新目录> 导出全部资料');
+});
 const workflow=program.command('workflow').description('查看和检查工作流');
 workflow.command('list').action(()=>use(async a=>console.log(JSON.stringify(await a.listWorkflows(),null,2))));
 workflow.command('check <id>').action(id=>use(async a=>{await a.checkWorkflow(id);console.log('工作流校验通过');}));
 program.command('run <id>').option('--input <file>','JSON 输入文件').action((id,o)=>use(async a=>{
   const run=await a.startRun(id,o.input?JSON.parse(await readFile(o.input,'utf8')):{});
-  const r=await waitForCliRun(a,run);console.log(JSON.stringify(r.status==='succeeded'?r.output:r.error,null,2));
-  process.exitCode=r.status==='succeeded'?0:r.status==='cancelled'?130:1;
+  const result=cliRunResult(await waitForCliRun(a,run));console.log(JSON.stringify(result.value,null,2));
+  process.exitCode=result.exitCode;
 }));
 const plugin=program.command('plugin').description('管理插件');
 plugin.command('list').action(()=>use(a=>console.log(JSON.stringify(a.listPlugins(),null,2))));
@@ -36,7 +44,7 @@ packOptions(program.command('portable').description('导出完整便携工具、
 program.command('command [name]').description('列出插件命令或执行动作命令').option('--input <file>','JSON 输入').action((name,o)=>use(async a=>{
   if(!name){console.log(JSON.stringify(a.listCommands(),null,2));return;}
   const run=await a.startCommand(name,o.input?JSON.parse(await readFile(o.input,'utf8')):{});
-  const result=await waitForCliRun(a,run);console.log(JSON.stringify(result.error??result.output,null,2));process.exitCode=result.status==='succeeded'?0:result.status==='cancelled'?130:1;
+  const result=cliRunResult(await waitForCliRun(a,run));console.log(JSON.stringify(result.value,null,2));process.exitCode=result.exitCode;
 }));
 program.command('configure <plugin> <file>').description('从 JSON 保存插件配置').action((id,file)=>use(async a=>{await a.configurePlugin(id,JSON.parse(await readFile(file,'utf8')));console.log('插件配置已保存');}));
 async function web(o){

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

@@ -68,12 +68,17 @@ export async function createApplication({projectDir=process.cwd(),workspace,outp
       run.done=(async()=>{
         try {
           await event({type:'run.started'});
-          run.output=await execute(activeHost,{outputDir:dir,signal:controller.signal,runId,log:(message,data)=>event({type:'log',message,data})},event);
+          run.output=await execute(activeHost,{outputDir:dir,signal:controller.signal,runId,log:(message,data,meta={})=>event({...meta,type:'log',message,data})},event);
           run.status='succeeded';await event({type:'run.succeeded'});
         } catch(error) {
-          run.status=controller.signal.aborted||error?.code==='PROMPT_CANCELLED'?'cancelled':'failed';
-          run.error=errorRecord(error);
-          await event({type:`run.${run.status}`,message:run.error.message,code:run.error.code,plugin:run.error.plugin,action:run.error.action,command:run.error.command,details:run.error.details,error:run.error});
+          if(error?.code==='WORKFLOW_STOPPED'){
+            run.status='stopped';run.reason=error.details?.reason??error.message;
+            await event({type:'run.stopped',reason:run.reason});
+          }else{
+            run.status=error?.code==='EXECUTION_FAILED'?'failed':controller.signal.aborted||['PROMPT_CANCELLED','CANCELLED'].includes(error?.code)?'cancelled':'failed';
+            run.error=errorRecord(error);
+            await event({type:`run.${run.status}`,message:run.error.message,code:run.error.code,plugin:run.error.plugin,action:run.error.action,command:run.error.command,details:run.error.details,error:run.error});
+          }
         } finally {
           run.finishedAt=new Date().toISOString();
           await writes;

package/node_modules/@mytools/core/src/cli-run.js

@@ -4,3 +4,9 @@ export async function waitForCliRun(app,run,signals=process){
   try{return await run.done??app.getRun(run.id);}
   finally{signals.removeListener('SIGINT',cancel);}
 }
+
+export function cliRunResult(run){
+  const value=run.status==='stopped'?{status:'stopped',reason:run.reason}:run.error??run.output;
+  const exitCode=['succeeded','stopped'].includes(run.status)?0:run.status==='cancelled'?130:1;
+  return {value,exitCode};
+}

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

@@ -1,13 +1,26 @@
 import {FlowError} from '@mytools/sdk';
+import {conditionOperators} from './control.js';
 
 export const builtinCommands=[
   ['workflows','选择已有工作流'],['new','新建工作流'],['add','添加插件能力或子工作流'],
   ['steps','设置步骤参数、排序或删除'],['outputs','设置最终输出'],['save','保存工作流'],
-  ['run','运行工作流，可附带 @参数.json'],['logs','查看运行日志与保留设置'],['plugins','管理插件'],['config','设置插件配置'],
-  ['pack','选择工作流打包'],['web','启动 Web 工作台'],['help','查看操作说明'],['exit','退出终端工作台'],
+  ['run','运行工作流，可附带 @参数.json'],['runs','观察运行中的步骤、输入输出与实时日志'],['logs','查看运行日志与保留设置'],['plugins','管理插件'],['config','设置插件配置'],
+  ['pack','选择工作流打包'],['web','启动 Web 工作台'],['docs','阅读离线开发与使用文档'],['help','查看操作说明'],['exit','退出终端工作台'],
 ].map(([name,description])=>({name,description}));
 
 export function validateDeclarations(plugin){
+  for(const [name,action] of Object.entries(plugin.actions??{})){
+    if(action.conditions!==undefined&&(!action.conditions||typeof action.conditions!=='object'||Array.isArray(action.conditions)))throw new FlowError(`动作 ${name} 的 conditions 必须为对象`,{code:'VALIDATION'});
+    for(const [key,preset] of Object.entries(action.conditions??{})){
+      if(!preset||typeof preset.title!=='string'||!preset.title.trim()||typeof preset.path!=='string'||!preset.path||preset.path.split('.').some(p=>!p||['__proto__','constructor','prototype'].includes(p))||!conditionOperators.includes(preset.op)||(preset.op!=='exists'&&!Object.hasOwn(preset,'value')))throw new FlowError(`动作 ${name} 的判定预设 ${key} 无效`,{code:'VALIDATION'});
+      let schema=action.output;
+      for(const part of preset.path.split('.')){
+        if(schema?.properties&&Object.hasOwn(schema.properties,part))schema=schema.properties[part];
+        else if(schema?.type==='array'&&/^\d+$/.test(part))schema=schema.items;
+        else throw new FlowError(`判定预设 ${key} 引用了未声明的输出字段 ${preset.path}`,{code:'VALIDATION'});
+      }
+    }
+  }
   for(const key of ['platforms','architectures'])if(plugin[key]!==undefined&&(!Array.isArray(plugin[key])||!plugin[key].every(x=>typeof x==='string'&&x)))throw new FlowError(`${plugin.id} 的 ${key} 必须是字符串数组`);
   for(const declarations of [plugin.environments,...Object.values(plugin.actions??{}).map(a=>a.environments)]){
     for(const [id,e] of Object.entries(declarations??{})){

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

@@ -0,0 +1,63 @@
+import {isDeepStrictEqual} from 'node:util';
+import {FlowError} from '@mytools/sdk';
+import {bind,references} from './validation.js';
+
+export const conditionOperators=['eq','ne','gt','gte','lt','lte','contains','exists'];
+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/src/documentation.js

@@ -0,0 +1,65 @@
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {access,readFile,readdir,lstat,mkdir,copyFile,realpath} from 'node:fs/promises';
+
+const topics=[
+  ['plugins','插件开发规范','docs/plugin-development.md'],
+  ['deployment','安装与部署','docs/deployment.md'],
+  ['control','控制流与运行观察规范','docs/superpowers/specs/2026-10-11-control-observation.md'],
+  ['services','服务插件示例','examples/service-plugins/README.md'],
+  ['example','可安装的零依赖动作插件','docs/examples/action-plugin/README.md'],
+  ['roadmap','路线图','docs/roadmap.md'],
+  ['readme','Fishtools 使用说明','README.md'],
+];
+// 保留文档链接所需的目录布局；参考代码仅供阅读，不是第二份运行时。
+const assets=['README.md','LICENSE','THIRD_PARTY_NOTICES.md','docs','examples/service-plugins','plugins/examples','plugins/environment','packages/sdk','packages/core/src/host.js','packages/core/LICENSE','tests/application.test.js'];
+const excluded=new Set(['node_modules','dist','.git','.cache','__pycache__','.pytest_cache','coverage','public']);
+const inside=(parent,child)=>{const relative=path.relative(parent,child);return relative===''||(!relative.startsWith(`..${path.sep}`)&&relative!=='..'&&!path.isAbsolute(relative));};
+
+export async function findDocumentationRoot(){
+  let directory=path.dirname(fileURLToPath(import.meta.url));
+  for(;;){
+    for(const candidate of [directory,path.join(directory,'manual')]){
+      try{await access(path.join(candidate,'docs/plugin-development.md'));await access(path.join(candidate,'LICENSE'));return candidate;}
+      catch(error){if(error.code!=='ENOENT'&&error.code!=='ENOTDIR')throw error;}
+    }
+    const parent=path.dirname(directory);if(parent===directory)break;directory=parent;
+  }
+  throw new Error('当前安装缺少离线文档，请重新安装完整的 Fishtools 发行包');
+}
+
+export async function listDocumentation(){
+  const root=await findDocumentationRoot();
+  return topics.map(([id,title,file])=>({id,title,path:path.join(root,file)}));
+}
+
+export async function readDocumentation(topic='plugins'){
+  const entry=(await listDocumentation()).find(item=>item.id===topic);
+  if(!entry)throw new Error(`未知文档主题：${topic}。运行 fst docs 查看可用主题`);
+  return {...entry,text:await readFile(entry.path,'utf8')};
+}
+
+export async function copyDocumentation(destination,{sourceRoot}={}){
+  const source=await realpath(sourceRoot??await findDocumentationRoot());
+  const target=path.resolve(destination);
+  try{await lstat(target);throw new Error(`文档导出目标已存在：${target}`);}catch(error){if(error.code!=='ENOENT')throw error;}
+  // 目标可位于仓库 dist 下，但不能嵌入即将复制的资料目录。
+  await mkdir(path.dirname(target),{recursive:true});
+  const canonicalTarget=path.join(await realpath(path.dirname(target)),path.basename(target));
+  for(const asset of assets)if(inside(path.join(source,asset),canonicalTarget))throw new Error('文档导出目标不能位于原资料目录内');
+  await mkdir(target);
+  const copy=async(from,to)=>{
+    const info=await lstat(from);
+    if(info.isSymbolicLink())throw new Error(`离线文档不允许符号链接：${from}`);
+    if(info.isDirectory()){
+      await mkdir(to,{recursive:true});
+      for(const entry of await readdir(from))if(!excluded.has(entry))await copy(path.join(from,entry),path.join(to,entry));
+    }else if(info.isFile()){
+      await mkdir(path.dirname(to),{recursive:true});await copyFile(from,to);
+    }else throw new Error(`离线文档包含不支持的文件：${from}`);
+  };
+  for(const asset of assets)await copy(path.join(source,asset),path.join(target,asset));
+  return target;
+}
+
+export async function exportDocumentation(destination){return copyDocumentation(destination);}

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

@@ -2,38 +2,92 @@ import { randomUUID } from 'node:crypto';
 import { FlowError } from '@mytools/sdk';
 import { bind, validate, emptyObject } from './validation.js';
 import {errorRecord} from './diagnostics.js';
+import {evaluateCondition,childLists} from './control.js';
 
 export async function runWorkflow({store,host,id,input={},signal,onEvent=()=>{},runId=randomUUID(),context={}}) {
   const closure=await store.resolve([id],host);
   const snapshot=new Map(closure.workflows.map(w=>[w.id,w]));
   const emit=event=>onEvent({time:new Date().toISOString(),runId,...event});
-  const execute=async (workflowId,values,callPath)=>{
-    signal?.throwIfAborted();
-    const w=snapshot.get(workflowId);
-    const state={inputs:validate(w.inputs??emptyObject,values,`${workflowId} 输入`),steps:{}};
-    await emit({type:'workflow.started',workflowId,callPath});
-    for(const step of w.steps) {
-      signal?.throwIfAborted();
-      const stepPath=`${callPath}/${step.id}`, start=Date.now();
-      await emit({type:'step.started',workflowId,stepId:step.id,callPath:stepPath,action:step.action});
-      try {
-        const args=bind(step.with??{},state);
-        const output=step.action ? await host.invoke(step.action,args,{
-          ...context,signal,runId,stepId:step.id,callPath:stepPath,workflow:w,
-          log:(message,data)=>emit({type:'log',stepId:step.id,callPath:stepPath,message,data}),
-        }) : await execute(store.childId(step.workflow),args,stepPath);
-        state.steps[step.id]={output};
-        await emit({type:'step.succeeded',workflowId,stepId:step.id,callPath:stepPath,durationMs:Date.now()-start,output});
-      } catch(cause) {
-        const cancelled=signal?.aborted;
-        const error=errorRecord(cause);
-        await emit({type:cancelled?'step.cancelled':'step.failed',workflowId,stepId:step.id,callPath:stepPath,action:step.action,plugin:error.plugin,message:error.message,code:error.code,details:error.details,error,durationMs:Date.now()-start});
-        throw Object.assign(new FlowError(`${stepPath}: ${error.message}`,{code:cancelled?'CANCELLED':'EXECUTION_FAILED',cause,details:error.details}),{plugin:error.plugin,action:error.action});
+  const failures=new WeakMap();
+  const checkCancelled=currentSignal=>{if(currentSignal?.aborted)throw new FlowError('运行已取消',{code:'CANCELLED'});};
+  const skip=async(step,w,path,message)=>{
+    const callPath=`${path}/${step.id}`;
+    await emit({type:'step.skipped',workflowId:w.id,stepId:step.id,callPath,action:step.action,message});
+    for(const list of childLists(step))for(const child of list)await skip(child,w,callPath,message);
+    if(step.workflow){const child=snapshot.get(store.childId(step.workflow));for(const node of child.steps)await skip(node,child,callPath,message);}
+  };
+  const sequence=async(steps,w,base,path,currentSignal,reportFailure)=>{
+    const state={inputs:base.inputs,steps:{...base.steps}},outputs={};
+    for(let i=0;i<steps.length;i++){
+      try{
+        const result=await executeStep(steps[i],w,state,path,currentSignal,reportFailure);
+        state.steps[steps[i].id]=result;
+        if(Object.hasOwn(result,'output'))outputs[steps[i].id]=result.output;
+      }catch(error){
+        for(const pending of steps.slice(i+1))await skip(pending,w,path,error.code==='WORKFLOW_STOPPED'?'工作流已提前结束':'前序步骤失败或运行已取消');
+        throw error;
+      }
+    }
+    checkCancelled(currentSignal);return {state,outputs};
+  };
+  const parallel=async(group,w,state,path,currentSignal,reportFailure)=>{
+    const controller=new AbortController(),combined=currentSignal?AbortSignal.any([currentSignal,controller.signal]):controller.signal;
+    const results=new Array(group.steps.length);let next=0,firstError;
+    // 叶子先锁定首因，再写事件；父控制节点的异步收尾不能改变失败顺序。
+    const fail=error=>{if(!firstError){firstError=error;reportFailure?.(error);controller.abort(error);}};
+    const worker=async()=>{
+      while(!firstError&&next<group.steps.length){
+        const index=next++,step=group.steps[index];
+        try{results[index]=await executeStep(step,w,{inputs:state.inputs,steps:{...state.steps}},path,combined,fail);}
+        catch(error){fail(error);}
       }
+    };
+    // 等待所有已启动任务清理，避免 Promise.all 首次拒绝后仍有后台动作执行。
+    await Promise.all(Array.from({length:Math.min(group.concurrency??4,group.steps.length)},worker));
+    if(firstError){for(const step of group.steps.slice(next))await skip(step,w,path,'并行组已停止调度');throw firstError;}
+    return Object.fromEntries(group.steps.flatMap((step,index)=>Object.hasOwn(results[index]??{},'output')?[[step.id,results[index].output]]:[]));
+  };
+  const executeStep=async(step,w,state,parentPath,currentSignal,reportFailure)=>{
+    const callPath=`${parentPath}/${step.id}`,start=Date.now(),base={workflowId:w.id,stepId:step.id,callPath,action:step.action};
+    try{
+      checkCancelled(currentSignal);
+      if(step.when&&!evaluateCondition(step.when,state)){await skip(step,w,parentPath,'执行条件不满足');return {status:'skipped'};}
+      const args=step.action||step.workflow?bind(step.with??{},state):{};
+      await emit({type:'step.started',...base,input:args});
+      let output;
+      if(step.action)output=await host.invoke(step.action,args,{
+        ...context,signal:currentSignal,runId,stepId:step.id,callPath,workflow:w,
+        log:(message,data,meta={})=>emit({type:'log',stream:meta.stream,...base,message,data}),
+      });
+      else if(step.workflow)output=await execute(store.childId(step.workflow),args,callPath,currentSignal,reportFailure);
+      else if(step.branch){
+        const matched=evaluateCondition(step.branch.condition,state);
+        for(const unused of matched?(step.branch.else??[]):step.branch.then)await skip(unused,w,callPath,'未选择此分支');
+        output=(await sequence(matched?step.branch.then:(step.branch.else??[]),w,state,callPath,currentSignal,reportFailure)).outputs;
+      }else if(step.parallel)output=await parallel(step.parallel,w,state,callPath,currentSignal,reportFailure);
+      else throw new FlowError(step.stop.reason,{code:'WORKFLOW_STOPPED',details:{reason:step.stop.reason}});
+      checkCancelled(currentSignal);
+      await emit({type:'step.succeeded',...base,durationMs:Date.now()-start,output});
+      return {status:'succeeded',output};
+    }catch(cause){
+      const origin=failures.get(cause),propagated=origin&&(origin===callPath||origin.startsWith(callPath+'/'));
+      const cancelled=propagated?cause.code==='CANCELLED':!!currentSignal?.aborted,stopped=!cancelled&&cause.code==='WORKFLOW_STOPPED',error=errorRecord(cause);
+      const failure=propagated||stopped?cause:Object.assign(new FlowError(`${callPath}: ${error.message}`,{code:cancelled?'CANCELLED':'EXECUTION_FAILED',cause,details:error.details}),{plugin:error.plugin,action:error.action});
+      if(!failures.has(failure))failures.set(failure,callPath);
+      reportFailure?.(failure);
+      await emit({type:cancelled?'step.cancelled':stopped?'step.stopped':'step.failed',...base,plugin:error.plugin,message:error.message,code:error.code,details:error.details,error:stopped?undefined:error,durationMs:Date.now()-start});
+      throw failure;
     }
-    const output=bind(w.outputs??{},state);
-    await emit({type:'workflow.succeeded',workflowId,callPath});
-    return output;
   };
-  return execute(id,input,id);
+  const execute=async(workflowId,values,callPath,currentSignal,reportFailure)=>{
+    checkCancelled(currentSignal);
+    const w=snapshot.get(workflowId),state={inputs:validate(w.inputs??emptyObject,values,`${workflowId} 输入`),steps:{}};
+    await emit({type:'workflow.started',workflowId,callPath});
+    try{
+      const result=await sequence(w.steps,w,state,callPath,currentSignal,reportFailure),output=bind(w.outputs??{},result.state);
+      checkCancelled(currentSignal);
+      await emit({type:'workflow.succeeded',workflowId,callPath});return output;
+    }catch(error){if(error.code==='WORKFLOW_STOPPED')await emit({type:'workflow.stopped',workflowId,callPath,message:error.details.reason});throw error;}
+  };
+  return execute(id,input,id,signal);
 }

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

@@ -14,6 +14,17 @@ export async function createHost({ plugins = [], config = {}, services = {}, env
   const extensions = new Map();
   const serviceNames = new Set();
   const commandNames=new Set(),commands=new Map();
+  function bindContext(context){
+    const bound={...services,...context},execute=bound.runProcess;
+    if(typeof execute==='function')bound.runProcess=(file,args,options={})=>{
+      const signal=context.signal&&options.signal?AbortSignal.any([context.signal,options.signal]):context.signal??options.signal;
+      return execute(file,args,{...options,signal,onOutput:async({stream,message})=>{
+        await bound.log?.(message,undefined,{stream});
+        await options.onOutput?.({stream,message});
+      }});
+    };
+    return bound;
+  }
   for (const entry of plugins) {
     const plugin = entry.plugin ?? entry;
     validateDeclarations(plugin);validateCommands(plugin,commandNames);
@@ -79,7 +90,7 @@ export async function createHost({ plugins = [], config = {}, services = {}, env
       try{
       const getService=runtime.bindServices(plugin.id);
       context.signal?.throwIfAborted();
-      const result=await command.run(validate(command.input??emptyObject,input,`/${name} 输入`),{...services,...context,getService,config:command.config,resourceDir:plugin.root,environments:resolveEnvironments(plugin,undefined,environmentOverrides[plugin.id])});
+      const result=await command.run(validate(command.input??emptyObject,input,`/${name} 输入`),{...bindContext(context),getService,config:command.config,resourceDir:plugin.root,environments:resolveEnvironments(plugin,undefined,environmentOverrides[plugin.id])});
       context.signal?.throwIfAborted();
       return validate(command.output,JSON.parse(JSON.stringify(result??{})),`/${name} 输出`);
       }catch(cause){throw pluginError(cause,{plugin:plugin.id,command:`/${name}`});}
@@ -92,7 +103,7 @@ export async function createHost({ plugins = [], config = {}, services = {}, env
       try{
       const getService=runtime.bindServices(action.plugin);
       context.signal?.throwIfAborted();
-      const result = await action.run(validate(action.input ?? emptyObject,input,`${id} 输入`), {...services,...context,getService, config:action.config, resourceDir:action.root,environments:resolveEnvironments(definitions.get(action.plugin),action,environmentOverrides[action.plugin])});
+      const result = await action.run(validate(action.input ?? emptyObject,input,`${id} 输入`), {...bindContext(context),getService, config:action.config, resourceDir:action.root,environments:resolveEnvironments(definitions.get(action.plugin),action,environmentOverrides[action.plugin])});
       context.signal?.throwIfAborted();
       // 通过 JSON 边界验证返回值，避免函数、循环引用等进入工作流状态。
       const encoded = JSON.stringify(result);

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

@@ -1,9 +1,9 @@
 const names={
-  'run.started':'运行开始','run.succeeded':'运行成功','run.failed':'运行失败','run.cancelled':'运行取消',
-  'workflow.started':'工作流开始','workflow.succeeded':'工作流完成',
-  'step.started':'步骤开始','step.succeeded':'步骤成功','step.failed':'步骤失败','step.cancelled':'步骤取消',log:'插件日志',
+  'run.started':'运行开始','run.succeeded':'运行成功','run.failed':'运行失败','run.cancelled':'运行取消','run.stopped':'运行停止',
+  'workflow.started':'工作流开始','workflow.succeeded':'工作流完成','workflow.stopped':'工作流停止',
+  'step.started':'步骤开始','step.succeeded':'步骤成功','step.failed':'步骤失败','step.cancelled':'步骤取消','step.skipped':'步骤跳过','step.stopped':'步骤停止',log:'插件日志',
 };
-const statuses={running:'运行中',succeeded:'成功',failed:'失败',cancelled:'已取消'};
+const statuses={running:'运行中',succeeded:'成功',failed:'失败',cancelled:'已取消',stopped:'已停止'};
 
 // 用长于正文的围栏包裹插件文本，避免错误消息中的 Markdown 改写日志结构。
 function block(value,language='text'){
@@ -34,12 +34,14 @@ export function markdownHeader(run){
 export function markdownEvent(event){
   let output=`### ${names[event.type]??'事件'}\n\n`;
   const lines=[`时间：${event.time}`];
-  for(const [key,label] of [['callPath','调用路径'],['action','动作'],['plugin','插件'],['command','命令'],['durationMs','耗时（毫秒）']]){
+  for(const [key,label] of [['callPath','调用路径'],['action','动作'],['plugin','插件'],['command','命令'],['stream','输出流'],['durationMs','耗时（毫秒）']]){
     if(event[key]!==undefined)lines.push(`${label}：${event[key]}`);
   }
   output+=block(lines.join('\n'));
   if(event.message)output+=block(event.message);
+  if(event.reason!==undefined)output+='停止或跳过原因：\n\n'+block(event.reason);
   if(event.data!==undefined)output+='附加信息：\n\n'+block(event.data,'json');
+  if(event.input!==undefined)output+='步骤输入：\n\n'+block(event.input,'json');
   if(event.output!==undefined)output+='步骤输出：\n\n'+block(event.output,'json');
   if(event.error)output+=errorText(event.error);
   return output;
@@ -47,6 +49,7 @@ export function markdownEvent(event){
 
 export function markdownResult(run){
   let output='## 最终结果\n\n'+block(`状态：${statuses[run.status]??run.status}\n结束时间：${run.finishedAt}`);
+  if(run.reason!==undefined)output+='停止原因：\n\n'+block(run.reason);
   if(run.output!==undefined)output+=block(run.output,'json');
   return output;
 }

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

@@ -2,14 +2,15 @@ import { execa } from 'execa';
 import treeKill from 'tree-kill';
 import which from 'which';
 import { FlowError } from '@mytools/sdk';
+import { StringDecoder } from 'node:string_decoder';
 
-export async function runProcess(file,args=[],{cwd,env,signal,timeout=30000,maxBuffer=4*1024*1024}={}) {
+export async function runProcess(file,args=[],{cwd,env,signal,timeout=30000,maxBuffer=4*1024*1024,onOutput}={}) {
   if(signal?.aborted) throw new FlowError('操作已取消',{code:'CANCELLED'});
   let executable;
   try {executable=await which(file,{path:env?.PATH??process.env.PATH});}
   catch(cause){throw new FlowError(`未找到程序：${file}`,{code:'ENOENT',details:{executable:file},cause});}
   const child=execa(executable,args,{cwd,env,reject:false,windowsHide:true,maxBuffer,timeout:0,shell:false});
-  let reason, killing;
+  let reason,killing,outputError,outputFailed=false,outputWrites=Promise.resolve();
   const stop=kind=>{
     if(reason) return; reason=kind;
     killing=new Promise(resolve=>child.pid ? treeKill(child.pid,'SIGKILL',()=>resolve()) : resolve());
@@ -17,21 +18,41 @@ export async function runProcess(file,args=[],{cwd,env,signal,timeout=30000,maxB
   const cancel=()=>stop('cancelled');
   signal?.addEventListener('abort',cancel,{once:true});
   if(signal?.aborted)cancel();
-  // 流量超限时立即回收整棵进程树，不能只等输出收集器或进程自行退出。
-  for(const stream of [child.stdout,child.stderr]){
-    let bytes=0;
-    stream?.on('data',chunk=>{bytes+=Buffer.byteLength(chunk);if(bytes>maxBuffer)stop('output-limit');});
+  const emit=(stream,message)=>{
+    if(!onOutput||!message)return;
+    // 立即挂接拒绝处理，不能让事件回调中的异步落盘变成未处理拒绝。
+    outputWrites=outputWrites.then(async()=>{if(!outputFailed)await onOutput({stream,message});}).catch(error=>{
+      if(!outputFailed){outputFailed=true;outputError=error;stop('output-callback');}
+    });
+  };
+  const flush=[];
+  for(const [name,stream] of [['stdout',child.stdout],['stderr',child.stderr]]){
+    let bytes=0,ended=false;
+    const decoder=new StringDecoder('utf8');
+    const finish=()=>{if(!ended){ended=true;emit(name,decoder.end());}};
+    flush.push(finish);stream?.once('end',finish);
+    stream?.on('data',chunk=>{
+      bytes+=Buffer.byteLength(chunk);
+      // 流量超限时立即回收整棵进程树，不继续扩张待落盘的日志队列。
+      if(bytes>maxBuffer){stop('output-limit');return;}
+      if(onOutput)emit(name,decoder.write(Buffer.isBuffer(chunk)?chunk:Buffer.from(chunk)));
+    });
   }
   const timer=timeout>0 ? setTimeout(()=>stop('timeout'),timeout) : null;
+  let result;
   try {
-    const result=await child;
-    if(killing) await killing;
-    if(reason==='output-limit')throw new FlowError('程序输出超过上限',{code:'OUTPUT_LIMIT'});
-    if(reason) throw new FlowError(reason==='cancelled'?'操作已取消':'程序运行超时',{code:reason==='cancelled'?'CANCELLED':'TIMEOUT'});
-    if(result.isMaxBuffer) throw new FlowError('程序输出超过上限',{code:'OUTPUT_LIMIT'});
-    if(result.exitCode===undefined && result.failed) throw new FlowError(`无法启动程序 ${file}：${result.shortMessage??result.message}`,{code:result.code??'SPAWN_FAILED'});
-    return {exitCode:result.exitCode,stdout:result.stdout??'',stderr:result.stderr??''};
+    result=await child;
   } finally {
-    clearTimeout(timer); signal?.removeEventListener('abort',cancel);
+    clearTimeout(timer);
+    for(const finish of flush)finish();
+    await outputWrites;
+    if(killing)await killing;
+    signal?.removeEventListener('abort',cancel);
   }
+  if(reason==='output-callback')throw outputError;
+  if(reason==='output-limit')throw new FlowError('程序输出超过上限',{code:'OUTPUT_LIMIT'});
+  if(reason)throw new FlowError(reason==='cancelled'?'操作已取消':'程序运行超时',{code:reason==='cancelled'?'CANCELLED':'TIMEOUT'});
+  if(result.isMaxBuffer)throw new FlowError('程序输出超过上限',{code:'OUTPUT_LIMIT'});
+  if(result.exitCode===undefined&&result.failed)throw new FlowError(`无法启动程序 ${file}：${result.shortMessage??result.message}`,{code:result.code??'SPAWN_FAILED'});
+  return {exitCode:result.exitCode,stdout:result.stdout??'',stderr:result.stderr??''};
 }

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

@@ -12,7 +12,7 @@ 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']){
+  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;}
   }

package/node_modules/@mytools/core/src/run-logs.js

@@ -28,7 +28,7 @@ export function createRunLogs(directory,{projectDir,allowLegacy=false}){
       if(!entry.isDirectory()||!validId(entry.name))continue;
       try{
         const record=await read(entry.name);
-        if(typeof record.workflowId==='string'&&['succeeded','failed','cancelled'].includes(record.status)&&Number.isFinite(Date.parse(record.finishedAt)))results.push(record);
+        if(typeof record.workflowId==='string'&&['succeeded','failed','cancelled','stopped'].includes(record.status)&&Number.isFinite(Date.parse(record.finishedAt)))results.push(record);
       }catch(error){if(error.code==='EACCES'||error.code==='EPERM')throw error;}
     }
     return results.sort((a,b)=>Date.parse(b.finishedAt)-Date.parse(a.finishedAt)||b.id.localeCompare(a.id));

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

@@ -0,0 +1,32 @@
+import { outputSources, precedingSteps, stepMetadata } from './model.js';
+import { editValue } from './schema.js';
+
+export function conditionSources(flow,index,catalog,workflows){
+  const flatten=(schema,prefix)=>Object.entries(schema?.properties??{}).flatMap(([key,value])=>[{value:`${prefix}.${key}`,label:value.title??`${prefix}.${key}`,schema:value},...flatten(value,`${prefix}.${key}`)]);
+  return [...flatten(flow.inputs,'inputs'),...outputSources(flow,index,catalog,workflows)];
+}
+
+// 条件使用结构化表单构造；用户不需要了解底层 JSON 协议。
+export async function editCondition(ui,flow,index,catalog,workflows,{baseDir,current}={}){
+  const presets=precedingSteps(flow,index).flatMap(step=>Object.entries(stepMetadata(step,catalog,workflows)?.conditions??{}).map(([key,preset])=>({value:`preset:steps.${step.id}.output:${key}`,label:`${step.title??step.id} · ${preset.title??key}`,condition:{left:{$ref:`steps.${step.id}.output.${preset.path}`},op:preset.op,...(preset.op==='exists'?{}:{right:preset.value})}})));
+  const mode=await ui.select('设置判断条件',[
+    ...presets,{value:'compare',label:'选择字段与比较方式'},{value:'all',label:'全部条件成立（且）'},{value:'any',label:'任一条件成立（或）'},{value:'not',label:'条件取反'},...(current?[{value:'keep',label:'保留当前条件'}]:[]),
+  ]);
+  if(mode==='keep')return current;
+  const preset=presets.find(p=>p.value===mode);if(preset)return structuredClone(preset.condition);
+  if(mode==='not')return {not:await editCondition(ui,flow,index,catalog,workflows,{baseDir})};
+  if(mode==='all'||mode==='any'){
+    const children=[];
+    do{children.push(await editCondition(ui,flow,index,catalog,workflows,{baseDir}));}while(await ui.confirm('继续添加判断条件？'));
+    return {[mode]:children};
+  }
+  const sources=conditionSources(flow,index,catalog,workflows);
+  if(!sources.length)throw new Error('请先添加运行参数或产生输出的前置步骤');
+  const source=await ui.select('选择要判断的字段',sources),schema=sources.find(s=>s.value===source)?.schema??{};
+  const op=await ui.select('比较方式',[['eq','等于'],['ne','不等于'],['gt','大于'],['gte','大于等于'],['lt','小于'],['lte','小于等于'],['contains','包含'],['exists','存在']].map(([value,label])=>({value,label})));
+  if(op==='exists')return {left:{$ref:source},op};
+  const type=op==='contains'&&schema.type==='array'?schema.items?.type:schema.type;
+  const chosen=['string','number','integer','boolean'].includes(type)?type:await ui.select('比较值类型',[{value:'string',label:'文本'},{value:'number',label:'数字'},{value:'boolean',label:'是 / 否'}]);
+  const right=await editValue(ui,{type:chosen},current?.right,{baseDir,required:true,label:'比较值'});
+  return {left:{$ref:source},op,right};
+}

package/node_modules/@mytools/core/src/terminal/log-viewer.js

@@ -1,10 +1,8 @@
 import { Markdown, matchesKey, truncateToWidth } from '@mariozechner/pi-tui';
+import { mouseWheel } from './run-viewer.js';
+import {palette,markdownTheme} from './theme.js';
 
-const plain=text=>text;
-const cyan=text=>`\x1b[36m${text}\x1b[0m`;
-const dim=text=>`\x1b[2m${text}\x1b[0m`;
-const theme={heading:cyan,link:cyan,linkUrl:dim,code:cyan,codeBlock:plain,codeBlockBorder:dim,quote:plain,quoteBorder:dim,hr:dim,listBullet:cyan,
-  bold:text=>`\x1b[1m${text}\x1b[22m`,italic:text=>`\x1b[3m${text}\x1b[23m`,strikethrough:text=>`\x1b[9m${text}\x1b[29m`,underline:text=>`\x1b[4m${text}\x1b[24m`};
+const theme=markdownTheme();
 
 // 文本已由 TerminalView 的 safe 清理；每次只向 Overlay 提交当前窗口内的行。
 export class MarkdownLogViewer{
@@ -27,14 +25,15 @@ export class MarkdownLogViewer{
     const body=lines.slice(this.offset,this.offset+pageSize);
     while(body.length<pageSize)body.push('');
     const start=lines.length?this.offset+1:0,end=Math.min(this.offset+pageSize,lines.length);
-    const footer=dim(`${start}–${end}/${lines.length} · ↑↓ 滚动 · PgUp/PgDn 翻页 · Home/End · Esc/Enter/q 返回`);
-    const screen=height===1?body:height===2?[...body,footer]:[cyan(this.title),...body,footer];
+    const footer=palette.muted(`Esc/q 返回 · ↑↓/滚轮 · PgUp/PgDn · Home/End · ${start}–${end}/${lines.length}`);
+    const screen=height===1?body:height===2?[...body,footer]:[palette.brand(this.title),...body,footer];
     return screen.map(line=>truncateToWidth(line,width));
   }
   handleInput(data){
     if(['escape','enter','q'].some(key=>matchesKey(data,key))){this.onClose();return;}
     const {pageSize,maxOffset}=this.layout(this.terminal.columns);
-    if(matchesKey(data,'up'))this.offset--;
+    if(mouseWheel(data))this.offset+=mouseWheel(data)*3;
+    else if(matchesKey(data,'up'))this.offset--;
     else if(matchesKey(data,'down'))this.offset++;
     else if(matchesKey(data,'pageUp'))this.offset-=pageSize;
     else if(matchesKey(data,'pageDown'))this.offset+=pageSize;