@yanglaofish/fishtools 0.5.1 → 0.5.2

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": ">=24.15.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": ">=24.15.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,8 @@
 
 ## 维护与验证
 
+`app.startShell(script,options)` 执行临时命令，`app.startAction(id,input,context)` 调用任意动作，两者均纳入运行记录与关闭等待。`startCommand(name,input,{expectedPlugin,...context})` 可固定命令提供者，启动时再次检查，防止参数填写期间被其他同名能力替换。`configureCommandPresets` 和 `configureShortcuts` 在备份、冲突检查与变更锁内保存项目设置；命令快捷项在用户明确设置时绑定提供者 ID，普通安装/卸载和未改变目标的整组保存不会重新绑定；已有未绑定项必须明确提供 plugin 或在界面重新选择目标。注册项变化通过定向宿主更新生效，导出快照保留所需定义与有效快捷项。
+
 本模块负责上述职责的实现、文档与回归；跨模块接口调整需要同时检查生产者与消费者。具体维护人员尚未指定。
 
 在仓库根目录执行：

package/node_modules/@mytools/core/package.json

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

package/node_modules/@mytools/core/src/application.js

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

package/node_modules/@mytools/core/src/export-snapshot.js

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

package/node_modules/@mytools/core/src/version.js

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

package/node_modules/@mytools/fst-cli/README.md

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