@yanglaofish/fishtools 0.5.1 → 0.5.3

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/fst-workspace/src/workflows.js

@@ -71,16 +71,18 @@ export class WorkflowStore {
     const files=await readdir(this.root);
     return Promise.all(files.filter(f=>f.endsWith('.yaml')).sort().map(f=>this.get(f.slice(0,-5))));
   }
-  async remove(id){
+  async remove(id,{backup=true}={}){
+    if(typeof backup!=='boolean')throw new FlowError('backup 必须是布尔值',{code:'VALIDATION'});
     await this.get(id);
     const refers=steps=>steps.some(step=>step.workflow&&this.childId(step.workflow)===id||step.branch&&(refers(step.branch.then)||refers(step.branch.else??[]))||step.parallel&&refers(step.parallel.steps));
     const dependents=(await this.list()).filter(flow=>flow.id!==id&&refers(flow.steps));
     if(dependents.length)throw new FlowError(`工作流仍被引用：${dependents.map(flow=>flow.title??flow.id).join('、')}`);
+    if(!backup){await unlink(this.file(id));return null;}
     const directory=path.join(path.dirname(this.root),'.flow','deleted-workflows');
     await mkdir(directory,{recursive:true});
-    const backup=path.join(directory,`${id}-${randomUUID()}.yaml`);
+    const backupFile=path.join(directory,`${id}-${randomUUID()}.yaml`);
     // 同项目内原子移动，备份保留完整原文；复制回原文件名即可恢复。
-    await rename(this.file(id),backup);return backup;
+    await rename(this.file(id),backupFile);return backupFile;
   }
   childId(reference) {
     if(typeof reference!=='string' || !/^(\.\/)?[A-Za-z0-9][A-Za-z0-9_-]*\.yaml$/.test(reference)) throw new FlowError(`子流程必须位于工作流目录内：${reference}`,{code:'VALIDATION'});

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/packages/pack/package.json

@@ -9,10 +9,10 @@
   "license": "MIT",
   "dependencies": {
     "@mytools/sdk": "0.1.0",
-    "@npmcli/arborist": "10.0.3",
+    "@npmcli/arborist": "9.9.2",
     "archiver": "8.0.0",
-    "make-fetch-happen": "16.0.1",
-    "npm-packlist": "11.3.0",
+    "make-fetch-happen": "15.0.6",
+    "npm-packlist": "10.0.4",
     "tar": "7.5.22",
     "yaml": "2.9.1",
     "@mytools/fst-platform": "0.1.0",

package/manual/packages/pack/runtime-cache.js

@@ -0,0 +1,26 @@
+import {readFile,rename,unlink,writeFile} from 'node:fs/promises';
+import {createHash,randomUUID} from 'node:crypto';
+import {FlowError} from '@mytools/sdk';
+
+export async function writeCachedFile(file,bytes){
+  const temporary=`${file}.${randomUUID()}.tmp`;
+  try{
+    await writeFile(temporary,bytes,{flag:'wx'});
+    try{await rename(temporary,file);}catch(error){
+      // Windows 上并发替换可能返回 EPERM；仅接受另一写入者已留下的完全相同内容。
+      if(process.platform!=='win32'||!['EPERM','EACCES','EBUSY'].includes(error.code))throw error;
+      let existing;try{existing=await readFile(file);}catch{throw error;}
+      if(!existing.equals(bytes))throw error;
+    }
+  }
+  finally{await unlink(temporary).catch(error=>{if(error.code!=='ENOENT')throw error;});}
+}
+
+export async function readVerifiedCache(file,load,{sha256,message}){
+  let bytes,missing=false;
+  try{bytes=await readFile(file);}catch(error){if(error.code!=='ENOENT')throw error;missing=true;bytes=await load();}
+  if(createHash('sha256').update(bytes).digest('hex')!==sha256)throw new FlowError(message);
+  // 命中有效缓存不再截断重写；冷缓存校验后原子替换，读取者只见完整文件。
+  if(missing)await writeCachedFile(file,bytes);
+  return bytes;
+}

package/manual/packages/pack/runtime.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import * as tar from 'tar';
 import fetch from 'make-fetch-happen';
 import { FlowError } from '@mytools/sdk';
+import {readVerifiedCache,writeCachedFile} from './runtime-cache.js';
 
 export const NODE_VERSION='24.15.0';
 const hashes={
@@ -24,13 +25,11 @@ export async function copyRuntime({target,directory,cacheDir,runtimePath,include
   if(runtimePath){
     if(!win)throw new FlowError('自定义 runtimePath 首版只接受已验证的 Windows Node.js 文件');
     bytes=await readFile(runtimePath);
+    if(digest(bytes)!==hashes[target])throw new FlowError('Node.js 运行时校验失败，请检查缓存或指定文件');
+    await writeCachedFile(cache,bytes);
   }else{
-    try{bytes=await readFile(cache);}catch{
-      bytes=await download(`https://nodejs.org/download/release/v${NODE_VERSION}/${file}`);
-    }
+    bytes=await readVerifiedCache(cache,()=>download(`https://nodejs.org/download/release/v${NODE_VERSION}/${file}`),{sha256:hashes[target],message:'Node.js 运行时校验失败，请检查缓存或指定文件'});
   }
-  if(digest(bytes)!==hashes[target])throw new FlowError('Node.js 运行时校验失败，请检查缓存或指定文件');
-  await writeFile(cache,bytes);
   if(win)await writeFile(path.join(directory,'runtime','node.exe'),bytes);
   else{
     const extraction=path.join(cacheDir,'linux-extracted');await mkdir(extraction,{recursive:true});
@@ -43,16 +42,13 @@ export async function copyRuntime({target,directory,cacheDir,runtimePath,include
   try{license=await readFile(licenseCache);}catch{
     try{if(process.versions.node!==NODE_VERSION)throw new Error('版本不同');license=await readFile(path.join(path.dirname(process.execPath),'LICENSE'));}
     catch{license=await download(`https://raw.githubusercontent.com/nodejs/node/v${NODE_VERSION}/LICENSE`);}
-    await writeFile(licenseCache,license);
+    await writeCachedFile(licenseCache,license);
   }
   await mkdir(path.join(directory,'licenses'),{recursive:true});await writeFile(path.join(directory,'licenses','NODE_LICENSE'),license);
   if(includeNpm){
     // npm 是平台无关的 JS，直接复用已固定校验的官方 Linux 分发中的完整 npm 目录。
     const npmArchive=path.join(cacheDir,`node-v${NODE_VERSION}-linux-x64.tar.gz`);
-    let npmBytes;
-    try{npmBytes=await readFile(npmArchive);}catch{npmBytes=await download(`https://nodejs.org/download/release/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.gz`);}
-    if(digest(npmBytes)!==hashes['linux-x64-glibc'])throw new FlowError('npm 来源的 Node.js 归档校验失败');
-    await writeFile(npmArchive,npmBytes);
+    await readVerifiedCache(npmArchive,()=>download(`https://nodejs.org/download/release/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.gz`),{sha256:hashes['linux-x64-glibc'],message:'npm 来源的 Node.js 归档校验失败'});
     const extraction=path.join(cacheDir,'npm-extracted');await mkdir(extraction,{recursive:true});
     await tar.x({file:npmArchive,cwd:extraction,filter:name=>name.includes('/lib/node_modules/npm/')});
     await cp(path.join(extraction,`node-v${NODE_VERSION}-linux-x64/lib/node_modules/npm`),path.join(directory,'runtime/node_modules/npm'),{recursive:true,dereference:true});

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 = {})`。校验函数返回独立副本；工厂生成标准插件定义，输入校验与默认值由宿主统一处理。

package/manual/plugins/commands/index.js

@@ -0,0 +1,94 @@
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {createHash} from 'node:crypto';
+import {definePlugin,FlowError} from '@mytools/sdk';
+import {runShell} from '@mytools/fst-platform/shell';
+
+export const COMMANDS_PLUGIN_ID='@mytools/commands';
+export const commandsPluginRoot=path.dirname(fileURLToPath(import.meta.url));
+
+const reserved=new Set(['__proto__','constructor','prototype']);
+const validObject=value=>value!==null&&typeof value==='object'&&!Array.isArray(value)&&[Object.prototype,null].includes(Object.getPrototypeOf(value));
+const validText=value=>typeof value==='string'&&Boolean(value.trim())&&!value.includes('\u0000');
+const invalid=(location,message)=>{throw new FlowError(`${location}：${message}`,{code:'VALIDATION',details:{path:location}});};
+function fields(value,allowed,location){
+  if(!validObject(value))invalid(location,'必须为字段对象');
+  for(const key of Reflect.ownKeys(value))if(typeof key!=='string'||!allowed.includes(key))invalid(`${location}.${String(key)}`,'包含未知字段');
+}
+
+export function validateCommandPresets(presets){
+  if(!validObject(presets))invalid('commandPresets','必须为命令注册对象');
+  for(const id of Reflect.ownKeys(presets)){
+    const location=`commandPresets.${String(id)}`;
+    if(typeof id!=='string'||!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,79}$/.test(id)||reserved.has(id))invalid(location,'ID 只能使用 ASCII 字母、数字、下划线和短横线，最多 80 字符，且不能为原型保留名称');
+    const preset=presets[id];
+    fields(preset,['title','script','shell','timeout','parameters','requireRoot'],location);
+    if(!validText(preset.title))invalid(`${location}.title`,'标题必须为非空字符串');
+    if(!validText(preset.script))invalid(`${location}.script`,'命令文本必须为非空字符串，且不能包含 NUL 字符');
+    if(preset.shell!==undefined&&!['auto','powershell','pwsh','sh','bash'].includes(preset.shell))invalid(`${location}.shell`,'Shell 必须为 auto、powershell、pwsh、sh 或 bash');
+    if(preset.timeout!==undefined&&(!Number.isSafeInteger(preset.timeout)||preset.timeout<0||preset.timeout>2147483647))invalid(`${location}.timeout`,'超时必须为 0 到 2147483647 的整数毫秒，0 表示不限时');
+    if(preset.requireRoot!==undefined&&typeof preset.requireRoot!=='boolean')invalid(`${location}.requireRoot`,'root 需求必须为布尔值');
+    if(preset.parameters===undefined)continue;
+    if(!validObject(preset.parameters))invalid(`${location}.parameters`,'参数必须为字段对象');
+    const names=new Set();
+    for(const name of Reflect.ownKeys(preset.parameters)){
+      const at=`${location}.parameters.${String(name)}`;
+      if(typeof name!=='string'||!/^[a-zA-Z_][a-zA-Z0-9_]{0,79}$/.test(name)||reserved.has(name)||Object.hasOwn(Object.prototype,name))invalid(at,'参数名只能使用 ASCII 字母、数字和下划线，不能以数字开头或使用原型保留名称');
+      const portable=name.toLowerCase();
+      if(names.has(portable))invalid(at,'参数名不能仅以大小写区分，以免 Windows 环境变量冲突');
+      names.add(portable);
+      const field=preset.parameters[name];
+      fields(field,['type','title','default','required'],at);
+      if(!['string','number','boolean'].includes(field.type))invalid(`${at}.type`,'参数类型必须为 string、number 或 boolean');
+      if(field.title!==undefined&&!validText(field.title))invalid(`${at}.title`,'参数标题必须为非空字符串');
+      if(field.required!==undefined&&typeof field.required!=='boolean')invalid(`${at}.required`,'必填声明必须为布尔值');
+      if(Object.hasOwn(field,'default')&&(typeof field.default!==field.type||field.type==='number'&&!Number.isFinite(field.default)||field.type==='string'&&field.default.includes('\u0000')))invalid(`${at}.default`,'默认值必须符合参数类型且可作为环境变量传递');
+    }
+  }
+  try{return structuredClone(presets);}
+  catch(cause){throw new FlowError('命令注册项必须可复制和保存',{code:'VALIDATION',cause});}
+}
+
+function inputSchema(parameters){
+  const properties=Object.fromEntries(Object.entries(parameters).map(([name,{type,title,default:value}])=>[name,{
+    type,title:title??name,...(type==='string'?{pattern:'^[^\\u0000]*$'}:{}),
+    ...(Object.hasOwn(parameters[name],'default')?{default:value}:{}),
+  }]));
+  return {type:'object',properties,required:Object.entries(parameters).filter(([,field])=>field.required).map(([name])=>name),additionalProperties:false};
+}
+
+const outputSchema={type:'object',properties:{
+  exitCode:{type:'integer',title:'退出码'},stdout:{type:'string',title:'标准输出摘要'},stderr:{type:'string',title:'标准错误摘要'},
+  outputBytes:{type:'object',title:'完整输出字节数',properties:{stdout:{type:'integer',minimum:0},stderr:{type:'integer',minimum:0}},required:['stdout','stderr'],additionalProperties:false},
+  outputTruncated:{type:'boolean',title:'摘要已截断'},
+},required:['exitCode','stdout','stderr','outputBytes','outputTruncated'],additionalProperties:false};
+
+export function createCommandsPlugin(presets={}){
+  const checked=validateCommandPresets(presets);
+  const actions=Object.fromEntries(Object.entries(checked).map(([id,preset])=>{
+    const parameters=preset.parameters??{};
+    return [id,{
+      title:preset.title,description:'执行已注册的非交互 Shell 命令，完整输出保存到运行日志。',
+      input:inputSchema(parameters),output:structuredClone(outputSchema),
+      ...(preset.requireRoot?{requirements:{privilege:{linux:{level:'root',reason:`命令“${preset.title}”声明需要 Linux root 权限`,remediation:'请使用具备 root 权限的会话运行 Fishtools，或修改命令以使用普通用户权限。'}}}}:{}),
+      async run(input,ctx){
+        // 仅传递字段值；参数中的引号、换行和命令替换都不会进入脚本源码。
+        const env=Object.fromEntries(Object.keys(parameters).map(name=>[`FST_INPUT_${name}`,Object.hasOwn(input,name)?String(input[name]):'']));
+        const {exitCode,stdout,stderr,outputBytes,outputTruncated}=await runShell(preset.script,{
+          shell:preset.shell??'auto',runProcess:ctx.runProcess,temporaryDir:ctx.outputDir,
+          signal:ctx.signal,cwd:ctx.projectDir,env,outputMode:'stream',summaryBytes:65536,
+          ...(preset.timeout!==undefined?{timeout:preset.timeout}:{}),
+        });
+        const output={exitCode,stdout,stderr,outputBytes,outputTruncated};
+        if(exitCode!==0)throw new FlowError(`命令“${preset.title}”执行失败（退出码 ${exitCode}）：${(stderr||stdout||'没有输出').slice(-2000)}`,{code:'EXECUTION_FAILED',details:output});
+        return output;
+      },
+    }];
+  }));
+  // run 的函数文本不包含闭包中的脚本；摘要使定向更新能识别脚本、Shell 和超时变化。
+  const commandPresetDigest=createHash('sha256').update(JSON.stringify(checked)).digest('hex');
+  return definePlugin({id:COMMANDS_PLUGIN_ID,version:'0.1.0',commandPresetDigest,title:'轻量命令',description:'将项目中注册的系统命令作为稳定的工作流动作执行。',platforms:['win32','linux'],
+    requirements:{privilege:{linux:{level:'user'},win32:{level:'user'}}},actions});
+}
+
+export default createCommandsPlugin();

package/manual/plugins/commands/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@mytools/commands",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./package.json": "./package.json"
+  },
+  "files": ["index.js", "README.md", "LICENSE"],
+  "license": "MIT",
+  "engines": {"node": "^22.22.2 || >=24.0.0"},
+  "dependencies": {
+    "@mytools/sdk": "0.1.0",
+    "@mytools/fst-platform": "0.1.0"
+  }
+}

package/node_modules/@mytools/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/node_modules/@mytools/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 = {})`。校验函数返回独立副本；工厂生成标准插件定义，输入校验与默认值由宿主统一处理。

package/node_modules/@mytools/commands/index.js

@@ -0,0 +1,94 @@
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {createHash} from 'node:crypto';
+import {definePlugin,FlowError} from '@mytools/sdk';
+import {runShell} from '@mytools/fst-platform/shell';
+
+export const COMMANDS_PLUGIN_ID='@mytools/commands';
+export const commandsPluginRoot=path.dirname(fileURLToPath(import.meta.url));
+
+const reserved=new Set(['__proto__','constructor','prototype']);
+const validObject=value=>value!==null&&typeof value==='object'&&!Array.isArray(value)&&[Object.prototype,null].includes(Object.getPrototypeOf(value));
+const validText=value=>typeof value==='string'&&Boolean(value.trim())&&!value.includes('\u0000');
+const invalid=(location,message)=>{throw new FlowError(`${location}：${message}`,{code:'VALIDATION',details:{path:location}});};
+function fields(value,allowed,location){
+  if(!validObject(value))invalid(location,'必须为字段对象');
+  for(const key of Reflect.ownKeys(value))if(typeof key!=='string'||!allowed.includes(key))invalid(`${location}.${String(key)}`,'包含未知字段');
+}
+
+export function validateCommandPresets(presets){
+  if(!validObject(presets))invalid('commandPresets','必须为命令注册对象');
+  for(const id of Reflect.ownKeys(presets)){
+    const location=`commandPresets.${String(id)}`;
+    if(typeof id!=='string'||!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,79}$/.test(id)||reserved.has(id))invalid(location,'ID 只能使用 ASCII 字母、数字、下划线和短横线，最多 80 字符，且不能为原型保留名称');
+    const preset=presets[id];
+    fields(preset,['title','script','shell','timeout','parameters','requireRoot'],location);
+    if(!validText(preset.title))invalid(`${location}.title`,'标题必须为非空字符串');
+    if(!validText(preset.script))invalid(`${location}.script`,'命令文本必须为非空字符串，且不能包含 NUL 字符');
+    if(preset.shell!==undefined&&!['auto','powershell','pwsh','sh','bash'].includes(preset.shell))invalid(`${location}.shell`,'Shell 必须为 auto、powershell、pwsh、sh 或 bash');
+    if(preset.timeout!==undefined&&(!Number.isSafeInteger(preset.timeout)||preset.timeout<0||preset.timeout>2147483647))invalid(`${location}.timeout`,'超时必须为 0 到 2147483647 的整数毫秒，0 表示不限时');
+    if(preset.requireRoot!==undefined&&typeof preset.requireRoot!=='boolean')invalid(`${location}.requireRoot`,'root 需求必须为布尔值');
+    if(preset.parameters===undefined)continue;
+    if(!validObject(preset.parameters))invalid(`${location}.parameters`,'参数必须为字段对象');
+    const names=new Set();
+    for(const name of Reflect.ownKeys(preset.parameters)){
+      const at=`${location}.parameters.${String(name)}`;
+      if(typeof name!=='string'||!/^[a-zA-Z_][a-zA-Z0-9_]{0,79}$/.test(name)||reserved.has(name)||Object.hasOwn(Object.prototype,name))invalid(at,'参数名只能使用 ASCII 字母、数字和下划线，不能以数字开头或使用原型保留名称');
+      const portable=name.toLowerCase();
+      if(names.has(portable))invalid(at,'参数名不能仅以大小写区分，以免 Windows 环境变量冲突');
+      names.add(portable);
+      const field=preset.parameters[name];
+      fields(field,['type','title','default','required'],at);
+      if(!['string','number','boolean'].includes(field.type))invalid(`${at}.type`,'参数类型必须为 string、number 或 boolean');
+      if(field.title!==undefined&&!validText(field.title))invalid(`${at}.title`,'参数标题必须为非空字符串');
+      if(field.required!==undefined&&typeof field.required!=='boolean')invalid(`${at}.required`,'必填声明必须为布尔值');
+      if(Object.hasOwn(field,'default')&&(typeof field.default!==field.type||field.type==='number'&&!Number.isFinite(field.default)||field.type==='string'&&field.default.includes('\u0000')))invalid(`${at}.default`,'默认值必须符合参数类型且可作为环境变量传递');
+    }
+  }
+  try{return structuredClone(presets);}
+  catch(cause){throw new FlowError('命令注册项必须可复制和保存',{code:'VALIDATION',cause});}
+}
+
+function inputSchema(parameters){
+  const properties=Object.fromEntries(Object.entries(parameters).map(([name,{type,title,default:value}])=>[name,{
+    type,title:title??name,...(type==='string'?{pattern:'^[^\\u0000]*$'}:{}),
+    ...(Object.hasOwn(parameters[name],'default')?{default:value}:{}),
+  }]));
+  return {type:'object',properties,required:Object.entries(parameters).filter(([,field])=>field.required).map(([name])=>name),additionalProperties:false};
+}
+
+const outputSchema={type:'object',properties:{
+  exitCode:{type:'integer',title:'退出码'},stdout:{type:'string',title:'标准输出摘要'},stderr:{type:'string',title:'标准错误摘要'},
+  outputBytes:{type:'object',title:'完整输出字节数',properties:{stdout:{type:'integer',minimum:0},stderr:{type:'integer',minimum:0}},required:['stdout','stderr'],additionalProperties:false},
+  outputTruncated:{type:'boolean',title:'摘要已截断'},
+},required:['exitCode','stdout','stderr','outputBytes','outputTruncated'],additionalProperties:false};
+
+export function createCommandsPlugin(presets={}){
+  const checked=validateCommandPresets(presets);
+  const actions=Object.fromEntries(Object.entries(checked).map(([id,preset])=>{
+    const parameters=preset.parameters??{};
+    return [id,{
+      title:preset.title,description:'执行已注册的非交互 Shell 命令，完整输出保存到运行日志。',
+      input:inputSchema(parameters),output:structuredClone(outputSchema),
+      ...(preset.requireRoot?{requirements:{privilege:{linux:{level:'root',reason:`命令“${preset.title}”声明需要 Linux root 权限`,remediation:'请使用具备 root 权限的会话运行 Fishtools，或修改命令以使用普通用户权限。'}}}}:{}),
+      async run(input,ctx){
+        // 仅传递字段值；参数中的引号、换行和命令替换都不会进入脚本源码。
+        const env=Object.fromEntries(Object.keys(parameters).map(name=>[`FST_INPUT_${name}`,Object.hasOwn(input,name)?String(input[name]):'']));
+        const {exitCode,stdout,stderr,outputBytes,outputTruncated}=await runShell(preset.script,{
+          shell:preset.shell??'auto',runProcess:ctx.runProcess,temporaryDir:ctx.outputDir,
+          signal:ctx.signal,cwd:ctx.projectDir,env,outputMode:'stream',summaryBytes:65536,
+          ...(preset.timeout!==undefined?{timeout:preset.timeout}:{}),
+        });
+        const output={exitCode,stdout,stderr,outputBytes,outputTruncated};
+        if(exitCode!==0)throw new FlowError(`命令“${preset.title}”执行失败（退出码 ${exitCode}）：${(stderr||stdout||'没有输出').slice(-2000)}`,{code:'EXECUTION_FAILED',details:output});
+        return output;
+      },
+    }];
+  }));
+  // run 的函数文本不包含闭包中的脚本；摘要使定向更新能识别脚本、Shell 和超时变化。
+  const commandPresetDigest=createHash('sha256').update(JSON.stringify(checked)).digest('hex');
+  return definePlugin({id:COMMANDS_PLUGIN_ID,version:'0.1.0',commandPresetDigest,title:'轻量命令',description:'将项目中注册的系统命令作为稳定的工作流动作执行。',platforms:['win32','linux'],
+    requirements:{privilege:{linux:{level:'user'},win32:{level:'user'}}},actions});
+}
+
+export default createCommandsPlugin();

package/node_modules/@mytools/commands/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@mytools/commands",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./package.json": "./package.json"
+  },
+  "files": ["index.js", "README.md", "LICENSE"],
+  "license": "MIT",
+  "engines": {"node": "^22.22.2 || >=24.0.0"},
+  "dependencies": {
+    "@mytools/sdk": "0.1.0",
+    "@mytools/fst-platform": "0.1.0"
+  }
+}

package/node_modules/@mytools/core/README.md

@@ -6,7 +6,7 @@
 
 组合各能力模块、协调运行与关闭、提供 CLI/Web 共用应用接口及导出声明快照。日志写入和缓存由 logs 负责；导出实现通过可选 pack 依赖加载。
 
-内部依赖：`@mytools/sdk`、`@mytools/fst-platform`、`@mytools/fst-logs`、`@mytools/fst-workflow`、`@mytools/fst-plugin`、`@mytools/fst-workspace`、`@mytools/pack`。
+内部依赖：`@mytools/sdk`、`@mytools/fst-platform`、`@mytools/fst-logs`、`@mytools/fst-workflow`、`@mytools/fst-plugin`、`@mytools/fst-workspace`、官方 `@mytools/commands`、`@mytools/pack`。
 `@mytools/pack` 是可选 peer 依赖；普通发行包含它，只读发行省略它。既有 `/process`、`/bundle`、`/environments` 子入口保留兼容转发。
 
 ## 公开入口
@@ -25,6 +25,10 @@
 
 ## 维护与验证
 
+`createApplication({projectDir,pluginRegistryDir})` 可让多个工作区读取同一插件库；CLI 默认接入用户级全局库，程序未传此选项时保留工作区模式。分发包始终使用自身工作区安装状态。`listPlugins()` 返回 scope/source 和待配置原因；`pluginDefinition(id)` 返回作者声明。`app.resultsDir` 是业务文件根，`app.outputDir` 保留为日志根；插件 `ctx.outputDir` 与 `ctx.logDir` 分别对应本次业务目录和日志目录。
+
+`app.startShell(script,options)` 执行临时命令，`app.startAction(id,input,context)` 调用任意动作，两者均纳入运行记录与关闭等待。`startCommand(name,input,{expectedPlugin,...context})` 可固定命令提供者，启动时再次检查，防止参数填写期间被其他同名能力替换。`configureCommandPresets` 和 `configureShortcuts` 在备份、冲突检查与变更锁内保存项目设置；命令快捷项在用户明确设置时绑定提供者 ID，普通安装/卸载和未改变目标的整组保存不会重新绑定；已有未绑定项必须明确提供 plugin 或在界面重新选择目标。注册项变化通过定向宿主更新生效，导出快照保留所需定义与有效快捷项。
+
 本模块负责上述职责的实现、文档与回归；跨模块接口调整需要同时检查生产者与消费者。具体维护人员尚未指定。
 
 在仓库根目录执行：