@yanglaofish/fishtools 0.5.1 → 0.5.3

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,25 @@
 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` 保留构造简短命令参数的兼容接口。
+
+Windows 的 `shell:'auto'` 对单行 `ipconfig` / `ipconfig.exe` 及其字面量参数（如 `ipconfig /all`）直接执行系统目录中的 `ipconfig.exe`，读取当前系统 OEM 代码页后统一解码结果和实时输出。自动适配限于 TextDecoder 支持的 OEM 866、874、932、936、949、950、65001；中文 Windows 的 OEM 936 使用 GBK。代码页探测失败或代码页不受支持（如 437、850）时保留原 Shell 路径。变量、管道、多行、重定向等脚本继续按原 PowerShell 语义执行；复杂脚本中的旧编码与 UTF-8 混合输出没有自动转码。`onStart` 的 `script` 字段保留用户原始指令，直接执行的简单命令同时记录实际程序路径和参数。
+
 `runProcess(file,args,{env,extendEnv=true})` 默认把 `env` 覆盖到宿主环境上。
+
+可选 `onStart({file,args,cwd,script?})` 在程序路径解析后、实际启动前调用并等待完成；回调失败或此时取消不会启动子进程。`args` 使用独立数组，`cwd` 是实际绝对目录，`commandText` 可补充原始 Shell 指令。宿主通过该接口保存过程记录，执行结果与输出编码仍由原有接口返回。
 当调用方已按动作代理规则构造完整环境时，传 `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",
@@ -21,13 +22,13 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=24.15.0"
+    "node": "^22.22.2 || >=24.0.0"
   },
   "dependencies": {
     "@mytools/sdk": "0.1.0",
     "execa": "10.1.0",
     "tree-kill": "1.2.2",
-    "undici": "^8.4.1",
-    "which": "7.0.0"
+    "undici": "7.30.0",
+    "which": "6.0.1"
   }
 }

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}={}) {
+export async function runProcess(file,args=[],{cwd,env,extendEnv=true,signal,timeout=30000,maxBuffer=4*1024*1024,encoding='utf8',onOutput,onStart,commandText,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,15 @@ 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});
+  // 先保存实际程序和参数；记录失败时尚未启动进程，不留下未受管副作用。
+  await onStart?.({file:executable,args:[...args],cwd:path.resolve(cwd??process.cwd()),...(commandText!==undefined?{script:commandText}:{})});
+  if(signal?.aborted)throw new FlowError('操作已取消',{code:'CANCELLED'});
+  // 平台统一收集原始字节和执行上限；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 +71,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 +86,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 +111,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,103 @@
+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'];
+const windowsOemEncodings=new Map([[866,'ibm866'],[874,'windows-874'],[932,'shift_jis'],[936,'gbk'],[949,'euc-kr'],[950,'big5'],[65001,'utf-8']]);
+let windowsOemCodePage;
+
+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 ipconfigArguments(script){
+  // 只解析单行字面量；Shell 运算符、展开、组合引号与特殊引号均留给 PowerShell。
+  if(/[\r\n\u0085\u2028\u2029\u2018\u2019\u201c\u201d]/.test(script))return;
+  const command=/^\s*ipconfig(?:\.exe)?(?=\s|$)/i.exec(script);
+  if(!command)return;
+  let remaining=script.slice(command[0].length);const args=[];
+  while(remaining.trim()){
+    const token=/^\s+(?:'((?:[^']|'')*)'|"([^"`$]*)"|([^\s"'`$;|&<>(){}\[\]#@,]+))(?=\s|$)/.exec(remaining);
+    if(!token)return;
+    const value=token[1]!==undefined?token[1].replaceAll("''","'"):token[2]??token[3];
+    if(value==='--%')return;
+    args.push(value);remaining=remaining.slice(token[0].length);
+  }
+  return args;
+}
+
+async function ipconfigEncoding(windowsRoot,{cwd,env,extendEnv,signal,timeout}){
+  if(windowsOemCodePage===undefined){
+    // GetOEMCP 读取当前系统原生代码页，不修改控制台代码页或依赖用户的区域格式。
+    const source=`Add-Type -Namespace Fst -Name NativeCodePage -MemberDefinition '[System.Runtime.InteropServices.DllImport("kernel32.dll")] public static extern uint GetOEMCP();'; [Console]::WriteLine([Fst.NativeCodePage]::GetOEMCP())`;
+    const encoded=Buffer.from(source,'utf16le').toString('base64');
+    const command=`& ([ScriptBlock]::Create([Text.Encoding]::Unicode.GetString([Convert]::FromBase64String('${encoded}'))))`;
+    let result;
+    try{
+      result=await executeProcess(path.join(windowsRoot,'System32','WindowsPowerShell','v1.0','powershell.exe'),[...powerShellArgs,'-Command',command],{cwd,env,extendEnv,signal,timeout,maxBuffer:4096});
+    }catch(error){
+      if(error.code==='CANCELLED'||error.code==='TIMEOUT')throw error;
+      return;
+    }
+    if(result.exitCode!==0||!/^\d+$/.test(result.stdout.trim()))return;
+    windowsOemCodePage=Number(result.stdout.trim());
+  }
+  // TextDecoder 不支持 OEM 437、850 等代码页；无法准确解码时保留原 Shell 路径。
+  return windowsOemEncodings.get(windowsOemCodePage);
+}
+
+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'});
+  if(process.platform==='win32'&&shell==='auto'){
+    const args=ipconfigArguments(script),windowsRoot=process.env.SystemRoot??process.env.windir;
+    if(args&&windowsRoot&&path.isAbsolute(windowsRoot)){
+      const encoding=processOptions.encoding??await ipconfigEncoding(windowsRoot,processOptions);
+      if(encoding)return execute(path.join(windowsRoot,'System32','ipconfig.exe'),args,{...processOptions,encoding,commandText:script});
+    }
+  }
+  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,commandText:script});
+  }finally{await rm(scriptFile,{force:true});}
+}

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

@@ -18,7 +18,7 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=24.15.0"
+    "node": "^22.22.2 || >=24.0.0"
   },
   "dependencies": {
     "@mytools/sdk": "0.1.0",

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-plugin/src/host.js

@@ -7,7 +7,7 @@ import {prepareEnvironments,platformWarnings} from '@mytools/fst-platform/enviro
 import path from 'node:path';
 import {mkdir} from 'node:fs/promises';
 import {createHash} from 'node:crypto';
-import {createRuntime} from './runtime.js';
+import {createRuntime,validateRuntimes} from './runtime.js';
 import {pluginError} from '@mytools/sdk/diagnostics';
 import {validateNetworkPolicy,resolveNetworkPolicy,createHttpClient,buildProcessEnv} from '@mytools/fst-platform/network';
 import {resolvePrivilegeRequirement,resolvePrivilegePreflight,checkStaticPrivilege,runPrivilegePreflight} from './privileges.js';
@@ -17,10 +17,9 @@ export async function createHost({ plugins = [], config = {}, services = {}, pro
   validateNetworkPolicy(currentNetwork());
   const ctx = new Context();
   const actions = new Map();
-  const definitions = new Map();
+  const definitions = validatePluginDefinitions(plugins);
   const extensions = new Map();
-  const serviceNames = new Set();
-  const commandNames=new Set(),commands=new Map();
+  const commands=new Map();
   function bindContext(context){
     const {application:ignored,...capabilities}=services;
     const bound={...capabilities,...context},execute=bound.runProcess;
@@ -28,7 +27,10 @@ export async function createHost({ plugins = [], config = {}, services = {}, pro
     bound.print=(message,data)=>Promise.resolve(bound.log?.(message,data,{audience:'user'}));
     if(typeof execute==='function')bound.runProcess=(file,args,options={})=>{
       const signal=context.signal&&options.signal?AbortSignal.any([context.signal,options.signal]):context.signal??options.signal;
-      return execute(file,args,{...options,signal,onOutput:async({stream,message})=>{
+      return execute(file,args,{...options,signal,onStart:async invocation=>{
+        await bound.log?.('执行程序',invocation,{kind:'process'});
+        await options.onStart?.(invocation);
+      },onOutput:async({stream,message})=>{
         await bound.log?.(message,undefined,{stream});
         await options.onOutput?.({stream,message});
       }});
@@ -48,6 +50,7 @@ export async function createHost({ plugins = [], config = {}, services = {}, pro
     const stateDir=projectDir&&!readOnly?path.join(projectDir,'.flow','plugin-state',createHash('sha256').update(plugin.id).digest('hex')):undefined;
     if(stateDir)await mkdir(stateDir,{recursive:true});
     for(const message of platformWarnings(plugin))await bound.log?.(message,{code:'PLATFORM_MISMATCH'},{audience:'user'});
+    if(plugin.root)await bound.log?.('插件文件目录',{plugin:plugin.id,directory:plugin.root},{kind:'source'});
     const environments=await prepareEnvironments(plugin,action,environmentOverrides[plugin.id],{cwd:projectDir??process.cwd()});
     context.signal?.throwIfAborted();
     const policy=context.networkPolicy??currentNetwork();
@@ -75,26 +78,8 @@ export async function createHost({ plugins = [], config = {}, services = {}, pro
     if(result.status==='unknown')await context.log?.('权限状态未确认，按本次选择继续运行',{plugin:plugin.id,action:actionName,reason:result.reason},{audience:'user'});
     return requirement;
   }
-  for (const entry of plugins) {
-    const plugin = entry.plugin ?? entry;
-    validateDeclarations(plugin);validateCommands(plugin,commandNames);
-    if (!plugin.id || definitions.has(plugin.id)) throw new FlowError(`插件标识缺失或重复：${plugin.id}`, {code:'VALIDATION'});
-    if (!semver.satisfies(SDK_VERSION, plugin.sdk ?? '^0.1.0')) throw new FlowError(`插件 ${plugin.id} 与 SDK ${SDK_VERSION} 不兼容`, {code:'VALIDATION'});
-    for(const [name,action] of Object.entries(plugin.actions??{})){
-      if(typeof action?.run!=='function')throw new FlowError(`动作 ${plugin.id}:${name} 缺少执行函数`);
-    }
-    for(const [name,extension] of Object.entries(plugin.services??{})){
-      if(serviceNames.has(name))throw new FlowError(`服务重复：${name}`);
-      if(typeof extension!=='function')throw new FlowError(`服务 ${name} 缺少执行函数`);
-      serviceNames.add(name);
-    }
-    definitions.set(plugin.id, {...plugin, root:entry.root});
-  }
   const settingsById=new Map();
   for (const plugin of definitions.values()) {
-    for (const [id, range] of Object.entries(plugin.dependencies ?? {})) {
-      if (!definitions.has(id) || !semver.satisfies(definitions.get(id).version,range)) throw new FlowError(`插件 ${plugin.id} 缺少兼容依赖 ${id}@${range}`,{code:'VALIDATION'});
-    }
     const settings = validate(plugin.config, config[plugin.id] ?? {}, `${plugin.id} 配置`);
     settingsById.set(plugin.id,settings);
   }
@@ -233,3 +218,26 @@ export async function createHost({ plugins = [], config = {}, services = {}, pro
     close:()=>runtime.close(),
   };
 }
+
+// 可用和待配置的插件共用声明检查；配置不足不会掩盖 SDK、依赖或代码错误。
+export function validatePluginDefinitions(entries){
+  const definitions=new Map(),commandNames=new Set(),serviceNames=new Set();
+  for(const entry of entries){
+    const plugin=entry.plugin??entry;
+    validateDeclarations(plugin);validateCommands(plugin,commandNames);
+    if(!plugin.id||definitions.has(plugin.id))throw new FlowError(`插件标识缺失或重复：${plugin.id}`,{code:'VALIDATION'});
+    if(!semver.satisfies(SDK_VERSION,plugin.sdk??'^0.1.0'))throw new FlowError(`插件 ${plugin.id} 与 SDK ${SDK_VERSION} 不兼容`,{code:'VALIDATION'});
+    for(const [name,action] of Object.entries(plugin.actions??{}))if(typeof action?.run!=='function')throw new FlowError(`动作 ${plugin.id}:${name} 缺少执行函数`,{code:'VALIDATION'});
+    for(const [name,extension] of Object.entries(plugin.services??{})){
+      if(serviceNames.has(name))throw new FlowError(`服务重复：${name}`,{code:'VALIDATION'});
+      if(typeof extension!=='function')throw new FlowError(`服务 ${name} 缺少执行函数`,{code:'VALIDATION'});
+      serviceNames.add(name);
+    }
+    definitions.set(plugin.id,{...plugin,root:entry.root});
+  }
+  for(const plugin of definitions.values())for(const [id,range] of Object.entries(plugin.dependencies??{})){
+    if(!definitions.has(id)||!semver.satisfies(definitions.get(id).version,range))throw new FlowError(`插件 ${plugin.id} 缺少兼容依赖 ${id}@${range}`,{code:'VALIDATION'});
+  }
+  validateRuntimes(definitions,new Context());
+  return definitions;
+}

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

@@ -16,7 +16,7 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=24.15.0"
+    "node": "^22.22.2 || >=24.0.0"
   },
   "dependencies": {
     "@mytools/sdk": "0.1.0"

package/manual/packages/fst-workflow/src/engine.js

@@ -57,7 +57,7 @@ export async function runWorkflow({store,host,id,input={},signal,onEvent=()=>{},
       let output;
       if(step.action)output=await host.invoke(step.action,args,{
         ...context,signal:currentSignal,runId,stepId:step.id,callPath,workflow:w,
-        log:(message,data,meta={})=>emit({type:'log',stream:meta.stream,...(meta.audience==='user'?{audience:'user'}:{}),...base,message,data}),
+        log:(message,data,meta={})=>emit({type:'log',stream:meta.stream,...(meta.audience==='user'?{audience:'user'}:{}),...(['process','source'].includes(meta.kind)?{kind:meta.kind}:{}),...base,message,data}),
       });
       else if(step.workflow)output=await execute(store.childId(step.workflow),args,callPath,currentSignal,reportFailure);
       else if(step.branch){

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

@@ -6,6 +6,8 @@
 
 项目初始化、模板、工作流文件、插件安装批次、租约、开发引用及便携工作区。插件执行由 plugin 负责，系统调用由 platform 负责。
 
+`@mytools/fst-workspace/registry` 提供用户级插件库路径、工作区登记与跨工作区工作流引用查询。共享库复用安装批次、状态恢复备份及租约；普通工作区的配置与文件仍独立保存。
+
 内部依赖：`@mytools/sdk`、`@mytools/fst-platform`、`@mytools/fst-plugin`、`@mytools/fst-workflow`。
 ## 公开入口
 
@@ -17,12 +19,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,8 +8,10 @@
     ".": "./src/index.js",
     "./workflows": "./src/workflows.js",
     "./project": "./src/project.js",
+    "./shortcuts": "./src/shortcuts.js",
     "./plugins": "./src/plugins.js",
     "./installations": "./src/plugin-installations.js",
+    "./registry": "./src/plugin-registry.js",
     "./bundles": "./src/bundle-workspace.js",
     "./package.json": "./package.json"
   },
@@ -21,7 +23,7 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=24.15.0"
+    "node": "^22.22.2 || >=24.0.0"
   },
   "dependencies": {
     "@mytools/sdk": "0.1.0",

package/manual/packages/fst-workspace/src/plugin-registry.js

@@ -0,0 +1,58 @@
+import path from 'node:path';
+import os from 'node:os';
+import {mkdir,writeFile,rename} from 'node:fs/promises';
+import {randomUUID} from 'node:crypto';
+import {readJson} from '@mytools/fst-platform/json';
+import {withPluginMutation} from './plugin-installations.js';
+import {WorkflowStore} from './workflows.js';
+import {readPluginState} from './plugin-installations.js';
+import {loadPlugin} from '@mytools/fst-plugin/loader';
+
+export const userPluginRegistry=()=>path.resolve(process.env.FISHTOOLS_HOME??path.join(os.homedir(),'.fishtools'),'plugins');
+
+export async function registerWorkspace(registryDir,projectDir){
+  return withPluginMutation(registryDir,async()=>{
+    const file=path.join(registryDir,'.flow','workspaces.json'),projects=await readJson(file,[]),directory=path.resolve(projectDir);
+    if(projects.includes(directory))return;
+    const temporary=`${file}.${randomUUID()}.tmp`;
+    await mkdir(path.dirname(file),{recursive:true});
+    await writeFile(temporary,JSON.stringify([...projects,directory],null,2));await rename(temporary,file);
+  });
+}
+
+function referencedActions(steps,id,result=new Set()){
+  for(const step of steps??[]){
+    if(step.action?.startsWith(`${id}:`))result.add(step.action);
+    if(step.branch){referencedActions(step.branch.then,id,result);referencedActions(step.branch.else,id,result);}
+    if(step.parallel)referencedActions(step.parallel.steps,id,result);
+  }
+  return [...result];
+}
+
+// 调用方持有共享库锁；各工作区的工作流修改也持有该锁，因此扫描期间不会补写引用。
+export async function registryWorkflowReferences(registryDir,id){
+  const projects=await readJson(path.join(registryDir,'.flow','workspaces.json'),[]),references=[];
+  for(const projectDir of projects){
+    for(const workflow of await new WorkflowStore(path.join(projectDir,'workflows')).list()){
+      const actions=referencedActions(workflow.steps,id);
+      if(actions.length)references.push({projectDir,id:workflow.id,title:workflow.title??workflow.id,actions});
+    }
+  }
+  return references;
+}
+
+export async function registryPluginReferences(registryDir,id,{globalPlugins=[]}={}){
+  const projects=await readJson(path.join(registryDir,'.flow','workspaces.json'),[]),globalState=await readPluginState(registryDir),references=[];
+  const excluded=new Set([...Object.keys(globalState.dependencies??{}),...Object.keys(globalState.links??{}),...(globalState.disabledLegacy??[])]);
+  for(const projectDir of projects){
+    const project=await readJson(path.join(projectDir,'flow.project.json'),{});
+    if(project.readOnly||project.baseBundle)continue;
+    const local=await readPluginState(projectDir),definitions=new Map(globalPlugins.map(plugin=>[plugin.id,plugin]));
+    const add=async(spec,base)=>{const {plugin}=await loadPlugin(spec,base);if(!excluded.has(plugin.id))definitions.set(plugin.id,plugin);};
+    for(const spec of project.plugins??[])if(!excluded.has(spec))await add(spec,projectDir);
+    for(const name of Object.keys(local.dependencies??{}))if(!excluded.has(name))await add(name,local.root);
+    for(const [name,source] of Object.entries(local.links??{}))if(!excluded.has(name))await add(source,projectDir);
+    for(const plugin of definitions.values())if(plugin.id!==id&&Object.hasOwn(plugin.dependencies??{},id))references.push({projectDir,plugin:plugin.id});
+  }
+  return references;
+}

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

@@ -5,22 +5,25 @@ import {FlowError} from '@mytools/sdk';
 import {readJson} from '@mytools/fst-platform/json';
 import {npm} from '@mytools/fst-platform/npm';
 import {loadPlugin} from '@mytools/fst-plugin/loader';
-export async function installGeneration(projectDir,{add,remove,link,state}) {
+export async function installGeneration(projectDir,{add,remove,link,state,sourceDir=projectDir}) {
   const root=path.join(projectDir,'.flow','installations',randomUUID());
   await mkdir(root,{recursive:true});
   const dependencies={...(state?.dependencies??{})};
   const links={...(state?.links??{})};
+  const disabledLegacy=new Set(state?.disabledLegacy??[]);
   if(remove){delete dependencies[remove];delete links[remove];}
+  if(remove&&state?.global)disabledLegacy.add(remove);
   if(link){
     const source=path.resolve(link),pkg=await readJson(path.join(source,'package.json'));
     const loaded=await loadPlugin(source,projectDir);
     if(!pkg.name||pkg.name!==loaded.plugin?.id||pkg.version!==loaded.plugin?.version)throw new FlowError('开发插件的包名/版本必须与插件 id/version 一致',{code:'VALIDATION'});
     links[pkg.name]=source;delete dependencies[pkg.name];
+    disabledLegacy.delete(pkg.name);
   }
   await writeFile(path.join(root,'package.json'),JSON.stringify({name:'flow-project-plugins',private:true,dependencies},null,2));
   let source=add;
   if(add) {
-    try {await access(path.resolve(projectDir,add));source=path.resolve(projectDir,add);} catch {}
+    try {await access(path.resolve(sourceDir,add));source=path.resolve(sourceDir,add);} catch {}
     if(source.startsWith('-')) throw new FlowError('插件来源不能以选项符号开头',{code:'VALIDATION'});
   }
   if(source||Object.keys(dependencies).length){
@@ -29,7 +32,7 @@ export async function installGeneration(projectDir,{add,remove,link,state}) {
   }
   const pkg=await readJson(path.join(root,'package.json'));
   const loaded=[];
-  for(const name of Object.keys(pkg.dependencies??{})){delete links[name];loaded.push(await loadPlugin(name,root));}
+  for(const name of Object.keys(pkg.dependencies??{})){delete links[name];disabledLegacy.delete(name);loaded.push(await loadPlugin(name,root));}
   for(const source of Object.values(links))loaded.push(await loadPlugin(source,projectDir));
-  return {state:{root,dependencies:pkg.dependencies??{},links,...(state?.root?{previousRoot:state.root}:{})},loaded};
+  return {state:{root,dependencies:pkg.dependencies??{},links,...(state?.global?{global:true,disabledLegacy:[...disabledLegacy]}:{}),...(state?.root?{previousRoot:state.root}:{})},loaded};
 }