@yanglaofish/fishtools 0.3.0 → 0.4.0

package/node_modules/@mytools/core/src/plugin-installations.js

@@ -0,0 +1,84 @@
+import path from 'node:path';
+import {mkdir,readFile,writeFile,rename,readdir,realpath,lstat,rm,unlink,rmdir} from 'node:fs/promises';
+import {randomUUID} from 'node:crypto';
+import {isDeepStrictEqual} from 'node:util';
+import {create as archive} from 'tar';
+import {FlowError} from '@mytools/sdk';
+
+async function json(file,fallback){try{return JSON.parse(await readFile(file,'utf8'));}catch(error){if(error.code==='ENOENT')return fallback;throw error;}}
+const flow=project=>path.join(project,'.flow');
+const stateFile=project=>path.join(flow(project),'plugins.json');
+export const readPluginState=project=>json(stateFile(project),{});
+
+// 所有安装/引用/回收操作共用工作区锁，防止其他 fst 进程同时切换批次。
+export async function withPluginMutation(project,callback){
+  await mkdir(flow(project),{recursive:true});const lock=path.join(flow(project),'plugin-mutation.lock');
+  try{await mkdir(lock);}catch(error){if(error.code==='EEXIST')throw new FlowError('插件状态正在被其他进程修改；若上次异常退出，请确认没有活动 fst 后移除 .flow/plugin-mutation.lock',{code:'PLUGIN_BUSY'});throw error;}
+  try{return await callback();}finally{await rmdir(lock);}
+}
+
+export async function leaseInstallation(project,root){
+  if(!root)return async()=>{};
+  const directory=path.join(flow(project),'installation-leases');await mkdir(directory,{recursive:true});
+  const file=path.join(directory,`${randomUUID()}.json`);
+  await writeFile(file,JSON.stringify({pid:process.pid,root:path.resolve(root)}));
+  return async()=>{try{await unlink(file);}catch(error){if(error.code!=='ENOENT')throw error;}};
+}
+
+export async function openPluginState(project,{readOnly=false}={}){
+  const existing=await readPluginState(project);
+  if(readOnly||!existing.root)return {state:existing,release:async()=>{}};
+  return withPluginMutation(project,async()=>{const state=await readPluginState(project);return {state,release:await leaseInstallation(project,state.root)};});
+}
+
+export async function assertPluginState(project,expected){
+  if(!isDeepStrictEqual(await readPluginState(project),expected))throw new FlowError('插件状态已被其他进程修改，请重启当前宿主后再操作',{code:'PLUGIN_STATE_CHANGED'});
+}
+
+export async function savePluginState(project,next,previous){
+  const backup=path.join(flow(project),'plugins.previous.json'),id=randomUUID();
+  await writeFile(`${backup}.${id}.tmp`,JSON.stringify(previous,null,2));await rename(`${backup}.${id}.tmp`,backup);
+  const file=stateFile(project);await writeFile(`${file}.${id}.tmp`,JSON.stringify(next,null,2));await rename(`${file}.${id}.tmp`,file);
+}
+
+export async function collectInstallations(project,{apply=false}={}){
+  // 预览仅读取，不创建锁或备份目录；执行时在锁内重新计算，不能复用旧预览。
+  const collect=async()=>{
+    const base=path.join(flow(project),'installations'),state=await readPluginState(project),previous=await json(path.join(flow(project),'plugins.previous.json'),{});
+    const protectedRoots=new Set([state.root,state.previousRoot,previous.root].filter(Boolean).map(root=>path.resolve(root)));
+    let leases=[];try{leases=await readdir(path.join(flow(project),'installation-leases'));}catch(error){if(error.code!=='ENOENT')throw error;}
+    for(const file of leases){
+      const lease=await json(path.join(flow(project),'installation-leases',file),null);if(!lease)continue;
+      // 无法确认进程已退出时宁可保留；PID 重用只会保守地多保留一个批次。
+      try{process.kill(lease.pid,0);protectedRoots.add(path.resolve(lease.root));}catch(error){if(error.code!=='ESRCH')protectedRoots.add(path.resolve(lease.root));}
+    }
+    let entries=[];try{entries=await readdir(base,{withFileTypes:true});}catch(error){if(error.code!=='ENOENT')throw error;}
+    const candidates=[],kept=[],removed=[];
+    const canonicalBase=entries.length?await realpath(base):base;
+    if(entries.length){
+      const projectRoot=await realpath(project),relative=path.relative(projectRoot,canonicalBase);
+      if(relative==='..'||relative.startsWith('..'+path.sep)||path.isAbsolute(relative)||(await lstat(base)).isSymbolicLink())throw new FlowError('安装目录越界或是目录链接，拒绝清理');
+      for(const root of [...protectedRoots]){try{protectedRoots.add(await realpath(root));}catch(error){if(error.code!=='ENOENT')throw error;}}
+    }
+    for(const entry of entries){
+      const directory=path.join(base,entry.name);
+      if(!entry.isDirectory()||!/^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/.test(entry.name)){kept.push({directory,reason:'非受管批次'});continue;}
+      const physical=await realpath(directory);
+      if(path.dirname(physical)!==canonicalBase||(await lstat(directory)).isSymbolicLink()||protectedRoots.has(physical)){kept.push({directory,reason:'当前、恢复、活动批次或链接'});continue;}
+      const pkg=await json(path.join(directory,'package.json'),{});
+      if(pkg.name!=='flow-project-plugins'){kept.push({directory,reason:'无法确认批次归属'});continue;}
+      candidates.push({directory});
+      if(apply){
+        const backups=path.join(flow(project),'installation-backups');await mkdir(backups,{recursive:true});
+        const backup=path.join(backups,`${entry.name}-${randomUUID()}.tgz`),temporary=`${backup}.tmp`;
+        await archive({cwd:canonicalBase,file:temporary,gzip:true,follow:false,portable:true},[entry.name]);
+        await rename(temporary,backup);
+        // 备份完成后再次确认真实绝对路径仍是本项目的直接子目录，才允许递归删除。
+        if(await realpath(directory)!==physical||path.dirname(physical)!==canonicalBase)throw new FlowError('安装批次路径在清理期间改变，已停止');
+        await rm(physical,{recursive:true,maxRetries:5,retryDelay:200});removed.push({directory,backup});
+      }
+    }
+    return {candidates,kept,removed};
+  };
+  return apply?withPluginMutation(project,collect):collect();
+}

package/node_modules/@mytools/core/src/plugin-tools.js

@@ -0,0 +1,133 @@
+import path from 'node:path';
+import {readFile,writeFile,mkdir,mkdtemp,rename,rm,access} from 'node:fs/promises';
+import semver from 'semver';
+import validateNpmPackageName from 'validate-npm-package-name';
+import {SDK_VERSION} from '@mytools/sdk';
+import {loadPlugin} from './plugins.js';
+import {validateDeclarations,validateCommands} from './contracts.js';
+import {assertSchema} from './validation.js';
+import {platformWarnings} from './environments.js';
+
+const validNpmName=name=>typeof name==='string'&&validateNpmPackageName(name).validForNewPackages===true;
+const hasOwn=(value,key)=>Object.hasOwn(value,key);
+
+function inspectRequired(schema,location,warning,seen=new WeakSet()){
+  if(!schema||typeof schema!=='object'||seen.has(schema))return;
+  seen.add(schema);
+  if(Array.isArray(schema.required)){
+    schema.required.forEach((name,index)=>{
+      if(typeof name==='string'&&!hasOwn(schema.properties??{},name))warning('REQUIRED_UNDECLARED',`必填字段 ${name} 未在同层 properties 声明；请检查 required 所在层级`,`${location}.required[${index}]`);
+    });
+  }
+  for(const key of ['properties','patternProperties','$defs','definitions']){
+    for(const [name,child] of Object.entries(schema[key]??{}))inspectRequired(child,`${location}.${key}.${name}`,warning,seen);
+  }
+  for(const key of ['items','additionalProperties','not','if','then','else'])inspectRequired(schema[key],`${location}.${key}`,warning,seen);
+  for(const key of ['allOf','anyOf','oneOf','prefixItems']){
+    if(Array.isArray(schema[key]))schema[key].forEach((child,index)=>inspectRequired(child,`${location}.${key}[${index}]`,warning,seen));
+  }
+}
+
+export async function validatePluginDirectory(directory){
+  const root=path.resolve(directory),diagnostics=[];
+  const report=(severity,code,message,location)=>diagnostics.push({severity,code,message,...(location?{path:location}:{})});
+  const error=(code,message,location)=>report('error',code,message,location);
+  const warning=(code,message,location)=>report('warning',code,message,location);
+  let pkg,plugin;
+  try{pkg=JSON.parse(await readFile(path.join(root,'package.json'),'utf8'));}
+  catch(cause){error('PACKAGE_READ_FAILED',`无法读取 package.json：${cause.message}`,'package.json');return {valid:false,plugin:{},diagnostics};}
+  if(!pkg||typeof pkg!=='object'||Array.isArray(pkg)){error('INVALID_PACKAGE','package.json 必须是对象','package.json');return {valid:false,plugin:{},diagnostics};}
+  if(!validNpmName(pkg.name))error('INVALID_PACKAGE_NAME','package.json 的 name 必须是合法 npm 包名','package.json.name');
+  if(!semver.valid(pkg.version))error('INVALID_PACKAGE_VERSION','package.json 的 version 必须是 semver 版本','package.json.version');
+  if(pkg.type!=='module')error('ESM_REQUIRED','插件必须声明 type: module','package.json.type');
+  try{({plugin}=await loadPlugin('.',root));}
+  catch(cause){error('PLUGIN_LOAD_FAILED',`无法导入插件：${cause.message}`,'package.json.main');return {valid:false,plugin:{},diagnostics};}
+  if(!plugin||typeof plugin!=='object'||Array.isArray(plugin)){error('INVALID_PLUGIN','默认导出必须是插件定义对象','plugin');return {valid:false,plugin:{},diagnostics};}
+  const identity={id:plugin.id,version:plugin.version};
+  if(!validNpmName(plugin.id))error('INVALID_PLUGIN_ID','插件 id 必须是合法 npm 包名','plugin.id');
+  else if(plugin.id!==pkg.name)error('PLUGIN_ID_MISMATCH',`插件 id ${plugin.id} 与包名 ${pkg.name} 不一致`,'plugin.id');
+  if(!semver.valid(plugin.version))error('INVALID_PLUGIN_VERSION','插件 version 必须是 semver 版本','plugin.version');
+  else if(plugin.version!==pkg.version)error('PLUGIN_VERSION_MISMATCH',`插件 version ${plugin.version} 与包版本 ${pkg.version} 不一致`,'plugin.version');
+  if(typeof plugin.sdk!=='string'||!semver.validRange(plugin.sdk))error('INVALID_SDK_RANGE','插件 sdk 必须明确声明有效的 semver 范围','plugin.sdk');
+  else if(!semver.satisfies(SDK_VERSION,plugin.sdk))error('SDK_INCOMPATIBLE',`插件 SDK 范围 ${plugin.sdk} 不包含当前 ${SDK_VERSION}`,'plugin.sdk');
+  for(const [key,location] of [['platforms','plugin.platforms'],['architectures','plugin.architectures']]){
+    if(plugin[key]===undefined)warning(`${key.toUpperCase()}_UNDECLARED`,`${key} 未声明，请明确插件支持范围`,location);
+  }
+  try{validateDeclarations(plugin);}catch(cause){error('INVALID_DECLARATION',cause.message,cause.details?.path??'plugin');}
+  if(['platforms','architectures'].every(key=>plugin[key]===undefined||Array.isArray(plugin[key]))) {
+    for(const message of platformWarnings(plugin))warning('PLATFORM_MISMATCH',message,message.includes('架构')?'plugin.architectures':'plugin.platforms');
+  }
+  try{validateCommands(plugin,new Set());}catch(cause){error('INVALID_COMMAND',cause.message,'plugin.commands');}
+  for(const [location,schema] of [['plugin.config',plugin.config]]){
+    if(schema!==undefined){try{assertSchema(schema,location);inspectRequired(schema,location,warning);}catch(cause){error('INVALID_SCHEMA',cause.message,location);}}
+  }
+  if(plugin.actions!==undefined&&(!plugin.actions||typeof plugin.actions!=='object'||Array.isArray(plugin.actions)))error('INVALID_ACTIONS','actions 必须是动作字典','plugin.actions');
+  for(const [name,action] of Object.entries(plugin.actions??{})){
+    const location=`plugin.actions.${name}`;
+    if(!action||typeof action!=='object'){error('INVALID_ACTION','动作必须是对象',location);continue;}
+    if(typeof action.run!=='function')error('MISSING_RUN','动作必须声明 run 函数',`${location}.run`);
+    for(const key of ['input','output']){
+      const schema=action[key],at=`${location}.${key}`;
+      if(schema===undefined){error('MISSING_SCHEMA',`动作 ${name} 必须明确声明 ${key} schema`,at);continue;}
+      try{assertSchema(schema,at);inspectRequired(schema,at,warning);}catch(cause){error('INVALID_SCHEMA',cause.message,at);}
+    }
+  }
+  if(plugin.commands!==undefined&&(!plugin.commands||typeof plugin.commands!=='object'||Array.isArray(plugin.commands)))error('INVALID_COMMANDS','commands 必须是命令字典','plugin.commands');
+  for(const [name,command] of Object.entries(plugin.commands??{})){
+    if(!command||typeof command!=='object'||command.action)continue;
+    for(const key of ['input','output']){
+      const schema=command[key],at=`plugin.commands.${name}.${key}`;
+      if(schema===undefined){error('MISSING_SCHEMA',`命令 ${name} 必须明确声明 ${key} schema`,at);continue;}
+      try{assertSchema(schema,at);inspectRequired(schema,at,warning);}catch(cause){error('INVALID_SCHEMA',cause.message,at);}
+    }
+  }
+  if(plugin.dependencies!==undefined){
+    if(!plugin.dependencies||typeof plugin.dependencies!=='object'||Array.isArray(plugin.dependencies))error('INVALID_DEPENDENCIES','dependencies 必须是插件 ID 到版本范围的字典','plugin.dependencies');
+    else for(const [name,range] of Object.entries(plugin.dependencies)){
+      if(!validNpmName(name))error('INVALID_DEPENDENCY_ID',`依赖插件 ID 无效：${name}`,`plugin.dependencies.${name}`);
+      if(typeof range!=='string'||!semver.validRange(range))error('INVALID_DEPENDENCY_RANGE',`依赖 ${name} 的版本范围无效`,`plugin.dependencies.${name}`);
+    }
+  }
+  if(plugin.runtime!==undefined){
+    const runtime=plugin.runtime;
+    if(!runtime||typeof runtime!=='object'||Array.isArray(runtime))error('INVALID_RUNTIME','runtime 必须是声明对象','plugin.runtime');
+    else{
+      if(typeof runtime.apply!=='function')error('INVALID_RUNTIME','runtime 必须提供 apply 函数','plugin.runtime.apply');
+      for(const key of ['provides','inject']){
+        const names=runtime[key]??[];
+        if(!Array.isArray(names)||names.some(name=>typeof name!=='string'||!/^\w[\w.-]*$/.test(name))||new Set(names).size!==names.length)
+          error('INVALID_RUNTIME',`runtime.${key} 必须是不重复的有效服务名数组`,`plugin.runtime.${key}`);
+      }
+      if(Array.isArray(runtime.provides)&&Array.isArray(runtime.inject)&&runtime.inject.some(name=>runtime.provides.includes(name)))
+        error('RUNTIME_SELF_DEPENDENCY','runtime.inject 不能依赖本插件提供的服务','plugin.runtime.inject');
+    }
+  }
+  return {valid:!diagnostics.some(item=>item.severity==='error'),plugin:identity,diagnostics};
+}
+
+function scaffold(name){
+  const packageJson={name,version:'1.0.0',type:'module',main:'index.js',files:['index.js','test','README.md','LICENSE'],scripts:{test:'node --test'},license:'MIT',engines:{node:'>=24.15.0'}};
+  const plugin=`// 直接导出插件定义，无需安装内部 SDK。\nexport default {\n  id:${JSON.stringify(name)},version:'1.0.0',sdk:'^0.1.0',\n  title:'嵌套输入示例',description:'演示业务结果、嵌套输入和判定预设。',\n  platforms:['win32','linux','darwin'],architectures:['x64','arm64'],\n  actions:{\n    check:{\n      title:'检查请求',description:'根据嵌套请求生成业务结果。',\n      input:{type:'object',properties:{request:{type:'object',properties:{name:{type:'string',minLength:1,title:'姓名'},enabled:{type:'boolean',title:'启用'}},required:['name','enabled'],additionalProperties:false}},required:['request'],additionalProperties:false},\n      output:{type:'object',properties:{ok:{type:'boolean'},message:{type:'string'}},required:['ok','message'],additionalProperties:false},\n      conditions:{passed:{title:'业务通过',path:'ok',op:'eq',value:true}},\n      async run({request},{signal}={}){\n        signal?.throwIfAborted?.();\n        return request.enabled?{ok:true,message:\`你好，\${request.name}\`}:{ok:false,message:'已禁用'};\n      },\n    },\n  },\n};\n`;
+  const testSource=`import test from 'node:test';\nimport assert from 'node:assert/strict';\nimport plugin from '../index.js';\n\ntest('嵌套参数和业务判定',async()=>{\n  assert.deepEqual(await plugin.actions.check.run({request:{name:'阿青',enabled:true}}),{ok:true,message:'你好，阿青'});\n  assert.deepEqual(await plugin.actions.check.run({request:{name:'阿青',enabled:false}}),{ok:false,message:'已禁用'});\n});\n`;
+  const readme=`# ${name}\n\n可独立安装的 Fishtools 插件示例，不依赖尚未公开发布的 SDK。\n\n## 使用\n\n在本目录运行 \`npm test\`，并运行 \`fst plugin validate .\` 检查声明。安装后可将 \`${name}:check\` 加入工作流。\n\n输入示例：\n\n\`\`\`json\n{"request":{"name":"阿青","enabled":true}}\n\`\`\`\n\n输出含 \`ok\` 与 \`message\`。\`ok:false\` 表示业务未通过，但动作仍正常返回；\`conditions.passed\` 可供工作流分支使用。请同步修改 package.json 和 index.js 中的名称、版本，并根据实际支持情况调整 platforms / architectures。\n`;
+  const license=`MIT License\n\nCopyright (c) ${new Date().getFullYear()} ${name}\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the "Software"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n`;
+  return {'package.json':`${JSON.stringify(packageJson,null,2)}\n`,'index.js':plugin,'README.md':readme,'LICENSE':license,'test/plugin.test.js':testSource};
+}
+
+export async function createPlugin(name,directory=path.resolve(name)){
+  if(!validNpmName(name))throw new Error('插件名称必须是合法 npm 包名（可带 @scope）');
+  const target=path.resolve(directory),parent=path.dirname(target);
+  await mkdir(parent,{recursive:true});
+  try{await access(target);throw new Error(`目标目录已存在：${target}`);}catch(cause){if(cause.code!=='ENOENT')throw cause;}
+  const staging=await mkdtemp(path.join(parent,'.plugin-create-'));
+  try{
+    for(const [file,contents] of Object.entries(scaffold(name))){
+      const destination=path.join(staging,file);
+      await mkdir(path.dirname(destination),{recursive:true});
+      await writeFile(destination,contents,{flag:'wx'});
+    }
+    try{await access(target);throw new Error(`目标目录已存在：${target}`);}catch(cause){if(cause.code!=='ENOENT')throw cause;}
+    await rename(staging,target);
+  }catch(cause){await rm(staging,{recursive:true,force:true});throw cause;}
+  return {directory:target};
+}

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

@@ -35,21 +35,31 @@ export async function npm(args,options={}) {
   return runProcess('npm',args,{timeout:180000,...options});
 }
 
-export async function installGeneration(projectDir,{add,remove,state}) {
+export async function installGeneration(projectDir,{add,remove,link,state}) {
   const root=path.join(projectDir,'.flow','installations',randomUUID());
   await mkdir(root,{recursive:true});
   const dependencies={...(state?.dependencies??{})};
-  if(remove) delete dependencies[remove];
+  const links={...(state?.links??{})};
+  if(remove){delete dependencies[remove];delete links[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];
+  }
   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 {}
     if(source.startsWith('-')) throw new FlowError('插件来源不能以选项符号开头',{code:'VALIDATION'});
   }
-  const result=await npm(['install',...(source?[source]:[]),'--save-exact','--ignore-scripts','--install-links','--no-audit','--no-fund'],{cwd:root});
-  if(result.exitCode!==0) throw new FlowError(`插件安装失败：${result.stderr}`,{code:'INSTALL_FAILED'});
+  if(source||Object.keys(dependencies).length){
+    const result=await npm(['install',...(source?[source]:[]),'--save-exact','--ignore-scripts','--install-links','--no-audit','--no-fund'],{cwd:root});
+    if(result.exitCode!==0) throw new FlowError(`插件安装失败：${result.stderr}`,{code:'INSTALL_FAILED'});
+  }
   const pkg=await readJson(path.join(root,'package.json'));
   const loaded=[];
-  for(const name of Object.keys(pkg.dependencies??{})) loaded.push(await loadPlugin(name,root));
-  return {state:{root,dependencies:pkg.dependencies??{}},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};
 }

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

@@ -2,10 +2,17 @@ import { execa } from 'execa';
 import treeKill from 'tree-kill';
 import which from 'which';
 import { FlowError } from '@mytools/sdk';
-import { StringDecoder } from 'node:string_decoder';
 import path from 'node:path';
 
-export async function runProcess(file,args=[],{cwd,env,signal,timeout=30000,maxBuffer=4*1024*1024,onOutput}={}) {
+const outputText=bytes=>bytes??new Uint8Array();
+const stripFinalNewline=text=>text.endsWith('\r\n')?text.slice(0,-2):text.endsWith('\n')?text.slice(0,-1):text;
+
+export async function runProcess(file,args=[],{cwd,env,signal,timeout=30000,maxBuffer=4*1024*1024,encoding='utf8',onOutput}={}) {
+  if(typeof encoding!=='string')throw new TypeError(`不支持的程序输出编码：${String(encoding)}`);
+  const label=/^(utf16le|ucs2|ucs-2)$/i.test(encoding)?'utf-16le':encoding;
+  let decoderEncoding;
+  try {decoderEncoding=new TextDecoder(label).encoding;}
+  catch {throw new TypeError(`不支持的程序输出编码：${encoding}`);}
   if(signal?.aborted) throw new FlowError('操作已取消',{code:'CANCELLED'});
   let executable;
   try {
@@ -22,7 +29,8 @@ export async function runProcess(file,args=[],{cwd,env,signal,timeout=30000,maxB
     if(!executable)throw Object.assign(new Error(`not found: ${file}`),{code:'ENOENT'});
   }
   catch(cause){throw new FlowError(`未找到程序：${file}`,{code:'ENOENT',details:{executable:file},cause});}
-  const child=execa(executable,args,{cwd,env,reject:false,windowsHide:true,maxBuffer,timeout:0,shell:false});
+  // Execa 收集原始字节；文本只在这里按同一编码解码，避免返回值被默认 UTF-8 解码。
+  const child=execa(executable,args,{cwd,env,reject:false,windowsHide:true,maxBuffer,timeout:0,shell:false,encoding:'buffer',stripFinalNewline:false});
   let reason,killing,outputError,outputFailed=false,outputWrites=Promise.resolve();
   const stop=kind=>{
     if(reason) return; reason=kind;
@@ -41,14 +49,14 @@ export async function runProcess(file,args=[],{cwd,env,signal,timeout=30000,maxB
   const flush=[];
   for(const [name,stream] of [['stdout',child.stdout],['stderr',child.stderr]]){
     let bytes=0,ended=false;
-    const decoder=new StringDecoder('utf8');
-    const finish=()=>{if(!ended){ended=true;emit(name,decoder.end());}};
+    const decoder=new TextDecoder(decoderEncoding);
+    const finish=()=>{if(!ended){ended=true;emit(name,decoder.decode());}};
     flush.push(finish);stream?.once('end',finish);
     stream?.on('data',chunk=>{
       bytes+=Buffer.byteLength(chunk);
       // 流量超限时立即回收整棵进程树，不继续扩张待落盘的日志队列。
       if(bytes>maxBuffer){stop('output-limit');return;}
-      if(onOutput)emit(name,decoder.write(Buffer.isBuffer(chunk)?chunk:Buffer.from(chunk)));
+      if(onOutput)emit(name,decoder.decode(chunk,{stream:true}));
     });
   }
   const timer=timeout>0 ? setTimeout(()=>stop('timeout'),timeout) : null;
@@ -67,5 +75,6 @@ export async function runProcess(file,args=[],{cwd,env,signal,timeout=30000,maxB
   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'});
-  return {exitCode:result.exitCode,stdout:result.stdout??'',stderr:result.stderr??''};
+  const decode=bytes=>stripFinalNewline(new TextDecoder(decoderEncoding).decode(outputText(bytes)));
+  return {exitCode:result.exitCode,stdout:decode(result.stdout),stderr:decode(result.stderr)};
 }

package/node_modules/@mytools/core/src/schema-path.js

@@ -0,0 +1,31 @@
+import {FlowError} from '@mytools/sdk';
+
+const forbidden=new Set(['__proto__','constructor','prototype']);
+const missing=ref=>{throw new FlowError(`引用字段不存在：${ref}`,{code:'VALIDATION'});};
+
+// 路径只用于已声明的字段；开放对象可继续引用，带类型的动态键则继续逐层检查。
+export function resolveSchemaPath(schema,fields,ref=Array.isArray(fields)?fields.join('.'):fields){
+  const parts=Array.isArray(fields)?fields:typeof fields==='string'?fields.split('.'):[];
+  if(!parts.length)return schema;
+  if(parts.some(part=>typeof part!=='string'||!part||forbidden.has(part)))missing(ref);
+  let current=schema;
+  for(const field of parts){
+    if(current===true){continue;}
+    if(current===false||!current||typeof current!=='object'||Array.isArray(current))missing(ref);
+    const types=Array.isArray(current.type)?current.type:[current.type];
+    const isArray=types.includes('array')||current.items!==undefined;
+    if(isArray){
+      if(!/^(0|[1-9]\d*)$/.test(field))missing(ref);
+      if(Array.isArray(current.items))current=current.items[Number(field)]??current.additionalItems??true;
+      else current=current.items??true;
+      continue;
+    }
+    if(current.properties&&Object.hasOwn(current.properties,field)){
+      current=current.properties[field];continue;
+    }
+    if(!types.includes('object')&&types.some(type=>type!==undefined))missing(ref);
+    current=current.additionalProperties??true;
+  }
+  if(current===false)missing(ref);
+  return current;
+}

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

@@ -1,29 +1,42 @@
 import Ajv from 'ajv';
 import { FlowError } from '@mytools/sdk';
 
-const ajv = new Ajv({ allErrors: true, strict: false, useDefaults: true });
-const validators = new WeakMap();
-const booleanValidators = new Map();
+const ajv = new Ajv({ allErrors: true, strict: false });
+const validators = {true:new WeakMap(),false:new WeakMap()};
+const booleanValidators = {true:new Map(),false:new Map()};
 export const emptyObject = { type: 'object', properties: {}, additionalProperties: false };
 
-export function assertSchema(schema,label) {
+export function assertSchema(schema,label,{useDefaults=true}={}) {
   if (!(typeof schema==='boolean'||schema&&typeof schema==='object'&&!Array.isArray(schema))) throw new FlowError(`${label} 必须声明有效的 JSON Schema`,{code:'VALIDATION'});
-  const cache=typeof schema==='boolean'?booleanValidators:validators;
+  const cache=(typeof schema==='boolean'?booleanValidators:validators)[Boolean(useDefaults)];
   let check=cache.get(schema);
   if(!check){
     // 每份定义独立解析 $id/$ref，避免插件重载或不同插件共用 ID 时串用约束。
     // 编译结果仍按对象缓存；注册表随校验器释放，不污染后续安装批次。
-    try{check=new Ajv({allErrors:true,strict:false,useDefaults:true}).compile(schema);cache.set(schema,check);}
+    try{check=new Ajv({allErrors:true,strict:false,useDefaults:Boolean(useDefaults)}).compile(schema);cache.set(schema,check);}
     catch(cause){throw new FlowError(`${label} JSON Schema 无效：${cause.message}`,{code:'VALIDATION',cause});}
   }
   return check;
 }
 
-export function validate(schema, value, label) {
+const pointerToken=value=>String(value).replaceAll('~','~0').replaceAll('/','~1');
+function diagnostic(error){
+  let instancePath=error.instancePath;
+  if(error.keyword==='required')instancePath+=`/${pointerToken(error.params.missingProperty)}`;
+  if(error.keyword==='additionalProperties')instancePath+=`/${pointerToken(error.params.additionalProperty)}`;
+  // 保留 Ajv 原有 instancePath 语义，新字段提供指向缺失/额外属性的完整位置。
+  return {...error,jsonPointer:instancePath};
+}
+
+export function validate(schema, value, label,{useDefaults=true}={}) {
   if (schema==null) return structuredClone(value);
-  const check = assertSchema(schema,label);
+  const check = assertSchema(schema,label,{useDefaults});
   const copy = structuredClone(value);
-  if (!check(copy)) throw new FlowError(`${label}: ${ajv.errorsText(check.errors, { separator: '；' })}`, { code: 'VALIDATION', details: check.errors });
+  if (!check(copy)) {
+    const details=check.errors.map(diagnostic);
+    const locations=details.map(error=>`${error.jsonPointer||'/'} (${error.schemaPath})`).join('；');
+    throw new FlowError(`${label}: ${ajv.errorsText(check.errors, { separator: '；' })}；位置 ${locations}`, { code: 'VALIDATION', details });
+  }
   return copy;
 }
 

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

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

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

@@ -4,22 +4,9 @@ import { randomUUID } from 'node:crypto';
 import YAML from 'yaml';
 import { FlowError } from '@mytools/sdk';
 import { assertId, assertSchema, references, referenceParts, emptyObject } from './validation.js';
+import {resolveSchemaPath} from './schema-path.js';
 import {validateCondition,validateStepList} from './control.js';
 
-function fieldSchema(schema,fields,ref){
-  let current=schema;
-  for(const field of fields){
-    if(!current||current===true)return {};
-    if(current.properties&&Object.hasOwn(current.properties,field)){current=current.properties[field];continue;}
-    if(current.type==='array'&&/^\d+$/.test(field)){current=current.items;continue;}
-    if(current.additionalProperties===false||current===false||(current.type&&!['object','array'].includes(current.type))){
-      throw new FlowError(`引用字段不存在：${ref}`,{code:'VALIDATION'});
-    }
-    return {};
-  }
-  return current??{};
-}
-
 export class WorkflowStore {
   constructor(root) { this.root = path.resolve(root); }
   file(id) { assertId(id); return path.join(this.root,`${id}.yaml`); }
@@ -76,7 +63,7 @@ export class WorkflowStore {
       const checker=previous=>ref=>{
         const p=referenceParts(ref);
         if(p[0]==='steps' && !previous.has(p[1])) throw new FlowError(`${id} 引用必须指向前序步骤：${ref}`,{code:'VALIDATION'});
-        return fieldSchema(p[0]==='inputs'?(w.inputs??emptyObject):previous.get(p[1]),p.slice(p[0]==='inputs'?1:3),ref);
+        return resolveSchemaPath(p[0]==='inputs'?(w.inputs??emptyObject):previous.get(p[1]),p.slice(p[0]==='inputs'?1:3),ref);
       };
       const resolveList=async(steps,inherited=new Map(),parallel=false)=>{
         const previous=new Map(inherited),own={};

package/node_modules/@mytools/pack/dependencies.js

@@ -24,7 +24,12 @@ export async function collectPackages(roots) {
     }
     if(!trees.has(base))trees.set(base,await new Arborist({path:base}).loadActual());
     const tree=trees.get(base);
-    const found=[...tree.inventory.values()].find(n=>n.realpath===root && !n.isLink);
+    let found=[...tree.inventory.values()].find(n=>path.relative(n.realpath,root)==='' && !n.isLink);
+    // 开发引用可能嵌套在无关项目下，其上层 lock 不代表当前插件属于该依赖树。
+    if(!found&&base!==root){
+      if(!trees.has(root))trees.set(root,await new Arborist({path:root}).loadActual());
+      found=[...trees.get(root).inventory.values()].find(n=>path.relative(n.realpath,root)===''&&!n.isLink);
+    }
     if(!found)throw new FlowError(`无法解析包的生产依赖：${root}`);
     return found;
   }
@@ -66,6 +71,8 @@ export async function copyPackages(nodes,destination,target,{filters=new Map()}=
     const filter=filters.get(packageRoot);
     const files=[...new Set([...await packlist(await new Arborist({path:packageRoot}).loadActual()),...(filter?.extraFiles??[])])];
     for(const file of files){
+      // 项目可以与开发插件共用根目录；宿主私有状态和安装批次永远不进入插件快照。
+      if(file.split(/[\\/]/)[0]==='.flow')continue;
       if(filter&&!filter.include(file))continue;
       const source=path.resolve(packageRoot,file),physical=await realpath(source);
       // 两端先解析实际路径，再按系统规则比较，兼容 Windows 大小写、短路径和目录联接。