@yanglaofish/fishtools 0.5.1 → 0.5.2

package/manual/packages/core/package.json

@@ -22,6 +22,7 @@
     "node": ">=24.15.0"
   },
   "dependencies": {
+    "@mytools/commands": "0.1.0",
     "@mytools/sdk": "0.1.0",
     "@mytools/fst-platform": "0.1.0",
     "@mytools/fst-logs": "0.1.0",

package/manual/packages/core/src/application.js

@@ -1,4 +1,4 @@
-import { mkdir, readFile, writeFile, rename } from 'node:fs/promises';
+import { mkdir, readFile, writeFile, rename, rm } from 'node:fs/promises';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { EventEmitter } from 'node:events';
@@ -7,6 +7,9 @@ import { createHost } from '@mytools/fst-plugin';
 import { WorkflowStore } from '@mytools/fst-workspace/workflows';
 import { runWorkflow } from '@mytools/fst-workflow';
 import { runProcess } from '@mytools/fst-platform';
+import {runShell} from '@mytools/fst-platform/shell';
+import {COMMANDS_PLUGIN_ID,commandsPluginRoot,createCommandsPlugin,validateCommandPresets} from '@mytools/commands';
+import {validateShortcuts,describeShortcuts,bindShortcutCommands} from '@mytools/fst-workspace/shortcuts';
 import {createFileProbe} from '@mytools/fst-platform/fs';
 import {readJson} from '@mytools/fst-platform/json';
 import {loadPlugin} from '@mytools/fst-plugin/loader';
@@ -20,9 +23,22 @@ import {createExportSnapshot} from './export-snapshot.js';
 import {createRunLogs,validateKeepRuns} from '@mytools/fst-logs';
 import {openPluginState,withPluginMutation,assertPluginState,savePluginState,leaseInstallation} from '@mytools/fst-workspace/installations';
 import {planPluginUpdate,changedPluginSources} from './plugin-update.js';
-import {validateNetworkPolicy,inspectNetworkPolicy} from '@mytools/fst-platform/network';
+import {validateNetworkPolicy,inspectNetworkPolicy,resolveNetworkPolicy,buildProcessEnv} from '@mytools/fst-platform/network';
 import {resolvePrivilegeRequirement,checkStaticPrivilege} from '@mytools/fst-plugin/privileges';
 
+function declaredCommands(entries){
+  return entries.flatMap(entry=>{const plugin=entry.plugin??entry;return Object.keys(plugin.commands??{}).map(name=>({name,plugin:plugin.id}));});
+}
+
+function workflowActions(steps,found=new Set()){
+  for(const step of steps??[]){
+    if(step.action)found.add(step.action);
+    if(step.branch){workflowActions(step.branch.then,found);workflowActions(step.branch.else,found);}
+    if(step.parallel)workflowActions(step.parallel.steps,found);
+  }
+  return found;
+}
+
 export async function createApplication({projectDir=process.cwd(),workspace,outputDir,plugins,config={},maintenance=false,omitInstalledPlugin,allowUnknownPrivileges=false}={}) {
   projectDir=await prepareBundleWorkspace(path.resolve(projectDir),workspace);
   const project=await readJson(path.join(projectDir,'flow.project.json'),{plugins:[]});
@@ -47,9 +63,14 @@ export async function createApplication({projectDir=process.cwd(),workspace,outp
     catalog:()=>host.catalog(),
     listPlugins:()=>[...host.definitions.values()].map(p=>({id:p.id,version:p.version,title:p.title,description:p.description,platforms:p.platforms,architectures:p.architectures,environments:p.environments,config:p.config,requirements:p.requirements,privileges:pluginPrivileges(p),runtime:{...host.runtimeStatus().find(r=>r.id===p.id),...(p.runtime?{updatePolicy:p.runtime.updatePolicy??'maintenance'}:{})},removable:!!(state.dependencies?.[p.id]||state.links?.[p.id]),development:!!state.links?.[p.id],warnings:host.warnings.filter(item=>item.plugin===p.id).map(item=>item.message)})),
     listCommands:()=>host.commands(),
+    listShortcuts:()=>describeShortcuts(project.shortcuts??{},{actions:host.catalog(),commands:host.commands()}),
+    async configureShortcuts(value){return updateUserCommands({shortcuts:value});},
+    async configureCommandPresets(value,options={}){
+      return updateUserCommands({commandPresets:value,...(options.shortcuts!==undefined?{shortcuts:options.shortcuts}:{})},options);
+    },
     listWorkflows:()=>store.list(),
-    async saveWorkflow(w){return mutateWorkflow(()=>store.save(w));},
-    async duplicateWorkflow(definition,options){return mutateWorkflow(()=>store.duplicate(definition,options));},
+    async saveWorkflow(w){return mutateWorkflow(()=>store.save(w),w);},
+    async duplicateWorkflow(definition,options){return mutateWorkflow(()=>store.duplicate(definition,options),definition);},
     async removeWorkflow(id){return mutateWorkflow(()=>store.remove(id));},
     async checkWorkflow(id){
       host.assertHealthy();
@@ -71,7 +92,29 @@ export async function createApplication({projectDir=process.cwd(),workspace,outp
     async startCommand(name,input={},context={}){
       if(busy)throw new FlowError('插件更新中，请稍后调用');
       const networkPolicy=structuredClone(project.network??{});
-      return app.executeTracked(`/${name}`,(activeHost,runContext)=>activeHost.invokeCommand(name,input,{...context,...runContext,networkPolicy}));
+      return app.executeTracked(`/${name}`,(activeHost,runContext)=>{
+        if(context.expectedPlugin!==undefined&&!activeHost.commands().some(command=>command.name===name&&command.plugin===context.expectedPlugin)){
+          throw new FlowError('命令目标插件已变更，请重新选择目标后执行',{code:'COMMAND_TARGET_CHANGED',details:{command:name,plugin:context.expectedPlugin}});
+        }
+        return activeHost.invokeCommand(name,input,{...context,...runContext,networkPolicy});
+      });
+    },
+    async startAction(id,input={},context={}){
+      if(busy)throw new FlowError('插件更新中，请稍后调用');
+      const networkPolicy=structuredClone(project.network??{});
+      return app.executeTracked(id,(activeHost,runContext)=>activeHost.invoke(id,input,{...context,...runContext,networkPolicy}));
+    },
+    async startShell(script,{shell='auto',timeout=30000}={}){
+      if(busy)throw new FlowError('项目更新中，请稍后执行命令');
+      if(!Number.isSafeInteger(timeout)||timeout<0||timeout>2147483647)throw new FlowError('命令超时必须为 0 到 2147483647 毫秒，0 表示不限时',{code:'VALIDATION'});
+      const policy=resolveNetworkPolicy(structuredClone(project.network??{}));
+      const env=buildProcessEnv(policy);
+      return app.executeTracked('!命令',async(_host,context)=>{
+        const result=await runShell(script,{shell,temporaryDir:context.outputDir,cwd:projectDir,env,extendEnv:false,signal:context.signal,timeout,outputMode:'stream',summaryBytes:65536,
+          onOutput:({stream,message})=>context.log(message,undefined,{stream})});
+        if(result.exitCode!==0)throw new FlowError(`命令执行失败，退出码 ${result.exitCode}`,{code:'EXECUTION_FAILED',details:result});
+        return result;
+      });
     },
     async executeTracked(id,execute){
       const runId=randomUUID(),controller=new AbortController();
@@ -245,7 +288,11 @@ export async function createApplication({projectDir=process.cwd(),workspace,outp
   let initial;
   const services={application:app,runProcess,fs:fileProbe};
   const hostProject=()=>({directory:projectDir,readOnly:!!project.readOnly});
-  const build=extra=>createHost({plugins:[...initial,...extra],config:{...project.config,...config},services,project:hostProject(),network:()=>project.network,environmentOverrides:project.environments,runtimeEnabled:!maintenance,allowUnknownPrivileges});
+  const build=extra=>{
+    const entries=entriesWithPresets([...initial,...extra],project.commandPresets??{});
+    validateShortcuts(project.shortcuts??{},{reservedNames:declaredCommands(entries).map(command=>command.name)});
+    return createHost({plugins:entries,config:{...project.config,...config},services,project:hostProject(),network:()=>project.network,environmentOverrides:project.environments,runtimeEnabled:!maintenance,allowUnknownPrivileges});
+  };
   try{
     initial=plugins??await Promise.all((project.plugins??[]).map(spec=>loadPlugin(spec,project.baseBundle?.root??projectDir)));
     const external=[];
@@ -253,8 +300,8 @@ export async function createApplication({projectDir=process.cwd(),workspace,outp
     for(const [name,source] of Object.entries(state.links??{}))if(!maintenance||name!==omitInstalledPlugin)external.push(await loadPlugin(source,projectDir));
     host=await build(external);
   }catch(error){await fileProbe.close();await opened.release();throw error;}
-  for(const name of ['startRun','startCommand','startWeb','saveWorkflow','duplicateWorkflow','removeWorkflow','installPlugin','linkPlugin','removePlugin','configurePlugin','configureNetworkPolicy','configureLogs','setMaintenance','pack']){
-    const original=app[name],isRun=['startRun','startCommand'].includes(name);
+  for(const name of ['startRun','startCommand','startAction','startShell','startWeb','saveWorkflow','duplicateWorkflow','removeWorkflow','installPlugin','linkPlugin','removePlugin','configurePlugin','configureNetworkPolicy','configureLogs','configureCommandPresets','configureShortcuts','setMaintenance','pack']){
+    const original=app[name],isRun=['startRun','startCommand','startAction','startShell'].includes(name);
     app[name]=async(...args)=>{
       if(closing)throw new FlowError('应用已关闭');
       if(isRun)launching++;
@@ -262,11 +309,16 @@ export async function createApplication({projectDir=process.cwd(),workspace,outp
       try{return await task;}finally{operations.delete(task);if(isRun)launching--;}
     };
   }
-  async function mutateWorkflow(operation){
+  async function mutateWorkflow(operation,definition){
     if(project.readOnly)throw new FlowError('只读运行包不能修改工作流');
     if(busy)throw new FlowError('插件变更期间暂不能修改工作流',{code:'PLUGIN_BUSY'});
     return withPluginMutation(projectDir,async()=>{
       await assertPluginState(projectDir,state);
+      if(definition){
+        const workflow=store.validateShape(definition),latest=await readJson(path.join(projectDir,'flow.project.json'),project);
+        const missing=[...workflowActions(workflow.steps)].filter(id=>id.startsWith(`${COMMANDS_PLUGIN_ID}:`)&&!Object.hasOwn(latest.commandPresets??{},id.slice(COMMANDS_PLUGIN_ID.length+1)));
+        if(missing.length)throw new FlowError('引用的注册命令已删除，请重新选择动作后保存',{code:'COMMAND_NOT_FOUND',details:{actions:missing}});
+      }
       return operation();
     });
   }
@@ -280,6 +332,55 @@ export async function createApplication({projectDir=process.cwd(),workspace,outp
     await writeFile(backup,original,{flag:'wx',mode:0o600});
     return backup;
   }
+  function entriesWithPresets(entries,presets){
+    const definition=createCommandsPlugin(presets);
+    const result=entries.filter(entry=>(entry.plugin??entry).id!==COMMANDS_PLUGIN_ID);
+    if(Object.keys(definition.actions).length)result.push({plugin:definition,root:commandsPluginRoot});
+    return result;
+  }
+  async function updateUserCommands(changes,options={}){
+    if(project.readOnly)throw new FlowError('只读运行包不能修改注册命令或快捷名称');
+    if(busy||launching||app.listRuns().some(run=>run.status==='running'))throw new FlowError('请等待运行或安装结束');
+    const requested=structuredClone(changes);
+    if(Object.hasOwn(requested,'commandPresets'))requested.commandPresets=validateCommandPresets(requested.commandPresets);
+    busy=true;
+    try{return await withPluginMutation(projectDir,async()=>{
+      await assertPluginState(projectDir,state);
+      const file=path.join(projectDir,'flow.project.json'),latest=await readJson(file,project);
+      if(latest.readOnly)throw new FlowError('只读运行包不能修改注册命令或快捷名称');
+      for(const field of Object.keys(requested))if(!isDeepStrictEqual(latest[field]??{},project[field]??{})){
+        throw new FlowError('注册命令或快捷名称已被另一实例修改，请重新打开工作区再保存',{code:'USER_COMMANDS_CONFLICT',details:{field}});
+      }
+      const nextProject={...latest,...requested};
+      const presets=validateCommandPresets(nextProject.commandPresets??{});
+      const oldEntries=[...host.definitions.values()].map(plugin=>({plugin,root:plugin.root}));
+      const entries=entriesWithPresets(oldEntries,presets);
+      const reservedNames=declaredCommands(entries).map(command=>command.name);
+      const shortcuts=Object.hasOwn(requested,'shortcuts')?bindShortcutCommands(nextProject.shortcuts??{},{commands:declaredCommands(entries),previous:latest.shortcuts??{}}):nextProject.shortcuts??{};
+      nextProject.shortcuts=validateShortcuts(shortcuts,{reservedNames});
+      const removed=new Set(Object.keys(project.commandPresets??{}).filter(id=>!Object.hasOwn(presets,id)).map(id=>`${COMMANDS_PLUGIN_ID}:${id}`));
+      if(removed.size){
+        const workflows=(await findPluginWorkflowReferences(COMMANDS_PLUGIN_ID)).filter(workflow=>workflow.actions.some(action=>removed.has(action)));
+        if(workflows.length)throw new FlowError(`命令仍被工作流使用：${workflows.map(workflow=>workflow.title).join('、')}`,{code:'COMMAND_IN_USE',details:{workflows}});
+      }
+      const effectiveConfig={...latest.config,...config},oldConfig={...project.config,...config};
+      const nextDefinitions=new Map(entries.map(entry=>{const plugin=entry.plugin??entry;return [plugin.id,plugin];}));
+      const changed=new Set(isDeepStrictEqual(presets,project.commandPresets??{})?[]:[COMMANDS_PLUGIN_ID]);
+      const plan=planPluginUpdate(host.definitions,nextDefinitions,oldConfig,effectiveConfig,changed);
+      assertMaintenance(plan,options);
+      const backup=await backupProjectFile(file,latest,'commands');
+      if(plan.affected.length)await host.replace({plugins:entries,config:effectiveConfig,affected:plan.affected});
+      const temp=`${file}.${randomUUID()}.tmp`;
+      try{await writeFile(temp,JSON.stringify(nextProject,null,2));await rename(temp,file);}
+      catch(error){
+        if(plan.affected.length)try{await host.replace({plugins:oldEntries,config:oldConfig,affected:plan.affected});}
+        catch(recovery){host.invalidate();throw new AggregateError([error,recovery],`命令设置保存失败且恢复失败：${error.message}；${recovery.message}`);}
+        throw error;
+      }finally{await rm(temp,{force:true});}
+      for(const key of Object.keys(project))delete project[key];Object.assign(project,nextProject);
+      return {backup,commandPresets:structuredClone(presets),shortcuts:structuredClone(nextProject.shortcuts)};
+    });}finally{busy=false;}
+  }
   function pluginPrivileges(plugin){
     const report=action=>{
       const requirement=resolvePrivilegeRequirement(plugin,action);
@@ -327,14 +428,9 @@ export async function createApplication({projectDir=process.cwd(),workspace,outp
   }
   async function findPluginWorkflowReferences(id){
     const refs=[];
-    const collect=(steps,found)=>{for(const step of steps??[]){
-      if(typeof step.action==='string'&&step.action.startsWith(`${id}:`))found.add(step.action);
-      if(step.branch){collect(step.branch.then,found);collect(step.branch.else,found);}
-      if(step.parallel)collect(step.parallel.steps,found);
-    }};
     for(const workflow of await store.list()){
-      const found=new Set();collect(workflow.steps,found);
-      if(found.size)refs.push({id:workflow.id,title:workflow.title??workflow.id,actions:[...found]});
+      const actions=[...workflowActions(workflow.steps)].filter(action=>action.startsWith(`${id}:`));
+      if(actions.length)refs.push({id:workflow.id,title:workflow.title??workflow.id,actions});
     }
     return refs;
   }
@@ -371,8 +467,9 @@ export async function createApplication({projectDir=process.cwd(),workspace,outp
         if(workflows.length&&!options.force)throw new FlowError(`插件 ${name} 仍被工作流引用：${workflows.map(w=>w.id).join('、')}`,{code:'PLUGIN_IN_USE',details:{workflows}});
       }
       const next=await installGeneration(projectDir,{...operation,state});
-      const nextEntries=[...initial,...next.loaded],activeConfig={...project.config,...config},effectiveConfig={...latest.config,...config};
+      const nextEntries=entriesWithPresets([...initial,...next.loaded],latest.commandPresets??{}),activeConfig={...project.config,...config},effectiveConfig={...latest.config,...config};
       candidate=await createHost({plugins:nextEntries,config:effectiveConfig,services,project:hostProject(),network:()=>project.network,environmentOverrides:project.environments,runtimeEnabled:false,allowUnknownPrivileges});
+      validateShortcuts(latest.shortcuts??{},{reservedNames:declaredCommands(nextEntries).map(command=>command.name)});
       const sourceChanges=await changedPluginSources(host.definitions,candidate.definitions,{oldInstallationRoot:state.root,newInstallationRoot:next.state.root});
       const plan=planPluginUpdate(host.definitions,candidate.definitions,activeConfig,effectiveConfig,sourceChanges);
       assertMaintenance(plan,options);

package/manual/packages/core/src/export-snapshot.js

@@ -1,5 +1,6 @@
 import {fileURLToPath} from 'node:url';
 import {FlowError} from '@mytools/sdk';
+import {COMMANDS_PLUGIN_ID} from '@mytools/commands';
 
 function selectedNetwork(network,ids){
   if(!network)return undefined;
@@ -28,6 +29,24 @@ export async function createExportSnapshot({store,host,project},{entries,portabl
   for(const id of closure.plugins)ids.add(id);
   if(includeWeb){if(!web)throw new FlowError('未安装提供 Web 服务的插件');ids.add(web.id);}
   for(const id of ids)for(const dependency of Object.keys(host.definitions.get(id)?.dependencies??{}))ids.add(dependency);
+  const usedActions=new Set();
+  const scan=steps=>{for(const step of steps??[]){
+    if(step.action)usedActions.add(step.action);
+    if(step.branch){scan(step.branch.then);scan(step.branch.else);}
+    if(step.parallel)scan(step.parallel.steps);
+  }};
+  for(const workflow of closure.workflows)scan(workflow.steps);
+  const commandPresets=Object.fromEntries(Object.entries(project.commandPresets??{}).filter(([id])=>ids.has(COMMANDS_PLUGIN_ID)&&(portable||usedActions.has(`${COMMANDS_PLUGIN_ID}:${id}`))));
+  const commandAllowed=id=>!id.startsWith(`${COMMANDS_PLUGIN_ID}:`)||Object.hasOwn(commandPresets,id.slice(COMMANDS_PLUGIN_ID.length+1));
+  const commands=new Map(host.commands().map(command=>[command.name,command]));
+  const shortcuts=Object.fromEntries(Object.entries(project.shortcuts??{}).filter(([,target])=>{
+    if(target.action){
+      const action=host.actions.get(target.action);
+      return action&&ids.has(action.plugin)&&commandAllowed(target.action);
+    }
+    const command=commands.get(target.command);
+    return command&&target.plugin===command.plugin&&ids.has(command.plugin)&&(!command.action||commandAllowed(`${command.plugin}:${command.action}`));
+  }));
   const plugins=[...ids].map(id=>{
     const p=host.definitions.get(id);
     if(!p?.root)throw new FlowError('内存中临时定义的插件不能打包，请先安装为标准包');
@@ -37,6 +56,6 @@ export async function createExportSnapshot({store,host,project},{entries,portabl
       ['actions',Object.fromEntries(Object.entries(p.actions??{}).map(([name,action])=>[name,{environments:action.environments,requirements:action.requirements}]))],
     ]);
   });
-  return structuredClone({entries,closure,plugins,project:{environments:project.environments,network:selectedNetwork(project.network,ids),logs:project.logs,baseBundle:project.baseBundle},
+  return structuredClone({entries,closure,plugins,project:{environments:project.environments,network:selectedNetwork(project.network,ids),logs:project.logs,baseBundle:project.baseBundle,commandPresets,shortcuts},
     toolRoot:fileURLToPath(new URL('../../fst-cli',import.meta.url))});
 }

package/manual/packages/core/src/version.js

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

package/manual/packages/fst-cli/README.md

@@ -33,6 +33,8 @@ fst 命令入口、交互终端、输入呈现和运行观察。通过公开应
 
 ## 维护与验证
 
+TUI 支持 `!` 系统命令、`/commands` 常用命令注册和 `/shortcuts` 任意插件能力快捷名。主输入框与命令编辑框使用 Shift+Enter / Alt+Enter 换行、Enter 提交；真实多行粘贴保持换行及缩进。使用说明可通过 `fst docs commands` 离线阅读。
+
 本模块负责上述职责的实现、文档与回归；跨模块接口调整需要同时检查生产者与消费者。具体维护人员尚未指定。
 
 在仓库根目录执行：

package/manual/packages/fst-cli/src/terminal/command-menu.js

@@ -0,0 +1,186 @@
+import {randomUUID} from 'node:crypto';
+import {isCommandName} from '@mytools/fst-plugin/contracts';
+import {editValue} from './schema.js';
+
+export async function runShortcut(session,entry,args=[]){
+  if(!entry.available)throw new Error(`快捷名称 /${entry.name} 已失效：${entry.reason??'目标不存在'}`);
+  const {app}=session,target=entry.target;
+  if(target.command){
+    const command=app.listCommands().find(command=>command.name===target.command&&command.plugin===target.plugin);
+    if(!command)throw new Error(`快捷名称 /${entry.name} 的目标命令不存在`);
+    return session.pluginCommand({...command,name:entry.name,targetName:command.name,shortcutInput:entry.input??{}},args);
+  }
+  const action=app.catalog().find(action=>action.id===target.action);
+  if(!action)throw new Error(`快捷名称 /${entry.name} 的目标动作不存在`);
+  const plugin=action.plugin??action.id.slice(0,action.id.lastIndexOf(':'));
+  return session.pluginCommand({...action,name:entry.name,plugin,action:action.id.slice(plugin.length+1),actionId:action.id,shortcutInput:entry.input??{}},args);
+}
+
+async function parameters(session,value={}){
+  const result=structuredClone(value),{ui}=session;
+  for(;;){
+    const choice=await ui.select('命令参数（脚本通过 FST_INPUT_参数名 环境变量读取）',[
+      ...Object.entries(result).map(([name,field])=>({value:`field:${name}`,label:field.title??name,description:`${name} · ${field.type}`})),
+      {value:'new',label:'添加参数'},{value:'back',label:'完成参数设置'},
+    ]);
+    if(choice==='back')return result;
+    const existing=choice.startsWith('field:')?choice.slice(6):undefined;
+    if(existing){
+      const operation=await ui.select(`参数 ${existing}`,[{value:'edit',label:'编辑'},{value:'remove',label:'删除'},{value:'back',label:'返回'}]);
+      if(operation==='back')continue;
+      if(operation==='remove'){delete result[existing];continue;}
+    }
+    const name=existing??(await ui.input('参数名（英文字母、数字、下划线，不能以数字开头）',{files:false})).trim();
+    if(!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)||['__proto__','constructor','prototype'].includes(name)){ui.show('参数名无效，请重新填写。');continue;}
+    if(!existing&&Object.hasOwn(result,name)){ui.show('参数名已经存在。');continue;}
+    const title=await ui.input('参数显示名称',{value:result[name]?.title??name,files:false});
+    const type=await ui.select('参数类型',[{value:'string',label:'文本'},{value:'number',label:'数字'},{value:'boolean',label:'是 / 否'}]);
+    const field={title,type,required:await ui.confirm('这个参数必须填写吗？')};
+    if(await ui.confirm('设置默认值吗？'))field.default=await editValue(ui,{type},result[name]?.default,{baseDir:session.baseDir,required:true,label:'默认值'});
+    result[name]=field;
+  }
+}
+
+async function editPreset(session,id,current){
+  const {ui,app}=session,preset=structuredClone(current??{shell:'auto'});
+  preset.title=(await ui.input('常用命令名称',{value:preset.title??'',files:false})).trim();
+  preset.script=await ui.input('命令文本 · Shift+Enter 换行，Enter 提交（Alt+Enter 备用）',{value:preset.script??'',files:false,multiline:true});
+  const action=`@mytools/commands:${id}`;
+  const oldName=Object.keys(app.project.shortcuts??{}).find(name=>app.project.shortcuts[name].action===action);
+  let shortcut=oldName??(isCommandName(preset.title)?preset.title:'');
+  for(;;){
+    const choice=await ui.select('常用命令设置',[
+      {value:'save',label:'保存',description:shortcut?`快捷执行 /${shortcut}`:'只注册工作流动作'},
+      {value:'title',label:'修改名称'},{value:'script',label:'编辑多行命令'},
+      {value:'shortcut',label:'快捷名称',description:shortcut||'未设置'},
+      {value:'shell',label:'命令解释器',description:preset.shell??'auto'},
+      {value:'timeout',label:'超时时间',description:preset.timeout===0?'不限时':`${(preset.timeout??30000)/1000} 秒`},
+      {value:'parameters',label:'参数',description:`${Object.keys(preset.parameters??{}).length} 项，可不设置`},
+      {value:'root',label:'Linux root 权限要求',description:preset.requireRoot?'需要 root':'按当前用户权限执行'},
+      {value:'back',label:'取消，返回'},
+    ]);
+    if(choice==='back')return;
+    if(choice==='title')preset.title=(await ui.input('常用命令名称',{value:preset.title,files:false})).trim();
+    else if(choice==='script')preset.script=await ui.input('命令文本 · Shift+Enter 换行，Enter 提交（Alt+Enter 备用）',{value:preset.script,files:false,multiline:true});
+    else if(choice==='shortcut')shortcut=(await ui.input('快捷名称（支持中文，不含空格或 /；留空不设置）',{value:shortcut,files:false})).trim();
+    else if(choice==='shell')preset.shell=await ui.select('命令解释器',[
+      {value:'auto',label:'按系统选择（Windows PowerShell / Linux sh）'},
+      {value:'powershell',label:'Windows PowerShell'},{value:'pwsh',label:'PowerShell 7（pwsh）'},
+      {value:'sh',label:'sh'},{value:'bash',label:'bash'},
+    ]);
+    else if(choice==='timeout'){
+      const seconds=Number(await ui.input('超时时间（秒，0 表示不限时）',{value:String((preset.timeout??30000)/1000),files:false}));
+      if(!Number.isFinite(seconds)||!Number.isSafeInteger(seconds*1000)||seconds<0||seconds*1000>2147483647){ui.show('超时时间无效。');continue;}
+      preset.timeout=seconds*1000;
+    }else if(choice==='parameters')preset.parameters=await parameters(session,preset.parameters);
+    else if(choice==='root')preset.requireRoot=await ui.confirm('这个命令在 Linux 上必须使用 root 吗？执行前会检查，不会自动提权。');
+    else if(choice==='save'){
+      const next={...app.project.commandPresets,[id]:preset},shortcuts=structuredClone(app.project.shortcuts??{});
+      if(oldName)delete shortcuts[oldName];
+      if(shortcut){
+        if(Object.hasOwn(shortcuts,shortcut)){ui.show(`快捷名称 /${shortcut} 已存在，请选择其他名称。`);continue;}
+        shortcuts[shortcut]={...(oldName?app.project.shortcuts[oldName]:{}),action};
+      }
+      try{
+        const result=await session.withMaintenance(options=>app.configureCommandPresets(next,{...options,shortcuts}));
+        if(result===null){ui.show('已取消保存。');continue;}
+        ui.show(`常用命令已保存，修改前配置已备份。${shortcut?`输入 /${shortcut} 可直接运行。`:''}也可在工作流中添加此动作。`);
+        return;
+      }catch(error){ui.show(`保存失败：${error.message}`);}
+    }
+  }
+}
+
+export async function commandPresetsMenu(session){
+  const {app,ui}=session;
+  for(;;){
+    const choice=await ui.select('常用命令',[
+      ...(!app.project.readOnly?[{value:'new',label:'注册常用命令'}]:[]),
+      ...Object.entries(app.project.commandPresets??{}).map(([id,preset])=>({value:`preset:${id}`,label:preset.title,description:id})),
+      {value:'back',label:'返回主面板'},
+    ]);
+    if(choice==='back')return;
+    if(choice==='new'){session.writable();await editPreset(session,`command-${randomUUID().slice(0,8)}`);continue;}
+    const id=choice.slice(7),preset=app.project.commandPresets?.[id];if(!preset)continue;
+    const operation=await ui.select(preset.title,[{value:'run',label:'运行'},
+      ...(!app.project.readOnly?[{value:'edit',label:'编辑'},{value:'remove',label:'删除注册项'}]:[]),{value:'back',label:'返回'}]);
+    if(operation==='run')await runShortcut(session,{name:preset.title,target:{action:`@mytools/commands:${id}`},input:{},available:true});
+    else if(operation==='edit'){session.writable();await editPreset(session,id,preset);}
+    else if(operation==='remove'){
+      session.writable();if(!await ui.confirm(`删除 ${preset.title}？指向它的快捷名称会显示失效；引用中的工作流需先调整。`))continue;
+      const next=structuredClone(app.project.commandPresets);delete next[id];
+      try{const result=await session.withMaintenance(options=>app.configureCommandPresets(next,options));if(result!==null)ui.show('注册项已删除，修改前配置已备份。');}
+      catch(error){ui.show(`删除失败：${error.message}`);}
+    }
+  }
+}
+
+function targets(app){
+  return [...app.catalog().map(action=>({value:`action:${action.id}`,label:`动作：${action.title??action.id}`,description:action.id})),
+    ...app.listCommands().map(command=>({value:`command:${command.name}`,label:`命令：/${command.name}`,description:command.description}))];
+}
+function shortcutTarget(app,selected){
+  if(selected.startsWith('action:'))return {action:selected.slice(7)};
+  const name=selected.slice(8),command=app.listCommands().find(command=>command.name===name);
+  if(!command)throw new Error('目标命令已失效，请重新选择');
+  return {command:name,plugin:command.plugin};
+}
+async function editShortcut(session,oldName){
+  const {app,ui}=session,old=app.project.shortcuts?.[oldName];
+  let name=(await ui.input('快捷名称（支持中文，不含空格或 /）',{value:oldName??'',files:false})).trim();
+  let target=old?structuredClone(old):{};
+  if(!old){
+    const choices=targets(app);if(!choices.length){ui.show('当前没有可选择的插件动作或命令。');return;}
+    const selected=await ui.select('选择快捷名称指向的能力',choices);
+    target=shortcutTarget(app,selected);
+  }
+  for(;;){
+    const choice=await ui.select(`快捷名称 /${name}`,[
+      {value:'save',label:'保存'},{value:'name',label:'修改快捷名称'},
+      {value:'target',label:'选择目标',description:target.action??target.command},
+      {value:'input',label:'设置默认参数',description:'可留空，运行时按需要填写'},
+      {value:'back',label:'取消，返回'},
+    ]);
+    if(choice==='back')return;
+    if(choice==='name')name=(await ui.input('快捷名称',{value:name,files:false})).trim();
+    else if(choice==='target'){
+      const selected=await ui.select('选择目标',targets(app));
+      target=shortcutTarget(app,selected);
+    }else if(choice==='input'){
+      const metadata=target.action?app.catalog().find(action=>action.id===target.action):app.listCommands().find(command=>command.name===target.command&&command.plugin===target.plugin);
+      if(!metadata){ui.show('目标已失效，请先重新选择目标。');continue;}
+      target.input=await editValue(ui,metadata.input??{type:'object',properties:{},additionalProperties:false},target.input??{},{baseDir:session.baseDir,required:true,label:'快捷名称默认参数'});
+    }else if(choice==='save'){
+      const next=structuredClone(app.project.shortcuts??{});if(oldName)delete next[oldName];
+      if(Object.hasOwn(next,name)){ui.show('快捷名称已经存在，请选择其他名称。');continue;}
+      next[name]=target;
+      try{await app.configureShortcuts(next);ui.show('快捷名称已保存，修改前配置已备份。');return;}
+      catch(error){ui.show(`保存失败：${error.message}`);}
+    }
+  }
+}
+
+export async function shortcutsMenu(session){
+  const {app,ui}=session;
+  for(;;){
+    const entries=app.listShortcuts(),choice=await ui.select('自定义快捷名称',[
+      ...(!app.project.readOnly?[{value:'new',label:'添加快捷名称'}]:[]),
+      ...entries.map(entry=>({value:`shortcut:${entry.name}`,label:`/${entry.name}${entry.available?'':' [失效]'}`,description:entry.available?entry.description:entry.reason})),
+      {value:'back',label:'返回主面板'},
+    ]);
+    if(choice==='back')return;
+    if(choice==='new'){session.writable();await editShortcut(session);continue;}
+    const name=choice.slice(9),entry=entries.find(entry=>entry.name===name);if(!entry)continue;
+    const operation=await ui.select(`/${name}`,[
+      ...(entry.available?[{value:'run',label:'运行'}]:[]),
+      ...(!app.project.readOnly?[{value:'edit',label:'编辑'},{value:'remove',label:'删除快捷名称'}]:[]),{value:'back',label:'返回'},
+    ]);
+    if(operation==='run')await runShortcut(session,entry);
+    else if(operation==='edit'){session.writable();await editShortcut(session,name);}
+    else if(operation==='remove'){
+      session.writable();if(!await ui.confirm(`删除快捷名称 /${name}？`))continue;
+      const next=structuredClone(app.project.shortcuts??{});delete next[name];
+      await app.configureShortcuts(next);ui.show('快捷名称已删除，插件能力仍可使用。');
+    }
+  }
+}

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

@@ -1,10 +1,11 @@
 import {builtinCommands} from '@mytools/fst-plugin/contracts';
 
-const visible=['workflows','run','pack','logs','plugin','config','tools','help','exit'];
+const visible=['workflows','run','pack','logs','plugin','commands','shortcuts','config','tools','help','exit'];
 // 入口由插件 ID 推导；冲突时加前缀，不能覆盖内置或作者注册的命令。
-export function commandMenu(plugins,commands){
+export function commandMenu(plugins,commands,shortcuts=[]){
   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 used=new Set([...builtinCommands.map(c=>c.name),...commands.map(c=>c.name),...shortcuts.map(entry=>entry.name)]);
+  entries.push(...shortcuts.map(entry=>({name:entry.name,shortcut:true,description:`[快捷] ${entry.available?entry.description:`已失效：${entry.reason}`}`})));
   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,'-');

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

@@ -9,6 +9,8 @@ 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';
+import {commandPresetsMenu,shortcutsMenu,runShortcut} from './command-menu.js';
+import {validate} from '@mytools/sdk/schema';
 import {resolvePrivilegeRequirement,checkStaticPrivilege} from '@mytools/fst-plugin/privileges';
 
 export class TerminalSession{
@@ -24,7 +26,7 @@ export class TerminalSession{
     }
   }
   current(){if(!this.flow)throw new Error('先用 /workflows 打开或新建工作流');return this.flow;}
-  commands(){return commandMenu(this.app.listPlugins?.()??[],this.app.listCommands());}
+  commands(){return commandMenu(this.app.listPlugins?.()??[],this.app.listCommands(),this.app.listShortcuts?.()??[]);}
   async discard(){return !this.dirty||await this.ui.confirm('当前修改未保存，是否放弃修改？');}
   async mayExit(){
     if(!await this.discard())return false;
@@ -41,7 +43,7 @@ export class TerminalSession{
       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()});}
+        try{text=await this.ui.input('fst > / 操作 · ! 系统命令 · Shift+Enter 换行 · Enter 提交',{commands:this.commands(),workflows:await this.app.listWorkflows(),multiline:true});}
         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}`);}
@@ -57,19 +59,25 @@ export class TerminalSession{
     finally{this.commandDepth--;if(outer&&!this.exiting)this.ui.endCommand?.();}
   }
   async executeCommand(text){
+    if(text.trimStart().startsWith('!'))return this.shellCommand(text.trimStart().slice(1));
     const [command,...args]=parseCommand(text);
+    const shortcut=this.app.listShortcuts?.().find(entry=>entry.name===command);
+    if(shortcut)return runShortcut(this,shortcut,args);
     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 'commands':return commandPresetsMenu(this);
+      case 'shortcuts':return shortcutsMenu(this);
       case 'help':await this.ui.viewMarkdown('Fishtools 使用指南',[
         '# Fishtools',
         '将插件能力组合为工作流，在终端内编辑、运行并查看结果。',
         `当前工作区：${this.app.projectDir}`,
         `文件路径起点：${this.baseDir}`,
         '## 常用操作',gettingStarted(await this.app.listWorkflows(),this.app.project),
+        '## 系统命令与快捷名称','输入 ! 后接系统命令可直接执行，输出和状态保留在主面板；/commands 注册常用命令供快捷执行与工作流编排，/shortcuts 给任意插件动作或命令设置中文快捷名称。主输入框和命令编辑框使用 Shift+Enter 换行、Enter 提交，Alt+Enter 为备用换行；支持多行粘贴。系统命令按当前 Shell 语法执行，目标机器需要已安装相应外部程序。',
         '## 编排工作流','/workflows 浏览、新建、打开工作流，进入后添加步骤、编辑参数、设置输出、保存或删除。删除会保留备份，仍被其他流程引用时不能删除。/run 选择已保存的工作流，或补全工作流 ID/中文标题后执行已保存版本，不会要求保存编辑草稿。要执行未保存修改，在工作流编辑菜单选择运行，再选择保存并运行；返回编辑会保留草稿。',
         '## 主面板','运行期间可以继续输入命令，打开配置、管理插件或执行其他工作流。↑/↓ 回看本次启动已提交的命令，回到底部恢复草稿；补全菜单打开时仍用于选择候选。Ctrl+O 展开或收起执行详情，PgUp/PgDn 或滚轮浏览执行过程；/logs 回看各次执行的步骤、输入输出和日志。关闭菜单不会清空运行内容。',
         '## 命令分层','/config 配置 Fishtools，/plugin 管理插件及各插件配置。输入 /插件入口名 后进入该插件的能力菜单；补全列表标明 [内置] 或 [插件]。/tools 包含 Web 与离线文档。旧 /new、/add、/steps、/outputs、/save、/plugins 以及插件的原始命令仍可直接输入。',
@@ -118,14 +126,26 @@ export class TerminalSession{
   }
   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}):{};
+    let input;
+    if(args.length)input=await readRunInput(args[0],this.baseDir);
+    else{
+      const initial=structuredClone(command.shortcutInput??{});
+      const empty=command.input?.type==='object'&&command.input.properties&&Object.keys(command.input.properties).length===0;
+      if(command.shortcutInput!==undefined||empty){
+        try{input=validate(command.input,initial,command.description??command.name);}
+        catch{input=await editValue(this.ui,command.input,initial,{baseDir:this.baseDir,required:true,label:command.description});}
+      }else input=command.input?await editValue(this.ui,command.input,initial,{baseDir:this.baseDir,required:true,label:command.description}):initial;
+    }
     const ui=Object.fromEntries(['input','select','show','confirm'].map(name=>[name,this.ui[name].bind(this.ui)]));
     const definition=this.app.host.definitions.get(command.plugin);
+    if(!definition)throw new Error('目标插件已移除，请重新选择目标后执行');
     const requirement=resolvePrivilegeRequirement(definition,command.action);
     const unknown=requirement.declared&&checkStaticPrivilege(requirement).status==='unknown';
     const allowUnknownPrivileges=unknown?await this.ui.confirm(`/${command.name} 的权限需要运行时核查。若检查结果仍无法确认，是否允许本次继续？\n${requirement.reason??''}\n${requirement.remediation??''}`):false;
     if(unknown&&!allowUnknownPrivileges)return;
-    const run=await this.app.startCommand(command.name,input,{ui,allowUnknownPrivileges});
+    const targetName=command.targetName??command.name;
+    if(!command.actionId&&!this.app.listCommands().some(current=>current.name===targetName&&current.plugin===command.plugin))throw new Error('命令目标插件已变更，请重新选择目标后执行');
+    const run=command.actionId?await this.app.startAction(command.actionId,input,{ui,allowUnknownPrivileges}):await this.app.startCommand(targetName,input,{ui,allowUnknownPrivileges,expectedPlugin:command.plugin});
     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;}
@@ -135,6 +155,17 @@ export class TerminalSession{
     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 shellCommand(script){
+    const run=await this.app.startShell(script);
+    if(this.ui.trackRun){
+      this.ui.clearMessages?.();this.ui.trackRun({app:this.app,runId:run.id,title:'系统命令'});
+      void run.done.catch(error=>{if(!this.ui.closed)this.ui.show(`运行记录保存失败：${error.message}`);});return;
+    }
+    const unsubscribe=this.app.subscribe(event=>{if(event.runId===run.id&&event.type==='log')this.ui.show(event.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${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);