@yanglaofish/fishtools 0.5.2 → 0.6.0

package/manual/packages/fst-cli/src/terminal/run-presentation.js

@@ -1,14 +1,60 @@
+import {visibleWidth} from '@mariozechner/pi-tui';
+import {resultTable} from './result-table.js';
+import {renderReport,forwardedReport} from './report-presentation.js';
 // 阅读层只处理展示；原始事件、输入输出与错误仍保留在运行记录中。
-export function readableValue(value,indent=''){
+const fieldNames={stdout:'标准输出',stderr:'标准错误',stdin:'标准输入',exitCode:'退出码',path:'路径',file:'文件',directory:'文件目录',cwd:'执行目录',args:'参数',script:'原始脚本',executable:'程序',ok:'是否成功',success:'是否成功',plugin:'插件',durationMs:'耗时（毫秒）',id:'标识',title:'名称',group:'分组',found:'已找到',version:'版本',source:'来源',error:'错误',note:'说明'};
+const jsonTextLimit=65536;
+// 斜杠命令与工作流动作共用阅读元信息，避免直接调用时丢失字段标题。
+export function presentationCatalog(app){
+  return [...(app.catalog?.()??[]),...(app.listCommands?.()??[]).map(command=>({...command,id:`/${command.name}`}))];
+}
+function decodedValue(value){
+  if(typeof value!=='string'||value.length>jsonTextLimit||!/^\s*(?:[\[{"\d-]|true\b|false\b|null\b)/.test(value)||Buffer.byteLength(value)>jsonTextLimit)return value;
+  try{return JSON.parse(value);}catch{return value;}
+}
+const emptyField=value=>value==null||value===''||typeof value==='object'&&Object.keys(value).length===0;
+function valueText(value,indent,schema,depth,seen,decodeStrings,compact,width,truncated){
+  if(depth>32)return `${indent}（结构较深，请按 j 查看原始数据）`;
   if(value===undefined)return '暂无记录';
-  if(value===null)return 'null';
+  if(value===null)return '空值';
+  if(typeof value==='boolean')return value?'是':'否';
+  if(typeof value==='string'&&!decodeStrings)return JSON.stringify(value);
   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');
+  if(seen.has(value))return `${indent}（循环引用）`;
+  if(decodeStrings){
+    const report=renderReport(value,{indent,truncated,render:(item,prefix,child,{raw=false,inset=0}={})=>valueText(item,prefix,child,depth+1,seen,!raw,raw?false:compact,raw?width:width-visibleWidth(indent)-inset,truncated)});
+    if(report!==undefined)return report;
+  }
+  seen.add(value);
+  try{
+    const list=Array.isArray(value),entries=list?value.map((v,i)=>[i,v]):Object.entries(value);
+    if(!entries.length)return list?'（空列表）':'（空对象）';
+    const table=compact&&decodeStrings?resultTable(value,{schema,width,indent,label:(key,child)=>(typeof child?.title==='string'&&child.title.trim())||fieldNames[key]||key,render:(item,prefix,child)=>valueText(item,prefix,child,depth+1,seen,decodeStrings,compact,undefined,truncated)}):undefined;
+    if(table!==undefined)return table;
+    const rows=[];let inline=[];
+    const flush=()=>{if(inline.length){rows.push(indent+inline.join(' · '));inline=[];}};
+    for(let [key,item] of entries){
+      // 输入采用原值阅读，显式空值也可能有意义；仅结果紧凑模式折叠空字段。
+      if(compact&&decodeStrings&&!list&&emptyField(item))continue;
+      const child=list?(schema?.prefixItems?.[key]??(Array.isArray(schema?.items)?schema.items[key]:schema?.items)):(schema?.properties?.[key]??(typeof schema?.additionalProperties==='object'?schema.additionalProperties:undefined));
+      const title=typeof child?.title==='string'&&child.title.trim()?child.title.trim():undefined;
+      const label=list?`[${key+1}]`:title??fieldNames[key]??key;
+      if(decodeStrings)item=decodedValue(item);const nested=item!==null&&typeof item==='object';
+      const text=valueText(item,nested?indent+'  ':'',child,depth+1,seen,decodeStrings,compact,width,truncated);
+      const scalar=`${label}：${text}`;
+      if(compact&&!nested&&!/[\r\n]/.test(scalar)&&scalar.length<=100){
+        if(inline.join(' · ').length+scalar.length>120)flush();
+        inline.push(scalar);
+      }else{
+        flush();
+        rows.push(`${indent}${label}：${nested?(compact&&!text.includes('\n')?text.trimStart():'\n'+text):text.replaceAll('\r\n','\n').replaceAll('\r','\n').replaceAll('\n','\n'+indent+'  ')}`);
+      }
+    }
+    flush();return rows.join('\n')||(compact?'（空字段已折叠）':'');
+  }finally{seen.delete(value);}
+}
+export function readableValue(value,indent='',schema,{decodeStrings=true,compact=false,width,truncated=false}={}){
+  return valueText(decodeStrings?decodedValue(value):value,indent,schema,0,new Set(),decodeStrings,compact,width,truncated);
 }
 export function readableError(error,{details=false}={}){
   if(!error)return '';
@@ -27,10 +73,23 @@ export function readableError(error,{details=false}={}){
 }
 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 actionFrom=(catalog,id)=>catalog instanceof Map?catalog.get(id):catalog?.find(action=>action.id===id);
+export function readableProcess(data){
+  if(!data||typeof data!=='object')return readableValue(data);
+  const rows=[];
+  if(data.file!==undefined||data.executable!==undefined)rows.push(`程序：${data.file??data.executable}`);
+  if(Array.isArray(data.args))rows.push(data.args.length?'参数：\n'+data.args.map((argument,index)=>`  [${index+1}] ${String(argument)}`).join('\n'):'参数：（无）');
+  if(data.cwd!==undefined)rows.push(`执行目录：${data.cwd}`);
+  if(data.script!==undefined)rows.push(`原始脚本：\n${data.script}`);
+  return rows.join('\n')||readableValue(data);
+}
+export function readableTimeline(events,{callPath,values=false,catalog=[],width,finalOutput}={}){
+  const actions=new Map();for(const event of events??[])if(event.callPath&&event.action)actions.set(event.callPath,event.action);
   const rows=[];let pending;
+  const identity=event=>`${event.callPath??'运行'}${typeof event.processId==='string'&&event.processId?' · #'+event.processId.slice(0,8):''}${event.stream?' · '+event.stream:''}`;
+  const contentWidth=event=>Number.isFinite(width)?Math.max(1,width-visibleWidth(`00:00:00  [${identity(event)}]  `)):undefined;
   const push=(event,message)=>{
-    const prefix=`${time(event.time)}  [${event.callPath??'运行'}${event.stream?' · '+event.stream:''}]`;
+    const prefix=`${time(event.time)}  [${identity(event)}]`;
     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}`);
@@ -39,22 +98,40 @@ export function readableTimeline(events,{callPath,values=false}={}){
   for(const event of events??[]){
     if(callPath&&event.callPath!==callPath)continue;
     if(event.type==='log'&&event.stream){
-      const key=`${event.callPath}\0${event.stream}`;
+      const key=`${event.callPath}\0${event.processId??''}\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(event.type==='log'){
+      flush();const data=event.kind==='process'?readableProcess(event.data):readableValue(event.data,'',undefined,{compact:true,width:contentWidth(event),truncated:event.eventTruncated});
+      push(event,`${event.message??''}${event.data!==undefined?'\n'+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));
+        const action=actionFrom(catalog,event.action??actions.get(event.callPath));
+        if(event.input!==undefined)push(event,'输入\n'+readableValue(event.input,'',action?.input,{decodeStrings:false,compact:true,width:contentWidth(event)}));
+        if(event.output!==undefined){
+          const forwarded=forwardedReport(event.output,finalOutput);
+          const output=forwarded?(forwarded===event.output?undefined:Object.fromEntries(Object.entries(event.output).filter(([key])=>key!=='report'))):event.output;
+          if(forwarded)push(event,'报告已展示在本次运行的最终输出。');
+          if(output!==undefined&&(!forwarded||Object.keys(output).length))push(event,'输出（紧凑显示）\n'+readableValue(output,'',action?.output,{compact:true,width:contentWidth(event),truncated:event.eventTruncated}));
+        }
       }
     }
   }
   flush();return rows.join('\n')||'等待执行记录。插件通过 log 或 runProcess 输出的内容会显示在这里。';
 }
+const timestamp=value=>typeof value==='number'?value:typeof value==='string'?Date.parse(value):NaN;
+export function elapsedTime(record,now=Date.now()){
+  const start=timestamp(record?.startedAt),finish=timestamp(record?.finishedAt);
+  const end=record?.status==='running'||record?.status==='pending'?timestamp(now):finish;
+  const duration=Number.isFinite(start)&&Number.isFinite(end)?Math.max(0,end-start):record?.status!=='running'&&Number.isFinite(record?.durationMs)?Math.max(0,record.durationMs):undefined;
+  return duration===undefined?undefined:`${(duration/1000).toFixed(1)} 秒`;
+}
+export const runCategoryNames={workflow:'工作流',action:'插件动作',command:'插件命令',shell:'系统命令'};
+export function runCategory(run){return run.kind??(run.workflowId?.startsWith('!')?'shell':run.workflowId?.startsWith('/')?'command':run.workflowId?.includes(':')?'action':'workflow');}

package/manual/packages/fst-cli/src/terminal/run-viewer.js

@@ -1,17 +1,16 @@
-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';
+import {palette,cleanText as safe} from './theme.js';
+import {readableValue,readableError,readableTimeline,elapsedTime} from './run-presentation.js';
+import {outputReport} from './report-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;
+  constructor({record,flow,workflows=[],catalog=[],terminal,onClose,onCancel,onReadLogs,onReadOutput,now=Date.now,requestRender}){
+    Object.assign(this,{terminal,onClose,onCancel,onReadLogs,onReadOutput,now,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??[]){
@@ -27,6 +26,7 @@ export class RunViewer{
   invalidate(){}
   update(record){
     if(!record)return;
+    if(record.status!=='running')this.confirmCancel=false;
     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;
@@ -37,30 +37,48 @@ export class RunViewer{
     this.nodes=[...nodes.values()];this.selected=Math.max(0,Math.min(this.selected,this.nodes.length-1));
     this.requestRender();
   }
-  content(){
+  outputSchema(node){return this.catalog.find(action=>action.id===(node?.action??this.record.action??this.record.workflowId))?.output;}
+  getRenderedOutput(width=this.terminal.columns,{markdown=false}={}){
+    const node=this.view===0?undefined:this.nodes[this.selected],output=node?node.output:this.record.output,schema=this.outputSchema(node);
+    if(output&&typeof output==='object'&&!outputReport(output)){
+      if(typeof output.markdown==='string')return output.markdown;
+      for(const [key,value] of Object.entries(output))if(typeof value==='string'&&(schema?.properties?.[key]?.format==='markdown'||schema?.properties?.[key]?.contentMediaType==='text/markdown'))return value;
+    }
+    const text=readableValue(output,'',schema,{compact:true,width:markdown?Math.max(1,width-2):width,truncated:node?node.eventTruncated:this.record.outputTruncated});
+    if(!markdown)return text;
+    const fence='`'.repeat(Math.max(3,...[...text.matchAll(/`+/g)].map(match=>match[0].length+1)));
+    return `${fence}text\n${text}\n${fence}`;
+  }
+  content(width=this.terminal.columns){
     const node=this.nodes[this.selected],status=runStatuses[this.record.status]??this.record.status;
+    const elapsed=elapsedTime(this.record,this.now());
     if(this.view===0)return [
       `运行：${status}${this.record.reason?` · ${this.record.reason}`:''}`,
+      elapsed!==undefined?`耗时：${elapsed}`:'',
       this.record.error?readableError(this.record.error):'',
       ...(this.record.warnings??[]).map(warning=>`警告：${warning.message}`),
-      this.record.output!==undefined?'\n最终输出\n'+readableValue(this.record.output):'',
+      this.record.output!==undefined?'\n最终输出（紧凑显示）\n'+readableValue(this.record.output,'',this.outputSchema(),{compact:true,width,truncated:this.record.outputTruncated}):'',
+      this.record.resultDir?'\n生成文件：'+this.record.resultDir:'',
       '\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 action=this.catalog.find(action=>action.id===(node?.action??this.record.action??this.record.workflowId));
+      const format=(value,schema,{compact=false,decodeStrings=true}={})=>this.raw?JSON.stringify(value??null,null,2):readableValue(value,'',schema,{compact,decodeStrings,width,truncated:node?node.eventTruncated:compact?this.record.outputTruncated:this.record.inputTruncated});
       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),
+      const input=node?node.input:this.record.input!==undefined?this.record.input:this.record.events?.find(event=>event.type==='run.input')?.input;
+      return [`步骤：${node?.title??node?.callPath??'整个运行'}`,node?.title&&node.callPath?'调用路径：'+node.callPath:'',node?.action?'能力：'+node.action:'',error?'\n错误\n'+(this.raw?format(error):readableError(error)):'',
+        '\n输入\n'+format(input,action?.input,{decodeStrings:false}), '\n输出\n'+format(node?node.output:this.record.output,action?.output,{compact:true}),
         !error&&(node?.reason||node?.message)?'\n说明：'+(node.reason??node.message):'',this.raw?'\n原始 JSON · 包含完整错误详情与调用栈':'\nj 查看原始 JSON 与完整诊断',
+        this.onReadOutput?'m 格式化阅读输出':'',
       ].filter(Boolean).join('\n');
     }
-    return (this.record.eventsTruncated?'当前为近期日志摘要，按 p 分页查看完整落盘日志。\n\n':'')+readableTimeline(this.record.events,{callPath:this.allLogs?undefined:node?.callPath});
+    return (this.record.eventsTruncated?'当前为近期日志摘要，按 p 分页查看完整落盘日志。\n\n':'')+readableTimeline(this.record.events,{callPath:this.allLogs?undefined:node?.callPath,catalog:this.catalog,width});
   }
   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 lines=new Text(safe(this.content(width)),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};
@@ -70,7 +88,7 @@ export class RunViewer{
     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 footer=this.confirmCancel?'取消整个运行？y 确认 · 任意其他键返回':`q/Esc 返回${this.record.status==='running'?' · x 取消':''} · p 完整日志${this.onReadOutput?' · m 阅读输出':''} · 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));
@@ -79,7 +97,8 @@ export class RunViewer{
   }
   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(this.confirmCancel){this.confirmCancel=false;if(data==='y'&&this.record.status==='running')this.onCancel();this.requestRender();return;}
+    if(data==='m'&&this.onReadOutput){this.onReadOutput(this.getRenderedOutput());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;}

package/manual/packages/fst-cli/src/terminal/schema.js

@@ -1,18 +1,128 @@
-import { validate } from '@mytools/sdk/schema';
+import { validate, assertSchema } from '@mytools/sdk/schema';
+import {isDeepStrictEqual} from 'node:util';
 import { fileReference } from './model.js';
+import {readableValue} from './run-presentation.js';
+import {cleanText,fitLine} from './theme.js';
+import {visibleWidth} from '@mariozechner/pi-tui';
+import {hasInputRules,resolveInput} from '@mytools/sdk/inputs';
 
 export const needsJsonEditor=schema=>['oneOf','anyOf','allOf','if','$ref','patternProperties'].some(key=>schema?.[key]!==undefined);
 
+// 与执行时共用校验器；即使尚缺必填字段，也保留已能确定的默认值供编辑。
+function editableDefaults(schema,value){
+  const copy=structuredClone(value);
+  if(schema!=null)assertSchema(schema,'参数')(copy);
+  return copy;
+}
+
+export function inputEntries(schema,value,fields={}){
+  if(schema?.type!=='object'||!schema.properties||needsJsonEditor(schema))return [readableValue(value,'',schema,{decodeStrings:false})];
+  const names=new Set([...Object.keys(schema.properties),...Object.keys(value??{})]);
+  return [...names].map(name=>{
+    const field=fields[name],title=schema.properties[name]?.title??name;
+    if(value?.[name]===undefined)return `${title}：${schema.required?.includes(name)?'未填写（必填）':field?.unsetLabel??'未提供（插件未声明缺省行为）'}`;
+    const text=readableValue({[name]:value[name]},'',schema,{decodeStrings:false});
+    if(!field)return text;
+    const source=field?.source==='config'?'继承插件配置：':field?.source==='default'?'默认值：':field?.source==='input'?'本次输入：':'';
+    return `${title}：${source}${readableValue(value[name],'',schema.properties[name],{decodeStrings:false})}${field?.unit?' '+field.unit:''}${field?.path?'（'+field.path+'）':''}`;
+  });
+}
+
+function parameterPreview(entries,label,screenWidth=80,screenHeight=24){
+  const limit=Math.max(1,Math.min(4,screenHeight-10)),width=Math.max(8,screenWidth-6);
+  const values=entries.map(entry=>cleanText(entry).replace(/[\r\n\t]/g,' '));
+  let columns=width>=110?3:width>=60?2:1;
+  // 来源说明较长时减少列数，优先显示完整含义，仍保持预览行数有界。
+  while(columns>1&&values.some(value=>visibleWidth(value)>Math.floor((width-(columns-1)*3)/columns)))columns--;
+  const cellWidth=Math.floor((width-(columns-1)*3)/columns);
+  const cells=values.slice(0,limit*columns).map(entry=>fitLine(entry,cellWidth));
+  const rows=[];
+  for(let index=0;index<cells.length;index+=columns){
+    rows.push(cells.slice(index,index+columns).map((cell,i)=>i<columns-1?cell+' '.repeat(cellWidth-visibleWidth(cell)):cell).join('   '));
+  }
+  const preview=rows.join('\n')||'无需参数';
+  return {text:`${fitLine(cleanText(label??'插件能力').replace(/\s+/g,' '),width)}\n当前参数（含默认值）：\n${preview}`,truncated:values.length>cells.length||values.some(value=>visibleWidth(value)>cellWidth)||entries.some(entry=>/[\r\n\t]/.test(entry))};
+}
+
+export async function commandInput(ui,schema,value,{baseDir,label,preview}={}){
+  const rules=hasInputRules(schema),project=preview??(value=>resolveInput(schema,value,{}, {check:false}));
+  let current=rules?structuredClone(value):editableDefaults(schema,value);
+  while(true){
+    const resolved=rules?project(current):{value:current};
+    const entries=inputEntries(schema,resolved.value,resolved.fields),summary=entries.join('\n')||'无需参数';
+    const layout=()=>parameterPreview(entries,label,ui.terminal?.columns,ui.terminal?.rows);
+    const message=(width,height)=>parameterPreview(entries,label,width,height).text;
+    const choice=await ui.select(ui.terminal?message:message(),[
+      {value:'run',label:'执行'},
+      {value:'edit',label:'配置参数'},
+      ...(ui.viewMarkdown?[{value:'view',label:'展开未显示完整的参数',description:`共 ${entries.length} 项`,hidden:()=>!layout().truncated}]:[]),
+      {value:'cancel',label:'返回'},
+    ]);
+    if(choice==='cancel')return {cancelled:true};
+    if(choice==='view'){
+      // 保留换行和引号，参数里的 Markdown 符号不能改变显示含义。
+      let fenceLength=3;for(const match of summary.matchAll(/`+/g))fenceLength=Math.max(fenceLength,match[0].length+1);
+      const fence='`'.repeat(fenceLength);
+      await ui.viewMarkdown('当前参数（含默认值）',`${fence}text\n${summary}\n${fence}`);continue;
+    }
+    if(choice==='edit')current=await editInput(ui,schema,current,{baseDir,label,preview:project,required:true});
+    else if(choice==='run'){
+      try{
+        if(rules){validate(schema,project(current).value,label??'插件参数',{useDefaults:false});return {value:structuredClone(current)};}
+        return {value:validate(schema,current,label??'插件参数')};
+      }
+      catch(error){if(error.code!=='VALIDATION')throw error;ui.show(`暂不能执行，请配置参数：${error.message}`);}
+    }
+  }
+}
+
+// 能力调用和快捷名称保存使用同一编辑入口，省略值不因打开表单而固化。
+export async function editInput(ui,schema,value,options={}){
+  if(!hasInputRules(schema))return editValue(ui,schema,value,options);
+  return editInputRules(ui,schema,value,{...options,preview:options.preview??(value=>resolveInput(schema,value,{}, {check:false}))});
+}
+
+async function editInputRules(ui,schema,value,{baseDir,label,preview}){
+  const current=structuredClone(value);
+  while(true){
+    const resolved=preview(current),entries=inputEntries(schema,resolved.value,resolved.fields);
+    const names=Object.keys(schema.properties);
+    const choice=await ui.select(`${label??'参数'} · 选择字段`,[
+      ...names.map((name,index)=>({value:`field:${name}`,label:schema.properties[name].title??name,description:entries[index]})),
+      {value:'__done',label:'完成填写'},
+    ]);
+    if(choice==='__done'){
+      try{validate(schema,preview(current).value,label??'参数',{useDefaults:false});return current;}
+      catch(error){ui.show(error.message);continue;}
+    }
+    const name=choice.slice(6),field=schema.properties[name],rule=field['x-fst'];
+    if(rule){
+      const action=await ui.select(field.title??name,[{value:'set',label:'设置本次输入'},{value:'inherit',label:rule.fromConfig?'恢复继承插件配置':'恢复省略参数'},{value:'back',label:'返回'}]);
+      if(action==='back')continue;
+      if(action==='inherit'){delete current[name];continue;}
+    }
+    const next=await editValue(ui,field,resolved.value[name],{baseDir,label:field.title??name,required:schema.required?.includes(name)});
+    if(next===undefined)delete current[name];else Object.defineProperty(current,name,{value:next,enumerable:true,writable:true,configurable:true});
+  }
+}
+
 // 值只在整个编辑过程完成后返回，Escape 不会留下半个修改。
 export async function editValue(ui,schema={},value,{baseDir,required=false,label=schema.title??'值'}={}){
   if(value===undefined&&schema.default!==undefined)value=structuredClone(schema.default);
   if(schema.enum&&!needsJsonEditor(schema)){
-    const index=await ui.select(label,schema.enum.map((v,i)=>({value:String(i),label:JSON.stringify(v)})));
+    const choices=schema.enum.map((v,i)=>({value:String(i),label:JSON.stringify(v)}));
+    const selected=schema.enum.findIndex(item=>isDeepStrictEqual(item,value));
+    if(selected>0)choices.unshift(...choices.splice(selected,1));
+    const index=await ui.select(label,choices);
     return schema.enum[Number(index)];
   }
-  if(schema.type==='boolean'&&!needsJsonEditor(schema))return (await ui.select(label,[{value:'true',label:'是 / true'},{value:'false',label:'否 / false'}]))==='true';
+  if(schema.type==='boolean'&&!needsJsonEditor(schema)){
+    const choices=[{value:'true',label:'是 / true'},{value:'false',label:'否 / false'}];
+    if(value===false)choices.reverse();
+    return (await ui.select(label,choices))==='true';
+  }
   if(schema.type==='object'&&schema.properties&&!needsJsonEditor(schema)){
-    const result=structuredClone(value??{}),props=Object.entries(schema.properties);
+    const result=editableDefaults(schema,value??{}),props=Object.entries(schema.properties);
     while(true){
       const key=await ui.select(`${label} · 选择字段`,[
         ...props.map(([key,s])=>({value:`field:${key}`,label:`${s.title??key}${schema.required?.includes(key)?' *':''}`,description:JSON.stringify(result[key])??'未填写'})),

package/manual/packages/fst-cli/src/terminal/session-history.js

@@ -0,0 +1,82 @@
+import path from 'node:path';
+import {randomUUID} from 'node:crypto';
+import {createSessionHistory} from '@mytools/fst-logs/sessions';
+import {readableValue,readableError,runCategory,runCategoryNames,presentationCatalog} from './run-presentation.js';
+
+// 完整交互追加落盘，快照只保存可立即恢复的近期窗口，不重复保存运行日志全文。
+export class TerminalHistory{
+  constructor(app,ui){
+    this.app=app;this.ui=ui;this.id=app.sessionId??randomUUID();this.startedAt=new Date().toISOString();this.pending=Promise.resolve();
+    const directory=app.project.readOnly?path.join(app.outputDir,'sessions'):path.join(app.projectDir,'.flow','sessions');
+    this.store=createSessionHistory(directory,{projectDir:app.projectDir});
+  }
+  snapshot(){
+    const commands=[];let bytes=0;
+    for(const command of [...this.ui.commandHistory].reverse()){
+      const size=Buffer.byteLength(JSON.stringify(command));if(bytes+size>256*1024)continue;
+      commands.unshift(command);bytes+=size;if(commands.length===100)break;
+    }
+    return {schemaVersion:1,id:this.id,startedAt:this.startedAt,updatedAt:new Date().toISOString(),...(this.resumedFrom?{resumedFrom:this.resumedFrom}:{}),commandHistory:commands,feed:this.ui.feed.exportState()};
+  }
+  report(error){
+    if(this.reported)return;this.reported=true;this.reporting=true;
+    try{this.ui.show(`历史会话保存失败：${error.message}。当前操作可继续，退出前的会话可能无法完整恢复。`);}
+    finally{this.reporting=false;}
+  }
+  async start(){
+    await this.store.save(this.snapshot());
+    this.ui.feed.onEntry=entry=>this.append(entry);
+    this.ui.onHistoryChange=()=>this.schedule();
+  }
+  append(entry){
+    if(this.reporting||this.closed)return;
+    const entries=[];
+    if(entry.type==='message'){
+      // 按字符切分完整命令及反馈，避免单条 JSON 或待写内存无限增长。
+      for(let offset=0;offset<entry.text.length;){
+        let end=Math.min(offset+8192,entry.text.length);
+        if(end<entry.text.length&&entry.text.charCodeAt(end-1)>=0xd800&&entry.text.charCodeAt(end-1)<=0xdbff&&entry.text.charCodeAt(end)>=0xdc00&&entry.text.charCodeAt(end)<=0xdfff)end--;
+        entries.push({...entry,text:entry.text.slice(offset,end),continuation:offset>0});offset=end;
+      }
+    }else entries.push(entry);
+    for(const value of entries){
+      const saved={...value,time:new Date().toISOString()};
+      // 直接进入 logs 的有界队列，不能在界面层用无限 Promise 链藏住待写数据。
+      const job=this.store.append(this.id,saved).catch(error=>this.report(error));this.pending=Promise.all([this.pending,job]).then(()=>{});
+    }
+    this.schedule();
+  }
+  schedule(){
+    if(this.closed||this.reporting||this.timer)return;
+    this.timer=setTimeout(()=>{this.timer=null;void this.flush();},250);this.timer.unref?.();
+  }
+  async flush(){
+    if(this.timer){clearTimeout(this.timer);this.timer=null;}
+    // 快照在调用时复制，保存排在已收到的交互之后；关闭时可等待同一条队列。
+    const snapshot=this.snapshot(),job=this.store.save(snapshot).catch(error=>this.report(error));this.pending=Promise.all([this.pending,job]).then(()=>{});await this.pending;
+  }
+  async restore(record){
+    if(this.app.listRuns().some(run=>run.status==='running'))throw new Error('当前有运行中的任务，完成后再恢复历史会话。');
+    await this.flush();this.resumedFrom=record.id;
+    this.ui.commandHistory=[...record.commandHistory];this.ui.commandHistoryIndex=null;
+    this.ui.feed.restoreState(record.feed,{catalog:presentationCatalog(this.app)});
+    this.append({type:'restored',sessionId:record.id});await this.flush();
+  }
+  async close(){await this.flush();this.closed=true;this.ui.feed.onEntry=null;this.ui.onHistoryChange=null;}
+}
+
+export function sessionPageText(entries){
+  const joined=[];
+  for(const entry of entries){
+    const previous=joined.at(-1);
+    if(entry.type==='message'&&entry.continuation&&previous?.type==='message')previous.text+=entry.text;
+    else joined.push({...entry});
+  }
+  return joined.map(entry=>{
+    if(entry.type==='message')return entry.text;
+    if(entry.type==='restored')return `恢复并继续会话：${entry.sessionId}`;
+    const run=entry.run;if(!run)return '';
+    const header=`${entry.type==='start'?'开始':'结果'} · ${runCategoryNames[runCategory(run)]} · ${run.title??run.workflowId} · ${run.id}`;
+    return [header,run.input!==undefined?'输入\n'+readableValue(run.input):'',run.output!==undefined?'输出\n'+readableValue(run.output):'',run.error&&readableError(run.error),`/logs 可查看该次运行的完整日志和步骤详情`].filter(Boolean).join('\n');
+  }).filter(Boolean).join('\n\n');
+}