@yanglaofish/fishtools 0.3.0 → 0.5.0

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

@@ -0,0 +1,239 @@
+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,preview,eventPreview} from './log-bounds.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=new Map();
+      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,stepSummaryBytes=2,stepsTruncated=false,finished=false;
+      const snapshot=state=>structuredClone({...initial,...state,logOwner:owner,events,eventCount,eventBytes,eventsTruncated,stepSummaries:[...steps.values()].map(entry=>entry.event),stepSummaryBytes,stepsTruncated});
+      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;
+        }
+        if(typeof full.type==='string'&&full.type.startsWith('step.')&&(full.callPath!==undefined||full.stepId!==undefined)){
+          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){
+            const previous=steps.get(key);
+            if(previous){steps.delete(key);stepSummaryBytes-=previous.bytes+(steps.size?1:0);}
+            const bytes=Buffer.byteLength(JSON.stringify(summary));steps.set(key,{event:summary,bytes});stepSummaryBytes+=bytes+(steps.size>1?1:0);
+            while(steps.size>policy.maxEvents||stepSummaryBytes>policy.maxMemoryBytes){
+              const oldest=steps.keys().next().value,removed=steps.get(oldest);steps.delete(oldest);stepSummaryBytes-=removed.bytes+(steps.size?1:0);stepsTruncated=true;
+            }
+          }else stepsTruncated=true;
+        }
+        onEvent(structuredClone(event));
+      }
+      function metadata(state){
+        const run={...initial,...state,logOwner:owner,events,eventCount,eventBytes,eventsTruncated,stepSummaries:[...steps.values()].map(entry=>entry.event),stepSummaryBytes,stepsTruncated};
+        for(const key of Object.keys(run)){
+          if(['events','stepSummaries','id','workflowId','logOwner','status','startedAt','finishedAt'].includes(key))continue;
+          if(run[key]===undefined)continue;
+          const bounded=preview(run[key],policy.maxEventBytes);run[key]=bounded.value;if(bounded.truncated)run[`${key}Truncated`]=true;
+        }
+        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/manual/packages/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/manual/packages/fst-platform/README.md

@@ -0,0 +1,67 @@
+# 平台模块
+
+包名：`@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/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
+```
+
+## 隔离文件探测
+
+`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/manual/packages/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/manual/packages/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/manual/packages/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;
+}

package/manual/packages/fst-platform/src/file-probe-engine.js

@@ -0,0 +1,183 @@
+import { fork } from 'node:child_process';
+
+const workerPath = new URL('./file-probe-worker.js', import.meta.url);
+const MAX_DIRECTORY_ENTRIES = 10000;
+
+function integer(value, name, minimum = 1, maximum = 2147483647) {
+  if (!Number.isSafeInteger(value) || value < minimum || value > maximum) {
+    throw new TypeError(`${name} 必须是 ${minimum} 到 ${maximum} 的整数`);
+  }
+  return value;
+}
+
+function failure(status, reason, error) {
+  return { status, incomplete: true, reason, ...(error ? { error: { code: error.code || 'PROBE_ERROR', message: error.message || String(error) } } : {}) };
+}
+
+function isRemotePath(value) {
+  const normalized = value.replaceAll('/', '\\');
+  // Windows 扩展本地路径仍可探测；显式 UNC 和网络设备路径默认跳过。
+  if (/^\\\\[?.]\\/u.test(normalized)) {
+    return /^\\\\[?.]\\UNC(?:\\|$)/iu.test(normalized)
+      || /^\\\\[?.]\\GLOBALROOT\\Device\\(?:Mup|LanmanRedirector|WebDavRedirector)(?:\\|$)/iu.test(normalized);
+  }
+  return /^\\\\/u.test(normalized)
+    || /^\\(?:\?\?\\UNC|Device\\(?:Mup|LanmanRedirector|WebDavRedirector))(?:\\|$)/iu.test(normalized);
+}
+
+/** 私有运行时边界：测试可使用真实阻塞 worker 和模拟操作系统终止失败。 */
+export function createFileProbeEngine(options = {}, runtime = {}) {
+  const timeout = integer(options.timeout ?? 2000, 'timeout');
+  const maxConcurrent = integer(options.maxConcurrent ?? 2, 'maxConcurrent');
+  const maxPending = integer(options.maxPending ?? 16, 'maxPending', 0);
+  const allowRemote = options.allowRemote ?? false;
+  if (typeof allowRemote !== 'boolean') throw new TypeError('allowRemote 必须为布尔值');
+  const closeTimeout = runtime.closeTimeout ?? 250;
+  const terminate = runtime.terminate ?? (child => child.kill('SIGKILL'));
+  const active = new Set();
+  const pending = [];
+  const closeWaiters = new Set();
+  let closed = false;
+  let closing;
+
+  function status() {
+    return { closed, active: active.size, pending: pending.length,
+      unreaped: [...active].filter(record => record.unreaped).length, maxConcurrent, maxPending };
+  }
+
+  function finish(request, result) {
+    if (request.finished) return;
+    request.finished = true;
+    clearTimeout(request.timer);
+    request.signal?.removeEventListener('abort', request.onAbort);
+    const index = pending.indexOf(request);
+    if (index !== -1) pending.splice(index, 1);
+    request.resolve(result);
+  }
+
+  function stop(record) {
+    if (!active.has(record)) return;
+    record.unreaped = true;
+    try { terminate(record.child); } catch { /* 退出事件到达前继续占预算。 */ }
+  }
+
+  function drain() {
+    while (!closed && active.size < maxConcurrent && pending.length) {
+      start(pending.shift());
+    }
+  }
+
+  function release(record) {
+    if (!active.delete(record)) return;
+    if (!record.request.finished) {
+      finish(record.request, failure('error', 'workerExited', { code: 'PROBE_WORKER_EXIT', message: '文件探测进程未返回结果即退出' }));
+    }
+    drain();
+    if (closed && active.size === 0) for (const notify of closeWaiters) notify();
+  }
+
+  function start(request) {
+    if (request.finished) return;
+    let child;
+    try {
+      child = fork(runtime.workerPath ?? workerPath, [], {
+        execPath: runtime.execPath ?? process.execPath,
+        execArgv: [], windowsHide: true,
+        stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+      });
+    } catch (error) {
+      finish(request, failure('error', 'workerStartFailed', error));
+      drain();
+      return;
+    }
+    const record = { child, request, unreaped: false };
+    request.record = record;
+    active.add(record);
+    child.once('exit', () => release(record));
+    child.once('close', () => release(record));
+    child.on('error', error => {
+      finish(request, failure('error', 'workerStartFailed', error));
+      if (child.pid) stop(record);
+      else release(record);
+    });
+    child.once('message', result => {
+      if (request.finished) return;
+      if (!result || !['ok', 'missing', 'error'].includes(result.status) || typeof result.incomplete !== 'boolean') {
+        finish(request, failure('error', 'workerProtocol', { code: 'PROBE_PROTOCOL', message: '文件探测进程返回非法结果' }));
+        stop(record);
+        return;
+      }
+      finish(request, result);
+      // 结果已到达也必须收到 exit 后才释放预算，避免新旧进程短暂重叠。
+    });
+    child.send({ operation: request.operation, path: request.path, limit: request.limit }, error => {
+      if (!error || request.finished) return;
+      finish(request, failure('error', 'workerStartFailed', error));
+      stop(record);
+    });
+  }
+
+  function submit(operation, path, requestOptions = {}) {
+    if (closed) return Promise.resolve(failure('cancelled', 'closed'));
+    let requestTimeout, limit, signal;
+    try {
+      if (typeof path !== 'string' || !path.length || path.includes('\0')) {
+        throw Object.assign(new TypeError('path 必须是非空且不含空字符的字符串'), { code: 'INVALID_PATH' });
+      }
+      requestTimeout = integer(requestOptions.timeout ?? timeout, 'timeout');
+      limit = operation === 'readDirectory' ? integer(requestOptions.limit ?? 1000, 'limit', 1, MAX_DIRECTORY_ENTRIES) : undefined;
+      signal = requestOptions.signal;
+      if (signal && (typeof signal.addEventListener !== 'function' || typeof signal.removeEventListener !== 'function' || typeof signal.aborted !== 'boolean')) {
+        throw new TypeError('signal 必须是 AbortSignal');
+      }
+    } catch (error) {
+      return Promise.resolve(failure('error', 'invalidOptions', error));
+    }
+    if (signal?.aborted) return Promise.resolve(failure('cancelled', 'signal'));
+    if (!allowRemote && isRemotePath(path)) return Promise.resolve(failure('skipped', 'remotePath'));
+    if (active.size >= maxConcurrent && pending.length >= maxPending) {
+      return Promise.resolve(failure('error', 'queueFull', { code: 'PROBE_BUSY', message: '文件探测并发和排队预算已满' }));
+    }
+    return new Promise(resolve => {
+      const request = { operation, path, limit, signal, resolve, finished: false };
+      function cancel(result) {
+        finish(request, result);
+        if (request.record) stop(request.record);
+      }
+      request.onAbort = () => cancel(failure('cancelled', 'signal'));
+      request.timer = setTimeout(() => cancel(failure('timedOut', 'timeout')), requestTimeout);
+      signal?.addEventListener('abort', request.onAbort, { once: true });
+      if (active.size < maxConcurrent) start(request);
+      else pending.push(request);
+    });
+  }
+
+  function close() {
+    if (closing) return closing;
+    closed = true;
+    for (const request of [...pending]) finish(request, failure('cancelled', 'closed'));
+    for (const record of active) {
+      finish(record.request, failure('cancelled', 'closed'));
+      stop(record);
+    }
+    closing = new Promise(resolve => {
+      let timer;
+      function done() {
+        clearTimeout(timer);
+        closeWaiters.delete(done);
+        // 不能立即退出的底层 I/O 仍被记录，但不会让宿主关闭无限等待。
+        for (const record of active) {
+          record.child.unref();
+          record.child.channel?.unref();
+        }
+        resolve({ closed: true, incomplete: active.size > 0, unreaped: active.size });
+      }
+      if (!active.size) done();
+      else { closeWaiters.add(done); timer = setTimeout(done, closeTimeout); }
+    });
+    return closing;
+  }
+
+  return { stat: (path, options) => submit('stat', path, options),
+    readDirectory: (path, options) => submit('readDirectory', path, options), close, status };
+}