@yanglaofish/fishtools 0.5.2 → 0.6.0

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

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

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

@@ -57,7 +57,7 @@ export async function runWorkflow({store,host,id,input={},signal,onEvent=()=>{},
       let output;
       if(step.action)output=await host.invoke(step.action,args,{
         ...context,signal:currentSignal,runId,stepId:step.id,callPath,workflow:w,
-        log:(message,data,meta={})=>emit({type:'log',stream:meta.stream,...(meta.audience==='user'?{audience:'user'}:{}),...base,message,data}),
+        log:(message,data,meta={})=>emit({type:'log',stream:meta.stream,...(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

@@ -6,6 +6,8 @@
 
 项目初始化、模板、工作流文件、插件安装批次、租约、开发引用及便携工作区。插件执行由 plugin 负责，系统调用由 platform 负责。
 
+`@mytools/fst-workspace/registry` 提供用户级插件库路径、工作区登记与跨工作区工作流引用查询。共享库复用安装批次、状态恢复备份及租约；普通工作区的配置与文件仍独立保存。
+
 内部依赖：`@mytools/sdk`、`@mytools/fst-platform`、`@mytools/fst-plugin`、`@mytools/fst-workflow`。
 ## 公开入口
 
@@ -26,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/package.json

@@ -11,6 +11,7 @@
     "./shortcuts": "./src/shortcuts.js",
     "./plugins": "./src/plugins.js",
     "./installations": "./src/plugin-installations.js",
+    "./registry": "./src/plugin-registry.js",
     "./bundles": "./src/bundle-workspace.js",
     "./package.json": "./package.json"
   },
@@ -22,7 +23,7 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=24.15.0"
+    "node": "^22.22.2 || >=24.0.0"
   },
   "dependencies": {
     "@mytools/sdk": "0.1.0",

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

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

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

@@ -5,22 +5,25 @@ import {FlowError} from '@mytools/sdk';
 import {readJson} from '@mytools/fst-platform/json';
 import {npm} from '@mytools/fst-platform/npm';
 import {loadPlugin} from '@mytools/fst-plugin/loader';
-export async function installGeneration(projectDir,{add,remove,link,state}) {
+export async function installGeneration(projectDir,{add,remove,link,state,sourceDir=projectDir,recoverInstalled}) {
   const root=path.join(projectDir,'.flow','installations',randomUUID());
   await mkdir(root,{recursive:true});
   const dependencies={...(state?.dependencies??{})};
   const links={...(state?.links??{})};
+  const disabledLegacy=new Set(state?.disabledLegacy??[]);
   if(remove){delete dependencies[remove];delete links[remove];}
+  if(remove&&state?.global)disabledLegacy.add(remove);
   if(link){
     const source=path.resolve(link),pkg=await readJson(path.join(source,'package.json'));
     const loaded=await loadPlugin(source,projectDir);
     if(!pkg.name||pkg.name!==loaded.plugin?.id||pkg.version!==loaded.plugin?.version)throw new FlowError('开发插件的包名/版本必须与插件 id/version 一致',{code:'VALIDATION'});
     links[pkg.name]=source;delete dependencies[pkg.name];
+    disabledLegacy.delete(pkg.name);
   }
   await writeFile(path.join(root,'package.json'),JSON.stringify({name:'flow-project-plugins',private:true,dependencies},null,2));
   let source=add;
   if(add) {
-    try {await access(path.resolve(projectDir,add));source=path.resolve(projectDir,add);} catch {}
+    try {await access(path.resolve(sourceDir,add));source=path.resolve(sourceDir,add);} catch {}
     if(source.startsWith('-')) throw new FlowError('插件来源不能以选项符号开头',{code:'VALIDATION'});
   }
   if(source||Object.keys(dependencies).length){
@@ -29,7 +32,9 @@ export async function installGeneration(projectDir,{add,remove,link,state}) {
   }
   const pkg=await readJson(path.join(root,'package.json'));
   const loaded=[];
-  for(const name of Object.keys(pkg.dependencies??{})){delete links[name];loaded.push(await loadPlugin(name,root));}
-  for(const source of Object.values(links))loaded.push(await loadPlugin(source,projectDir));
-  return {state:{root,dependencies:pkg.dependencies??{},links,...(state?.root?{previousRoot:state.root}:{})},loaded};
+  // 卸载故障插件时允许保留其他旧故障；安装/链接操作仍严格校验新批次。
+  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,21 +73,33 @@ 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){
+  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');
     await mkdir(directory,{recursive:true});
-    const backup=path.join(directory,`${id}-${randomUUID()}.yaml`);
+    const backupFile=path.join(directory,`${id}-${randomUUID()}.yaml`);
     // 同项目内原子移动，备份保留完整原文；复制回原文件名即可恢复。
-    await rename(this.file(id),backup);return backup;
+    await rename(this.file(id),backupFile);return backupFile;
   }
   childId(reference) {
     if(typeof reference!=='string' || !/^(\.\/)?[A-Za-z0-9][A-Za-z0-9_-]*\.yaml$/.test(reference)) throw new FlowError(`子流程必须位于工作流目录内：${reference}`,{code:'VALIDATION'});
@@ -93,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/pack/package.json

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

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

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

package/manual/packages/pack/runtime.js

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

package/manual/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",

package/manual/packages/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});
+}

package/manual/plugins/commands/package.json

@@ -9,7 +9,7 @@
   },
   "files": ["index.js", "README.md", "LICENSE"],
   "license": "MIT",
-  "engines": {"node": ">=24.15.0"},
+  "engines": {"node": "^22.22.2 || >=24.0.0"},
   "dependencies": {
     "@mytools/sdk": "0.1.0",
     "@mytools/fst-platform": "0.1.0"

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

@@ -9,7 +9,7 @@
   },
   "files": ["index.js", "README.md", "LICENSE"],
   "license": "MIT",
-  "engines": {"node": ">=24.15.0"},
+  "engines": {"node": "^22.22.2 || >=24.0.0"},
   "dependencies": {
     "@mytools/sdk": "0.1.0",
     "@mytools/fst-platform": "0.1.0"

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

@@ -25,6 +25,10 @@
 
 ## 维护与验证
 
+`createApplication({projectDir,pluginRegistryDir})` 可让多个工作区读取同一插件库；CLI 默认接入用户级全局库，程序未传此选项时保留工作区模式。分发包始终使用自身工作区安装状态。`listPlugins()` 返回 scope/source 和待配置原因；`pluginDefinition(id)` 返回作者声明。`app.resultsDir` 是业务文件根，`app.outputDir` 保留为日志根；插件 `ctx.outputDir` 与 `ctx.logDir` 分别对应本次业务目录和日志目录。
+
+已安装条目的加载或单插件契约错误隔离为 `runtime.status: 'unavailable'`，`listPlugins()` 返回 `loadError` 与来源，传递依赖者同样不可用。直接调用或检查引用它的流程抛出 `PLUGIN_UNAVAILABLE`；无关插件继续装配。纯卸载允许保留其他旧故障；新安装/链接严格检查。修复来源后须重新启动。此恢复不覆盖预置插件、明确的跨插件图错误和运行时初始化错误。
+
 `app.startShell(script,options)` 执行临时命令，`app.startAction(id,input,context)` 调用任意动作，两者均纳入运行记录与关闭等待。`startCommand(name,input,{expectedPlugin,...context})` 可固定命令提供者，启动时再次检查，防止参数填写期间被其他同名能力替换。`configureCommandPresets` 和 `configureShortcuts` 在备份、冲突检查与变更锁内保存项目设置；命令快捷项在用户明确设置时绑定提供者 ID，普通安装/卸载和未改变目标的整组保存不会重新绑定；已有未绑定项必须明确提供 plugin 或在界面重新选择目标。注册项变化通过定向宿主更新生效，导出快照保留所需定义与有效快捷项。
 
 本模块负责上述职责的实现、文档与回归；跨模块接口调整需要同时检查生产者与消费者。具体维护人员尚未指定。
@@ -35,6 +39,10 @@
 node --test tests/modules.test.js tests/application.test.js tests/lifecycle.test.js tests/module-interfaces.test.js
 ```
 
+## 输入预览
+
+应用接口 `app.previewInput(target, input)` 读取目标动作或命令的当前有效输入及来源；`target` 为 `插件ID:动作名` 或 `/命令名`。由宿主使用当前有效配置解析，返回脱离原对象的 `{value, fields}`，不回写输入，也不暴露整份配置。预览允许缺参，执行时仍作完整校验。验证见 `tests/effective-inputs.test.js`。
+
 ## 开发监督进程
 
 `createDevelopmentSupervisor({projectDir,entry,args,env,configFile,onEvent})` 启动文件监听 worker 和应用子进程，返回 `status()`、幂等 `close()`。父进程不加载插件运行模块；每次重启使用全新的 Node 进程，完整更新 ESM 导入依赖。`bindDevelopmentChild(app,{details,closePresentation})` 通过 IPC 报告就绪，收到重启请求后等待 `app.developmentStatus()` 的运行和管理操作均为空闲，再调用 `app.close()` 及界面清理。

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

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