@yanglaofish/fishtools 0.5.3 → 0.6.0

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

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

package/node_modules/@mytools/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/node_modules/@mytools/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/node_modules/@mytools/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/node_modules/@mytools/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/node_modules/@mytools/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/node_modules/@mytools/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/node_modules/@mytools/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/node_modules/@mytools/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/node_modules/@mytools/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/node_modules/@mytools/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/node_modules/@mytools/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",

package/node_modules/@mytools/sdk/reports.js

@@ -0,0 +1,53 @@
+import {FlowError} from './index.js';
+import {assertSchema,validate} from './validation.js';
+
+const text={type:'string',pattern:'\\S'};
+const alerts={type:'array',items:{type:'object',properties:{level:{enum:['info','warning','error']},message:text},required:['level','message'],additionalProperties:false}};
+const conclusions={summary:text,alerts,recommendations:{type:'array',items:text}};
+export const reportSchema={
+  type:'object',
+  properties:{
+    kind:{const:'fst-report'},version:{const:1},title:text,...conclusions,
+    sections:{type:'array',items:{type:'object',properties:{title:text,...conclusions,data:true,columns:{type:'array',items:text,minItems:1,uniqueItems:true},titles:{type:'object',additionalProperties:text}},required:['title'],additionalProperties:false}},
+  },
+  required:['kind','version','title'],additionalProperties:false,
+};
+
+// 与落盘 JSON 边界一致，提前拒绝会被 JSON.stringify 静默改值的内容。
+function assertJson(value,ancestors=new Set()){
+  if(value===null||typeof value==='string'||typeof value==='boolean'||typeof value==='number'&&Number.isFinite(value))return;
+  if(typeof value!=='object'||!value||ancestors.has(value)||(!Array.isArray(value)&&![Object.prototype,null].includes(Object.getPrototypeOf(value))))throw new Error('报告必须为无循环引用的 JSON 数据');
+  ancestors.add(value);
+  try{
+    const list=Array.isArray(value),keys=Reflect.ownKeys(value);
+    if(list&&keys.length!==value.length+1)throw new Error('报告数组不能含空槽或附加属性');
+    for(const key of keys){
+      if(list&&key==='length')continue;
+      const field=Object.getOwnPropertyDescriptor(value,key);
+      if(typeof key!=='string'||!field.enumerable||!Object.hasOwn(field,'value')||list&&(!Number.isInteger(Number(key))||Number(key)<0||Number(key)>=value.length||String(Number(key))!==key))throw new Error('报告只能包含 JSON 可保留的普通数据属性');
+      assertJson(field.value,ancestors);
+    }
+  }finally{ancestors.delete(value);}
+}
+
+export function inspectReport(value){
+  try{
+    if(!value||typeof value!=='object'||Array.isArray(value))return {status:'none'};
+    const kind=Object.getOwnPropertyDescriptor(value,'kind');
+    if(kind&&!Object.hasOwn(kind,'value'))throw new Error('报告标记不能为访问器');
+    if(kind?.value!=='fst-report')return {status:'none'};
+    assertJson(value);
+    if(Number.isInteger(value.version)&&value.version!==1)return {status:'unsupported',message:`不支持报告版本 ${value.version}，已回退字段阅读。`};
+    const check=assertSchema(reportSchema,'报告',{useDefaults:false});
+    if(!check(value))return {status:'invalid',message:'报告格式无效，已回退字段阅读。',details:structuredClone(check.errors)};
+    return {status:'valid',report:value};
+  }catch(error){return {status:'invalid',message:`报告格式无效：${error.message}，已回退字段阅读。`};}
+}
+
+export function createReport(content){
+  try{assertJson(content);}catch(error){throw new FlowError(`报告格式无效：${error.message}`,{code:'REPORT_INVALID'});}
+  const value={kind:'fst-report',version:1,...content};
+  const result=inspectReport(value);
+  if(result.status!=='valid')throw new FlowError(result.message??'报告格式无效',{code:'REPORT_INVALID',details:result.details});
+  return validate(reportSchema,value,'报告',{useDefaults:false});
+}