@yanglaofish/fishtools 0.4.0 → 0.5.1

package/node_modules/@mytools/fst-logs/src/markdown-log.js

@@ -0,0 +1,55 @@
+const names={
+  'run.started':'运行开始','run.succeeded':'运行成功','run.failed':'运行失败','run.cancelled':'运行取消','run.stopped':'运行停止',
+  'workflow.started':'工作流开始','workflow.succeeded':'工作流完成','workflow.stopped':'工作流停止',
+  'step.started':'步骤开始','step.succeeded':'步骤成功','step.failed':'步骤失败','step.cancelled':'步骤取消','step.skipped':'步骤跳过','step.stopped':'步骤停止',log:'插件日志',
+};
+const statuses={running:'运行中',succeeded:'成功',failed:'失败',cancelled:'已取消',stopped:'已停止'};
+
+// 用长于正文的围栏包裹插件文本，避免错误消息中的 Markdown 改写日志结构。
+function block(value,language='text'){
+  const text=typeof value==='string'?value:JSON.stringify(value,null,2)??String(value);
+  let longest=2;for(const match of text.matchAll(/`+/g))longest=Math.max(longest,match[0].length);
+  const fence='`'.repeat(longest+1);
+  return `${fence}${language}\n${text}\n${fence}\n\n`;
+}
+
+function errorText(error){
+  let output='',depth=0;
+  for(let current=error;current;current=current.cause){
+    const lines=[];
+    for(const [key,label] of [['plugin','插件'],['action','动作'],['command','命令'],['code','错误码'],['message','原因']]){
+      if(current[key]!==undefined)lines.push(`${label}：${current[key]}`);
+    }
+    output+=`#### ${depth++?'原始错误':'错误信息'}\n\n`+block(lines.join('\n'));
+    if(current.details!==undefined)output+='详情：\n\n'+block(current.details,'json');
+    if(current.stack)output+='调用栈：\n\n'+block(current.stack);
+  }
+  return output;
+}
+
+export function markdownHeader(run){
+  return '# Fishtools 运行日志\n\n'+block(`运行 ID：${run.id}\n工作流或命令：${run.workflowId}\n开始时间：${run.startedAt}`)+'## 执行过程\n\n';
+}
+
+export function markdownEvent(event){
+  let output=`### ${event.type==='log'&&event.audience==='user'?'用户输出':names[event.type]??'事件'}\n\n`;
+  const lines=[`时间：${event.time}`];
+  for(const [key,label] of [['callPath','调用路径'],['action','动作'],['plugin','插件'],['command','命令'],['stream','输出流'],['durationMs','耗时（毫秒）']]){
+    if(event[key]!==undefined)lines.push(`${label}：${event[key]}`);
+  }
+  output+=block(lines.join('\n'));
+  if(event.message)output+=block(event.message);
+  if(event.reason!==undefined)output+='停止或跳过原因：\n\n'+block(event.reason);
+  if(event.data!==undefined)output+='附加信息：\n\n'+block(event.data,'json');
+  if(event.input!==undefined)output+='步骤输入：\n\n'+block(event.input,'json');
+  if(event.output!==undefined)output+='步骤输出：\n\n'+block(event.output,'json');
+  if(event.error)output+=errorText(event.error);
+  return output;
+}
+
+export function markdownResult(run){
+  let output='## 最终结果\n\n'+block(`状态：${statuses[run.status]??run.status}\n结束时间：${run.finishedAt}`);
+  if(run.reason!==undefined)output+='停止原因：\n\n'+block(run.reason);
+  if(run.output!==undefined)output+=block(run.output,'json');
+  return output;
+}

package/node_modules/@mytools/fst-logs/src/run-logs.js

@@ -0,0 +1,224 @@
+import path from 'node:path';
+import {readdir,readFile,lstat,unlink,rmdir,mkdir,writeFile,appendFile,open} from 'node:fs/promises';
+import {FlowError} from '@mytools/sdk';
+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';
+
+const validId=id=>typeof id==='string'&&/^[a-f0-9-]{36}$/.test(id);
+const logFiles=['run.md','events.jsonl','result.json','run.meta.json'];
+function pageBuffer(buffer,offset,limit,cursor=offset,totalBytes=buffer.length){
+  if(offset>buffer.length)throw new FlowError('日志 cursor 超过正文长度',{code:'LOG_CURSOR_INVALID'});
+  if(offset<buffer.length&&(buffer[offset]&0xc0)===0x80)throw new FlowError('日志 cursor 必须位于 UTF-8 字符边界',{code:'LOG_CURSOR_INVALID'});
+  let end=Math.min(offset+limit,buffer.length);
+  if(end<buffer.length)while(end>offset&&(buffer[end]&0xc0)===0x80)end--;
+  const text=buffer.subarray(offset,end).toString('utf8'),nextCursor=cursor+end-offset;
+  return {text,cursor,nextCursor,hasMore:nextCursor<totalBytes,totalBytes};
+}
+export function validateKeepRuns(value){
+  if(value!==null&&(!Number.isSafeInteger(value)||value<1))throw new FlowError('日志保留次数必须为正整数；null 表示不自动清理');
+  return value;
+}
+
+export function createRunLogs(directory,{projectDir,allowLegacy=false,...options}){
+  const root=path.resolve(directory);let cleaning=Promise.resolve();
+  const policy=logPolicy(options),metadataLimit=Math.max(2*1024*1024,2*policy.maxMemoryBytes+8*policy.maxEventBytes+65536);
+  const owner=process.platform==='win32'?path.resolve(projectDir).toLowerCase():path.resolve(projectDir);
+  function location(id){if(!validId(id))throw new FlowError('运行 ID 无效');return path.join(root,id);}
+  async function regular(file){try{return (await lstat(file)).isFile();}catch(error){if(error.code==='ENOENT')return false;throw error;}}
+  async function safeDirectory(id){
+    const stat=await lstat(root);if(!stat.isDirectory()||stat.isSymbolicLink())throw new FlowError('日志根目录无效');
+    const dir=location(id),child=await lstat(dir);if(!child.isDirectory()||child.isSymbolicLink())throw new FlowError('日志目录无效');
+    return dir;
+  }
+  async function safeFile(file){
+    const before=await lstat(file);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;}
+    catch(error){await handle.close();throw error;}
+  }
+  async function read(id){
+    const dir=await safeDirectory(id);
+    let file=path.join(dir,'result.json');
+    try{await lstat(file);}catch(error){if(error.code!=='ENOENT')throw error;file=path.join(dir,'run.meta.json');}
+    if(!await regular(file))throw new FlowError('运行记录不存在');
+    const handle=await safeFile(file);let result;
+    try{
+      const stat=await handle.stat();if(stat.size>metadataLimit)throw new FlowError('运行记录元数据超过读取预算',{code:'LOG_METADATA_LIMIT'});
+      // 读固定预算，文件在检查后增长也不会形成无限内存读取。
+      const buffer=Buffer.alloc(Math.min(stat.size+1,metadataLimit+1)),{bytesRead}=await handle.read(buffer,0,buffer.length,0);
+      if(bytesRead>metadataLimit)throw new FlowError('运行记录元数据超过读取预算',{code:'LOG_METADATA_LIMIT'});
+      result=JSON.parse(buffer.subarray(0,bytesRead).toString('utf8'));
+    }finally{await handle.close();}
+    if(result.id!==id)throw new FlowError('运行记录 ID 不匹配');
+    if(result.logOwner!==owner&&!(allowLegacy&&result.logOwner===undefined))throw new FlowError('运行记录不属于此项目');
+    return result;
+  }
+  async function list(){
+    let entries;try{const stat=await lstat(root);if(!stat.isDirectory()||stat.isSymbolicLink())throw new FlowError('日志根目录无效');entries=await readdir(root,{withFileTypes:true});}catch(error){if(error.code==='ENOENT')return [];throw error;}
+    const results=[];
+    for(const entry of entries){
+      if(!entry.isDirectory()||!validId(entry.name))continue;
+      try{
+        const record=await read(entry.name);
+        if(typeof record.workflowId==='string'&&['succeeded','failed','cancelled','stopped'].includes(record.status)&&Number.isFinite(Date.parse(record.finishedAt)))results.push(record);
+      }catch(error){if(error.code==='EACCES'||error.code==='EPERM')throw error;}
+    }
+    return results.sort((a,b)=>Date.parse(b.finishedAt)-Date.parse(a.finishedAt)||b.id.localeCompare(a.id));
+  }
+  return {
+    list,read,owner,policy:Object.freeze({...policy}),
+    async start(initial,{onEvent=()=>{}}={}){
+      const directory=location(initial.id),events=[],sizes=[],steps=createStepSummaries(policy);
+      await mkdir(root,{recursive:true});
+      const rootStat=await lstat(root);if(!rootStat.isDirectory()||rootStat.isSymbolicLink())throw new FlowError('日志根目录无效');
+      await mkdir(directory,{recursive:true});
+      await safeDirectory(initial.id);
+      for(const name of logFiles){try{await lstat(path.join(directory,name));throw new FlowError('运行日志已存在，拒绝覆盖');}catch(error){if(error.code!=='ENOENT')throw error;}}
+      const markdownFile=path.join(directory,'run.md');
+      let writes=Promise.resolve(),failure=null,pendingBytes=0,diskBytes=0,resultBytes=0,eventCount=0,eventBytes=2,eventsTruncated=false,finished=false;
+      const snapshot=state=>structuredClone({...initial,...state,logOwner:owner,events,eventCount,eventBytes,eventsTruncated,...steps.snapshot()});
+      const reject=error=>{failure??=error;const promise=Promise.reject(failure);promise.catch(()=>{});return promise;};
+      function diskCheck(extra){if(policy.maxDiskBytes!==null&&diskBytes+extra>policy.maxDiskBytes)throw new FlowError('日志磁盘预算已满',{code:'LOG_DISK_LIMIT',details:{maxDiskBytes:policy.maxDiskBytes}});}
+      const queue=(bytes,operation)=>{
+        if(failure)return reject(failure);
+        if(pendingBytes+bytes>policy.maxPendingBytes)return reject(new FlowError('日志待写队列超过字节预算',{code:'LOG_QUEUE_LIMIT',details:{maxPendingBytes:policy.maxPendingBytes}}));
+        pendingBytes+=bytes;
+        const job=writes.then(operation).catch(error=>{failure??=error;throw error;}).finally(()=>{pendingBytes-=bytes;});
+        writes=job;
+        // 调用方仍收到失败；同时防止未 await 的插件日志产生未处理拒绝。
+        writes.catch(()=>{});return writes;
+      };
+      function retain(full){
+        const event=eventPreview(full,policy.maxEventBytes),size=Buffer.byteLength(JSON.stringify(event));
+        eventCount++;eventsTruncated ||= event.eventTruncated===true;
+        events.push(event);sizes.push(size);eventBytes+=size+(events.length>1?1:0);
+        while(events.length>policy.maxEvents||eventBytes>policy.maxMemoryBytes){
+          const removed=sizes.shift();events.shift();eventBytes-=removed+(events.length?1:0);eventsTruncated=true;
+        }
+        steps.append(full);
+        onEvent(structuredClone(event));
+      }
+      function metadata(state){
+        const run=previewRun({...initial,...state,logOwner:owner,events,eventCount,eventBytes,eventsTruncated,...steps.snapshot()},{maxValueBytes:policy.maxEventBytes});
+        const text=JSON.stringify(run);
+        if(Buffer.byteLength(text)>metadataLimit)throw new FlowError('运行记录元数据超过写入预算',{code:'LOG_METADATA_LIMIT'});
+        return text;
+      }
+      async function saveText(text){
+        const bytes=Buffer.byteLength(text);diskCheck(bytes-resultBytes);
+        await rejectLink(path.join(directory,'result.json'));
+        await safeDirectory(initial.id);
+        await writeFile(path.join(directory,'result.json'),text);diskBytes+=bytes-resultBytes;resultBytes=bytes;
+      }
+      async function rejectLink(file){try{if((await lstat(file)).isSymbolicLink())throw new FlowError('日志文件无效');}catch(error){if(error.code!=='ENOENT')throw error;}}
+      async function appendText(json,markdown){
+        const bytes=Buffer.byteLength(json)+Buffer.byteLength(markdown);diskCheck(bytes);
+        await safeDirectory(initial.id);await rejectLink(path.join(directory,'events.jsonl'));await rejectLink(markdownFile);
+        await appendFile(path.join(directory,'events.jsonl'),json);await appendFile(markdownFile,markdown);diskBytes+=bytes;
+      }
+      const header=markdownHeader(initial);diskCheck(Buffer.byteLength(header));
+      // 独占创建，拒绝覆盖旧日志和文件链接。
+      await writeFile(markdownFile,header,{flag:'wx'});diskBytes+=Buffer.byteLength(header);
+      const ownership=JSON.stringify({id:initial.id,workflowId:initial.workflowId,startedAt:initial.startedAt,status:'running',logOwner:owner});
+      diskCheck(Buffer.byteLength(ownership));await writeFile(path.join(directory,'run.meta.json'),ownership,{flag:'wx'});diskBytes+=Buffer.byteLength(ownership);
+      return {
+        directory,snapshot,
+        markdown:state=>markdownHeader({...initial,...state})+events.map(markdownEvent).join(''),
+        append(event){
+          if(finished)return reject(new FlowError('日志已经完成',{code:'LOG_CLOSED'}));
+          if(failure)return reject(failure);
+          try{
+            const full={time:new Date().toISOString(),...event,runId:initial.id,seq:eventCount+1};
+            if(jsonSize(full,policy.maxPendingBytes)>policy.maxPendingBytes)throw new FlowError('单条日志超过待写字节预算',{code:'LOG_QUEUE_LIMIT'});
+            const json=JSON.stringify(full)+'\n',markdown=markdownEvent(full),bytes=Buffer.byteLength(json)+Buffer.byteLength(markdown);
+            if(pendingBytes+bytes>policy.maxPendingBytes)throw new FlowError('日志待写队列超过字节预算',{code:'LOG_QUEUE_LIMIT'});
+            retain(full);return queue(bytes,()=>appendText(json,markdown));
+          }catch(error){return reject(error);}
+        },
+        finish(state){
+          if(failure)return reject(failure);
+          if(finished)return reject(new FlowError('日志已经完成',{code:'LOG_CLOSED'}));
+          try{
+            const full={...state,time:new Date().toISOString(),runId:initial.id,type:'run.result',seq:eventCount+1};
+            if(jsonSize(full,policy.maxPendingBytes)>policy.maxPendingBytes)throw new FlowError('最终结果超过待写字节预算',{code:'LOG_QUEUE_LIMIT'});
+            const json=JSON.stringify(full)+'\n',markdown=markdownResult({...initial,...state}),bytes=Buffer.byteLength(json)+Buffer.byteLength(markdown);
+            if(pendingBytes+bytes>policy.maxPendingBytes)throw new FlowError('日志待写队列超过字节预算',{code:'LOG_QUEUE_LIMIT'});
+            // 最终业务结果已由快照提供；JSONL 补充完整记录，不重复广播到插件事件预览。
+            eventCount++;finished=true;
+            return queue(bytes,async()=>{const text=metadata(state);diskCheck(bytes+Buffer.byteLength(text)-resultBytes);await appendText(json,markdown);await saveText(text);});
+          }catch(error){return reject(error);}
+        },
+        save(state){try{const text=metadata(state);return queue(Buffer.byteLength(text),()=>saveText(text));}catch(error){return reject(error);}},
+      };
+    },
+    async usage(){
+      const report={directory:root,bytes:0,files:0,incomplete:false};
+      let entries;
+      try{
+        const stat=await lstat(root);
+        if(!stat.isDirectory()||stat.isSymbolicLink()){report.incomplete=true;return report;}
+        entries=await readdir(root,{withFileTypes:true});
+      }
+      catch(error){if(error.code!=='ENOENT')report.incomplete=true;return report;}
+      for(const entry of entries){
+        if(!entry.isDirectory()||!/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(entry.name))continue;
+        const dir=location(entry.name);
+        try{
+          const stat=await lstat(dir);if(!stat.isDirectory()||stat.isSymbolicLink())continue;
+          // 只计约定的日志文件，不读内容、不递归遍历业务目录、不跟随文件链接。
+          for(const name of logFiles){
+            try{const file=await lstat(path.join(dir,name));if(file.isFile()){report.bytes+=file.size;report.files++;}}
+            catch(error){if(error.code!=='ENOENT')report.incomplete=true;}
+          }
+        }catch(error){if(error.code!=='ENOENT')report.incomplete=true;}
+      }
+      return report;
+    },
+    async markdown(id){
+      const dir=location(id);const stat=await lstat(dir);if(!stat.isDirectory()||stat.isSymbolicLink())throw new FlowError('日志目录无效');
+      const run=await read(id),file=path.join(dir,'run.md');if(await regular(file))return readFile(file,'utf8');
+      return markdownHeader(run)+(run.events??[]).map(markdownEvent).join('')+markdownResult(run);
+    },
+    async page(id,{cursor=0,limit=65536}={}){
+      if(!Number.isSafeInteger(cursor)||cursor<0)throw new FlowError('日志 cursor 必须为非负整数字节位置',{code:'LOG_CURSOR_INVALID'});
+      if(!Number.isSafeInteger(limit)||limit<4)throw new FlowError('日志 limit 必须为至少 4 的正整数');
+      limit=Math.min(limit,256*1024);
+      const dir=await safeDirectory(id),run=await read(id),file=path.join(dir,'run.md');
+      let handle;
+      try{handle=await safeFile(file);}catch(error){
+        if(error.code!=='ENOENT')throw error;
+        const buffer=Buffer.from(markdownHeader(run)+(run.events??[]).map(markdownEvent).join('')+markdownResult(run));
+        return pageBuffer(buffer,cursor,limit);
+      }
+      try{
+        const totalBytes=(await handle.stat()).size;
+        if(cursor>totalBytes)throw new FlowError('日志 cursor 超过正文长度',{code:'LOG_CURSOR_INVALID'});
+        const buffer=Buffer.alloc(Math.min(limit+1,totalBytes-cursor));
+        let offset=0;
+        while(offset<buffer.length){const {bytesRead}=await handle.read(buffer,offset,buffer.length-offset,cursor+offset);if(!bytesRead)break;offset+=bytesRead;}
+        return pageBuffer(buffer.subarray(0,offset),0,limit,cursor,totalBytes);
+      }finally{await handle.close();}
+    },
+    prune(keepRuns,protectedIds){
+      const job=cleaning.then(async()=>{
+        if(keepRuns===null)return [];
+        validateKeepRuns(keepRuns);
+        const ended=await list(),removed=[];
+        for(const run of ended.slice(keepRuns)){
+          if(protectedIds.has(run.id))continue;
+          const dir=location(run.id);
+          // 只删除本工具约定的四个日志文件；不递归删除目录或插件生成的业务结果。
+          for(const name of logFiles){
+            const file=path.join(dir,name);
+            if(await regular(file))try{await unlink(file);}catch(error){if(error.code!=='ENOENT')throw error;}
+          }
+          try{await rmdir(dir);}catch(error){if(!['ENOTEMPTY','EEXIST','ENOENT'].includes(error.code))throw error;}
+          removed.push(run.id);
+        }
+        return removed;
+      });cleaning=job.catch(()=>{});return job;
+    },
+  };
+}

package/node_modules/@mytools/fst-logs/src/run-preview.js

@@ -0,0 +1,18 @@
+import {FlowError} from '@mytools/sdk';
+import {defaults,preview,jsonSize} from './log-bounds.js';
+
+const retainedFields=new Set(['events','stepSummaries','id','workflowId','logOwner','status','startedAt','finishedAt']);
+
+// 路由信息与已有独立预算的缓存保留；业务正文和诊断字段只投影有界预览。
+export function previewRun(record,{maxValueBytes=defaults.maxEventBytes}={}){
+  if(!Number.isSafeInteger(maxValueBytes)||maxValueBytes<2)throw new FlowError('结果预览 maxValueBytes 必须为至少 2 的整数字节数');
+  const run={...record};
+  for(const key of Object.keys(run)){
+    if(retainedFields.has(key)||run[key]===undefined)continue;
+    const bounded=preview(run[key],maxValueBytes);
+    if(jsonSize(bounded.value,maxValueBytes)>maxValueBytes)delete run[key];
+    else run[key]=bounded.value;
+    if(bounded.truncated)run[`${key}Truncated`]=true;
+  }
+  return run;
+}

package/node_modules/@mytools/fst-logs/src/step-summaries.js

@@ -0,0 +1,28 @@
+import {logPolicy,eventPreview} from './log-bounds.js';
+
+// 日志写入器与展示端共用轻量摘要，避免各端重新缓存业务 input/output。
+export function createStepSummaries(options={}){
+  const policy=logPolicy(options),steps=new Map();
+  let bytes=2,truncated=false;
+  return {
+    append(full){
+      if(typeof full.type!=='string'||!full.type.startsWith('step.')||(full.callPath===undefined&&full.stepId===undefined))return;
+      const lightweight={};
+      for(const key of ['type','callPath','stepId','action','time','seq','durationMs','reason','error'])if(full[key]!==undefined)lightweight[key]=full[key];
+      const summary=eventPreview(lightweight,policy.maxEventBytes),key=summary.callPath??summary.stepId;
+      if(key===undefined||summary.callPath!==full.callPath||summary.stepId!==full.stepId){truncated=true;return;}
+      const previous=steps.get(key);
+      if(previous){steps.delete(key);bytes-=previous.bytes+(steps.size?1:0);}
+      const size=Buffer.byteLength(JSON.stringify(summary));
+      steps.set(key,{event:summary,bytes:size});bytes+=size+(steps.size>1?1:0);
+      while(steps.size>policy.maxEvents||bytes>policy.maxMemoryBytes){
+        const oldest=steps.keys().next().value,removed=steps.get(oldest);
+        steps.delete(oldest);bytes-=removed.bytes+(steps.size?1:0);truncated=true;
+      }
+    },
+    get size(){return steps.size;},
+    get(key){return structuredClone(steps.get(key)?.event);},
+    values(){return [...steps.values()].map(entry=>structuredClone(entry.event));},
+    snapshot(){return {stepSummaries:this.values(),stepSummaryBytes:bytes,stepsTruncated:truncated};},
+  };
+}

package/node_modules/@mytools/fst-platform/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mytools contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -0,0 +1,73 @@
+# 平台模块
+
+包名：`@mytools/fst-platform`。内部 workspace 包，随 `@yanglaofish/fishtools` 统一交付。
+
+## 职责与边界
+
+进程调用、环境解析、JSON 文件读取、npm 和产物完整性检查。日志留存策略由 logs 负责，项目状态由 workspace 负责。
+
+内部依赖：`@mytools/sdk`。
+## 公开入口
+
+| 导入路径 | 实现位置 |
+| --- | --- |
+| `@mytools/fst-platform` | `./src/process.js` |
+| `@mytools/fst-platform/environments` | `./src/environments.js` |
+| `@mytools/fst-platform/bundle` | `./src/bundle.js` |
+| `@mytools/fst-platform/json` | `./src/json.js` |
+| `@mytools/fst-platform/npm` | `./src/npm.js` |
+| `@mytools/fst-platform/network` | `./src/network.js` |
+| `@mytools/fst-platform/fs` | `./src/file-probe.js` |
+| `@mytools/fst-platform/package.json` | `./package.json` |
+
+仅依赖 exports 声明的入口，禁止消费者跨包读取 src/bin 私有文件。入口路径由本模块维护，修改协议时同步消费方回归。
+
+## 维护与验证
+
+本模块负责上述职责的实现、文档与回归；跨模块接口调整需要同时检查生产者与消费者。具体维护人员尚未指定。
+
+在仓库根目录执行：
+
+```sh
+node --test tests/modules.test.js tests/process.test.js tests/environments.test.js
+```
+
+## 子进程环境
+
+`runProcess(file,args,{env,extendEnv=true})` 默认把 `env` 覆盖到宿主环境上。
+当调用方已按动作代理规则构造完整环境时，传 `extendEnv:false`，防止已移除的代理变量被重新继承。
+
+## 隔离文件探测
+
+`createFileProbe({timeout=2000,maxConcurrent=2,maxPending=16,allowRemote=false})` 创建只读探测器。
+`stat(path,{signal,timeout})` 和 `readDirectory(path,{signal,timeout,limit=1000})` 把实际 I/O 放入独立 Node 子进程。
+超时从接收请求开始计时，包含排队；并发和排队预算满时返回 `error`，错误码为 `PROBE_BUSY`。
+Windows 子进程使用 `windowsHide`，不会启动可见窗口。
+
+每个结果都有 `status` 和 `incomplete`。状态为 `ok/missing/timedOut/cancelled/skipped/error`；非成功结果附 `reason`，错误结果还附 `{code,message}`。
+`stat` 使用 `lstat`，不追踪符号链接；成功的 `value` 包含 `{type,size,mtimeMs,ctimeMs,birthtimeMs,mode}`，
+其中 `type` 为 `file/directory/symlink/other`。目录成功的 `value` 为 `[{name,type}]`；顺序取决于文件系统。
+目录只列一级、不读文件正文；达到条目上限且仍有条目时返回 `incomplete:true,reason:'entryLimit'`。
+`limit` 必须为 1 到 10000 的整数，所有容量和超时参数必须是有限整数。
+
+显式 UNC 和网络设备路径默认返回 `skipped`，原因 `remotePath`；Windows 扩展本地路径仍可探测。
+普通挂载不根据路径字符串推测位置，由子进程超时约束。允许远端探测时设 `allowRemote:true`。
+这提供响应时间和资源预算约束，底层内核 I/O 仍可能无法立即回收，不构成安全沙箱。
+
+`status()` 返回 `{closed,active,pending,unreaped,maxConcurrent,maxPending}`；超时或取消的 worker 在确认退出前仍计入 `active` 和 `unreaped`。
+`close()` 取消当前和排队请求，尝试终止进程，最多等待 250 ms；返回 `{closed:true,incomplete,unreaped}`。
+关闭后拒绝新请求；关闭报告中的未回收数为关闭等待结束时的快照，后续实际状态可通过 `status()` 查询。
+
+```js
+import { createFileProbe } from '@mytools/fst-platform/fs';
+const fs = createFileProbe();
+try {
+  const result = await fs.readDirectory('.', { limit: 100 });
+  if (result.status === 'ok') console.log(result.value, result.incomplete);
+} finally {
+  const closed = await fs.close();
+  if (closed.incomplete) console.error('仍有未回收探测进程', closed.unreaped);
+}
+```
+
+定向验证：`node --test tests/file-probe.test.js`。阻塞 fixture 使用真实子进程同步等待，并验证终止失败后预算不会被释放。

package/node_modules/@mytools/fst-platform/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@mytools/fst-platform",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/process.js",
+  "exports": {
+    ".": "./src/process.js",
+    "./environments": "./src/environments.js",
+    "./bundle": "./src/bundle.js",
+    "./json": "./src/json.js",
+    "./npm": "./src/npm.js",
+    "./fs": "./src/file-probe.js",
+    "./network": "./src/network.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "dependencies": {
+    "@mytools/sdk": "0.1.0",
+    "execa": "10.1.0",
+    "tree-kill": "1.2.2",
+    "undici": "^8.4.1",
+    "which": "7.0.0"
+  }
+}

package/node_modules/@mytools/fst-platform/src/bundle.js

@@ -0,0 +1,17 @@
+import { createHash } from 'node:crypto';
+import { readFile, realpath } from 'node:fs/promises';
+import path from 'node:path';
+
+export async function verifyBundle(root){
+  root=await realpath(root);
+  const manifest=JSON.parse(await readFile(path.join(root,'manifest.json'),'utf8'));
+  const errors=[];
+  for(const [relative,expected] of Object.entries(manifest.files??{})){
+    const file=path.resolve(root,relative);
+    try{
+      if(!file.startsWith(root+path.sep)||!(await realpath(file)).startsWith(root+path.sep))throw new Error('路径越界');
+      if(createHash('sha256').update(await readFile(file)).digest('hex')!==expected)errors.push(relative);
+    }catch{errors.push(relative);}
+  }
+  return {ok:errors.length===0,errors};
+}

package/node_modules/@mytools/fst-platform/src/environments.js

@@ -0,0 +1,67 @@
+import path from 'node:path';
+import {FlowError} from '@mytools/sdk';
+import which from 'which';
+
+export const currentTarget=()=>`${process.platform}-${process.arch}${process.platform==='linux'?'-glibc':''}`;
+export function inside(root,relative){
+  if(typeof relative!=='string'||!relative||path.isAbsolute(relative)||/^[A-Za-z]:|\\/.test(relative))throw new FlowError(`资源路径必须是包内相对路径：${relative}`);
+  const absolute=path.resolve(root,relative),rel=path.relative(root,absolute);
+  if(rel==='..'||rel.startsWith('..'+path.sep)||path.isAbsolute(rel))throw new FlowError(`资源路径越界：${relative}`);
+  return absolute;
+}
+export function environmentDeclarations(plugin,action){return {...plugin.environments,...action?.environments};}
+export function resolveEnvironments(plugin,action,overrides={},target=currentTarget()){
+  return Object.fromEntries(Object.entries(environmentDeclarations(plugin,action)).map(([id,declaration])=>{
+    const selected=overrides[id];
+    if(selected!==undefined&&(!selected||typeof selected!=='object'||Array.isArray(selected)||Object.keys(selected).some(k=>!['source','executable'].includes(k))||selected.source!==undefined&&typeof selected.source!=='string'||selected.executable!==undefined&&(typeof selected.executable!=='string'||!selected.executable.trim())))throw new FlowError(`环境来源覆盖无效：${plugin.id}/${id}`);
+    const source=selected?.source??declaration.source;
+    if(!(declaration.allowedSources??[declaration.source]).includes(source))throw new FlowError(`环境 ${plugin.id}/${id} 不允许来源 ${source}`);
+    const e={...declaration,source};delete e.artifacts;
+    if(selected?.executable!==undefined){
+      if(source!=='host')throw new FlowError(`只有 host 环境允许覆盖解释器：${plugin.id}/${id}`);
+      e.executable=selected.executable;
+    }
+    if(source==='tool'){
+      if(id!=='node')throw new FlowError(`工具尚未提供环境：${id}`);
+      e.executable=process.execPath;
+    }else if(source==='bundled'){
+      const artifact=declaration.artifacts?.[target];
+      if(!artifact)throw new FlowError(`环境 ${plugin.id}/${id} 未提供 ${target} 的随包资源`);
+      e.root=inside(plugin.root,artifact.directory);e.executable=inside(e.root,artifact.executable);
+    }
+    return [id,e];
+  }));
+}
+
+// 打包只解析声明；真正调用时才在当前工作区选择候选，避免将开发机路径写入跨平台分发包。
+export async function prepareEnvironments(plugin,action,overrides={}, {cwd=process.cwd()}={}){
+  const resolved=resolveEnvironments(plugin,action,overrides);
+  for(const [id,environment] of Object.entries(resolved)){
+    if(environment.source!=='host'||!Array.isArray(environment.executable)&&overrides[id]?.executable===undefined)continue;
+    const candidates=Array.isArray(environment.executable)?environment.executable:[environment.executable];
+    const windows=process.platform==='win32',directory=path.resolve(cwd);
+    const searchDirectories=[...(windows?[directory]:[]),...(process.env.PATH??'').split(path.delimiter)]
+      .map(entry=>path.resolve(directory,entry.replace(/^"(.*)"$/,'$1')));
+    let found;
+    for(const candidate of candidates){
+      const direct=path.isAbsolute(candidate)||candidate.includes('/')||windows&&candidate.includes('\\');
+      // 使用绝对候选，防止 which 在 Windows 擅自优先搜索宿主启动目录。
+      const paths=direct?[path.resolve(directory,candidate)]:searchDirectories.map(base=>path.resolve(base,candidate));
+      for(const executable of paths){
+        found=await which(executable,{nothrow:true});
+        if(found)break;
+      }
+      if(found)break;
+    }
+    if(!found)throw new FlowError(`环境 ${plugin.id}/${id} 未找到程序：${candidates.join('、')}`,{code:'ENOENT',details:{plugin:plugin.id,environment:id,candidates}});
+    environment.executable=path.resolve(found);
+  }
+  return resolved;
+}
+
+export function platformWarnings(plugin,platform=process.platform,architecture=process.arch){
+  const warnings=[];
+  if(plugin.platforms&&!plugin.platforms.includes(platform))warnings.push(`插件 ${plugin.id} 的平台声明不包含当前 ${platform}，继续执行；请核实插件支持范围`);
+  if(plugin.architectures&&!plugin.architectures.includes(architecture))warnings.push(`插件 ${plugin.id} 的架构声明不包含当前 ${architecture}，继续执行；请核实插件支持范围`);
+  return warnings;
+}