@yanglaofish/fishtools 0.5.1 → 0.5.2

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

@@ -76,7 +76,20 @@ export class TerminalView{
       input(data);
     },resize);
     this.header=new Text('',1,0);this.transcript=new Text('',1,0);this.prompt=new Container();this.hint=new Text('',1,0);
-    this.hint.render=width=>['',fitLine(' '+palette.muted(this.homeInput?(width<45?`/ 操作 · Ctrl+O ${this.feed.expanded?'收起':'展开'}`:`/ 操作 · Ctrl+O ${this.feed.expanded?'收起':'展开'}详情 · /logs 回看 · Ctrl+C 退出`):(width<45?'↑↓ 选择  Enter 确认  Esc 返回':'↑↓ 选择   Enter 确认   Tab 补全   Esc 返回   Ctrl+C 退出')),width)];
+    this.hint.render=width=>{
+      const lines=[''];
+      if(this.editor&&(this.homeInput||this.multilineInput)){
+        // 按完整按键分组换行，窄屏也能看清主键和备用键。
+        let line='';
+        for(const hint of ['Shift+Enter 换行','Enter 提交','Alt+Enter 备用换行']){
+          const next=line?line+' · '+hint:hint;
+          if(line&&visibleWidth(next)>width-1){lines.push(line);line=hint;}else line=next;
+        }
+        lines.push(line);
+      }
+      lines.push(this.homeInput?(width<45?`/ 操作 · ! 命令 · Ctrl+O ${this.feed.expanded?'收起':'展开'}`:`/ 操作 · ! 命令 · Ctrl+O ${this.feed.expanded?'收起':'展开'}详情 · /logs 回看 · Ctrl+C 退出`):this.editor&&this.multilineInput?'↑↓ 移动 · Tab 补全 · Esc 返回 · Ctrl+C 退出':(width<45?'↑↓ 选择  Enter 确认  Esc 返回':'↑↓ 选择   Enter 确认   Tab 补全   Esc 返回   Ctrl+C 退出'));
+      return lines.map(line=>line?fitLine(' '+palette.muted(line),width):'');
+    };
     const renderTranscript=this.transcript.render.bind(this.transcript);
     this.headingLines=(width,mark='FISHtools')=>{
       const room=Math.max(1,width-2),lines=[''];
@@ -127,7 +140,7 @@ export class TerminalView{
   browseCommands(data){
     const direction=matchesKey(data,'up')?-1:matchesKey(data,'down')?1:0;
     // 补全菜单保留方向键；多行编辑保留光标移动，不把配置值放进命令历史。
-    if(!direction||!this.editor||this.editor.isShowingAutocomplete()||this.editor.getText().includes('\n')||!this.commandHistory.length)return false;
+    if(!direction||!this.editor||this.editor.isShowingAutocomplete()||this.editor.getExpandedText().includes('\n')||!this.commandHistory.length)return false;
     const current=this.commandHistoryIndex??this.commandHistory.length;
     const next=Math.max(0,Math.min(this.commandHistory.length,current+direction));
     if(next===current)return true;
@@ -235,19 +248,40 @@ export class TerminalView{
     if(message.startsWith('fst >'))title.render=()=>[];
     this.prompt.clear();this.prompt.addChild(title);this.prompt.addChild(component);this.tui.setFocus(component);this.tui.requestRender();
     try{return await new Promise((resolve,reject)=>{this.pending={resolve,reject};component.onSubmit=text=>{
-      if(this.homeInput&&text.trim()&&this.commandHistory.at(-1)!==text.trim()){
-        this.commandHistory.push(text.trim());if(this.commandHistory.length>100)this.commandHistory.shift();
+      // Shell 历史保留末尾换行，避免再次执行时改变反斜杠续行等语义。
+      const historyText=text.trimStart().startsWith('!')?text:text.trim();
+      if(this.homeInput&&historyText&&this.commandHistory.at(-1)!==historyText){
+        this.commandHistory.push(historyText);if(this.commandHistory.length>100)this.commandHistory.shift();
       }
       resolve(text);
     };component.onSelect=item=>resolve(item.value);component.onCancel=()=>reject(cancelled());});}
-    finally{if(this.homeInput)this.terminal.write(mouseOff);this.pending=null;this.editor=null;this.homeInput=false;this.prompt.clear();this.tui.requestRender();}
+    finally{if(this.homeInput)this.terminal.write(mouseOff);this.pending=null;this.editor=null;this.homeInput=false;this.multilineInput=false;this.prompt.clear();this.tui.requestRender();}
   }
-  input(message,{value='',commands=[],files=true,workflows=[]}={}){
+  input(message,{value='',commands=[],files=true,workflows=[],multiline=false}={}){
     const editor=new Editor(this.tui,{borderColor:palette.border,selectList:theme},{paddingX:1});
+    const handleInput=editor.handleInput.bind(editor);
+    editor.handleInput=data=>{
+      // ProcessTerminal 已把分段粘贴合并为完整事件；公开插入接口保留脚本制表符和换行。
+      if(data.startsWith('\x1b[200~')&&data.endsWith('\x1b[201~')){
+        const text=safe(data.slice(6,-6).replace(/\r\n?/g,'\n'));
+        if(this.homeInput||multiline||text.includes('\n')){editor.insertTextAtCursor(text);return;}
+      }
+      if(matchesKey(data,'shift+enter')||matchesKey(data,'alt+enter')||data==='\x1b[13;2~'){
+        editor.insertTextAtCursor('\n');return;
+      }
+      // 反斜杠属于命令原文，不能触发上游的“反斜杠后 Enter 换行”兼容键位。
+      if(data==='\\'){editor.insertTextAtCursor(data);return;}
+      if(matchesKey(data,'enter')&&!editor.isShowingAutocomplete()){
+        if(!editor.disableSubmit){const text=editor.getExpandedText();editor.setText('');editor.onSubmit?.(text);}
+        return;
+      }
+      handleInput(data);
+    };
     const renderEditor=editor.render.bind(editor);
     editor.render=width=>{
-      if(width<8)return renderEditor(width);
-      const inner=width-4,lines=renderEditor(inner);let closed=false;
+      // 上游 visibleWidth 按三个空格计算 Tab；只扩展显示，提交仍保留原始 Tab。
+      if(width<8)return renderEditor(width).map(line=>line.replaceAll('\t','   '));
+      const inner=width-4,lines=renderEditor(inner).map(line=>line.replaceAll('\t','   '));let closed=false;
       return lines.map((line,i)=>{
         if(i===0)return ' '+palette.border('╭'+'─'.repeat(inner)+'╮');
         if(!closed&&/^─+$/.test(safe(line))){closed=true;return ' '+palette.border('╰'+'─'.repeat(inner)+'╯');}
@@ -256,6 +290,7 @@ export class TerminalView{
       });
     };
     this.homeInput=message.startsWith('fst >');
+    this.multilineInput=multiline;
     this.commandHistoryIndex=null;
     if(this.homeInput)editor.onChange=text=>{
       if(this.commandHistoryIndex!==null&&text!==this.commandHistory[this.commandHistoryIndex])this.commandHistoryIndex=null;

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

@@ -4,7 +4,6 @@ export async function workflowMenu(session){
     const workflows=await app.listWorkflows();
     const choice=await ui.select('工作流 · 选择后编辑或执行',[
       ...workflows.map(flow=>({value:`workflow:${flow.id}`,label:flow.title??flow.id,description:`${flow.id} · ${flow.steps.length} 步`})),
-      ...(!app.project.readOnly?workflows.map(flow=>({value:`duplicate:${flow.id}`,label:`复制 ${flow.title??flow.id} 为新工作流`,description:`从已保存版本 ${flow.id} 创建副本` })):[]),
       ...(!app.project.readOnly?[{value:'new',label:'＋ 新建工作流'}]:[]),
       ...(session.dirty?[{value:'draft',label:`继续编辑草稿：${session.flow.title}`}]:[]),
       {value:'back',label:'返回主面板'},
@@ -12,11 +11,7 @@ export async function workflowMenu(session){
     if(choice==='back')return;
     try{
       const id=choice.startsWith('workflow:')?choice.slice(9):null;
-      if(choice.startsWith('duplicate:')){
-        if(!await session.discard())continue;
-        await duplicateIntoSession(session,workflows.find(flow=>flow.id===choice.slice(10)));
-      }
-      else if(choice==='new'){if(await session.execute('/new')===false)continue;}
+      if(choice==='new'){if(await session.execute('/new')===false)continue;}
       else if(choice!=='draft'&&session.flow?.id!==id){
         if(!await session.discard())continue;
         session.flow=structuredClone(workflows.find(flow=>flow.id===id));session.dirty=false;

package/manual/packages/fst-devtools/src/documentation.js

@@ -3,6 +3,7 @@ import {fileURLToPath} from 'node:url';
 import {access,readFile,readdir,lstat,mkdir,copyFile,realpath} from 'node:fs/promises';
 
 const topics=[
+  ['commands','系统命令与快捷名称','docs/terminal-commands.md'],
   ['plugins','插件开发规范','docs/plugin-development.md'],
   ['deployment','安装与部署','docs/deployment.md'],
   ['control','控制流与运行观察规范','docs/superpowers/specs/2026-10-11-control-observation.md'],
@@ -14,7 +15,7 @@ const topics=[
   ['readme','Fishtools 使用说明','README.md'],
 ];
 // 保留文档链接所需的目录布局；参考代码仅供阅读，不是第二份运行时。
-const assets=['README.md','LICENSE','THIRD_PARTY_NOTICES.md','docs','examples/service-plugins','plugins/examples','plugins/environment','plugins/web/README.md','packages/sdk','packages/core','packages/pack','packages/fst-logs','packages/fst-platform','packages/fst-workflow','packages/fst-plugin','packages/fst-workspace','packages/fst-devtools','packages/fst-cli','tests/application.test.js'];
+const assets=['README.md','LICENSE','THIRD_PARTY_NOTICES.md','docs','examples/service-plugins','plugins/examples','plugins/environment','plugins/commands','plugins/web/README.md','packages/sdk','packages/core','packages/pack','packages/fst-logs','packages/fst-platform','packages/fst-workflow','packages/fst-plugin','packages/fst-workspace','packages/fst-devtools','packages/fst-cli','tests/application.test.js'];
 const excluded=new Set(['node_modules','dist','.git','.cache','__pycache__','.pytest_cache','coverage','public']);
 const inside=(parent,child)=>{const relative=path.relative(parent,child);return relative===''||(!relative.startsWith(`..${path.sep}`)&&relative!=='..'&&!path.isAbsolute(relative));};
 

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

@@ -18,6 +18,7 @@
 | `@mytools/fst-platform/npm` | `./src/npm.js` |
 | `@mytools/fst-platform/network` | `./src/network.js` |
 | `@mytools/fst-platform/fs` | `./src/file-probe.js` |
+| `@mytools/fst-platform/shell` | `./src/shell.js` |
 | `@mytools/fst-platform/package.json` | `./package.json` |
 
 仅依赖 exports 声明的入口，禁止消费者跨包读取 src/bin 私有文件。入口路径由本模块维护，修改协议时同步消费方回归。
@@ -32,11 +33,21 @@
 node --test tests/modules.test.js tests/process.test.js tests/environments.test.js
 ```
 
+进程停止专项：`node --test tests/process.test.js tests/process-stream.test.js tests/process-tree-stop.test.js`。
+
 ## 子进程环境
 
+`/shell` 的 `runShell(script,{shell='auto',runProcess,temporaryDir,...processOptions})` 使用唯一临时脚本文件，避免长脚本超过系统命令行长度上限，运行结束后删除本次文件。默认 Windows PowerShell / Linux sh，可选 powershell、pwsh、sh、bash；PowerShell 使用 UTF-8 BOM，其他 Shell 使用无 BOM UTF-8。插件传入 `ctx.runProcess` 与 `temporaryDir:ctx.outputDir`，保留当前代理、取消与日志规则，并兼容只读包目录。`shellInvocation` 保留构造简短命令参数的兼容接口。
+
 `runProcess(file,args,{env,extendEnv=true})` 默认把 `env` 覆盖到宿主环境上。
 当调用方已按动作代理规则构造完整环境时，传 `extendEnv:false`，防止已移除的代理变量被重新继承。
 
+缓冲模式由平台按每条输出流的原始字节计算 `maxBuffer`，默认每条流 4 MiB；超限返回 `OUTPUT_LIMIT`。
+`maxBuffer` 必须为非负数，`0` 仅允许空输出，`Infinity` 表示调用方显式取消缓冲上限；对象、`NaN` 和负数会在启动前被拒绝。
+流式模式通过 `onOutput` 消费输出，仅保留 `summaryBytes` 指定的尾部摘要。
+超限、取消、超时或输出回调失败时，平台终止整棵进程树，等待回收结束后返回错误。
+停止过程中继续排空并丢弃管道输出，避免提前关闭管道使父进程因 `EPIPE` 退出，导致 Windows `taskkill /T` 无法找到后代进程。
+
 ## 隔离文件探测
 
 `createFileProbe({timeout=2000,maxConcurrent=2,maxPending=16,allowRemote=false})` 创建只读探测器。

package/manual/packages/fst-platform/package.json

@@ -6,6 +6,7 @@
   "main": "src/process.js",
   "exports": {
     ".": "./src/process.js",
+    "./shell": "./src/shell.js",
     "./environments": "./src/environments.js",
     "./bundle": "./src/bundle.js",
     "./json": "./src/json.js",

package/manual/packages/fst-platform/src/process.js

@@ -4,11 +4,11 @@ import which from 'which';
 import { FlowError } from '@mytools/sdk';
 import path from 'node:path';
 
-const outputText=bytes=>bytes??new Uint8Array();
 const stripFinalNewline=text=>text.endsWith('\r\n')?text.slice(0,-2):text.endsWith('\n')?text.slice(0,-1):text;
 
 export async function runProcess(file,args=[],{cwd,env,extendEnv=true,signal,timeout=30000,maxBuffer=4*1024*1024,encoding='utf8',onOutput,outputMode='buffer',summaryBytes=65536}={}) {
   if(!['buffer','stream'].includes(outputMode))throw new TypeError('outputMode 必须为 buffer 或 stream');
+  if(typeof maxBuffer!=='number'||Number.isNaN(maxBuffer)||maxBuffer<0)throw new TypeError('maxBuffer 必须为非负数，可用 Infinity 表示不限制缓冲');
   const streaming=outputMode==='stream';
   if(streaming&&typeof onOutput!=='function')throw new TypeError('stream 模式必须提供 onOutput 消费输出');
   if(!Number.isSafeInteger(summaryBytes)||summaryBytes<0||summaryBytes>1024*1024)throw new TypeError('summaryBytes 必须为 0 到 1048576 的整数');
@@ -33,11 +33,12 @@ export async function runProcess(file,args=[],{cwd,env,extendEnv=true,signal,tim
     if(!executable)throw Object.assign(new Error(`not found: ${file}`),{code:'ENOENT'});
   }
   catch(cause){throw new FlowError(`未找到程序：${file}`,{code:'ENOENT',details:{executable:file},cause});}
-  // Execa 收集原始字节；文本只在这里按同一编码解码，避免返回值被默认 UTF-8 解码。
-  const child=execa(executable,args,{cwd,env,extendEnv,reject:false,windowsHide:true,maxBuffer,buffer:!streaming,timeout:0,shell:false,encoding:'buffer',stripFinalNewline:false});
+  // 平台统一收集原始字节和执行上限；Execa 的超限收集器会提前关闭管道，
+  // 导致持续输出的父进程因 EPIPE 退出，taskkill 尚未遍历就失去父 PID。
+  const child=execa(executable,args,{cwd,env,extendEnv,reject:false,windowsHide:true,maxBuffer,buffer:false,timeout:0,shell:false,encoding:'buffer',stripFinalNewline:false});
   let reason,killing,outputError,outputFailed=false,outputWrites=Promise.resolve();
   let markStopped;const stopped=new Promise(resolve=>{markStopped=resolve;});
-  const outputBytes={stdout:0,stderr:0},tails={stdout:'',stderr:''};let outputTruncated=false;
+  const outputBytes={stdout:0,stderr:0},tails={stdout:'',stderr:''},buffers={stdout:[],stderr:[]};let outputTruncated=false;
   const remember=(name,message)=>{
     const bytes=Buffer.from(tails[name]+message);let start=Math.max(0,bytes.length-summaryBytes);
     if(start){outputTruncated=true;while(start<bytes.length&&(bytes[start]&0xc0)===0x80)start++;}
@@ -67,7 +68,8 @@ export async function runProcess(file,args=[],{cwd,env,extendEnv=true,signal,tim
         const decoder=new TextDecoder(decoderEncoding);
         try{
           for await(const chunk of stream){
-            if(reason)break;outputBytes[name]+=chunk.byteLength;
+            // 停止后继续排空并丢弃输出，避免迭代器 break 提前关闭管道触发 EPIPE。
+            if(reason)continue;outputBytes[name]+=chunk.byteLength;
             const message=decoder.decode(chunk,{stream:true});remember(name,message);
             await Promise.race([emit(name,message),stopped]);
           }
@@ -81,9 +83,11 @@ export async function runProcess(file,args=[],{cwd,env,extendEnv=true,signal,tim
     const finish=()=>{if(!ended){ended=true;emit(name,decoder.decode());}};
     flush.push(finish);stream?.once('end',finish);
     stream?.on('data',chunk=>{
+      if(reason)return;
       bytes+=Buffer.byteLength(chunk);
       // 流量超限时立即回收整棵进程树，不继续扩张待落盘的日志队列。
       if(bytes>maxBuffer){stop('output-limit');return;}
+      buffers[name].push(chunk);
       if(onOutput)emit(name,decoder.decode(chunk,{stream:true}));
     });
   }
@@ -104,7 +108,7 @@ export async function runProcess(file,args=[],{cwd,env,extendEnv=true,signal,tim
   if(reason)throw new FlowError(reason==='cancelled'?'操作已取消':'程序运行超时',{code:reason==='cancelled'?'CANCELLED':'TIMEOUT'});
   if(result.isMaxBuffer)throw new FlowError('程序输出超过上限',{code:'OUTPUT_LIMIT'});
   if(result.exitCode===undefined&&result.failed)throw new FlowError(`无法启动程序 ${file}：${result.shortMessage??result.message}`,{code:result.code??'SPAWN_FAILED'});
-  const decode=bytes=>stripFinalNewline(new TextDecoder(decoderEncoding).decode(outputText(bytes)));
+  const decode=chunks=>stripFinalNewline(new TextDecoder(decoderEncoding).decode(Buffer.concat(chunks)));
   if(streaming)return {exitCode:result.exitCode,stdout:stripFinalNewline(tails.stdout),stderr:stripFinalNewline(tails.stderr),outputMode,outputTruncated,outputBytes};
-  return {exitCode:result.exitCode,stdout:decode(result.stdout),stderr:decode(result.stderr)};
+  return {exitCode:result.exitCode,stdout:decode(buffers.stdout),stderr:decode(buffers.stderr)};
 }

package/manual/packages/fst-platform/src/shell.js

@@ -0,0 +1,58 @@
+import {FlowError} from '@mytools/sdk';
+import {randomUUID} from 'node:crypto';
+import {mkdir,open,rm} from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import path from 'node:path';
+import {runProcess as executeProcess} from './process.js';
+
+const shells=new Set(['auto','powershell','pwsh','sh','bash']);
+const powerShellArgs=['-NoLogo','-NoProfile','-NonInteractive','-OutputFormat','Text'];
+
+function selectShell(script,shell,platform){
+  if(typeof script!=='string'||!script.trim()||script.includes('\u0000'))throw new FlowError('命令文本必须是非空字符串，且不能包含 NUL 字符',{code:'VALIDATION'});
+  if(!shells.has(shell))throw new FlowError(`不支持的 Shell：${String(shell)}`,{code:'VALIDATION'});
+  return shell==='auto'?(platform==='win32'?'powershell':'sh'):shell;
+}
+
+function powerShellSource(script){
+  // $? 在脚本最后一条命令后立即读取，避免沿用更早的外部命令退出码。
+  return `[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)
+$OutputEncoding = [Console]::OutputEncoding
+& {
+${script}
+if (-not $?) {
+  if ($LASTEXITCODE) { exit $LASTEXITCODE }
+  exit 1
+}
+exit 0
+}`;
+}
+
+export function shellInvocation(script,{shell='auto',platform=process.platform}={}){
+  const file=selectShell(script,shell,platform);
+  if(file==='sh'||file==='bash')return {file,args:['-c',script]};
+  // 编码只改变传输形式；保留用户的引号、管道、换行及尾部注释。
+  const source=powerShellSource(script);
+  const encoded=Buffer.from(source,'utf16le').toString('base64');
+  // 普通 -Command 避免 Windows PowerShell 在 -EncodedCommand 下把 stderr 序列化为 CLIXML。
+  const command=`& ([ScriptBlock]::Create([Text.Encoding]::Unicode.GetString([Convert]::FromBase64String('${encoded}'))))`;
+  return {file,args:[...powerShellArgs,'-Command',command]};
+}
+
+export async function runShell(script,{shell='auto',runProcess:execute=executeProcess,temporaryDir=tmpdir(),...processOptions}={}){
+  const file=selectShell(script,shell,process.platform),powershell=file==='powershell'||file==='pwsh';
+  if(processOptions.signal?.aborted)throw new FlowError('操作已取消',{code:'CANCELLED'});
+  const directory=path.resolve(temporaryDir);
+  await mkdir(directory,{recursive:true});
+  const scriptFile=path.join(directory,`fst-shell-${randomUUID()}.${powershell?'ps1':'sh'}`);
+  // 独占创建后才承担清理责任；不覆盖已有文件，也不清空调用者的输出目录。
+  const handle=await open(scriptFile,'wx',0o600);
+  try{
+    try{
+      // Windows PowerShell 5.1 读取 UTF-8 文件需要 BOM；POSIX Shell 使用无 BOM 原文。
+      await handle.writeFile(powershell?'\uFEFF'+powerShellSource(script):script,'utf8');
+    }finally{await handle.close();}
+    const args=powershell?[...powerShellArgs,'-ExecutionPolicy','Bypass','-File',scriptFile]:[scriptFile];
+    return await execute(file,args,processOptions);
+  }finally{await rm(scriptFile,{force:true});}
+}

package/manual/packages/fst-plugin/src/contracts.js

@@ -7,7 +7,7 @@ import path from 'node:path';
 export const builtinCommands=[
   ['workflows','选择已有工作流'],['new','新建工作流'],['add','添加插件能力或子工作流'],
   ['steps','设置步骤参数、排序或删除'],['outputs','设置最终输出'],['save','保存工作流'],
-  ['run','运行工作流，可附带 @参数.json'],['runs','运行记录：选择任意一次执行，查看进度、结果和日志'],['logs','查看运行日志'],['plugin','管理插件'],['plugins','管理插件（兼容旧入口）'],['config','配置 Fishtools'],['tools','Web 与离线文档'],
+  ['run','运行工作流，可附带 @参数.json'],['runs','运行记录：选择任意一次执行，查看进度、结果和日志'],['logs','查看运行日志'],['plugin','管理插件'],['plugins','管理插件（兼容旧入口）'],['commands','管理常用命令'],['shortcuts','管理自定义快捷名称'],['config','配置 Fishtools'],['tools','Web 与离线文档'],
   ['pack','选择工作流打包'],['web','启动 Web 工作台'],['docs','阅读离线开发与使用文档'],['help','查看操作说明'],['exit','退出终端工作台'],
 ].map(([name,description])=>({name,description}));
 
@@ -76,9 +76,13 @@ export function validateDeclarations(plugin){
   }
 }
 
+export function isCommandName(name){
+  return typeof name==='string'&&name===name.normalize('NFC')&&/^\p{L}[\p{L}\p{N}_.-]*$/u.test(name);
+}
+
 export function validateCommands(plugin,registered){
   for(const [name,c] of Object.entries(plugin.commands??{})){
-    if(!/^[a-zA-Z][\w.-]*$/.test(name)||builtinCommands.some(x=>x.name===name)||registered.has(name))throw new FlowError(`命令名称无效或冲突：/${name}`);
+    if(!isCommandName(name)||builtinCommands.some(x=>x.name===name)||registered.has(name))throw new FlowError(`命令名称无效或冲突：/${name}`);
     if(!c||Boolean(c.action)===Boolean(c.run)||c.run&&typeof c.run!=='function')throw new FlowError(`命令 /${name} 必须声明 action 或 run`);
     if(c.action&&!plugin.actions?.[c.action])throw new FlowError(`命令 /${name} 指向不存在的动作：${c.action}`);
     registered.add(name);

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

@@ -17,12 +17,15 @@
 | `@mytools/fst-workspace/plugins` | `./src/plugins.js` |
 | `@mytools/fst-workspace/installations` | `./src/plugin-installations.js` |
 | `@mytools/fst-workspace/bundles` | `./src/bundle-workspace.js` |
+| `@mytools/fst-workspace/shortcuts` | `./src/shortcuts.js` |
 | `@mytools/fst-workspace/package.json` | `./package.json` |
 
 仅依赖 exports 声明的入口，禁止消费者跨包读取 src/bin 私有文件。入口路径由本模块维护，修改协议时同步消费方回归。
 
 ## 维护与验证
 
+`/shortcuts` 提供 `validateShortcuts` 校验、`bindShortcutCommands` 在用户配置时补齐命令提供者身份，以及 `describeShortcuts` 生成可用或失效状态。绑定函数可传入 previous 保留旧项：未绑定命令修改参数或重命名仍保持失效，需重新选择目标。命令项使用 command 与 plugin 同时匹配，动作项使用稳定 action ID；不执行其他插件的同名能力。实际保存、备份与宿主装配由 core 协调。
+
 本模块负责上述职责的实现、文档与回归；跨模块接口调整需要同时检查生产者与消费者。具体维护人员尚未指定。
 
 在仓库根目录执行：

package/manual/packages/fst-workspace/package.json

@@ -8,6 +8,7 @@
     ".": "./src/index.js",
     "./workflows": "./src/workflows.js",
     "./project": "./src/project.js",
+    "./shortcuts": "./src/shortcuts.js",
     "./plugins": "./src/plugins.js",
     "./installations": "./src/plugin-installations.js",
     "./bundles": "./src/bundle-workspace.js",

package/manual/packages/fst-workspace/src/shortcuts.js

@@ -0,0 +1,119 @@
+import {FlowError} from '@mytools/sdk';
+import {builtinCommands,isCommandName} from '@mytools/fst-plugin/contracts';
+import {isBuiltin} from 'node:module';
+
+const dangerousFields=new Set(['__proto__','constructor','prototype']);
+const shortcutFields=new Set(['action','command','plugin','input']);
+
+function validPluginId(value){
+  if(typeof value!=='string'||!value.length||value.length>214||value!==value.toLowerCase()||isBuiltin(value)||['node_modules','favicon.ico'].includes(value))return false;
+  const parts=/^(?:@([^/]+)\/)?([^/]+)$/.exec(value);
+  if(!parts||/^[._-]/.test(value)||parts[2].startsWith('.'))return false;
+  return (!parts[1]||/^[a-z0-9_.~'!()*-]+$/.test(parts[1]))&&/^[a-z0-9_.-]+$/.test(parts[2]);
+}
+
+function invalid(location,message){
+  throw new FlowError(message,{code:'VALIDATION',details:{path:location}});
+}
+
+function plainObject(value){
+  return value!==null&&typeof value==='object'&&!Array.isArray(value)&&[Object.prototype,null].includes(Object.getPrototypeOf(value));
+}
+
+function entries(value,location){
+  if(!plainObject(value))invalid(location,`${location} 必须为普通 JSON 对象`);
+  return Reflect.ownKeys(value).map(key=>{
+    if(typeof key!=='string'||dangerousFields.has(key))invalid(location,`${location} 包含危险或非 JSON 字段`);
+    const field=Object.getOwnPropertyDescriptor(value,key);
+    if(!field.enumerable||!Object.hasOwn(field,'value'))invalid(`${location}.${key}`,`${location}.${key} 必须为普通 JSON 字段`);
+    return [key,field.value];
+  });
+}
+
+function cloneJson(value,location,ancestors=new Set()){
+  if(value===null||typeof value==='string'||typeof value==='boolean')return value;
+  if(typeof value==='number'&&Number.isFinite(value))return value;
+  if(typeof value!=='object')invalid(location,`${location} 必须为可序列化的 JSON 值`);
+  if(ancestors.has(value))invalid(location,`${location} 不能包含循环引用`);
+  ancestors.add(value);
+  try{
+    if(Array.isArray(value)){
+      if(Object.getPrototypeOf(value)!==Array.prototype||Reflect.ownKeys(value).length!==value.length+1)invalid(location,`${location} 必须为普通且完整的 JSON 数组`);
+      const copy=[];
+      for(let index=0;index<value.length;index++){
+        const field=Object.getOwnPropertyDescriptor(value,String(index));
+        if(!field?.enumerable||!Object.hasOwn(field,'value'))invalid(`${location}[${index}]`,`${location} 必须为普通且完整的 JSON 数组`);
+        copy.push(cloneJson(field.value,`${location}[${index}]`,ancestors));
+      }
+      return copy;
+    }
+    return Object.fromEntries(entries(value,location).map(([key,nested])=>[key,cloneJson(nested,`${location}.${key}`,ancestors)]));
+  }finally{ancestors.delete(value);}
+}
+
+export function validateShortcuts(shortcuts,{reservedNames=[]}={}){
+  if(!Array.isArray(reservedNames)||reservedNames.some(name=>typeof name!=='string'))invalid('reservedNames','保留名称必须为字符串数组');
+  const reserved=new Set([...builtinCommands.map(command=>command.name),...reservedNames].map(name=>name.normalize('NFC')));
+  const copy={};
+  for(const [name,shortcut] of entries(shortcuts,'shortcuts')){
+    const location=`shortcuts.${name}`;
+    // 明确拒绝未规范化名称，避免两个视觉相同的入口指向不同能力。
+    if(name!==name.normalize('NFC'))invalid(location,`快捷名称必须使用 NFC 规范形式：${name}`);
+    if(!isCommandName(name))invalid(location,`快捷名称无效：/${name}`);
+    if(reserved.has(name))invalid(location,`快捷名称与现有命令冲突：/${name}`);
+    reserved.add(name);
+    const fields=entries(shortcut,location);
+    if(fields.some(([key])=>!shortcutFields.has(key)))invalid(location,`快捷项 ${name} 包含未声明字段`);
+    const hasAction=Object.hasOwn(shortcut,'action'),hasCommand=Object.hasOwn(shortcut,'command');
+    if(hasAction===hasCommand)invalid(location,`快捷项 ${name} 必须声明 action 或 command 之一`);
+    const field=hasAction?'action':'command',target=shortcut[field];
+    if(hasAction){
+      const separator=typeof target==='string'?target.lastIndexOf(':'):-1;
+      if(separator<=0||separator===target.length-1||/[\s\p{C}]/u.test(target))invalid(`${location}.action`,`快捷项 ${name} 的 action 必须为稳定动作 ID`);
+    }else if(!isCommandName(target))invalid(`${location}.command`,`快捷项 ${name} 的 command 名称无效`);
+    copy[name]={[field]:target};
+    if(Object.hasOwn(shortcut,'plugin')){
+      if(hasAction)invalid(`${location}.plugin`,`动作快捷项 ${name} 不能声明 plugin`);
+      if(!validPluginId(shortcut.plugin))invalid(`${location}.plugin`,`快捷项 ${name} 的 plugin 必须为合法插件包 ID`);
+      copy[name].plugin=shortcut.plugin;
+    }
+    if(Object.hasOwn(shortcut,'input')){
+      if(!plainObject(shortcut.input))invalid(`${location}.input`,`快捷项 ${name} 的 input 必须为普通 JSON 对象`);
+      copy[name].input=cloneJson(shortcut.input,`${location}.input`);
+    }
+  }
+  return copy;
+}
+
+export function bindShortcutCommands(shortcuts,{commands=[],previous={}}={}){
+  const copy=validateShortcuts(shortcuts);
+  const old=validateShortcuts(previous),unbound=new Set(Object.values(old).filter(shortcut=>shortcut.command&&shortcut.plugin===undefined).map(shortcut=>shortcut.command));
+  for(const [name,shortcut] of Object.entries(copy)){
+    // 已有未绑定项即使改参数或重命名也需明确选择目标，不能被整组保存顺带启用。
+    if(!Object.hasOwn(shortcut,'command')||Object.hasOwn(shortcut,'plugin'))continue;
+    if(old[name]?.command===shortcut.command||unbound.has(shortcut.command))continue;
+    const command=commands.find(command=>command.name===shortcut.command);
+    if(command?.plugin!==undefined)shortcut.plugin=command.plugin;
+  }
+  return validateShortcuts(copy);
+}
+
+export function describeShortcuts(shortcuts,{actions=[],commands=[]}={}){
+  const actionIndex=new Map(actions.map(action=>[action.id,action]));
+  return Object.entries(validateShortcuts(shortcuts)).map(([name,shortcut])=>{
+    const field=Object.hasOwn(shortcut,'action')?'action':'command';
+    const id=shortcut[field];
+    let definition;
+    if(field==='action')definition=actionIndex.get(id);
+    else if(shortcut.plugin!==undefined)definition=commands.find(command=>command.name===id&&command.plugin===shortcut.plugin);
+    const descriptions=field==='action'?[definition?.title,definition?.description]:[definition?.description];
+    const target={[field]:id};
+    if(shortcut.plugin!==undefined)target.plugin=shortcut.plugin;
+    const entry={name,target,input:shortcut.input??{},available:Boolean(definition),description:descriptions.find(value=>typeof value==='string'&&value.trim())??id};
+    if(!definition){
+      if(field==='command'&&shortcut.plugin===undefined)entry.reason='尚未绑定目标插件，请重新选择目标';
+      else entry.reason=`${field==='action'?'动作':'命令'}不可用或尚未安装：${shortcut.plugin?`${shortcut.plugin} → `:''}${id}`;
+    }
+    return entry;
+  });
+}

package/manual/packages/pack/index.js

@@ -78,7 +78,7 @@ export async function packApplication(app,{entries,target,outDir='dist',includeW
   for(const w of closure.workflows)await writeFile(path.join(workflowDir,`${w.id}.yaml`),YAML.stringify(w));
   const config={};
   for(const p of plugins)if(p.defaultConfig)config[p.id]=p.defaultConfig;
-  await writeFile(path.join(directory,'flow.project.json'),JSON.stringify({readOnly,plugins:plugins.map(p=>`./app/node_modules/${p.id}`),config,entries,environments:overrides,network:snapshot.project.network,logs:snapshot.project.logs},null,2));
+  await writeFile(path.join(directory,'flow.project.json'),JSON.stringify({readOnly,plugins:plugins.map(p=>`./app/node_modules/${p.id}`),config,entries,environments:overrides,network:snapshot.project.network,logs:snapshot.project.logs,commandPresets:snapshot.project.commandPresets,shortcuts:snapshot.project.shortcuts},null,2));
   const bundleId=randomUUID();
   await writeFile(path.join(directory,'bundle.json'),JSON.stringify({format:2,id:bundleId,editable:!readOnly}));
   await writeFile(path.join(directory,'package.json'),JSON.stringify({private:true,type:'module'},null,2));

package/manual/plugins/commands/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mytools contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/manual/plugins/commands/README.md

@@ -0,0 +1,41 @@
+# 轻量命令插件
+
+官方包 `@mytools/commands` 将项目注册的系统命令生成标准工作流动作，动作标识为 `@mytools/commands:注册ID`。修改中文标题或脚本不会改变注册 ID。默认导出的插件没有动作，由 Fishtools 根据项目的 `commandPresets` 装配。
+
+## 注册格式
+
+```json
+{
+  "greet": {
+    "title": "中文问候",
+    "script": "printf '%s\\n' \"$FST_INPUT_name\"",
+    "shell": "sh",
+    "timeout": 30000,
+    "parameters": {
+      "name": {"type": "string", "title": "姓名", "default": "朋友", "required": true}
+    }
+  }
+}
+```
+
+`title` 与 `script` 必须填写；`shell` 省略或设为 `auto` 时，Windows 使用 PowerShell，Linux 使用 sh。也可显式选择 `powershell`、`pwsh`、`sh`、`bash`；目标机器须自行提供相应解释器和外部程序。脚本保留原始多行、引号、管道与重定向，并通过唯一临时文件交给解释器，避免长脚本超过系统命令行长度限制。PowerShell 文件使用 UTF-8 BOM 并固定 UTF-8 输出，最后命令失败时返回非零退出码。
+
+`timeout` 为可选的整数毫秒，范围为 0 到 2147483647，默认沿用受管进程的 30000 毫秒；`0` 表示不限时。第一版用于非交互命令。
+
+注册 ID 最多 80 字符，只能使用 ASCII 字母、数字、下划线、短横线，且以字母或数字开头。`parameters` 为字段对象；字段类型只接受 `string`、`number`、`boolean`，可选中文 `title`、同类型 `default` 和布尔 `required`。参数名以 ASCII 字母或下划线开头，后续可含字母、数字、下划线，最多 80 字符；不能仅以大小写区分，也不能使用原型保留名称。未知字段和不符合类型的默认值会被拒绝。
+
+## 参数与权限
+
+参数通过 `FST_INPUT_字段名` 环境变量传入；字符串原样保留，数值和布尔值转换为文本。Linux 脚本使用 `"$FST_INPUT_name"`，PowerShell 使用 `$env:FST_INPUT_name`，例如 `Write-Output $env:FST_INPUT_name`。请按所选 Shell 的规则引用环境变量。字段值不会拼接到脚本源码。
+
+无参数动作输入为 `{}`。默认以普通用户权限执行。`requireRoot: true` 声明该动作在 Linux 需要 root，宿主执行前预检并显示原因与处理建议；Windows 使用普通用户声明。
+
+## 输出与接口
+
+动作复用宿主的代理规则、取消信号、受管进程与完整日志。返回固定字段 `exitCode`、`stdout`、`stderr`、`outputBytes`、`outputTruncated`。`stdout` 和 `stderr` 各保留最多 65536 字节的尾部，`outputBytes` 分别记录两条流的完整字节数，`outputTruncated` 表示尾部摘要是否截断。完整输出可在运行日志中查看。
+
+临时脚本优先写入本次运行的 `outputDir`；未提供时使用系统临时目录。完成、失败、超时和取消后删除本次文件，保留同目录中的其他文件。PowerShell 文件执行使用本次进程的 `ExecutionPolicy Bypass`，沿用原先命令文本可执行的行为。
+
+非零退出抛出 `EXECUTION_FAILED`，错误包含退出码和输出摘要；超时、取消及解释器缺失沿用宿主错误语义。
+
+包公开导出 `COMMANDS_PLUGIN_ID`、自身目录 `commandsPluginRoot`、`validateCommandPresets(presets)` 和 `createCommandsPlugin(presets = {})`。校验函数返回独立副本；工厂生成标准插件定义，输入校验与默认值由宿主统一处理。