@yanglaofish/fishtools 0.4.0 → 0.5.0

package/node_modules/@mytools/fst-cli/bin/fst.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { readFile, access } from 'node:fs/promises';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import { createApplication } from '@mytools/core';
+import { verifyBundle } from '@mytools/fst-platform/bundle';
+import { resolveProject, initializeProject } from '@mytools/fst-workspace/project';
+import {waitForCliRun,cliRunResult} from '../src/cli-run.js';
+import {VERSION} from '@mytools/core/version';
+import {listDocumentation,readDocumentation,findDocumentationRoot,exportDocumentation} from '@mytools/fst-devtools/documentation';
+import {collectInstallations} from '@mytools/fst-workspace/installations';
+import {prepareBundleWorkspace} from '@mytools/fst-workspace/bundles';
+import {readJson} from '@mytools/fst-platform/json';
+
+const program=new Command().name('fst').description('Fishtools · 插件式工作流工作台').version(VERSION);
+program.option('--maintenance','维护模式：不启动有状态服务插件');
+program.option('--allow-unverified-privileges','本次允许权限预检结果无法确认的服务启动');
+program.option('--watch','开发模式：监听本地 link 源码，等待业务空闲后重启');
+program.option('--project <directory>','项目目录（默认当前项目或用户工作区）').option('--workspace <directory>','便携包的可写工作区').option('--output <directory>','日志与结果目录').option('--config <file>','插件配置覆盖文件').option('--host <host>','Web 监听地址','127.0.0.1').option('--port <port>','Web 监听端口','8765');
+async function app({management=false,removeInstalled,allowUnknownPrivileges=false}={}){const o=program.opts();return createApplication({projectDir:process.env.FISHTOOLS_DEV_PROJECT??await resolveProject(o.project,o.workspace),outputDir:o.output,maintenance:management||!!o.maintenance,omitInstalledPlugin:removeInstalled,allowUnknownPrivileges:allowUnknownPrivileges||!!o.allowUnverifiedPrivileges,config:o.config?JSON.parse(await readFile(o.config,'utf8')):{}});}
+const developmentChild=process.env.FISHTOOLS_DEV_CHILD==='1';
+program.hook('preAction',(_program,command)=>{
+  if(!program.opts().watch||developmentChild)return;
+  if(![program,program.commands.find(item=>item.name()==='web')].includes(command))throw new Error('--watch 开发模式只支持交互 TUI 和 fst --watch web，不能用于一次性命令');
+  if(command===program&&(!process.stdin.isTTY||!process.stdout.isTTY))throw new Error('fst --watch 需要交互终端；Web 开发请使用 fst --watch web');
+});
+async function watchDevelopment(mode,settings=program.opts()){
+  const {startDevelopment}=await import('../src/development.js');
+  return startDevelopment({projectDir:await resolveProject(settings.project,settings.workspace),entry:fileURLToPath(import.meta.url),
+    args:process.argv.slice(2).filter(argument=>argument!=='--watch'),configFile:settings.config,mode,port:Number(settings.port)});
+}
+async function use(fn,options){const a=await app(options);try{for(const warning of a.host.warnings)console.error(`警告：${warning.message}`);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('查看、检查和复制工作流');
+program.command('logs [id]').description('列出运行历史或分页读取完整日志').option('--cursor <bytes>','正文 UTF-8 字节游标','0').option('--limit <bytes>','每页字节数（4 到 262144）','65536').option('--json','输出正文与下一页游标').action((id,options)=>use(async a=>{
+  if(!id){console.log(JSON.stringify(await a.listRunHistory(),null,2));return;}
+  const page=await a.readLogPage(id,{cursor:Number(options.cursor),limit:Number(options.limit)});
+  if(options.json)console.log(JSON.stringify(page,null,2));else{process.stdout.write(page.text);if(page.hasMore)console.error(`\n下一页：fst logs ${id} --cursor ${page.nextCursor} --limit ${options.limit}`);}
+},{management:true}));
+workflow.command('list').action(()=>use(async a=>console.log(JSON.stringify(await a.listWorkflows(),null,2))));
+workflow.command('check <id>').option('--json','输出包含权限要求的检查结果').action((id,options)=>use(async a=>{const report=await a.checkWorkflow(id);console.log(options.json?JSON.stringify(report,null,2):`工作流校验通过；涉及 ${report.privileges.length} 个动作的权限声明`);}));
+workflow.command('duplicate <source>').description('复制已保存工作流，不修改原版').requiredOption('--title <name>','新工作流名称').option('--id <id>','新工作流 ID（默认自动生成）').action((source,options)=>use(async a=>{
+  const definition=await a.store.get(source);
+  const result=await a.duplicateWorkflow(definition,{id:options.id,title:options.title.trim()});
+  console.log(JSON.stringify(result,null,2));
+}));
+program.command('run <id>').option('--input <file>','JSON 输入文件').option('--allow-unverified-privileges','本次允许权限预检结果为待确认的动作继续运行').action((id,o)=>use(async a=>{
+  const run=await a.startRun(id,o.input?JSON.parse(await readFile(o.input,'utf8')):{},{allowUnknownPrivileges:!!o.allowUnverifiedPrivileges});
+  const result=cliRunResult(await waitForCliRun(a,run));console.log(JSON.stringify(result.value,null,2));
+  process.exitCode=result.exitCode;
+},{allowUnknownPrivileges:!!o.allowUnverifiedPrivileges}));
+const plugin=program.command('plugin').description('管理插件');
+plugin.command('list').action(()=>use(a=>console.log(JSON.stringify(a.listPlugins(),null,2))));
+plugin.command('add <source>').action(source=>use(async a=>console.log(JSON.stringify(await a.installPlugin(source),null,2)),{management:true}));
+plugin.command('link <directory>').description('引用本地开发源码，修改后重启 fst 生效').action(directory=>use(async a=>console.log(JSON.stringify(await a.linkPlugin(path.resolve(directory)),null,2)),{management:true}));
+plugin.command('remove <name>').option('--force','即使工作流仍引用此插件也继续卸载；不会越过插件依赖与活动 Web 检查').action((name,o)=>use(async a=>console.log(JSON.stringify(await a.removePlugin(name,{force:!!o.force}),null,2)),{management:true,removeInstalled:name}));
+const network=program.command('network').description('查看或保存工作区、插件和动作级代理规则');
+network.command('show').action(()=>use(a=>console.log(JSON.stringify(a.networkPolicy(),null,2))));
+network.command('set <file>').description('从 JSON 保存代理规则').action(file=>use(async a=>{const saved=await a.configureNetworkPolicy(JSON.parse(await readFile(file,'utf8')));console.log(`代理规则已保存；原项目配置备份：${saved.backup}`);}));
+for(const command of ['validate','lint'])plugin.command(`${command} <directory>`).description(command==='lint'?'检查可信插件声明与质量建议，不自动修改文件':'检查可信插件声明，不执行动作或运行时服务').option('--json','输出结构化报告').action(async(directory,options)=>{
+  const tools=await import('@mytools/fst-devtools');const report=await tools[command==='lint'?'lintPluginDirectory':'validatePluginDirectory'](path.resolve(directory));
+  if(options.json)console.log(JSON.stringify(report,null,2));else{
+    console.log(`${report.valid?'检查通过':'检查未通过'}：${report.plugin?.id??directory}`);
+    for(const item of report.diagnostics)console.log(`${item.severity==='error'?'错误':'警告'} [${item.code}] ${item.path??''} ${item.message}`);
+    for(const item of report.notes)console.log(`说明 [${item.code}] ${item.message}`);
+  }
+  if(!report.valid)process.exitCode=1;
+});
+plugin.command('create <name> [directory]').description('创建可独立安装的插件骨架').action(async(name,directory)=>{
+  const {createPlugin}=await import('@mytools/fst-devtools');const result=await createPlugin(name,path.resolve(directory??name));
+  console.log(`插件已创建：${result.directory}\n运行 fst plugin validate "${result.directory}" 检查；使用 fst plugin link "${result.directory}" 开发`);
+});
+plugin.command('gc').description('预览未引用安装批次；--apply 先备份再清理').option('--apply','压缩备份后清理安全批次').action(async options=>{
+  const settings=program.opts(),projectDir=await prepareBundleWorkspace(await resolveProject(settings.project,settings.workspace),settings.workspace);
+  const project=await readJson(path.join(projectDir,'flow.project.json'),{});
+  if(project.readOnly)throw new Error('只读项目不能清理插件批次');
+  console.log(JSON.stringify(await collectInstallations(projectDir,{apply:!!options.apply}),null,2));
+});
+const packOptions=command=>command.requiredOption('--target <target>','win32-x64 或 linux-x64-glibc').option('--out <directory>','导出目录','dist').option('--read-only','导出只读精简运行包').option('--environments <file>','环境来源覆盖 JSON').option('--plan','只查看打包资源计划');
+async function pack(a,entries,o,portable=false){
+  const options={entries,target:o.target,outDir:o.out,includeWeb:!!o.web,readOnly:!!o.readOnly,portable,environments:o.environments?JSON.parse(await readFile(o.environments,'utf8')):{}};
+  console.log(JSON.stringify(await (o.plan?a.packPlan(options):a.pack(options)),null,2));
+}
+packOptions(program.command('pack <entries...>')).option('--web','包含 Web 界面').action((entries,o)=>use(a=>pack(a,entries,o)));
+packOptions(program.command('portable').description('导出完整便携工具、当前全部流程和插件')).option('--no-web','不额外携带 Web').action(o=>use(a=>pack(a,[],o,true)));
+program.command('command [name]').description('列出插件命令或执行动作命令').option('--input <file>','JSON 输入').option('--allow-unverified-privileges','本次允许权限预检结果为待确认的命令继续运行').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')):{},{allowUnknownPrivileges:!!o.allowUnverifiedPrivileges});
+  const result=cliRunResult(await waitForCliRun(a,run));console.log(JSON.stringify(result.value,null,2));process.exitCode=result.exitCode;
+},{allowUnknownPrivileges:!!o.allowUnverifiedPrivileges}));
+program.command('configure <plugin> <file>').description('从 JSON 保存插件配置').action((id,file)=>use(async a=>{const saved=await a.configurePlugin(id,JSON.parse(await readFile(file,'utf8')));console.log(`插件配置已保存。原项目配置备份：${saved.backup}`);},{management:true}));
+async function web(o){
+  if(program.opts().watch&&!developmentChild)return watchDevelopment('web',o);
+  if(developmentChild){const {runDevelopmentChild}=await import('../src/development.js');const a=await app();try{return await runDevelopmentChild(a,{mode:'web',webOptions:{host:o.host,port:Number(o.port)}});}catch(error){await a.close();throw error;}}
+  const a=await app();let server;
+  try{server=await a.startWeb({host:o.host,port:Number(o.port)});}catch(error){await a.close();throw error;}
+  console.log(`Fishtools：${server.url}`);
+  const stop=async()=>{await server.close();await a.close();};process.once('SIGINT',stop);process.once('SIGTERM',stop);
+}
+program.action(async()=>{
+  if(program.opts().watch&&!developmentChild)return watchDevelopment('terminal');
+  if(!process.stdin.isTTY||!process.stdout.isTTY){program.outputHelp();return;}
+  if(developmentChild){const {runDevelopmentChild}=await import('../src/development.js');const a=await app();try{return await runDevelopmentChild(a,{mode:'terminal',webOptions:{host:program.opts().host,port:Number(program.opts().port)}});}catch(error){await a.close();throw error;}}
+  const {startTerminal}=await import('../src/terminal/session.js');
+  await use(a=>startTerminal(a,{webOptions:{host:program.opts().host,port:Number(program.opts().port)}}));
+});
+program.command('web').description('启动可选的 Fishtools Web 工作台').option('--host <host>','监听地址').option('--port <port>','监听端口').action(o=>web({...program.opts(),...o}));
+program.command('doctor').action(()=>use(async a=>{
+  let integrity;
+  const bundleRoot=a.project.baseBundle?.root??a.projectDir;
+  try{await access(path.join(bundleRoot,'manifest.json'));integrity=await verifyBundle(bundleRoot);}
+  catch(error){if(error.code!=='ENOENT')throw error;}
+  console.log(JSON.stringify({node:process.version,platform:process.platform,arch:process.arch,plugins:a.listPlugins(),integrity},null,2));
+  if(integrity&&!integrity.ok)process.exitCode=1;
+}));
+try {await program.parseAsync();}catch(error){console.error(error.message);process.exitCode=error.code==='CANCELLED'?130:2;if(developmentChild){process.send?.({type:'development:failed',message:error.message});process.disconnect?.();}}

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');}