@yanglaofish/fishtools 0.1.4 → 0.2.0

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

@@ -38,8 +38,21 @@ export async function readRunInput(reference,baseDir){
 
 export const newWorkflow=(title,description)=>({schemaVersion:1,id:`flow-${randomUUID().slice(0,8)}`,title,description,inputs:{type:'object',properties:{}},steps:[],outputs:{}});
 
+// 路径从根 steps 开始，例如 [1, 'branch', 'then', 0]。
+export const stepAt=(flow,index)=>[...(Array.isArray(index)?index:[index])].reduce((node,key)=>node[key],flow.steps);
+export const sequenceAt=(flow,parts=[])=>parts.reduce((node,key)=>node[key],flow.steps);
+export function precedingSteps(flow,index){
+  const parts=Array.isArray(index)?index:[index];let sequence=flow.steps;const result=[];
+  for(let i=0;i<parts.length;i+=3){
+    // 并行子项同属一批，不能把前面的兄弟当成已完成步骤。
+    if(i===0||parts[i-2]!=='parallel')result.push(...sequence.slice(0,parts[i]));
+    if(i+1<parts.length)sequence=sequence[parts[i]][parts[i+1]][parts[i+2]];
+  }
+  return result;
+}
+
 export function setBinding(flow,index,key,mode,schema,value){
-  const step=flow.steps[index],old=step.with?.[key];step.with??={};
+  const step=stepAt(flow,index),old=step.with?.[key];step.with??={};
   if(mode==='runtime'){
     flow.inputs??={type:'object',properties:{}};flow.inputs.properties??={};
     const name=`fst_${step.id}_${key}`;
@@ -60,15 +73,31 @@ export function setBinding(flow,index,key,mode,schema,value){
   }
 }
 
+export function pruneRuntimeInputs(flow){
+  const refs=new Set();
+  const scan=value=>{if(value&&typeof value==='object'){if(typeof value.$ref==='string')refs.add(value.$ref);Object.values(value).forEach(scan);}};
+  scan(flow.steps);scan(flow.outputs);
+  for(const name of Object.keys(flow.inputs?.properties??{})){
+    if(name.startsWith('fst_')&&!refs.has(`inputs.${name}`)){
+      delete flow.inputs.properties[name];flow.inputs.required=(flow.inputs.required??[]).filter(key=>key!==name);
+    }
+  }
+}
+
 export function stepMetadata(step,catalog,workflows){
+  if(step.branch||step.parallel){
+    const children=step.parallel?.steps??[...(step.branch.then??[]),...(step.branch.else??[])];
+    return {title:step.title??(step.branch?'条件分支':'并行组'),output:{type:'object',properties:Object.fromEntries(children.map(child=>[child.id,stepMetadata(child,catalog,workflows)?.output??{}]))}};
+  }
+  if(step.stop)return {title:step.title??'提前结束',output:{type:'object',properties:{}}};
   if(step.action)return catalog.find(a=>a.id===step.action);
-  const flow=workflows.find(w=>`./${w.id}.yaml`===step.workflow);
+  const flow=workflows.find(w=>`${w.id}.yaml`===step.workflow?.replace(/^\.\//,''));
   return flow?{title:flow.title??flow.id,description:flow.description,input:flow.inputs,output:{type:'object',properties:Object.fromEntries(Object.keys(flow.outputs??{}).map(k=>[k,{}]))}}:null;
 }
 
 export function outputSources(flow,index,catalog,workflows){
   const flatten=(schema,prefix='')=>Object.entries(schema?.properties??{}).flatMap(([key,s])=>{const name=prefix?`${prefix}.${key}`:key;return [{name,schema:s},...flatten(s,name)];});
-  return flow.steps.slice(0,index).flatMap((step,i)=>{
+  return precedingSteps(flow,index).flatMap((step,i)=>{
     const meta=stepMetadata(step,catalog,workflows),base=`steps.${step.id}.output`,label=`${i+1}. ${meta?.title??step.id}`;
     return [{value:base,label:`${label} → 完整输出`,schema:meta?.output},...flatten(meta?.output).map(f=>({value:`${base}.${f.name}`,label:`${label} → ${f.schema.title??f.name}`,schema:f.schema}))];
   });

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

@@ -1,9 +1,7 @@
 export const logo=[
-  'FFFFF IIIII  SSSS H   H  t             l',
-  'F       I   S     H   H ttt  oo   oo  l  sss',
-  'FFFF    I    SSS  HHHHH  t  o  o o  o l ss',
-  'F       I       S H   H  t  o  o o  o l   ss',
-  'F     IIIII SSSS  H   H  tt  oo   oo  l sss',
+  '█▀▀ ▀█▀ █▀▀ █ █',
+  '█▀   █  ▀▀█ █▀█',
+  '▀   ▀▀▀ ▀▀▀ ▀ ▀',
 ].join('\n');
 
 export const pluginStatus=plugin=>({ready:'可用',pending:'等待服务',failed:'失败',stopped:'已停止'})[plugin.runtime?.status]??'未知';
@@ -11,10 +9,10 @@ export const pluginStatus=plugin=>({ready:'可用',pending:'等待服务',failed
 export function gettingStarted(flows,{readOnly=false}={}){
   const sample=flows.find(w=>w.id==='hello')??flows[0];
   return [
-    sample?`先试一次：/run ${sample.id}  → ${sample.title??sample.id}\n${sample.description??'按提示填写参数，执行后可用 /logs 查看结果和日志。'}`:'当前工作区还没有工作流。',
-    `/workflows 浏览工作流    /plugins 查看已安装插件`,
-    ...(!readOnly?['自己编排：/new 新建 → /add 添加步骤 → /save 保存 → /run 执行']:['这是只读运行包：可选择工作流、填写运行参数并执行。']),
-    '/help 查看完整用法和文件参数示例',
+    sample?`试运行  /run ${sample.id}\n${sample.description??sample.title??'按提示填写参数，执行后查看结果。'}`:'当前工作区还没有工作流。',
+    '',
+    `/workflows 工作流   /plugins 插件`,
+    `${readOnly?'只读运行包': '/new 新建'}   /runs 运行观察   /help 帮助`,
   ].join('\n');
 }
 

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

@@ -0,0 +1,86 @@
+import { stripVTControlCharacters } from 'node:util';
+import { Text, matchesKey, truncateToWidth } from '@mariozechner/pi-tui';
+import {palette} from './theme.js';
+
+export const runStatuses={pending:'待执行',running:'运行中',succeeded:'成功',failed:'失败',cancelled:'已取消',skipped:'已跳过',stopped:'已停止'};
+const safe=value=>stripVTControlCharacters(String(value)).replace(/[\x00-\x08\x0b-\x1f\x7f]/g,'');
+export const mouseWheel=data=>{const match=/^\x1b\[<(\d+);\d+;\d+[Mm]$/.exec(data);return match&&(Number(match[1])&64)?(Number(match[1])&1?1:-1):0;};
+export const mouseOn='\x1b[?1000h\x1b[?1006h';
+export const mouseOff='\x1b[?1006l\x1b[?1000l';
+
+export class RunViewer{
+  constructor({record,flow,workflows=[],terminal,onClose,onCancel,requestRender}){
+    Object.assign(this,{terminal,onClose,onCancel,requestRender});this.view=0;this.selected=0;this.offset=0;this.follow=true;this.allLogs=false;this.confirmCancel=false;
+    this.planned=[];
+    const walk=(steps,prefix,ancestors)=>{
+      for(const step of steps??[]){
+        const callPath=`${prefix}/${step.id}`;this.planned.push({callPath,stepId:step.id,action:step.action,title:step.title,status:'pending'});
+        if(step.branch){walk(step.branch.then,callPath,ancestors);walk(step.branch.else,callPath,ancestors);}
+        if(step.parallel)walk(step.parallel.steps,callPath,ancestors);
+        if(step.workflow){const child=workflows.find(w=>`${w.id}.yaml`===step.workflow.replace(/^\.\//,''));if(child&&!ancestors.has(child.id))walk(child.steps,callPath,new Set([...ancestors,child.id]));}
+      }
+    };
+    if(flow)walk(flow.steps,flow.id,new Set([flow.id]));
+    this.update(record);
+  }
+  invalidate(){}
+  update(record){
+    if(!record)return;
+    this.record=record;const nodes=new Map(this.planned.map(node=>[node.callPath,{...node}]));
+    for(const event of record.events??[]){
+      if(!event.type.startsWith('step.')||!event.callPath)continue;
+      const node=nodes.get(event.callPath)??{callPath:event.callPath,stepId:event.stepId};
+      Object.assign(node,event,{status:event.type==='step.started'?'running':event.type.slice(5)});nodes.set(event.callPath,node);
+    }
+    this.nodes=[...nodes.values()];this.selected=Math.max(0,Math.min(this.selected,this.nodes.length-1));
+    this.requestRender();
+  }
+  content(){
+    const node=this.nodes[this.selected],status=runStatuses[this.record.status]??this.record.status;
+    if(this.view===0)return [`运行：${status}${this.record.reason?` · ${this.record.reason}`:''}`,this.record.error?`错误：${this.record.error.message}`:'',...this.nodes.map((n,i)=>`${i===this.selected?'›':' '} ${runStatuses[n.status]??n.status} · ${n.callPath}${n.action?` · ${n.action}`:''}${n.message?` · ${n.message}`:''}`)].filter(Boolean).join('\n');
+    if(this.view===1)return `步骤：${node?.callPath??'运行结果'}\n输入\n${JSON.stringify(node?.input??{},null,2)}\n输出\n${JSON.stringify(node?.output??{},null,2)}${node?.error?`\n错误\n${JSON.stringify(node.error,null,2)}`:''}${node?.reason||node?.message?`\n说明：${node.reason??node.message}`:''}\n运行状态：${status}${this.record.reason?` · ${this.record.reason}`:''}\n汇总输出\n${JSON.stringify(this.record.output??{},null,2)}`;
+    const logs=(this.record.events??[]).filter(e=>e.type==='log'&&(this.allLogs||!node||e.callPath===node.callPath));
+    return logs.length?logs.map(e=>`${this.allLogs?`[${e.callPath??'运行'}] `:''}[${e.stream??'日志'}] ${e.message??''}${e.data?` ${JSON.stringify(e.data)}`:''}`).join('\n'):'尚无日志';
+  }
+  layout(width){
+    const height=Math.max(1,this.terminal.rows),pageSize=Math.max(1,height-3);
+    const lines=new Text(safe(this.content()),0,0).render(Math.max(1,width));
+    const maxOffset=Math.max(0,lines.length-pageSize);
+    this.offset=this.follow&&this.view===2?maxOffset:Math.max(0,Math.min(this.offset,maxOffset));
+    return {height,pageSize,lines,maxOffset};
+  }
+  render(width){
+    const {height,pageSize,lines}=this.layout(width),node=this.nodes[this.selected];
+    const body=lines.slice(this.offset,this.offset+pageSize);while(body.length<pageSize)body.push('');
+    const tabs=`${['1 总览','2 输入输出','3 日志'].map((s,i)=>this.view===i?palette.brand(`[${s}]`):palette.muted(s)).join('  ')} ${palette.muted('·')} ${palette.text(safe(runStatuses[this.record.status]??this.record.status))} ${palette.muted('· '+safe(this.record.workflowId??'运行'))}`;
+    const selection=`[ / ] 切换步骤：${node?.callPath??'暂无步骤'}${this.view===2?` · ${this.allLogs?'全部日志':'本步骤日志'} · ${this.follow?'跟随尾部':'暂停跟随'}`:''}`;
+    const footer=this.confirmCancel?'取消整个运行？y 确认 · 任意其他键返回':`q/Esc 关闭 · x 取消 · ↑↓/滚轮 PgUp/PgDn · End 跟随 · a 全部日志 · ${this.offset+1}–${Math.min(this.offset+pageSize,lines.length)}/${lines.length}`;
+    const styledBody=body.map(line=>line.startsWith('›')?palette.brand(line):line);
+    const styledFooter=palette.muted(safe(footer));
+    const screen=height===1?styledBody:height===2?[styledBody[0],styledFooter]:height===3?[tabs,styledBody[0],styledFooter]:[tabs,palette.muted(safe(selection)),...styledBody,styledFooter];
+    return screen.map(line=>truncateToWidth(line,width));
+  }
+  handleInput(data){
+    if(this.confirmCancel){this.confirmCancel=false;if(data==='y')this.onCancel();this.requestRender();return;}
+    if(['escape','q','enter'].some(key=>matchesKey(data,key))){this.onClose();return;}
+    if(data==='x'&&this.record.status==='running'){this.confirmCancel=true;this.requestRender();return;}
+    if(['1','2','3'].includes(data)){this.view=Number(data)-1;this.offset=0;this.follow=true;this.requestRender();return;}
+    if(data==='['||data===']'){
+      this.selected=Math.max(0,Math.min(this.nodes.length-1,this.selected+(data===']'?1:-1)));this.offset=0;
+      if(this.view===0)this.offset=Math.max(0,this.selected-Math.floor((this.terminal.rows-3)/2));
+      this.requestRender();return;
+    }
+    if(data==='a'){this.allLogs=!this.allLogs;this.offset=0;this.requestRender();return;}
+    if(data==='f'){this.follow=!this.follow;this.requestRender();return;}
+    const {pageSize,maxOffset}=this.layout(this.terminal.columns),wheel=mouseWheel(data);
+    if(wheel)this.offset+=wheel*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;
+    else if(matchesKey(data,'home'))this.offset=0;
+    else if(matchesKey(data,'end')){this.offset=maxOffset;this.follow=true;this.requestRender();return;}
+    else return;
+    this.follow=false;this.offset=Math.max(0,Math.min(maxOffset,this.offset));this.requestRender();
+  }
+}

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

@@ -1,6 +1,8 @@
 import { randomUUID } from 'node:crypto';
 import path from 'node:path';
-import { commands, parseCommand, fileReference, readRunInput, newWorkflow, setBinding, stepMetadata, outputSources } from './model.js';
+import { commands, parseCommand, fileReference, readRunInput, newWorkflow, setBinding, stepMetadata, outputSources, stepAt, sequenceAt, pruneRuntimeInputs } from './model.js';
+import { editCondition } from './conditions.js';
+import { runStatuses } from './run-viewer.js';
 import { editValue, needsJsonEditor } from './schema.js';
 import {gettingStarted,pluginStatus,pluginDetails} from './presentation.js';
 
@@ -10,14 +12,23 @@ export class TerminalSession{
   current(){if(!this.flow)throw new Error('先用 /workflows 打开工作流，或用 /new 新建');return this.flow;}
   commands(){return [...commands,...this.app.listCommands()];}
   async discard(){return !this.dirty||await this.ui.confirm('当前修改未保存，是否放弃修改？');}
+  async mayExit(){
+    if(!await this.discard())return false;
+    const active=this.app.listRuns().filter(run=>run.status==='running');
+    if(active.length){
+      if(!await this.ui.confirm(`仍有 ${active.length} 个后台任务。退出工作台将取消这些任务，是否退出？`))return false;
+      for(const run of active)this.app.cancelRun(run.id);
+    }
+    return true;
+  }
   async run(){
-    this.ui.show(gettingStarted(await this.app.listWorkflows(),this.app.project));
+    this.ui.show(gettingStarted(await this.app.listWorkflows(),this.app.project),{kind:'welcome'});
     try{
       while(!this.exiting){
-        this.ui.summary(`欢迎使用 Fishtools，用它将插件能力按顺序编排成工作流。\n当前工作区：${this.app.projectDir}\n${this.app.listPlugins().length} 个插件 · ${(await this.app.listWorkflows()).length} 个工作流${this.flow?` · 当前：${this.flow.title??this.flow.id}（${this.flow.steps.length} 步，${this.dirty?'未保存':'已保存'}）`:''}`);
+        this.ui.summary(`欢迎使用 Fishtools · 插件编排工作台\n当前工作区：${this.app.projectDir}\n${this.app.listPlugins().length} 个插件 · ${(await this.app.listWorkflows()).length} 个工作流${this.flow?` · ${this.flow.title??this.flow.id} · ${this.dirty?'未保存':'已保存'}`:''}`);
         let text;
-        try{text=await this.ui.input('fst > 输入 / 选择操作',{commands:this.commands()});}
-        catch(e){if(e.code!=='PROMPT_CANCELLED')throw e;try{if(await this.discard())break;}catch{}continue;}
+        try{text=await this.ui.input('fst > 输入 / 选择操作，@ 引用文件',{commands:this.commands()});}
+        catch(e){if(e.code!=='PROMPT_CANCELLED')throw e;try{if(await this.mayExit())break;}catch{}continue;}
         if(!text.trim())continue;
         try{await this.execute(text);}catch(e){this.ui.show(e.code==='PROMPT_CANCELLED'?'已返回，未完成的修改已放弃。':`操作失败：${e.message}`);}
       }
@@ -29,8 +40,27 @@ export class TerminalSession{
     if(pluginCommand)return this.pluginCommand(pluginCommand,args);
     if(command!=='run'&&args.length)throw new Error(`/${command} 使用交互选择，请不要附加参数`);
     switch(command){
-      case 'help':await this.ui.viewMarkdown('Fishtools 使用指南',`# 从这里开始\n\n${gettingStarted(await this.app.listWorkflows(),this.app.project)}\n\n## 文件与运行参数\n\n输入 @ 后按 Tab 选择文件。相对路径以 ${this.baseDir} 为起点。\n\n参数字段中 @文件 表示文件路径；运行命令中的 @参数.json 会读取 JSON 对象作为本次输入。\n\n例如：/run 工作流ID @"参数 文件.json"\n\n## 全部操作\n\n${this.commands().map(c=>`- /${c.name}：${c.description}`).join('\n')}`);return;
-      case 'exit':if(await this.discard())this.exiting=true;return;
+      case 'help':await this.ui.viewMarkdown('Fishtools 使用指南',[
+        '# Fishtools',
+        '将插件能力组合为工作流，在终端内编辑、运行并查看结果。',
+        `当前工作区：${this.app.projectDir}`,
+        `文件路径起点：${this.baseDir}`,
+        '## 常用操作',gettingStarted(await this.app.listWorkflows(),this.app.project),
+        '## 编排工作流','/new 新建 → /add 添加步骤 → /steps 编辑参数、条件与分组 → /save 保存 → /run 执行。',
+        '## 观察运行','/runs 打开观察面板。1 / 2 / 3 切换步骤总览、输入输出和日志，[ / ] 切换步骤。↑↓、PgUp/PgDn 或滚轮浏览；End 恢复尾部跟随。q / Esc 关闭后任务在后台继续，x 后 y 明确取消。',
+        '## 文件与运行参数','输入 @ 后按 Tab 选择文件；@@ 表示字面量 @。运行命令的 @参数.json 会读取 JSON 对象作为输入。',
+        '/run 工作流ID @"参数 文件.json"',
+        '## 离线文档','输入 /docs 阅读插件开发、部署、控制流与服务文档。独立命令 fst docs --path 查看资料位置，fst docs --export 目标目录 导出资料。',
+        '## 全部操作',this.commands().map(c=>`- /${c.name}：${c.description}`).join('\n'),
+      ].join('\n\n'));return;
+      case 'docs':{
+        const {listDocumentation,readDocumentation}=await import('../documentation.js');
+        const topics=await listDocumentation();
+        const topic=await this.ui.select('离线文档', [...topics.map(item=>({value:item.id,label:item.title})),{value:'back',label:'返回工作台'}]);
+        if(topic!=='back'){const document=await readDocumentation(topic);await this.ui.viewMarkdown(document.title,document.text);}
+        return;
+      }
+      case 'exit':if(await this.mayExit())this.exiting=true;return;
       case 'workflows':{
         const flows=await this.app.listWorkflows();
         if(!flows.length){this.ui.show('没有工作流，输入 /new 新建。');return;}
@@ -49,6 +79,7 @@ export class TerminalSession{
       case 'outputs':return this.outputs();
       case 'save':this.writable();await this.app.saveWorkflow(this.current());this.dirty=false;this.ui.show(`已保存：${this.flow.title}`);return;
       case 'run':return this.startRun(args);
+      case 'runs':return this.runs();
       case 'logs':return this.logs();
       case 'plugins':return this.plugins();
       case 'config':return this.configure();
@@ -80,7 +111,7 @@ export class TerminalSession{
     await this.app.configurePlugin(id,value);this.ui.show('插件配置已保存到当前工作区。');
   }
   async logs(){
-    const statuses={running:'运行中',succeeded:'成功',failed:'失败',cancelled:'已取消'};
+    const statuses=runStatuses;
     while(true){
       const history=await this.app.listRunHistory(),keep=this.app.logSettings().keepRuns;
       const choice=await this.ui.select(`运行日志 · ${keep===null?'不自动清理':`项目保留最近 ${keep} 次`}`,[
@@ -101,17 +132,67 @@ export class TerminalSession{
   }
   async add(){
     this.writable();const flow=structuredClone(this.current()),catalog=this.app.catalog(),workflows=await this.app.listWorkflows();
-    const choice=await this.ui.select('添加一个能力或子工作流',[
+    await this.addNode(flow,[],catalog,workflows);
+    this.flow=flow;this.dirty=true;this.ui.show('步骤已添加。/add 继续添加，/steps 调整，/save 保存。');
+  }
+  async addNode(flow,parent,catalog,workflows){
+    this.writable();
+    const choice=await this.ui.select('添加能力、子工作流或控制节点',[
       ...catalog.map(a=>({value:`action:${a.id}`,label:a.title??a.id,description:a.description})),
       ...workflows.filter(w=>w.id!==flow.id).map(w=>({value:`workflow:${w.id}`,label:`工作流：${w.title}`,description:w.description})),
+      {value:'control:branch',label:'条件分支'},{value:'control:parallel',label:'并行组'},{value:'control:stop',label:'提前结束'},
     ]);
-    const step={id:`step-${randomUUID().slice(0,8)}`,with:{}};
-    if(choice.startsWith('action:'))step.action=choice.slice(7);else step.workflow=`./${choice.slice(9)}.yaml`;
-    flow.steps.push(step);await this.editBindings(flow,flow.steps.length-1,catalog,workflows);
-    this.flow=flow;this.dirty=true;this.ui.show('步骤已添加。/add 继续添加，/steps 调整，/save 保存。');
+    const sequence=sequenceAt(flow,parent),step={id:`step-${randomUUID().slice(0,8)}`},index=[...parent,sequence.length];
+    sequence.push(step);
+    if(choice==='control:branch')step.branch={condition:await editCondition(this.ui,flow,index,catalog,workflows,{baseDir:this.baseDir}),then:[],else:[]};
+    else if(choice==='control:parallel')step.parallel={concurrency:4,steps:[]};
+    else if(choice==='control:stop')step.stop={reason:''};
+    else{step.with={};if(choice.startsWith('action:'))step.action=choice.slice(7);else step.workflow=`./${choice.slice(9)}.yaml`;}
+    await this.editNode(flow,index,catalog,workflows);
+  }
+  async editNode(flow,index,catalog,workflows){
+    this.writable();const step=stepAt(flow,index);
+    if(step.stop){step.stop.reason=await this.ui.input('提前结束原因',{value:step.stop.reason,files:false});return;}
+    if(step.parallel){
+      const value=Number(await this.ui.input('最大并发数（1–32）',{value:String(step.parallel.concurrency??4),files:false}));
+      if(!Number.isInteger(value)||value<1||value>32)throw new Error('并发数必须为 1–32 的整数');
+      step.parallel.concurrency=value;await this.editSequence(flow,[...index,'parallel','steps'],catalog,workflows);return;
+    }
+    if(step.branch){
+      step.branch.else??=[];
+      while(true){
+        const choice=await this.ui.select('条件分支', [{value:'condition',label:'修改判断条件'},{value:'then',label:`条件成立 · ${step.branch.then.length} 步`},{value:'else',label:`条件不成立 · ${step.branch.else.length} 步`},{value:'done',label:'完成分支编辑'}]);
+        if(choice==='done')return;
+        if(choice==='condition')step.branch.condition=await editCondition(this.ui,flow,index,catalog,workflows,{baseDir:this.baseDir,current:step.branch.condition});
+        else await this.editSequence(flow,[...index,'branch',choice],catalog,workflows);
+      }
+    }
+    return this.editBindings(flow,index,catalog,workflows);
+  }
+  async editSequence(flow,parent,catalog,workflows){
+    const sequence=sequenceAt(flow,parent);
+    while(true){
+      const choice=await this.ui.select('嵌套步骤', [...sequence.map((s,i)=>({value:`step:${i}`,label:`${i+1}. ${stepMetadata(s,catalog,workflows)?.title??s.id}`})),{value:'add',label:'添加步骤'},{value:'done',label:'完成此组'}]);
+      if(choice==='done')return;
+      if(choice==='add')await this.addNode(flow,parent,catalog,workflows);
+      else await this.stepOperation(flow,[...parent,Number(choice.slice(5))],catalog,workflows);
+    }
+  }
+  async stepOperation(flow,index,catalog,workflows){
+    this.writable();const step=stepAt(flow,index),parent=index.slice(0,-1),position=index.at(-1),sequence=sequenceAt(flow,parent);
+    const action=await this.ui.select('步骤操作',[{value:'edit',label:step.branch||step.parallel||step.stop?'编辑控制节点与嵌套步骤':'设置参数'},{value:'when',label:'设置执行条件'},...(step.when?[{value:'clear-when',label:'移除执行条件'}]:[]),...(position>0?[{value:'up',label:'上移一步'}]:[]),...(position<sequence.length-1?[{value:'down',label:'下移一步'}]:[]),{value:'remove',label:'删除此步骤'}]);
+    if(action==='edit')await this.editNode(flow,index,catalog,workflows);
+    else if(action==='when')step.when=await editCondition(this.ui,flow,index,catalog,workflows,{baseDir:this.baseDir,current:step.when});
+    else if(action==='clear-when')delete step.when;
+    else if(action==='remove'){
+      if(!await this.ui.confirm('删除此步骤？引用它的步骤或输出需要重新设置。'))return;
+      for(const key of Object.keys(step.with??{}))setBinding(flow,index,key,'fixed',{},undefined);
+      sequence.splice(position,1);
+      pruneRuntimeInputs(flow);
+    }else{const to=position+(action==='up'?-1:1);[sequence[position],sequence[to]]=[sequence[to],sequence[position]];}
   }
   async editBindings(flow,index,catalog,workflows){
-    const step=flow.steps[index],meta=stepMetadata(step,catalog,workflows);
+    const step=stepAt(flow,index),meta=stepMetadata(step,catalog,workflows);
     if(!meta)throw new Error('该步骤所需插件或子工作流不可用');
     if(needsJsonEditor(meta.input)||!meta.input?.properties){
       step.with=await editValue(this.ui,meta.input??{type:'object'},step.with,{baseDir:this.baseDir,required:true,label:`${meta.title} · 完整参数 JSON`});return;
@@ -144,13 +225,7 @@ export class TerminalSession{
     const id=await this.ui.select('选择步骤',flow.steps.map((s,i)=>({value:s.id,label:`${i+1}. ${stepMetadata(s,catalog,workflows)?.title??s.id}`,description:JSON.stringify(s.with)})));
     const index=flow.steps.findIndex(s=>s.id===id);
     if(this.app.project.readOnly){this.ui.show(JSON.stringify(flow.steps[index],null,2));return;}
-    const action=await this.ui.select('步骤操作',[{value:'edit',label:'设置参数'},...(index>0?[{value:'up',label:'上移一步'}]:[]),...(index<flow.steps.length-1?[{value:'down',label:'下移一步'}]:[]),{value:'remove',label:'删除此步骤'}]);
-    if(action==='edit')await this.editBindings(flow,index,catalog,workflows);
-    else if(action==='remove'){
-      if(!await this.ui.confirm('删除此步骤？引用它的步骤或输出需要重新设置。'))return;
-      for(const key of Object.keys(flow.steps[index].with??{}))setBinding(flow,index,key,'fixed',{},undefined);
-      flow.steps.splice(index,1);
-    }else{const to=index+(action==='up'?-1:1);[flow.steps[index],flow.steps[to]]=[flow.steps[to],flow.steps[index]];}
+    await this.stepOperation(flow,[index],catalog,workflows);
     this.flow=flow;this.dirty=true;this.ui.show('步骤已更新，保存前可继续调整。');
   }
   async outputs(){
@@ -179,15 +254,27 @@ export class TerminalSession{
     await this.app.checkWorkflow(flow.id);
     const input=reference?await readRunInput(reference,this.baseDir):(needsJsonEditor(flow.inputs)||Object.keys(flow.inputs?.properties??{}).length)?await editValue(this.ui,flow.inputs,{}, {baseDir:this.baseDir,label:'本次运行参数',required:true}):{};
     const run=await this.app.startRun(flow.id,input);
+    if(this.ui.observeRun){
+      await this.ui.observeRun({app:this.app,runId:run.id,flow,workflows:await this.app.listWorkflows()});
+      this.ui.show(`已关闭运行观察面板。输入 /runs 重新查看，/logs 查看历史日志。`);return;
+    }
     const unsubscribe=this.app.subscribe(e=>{if(e.runId===run.id&&e.type.startsWith('step.'))this.ui.show(`${e.type} · ${e.callPath}${e.message?' · '+e.message:''}`);});
     const done=this.ui.busy('运行中 · Ctrl+C 取消当前运行',()=>this.app.cancelRun(run.id));
     try{
       const result=await run.done;
-      this.ui.show(`运行${result.status==='succeeded'?'成功':result.status==='cancelled'?'已取消':'失败'}\n${JSON.stringify(result.status==='succeeded'?result.output:result.error,null,2)}`);
+      this.ui.show(`运行${runStatuses[result.status]??result.status}\n${JSON.stringify(result.reason??(result.status==='succeeded'?result.output:result.error),null,2)}`);
       if(result.status==='succeeded'&&!Object.keys(result.output??{}).length)this.ui.show(JSON.stringify(result.events.filter(e=>e.type==='step.succeeded').map(e=>({step:e.callPath,output:e.output})),null,2));
       this.ui.show(`输入 /logs 在终端内查看日志\n可读日志：${path.join(this.app.outputDir,run.id,'run.md')}\n结果目录：${path.join(this.app.outputDir,run.id)}`);
     }finally{unsubscribe();done();}
   }
+  async runs(){
+    const runs=this.app.listRuns();
+    if(!runs.length){this.ui.show('当前会话还没有运行。/run 执行工作流，/logs 查看历史记录。');return;}
+    const id=await this.ui.select('运行观察 · 关闭面板后后台继续', [...runs.slice().reverse().map(run=>({value:run.id,label:`${runStatuses[run.status]??run.status} · ${run.workflowId}`,description:run.id})),{value:'back',label:'返回工作台'}]);
+    if(id==='back')return;
+    const workflows=await this.app.listWorkflows(),record=this.app.getRun(id);
+    await this.ui.observeRun({app:this.app,runId:id,flow:workflows.find(flow=>flow.id===record.workflowId),workflows});
+  }
   async plugins(){
     this.ui.clearMessages?.();
     while(true){

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

@@ -0,0 +1,28 @@
+import {stripVTControlCharacters} from 'node:util';
+import {truncateToWidth,visibleWidth} from '@mariozechner/pi-tui';
+
+// 先清理外部文本，再由受控主题函数添加颜色；不接受插件传入的 ANSI。
+export const cleanText=value=>stripVTControlCharacters(String(value)).replace(/[\x00-\x08\x0b-\x1f\x7f]/g,'');
+const color=(rgb,text)=>Object.hasOwn(process.env,'NO_COLOR')?text:`\x1b[38;2;${rgb}m${text}\x1b[39m`;
+export const palette={
+  brand:text=>color('78;201;176',text),
+  text:text=>color('229;233;237',text),
+  muted:text=>color('139;149;158',text),
+  border:text=>color('74;101;99',text),
+};
+export const menuTheme={selectedPrefix:palette.brand,selectedText:palette.brand,description:palette.muted,scrollInfo:palette.muted,noMatch:palette.muted};
+export const fitLine=(text,width)=>truncateToWidth(text,Math.max(1,width),'…');
+
+export function shortenPath(value,width){
+  if(visibleWidth(value)<=width)return value;
+  // 中间省略保留盘符与项目名；完整目录仍在帮助页中展示。
+  const chars=[...value],head=chars.splice(0,Math.min(3,Math.max(0,width-2))).join('');
+  while(chars.length&&visibleWidth(head+'…'+chars.join(''))>width)chars.shift();
+  return fitLine(head+'…'+chars.join(''),width);
+}
+
+export function markdownTheme(){
+  const plain=text=>text;
+  return {heading:palette.brand,link:palette.brand,linkUrl:palette.muted,code:palette.brand,codeBlock:plain,codeBlockBorder:palette.border,quote:plain,quoteBorder:palette.border,hr:palette.border,listBullet:palette.brand,
+    bold:palette.text,italic:plain,strikethrough:plain,underline:plain};
+}

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

@@ -1,15 +1,14 @@
 import { readdirSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { homedir } from 'node:os';
-import { stripVTControlCharacters } from 'node:util';
-import { TUI, Text, Container, Editor, SelectList, ProcessTerminal, CombinedAutocompleteProvider, matchesKey, truncateToWidth } from '@mariozechner/pi-tui';
+import { TUI, Text, Container, Editor, SelectList, ProcessTerminal, CombinedAutocompleteProvider, matchesKey, truncateToWidth, visibleWidth } from '@mariozechner/pi-tui';
 import { MarkdownLogViewer } from './log-viewer.js';
+import { RunViewer, mouseOn, mouseOff } from './run-viewer.js';
 import { logo } from './presentation.js';
 import { VERSION } from '../version.js';
+import {cleanText as safe,palette,menuTheme as theme,fitLine,shortenPath} from './theme.js';
 
 export const cancelled=()=>Object.assign(new Error('已返回主菜单'),{code:'PROMPT_CANCELLED'});
-const safe=value=>stripVTControlCharacters(String(value)).replace(/[\x00-\x08\x0b-\x1f\x7f]/g,'');
-const theme={selectedPrefix:s=>`\x1b[36m${s}\x1b[0m`,selectedText:s=>`\x1b[36m${s}\x1b[0m`,description:s=>s,scrollInfo:s=>s,noMatch:s=>s};
 // 上游菜单按字符数分配描述宽度，中文双宽字符需要再按终端列宽收口。
 function fit(component){const render=component.render.bind(component);component.render=width=>render(width).map(line=>truncateToWidth(line,width));return component;}
 
@@ -48,28 +47,41 @@ export class TerminalView{
     this.baseDir=baseDir;this.terminal=terminal;this.tui=new TUI(terminal);this.logs=[];
     const originalStart=terminal.start.bind(terminal);
     terminal.start=(input,resize)=>originalStart(data=>{
-      if(matchesKey(data,'ctrl+c')){if(this.cancelRun)this.cancelRun();this.pending?.reject(cancelled());return;}
-      if(matchesKey(data,'escape')&&this.pending&&!this.logViewer){
+      if(matchesKey(data,'ctrl+c')){if(this.runViewer){this.runViewer.onClose();return;}if(this.cancelRun)this.cancelRun();this.pending?.reject(cancelled());return;}
+      if(matchesKey(data,'escape')&&this.pending&&!this.logViewer&&!this.runViewer){
         // 编辑器自己处理补全菜单 Escape，第二次 Escape 返回上一级。
         if(this.editor?.isShowingAutocomplete?.()){input(data);return;}
         this.pending.reject(cancelled());return;
       }
       input(data);
     },resize);
-    this.header=new Text('',1,1);this.transcript=new Text('',1,0);this.prompt=new Container();this.hint=new Text('↑↓ 选择 · Enter 确认 · Tab 补全 · Esc 返回 · Ctrl+C 取消/退出',1,1);
+    this.header=new Text('',1,0);this.transcript=new Text('',1,0);this.prompt=new Container();this.hint=new Text('',1,0);
+    this.hint.render=width=>['',fitLine(' '+palette.muted(width<45?'↑↓ 选择  Enter 确认  Esc 返回':'↑↓ 选择   Enter 确认   Tab 补全   Esc 返回   Ctrl+C 退出'),width)];
     const renderTranscript=this.transcript.render.bind(this.transcript);
-    this.headingLines=(width,mark='FISHtools')=>new Text(`${mark}  v${VERSION}\n${this.summaryText??''}`,1,1).render(width).map(line=>truncateToWidth(line,width));
-    // 根据整屏换行后的行数选择标题，而不是只判断终端宽度。
+    this.headingLines=(width,mark='FISHtools')=>{
+      const room=Math.max(1,width-2),lines=[''];
+      if(mark===logo){
+        lines.push(...logo.split('\n').map((line,i)=>' '+palette.brand(line)+(i===2?' '+palette.text('tools')+'  '+palette.muted(`v${VERSION}`):'')));
+      }else lines.push(' '+palette.brand('FISH')+palette.text('tools')+'  '+palette.muted(`v${VERSION}`));
+      for(const [i,line] of (this.summaryText??'').split('\n').entries()){
+        if(line.startsWith('当前工作区：')){
+          const label='当前工作区：',folder=shortenPath(line.slice(label.length),Math.max(1,room-visibleWidth(label)));
+          lines.push(' '+palette.muted(label)+palette.text(folder));
+        }else lines.push(' '+(i===0?palette.text:palette.muted)(fitLine(line,room)));
+      }
+      lines.push('');return lines.map(line=>fitLine(line,width));
+    };
+    // 先保证输入与菜单可见，空间充足才展示三行字标。
     this.header.render=width=>{
       const full=this.headingLines(width,logo),other=renderTranscript(width).length+this.prompt.render(width).length+this.hint.render(width).length;
-      return width>=52&&full.length+other<=this.terminal.rows?full:this.headingLines(width);
+      return width>=34&&this.terminal.rows>=18&&full.length+other<=this.terminal.rows?full:this.headingLines(width);
     };
     this.transcript.render=width=>{
       const lines=renderTranscript(width),budget=Math.max(0,this.terminal.rows-this.header.render(width).length-this.prompt.render(width).length-this.hint.render(width).length);
       if(lines.length<=budget)return lines;
       if(!budget)return [];
       const excerpt=this.logs.length<=1?lines.slice(0,budget-1):lines.slice(-(budget-1)||lines.length);
-      return [...excerpt,truncateToWidth(' … /help 查看用法 · /logs 查看运行结果',width)];
+      return [...excerpt,fitLine(' '+palette.muted('… /help 完整帮助 · /logs 运行日志'),width)];
     };
     this.tui.addChild(this.header);this.tui.addChild(this.transcript);this.tui.addChild(this.prompt);this.tui.addChild(this.hint);
   }
@@ -81,7 +93,11 @@ export class TerminalView{
   }
   summary(text){this.summaryText=safe(text);this.tui.requestRender();}
   clearMessages(){this.logs=[];this.transcript.setText('');this.tui.requestRender();}
-  show(message){this.logs.push(safe(message).slice(0,6000));this.logs=this.logs.slice(-6);this.transcript.setText(this.logs.join('\n\n'));this.tui.requestRender();}
+  show(message,{kind='message'}={}){
+    const text=safe(message).slice(0,6000);
+    const formatted=kind==='welcome'?text.split('\n').map((line,i)=>i===0?palette.text(line):palette.muted(line)).join('\n'):text;
+    this.logs.push(formatted);this.logs=this.logs.slice(-6);this.transcript.setText(this.logs.join('\n\n'));this.tui.requestRender();
+  }
   async viewMarkdown(title,text){
     const previousPending=this.pending??null,previousViewer=this.logViewer;
     const children=this.tui.children;
@@ -90,6 +106,7 @@ export class TerminalView{
       await new Promise((resolve,reject)=>{
         this.pending={resolve,reject};
         this.logViewer=new MarkdownLogViewer({title:safe(title),text:safe(text),terminal:this.terminal,onClose:resolve,requestRender:()=>this.tui.requestRender()});
+        this.terminal.write(mouseOn);
         // Overlay 的基底为空，旧 transcript 不再撑高滚动区域；关闭后原样恢复。
         this.tui.children=[];
         overlay=this.tui.showOverlay(this.logViewer,{width:'100%',maxHeight:'100%',anchor:'top-left',margin:0});
@@ -98,34 +115,72 @@ export class TerminalView{
     }finally{
       this.tui.children=children;this.pending=previousPending;this.logViewer=previousViewer;
       overlay?.hide();this.tui.requestRender(true);
+      this.terminal.write(mouseOff);
+    }
+  }
+  async observeRun({app,runId,flow,workflows=[]}){
+    const previousPending=this.pending??null,children=this.tui.children;let overlay,unsubscribe;
+    try{
+      await new Promise((resolve,reject)=>{
+        this.pending={resolve,reject};
+        this.runViewer=new RunViewer({record:app.getRun(runId),flow,workflows,terminal:this.terminal,onClose:resolve,onCancel:()=>app.cancelRun(runId),requestRender:()=>this.tui.requestRender()});
+        unsubscribe=app.subscribe(event=>{if(event.runId===runId)this.runViewer?.update(app.getRun(runId));});
+        this.tui.children=[];this.terminal.write(mouseOn);
+        overlay=this.tui.showOverlay(this.runViewer,{width:'100%',maxHeight:'100%',anchor:'top-left',margin:0});this.tui.requestRender(true);
+      });
+    }finally{
+      unsubscribe?.();this.runViewer=null;this.tui.children=children;this.pending=previousPending;overlay?.hide();this.terminal.write(mouseOff);this.tui.requestRender(true);
     }
   }
   async ask(message,component){
     fit(component);
-    this.prompt.clear();this.prompt.addChild(new Text(safe(message),1,1));this.prompt.addChild(component);this.tui.setFocus(component);this.tui.requestRender();
+    const title=new Text(palette.text(safe(message)),1,0);
+    if(message.startsWith('fst >'))title.render=width=>[fitLine(' '+palette.text(width<45?'fst > / 选择操作 · @ 文件':safe(message)),width)];
+    this.prompt.clear();this.prompt.addChild(title);this.prompt.addChild(component);this.tui.setFocus(component);this.tui.requestRender();
     try{return await new Promise((resolve,reject)=>{this.pending={resolve,reject};component.onSubmit=resolve;component.onSelect=item=>resolve(item.value);component.onCancel=()=>reject(cancelled());});}
     finally{this.pending=null;this.editor=null;this.prompt.clear();this.tui.requestRender();}
   }
   input(message,{value='',commands=[],files=true}={}){
-    const editor=new Editor(this.tui,{borderColor:theme.selectedPrefix,selectList:theme},{paddingX:1});
+    const editor=new Editor(this.tui,{borderColor:palette.border,selectList:theme},{paddingX:1});
+    const renderEditor=editor.render.bind(editor);
+    editor.render=width=>{
+      if(width<8)return renderEditor(width);
+      const inner=width-4,lines=renderEditor(inner);let closed=false;
+      return lines.map((line,i)=>{
+        if(i===0)return ' '+palette.border('╭'+'─'.repeat(inner)+'╮');
+        if(!closed&&/^─+$/.test(safe(line))){closed=true;return ' '+palette.border('╰'+'─'.repeat(inner)+'╯');}
+        if(closed)return '  '+line;
+        return ' '+palette.border('│')+line+' '.repeat(Math.max(0,inner-visibleWidth(line)))+palette.border('│');
+      });
+    };
     this.editor=editor;editor.setText(value);
     if(files||commands.length)editor.setAutocompleteProvider(new FileAutocomplete(commands,this.baseDir));
     return this.ask(message,editor);
   }
   select(message,items){
     if(!items.length)throw new Error('当前没有可选择的项目');
-    const list=new SelectList(items.map(i=>({...i,label:safe(i.label),description:i.description?safe(i.description):undefined})),8,theme);
-    const render=list.render.bind(list);
+    const list=new SelectList(items.map(i=>({...i,label:safe(i.label).replace(/\s+/g,' '),description:i.description?safe(i.description).replace(/\s+/g,' '):undefined})),8,theme);
     list.render=width=>{
-      const reserved=this.headingLines(width).length+new Text(safe(message),1,1).render(width).length+this.hint.render(width).length+1;
+      const reserved=this.headingLines(width).length+new Text(palette.text(safe(message)),1,0).render(width).length+this.hint.render(width).length+1;
       list.maxVisible=Math.max(1,Math.min(8,this.terminal.rows-reserved));
-      return render(width);
+      const start=Math.max(0,Math.min(list.selectedIndex-Math.floor(list.maxVisible/2),list.filteredItems.length-list.maxVisible));
+      const end=Math.min(start+list.maxVisible,list.filteredItems.length),lines=[];
+      for(let i=start;i<end;i++){
+        const item=list.filteredItems[i],selected=i===list.selectedIndex,available=Math.max(1,width-4);
+        const labelWidth=item.description&&width>=56?Math.min(32,Math.floor(available*0.45)):available;
+        const label=fitLine(item.label||item.value,labelWidth),prefix=selected?'› ':'  ';
+        let line=' '+(selected?palette.brand(prefix+label):palette.text(prefix+label));
+        if(item.description&&width>=56)line+=' '.repeat(Math.max(2,labelWidth-visibleWidth(label)+2))+palette.muted(fitLine(item.description,Math.max(1,available-labelWidth-2)));
+        lines.push(fitLine(line,width));
+      }
+      if(start>0||end<list.filteredItems.length)lines.push(palette.muted(`   ${list.selectedIndex+1} / ${list.filteredItems.length}`));
+      return lines.length?lines:[palette.muted('  没有匹配项')];
     };
     return this.ask(message,list);
   }
   async confirm(message){return await this.select(message,[{value:'no',label:'否，返回'},{value:'yes',label:'是，继续'}])==='yes';}
   busy(message,cancel){
-    this.cancelRun=cancel;this.prompt.clear();this.prompt.addChild(new Text(safe(message),1,1));this.tui.setFocus(this.prompt);this.tui.requestRender();
+    this.cancelRun=cancel;this.prompt.clear();this.prompt.addChild(new Text(palette.text(safe(message)),1,0));this.tui.setFocus(this.prompt);this.tui.requestRender();
     return ()=>{this.cancelRun=null;this.prompt.clear();this.tui.requestRender();};
   }
 }

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

@@ -3,12 +3,23 @@ import { FlowError } from '@mytools/sdk';
 
 const ajv = new Ajv({ allErrors: true, strict: false, useDefaults: true });
 const validators = new WeakMap();
+const booleanValidators = new Map();
 export const emptyObject = { type: 'object', properties: {}, additionalProperties: false };
 
+export function assertSchema(schema,label) {
+  if (!(typeof schema==='boolean'||schema&&typeof schema==='object'&&!Array.isArray(schema))) throw new FlowError(`${label} 必须声明有效的 JSON Schema`,{code:'VALIDATION'});
+  const cache=typeof schema==='boolean'?booleanValidators:validators;
+  let check=cache.get(schema);
+  if(!check){
+    try{check=ajv.compile(schema);cache.set(schema,check);}
+    catch(cause){throw new FlowError(`${label} JSON Schema 无效：${cause.message}`,{code:'VALIDATION',cause});}
+  }
+  return check;
+}
+
 export function validate(schema, value, label) {
-  if (!schema) return structuredClone(value);
-  let check = validators.get(schema);
-  if (!check) { check = ajv.compile(schema); validators.set(schema, check); }
+  if (schema==null) return structuredClone(value);
+  const check = assertSchema(schema,label);
   const copy = structuredClone(value);
   if (!check(copy)) throw new FlowError(`${label}: ${ajv.errorsText(check.errors, { separator: '；' })}`, { code: 'VALIDATION', details: check.errors });
   return copy;
@@ -42,7 +53,7 @@ export function bind(value, context) {
   if (Object.hasOwn(value, '$ref')) {
     let current = context;
     for (const field of referenceParts(value.$ref)) {
-      if (current == null || !Object.hasOwn(current, field)) throw new FlowError(`引用的值不存在：${value.$ref}`);
+      if (current == null || !Object.hasOwn(current, field)) throw new FlowError(`引用的值不存在：${value.$ref}`,{code:'MISSING_REFERENCE'});
       current = current[field];
     }
     return structuredClone(current);

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

@@ -1,2 +1,2 @@
 // 由 npm version 的生命周期脚本同步，内部插件 API 版本独立维护。
-export const VERSION="0.1.4";
+export const VERSION="0.2.0";