@yanglaofish/fishtools 0.5.3 → 0.6.0

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

@@ -19,6 +19,8 @@
 
 ## 维护与验证
 
+`plugin lint` 的 `UNMANAGED_PROCESS` 迁移警告识别可追溯的 child_process、execa、cross-spawn、shelljs.exec 及平台底层 runProcess 调用，指向文件行列并建议上下文 ctx.runProcess。只导入未调用、注释、字符串及无法确认的局部重名不据此告警。诊断保持 warning，不拒绝旧插件；复杂动态代码、依赖内部和解释器内部不保证覆盖，不构成安全隔离。
+
 本模块负责上述职责的实现、文档与回归；跨模块接口调整需要同时检查生产者与消费者。具体维护人员尚未指定。
 
 在仓库根目录执行：

package/manual/packages/fst-devtools/src/plugin-quality.js

@@ -3,6 +3,7 @@ import {readFile,realpath} from 'node:fs/promises';
 import {isBuiltin,createRequire} from 'node:module';
 import {fileURLToPath,pathToFileURL} from 'node:url';
 import {parse} from 'acorn';
+import {inspectProcessUsage} from './process-usage.js';
 
 const nonempty=value=>typeof value==='string'&&value.trim().length>0;
 function inspectSchema(schema,location,warning,seen=new WeakSet()){
@@ -84,6 +85,8 @@ function sourceReferences(ast,commonjs,warning,location){
       base?.type==='MemberExpression'&&!base.computed&&base.property.name==='url'&&base.object.type==='MetaProperty'&&base.object.meta.name==='import')loaders.add(node.id.name);
   });
   // 保守跳过文件内重名绑定；不把局部对象当作 Node 全局对象。
+  const isRequire=node=>node.callee?.type==='Identifier'&&((commonjs&&!bindings.has('require')&&node.callee.name==='require')||loaders.has(node.callee.name));
+  inspectProcessUsage(ast,{bindings,isRequire,walk},warning,location);
   walk(ast,node=>{
     const at=`${location}:${node.loc.start.line}:${node.loc.start.column+1}`;
     if(['ImportDeclaration','ExportNamedDeclaration','ExportAllDeclaration','ImportExpression'].includes(node.type)&&typeof node.source?.value==='string'){
@@ -91,7 +94,7 @@ function sourceReferences(ast,commonjs,warning,location){
     }
     if(node.type!=='CallExpression')return;
     const callee=node.callee;
-    if(callee.type==='Identifier'&&((commonjs&&!bindings.has('require')&&callee.name==='require')||loaders.has(callee.name))&&typeof node.arguments[0]?.value==='string'){
+    if(isRequire(node)&&typeof node.arguments[0]?.value==='string'){
       references.push({specifier:node.arguments[0].value,at,commonjs:true});
     }
     if(!bindings.has('console')&&callee.type==='MemberExpression'&&callee.object.type==='Identifier'&&callee.object.name==='console'&&

package/manual/packages/fst-devtools/src/plugin-tools.js

@@ -38,6 +38,7 @@ export async function lintPluginDirectory(directory){
   const quality=await import('./plugin-quality.js');
   return {...await inspectPluginDirectory(directory,quality),notes:[...validationNotes(),
     {code:'STATIC_SCAN_LIMITS',message:'源码检查仅覆盖入口可达的本地 JavaScript 和字面量依赖；动态加载、别名调用和局部重名可能无法识别。质量警告不会修改文件，也不代表运行结果或安全保证。'},
+    {code:'UNMANAGED_PROCESS_LIMITS',message:'进程检查只定位可识别的直接调用；动态计算、复杂别名、依赖包及 Python/Shell 内部执行不保证覆盖。迁移警告不阻止旧插件加载，不构成安全隔离或自动提权。'},
   ]};
 }
 

package/manual/packages/fst-devtools/src/process-usage.js

@@ -0,0 +1,62 @@
+const processMembers=new Set(['spawn','spawnSync','exec','execSync','execFile','execFileSync','fork']);
+const sources=new Set(['node:child_process','child_process','execa','cross-spawn','shelljs','@mytools/fst-platform']);
+const property=node=>node.computed?node.property?.value:node.property?.name;
+
+function launches({source,members}){
+  const names=members[0]==='default'?members.slice(1):members;
+  if(['node:child_process','child_process'].includes(source))return names.length===1&&processMembers.has(names[0]);
+  if(source==='execa')return names.length===0||names.length===1&&['execa','execaSync','execaCommand','execaCommandSync','execaNode','$'].includes(names[0]);
+  if(source==='cross-spawn')return names.length===0||names.length===1&&['spawn','sync'].includes(names[0]);
+  if(source==='shelljs')return names.length===1&&names[0]==='exec';
+  return source==='@mytools/fst-platform'&&names.length===1&&names[0]==='runProcess';
+}
+
+// 仅诊断能追溯到已知模块的调用，不以模块导入本身判定违规，也不执行源码。
+export function inspectProcessUsage(ast,{bindings,isRequire,walk},warning,location){
+  const imported=new Map(),variables=new Map(),mutated=new Set();
+  const rootName=node=>node?.type==='Identifier'?node.name:node?.type==='MemberExpression'?rootName(node.object):undefined;
+  walk(ast,node=>{
+    if(node.type==='ImportDeclaration'&&sources.has(node.source.value))for(const spec of node.specifiers){
+      imported.set(spec.local.name,{source:node.source.value,members:spec.type==='ImportNamespaceSpecifier'?[]:[spec.type==='ImportDefaultSpecifier'?'default':spec.imported.name??spec.imported.value]});
+    }
+    if(node.type==='VariableDeclarator'){
+      if(node.id.type==='Identifier')variables.set(node.id.name,{value:node.init,members:[]});
+      else if(node.id.type==='ObjectPattern')for(const spec of node.id.properties){
+        if(spec.type==='Property'&&spec.value.type==='Identifier'&&(!spec.computed||typeof spec.key.value==='string'))variables.set(spec.value.name,{value:node.init,members:[spec.computed?spec.key.value:spec.key.name??spec.key.value]});
+      }
+    }
+    if(['AssignmentExpression','UpdateExpression','UnaryExpression'].includes(node.type)){
+      const target=node.left??node.argument;
+      if(target?.type==='MemberExpression'&&(node.type!=='UnaryExpression'||node.operator==='delete'))mutated.add(rootName(target));
+      if(node.type==='UpdateExpression'&&target?.type==='Identifier')mutated.add(target.name);
+    }
+  });
+  function resolve(node,seen=new Set()){
+    if(!node)return;
+    if(node.type==='AwaitExpression'||node.type==='ChainExpression')return resolve(node.argument??node.expression,seen);
+    if(node.type==='Identifier'){
+      if(bindings.get(node.name)!==1||mutated.has(node.name)||seen.has(node.name))return;
+      if(imported.has(node.name))return imported.get(node.name);
+      const variable=variables.get(node.name);if(!variable)return;
+      const result=resolve(variable.value,new Set([...seen,node.name]));
+      return result&&{source:result.source,members:[...result.members,...variable.members]};
+    }
+    if(node.type==='MemberExpression'){
+      const name=property(node);if(typeof name!=='string')return;
+      const result=resolve(node.object,seen);return result&&{source:result.source,members:[...result.members,name]};
+    }
+    // Execa 的对象参数只绑定选项，返回的函数被调用时才启动程序。
+    if(node.type==='CallExpression'&&node.arguments[0]?.type==='ObjectExpression'){
+      const target=resolve(node.callee,seen);
+      if(target?.source==='execa'&&launches(target))return target;
+    }
+    const source=node.type==='ImportExpression'?node.source?.value:node.type==='CallExpression'&&isRequire(node)?node.arguments[0]?.value:undefined;
+    if(sources.has(source))return {source,members:[]};
+  }
+  walk(ast,node=>{
+    if(!['CallExpression','TaggedTemplateExpression'].includes(node.type))return;
+    const target=resolve(node.callee??node.tag);if(!target||!launches(target))return;
+    if(target.source==='execa'&&node.type==='CallExpression'&&node.arguments[0]?.type==='ObjectExpression')return;
+    warning('UNMANAGED_PROCESS',`直接调用 ${target.source}${target.members.length?'.'+target.members.join('.'):''} 可能绕过统一执行记录、取消与代理规则；执行外部程序请改用 ctx.runProcess(file, args, options)。此提示不代表该调用已执行`,`${location}:${node.loc.start.line}:${node.loc.start.column+1}`);
+  });
+}

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

@@ -12,6 +12,7 @@
 | 导入路径 | 实现位置 |
 | --- | --- |
 | `@mytools/fst-platform` | `./src/process.js` |
+| `@mytools/fst-platform/managed-process` | `./src/managed-process.js` |
 | `@mytools/fst-platform/environments` | `./src/environments.js` |
 | `@mytools/fst-platform/bundle` | `./src/bundle.js` |
 | `@mytools/fst-platform/json` | `./src/json.js` |
@@ -37,6 +38,10 @@ node --test tests/modules.test.js tests/process.test.js tests/environments.test.
 
 ## 子进程环境
 
+`createProcessRunner({execute=runProcess,signal,log,audience})` 是内核调用方共用的受管包装，返回签名兼容 `runProcess(file,args,options)` 的函数。每次调用独立生成 `processId`，先写指令日志再执行自定义 onStart，先写输出日志再执行自定义 onOutput；合并调用级与上下文取消信号，不改变底层并发。插件经宿主 `ctx.runProcess` 使用，不能直接导入本入口代替上下文。权限检查由 plugin 负责，本包装不授予权限、不进行命令黑名单拦截。
+
+受管调用可指定 `logPolicy:false` 隐藏自动记录的参数与脚本，或 `{redactArgs:[零起算下标],omitArgs:true,omitScript:true}` 按需选择；实际参数和调用方 onStart 保留原值。有参数被隐藏时脚本也隐藏。无效策略执行前拒绝。该策略不自动识别密钥、不处理插件主动输出及已有日志；平台自动生成的进程启动失败信息也不再拼接 Execa 的完整命令行。
+
 `/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` 字段保留用户原始指令，直接执行的简单命令同时记录实际程序路径和参数。

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

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

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

@@ -0,0 +1,36 @@
+import {randomUUID} from 'node:crypto';
+import {runProcess} from './process.js';
+import {FlowError} from '@mytools/sdk';
+
+function invocationFilter(policy,args){
+  if(policy===undefined)return value=>value;
+  const invalid=()=>{throw new FlowError('logPolicy 必须为 false 或含 redactArgs、omitArgs、omitScript 的有效对象；参数下标从 0 开始且不能越界',{code:'VALIDATION'});};
+  if(policy!==false&&(!policy||typeof policy!=='object'||Array.isArray(policy)))invalid();
+  if(policy!==false){
+    if(Object.keys(policy).some(key=>!['redactArgs','omitArgs','omitScript'].includes(key)))invalid();
+    for(const key of ['omitArgs','omitScript'])if(policy[key]!==undefined&&typeof policy[key]!=='boolean')invalid();
+    if(policy.redactArgs!==undefined&&(!Array.isArray(policy.redactArgs)||policy.redactArgs.some(index=>!Number.isSafeInteger(index)||index<0||index>=(args?.length??0))))invalid();
+  }
+  const omitted=policy===false||policy.omitArgs===true,indices=new Set(policy.redactArgs??[]);
+  const omitScript=omitted||indices.size>0||policy.omitScript===true;
+  return value=>({...value,
+    ...(Array.isArray(value.args)?{args:omitted?(value.args.length?['[参数已隐藏]']:[]):value.args.map((arg,index)=>indices.has(index)?'[已隐藏]':arg)}:{}),
+    ...(value.script!==undefined&&omitScript?{script:'[原始脚本已隐藏]'}:{}),
+  });
+}
+
+// 每次调用独立绑定日志和取消信号；共享入口不串行化进程，也不授予额外权限。
+export function createProcessRunner({execute=runProcess,signal,log,audience}={}){
+  return (file,args,options={})=>{
+    const {logPolicy,...executionOptions}=options,displayInvocation=invocationFilter(logPolicy,args);
+    const processId=randomUUID();
+    const combined=signal&&options.signal?AbortSignal.any([signal,options.signal]):signal??options.signal;
+    return execute(file,args,{...executionOptions,signal:combined,onStart:async invocation=>{
+      await log?.('执行程序',displayInvocation(invocation),{kind:'process',processId});
+      await options.onStart?.(invocation);
+    },onOutput:async({stream,message})=>{
+      await log?.(message,undefined,{stream,processId,...(audience?{audience}:{})});
+      await options.onOutput?.({stream,message});
+    }});
+  };
+}

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

@@ -5,6 +5,8 @@ import { FlowError } from '@mytools/sdk';
 import path from 'node:path';
 
 const stripFinalNewline=text=>text.endsWith('\r\n')?text.slice(0,-2):text.endsWith('\n')?text.slice(0,-1):text;
+// 执行库的校验错误和启动错误都可能包含完整 argv，仅保留安全的错误代码。
+const spawnFailure=(file,code='SPAWN_FAILED')=>new FlowError(`无法启动程序 ${file}：${code}；请检查参数格式、执行目录、文件权限及程序依赖`,{code});
 
 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');
@@ -38,7 +40,9 @@ export async function runProcess(file,args=[],{cwd,env,extendEnv=true,signal,tim
   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 child;
+  try{child=execa(executable,args,{cwd,env,extendEnv,reject:false,windowsHide:true,maxBuffer,buffer:false,timeout:0,shell:false,encoding:'buffer',stripFinalNewline:false});}
+  catch(error){throw spawnFailure(file,error.code);}
   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:''},buffers={stdout:[],stderr:[]};let outputTruncated=false;
@@ -110,7 +114,8 @@ export async function runProcess(file,args=[],{cwd,env,extendEnv=true,signal,tim
   if(reason==='output-limit')throw new FlowError('程序输出超过上限',{code:'OUTPUT_LIMIT'});
   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'});
+  // Execa 的短错误包含完整 argv，不能重新写回已由受管入口隐藏的敏感参数。
+  if(result.exitCode===undefined&&result.failed)throw spawnFailure(file,result.code);
   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(buffers.stdout),stderr:decode(buffers.stderr)};

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

@@ -20,6 +20,10 @@
 
 ## 维护与验证
 
+动作及命令的上下文 runProcess 使用 platform/managed-process 的共用包装，统一指令、输出关联与取消信号；代理仍由宿主按动作构造。权限预检发生在动作主体之前，不自动提权。共享包装不串行化调用；宿主同进程信任模型不变，开发约束不能替代安全隔离。
+
+动作、动作别名命令及独立交互命令共用 SDK 输入解析。顶层输入字段的 `x-fst.fromConfig` 声明先取实际插件配置，再回退到输入 schema 默认值；显式输入优先。`host.previewInput(target, input)` 返回有效值及来源，管理界面无需读取整份宿主配置。声明由 `validateDeclarations` 检查，插件加载和开发工具使用同一规则。
+
 本模块负责上述职责的实现、文档与回归；跨模块接口调整需要同时检查生产者与消费者。具体维护人员尚未指定。
 
 在仓库根目录执行：

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

@@ -3,6 +3,7 @@ import {conditionOperators} from '@mytools/sdk/conditions';
 import {resolveSchemaPath} from '@mytools/sdk/schema-path';
 import {inside} from '@mytools/fst-platform/environments';
 import path from 'node:path';
+import {validateInputRules} from '@mytools/sdk/inputs';
 
 export const builtinCommands=[
   ['workflows','选择已有工作流'],['new','新建工作流'],['add','添加插件能力或子工作流'],
@@ -37,6 +38,8 @@ function validatePrivilegeDeclarations(plugin){
 }
 
 export function validateDeclarations(plugin){
+  for(const [name,owner] of Object.entries(plugin.actions??{}))validateInputRules(owner?.input,plugin.config,`plugin.actions.${name}.input`);
+  for(const [name,owner] of Object.entries(plugin.commands??{}))if(!owner?.action)validateInputRules(owner?.input,plugin.config,`plugin.commands.${name}.input`);
   for(const [name,action] of Object.entries(plugin.actions??{})){
     if(!action||typeof action!=='object'||Array.isArray(action))throw new FlowError(`动作 ${name} 的声明必须为对象`,{code:'VALIDATION'});
     if(action.conditions!==undefined&&(!action.conditions||typeof action.conditions!=='object'||Array.isArray(action.conditions)))throw new FlowError(`动作 ${name} 的 conditions 必须为对象`,{code:'VALIDATION'});

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

@@ -2,15 +2,17 @@ import { Context } from 'cordis';
 import semver from 'semver';
 import { SDK_VERSION, FlowError } from '@mytools/sdk';
 import { validate, emptyObject } from '@mytools/sdk/schema';
+import {resolveInput} from '@mytools/sdk/inputs';
 import {validateDeclarations,validateCommands} from './contracts.js';
 import {prepareEnvironments,platformWarnings} from '@mytools/fst-platform/environments';
 import path from 'node:path';
 import {mkdir} from 'node:fs/promises';
 import {createHash} from 'node:crypto';
-import {createRuntime,validateRuntimes} from './runtime.js';
+import {createRuntime,validateRuntimes,validateRuntimeDeclaration} 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';
+import {createProcessRunner} from '@mytools/fst-platform/managed-process';
 
 export async function createHost({ plugins = [], config = {}, services = {}, project,network,environmentOverrides={},runtimeEnabled=true,allowUnknownPrivileges=false } = {}) {
   const currentNetwork=()=>typeof network==='function'?network():network;
@@ -25,16 +27,7 @@ export async function createHost({ plugins = [], config = {}, services = {}, pro
     const bound={...capabilities,...context},execute=bound.runProcess;
     // 面向用户的输出与诊断日志共用持久化通道，只区分默认可见性。
     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,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});
-      }});
-    };
+    if(typeof execute==='function')bound.runProcess=createProcessRunner({execute,signal:context.signal,log:bound.log});
     return bound;
   }
   async function pluginContext(plugin,action,context){
@@ -161,6 +154,12 @@ export async function createHost({ plugins = [], config = {}, services = {}, pro
       }
     },
     commands(){assertReadable();return [...commands.values()].map(({run,preflight,config,...metadata})=>structuredClone(metadata));},
+    previewInput(target,input={}){
+      assertReadable();
+      const owner=target.startsWith('/')?commands.get(target.slice(1)):actions.get(target);
+      if(!owner)throw new FlowError(`参数目标不存在：${target}`,{code:'VALIDATION'});
+      return resolveInput(owner.input??emptyObject,input,owner.config,{check:false,label:`${target} 输入`});
+    },
     async invokeCommand(name,input,context={}){
       assertHealthy();
       const command=commands.get(name);if(!command)throw new FlowError(`命令不存在：/${name}`);
@@ -170,7 +169,7 @@ export async function createHost({ plugins = [], config = {}, services = {}, pro
       try{
       const getService=runtime.bindServices(plugin.id);
       context.signal?.throwIfAborted();
-      const checked=validate(command.input??emptyObject,input,`/${name} 输入`);
+      const checked=resolveInput(command.input??emptyObject,input,command.config,{label:`/${name} 输入`}).value;
       const bound=await pluginContext(plugin,undefined,context);
       let result;
       try{
@@ -189,7 +188,7 @@ export async function createHost({ plugins = [], config = {}, services = {}, pro
       try{
       const getService=runtime.bindServices(action.plugin);
       context.signal?.throwIfAborted();
-      const checked=validate(action.input ?? emptyObject,input,`${id} 输入`);
+      const checked=resolveInput(action.input??emptyObject,input,action.config,{label:`${id} 输入`}).value;
       const plugin=definitions.get(action.plugin),bound=await pluginContext(plugin,action,context);
       let result;
       try{
@@ -219,25 +218,41 @@ export async function createHost({ plugins = [], config = {}, services = {}, pro
   };
 }
 
-// 可用和待配置的插件共用声明检查；配置不足不会掩盖 SDK、依赖或代码错误。
-export function validatePluginDefinitions(entries){
+// 单插件契约检查不依赖其他插件，供启动恢复路径精确归属故障。
+export function validatePluginDefinition(entry){
+  const plugin=entry?.plugin??entry;
+  if(!plugin||typeof plugin!=='object'||Array.isArray(plugin)||typeof plugin.id!=='string'||!plugin.id)throw new FlowError('插件默认导出必须是包含 id 的对象',{code:'VALIDATION'});
+  validateDeclarations(plugin);validateCommands(plugin,new Set());
+  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(typeof extension!=='function')throw new FlowError(`服务 ${name} 缺少执行函数`,{code:'VALIDATION'});
+  validateRuntimeDeclaration(plugin,new Context());
+  return plugin;
+}
+
+// 恢复启动只豁免已确认故障的节点；其他可确定的声明和依赖错误仍明确拒绝。
+export function validatePluginDefinitions(entries,{unavailable=new Set(),blocked=new Set()}={}){
   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(unavailable.has(plugin.id)){definitions.set(plugin.id,{...plugin,root:entry.root});continue;}
+    validatePluginDefinition(entry);validateCommands(plugin,commandNames);
+    for(const name of Object.keys(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'});
+  for(const plugin of definitions.values()){
+    // 此节点已隔离且不会执行；它的损坏依赖不能阻断其他健康插件恢复。
+    if(unavailable.has(plugin.id))continue;
+    for(const [id,range] of Object.entries(plugin.dependencies??{})){
+      // 无法读取目标版本时保留恢复入口；已知版本仍须满足健康消费者的声明。
+      if(unavailable.has(id)&&!semver.valid(definitions.get(id)?.version))continue;
+      if(!definitions.has(id)||!semver.satisfies(definitions.get(id).version,range))throw new FlowError(`插件 ${plugin.id} 缺少兼容依赖 ${id}@${range}`,{code:'VALIDATION'});
+    }
   }
-  validateRuntimes(definitions,new Context());
+  validateRuntimes(new Map([...definitions].filter(([id])=>!unavailable.has(id))),new Context(),{blocked});
   return definitions;
 }

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

@@ -1,16 +1,20 @@
 import {FlowError} from '@mytools/sdk';
 
+export function validateRuntimeDeclaration(p,ctx){
+  const r=p.runtime;if(r===undefined)return;
+  if(!r||typeof r.apply!=='function')throw new FlowError(`${p.id} runtime 必须提供 apply`);
+  for(const key of ['provides','inject']){
+    const names=r[key]??[];
+    if(!Array.isArray(names)||names.some(n=>typeof n!=='string'||!/^\w[\w.-]*$/.test(n)||n in ctx)||new Set(names).size!==names.length)throw new FlowError(`${p.id} runtime.${key} 服务名称无效或重复`);
+  }
+}
+
 // 静态声明用于诊断与打包，运行时激活仍由 Cordis inject 驱动。
-export function validateRuntimes(definitions,ctx){
+export function validateRuntimes(definitions,ctx,{blocked=new Set()}={}){
   const providers=new Map(),ordered=[],visiting=new Set(),visited=new Set();
   for(const p of definitions.values()){
-    const r=p.runtime;if(r===undefined)continue;
-    if(!r||typeof r.apply!=='function')throw new FlowError(`${p.id} runtime 必须提供 apply`);
-    for(const key of ['provides','inject']){
-      const names=r[key]??[];
-      if(!Array.isArray(names)||names.some(n=>typeof n!=='string'||!/^\w[\w.-]*$/.test(n)||n in ctx)||new Set(names).size!==names.length)throw new FlowError(`${p.id} runtime.${key} 服务名称无效或重复`);
-    }
-    for(const name of r.provides??[]){
+    validateRuntimeDeclaration(p,ctx);
+    for(const name of p.runtime?.provides??[]){
       if(providers.has(name))throw new FlowError(`服务重复：${name}（${providers.get(name)}、${p.id}）`);
       providers.set(name,p.id);
     }
@@ -21,6 +25,8 @@ export function validateRuntimes(definitions,ctx){
     visiting.add(id);const p=definitions.get(id);
     for(const name of p.runtime?.inject??[]){
       const owner=providers.get(name);
+      // 故障依赖的声明不可读取时，只跳过无法确认归属的服务；已知冲突与环仍检查。
+      if(!owner&&blocked.has(id))continue;
       if(!owner)throw new FlowError(`${id} 缺少服务提供者：${name}`);
       if(owner!==id&&!Object.hasOwn(p.dependencies??{},owner))throw new FlowError(`${id} 的 dependencies 必须声明服务 ${name} 的提供者 ${owner}`);
       visit(owner);

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'}:{}),...(['process','source'].includes(meta.kind)?{kind:meta.kind}:{}),...base,message,data}),
+        log:(message,data,meta={})=>emit({type:'log',stream:meta.stream,...(typeof meta.processId==='string'?{processId:meta.processId}:{}),...(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

@@ -28,6 +28,10 @@
 
 `/shortcuts` 提供 `validateShortcuts` 校验、`bindShortcutCommands` 在用户配置时补齐命令提供者身份，以及 `describeShortcuts` 生成可用或失效状态。绑定函数可传入 previous 保留旧项：未绑定命令修改参数或重命名仍保持失效，需重新选择目标。命令项使用 command 与 plugin 同时匹配，动作项使用稳定 action ID；不执行其他插件的同名能力。实际保存、备份与宿主装配由 core 协调。
 
+`WorkflowStore.list()` 保留正常工作流，同时返回 `status: 'invalid'` 的损坏文件诊断条目，`diagnostic` 含文件路径、错误消息以及可获得的 YAML 行列。诊断条目不能保存或复制。`list({strict:true})` 遇错误即拒绝，删除和卸载依赖扫描必须使用此模式；`get/check/run` 保持严格读取。`resolve()` 对根及全部子流程的输入 Schema 提前编译，打包与执行共用闭包预检，不会先执行前置业务步骤才发现子流程声明错误。
+
+`installGeneration` 的可选 `recoverInstalled` 回调仅用于纯卸载时重新读取剩余旧插件，交由 core 提供恢复条目；默认调用、新安装和链接保持严格加载。
+
 本模块负责上述职责的实现、文档与回归；跨模块接口调整需要同时检查生产者与消费者。具体维护人员尚未指定。
 
 在仓库根目录执行：

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

@@ -33,7 +33,7 @@ function referencedActions(steps,id,result=new Set()){
 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()){
+    for(const workflow of await new WorkflowStore(path.join(projectDir,'workflows')).list({strict:true})){
       const actions=referencedActions(workflow.steps,id);
       if(actions.length)references.push({projectDir,id:workflow.id,title:workflow.title??workflow.id,actions});
     }

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

@@ -5,7 +5,7 @@ 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,sourceDir=projectDir}) {
+export async function installGeneration(projectDir,{add,remove,link,state,sourceDir=projectDir,recoverInstalled}) {
   const root=path.join(projectDir,'.flow','installations',randomUUID());
   await mkdir(root,{recursive:true});
   const dependencies={...(state?.dependencies??{})};
@@ -32,7 +32,9 @@ export async function installGeneration(projectDir,{add,remove,link,state,source
   }
   const pkg=await readJson(path.join(root,'package.json'));
   const loaded=[];
-  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));
+  // 卸载故障插件时允许保留其他旧故障；安装/链接操作仍严格校验新批次。
+  const load=remove&&!add&&!link&&recoverInstalled?recoverInstalled:(_id,spec,base)=>loadPlugin(spec,base);
+  for(const name of Object.keys(pkg.dependencies??{})){delete links[name];disabledLegacy.delete(name);loaded.push(await load(name,name,root));}
+  for(const [name,source] of Object.entries(links))loaded.push(await load(name,source,projectDir,{linked:true}));
   return {state:{root,dependencies:pkg.dependencies??{},links,...(state?.global?{global:true,disabledLegacy:[...disabledLegacy]}:{}),...(state?.root?{previousRoot:state.root}:{})},loaded};
 }

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

@@ -12,14 +12,21 @@ export class WorkflowStore {
   file(id) { assertId(id); return path.join(this.root,`${id}.yaml`); }
   async get(id) {
     const file=this.file(id);
-    const physical=await realpath(file);
-    const root=await realpath(this.root);
-    if (!physical.startsWith(root+path.sep)) throw new FlowError('工作流越界，必须位于工作流目录内',{code:'VALIDATION'});
-    const definition=YAML.parse(await readFile(file,'utf8'));
-    if (definition?.id !== id) throw new FlowError(`工作流 ID 与文件名不一致：${id}`,{code:'VALIDATION'});
-    return this.validateShape(definition);
+    try{
+      const physical=await realpath(file);
+      const root=await realpath(this.root);
+      if (!physical.startsWith(root+path.sep)) throw new FlowError('工作流越界，必须位于工作流目录内',{code:'VALIDATION'});
+      const definition=YAML.parse(await readFile(file,'utf8'));
+      if (definition?.id !== id) throw new FlowError(`工作流 ID 与文件名不一致：${id}`,{code:'VALIDATION'});
+      return this.validateShape(definition);
+    }catch(error){
+      const position=error.linePos?.[0];
+      const details={file,...(position?{line:position.line,column:position.col}:{}),reason:error.code};
+      throw new FlowError(`工作流读取失败：${file}${position?`:${position.line}:${position.col}`:''}\n${error.message}`,{code:'VALIDATION',details,cause:error});
+    }
   }
   validateShape(w) {
+    if(w?.status==='invalid')throw new FlowError(w.diagnostic?.message??'损坏工作流的诊断条目不能保存或复制，请先修复原文件',{code:'VALIDATION'});
     assertId(w?.id);
     if (w.schemaVersion!==1 || !Array.isArray(w.steps)) throw new FlowError('工作流格式错误：需要 schemaVersion: 1 与 steps 列表',{code:'VALIDATION'});
     validateStepList(w.steps,assertId);
@@ -66,16 +73,26 @@ export class WorkflowStore {
       throw error;
     }
   }
-  async list() {
+  async list({strict=false}={}) {
     await mkdir(this.root,{recursive:true});
     const files=await readdir(this.root);
-    return Promise.all(files.filter(f=>f.endsWith('.yaml')).sort().map(f=>this.get(f.slice(0,-5))));
+    return Promise.all(files.filter(f=>f.endsWith('.yaml')).sort().map(async f=>{
+      const id=f.slice(0,-5);
+      try{return await this.get(id);}
+      catch(error){
+        if(strict)throw error;
+        const file=path.join(this.root,f),diagnostic={...error.details,file,message:error.message};
+        // 保留数组协议和已有 Web 展示字段；此条目仅供诊断，不是可保存的定义。
+        return {id,title:`不可用：${f}`,description:`${file}\n${error.message}`,status:'invalid',diagnostic,inputs:false,steps:[],outputs:{}};
+      }
+    }));
   }
   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));
+    // 文件无法读取时不能证明不存在引用，必须阻止删除。
+    const dependents=(await this.list({strict:true})).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');
@@ -95,6 +112,7 @@ export class WorkflowStore {
       if(workflows.has(id)) return;
       visiting.add(id);
       const w=await this.get(id);
+      assertSchema(w.inputs??emptyObject,`${this.file(id)} inputs schema`);
       const checker=previous=>ref=>{
         const p=referenceParts(ref);
         if(p[0]==='steps' && !previous.has(p[1])) throw new FlowError(`${id} 引用必须指向前序步骤：${ref}`,{code:'VALIDATION'});

package/manual/packages/sdk/README.md

@@ -13,6 +13,8 @@
 | --- | --- |
 | `@mytools/sdk` | `./index.js` |
 | `@mytools/sdk/schema` | `./validation.js` |
+| `@mytools/sdk/inputs` | `./inputs.js` |
+| `@mytools/sdk/reports` | `./reports.js` |
 | `@mytools/sdk/schema-path` | `./schema-path.js` |
 | `@mytools/sdk/diagnostics` | `./diagnostics.js` |
 | `@mytools/sdk/conditions` | `./conditions.js` |
@@ -29,3 +31,11 @@
 ```sh
 node --test tests/modules.test.js tests/plugin-contract.test.js tests/schema-diagnostics.test.js
 ```
+
+## 输入解析
+
+`@mytools/sdk/inputs` 提供 `validateInputRules`、`hasInputRules`、`resolveInput`。输入字段 `x-fst` 支持 `fromConfig`、`unsetLabel` 和 `unit`，由插件宿主与 TUI 共用。`resolveInput` 返回有效输入和字段来源，始终复制输入；配置继承优先于输入固定默认值，显式输入优先于继承。声明范围与示例见插件开发文档。
+
+## 业务报告
+
+`@mytools/sdk/reports` 提供 `reportSchema`、`createReport(content)`、`inspectReport(value)`。v1 支持标题、摘要、分级提醒、建议、业务分组及推荐列；SDK 不负责界面渲染。helper 校验并复制 JSON 内容，错误码为 `REPORT_INVALID`。检查接口返回 `none` / `valid` / `invalid` / `unsupported` 状态，合法时 `report` 指向原值（只读使用），非法时包含 `message` 和可选 `details`。普通输出无需接入；已有插件可将报告放入 `output.report`，保留原数据字段。完整示例见 `docs/plugin-development.md`。

package/manual/packages/sdk/inputs.js

@@ -0,0 +1,53 @@
+import {FlowError} from '@mytools/sdk';
+import {assertSchema,validate,emptyObject} from './validation.js';
+
+const object=value=>value!==null&&typeof value==='object'&&!Array.isArray(value);
+const complex=['$ref','oneOf','anyOf','allOf','if','then','else','dependencies','patternProperties'];
+export const hasInputRules=schema=>Object.values(schema?.properties??{}).some(field=>field?.['x-fst']!==undefined);
+
+// 仅解释已声明的顶层输入规则，不分析插件执行代码或按同名字段猜测继承关系。
+export function validateInputRules(schema,configSchema,label='input'){
+  const fail=(at,message)=>{throw new FlowError(`${at} x-fst：${message}`,{code:'VALIDATION',details:{path:at}});};
+  const visit=(node,at,allowed=false)=>{
+    if(!object(node))return;
+    const rule=node['x-fst'];
+    if(rule!==undefined){
+      if(!allowed||schema.type!=='object'||complex.some(key=>schema[key]!==undefined||node[key]!==undefined))fail(at,'只支持简单输入对象的顶层字段');
+      if(!object(rule)||Object.keys(rule).some(key=>!['fromConfig','unsetLabel','unit'].includes(key)))fail(at,'仅支持 fromConfig、unsetLabel、unit');
+      for(const [key,value] of Object.entries(rule))if(typeof value!=='string'||!value.trim())fail(at,`${key} 必须为非空字符串`);
+      if(rule.fromConfig!==undefined){
+        let current=configSchema;
+        for(const part of rule.fromConfig.split('.')){
+          if(!part||['__proto__','constructor','prototype'].includes(part)||!Object.hasOwn(current?.properties??{},part))fail(at,`配置路径未声明：${rule.fromConfig}`);
+          current=current.properties[part];
+        }
+      }
+    }
+    for(const key of ['properties','patternProperties','$defs','definitions','dependencies','dependentSchemas'])for(const [name,child] of Object.entries(node[key]??{}))visit(child,`${at}.${key}.${name}`,node===schema&&key==='properties');
+    for(const key of ['items','additionalItems','additionalProperties','contains','not','if','then','else','propertyNames']){
+      if(Array.isArray(node[key]))node[key].forEach((child,index)=>visit(child,`${at}.${key}.${index}`));
+      else visit(node[key],`${at}.${key}`);
+    }
+    for(const key of ['allOf','anyOf','oneOf','prefixItems'])node[key]?.forEach(child=>visit(child,`${at}.${key}`));
+  };
+  visit(schema,label);
+}
+
+export function resolveInput(schema=emptyObject,input={},config={}, {check=true,label='参数'}={}){
+  const value=structuredClone(input),fields={};
+  if(object(value))for(const [key,field] of Object.entries(schema?.properties??{})){
+    const rule=field?.['x-fst']??{};
+    let source=Object.hasOwn(value,key)&&value[key]!==undefined?'input':'omitted';
+    if(source==='omitted'&&rule.fromConfig){
+      let inherited=config;
+      for(const part of rule.fromConfig.split('.'))inherited=inherited!=null&&Object.hasOwn(inherited,part)?inherited[part]:undefined;
+      if(inherited!==undefined){Object.defineProperty(value,key,{value:structuredClone(inherited),enumerable:true,writable:true,configurable:true});source='config';}
+    }
+    Object.defineProperty(fields,key,{value:{source,...(source==='config'?{path:rule.fromConfig}:{}),...(rule.unit?{unit:rule.unit}:{}),...(rule.unsetLabel?{unsetLabel:rule.unsetLabel}:{})},enumerable:true});
+  }
+  // 预览允许缺少必填项；校验器仍与执行共用，默认值只作用于副本。
+  const effective=check?validate(schema,value,label):value;
+  if(!check&&schema!=null)assertSchema(schema,label)(effective);
+  for(const [key,field] of Object.entries(fields))if(field.source==='omitted'&&effective?.[key]!==undefined)field.source='default';
+  return {value:effective,fields};
+}

package/manual/packages/sdk/package.json

@@ -6,6 +6,8 @@
   "exports": {
     ".": "./index.js",
     "./schema": "./validation.js",
+    "./inputs": "./inputs.js",
+    "./reports": "./reports.js",
     "./schema-path": "./schema-path.js",
     "./diagnostics": "./diagnostics.js",
     "./conditions": "./conditions.js",