@yanglaofish/fishtools 0.3.0 → 0.5.0

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

@@ -0,0 +1,49 @@
+{
+  "name": "@mytools/fst-cli",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/terminal/session.js",
+  "exports": {
+    ".": "./src/terminal/session.js",
+    "./entry": "./bin/fst.js",
+    "./run": "./src/cli-run.js",
+    "./terminal/conditions": "./src/terminal/conditions.js",
+    "./terminal/log-viewer": "./src/terminal/log-viewer.js",
+    "./terminal/model": "./src/terminal/model.js",
+    "./terminal/navigation": "./src/terminal/navigation.js",
+    "./terminal/presentation": "./src/terminal/presentation.js",
+    "./terminal/run-feed": "./src/terminal/run-feed.js",
+    "./terminal/run-presentation": "./src/terminal/run-presentation.js",
+    "./terminal/run-viewer": "./src/terminal/run-viewer.js",
+    "./terminal/schema": "./src/terminal/schema.js",
+    "./terminal/session": "./src/terminal/session.js",
+    "./terminal/theme": "./src/terminal/theme.js",
+    "./terminal/view": "./src/terminal/view.js",
+    "./terminal/workflow-menu": "./src/terminal/workflow-menu.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "dependencies": {
+    "@mytools/sdk": "0.1.0",
+    "@mytools/core": "0.1.0",
+    "@mytools/fst-workspace": "0.1.0",
+    "@mytools/fst-platform": "0.1.0",
+    "@mytools/fst-plugin": "0.1.0",
+    "@mytools/fst-devtools": "0.1.0",
+    "@mariozechner/pi-tui": "0.50.0",
+    "commander": "14.0.3"
+  },
+  "bin": {
+    "fst": "bin/fst.js"
+  }
+}

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

@@ -0,0 +1,12 @@
+// 工作流与插件命令共享取消及落盘收尾。
+export async function waitForCliRun(app,run,signals=process){
+  const cancel=()=>app.cancelRun(run.id);signals.once('SIGINT',cancel);
+  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/fst-cli/src/development.js

@@ -0,0 +1,53 @@
+import {randomBytes} from 'node:crypto';
+import {createDevelopmentSupervisor,bindDevelopmentChild} from '@mytools/core/development';
+
+export async function startDevelopment({projectDir,entry,args,configFile,mode,port}){
+  console.error('开发模式：源码变化后等待当前业务结束并重启；终端未保存的编辑草稿不会保留。');
+  const supervisor=await createDevelopmentSupervisor({projectDir,entry,args,configFile,
+    env:{FISHTOOLS_DEV_PROJECT:projectDir,FISHTOOLS_DEV_MODE:mode,FISHTOOLS_DEV_TOKEN:randomBytes(24).toString('hex'),FISHTOOLS_DEV_PORT:String(port)},
+    onEvent(event){
+      if(event.type==='ready')console.error(event.recovered?'开发应用已恢复，源码监听继续。':`开发应用已就绪（第 ${event.generation} 代）。`);
+      else if(event.type==='waiting')console.error('开发源码已修改，等待当前运行及管理操作结束。');
+      else if(event.type==='restarting')console.error('开发应用准备重启。');
+      else if(event.type==='failed')console.error(`开发应用启动失败：${event.message}；修复源码后自动重试。`);
+      else if(['forced','blocked','watchError'].includes(event.type))console.error(`开发模式：${event.message}`);
+      if(event.type==='exited'&&mode==='terminal'&&process.stdout.isTTY){
+        process.stdin.setRawMode?.(false);process.stdout.write('\x1b[?1006l\x1b[?1000l\x1b[?25h\x1b[?1049l');
+      }
+    }});
+  const stop=()=>{void supervisor.close().catch(error=>{console.error(error.message);process.exitCode=2;}).finally(()=>{
+    process.removeListener('SIGINT',stop);process.removeListener('SIGTERM',stop);
+    // 子进程被强制回收时，监督器恢复终端的常用状态。
+    if(mode==='terminal'&&process.stdout.isTTY)process.stdout.write('\x1b[?1006l\x1b[?1000l\x1b[?25h\x1b[?1049l');
+  });};
+  process.once('SIGINT',stop);process.once('SIGTERM',stop);
+  return supervisor;
+}
+
+export async function runDevelopmentChild(app,{mode,webOptions}){
+  const web={...webOptions,port:Number(process.env.FISHTOOLS_DEV_PORT??webOptions.port),token:process.env.FISHTOOLS_DEV_TOKEN};
+  let binding;
+  const stop=()=>{void binding?.close();};
+  if(mode==='web'){
+    const server=await app.startWeb(web);console.log(`Fishtools：${server.url}`);
+    binding=bindDevelopmentChild(app,{details:{port:server.port},closePresentation:()=>{
+      process.removeListener('SIGINT',stop);process.removeListener('SIGTERM',stop);
+    }});
+    process.on('SIGINT',stop);process.on('SIGTERM',stop);return;
+  }
+  const [{TerminalView},{TerminalSession}]=await Promise.all([import('./terminal/view.js'),import('./terminal/session.js')]);
+  const ui=new TerminalView({baseDir:process.cwd()}),session=new TerminalSession(app,ui,{webOptions:web});
+  let presentation;
+  try{
+    ui.start();presentation=session.run();
+    binding=bindDevelopmentChild(app,{closePresentation:async()=>{
+      // 监督器已经确认业务空闲；开发重启直接结束草稿和 pending 提示。
+      session.exiting=true;session.dirty=false;
+      ui.pending?.reject(Object.assign(new Error('开发应用重启'),{code:'PROMPT_CANCELLED'}));
+      await presentation;
+      await ui.close();process.removeListener('SIGINT',stop);process.removeListener('SIGTERM',stop);
+    }});
+    process.on('SIGINT',stop);process.on('SIGTERM',stop);
+    await presentation;
+  }finally{await ui.close();await binding?.close();}
+}

package/node_modules/@mytools/fst-cli/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/fst-cli/src/terminal/log-viewer.js

@@ -0,0 +1,45 @@
+import { Markdown, matchesKey, truncateToWidth } from '@mariozechner/pi-tui';
+import { mouseWheel } from './run-viewer.js';
+import {palette,markdownTheme} from './theme.js';
+
+const theme=markdownTheme();
+
+// 文本已由 TerminalView 的 safe 清理；每次只向 Overlay 提交当前窗口内的行。
+export class MarkdownLogViewer{
+  constructor({title,text,terminal,onClose,requestRender}){
+    this.title=title.replace(/\s+/g,' ');this.terminal=terminal;this.onClose=onClose;this.requestRender=requestRender;
+    this.markdown=new Markdown(text,0,0,theme);this.offset=0;
+  }
+  invalidate(){this.markdown.invalidate();}
+  layout(width){
+    const height=Math.max(1,this.terminal.rows);
+    const pageSize=Math.max(1,height-2);
+    // Markdown 自身缓存同一宽度的完整渲染，滚动时不重新解析日志。
+    const lines=this.markdown.render(Math.max(1,width));
+    const maxOffset=Math.max(0,lines.length-pageSize);
+    this.offset=Math.min(maxOffset,Math.max(0,this.offset));
+    return {height,pageSize,lines,maxOffset};
+  }
+  render(width){
+    const {height,pageSize,lines}=this.layout(width);
+    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=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(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;
+    else if(matchesKey(data,'home'))this.offset=0;
+    else if(matchesKey(data,'end'))this.offset=maxOffset;
+    else return;
+    this.offset=Math.min(maxOffset,Math.max(0,this.offset));this.requestRender();
+  }
+}

package/node_modules/@mytools/fst-cli/src/terminal/model.js

@@ -0,0 +1,104 @@
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { readFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+
+export {builtinCommands as commands} from '@mytools/fst-plugin/contracts';
+
+export function parseCommand(text){
+  const args=[];let token='',quote='',started=false;
+  for(const char of text.trim()){
+    if(quote){if(char===quote)quote='';else token+=char;started=true;}
+    else if(char==='"'||char==="'"){quote=char;started=true;}
+    else if(/\s/.test(char)){if(started){args.push(token);token='';started=false;}}
+    else{token+=char;started=true;}
+  }
+  if(quote)throw new Error('文件路径的引号未闭合');
+  if(started)args.push(token);
+  if(!args[0]?.startsWith('/'))throw Object.assign(new Error('这不是斜杠命令。输入 / 选择操作；执行工作流请用 /run 工作流ID。'),{code:'COMMAND_INPUT'});
+  args[0]=args[0].slice(1);return args;
+}
+
+export function fileReference(text,baseDir){
+  if(text.startsWith('@@'))return text.slice(1);
+  if(!text.startsWith('@'))return text;
+  let file=text.slice(1).trim();
+  if((file.startsWith('"')&&file.endsWith('"'))||(file.startsWith("'")&&file.endsWith("'")))file=file.slice(1,-1);
+  if(!file)throw new Error('@ 后请选择文件路径');
+  if(file==='~')file=homedir();else if(file.startsWith('~/')||file.startsWith('~\\'))file=path.join(homedir(),file.slice(2));
+  return path.resolve(baseDir,file);
+}
+
+export async function readRunInput(reference,baseDir){
+  if(!reference.startsWith('@')||reference.startsWith('@@'))throw new Error('运行参数文件需要使用 @路径.json');
+  const value=JSON.parse(await readFile(fileReference(reference,baseDir),'utf8'));
+  if(!value||typeof value!=='object'||Array.isArray(value))throw new Error('运行参数文件必须是 JSON 对象');
+  return value;
+}
+
+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=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}`;
+    flow.inputs.properties[name]={...schema,title:schema.title??key};
+    flow.inputs.required=[...new Set([...(flow.inputs.required??[]),name])];
+    step.with[key]={$ref:`inputs.${name}`};
+  }else if(mode==='fixed'){
+    if(value===undefined)delete step.with[key];else step.with[key]=value;
+  }else step.with[key]={$ref:mode};
+  if(old?.$ref?.startsWith('inputs.fst_')){
+    const refs=[];
+    const scan=v=>{if(v&&typeof v==='object'){if(typeof v.$ref==='string')refs.push(v.$ref);for(const child of Object.values(v))scan(child);}};
+    scan(flow.steps);scan(flow.outputs);
+    if(!refs.includes(old.$ref)){
+      const name=old.$ref.slice('inputs.'.length);delete flow.inputs.properties[name];
+      flow.inputs.required=(flow.inputs.required??[]).filter(k=>k!==name);
+    }
+  }
+}
+
+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?.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 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/fst-cli/src/terminal/navigation.js

@@ -0,0 +1,17 @@
+import {builtinCommands} from '@mytools/fst-plugin/contracts';
+
+const visible=['workflows','run','pack','logs','plugin','config','tools','help','exit'];
+// 入口由插件 ID 推导；冲突时加前缀，不能覆盖内置或作者注册的命令。
+export function commandMenu(plugins,commands){
+  const entries=builtinCommands.filter(command=>visible.includes(command.name)).map(command=>({...command,description:`[内置] ${command.description}`}));
+  const used=new Set([...builtinCommands.map(c=>c.name),...commands.map(c=>c.name)]);
+  const groups=plugins.filter(plugin=>commands.some(c=>c.plugin===plugin.id)).sort((a,b)=>a.id.localeCompare(b.id));
+  for(const plugin of groups){
+    const leaf=plugin.id.split('/').at(-1).replace(/[^\w.-]/g,'-');
+    let name=/^[a-zA-Z]/.test(leaf)?leaf:`plugin-${leaf}`;
+    if(groups.filter(p=>p.id.split('/').at(-1)===leaf).length>1)name=plugin.id.replace(/^@/,'').replace(/[^\w.-]/g,'-');
+    while(used.has(name))name='plugin-'+name;
+    used.add(name);entries.push({name,plugin:plugin.id,description:`[插件] ${plugin.title??plugin.id} · ${plugin.id}`});
+  }
+  return entries;
+}

package/node_modules/@mytools/fst-cli/src/terminal/presentation.js

@@ -0,0 +1,50 @@
+export const logo=[
+  '█▀▀ ▀█▀ █▀▀ █ █',
+  '█▀   █  ▀▀█ █▀█',
+  '▀   ▀▀▀ ▀▀▀ ▀ ▀',
+].join('\n');
+
+export const pluginStatus=plugin=>({ready:'可用',pending:'等待服务',failed:'失败',stopped:'已停止'})[plugin.runtime?.status]??'未知';
+
+export function gettingStarted(flows,{readOnly=false}={}){
+  const sample=flows.find(w=>w.id==='hello')??flows[0];
+  return [
+    sample?`试运行  /run ${sample.id}\n${sample.description??sample.title??'按提示填写参数，执行后查看结果。'}`:'当前工作区还没有工作流。',
+    '',
+    `/workflows ${readOnly?'浏览工作流':'管理工作流'}   /plugin 插件   /config 工具配置`,
+    `/logs 回看执行记录、输入输出与日志   /help 帮助`,
+  ].join('\n');
+}
+
+function fields(schema){
+  if(!schema)return '未声明';
+  if(!schema.properties)return `类型：${schema.type??'由插件约束定义'}`;
+  const entries=Object.entries(schema.properties);
+  return entries.length?entries.map(([key,s])=>`${s.title??key} (${key}, ${s.type??'任意类型'}${schema.required?.includes(key)?', 必填':''})${s.description?`：${s.description}`:''}`).join('；'):'无';
+}
+
+function privilege(item,plugin){
+  const declaration=item.requirements?.privilege?.[process.platform]??plugin.requirements?.privilege?.[process.platform];
+  if(!declaration)return '未声明';
+  const names={user:'普通用户',root:'root',administrator:'管理员',resource:'特定资源权限'};
+  return `${names[declaration.level]??declaration.level}${declaration.reason?`；原因：${declaration.reason}`:''}${declaration.remediation?`；处理：${declaration.remediation}`:''}`;
+}
+
+export function pluginDetails(plugin,actions,commands){
+  return [
+    `# ${plugin.title??plugin.id}`,
+    plugin.description??'作者尚未提供用途说明。',
+    `标识：${plugin.id}\n\n版本：${plugin.version}\n\n来源：${plugin.removable?'自行安装（可移除）':'发行包内置 / 项目预置'}\n\n状态：${pluginStatus(plugin)}`,
+    ...(plugin.runtime?.missing?.length?[`缺少服务：${plugin.runtime.missing.join(', ')}`]:[]),
+    `更新方式：${!plugin.runtime?.updatePolicy?'无运行时服务':plugin.runtime.updatePolicy==='automatic'?'可自动短暂停止并重启':'需要本次维护确认'}\n\n插件权限：${privilege(plugin,plugin)}`,
+    `声明平台：${plugin.platforms?.join(', ')??'作者未声明'}\n\n声明架构：${plugin.architectures?.join(', ')??'作者未声明'}`,
+    '## 可用于编排的能力',
+    ...(actions.length?actions.map(a=>`### ${a.title??a.id}\n\n${a.description??''}\n\n能力 ID：${a.id}\n\n输入：${fields(a.input)}\n\n输出：${fields(a.output)}\n\n权限：${privilege(a,plugin)}`):['此插件没有提供编排动作，可能提供 Web、共享服务或交互命令。']),
+    '## 斜杠命令',commands.length?commands.map(c=>`- /${c.name}：${c.description??'未提供说明'}`).join('\n'):'没有注册斜杠命令。',
+    '## 插件配置',plugin.config?fields(plugin.config):'无需配置。',
+    '## 环境声明',
+    ...[plugin,...actions].flatMap(item=>Object.entries(item.environments??{}).map(([name,e])=>`- ${item.id} / ${name}：${({host:'使用宿主机环境',bundled:'随包携带',tool:'使用 Fishtools 自带环境'})[e.source]??e.source}`)),
+    '环境与平台由插件作者声明；具体执行结果请在 /logs 查看。',
+    '编排用法：/workflows 新建工作流 → 添加步骤并选择上述能力 → 填写参数 → 保存 → 运行。也可在主面板用 /run 选择已保存的工作流。',
+  ].join('\n\n');
+}

package/{manual/packages/core → node_modules/@mytools/fst-cli}/src/terminal/run-feed.js

@@ -3,7 +3,7 @@ import {runStatuses} from './run-viewer.js';
 
 // 主面板按事件到达顺序追加；运行快照另存，配置菜单不会清掉执行记录。
 export class RunFeed{
-  constructor(refresh){this.refresh=refresh;this.runs=new Map();this.entries=[];this.subscriptions=new Map();this.expanded=false;}
+  constructor(refresh,{maxEvents=1000,maxBytes=1048576,maxRuns=50}={}){Object.assign(this,{refresh,maxEvents,maxBytes,maxRuns});this.runs=new Map();this.entries=[];this.subscriptions=new Map();this.expanded=false;this.dropped=0;}
   track({app,runId,title,input}){
     if(this.runs.has(runId))return;
     const record=app.getRun(runId),item={app,record,title,input,count:0,ended:false,steps:new Map(),catalog:new Map((app.catalog?.()??[]).map(action=>[action.id,action]))};
@@ -26,12 +26,15 @@ export class RunFeed{
     this.refresh();
   }
   update(item,event){
-    if(event?.type&&!['run.succeeded','run.failed','run.cancelled','run.stopped'].includes(event.type))item.record.events.push(event);
+    let events;
+    if(event?.type&&!['run.succeeded','run.failed','run.cancelled','run.stopped'].includes(event.type)){item.record.events.push(event);events=[event];item.count++;}
     else{
       const record=item.app.getRun(item.record.id);if(!record)return;
       item.record={...record,events:[...(record.events??[])]};
+      events=record.events.filter((e,index)=>e.seq!==undefined?e.seq>item.count:index>=item.count);
+      item.count=record.eventCount??record.events.length;
     }
-    const {record}=item,events=record.events.slice(item.count);item.count=record.events.length;
+    const {record}=item;
     for(const event of events)if(event.type.startsWith('step.'))item.steps.set(event.callPath,{...item.steps.get(event.callPath),...event});
     if(events.length){
       const last=this.entries.at(-1);
@@ -39,12 +42,34 @@ export class RunFeed{
       else this.entries.push({type:'events',item,events});
     }
     if(record.status!=='running'&&!item.ended){item.ended=true;this.entries.push({type:'result',item});}
+    this.trim();
+  }
+  trim(){
+    let count=0,bytes=0;
+    for(let index=this.entries.length-1;index>=0;index--){
+      const entry=this.entries[index];if(!entry.events)continue;
+      let keep=entry.events.length;
+      for(let i=entry.events.length-1;i>=0;i--){
+        const size=Buffer.byteLength(JSON.stringify(entry.events[i]));
+        if(count>=this.maxEvents||bytes+size>this.maxBytes){keep=entry.events.length-i-1;this.dropped+=i+1;break;}
+        count++;bytes+=size;
+      }
+      if(keep!==entry.events.length)entry.events=keep?entry.events.slice(-keep):[];
+    }
+    this.entries=this.entries.filter(entry=>!entry.events||entry.events.length);
+    for(const item of this.runs.values()){
+      item.record.events=this.entries.filter(e=>e.item===item&&e.events).flatMap(e=>e.events);
+      while(item.steps.size>this.maxEvents)item.steps.delete(item.steps.keys().next().value);
+    }
+    const ended=[...this.runs.values()].filter(item=>item.ended);
+    for(const item of ended.slice(0,Math.max(0,ended.length-this.maxRuns))){this.runs.delete(item.record.id);this.entries=this.entries.filter(e=>e.item!==item);this.dropped++;}
+    const messages=this.entries.filter(e=>e.type==='message');for(const entry of messages.slice(0,Math.max(0,messages.length-100)))this.entries.splice(this.entries.indexOf(entry),1);
   }
   release(app){
     if([...this.runs.values()].some(item=>item.app===app&&!item.ended))return;
     this.subscriptions.get(app)?.();this.subscriptions.delete(app);
   }
-  message(text){this.entries.push({type:'message',text});this.refresh();}
+  message(text){this.entries.push({type:'message',text:String(text).slice(-65536)});this.trim();this.refresh();}
   compactEvents(entry,seen){
     const {item}=entry,rows=[];
     for(const event of entry.events){
@@ -61,7 +86,7 @@ export class RunFeed{
     }
     return rows.length?`${item.title??item.record.workflowId} · ${item.record.id.slice(0,8)}\n${rows.join('\n')}`:'';
   }
-  text(){const seen=new Set();return this.entries.map(entry=>{
+  text(){const seen=new Set();return (this.dropped?'主面板仅保留近期摘要；完整日志可在 /logs 中按 p 分页阅读。\n\n':'')+this.entries.map(entry=>{
     if(entry.type==='message')return entry.text;
     const {record,title,input}=entry.item,label=`${title??record.workflowId} · ${record.id.slice(0,8)}`;
     if(entry.type==='start')return [
@@ -71,6 +96,7 @@ export class RunFeed{
     ].filter(Boolean).join('\n');
     if(entry.type==='events')return this.expanded?`${label}\n${readableTimeline(entry.events,{values:true})}`:this.compactEvents(entry,seen);
     return [`结果 · ${label} · ${runStatuses[record.status]??record.status}`,
+      ...(record.warnings??[]).map(warning=>`警告：${warning.message}`),
       this.expanded&&record.output!==undefined?readableValue(record.output):'',record.error&&(this.expanded||![...entry.item.steps.values()].some(step=>step.type==='step.failed'))?readableError(record.error,{details:this.expanded}):'',record.reason??'',
     ].filter(Boolean).join('\n');
   }).filter(Boolean).join('\n\n');}

package/node_modules/@mytools/fst-cli/src/terminal/run-presentation.js

@@ -0,0 +1,60 @@
+// 阅读层只处理展示；原始事件、输入输出与错误仍保留在运行记录中。
+export function readableValue(value,indent=''){
+  if(value===undefined)return '暂无记录';
+  if(value===null)return 'null';
+  if(typeof value!=='object')return String(value);
+  const entries=Array.isArray(value)?value.map((v,i)=>[`[${i+1}]`,v]):Object.entries(value);
+  if(!entries.length)return Array.isArray(value)?'（空列表）':'（空对象）';
+  return entries.map(([key,item])=>{
+    const nested=item!==null&&typeof item==='object';
+    return `${indent}${key}：${nested?'\n'+readableValue(item,indent+'  '):String(item).replaceAll('\n','\n'+indent+'  ')}`;
+  }).join('\n');
+}
+export function readableError(error,{details=false}={}){
+  if(!error)return '';
+  const chain=[];for(let current=error;current;current=current.cause)chain.push(current);
+  const program=chain.find(e=>e.details?.executable)?.details.executable;
+  const code=chain.find(e=>e.code==='ENOENT')?.code??error.code;
+  const summary=[`原因：${code==='ENOENT'&&program?'未找到所需程序':error.message??'未知错误'}`,error.plugin&&`插件：${error.plugin}`,code&&`错误码：${code}`,program&&`程序：${program}`,code==='ENOENT'&&'请检查程序是否安装、路径是否正确以及 PATH 配置。'].filter(Boolean).join('\n');
+  if(!details)return summary;
+  const diagnostic=chain.flatMap((item,index)=>[
+    `${index===0?'错误':'上游原因 '+index}：${item.message??'未知错误'}`,
+    item.code&&`错误码：${item.code}`,
+    item.details!==undefined&&`细节：\n${readableValue(item.details)}`,
+    item.stack&&`调用栈：\n${item.stack}`,
+  ].filter(Boolean));
+  return `${summary}\n\n${diagnostic.join('\n')}`;
+}
+const eventNames={'step.started':'步骤开始','step.succeeded':'步骤成功','step.failed':'步骤失败','step.cancelled':'步骤取消','step.skipped':'步骤跳过','step.stopped':'步骤停止','run.started':'运行开始','run.succeeded':'运行成功','run.failed':'运行失败','run.cancelled':'运行取消','run.stopped':'提前结束'};
+const time=value=>{const date=new Date(value);return Number.isFinite(+date)?date.toLocaleTimeString('zh-CN',{hour12:false}):'--:--:--';};
+export function readableTimeline(events,{callPath,values=false}={}){
+  const rows=[];let pending;
+  const push=(event,message)=>{
+    const prefix=`${time(event.time)}  [${event.callPath??'运行'}${event.stream?' · '+event.stream:''}]`;
+    const lines=String(message).replaceAll('\r\n','\n').replaceAll('\r','\n').split('\n');
+    if(lines.at(-1)==='')lines.pop();
+    for(const line of lines)rows.push(`${prefix}  ${line}`);
+  };
+  const flush=()=>{if(pending){if(pending.text)push(pending.event,pending.text);pending=null;}};
+  for(const event of events??[]){
+    if(callPath&&event.callPath!==callPath)continue;
+    if(event.type==='log'&&event.stream){
+      const key=`${event.callPath}\0${event.stream}`;
+      if(pending?.key!==key){flush();pending={key,event,text:''};}
+      pending.text+=event.message??'';
+      const end=pending.text.lastIndexOf('\n');
+      if(end>=0){push(pending.event,pending.text.slice(0,end+1));pending.text=pending.text.slice(end+1);pending.event=event;}
+      continue;
+    }
+    if(event.type==='log'){flush();push(event,`${event.message??''}${event.data!==undefined?'\n'+readableValue(event.data):''}`);continue;}
+    if(eventNames[event.type]){
+      const detail=event.error?readableError(event.error,{details:values}):event.reason??event.message;
+      flush();push(event,`${eventNames[event.type]}${event.action?' · '+event.action:''}${event.durationMs!==undefined?` · ${event.durationMs} ms`:''}${detail?'\n'+detail:''}`);
+      if(values&&event.type.startsWith('step.')){
+        if(event.input!==undefined&&Object.keys(event.input??{}).length)push(event,'输入\n'+readableValue(event.input));
+        if(event.output!==undefined)push(event,'输出\n'+readableValue(event.output));
+      }
+    }
+  }
+  flush();return rows.join('\n')||'等待执行记录。插件通过 log 或 runProcess 输出的内容会显示在这里。';
+}

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

@@ -0,0 +1,106 @@
+import { stripVTControlCharacters } from 'node:util';
+import { Text, matchesKey, truncateToWidth } from '@mariozechner/pi-tui';
+import {palette} from './theme.js';
+import {readableValue,readableError,readableTimeline} from './run-presentation.js';
+
+export const runStatuses={pending:'待执行',unknown:'摘要已省略',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=[],catalog=[],terminal,onClose,onCancel,onReadLogs,requestRender}){
+    Object.assign(this,{terminal,onClose,onCancel,onReadLogs,requestRender,catalog});this.view=0;this.selected=0;this.offset=0;this.follow=true;this.allLogs=true;this.raw=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,...(record.stepsTruncated&&record.status!=='running'?{status:'unknown'}:{})}]));
+    for(const event of [...(record.events??[]),...(record.stepSummaries??[])].sort((a,b)=>(a.seq??0)-(b.seq??0))){
+      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)});
+      node.title??=this.catalog.find(action=>action.id===node.action)?.title;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?readableError(this.record.error):'',
+      ...(this.record.warnings??[]).map(warning=>`警告：${warning.message}`),
+      this.record.output!==undefined?'\n最终输出\n'+readableValue(this.record.output):'',
+      '\n步骤 · Enter 查看详情',
+      ...this.nodes.map((n,i)=>`${i===this.selected?'›':' '} ${runStatuses[n.status]??n.status} · ${n.title??n.callPath}${n.durationMs!==undefined?` · ${n.durationMs} ms`:''}${n.reason?' · '+n.reason:''}`),
+      !this.nodes.length?'此运行没有工作流步骤，可在日志页查看插件输出。':'',
+    ].filter(Boolean).join('\n');
+    if(this.view===1){
+      const format=value=>this.raw?JSON.stringify(value??null,null,2):readableValue(value);
+      const error=node?node.error:this.record.error;
+      return [`步骤：${node?.callPath??'整个运行'}`,node?.action?'能力：'+node.action:'',error?'\n错误\n'+(this.raw?format(error):readableError(error)):'',
+        node?'\n输入\n'+format(node.input):'', '\n输出\n'+format(node?node.output:this.record.output),
+        !error&&(node?.reason||node?.message)?'\n说明：'+(node.reason??node.message):'',this.raw?'\n原始 JSON · 包含完整错误详情与调用栈':'\nj 查看原始 JSON 与完整诊断',
+      ].filter(Boolean).join('\n');
+    }
+    return (this.record.eventsTruncated?'当前为近期日志摘要，按 p 分页查看完整落盘日志。\n\n':'')+readableTimeline(this.record.events,{callPath:this.allLogs?undefined:node?.callPath});
+  }
+  layout(width){
+    const height=Math.max(1,this.terminal.rows),pageSize=Math.max(1,height-4);
+    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 取消 · p 完整日志 · 1/2/3 切换';
+    const shortcuts=width<60?'↑↓/滚轮 · [ ] 步骤 · j 原始数据':`↑↓/滚轮 翻页 · [ ] 步骤 · j 原始数据 · a 全部/本步骤 · End 跟随 · ${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]:height===4?[tabs,styledBody[0],styledFooter,palette.muted(shortcuts)]:[tabs,palette.muted(safe(selection)),...styledBody,styledFooter,palette.muted(shortcuts)];
+    return screen.map(line=>truncateToWidth(line,width));
+  }
+  handleInput(data){
+    if(data==='p'&&this.onReadLogs){this.onReadLogs();return;}
+    if(this.confirmCancel){this.confirmCancel=false;if(data==='y')this.onCancel();this.requestRender();return;}
+    if(['escape','q'].some(key=>matchesKey(data,key))){this.onClose();return;}
+    if(matchesKey(data,'enter')){if(this.view===0){this.view=1;this.offset=0;this.requestRender();}return;}
+    if(data==='j'){this.raw=!this.raw;this.view=1;this.offset=0;this.requestRender();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){const {lines,pageSize,maxOffset}=this.layout(this.terminal.columns);const row=lines.findIndex(line=>line.startsWith('›'));this.offset=Math.min(maxOffset,Math.max(0,row-Math.floor(pageSize/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();
+  }
+}