@yanglaofish/fishtools 0.5.2 → 0.6.0

package/manual/packages/fst-logs/src/run-logs.js

@@ -5,6 +5,7 @@ import {markdownHeader,markdownEvent,markdownResult} from './markdown-log.js';
 import {logPolicy,jsonSize,eventPreview} from './log-bounds.js';
 import {createStepSummaries} from './step-summaries.js';
 import {previewRun} from './run-preview.js';
+import {samePathFileIdentity} from './file-identity.js';
 
 const validId=id=>typeof id==='string'&&/^[a-f0-9-]{36}$/.test(id);
 const logFiles=['run.md','events.jsonl','result.json','run.meta.json'];
@@ -33,9 +34,9 @@ export function createRunLogs(directory,{projectDir,allowLegacy=false,...options
     return dir;
   }
   async function safeFile(file){
-    const before=await lstat(file);if(!before.isFile()||before.isSymbolicLink())throw new FlowError('日志文件无效');
+    const before=await lstat(file,{bigint:true});if(!before.isFile()||before.isSymbolicLink())throw new FlowError('日志文件无效');
     const handle=await open(file,'r');
-    try{const after=await handle.stat();if(!after.isFile()||before.ino!==after.ino||before.dev!==after.dev)throw new FlowError('日志文件无效');return handle;}
+    try{const after=await handle.stat({bigint:true});if(!after.isFile()||!(await samePathFileIdentity(file,before,after)))throw new FlowError('日志文件无效');return handle;}
     catch(error){await handle.close();throw error;}
   }
   async function read(id){

package/manual/packages/fst-logs/src/session-history.js

@@ -0,0 +1,180 @@
+import path from 'node:path';
+import {constants} from 'node:fs';
+import {lstat,mkdir,open,readdir,rename,unlink} from 'node:fs/promises';
+import {randomUUID} from 'node:crypto';
+import {FlowError} from '@mytools/sdk';
+import {jsonSize} from './log-bounds.js';
+import {samePathFileIdentity} from './file-identity.js';
+
+const validId=id=>typeof id==='string'&&/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(id);
+const normalize=directory=>process.platform==='win32'?path.resolve(directory).toLowerCase():path.resolve(directory);
+const queues=new Map();
+const decoder=new TextDecoder('utf-8',{fatal:true});
+const failure=(message,code,cause)=>new FlowError(message,{code,cause});
+const plain=value=>value!==null&&typeof value==='object'&&!Array.isArray(value);
+
+function checkId(id){if(!validId(id))throw failure('会话 ID 无效','SESSION_ID_INVALID');}
+function checkSnapshot(record,id){
+  if(!plain(record)||record.schemaVersion!==1||record.id!==id||!Number.isFinite(Date.parse(record.startedAt))||!Number.isFinite(Date.parse(record.updatedAt))||Date.parse(record.updatedAt)<Date.parse(record.startedAt)||!Array.isArray(record.commandHistory)||!record.commandHistory.every(command=>typeof command==='string')||!Array.isArray(record.feed))throw failure('会话元数据格式无效','SESSION_RECORD_INVALID');
+  if(record.resumedFrom!==undefined&&(!validId(record.resumedFrom)||record.resumedFrom===id))throw failure('会话恢复来源 ID 无效','SESSION_RECORD_INVALID');
+}
+function encoded(value,limit,code){
+  try{
+    // 预估器会多计容器末尾分隔符，先用双倍预算拒绝巨大输入，再按实际 JSON 字节精确判断。
+    if(jsonSize(value,limit*2)>limit*2)throw failure('会话记录超过字节预算',code);
+    const text=JSON.stringify(value);
+    if(typeof text!=='string')throw failure('会话记录必须可以序列化为 JSON','SESSION_RECORD_INVALID');
+    if(Buffer.byteLength(text)>limit)throw failure('会话记录超过字节预算',code);
+    return text;
+  }catch(error){if(error instanceof FlowError)throw error;throw failure('会话记录不能序列化为 JSON','SESSION_RECORD_INVALID',error);}
+}
+function parsed(buffer){
+  try{return JSON.parse(decoder.decode(buffer));}
+  catch(error){throw failure('会话记录损坏或不是有效的 UTF-8 JSON','SESSION_RECORD_INVALID',error);}
+}
+
+export function createSessionHistory(directory,{projectDir,maxBytes=2*1024*1024,maxEntryBytes=65536,maxPageBytes=512*1024,maxPendingBytes=8*1024*1024}={}){
+  if(typeof directory!=='string'||!directory||typeof projectDir!=='string'||!projectDir)throw failure('会话目录和工作区目录必须为非空路径','SESSION_PATH_INVALID');
+  const policy={maxBytes,maxEntryBytes,maxPageBytes,maxPendingBytes};
+  for(const [key,value] of Object.entries(policy))if(!Number.isSafeInteger(value)||value<2)throw failure(`会话 ${key} 必须为至少 2 的整数字节数`,'SESSION_RECORD_INVALID');
+  if(maxPageBytes<maxEntryBytes+1)throw failure('会话分页预算必须容纳一条记录及换行','SESSION_PAGE_LIMIT');
+  const root=path.resolve(directory),owner=normalize(projectDir);
+  const location=(id,suffix)=>{checkId(id);return path.join(root,`${id}.${suffix}`);};
+
+  function queue(id,bytes,operation){
+    checkId(id);const key=`${normalize(root)}\0${id}`;
+    let state=queues.get(key);
+    if(!state)state={tail:Promise.resolve(),bytes:0,jobs:0};
+    if(state.bytes+bytes>maxPendingBytes)return Promise.reject(failure('会话待写队列超过字节预算','SESSION_QUEUE_LIMIT'));
+    queues.set(key,state);
+    state.bytes+=bytes;state.jobs++;
+    const job=state.tail.then(operation).finally(()=>{state.bytes-=bytes;state.jobs--;if(!state.jobs&&queues.get(key)===state)queues.delete(key);});
+    // 一次失败只影响对应调用，后续操作仍可以读取原文件或重试。
+    state.tail=job.catch(()=>{});return job;
+  }
+  async function safeRoot(create=false){
+    if(create)await mkdir(root,{recursive:true});
+    const stat=await lstat(root);
+    if(!stat.isDirectory()||stat.isSymbolicLink())throw failure('会话根目录无效，不能使用目录链接','SESSION_PATH_INVALID');
+  }
+  async function regular(file,missing=false){
+    let stat;
+    try{stat=await lstat(file,{bigint:true});}catch(error){if(missing&&error.code==='ENOENT')return null;throw error;}
+    if(!stat.isFile()||stat.isSymbolicLink())throw failure('会话文件无效，不能使用文件链接','SESSION_PATH_INVALID');
+    return stat;
+  }
+  async function safeFile(file,{append=false}={}){
+    const before=await regular(file,append);
+    const flags=(append?constants.O_RDWR|constants.O_APPEND|constants.O_CREAT:constants.O_RDONLY)|(constants.O_NOFOLLOW??0);
+    const handle=await open(file,flags,0o600);
+    try{
+      const after=await handle.stat({bigint:true}),current=await regular(file);
+      if(!after.isFile()||(before&&!(await samePathFileIdentity(file,before,after)))||!(await samePathFileIdentity(file,current,after)))throw failure('会话文件在访问期间发生替换','SESSION_PATH_INVALID');
+      return handle;
+    }catch(error){await handle.close();throw error;}
+  }
+  async function readRecord(id){
+    checkId(id);await safeRoot();const handle=await safeFile(location(id,'json'));
+    let record;
+    try{
+      const size=(await handle.stat()).size;
+      if(size>maxBytes)throw failure('会话元数据超过读取字节预算','SESSION_METADATA_LIMIT');
+      const buffer=Buffer.alloc(Math.min(size+1,maxBytes+1));let offset=0;
+      while(offset<buffer.length){const {bytesRead}=await handle.read(buffer,offset,buffer.length-offset,offset);if(!bytesRead)break;offset+=bytesRead;}
+      if(offset>maxBytes)throw failure('会话元数据超过读取字节预算','SESSION_METADATA_LIMIT');
+      record=parsed(buffer.subarray(0,offset));
+    }finally{await handle.close();}
+    checkSnapshot(record,id);
+    if(record.sessionOwner!==owner)throw failure('会话记录不属于此工作区','SESSION_OWNER_MISMATCH');
+    return record;
+  }
+  async function saveRecord(record,text){
+    await safeRoot(true);
+    let existing;
+    try{existing=await readRecord(record.id);}catch(error){if(error.code!=='ENOENT')throw error;}
+    if(existing){
+      if(existing.startedAt!==record.startedAt)throw failure('已有会话的开始时间不能改变；恢复会话请使用新 ID','SESSION_RECORD_INVALID');
+      if(Date.parse(record.updatedAt)<Date.parse(existing.updatedAt))return existing;
+    }else{
+      // 缺少元数据的旧追加日志也不能被新会话接管。
+      if(await regular(location(record.id,'jsonl'),true))throw failure('会话追加日志已存在但缺少有效元数据，请使用新 ID','SESSION_RECORD_INVALID');
+    }
+    const target=location(record.id,'json'),temporary=path.join(root,`.${record.id}.${randomUUID()}.tmp`);
+    let handle;
+    try{
+      handle=await open(temporary,'wx',0o600);await handle.writeFile(text,'utf8');await handle.sync();await handle.close();handle=null;
+      await safeRoot();await regular(target,true);await rename(temporary,target);
+    }finally{if(handle)await handle.close();try{await unlink(temporary);}catch(error){if(error.code!=='ENOENT')throw error;}}
+    return record;
+  }
+  async function appendRecord(id,text){
+    await readRecord(id);await safeRoot();const handle=await safeFile(location(id,'jsonl'),{append:true});
+    try{
+      const size=(await handle.stat()).size;
+      if(size){const last=Buffer.alloc(1);await handle.read(last,0,1,size-1);if(last[0]!==10)throw failure('会话追加日志末尾存在未完成记录，拒绝继续写入','SESSION_RECORD_INVALID');}
+      await handle.writeFile(text+'\n','utf8');await handle.sync();
+    }finally{await handle.close();}
+  }
+  async function readPage(id,{cursor=0,limit=100}={}){
+    if(!Number.isSafeInteger(cursor)||cursor<0)throw failure('会话 cursor 必须为非负整数字节位置','SESSION_CURSOR_INVALID');
+    if(!Number.isSafeInteger(limit)||limit<1)throw failure('会话 limit 必须为正整数条目数','SESSION_PAGE_LIMIT');
+    limit=Math.min(limit,200);await readRecord(id);
+    let handle;
+    try{handle=await safeFile(location(id,'jsonl'));}
+    catch(error){if(error.code!=='ENOENT')throw error;if(cursor!==0)throw failure('会话 cursor 超过记录长度','SESSION_CURSOR_INVALID');return {entries:[],cursor,nextCursor:0,hasMore:false,totalBytes:0};}
+    try{
+      const totalBytes=(await handle.stat()).size;
+      if(cursor>totalBytes)throw failure('会话 cursor 超过记录长度','SESSION_CURSOR_INVALID');
+      if(cursor){const previous=Buffer.alloc(1);await handle.read(previous,0,1,cursor-1);if(previous[0]!==10)throw failure('会话 cursor 必须位于完整记录边界','SESSION_CURSOR_INVALID');}
+      const buffer=Buffer.alloc(Math.min(maxPageBytes+1,totalBytes-cursor));let readBytes=0;
+      while(readBytes<buffer.length){const {bytesRead}=await handle.read(buffer,readBytes,buffer.length-readBytes,cursor+readBytes);if(!bytesRead)break;readBytes+=bytesRead;}
+      let offset=0;const entries=[];
+      while(offset<readBytes&&entries.length<limit){
+        const newline=buffer.indexOf(10,offset);
+        if(newline===-1||newline>=readBytes){
+          if(readBytes-offset>maxEntryBytes)throw failure('会话单条记录超过读取字节预算','SESSION_ENTRY_LIMIT');
+          if(cursor+readBytes<totalBytes&&entries.length)break;
+          throw failure('会话追加日志存在未完成记录','SESSION_RECORD_INVALID');
+        }
+        if(newline-offset>maxEntryBytes)throw failure('会话单条记录超过读取字节预算','SESSION_ENTRY_LIMIT');
+        if(newline+1>maxPageBytes)break;
+        const entry=parsed(buffer.subarray(offset,newline));
+        if(!plain(entry))throw failure('会话追加记录必须为 JSON 对象','SESSION_RECORD_INVALID');
+        entries.push(entry);offset=newline+1;
+      }
+      const nextCursor=cursor+offset;
+      return {entries,cursor,nextCursor,hasMore:nextCursor<totalBytes,totalBytes};
+    }finally{await handle.close();}
+  }
+
+  return {
+    owner,policy:Object.freeze({...policy}),
+    async save(snapshot){
+      checkId(snapshot?.id);checkSnapshot(snapshot,snapshot.id);
+      const text=encoded({...snapshot,sessionOwner:owner},maxBytes,'SESSION_METADATA_LIMIT'),record=JSON.parse(text);
+      checkSnapshot(record,record.id);return queue(record.id,Buffer.byteLength(text),()=>saveRecord(record,text));
+    },
+    async read(id){checkId(id);return queue(id,0,()=>readRecord(id));},
+    async list(){
+      let entries;
+      try{await safeRoot();entries=await readdir(root,{withFileTypes:true});}catch(error){if(error.code==='ENOENT')return [];throw error;}
+      const records=[];
+      for(const entry of entries){
+        if(!entry.isFile()||!entry.name.endsWith('.json'))continue;
+        const id=entry.name.slice(0,-5);if(!validId(id))continue;
+        try{
+          const record=await queue(id,0,()=>readRecord(id));
+          records.push({schemaVersion:1,id,sessionOwner:record.sessionOwner,startedAt:record.startedAt,updatedAt:record.updatedAt,...(record.resumedFrom?{resumedFrom:record.resumedFrom}:{}),commandCount:record.commandHistory.length,feedCount:record.feed.length});
+        }catch(error){if(error.code==='EACCES'||error.code==='EPERM')throw error;}
+      }
+      return records.sort((a,b)=>Date.parse(b.updatedAt)-Date.parse(a.updatedAt)||b.id.localeCompare(a.id));
+    },
+    async append(id,entry){
+      checkId(id);if(!plain(entry))throw failure('会话追加记录必须为 JSON 对象','SESSION_RECORD_INVALID');
+      const text=encoded(entry,maxEntryBytes,'SESSION_ENTRY_LIMIT');
+      if(!plain(JSON.parse(text)))throw failure('会话追加记录必须为 JSON 对象','SESSION_RECORD_INVALID');
+      return queue(id,Buffer.byteLength(text)+1,()=>appendRecord(id,text));
+    },
+    async page(id,options={}){checkId(id);return queue(id,0,()=>readPage(id,options));},
+  };
+}

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,9 +38,17 @@ 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` 字段保留用户原始指令，直接执行的简单命令同时记录实际程序路径和参数。
+
 `runProcess(file,args,{env,extendEnv=true})` 默认把 `env` 覆盖到宿主环境上。
+
+可选 `onStart({file,args,cwd,script?})` 在程序路径解析后、实际启动前调用并等待完成；回调失败或此时取消不会启动子进程。`args` 使用独立数组，`cwd` 是实际绝对目录，`commandText` 可补充原始 Shell 指令。宿主通过该接口保存过程记录，执行结果与输出编码仍由原有接口返回。
 当调用方已按动作代理规则构造完整环境时，传 `extendEnv:false`，防止已移除的代理变量被重新继承。
 
 缓冲模式由平台按每条输出流的原始字节计算 `maxBuffer`，默认每条流 4 MiB；超限返回 `OUTPUT_LIMIT`。

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",
@@ -22,13 +23,13 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=24.15.0"
+    "node": "^22.22.2 || >=24.0.0"
   },
   "dependencies": {
     "@mytools/sdk": "0.1.0",
     "execa": "10.1.0",
     "tree-kill": "1.2.2",
-    "undici": "^8.4.1",
-    "which": "7.0.0"
+    "undici": "7.30.0",
+    "which": "6.0.1"
   }
 }

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,8 +5,10 @@ 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,outputMode='buffer',summaryBytes=65536}={}) {
+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');
   if(typeof maxBuffer!=='number'||Number.isNaN(maxBuffer)||maxBuffer<0)throw new TypeError('maxBuffer 必须为非负数，可用 Infinity 表示不限制缓冲');
   const streaming=outputMode==='stream';
@@ -33,9 +35,14 @@ export async function runProcess(file,args=[],{cwd,env,extendEnv=true,signal,tim
     if(!executable)throw Object.assign(new Error(`not found: ${file}`),{code:'ENOENT'});
   }
   catch(cause){throw new FlowError(`未找到程序：${file}`,{code:'ENOENT',details:{executable:file},cause});}
+  // 先保存实际程序和参数；记录失败时尚未启动进程，不留下未受管副作用。
+  await onStart?.({file:executable,args:[...args],cwd:path.resolve(cwd??process.cwd()),...(commandText!==undefined?{script:commandText}:{})});
+  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;
@@ -107,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-platform/src/shell.js

@@ -7,6 +7,8 @@ import {runProcess as executeProcess} from './process.js';
 
 const shells=new Set(['auto','powershell','pwsh','sh','bash']);
 const powerShellArgs=['-NoLogo','-NoProfile','-NonInteractive','-OutputFormat','Text'];
+const windowsOemEncodings=new Map([[866,'ibm866'],[874,'windows-874'],[932,'shift_jis'],[936,'gbk'],[949,'euc-kr'],[950,'big5'],[65001,'utf-8']]);
+let windowsOemCodePage;
 
 function selectShell(script,shell,platform){
   if(typeof script!=='string'||!script.trim()||script.includes('\u0000'))throw new FlowError('命令文本必须是非空字符串，且不能包含 NUL 字符',{code:'VALIDATION'});
@@ -14,6 +16,42 @@ function selectShell(script,shell,platform){
   return shell==='auto'?(platform==='win32'?'powershell':'sh'):shell;
 }
 
+function ipconfigArguments(script){
+  // 只解析单行字面量；Shell 运算符、展开、组合引号与特殊引号均留给 PowerShell。
+  if(/[\r\n\u0085\u2028\u2029\u2018\u2019\u201c\u201d]/.test(script))return;
+  const command=/^\s*ipconfig(?:\.exe)?(?=\s|$)/i.exec(script);
+  if(!command)return;
+  let remaining=script.slice(command[0].length);const args=[];
+  while(remaining.trim()){
+    const token=/^\s+(?:'((?:[^']|'')*)'|"([^"`$]*)"|([^\s"'`$;|&<>(){}\[\]#@,]+))(?=\s|$)/.exec(remaining);
+    if(!token)return;
+    const value=token[1]!==undefined?token[1].replaceAll("''","'"):token[2]??token[3];
+    if(value==='--%')return;
+    args.push(value);remaining=remaining.slice(token[0].length);
+  }
+  return args;
+}
+
+async function ipconfigEncoding(windowsRoot,{cwd,env,extendEnv,signal,timeout}){
+  if(windowsOemCodePage===undefined){
+    // GetOEMCP 读取当前系统原生代码页，不修改控制台代码页或依赖用户的区域格式。
+    const source=`Add-Type -Namespace Fst -Name NativeCodePage -MemberDefinition '[System.Runtime.InteropServices.DllImport("kernel32.dll")] public static extern uint GetOEMCP();'; [Console]::WriteLine([Fst.NativeCodePage]::GetOEMCP())`;
+    const encoded=Buffer.from(source,'utf16le').toString('base64');
+    const command=`& ([ScriptBlock]::Create([Text.Encoding]::Unicode.GetString([Convert]::FromBase64String('${encoded}'))))`;
+    let result;
+    try{
+      result=await executeProcess(path.join(windowsRoot,'System32','WindowsPowerShell','v1.0','powershell.exe'),[...powerShellArgs,'-Command',command],{cwd,env,extendEnv,signal,timeout,maxBuffer:4096});
+    }catch(error){
+      if(error.code==='CANCELLED'||error.code==='TIMEOUT')throw error;
+      return;
+    }
+    if(result.exitCode!==0||!/^\d+$/.test(result.stdout.trim()))return;
+    windowsOemCodePage=Number(result.stdout.trim());
+  }
+  // TextDecoder 不支持 OEM 437、850 等代码页；无法准确解码时保留原 Shell 路径。
+  return windowsOemEncodings.get(windowsOemCodePage);
+}
+
 function powerShellSource(script){
   // $? 在脚本最后一条命令后立即读取，避免沿用更早的外部命令退出码。
   return `[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)
@@ -42,6 +80,13 @@ export function shellInvocation(script,{shell='auto',platform=process.platform}=
 export async function runShell(script,{shell='auto',runProcess:execute=executeProcess,temporaryDir=tmpdir(),...processOptions}={}){
   const file=selectShell(script,shell,process.platform),powershell=file==='powershell'||file==='pwsh';
   if(processOptions.signal?.aborted)throw new FlowError('操作已取消',{code:'CANCELLED'});
+  if(process.platform==='win32'&&shell==='auto'){
+    const args=ipconfigArguments(script),windowsRoot=process.env.SystemRoot??process.env.windir;
+    if(args&&windowsRoot&&path.isAbsolute(windowsRoot)){
+      const encoding=processOptions.encoding??await ipconfigEncoding(windowsRoot,processOptions);
+      if(encoding)return execute(path.join(windowsRoot,'System32','ipconfig.exe'),args,{...processOptions,encoding,commandText:script});
+    }
+  }
   const directory=path.resolve(temporaryDir);
   await mkdir(directory,{recursive:true});
   const scriptFile=path.join(directory,`fst-shell-${randomUUID()}.${powershell?'ps1':'sh'}`);
@@ -53,6 +98,6 @@ export async function runShell(script,{shell='auto',runProcess:execute=executePr
       await handle.writeFile(powershell?'\uFEFF'+powerShellSource(script):script,'utf8');
     }finally{await handle.close();}
     const args=powershell?[...powerShellArgs,'-ExecutionPolicy','Bypass','-File',scriptFile]:[scriptFile];
-    return await execute(file,args,processOptions);
+    return await execute(file,args,{...processOptions,commandText:script});
   }finally{await rm(scriptFile,{force:true});}
 }

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

@@ -18,7 +18,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-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,37 +2,32 @@ 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} 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;
   validateNetworkPolicy(currentNetwork());
   const ctx = new Context();
   const actions = new Map();
-  const definitions = new Map();
+  const definitions = validatePluginDefinitions(plugins);
   const extensions = new Map();
-  const serviceNames = new Set();
-  const commandNames=new Set(),commands=new Map();
+  const commands=new Map();
   function bindContext(context){
     const {application:ignored,...capabilities}=services;
     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,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){
@@ -48,6 +43,7 @@ export async function createHost({ plugins = [], config = {}, services = {}, pro
     const stateDir=projectDir&&!readOnly?path.join(projectDir,'.flow','plugin-state',createHash('sha256').update(plugin.id).digest('hex')):undefined;
     if(stateDir)await mkdir(stateDir,{recursive:true});
     for(const message of platformWarnings(plugin))await bound.log?.(message,{code:'PLATFORM_MISMATCH'},{audience:'user'});
+    if(plugin.root)await bound.log?.('插件文件目录',{plugin:plugin.id,directory:plugin.root},{kind:'source'});
     const environments=await prepareEnvironments(plugin,action,environmentOverrides[plugin.id],{cwd:projectDir??process.cwd()});
     context.signal?.throwIfAborted();
     const policy=context.networkPolicy??currentNetwork();
@@ -75,26 +71,8 @@ export async function createHost({ plugins = [], config = {}, services = {}, pro
     if(result.status==='unknown')await context.log?.('权限状态未确认，按本次选择继续运行',{plugin:plugin.id,action:actionName,reason:result.reason},{audience:'user'});
     return requirement;
   }
-  for (const entry of plugins) {
-    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} 缺少执行函数`);
-    }
-    for(const [name,extension] of Object.entries(plugin.services??{})){
-      if(serviceNames.has(name))throw new FlowError(`服务重复：${name}`);
-      if(typeof extension!=='function')throw new FlowError(`服务 ${name} 缺少执行函数`);
-      serviceNames.add(name);
-    }
-    definitions.set(plugin.id, {...plugin, root:entry.root});
-  }
   const settingsById=new Map();
   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'});
-    }
     const settings = validate(plugin.config, config[plugin.id] ?? {}, `${plugin.id} 配置`);
     settingsById.set(plugin.id,settings);
   }
@@ -176,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}`);
@@ -185,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{
@@ -204,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{
@@ -233,3 +217,42 @@ export async function createHost({ plugins = [], config = {}, services = {}, pro
     close:()=>runtime.close(),
   };
 }
+
+// 单插件契约检查不依赖其他插件，供启动恢复路径精确归属故障。
+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;
+    if(!plugin.id||definitions.has(plugin.id))throw new FlowError(`插件标识缺失或重复：${plugin.id}`,{code:'VALIDATION'});
+    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'});
+      serviceNames.add(name);
+    }
+    definitions.set(plugin.id,{...plugin,root:entry.root});
+  }
+  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(new Map([...definitions].filter(([id])=>!unavailable.has(id))),new Context(),{blocked});
+  return definitions;
+}