@yanglaofish/fishtools 0.2.0 → 0.4.0

package/manual/packages/core/src/terminal/session.js

@@ -0,0 +1,438 @@
+import { randomUUID } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import path from 'node:path';
+import { 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';
+import {readableValue,readableError} from './run-presentation.js';
+import {commandMenu} from './navigation.js';
+import {workflowMenu} from './workflow-menu.js';
+
+export class TerminalSession{
+  constructor(app,ui,{baseDir=process.cwd(),webOptions={}}={}){this.app=app;this.ui=ui;this.baseDir=baseDir;this.webOptions=webOptions;this.flow=null;this.dirty=false;this.exiting=false;this.web=null;ui.activeRuns=()=>app.listRuns().filter(run=>run.status==='running').length;}
+  writable(){if(this.app.project.readOnly)throw new Error('这是只读运行包，请在完整工作区中编排、安装或打包');}
+  current(){if(!this.flow)throw new Error('先用 /workflows 打开或新建工作流');return this.flow;}
+  commands(){return commandMenu(this.app.listPlugins?.()??[],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),{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.dirty?'未保存':'已保存'}`:''}`);
+        let text;
+        try{text=await this.ui.input('fst > 输入 / 选择操作，@ 引用文件',{commands:this.commands(),workflows:await this.app.listWorkflows()});}
+        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){if(e.code!=='PROMPT_CANCELLED'||!this.ui.endCommand)this.ui.show(e.code==='PROMPT_CANCELLED'?'已返回主面板。':`${e.code==='COMMAND_INPUT'?'输入提示':'操作失败'}：${e.message}`);}
+      }
+    }finally{if(this.web)await this.web.close();}
+  }
+  async execute(text){
+    // 只记录用户提交的入口；菜单内部调用 /save 等动作不制造伪命令。
+    const outer=!this.commandDepth;
+    if(outer)this.ui.beginCommand?.(text);
+    this.commandDepth=(this.commandDepth??0)+1;
+    try{return await this.executeCommand(text);}
+    finally{this.commandDepth--;if(outer&&!this.exiting)this.ui.endCommand?.();}
+  }
+  async executeCommand(text){
+    const [command,...args]=parseCommand(text);
+    const entry=this.commands().find(c=>c.name===command&&c.plugin);
+    if(entry){if(args.length)throw new Error(`/${command} 请从二级菜单选择能力`);return this.pluginSkills(entry.plugin);}
+    const pluginCommand=this.app.listCommands().find(c=>c.name===command);
+    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 使用指南',[
+        '# Fishtools',
+        '将插件能力组合为工作流，在终端内编辑、运行并查看结果。',
+        `当前工作区：${this.app.projectDir}`,
+        `文件路径起点：${this.baseDir}`,
+        '## 常用操作',gettingStarted(await this.app.listWorkflows(),this.app.project),
+        '## 编排工作流','/workflows 浏览、新建、打开工作流，进入后添加步骤、编辑参数、设置输出、保存或删除。删除会保留备份，仍被其他流程引用时不能删除。/run 选择已保存的工作流，或补全工作流 ID/中文标题后执行已保存版本，不会要求保存编辑草稿。要执行未保存修改，在工作流编辑菜单选择运行，再选择保存并运行；返回编辑会保留草稿。',
+        '## 主面板','运行期间可以继续输入命令，打开配置、管理插件或执行其他工作流。↑/↓ 回看本次启动已提交的命令，回到底部恢复草稿；补全菜单打开时仍用于选择候选。Ctrl+O 展开或收起执行详情，PgUp/PgDn 或滚轮浏览执行过程；/logs 回看各次执行的步骤、输入输出和日志。关闭菜单不会清空运行内容。',
+        '## 命令分层','/config 配置 Fishtools，/plugin 管理插件及各插件配置。输入 /插件入口名 后进入该插件的能力菜单；补全列表标明 [内置] 或 [插件]。/tools 包含 Web 与离线文档。旧 /new、/add、/steps、/outputs、/save、/plugins 以及插件的原始命令仍可直接输入。',
+        '## 观察运行','输入 /logs 打开执行记录。列表包含多个工作流的每次执行，运行中任务排在前面；选择后查看进度、结果和日志。从详情返回后可选择另一条记录，本次启动期间每条记录分别保留阅读位置。重启后仍可查看保留下来的执行记录。',
+        '1 / 2 / 3 切换总览、输入输出和日志，Enter 查看步骤详情，[ / ] 切换步骤，j 查看原始诊断数据。↑↓、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':return workflowMenu(this);
+      case 'new':{
+        this.writable();if(!await this.discard())return false;
+        const title=(await this.ui.input('工作流名称',{files:false})).trim();if(!title)throw new Error('名称不能为空');
+        const description=await this.ui.input('用途说明（可留空）',{files:false});
+        this.flow=newWorkflow(title,description);this.dirty=true;this.ui.show('工作流草稿已创建，可以在编辑菜单添加步骤。');return true;
+      }
+      case 'add':return this.add();
+      case 'steps':return this.steps();
+      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.logs();
+      case 'logs':return this.logs();
+      case 'plugin':case 'plugins':return this.plugins();
+      case 'config':return this.toolConfig();
+      case 'tools':{
+        const choice=await this.ui.select('工具',[{value:'web',label:'启动 Web 工作台'},{value:'docs',label:'阅读离线文档'},{value:'back',label:'返回主面板'}]);
+        if(choice!=='back')await this.execute('/'+choice);return;
+      }
+      case 'pack':return this.pack();
+      case 'web':{
+        if(!this.web)this.web=await this.app.startWeb(this.webOptions);
+        this.ui.show(`Web 已启动，退出 fst 时关闭：\n${this.web.url}`);return;
+      }
+      default:throw new Error(`未知操作 /${command}，输入 /help 查看可用操作`);
+    }
+  }
+  async pluginCommand(command,args){
+    if(args.length>1)throw new Error(`用法：/${command.name} [@参数.json]`);
+    const input=args.length?await readRunInput(args[0],this.baseDir):command.input?await editValue(this.ui,command.input,{}, {baseDir:this.baseDir,required:true,label:command.description}):{};
+    const ui=Object.fromEntries(['input','select','show','confirm'].map(name=>[name,this.ui[name].bind(this.ui)]));
+    const run=await this.app.startCommand(command.name,input,{ui});
+    if(this.ui.trackRun){
+      this.ui.clearMessages?.();this.ui.trackRun({app:this.app,runId:run.id,title:command.description??command.name,input});
+      if(command.action){void run.done.catch(error=>{if(!this.ui.closed)this.ui.show(`运行记录保存失败：${error.message}`);});return;}
+    }
+    const unsubscribe=this.ui.trackRun?()=>{}:this.app.subscribe(e=>{if(e.runId===run.id&&e.type==='log')this.ui.show(e.message);});
+    const done=this.ui.busy(`正在执行 /${command.name} · Ctrl+C 取消`,()=>this.app.cancelRun(run.id));
+    try{const result=await run.done;if(!this.ui.trackRun)this.ui.show(`插件执行${runStatuses[result.status]??result.status}\n${result.error?readableError(result.error):readableValue(result.output)}\n/logs 查看执行详情与历史日志`);}
+    finally{unsubscribe();done();}
+  }
+  async configure(selectedId){
+    this.writable();
+    const plugins=this.app.listPlugins().filter(p=>p.config);
+    if(!plugins.length){this.ui.show('当前插件没有声明可配置字段。');return;}
+    const id=selectedId??await this.ui.select('选择要配置的插件',plugins.map(p=>({value:p.id,label:p.title??p.id})));
+    const plugin=plugins.find(p=>p.id===id);
+    const value=await editValue(this.ui,plugin.config,this.app.project.config?.[id]??{}, {baseDir:this.baseDir,required:true,label:plugin.title??id});
+    await this.app.configurePlugin(id,value);this.ui.show('插件配置已保存到当前工作区。');
+  }
+  async logs(){
+    const statuses=runStatuses;
+    while(true){
+      const history=(await this.app.listRunHistory()).sort((a,b)=>(b.status==='running')-(a.status==='running'));
+      if(!history.length){this.ui.show('还没有执行记录。运行工作流后，可在 /logs 回看。');return;}
+      const titles=new Map((await this.app.listWorkflows()).map(flow=>[flow.id,flow.title??flow.id]));
+      const choice=await this.ui.select('执行记录 · 选择一次执行，查看步骤、输入输出与日志',[
+        ...history.map(r=>({value:`run:${r.id}`,label:`${statuses[r.status]??r.status} · ${titles.get(r.workflowId)??r.workflowId}`,description:`${new Date(r.startedAt).toLocaleString()} · ${r.id.slice(0,8)}`})),
+        {value:'back',label:'返回'},
+      ]);
+      if(choice==='back')return;
+      const id=choice.slice(4),record=history.find(r=>r.id===id);
+      try{
+        if(this.ui.observeRun)await this.openRun(record,{initialView:2});
+        else await this.ui.viewMarkdown(`${record.workflowId} · ${statuses[record.status]??record.status}`,await this.app.readLog(id));
+      }
+      catch(error){if(error.code!=='PROMPT_CANCELLED')throw error;}
+    }
+  }
+  async add(){
+    this.writable();const flow=structuredClone(this.current()),catalog=this.app.catalog(),workflows=await this.app.listWorkflows();
+    await this.addNode(flow,[],catalog,workflows);
+    this.flow=flow;this.dirty=true;this.ui.show('步骤已添加，可在工作流菜单继续调整或保存。');
+  }
+  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 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=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;
+    }
+    const props=Object.entries(meta.input?.properties??{});if(!props.length)return;
+    while(true){
+      const selection=await this.ui.select(`${meta.title} · 选择要设置的参数`,[
+        ...props.map(([key,s])=>({value:`field:${key}`,label:`${s.title??key}${meta.input.required?.includes(key)?' *':''}`,description:JSON.stringify(step.with?.[key]??s.default)??'未填写'})),
+        {value:'done',label:'完成参数设置'},
+      ]);
+      if(selection==='done')return;
+      const key=selection.slice(6);
+      const schema=meta.input.properties[key],required=meta.input.required?.includes(key);
+      const choices=outputSources(flow,index,catalog,workflows).filter(s=>!schema.type||!s.schema?.type||schema.type===s.schema.type);
+      const mode=await this.ui.select(`${schema.title??key} · 输入来源`,[
+        {value:'fixed',label:'填写固定值 / @本地文件路径'},{value:'runtime',label:'每次运行时填写'},
+        ...choices.map(({value,label})=>({value,label})),...(!required?[{value:'unset',label:'不传此参数，使用插件默认值'}]:[]),
+      ]);
+      if(mode==='unset')setBinding(flow,index,key,'fixed',schema,undefined);
+      else if(mode==='fixed'){
+        const previous=step.with?.[key];
+        const value=await editValue(this.ui,schema,previous?.$ref?undefined:previous,{baseDir:this.baseDir,required,label:schema.title??key});
+        setBinding(flow,index,key,mode,schema,value);
+      }else setBinding(flow,index,key,mode,schema);
+    }
+  }
+  async steps(){
+    const flow=structuredClone(this.current()),catalog=this.app.catalog(),workflows=await this.app.listWorkflows();
+    if(!flow.steps.length){this.ui.show('当前没有步骤，用 /add 添加。');return;}
+    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;}
+    await this.stepOperation(flow,[index],catalog,workflows);
+    if(isDeepStrictEqual(flow,this.flow))return;
+    this.flow=flow;this.dirty=true;this.ui.show('步骤已更新，保存前可继续调整。');
+  }
+  async outputs(){
+    this.writable();const flow=structuredClone(this.current());flow.outputs??={};
+    const choices=outputSources(flow,flow.steps.length,this.app.catalog(),await this.app.listWorkflows());
+    const action=await this.ui.select('工作流输出',[{value:'add',label:'添加汇总输出'},...Object.keys(flow.outputs).map(k=>({value:`remove:${k}`,label:`移除输出：${k}`}))]);
+    if(action==='add'){
+      const source=await this.ui.select('选择步骤输出',choices);
+      const name=(await this.ui.input('输出名称，例如 result',{files:false})).trim();
+      if(!/^[a-zA-Z][\w-]*$/.test(name)||['constructor','prototype','__proto__'].includes(name))throw new Error('输出名称请使用字母开头的英文、数字、下划线或短横线');
+      if(Object.hasOwn(flow.outputs,name))throw new Error('输出名称已存在，请使用另一个名称');
+      flow.outputs[name]={$ref:source};
+    }else delete flow.outputs[action.slice(7)];
+    this.flow=flow;this.dirty=true;this.ui.show('汇总输出已更新。');
+  }
+  async startRun(args,{draft=false}={}){
+    if(args.length>2)throw new Error('用法：/run [工作流ID] [@参数.json]');
+    const [first,second]=args;let reference=first?.startsWith('@')?first:second;
+    if(first?.startsWith('@')&&second)throw new Error('参数文件后不能再附加参数');
+    const workflows=await this.app.listWorkflows();
+    let flow=draft?this.current():null;
+    if(first&&!first.startsWith('@')){
+      flow=workflows.find(w=>w.id===first);if(!flow)throw new Error(`工作流不存在：${first}`);
+    }
+    if(!flow){
+      if(!workflows.length){this.ui.show('还没有已保存的工作流，请在 /workflows 中新建并保存。');return false;}
+      const id=await this.ui.select('运行 · 选择已保存的工作流',[...workflows.map(w=>({value:`workflow:${w.id}`,label:w.title??w.id,description:w.id})),{value:'back',label:'返回主面板'}]);
+      if(id==='back')return false;flow=workflows.find(w=>`workflow:${w.id}`===id);
+    }
+    if(flow===this.flow&&this.dirty){
+      const saved=workflows.find(w=>w.id===flow.id);
+      const choice=await this.ui.select(`${flow.title??flow.id} · 有未保存的修改`,[
+        {value:'cancel',label:'返回编辑',description:'保留草稿，本次不运行'},
+        {value:'save',label:'保存并运行',description:'将当前修改保存到工作流文件'},
+        ...(saved?[{value:'saved',label:'运行已保存版本',description:'保留当前草稿，不执行未保存修改'}]:[]),
+      ]);
+      if(choice==='cancel'){this.ui.show('已取消本次运行，草稿保留，返回工作流编辑。');return false;}
+      if(choice==='saved')flow=saved;
+      else await this.execute('/save');
+    }
+    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.trackRun){
+      this.ui.clearMessages?.();this.ui.trackRun({app:this.app,runId:run.id,title:flow.title??flow.id,input});
+      void run.done.catch(error=>{if(!this.ui.closed)this.ui.show(`运行记录保存失败：${error.message}`);});return true;
+    }
+    if(this.ui.observeRun){
+      await this.ui.observeRun({app:this.app,runId:run.id,flow,workflows:await this.app.listWorkflows()});
+      const status=this.app.getRun(run.id)?.status;
+      this.ui.clearMessages?.();this.ui.show(`${status==='running'?'已返回工作台，任务在后台继续执行。':`本次运行${runStatuses[status]??'已结束'}。`}\n输入 /logs 查看任意一次执行的进度、结果和日志。`);return true;
+    }
+    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(`运行${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();}
+    return true;
+  }
+  async pluginSkills(id){
+    const plugin=this.app.listPlugins().find(p=>p.id===id),commands=this.app.listCommands().filter(c=>c.plugin===id);
+    const choice=await this.ui.select(`[插件] ${plugin?.title??id} · 选择能力`,[
+      ...commands.map(c=>({value:`command:${c.name}`,label:c.description??c.name,description:`/${c.name}`})),{value:'back',label:'返回主面板'},
+    ]);
+    if(choice!=='back')await this.pluginCommand(commands.find(c=>`command:${c.name}`===choice),[]);
+  }
+  async toolConfig(){
+    while(true){
+      const keep=this.app.logSettings().keepRuns;
+      const choice=await this.ui.select('Fishtools 配置',[
+        {value:'info',label:'查看工作区信息'},
+        ...(!this.app.project.readOnly?[{value:'logs',label:'日志保留次数',description:keep===null?'不自动清理':`最近 ${keep} 次`}]:[]),
+        {value:'back',label:'返回主面板'},
+      ]);
+      if(choice==='back')return;
+      if(choice==='info')this.ui.show(`工作区：${this.app.projectDir}\n日志目录：${this.app.outputDir}\n模式：${this.app.project.readOnly?'只读运行包':'可编辑工作区'}`);
+      else await this.logSettings();
+    }
+  }
+  async logSettings(){
+    const keep=this.app.logSettings().keepRuns;
+    const mode=await this.ui.select('保留策略（整个项目合计，仅清理日志，保留业务文件）',[{value:'count',label:'仅保留最近 N 次已结束运行'},{value:'all',label:'不自动清理'},{value:'back',label:'返回'}]);
+    if(mode==='back')return;
+    const count=mode==='all'?null:Number(await this.ui.input('保留次数（例如 10）',{value:String(keep??10),files:false}));
+    await this.app.configureLogs(count);this.ui.show('日志保留设置已保存。');
+  }
+  async openRun(entry,{initialView}={}){
+    const record=this.app.getRun(entry.id)??await this.app.readRun(entry.id),workflows=await this.app.listWorkflows();
+    await this.ui.observeRun({app:this.app,runId:record.id,record,flow:workflows.find(flow=>flow.id===record.workflowId),workflows,initialView});
+  }
+  async plugins(){
+    this.ui.clearMessages?.();
+    while(true){
+    const plugins=this.app.listPlugins();
+    const action=await this.ui.select(`已安装插件（${plugins.length}）· ↑↓ 选择插件查看能力与配置`,[
+      ...plugins.map(p=>({value:`plugin:${p.id}`,label:`${p.title??p.id} · v${p.version} · ${pluginStatus(p)}`,description:p.description??p.id})),
+      ...(!this.app.project.readOnly?[{value:'local',label:'＋ 安装本地插件 / @路径'},{value:'npm',label:'＋ 安装 npm 插件包'},{value:'maintenance',label:this.app.maintenance?'恢复插件服务':'进入维护模式（停止有状态服务）'},...(this.web?[{value:'stop-web',label:'停止 Web 工作台'}]:[])]:[]),{value:'back',label:'返回工作台'},
+    ]);
+    if(action.startsWith('plugin:')){
+      try{await this.pluginPage(action.slice(7));}catch(error){if(error.code!=='PROMPT_CANCELLED')throw error;}
+      continue;
+    }
+    if(action==='maintenance'){await this.app.setMaintenance(!this.app.maintenance);this.ui.show(this.app.maintenance?'已进入维护模式，可修改插件与配置。':'插件服务已恢复。');return;}
+    if(action==='stop-web'){await this.web.close();this.web=null;this.ui.show('Web 已停止。');return;}
+    if(action==='back')return;
+    this.writable();
+    if(action==='local'||action==='npm'){
+      const text=await this.ui.input(action==='npm'?'npm 包名（支持 @scope/name）':'输入 @ 并选择插件目录或 .tgz',{files:action==='local'});
+      const source=action==='local'?fileReference(text,this.baseDir):text.trim();if(!source)throw new Error('插件来源不能为空');
+      if(!await this.ui.confirm(`安装并加载可信插件：${source}？`))return;
+      const done=this.ui.busy('正在安装插件…');try{await this.app.installPlugin(source);}finally{done();}
+    }
+    this.ui.show('插件列表已更新。');
+    }
+  }
+  async pluginPage(id){
+    while(true){
+      const plugin=this.app.listPlugins().find(p=>p.id===id);if(!plugin)return;
+      const definition=this.app.host.definitions.get(id);
+      // 详情显示作者声明；维护模式只停止执行，不能让能力说明消失。
+      const actions=Object.entries(definition.actions??{}).map(([name,a])=>({...a,id:`${id}:${name}`}));
+      const declaredCommands=Object.entries(definition.commands??{}).map(([name,c])=>({...c,name}));
+      const commands=this.app.listCommands().filter(c=>c.plugin===id);
+      const choice=await this.ui.select(`${plugin.title??id} · ${pluginStatus(plugin)} · ${actions.length} 项能力`,[
+        {value:'details',label:'查看用途、能力、输入输出和环境要求'},
+        ...(!this.app.project.readOnly&&plugin.config?[{value:'configure',label:'设置插件配置'}]:[]),
+        ...commands.map(c=>({value:`command:${c.name}`,label:`运行 /${c.name}`,description:c.description})),
+        ...(!this.app.project.readOnly&&plugin.removable?[{value:'remove',label:'移除此插件'}]:[]),
+        {value:'back',label:'返回插件列表'},
+      ]);
+      if(choice==='back')return;
+      if(choice==='details')await this.ui.viewMarkdown(plugin.title??id,pluginDetails(plugin,actions,declaredCommands));
+      else if(choice==='configure')await this.configure(id);
+      else if(choice.startsWith('command:'))await this.pluginCommand(commands.find(c=>c.name===choice.slice(8)),[]);
+      else if(choice==='remove'){
+        this.writable();if(await this.ui.confirm(`移除 ${id}？已有工作流可能依赖它。`)){await this.app.removePlugin(id);this.ui.show('插件已移除。');return;}
+      }
+    }
+  }
+  async pack(){
+    this.writable();if(this.dirty){if(!await this.ui.confirm('先保存当前工作流再选择打包？'))return;await this.execute('/save');}
+    const flows=await this.app.listWorkflows(),entries=new Set();if(!flows.length)throw new Error('没有可打包的工作流');
+    while(true){
+      const selection=await this.ui.select('选择入口工作流（Enter 切换勾选）',[...flows.map(w=>({value:`workflow:${w.id}`,label:`${entries.has(w.id)?'[x]':'[ ]'} ${w.title??w.id}`})),{value:'done',label:'完成选择'}]);
+      if(selection==='done'){if(entries.size)break;this.ui.show('请至少选择一个工作流');continue;}
+      const id=selection.slice(9);
+      if(entries.has(id))entries.delete(id);else entries.add(id);
+    }
+    const target=await this.ui.select('目标运行平台',[{value:'win32-x64',label:'Windows x64 ZIP'},{value:'linux-x64-glibc',label:'Linux x64 / Linux 容器 tar.gz'}]);
+    const includeWeb=await this.ui.confirm('包含可选 Web 运行界面？（终端界面始终可用）');
+    const readOnly=await this.ui.select('导出用途',[{value:'editable',label:'完整工具，可编辑工作区（含内部 npm）'},{value:'readonly',label:'只读精简运行包'}])==='readonly';
+    const closure=await this.app.checkWorkflow([...entries][0]);
+    const ids=new Set(closure.plugins);
+    for(const id of [...entries].slice(1))for(const plugin of (await this.app.checkWorkflow(id)).plugins)ids.add(plugin);
+    if(includeWeb){
+      const provider=[...this.app.host.definitions.values()].find(plugin=>typeof plugin.services?.web==='function');
+      if(!provider)throw new Error('未安装提供 Web 服务的插件');
+      ids.add(provider.id);
+    }
+    for(const id of ids)for(const dependency of Object.keys(this.app.host.definitions.get(id)?.dependencies??{}))ids.add(dependency);
+    const environments={};
+    for(const id of ids){
+      const plugin=this.app.host.definitions.get(id),declarations=new Map();
+      for(const group of [plugin.environments,...Object.values(plugin.actions??{}).map(a=>a.environments)])for(const [key,e] of Object.entries(group??{})){
+        const sources=e.allowedSources??[e.source],previous=declarations.get(key);
+        declarations.set(key,{...e,allowedSources:previous?previous.allowedSources.filter(s=>sources.includes(s)):sources});
+      }
+      for(const [key,e] of declarations)if(e.allowedSources.length>1){
+        const source=await this.ui.select(`${id} / ${key} · 环境来源`,e.allowedSources.map(value=>({value,label:{host:'使用目标环境，不入包',bundled:'携带作者提供的目标环境资源',tool:'使用 Fishtools 自带环境'}[value]})));
+        environments[id]??={};environments[id][key]={source};
+      }
+    }
+    const options={entries:[...entries],target,includeWeb,readOnly,environments,outDir:path.join(this.baseDir,'dist')};
+    const plan=await this.app.packPlan(options);
+    this.ui.show([...plan.warnings,...plan.environments.map(e=>`${e.plugin} / ${e.id}: ${e.source} · ${e.bytes} 字节`),`声明环境资源合计 ${plan.environmentBytes} 字节（另含工具及 Node）`].join('\n'));
+    if(!await this.ui.confirm('按此清单导出？'))return;
+    const done=this.ui.busy('正在收集依赖并打包…');
+    try{const result=await this.app.pack(options);this.ui.show(`已生成：${result.archive}`);}finally{done();}
+  }
+}
+
+export async function startTerminal(app,options={}){
+  const {TerminalView}=await import('./view.js');
+  const ui=new TerminalView({baseDir:options.baseDir??process.cwd(),previewLabel:options.previewLabel}),session=new TerminalSession(app,ui,options);
+  const terminate=()=>{session.exiting=true;ui.pending?.reject(Object.assign(new Error('退出'),{code:'PROMPT_CANCELLED'}));for(const r of app.listRuns())if(r.status==='running')app.cancelRun(r.id);};
+  process.once('SIGTERM',terminate);
+  try{ui.start();await session.run();}finally{process.removeListener('SIGTERM',terminate);await ui.close();}
+}