@yanglaofish/fishtools 0.5.2 → 0.5.3

package/node_modules/@mytools/fst-cli/src/terminal/workflow-menu.js

@@ -14,7 +14,7 @@ export async function workflowMenu(session){
       if(choice==='new'){if(await session.execute('/new')===false)continue;}
       else if(choice!=='draft'&&session.flow?.id!==id){
         if(!await session.discard())continue;
-        session.flow=structuredClone(workflows.find(flow=>flow.id===id));session.dirty=false;
+        session.loadWorkflow(workflows.find(flow=>flow.id===id));
       }
       if(await editWorkflow(session)==='running')return;
     }catch(error){if(error.code!=='PROMPT_CANCELLED')throw error;}
@@ -30,18 +30,23 @@ async function editWorkflow(session){
       ...(!app.project.readOnly?[
         {value:'add',label:'添加步骤 / 控制流'}, {value:'steps',label:'编辑步骤、参数与顺序'},
         {value:'outputs',label:'设置最终输出'},{value:'save',label:'保存工作流'},
-        {value:'duplicate',label:'复制为新工作流（包含当前未保存修改）'},
-        {value:'delete',label:'删除工作流（保留可恢复备份）'},
+        {value:'duplicate',label:`复制为新工作流${session.dirty?'（包含当前未保存修改）':''}`},
+        {value:'delete',label:'删除工作流'},
       ]:[{value:'steps',label:'查看步骤'}]),
-      {value:'back',label:'返回工作流列表（保留草稿）'},
+      {value:'back',label:`返回工作流列表${session.dirty?'（保留草稿）':''}`},
     ]);
     if(choice==='back')return;
     try{
       if(choice==='delete'){
-        if(!await ui.confirm(`删除 ${flow.title??flow.id}？已保存文件会移入备份，未保存修改将放弃。`))continue;
         const exists=(await app.listWorkflows()).some(w=>w.id===flow.id);
-        const backup=exists?await app.removeWorkflow(flow.id):null;
-        session.flow=null;session.dirty=false;ui.show(backup?`工作流已移入备份：${backup}`:'未保存的草稿已删除。');return;
+        const operation=await ui.select(`删除 ${flow.title??flow.id}？${session.dirty?'当前未保存修改将放弃。':''}`, [
+          {value:'cancel',label:'取消，返回'},
+          ...(exists?[{value:'backup',label:'备份后删除',description:'保留已保存文件，可恢复'},
+            {value:'delete',label:'直接删除',description:'不创建本次删除的备份'}]:[{value:'delete',label:'丢弃未保存的草稿'}]),
+        ]);
+        if(operation==='cancel')continue;
+        const backup=exists?await app.removeWorkflow(flow.id,{backup:operation==='backup'}):null;
+        session.loadWorkflow(null);ui.show(backup?`工作流已移入备份：${backup}`:exists?'工作流已删除，未创建本次删除的备份。':'未保存的草稿已丢弃。');return;
       }
       if(choice==='run'){
         if(await session.startRun([],{draft:true}))return 'running';
@@ -55,6 +60,6 @@ async function duplicateIntoSession(session,source){
   const title=(await session.ui.input('新工作流名称',{value:`${source.title??source.id} 副本`,files:false})).trim();
   if(!title)throw new Error('名称不能为空');
   const {definition}=await session.app.duplicateWorkflow(source,{title});
-  session.flow=structuredClone(definition);session.dirty=false;
-  session.ui.show(`已创建副本：${definition.title}（${definition.id}）。原工作流 ${source.id} 未修改。可在父工作流中依次加入原版和副本两个子流程步骤，比较输出和耗时。`);
+  session.loadWorkflow(definition);
+  session.ui.show(`已创建副本：${definition.title}（${definition.id}）。原工作流 ${source.id} 未修改。`);
 }

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

@@ -16,14 +16,14 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=24.15.0"
+    "node": "^22.22.2 || >=24.0.0"
   },
   "dependencies": {
     "@mytools/sdk": "0.1.0",
     "@mytools/fst-platform": "0.1.0",
     "@mytools/fst-plugin": "0.1.0",
     "semver": "7.7.4",
-    "validate-npm-package-name": "8.0.0",
+    "validate-npm-package-name": "7.0.2",
     "acorn": "8.19.0"
   }
 }

package/node_modules/@mytools/fst-devtools/src/plugin-tools.js

@@ -125,7 +125,7 @@ async function inspectPluginDirectory(directory,quality){
 }
 
 function scaffold(name){
-  const packageJson={name,version:'1.0.0',type:'module',main:'index.js',files:['index.js','test','README.md','LICENSE'],scripts:{test:'node --test'},license:'MIT',engines:{node:'>=24.15.0'}};
+  const packageJson={name,version:'1.0.0',type:'module',main:'index.js',files:['index.js','test','README.md','LICENSE'],scripts:{test:'node --test'},license:'MIT',engines:{node:'^22.22.2 || >=24.0.0'}};
   const plugin=`// 直接导出插件定义，无需安装内部 SDK。\nexport default {\n  id:${JSON.stringify(name)},version:'1.0.0',sdk:'^0.1.0',\n  title:'嵌套输入示例',description:'演示业务结果、嵌套输入和判定预设。',\n  platforms:['win32','linux','darwin'],architectures:['x64','arm64'],\n  actions:{\n    check:{\n      title:'检查请求',description:'根据嵌套请求生成业务结果。',\n      input:{type:'object',properties:{request:{type:'object',properties:{name:{type:'string',minLength:1,title:'姓名'},enabled:{type:'boolean',title:'启用'}},required:['name','enabled'],additionalProperties:false}},required:['request'],additionalProperties:false},\n      output:{type:'object',properties:{ok:{type:'boolean'},message:{type:'string'}},required:['ok','message'],additionalProperties:false},\n      conditions:{passed:{title:'业务通过',path:'ok',op:'eq',value:true}},\n      requirements:{privilege:{win32:{level:'user'},linux:{level:'user'}}},\n      async run({request},{signal}={}){\n        signal?.throwIfAborted?.();\n        return request.enabled?{ok:true,message:\`你好，\${request.name}\`}:{ok:false,message:'已禁用'};\n      },\n    },\n  },\n};\n`;
   const testSource=`import test from 'node:test';\nimport assert from 'node:assert/strict';\nimport plugin from '../index.js';\n\ntest('嵌套参数和业务判定',async()=>{\n  assert.deepEqual(await plugin.actions.check.run({request:{name:'阿青',enabled:true}}),{ok:true,message:'你好，阿青'});\n  assert.deepEqual(await plugin.actions.check.run({request:{name:'阿青',enabled:false}}),{ok:false,message:'已禁用'});\n});\n`;
   const readme=`# ${name}\n\n可独立安装的 Fishtools 插件示例，不依赖尚未公开发布的 SDK。\n\n## 使用\n\n在本目录运行 \`npm test\`，并运行 \`fst plugin validate .\` 检查声明。安装后可将 \`${name}:check\` 加入工作流。\n\n输入示例：\n\n\`\`\`json\n{"request":{"name":"阿青","enabled":true}}\n\`\`\`\n\n输出含 \`ok\` 与 \`message\`。\`ok:false\` 表示业务未通过，但动作仍正常返回；\`conditions.passed\` 可供工作流分支使用。请同步修改 package.json 和 index.js 中的名称、版本，并根据实际支持情况调整 platforms / architectures。\n`;

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

@@ -4,7 +4,7 @@
 
 ## 职责与边界
 
-运行日志写入器、串行落盘、有界事件缓存、快照、历史分页、保留和体积统计。运行调度由 core 负责。
+运行日志写入器、串行落盘、有界事件缓存、快照、历史分页、保留和体积统计，以及 TUI 会话元数据和完整交互摘要存储。运行调度由 core 负责。
 
 内部依赖：`@mytools/sdk`。
 ## 公开入口
@@ -15,6 +15,7 @@
 | `@mytools/fst-logs/markdown` | `./src/markdown-log.js` |
 | `@mytools/fst-logs/steps` | `./src/step-summaries.js` |
 | `@mytools/fst-logs/preview` | `./src/run-preview.js` |
+| `@mytools/fst-logs/sessions` | `./src/session-history.js` |
 | `@mytools/fst-logs/package.json` | `./package.json` |
 
 仅依赖 exports 声明的入口，禁止消费者跨包读取 src/bin 私有文件。入口路径由本模块维护，修改协议时同步消费方回归。
@@ -56,6 +57,26 @@ maxValueBytes 至少为 2，连预览本身也容不下时省略字段值并保
 
 拒绝日志根目录、运行目录或正文文件链接，已有同 ID 日志拒绝覆盖。体积统计和保留策略仅涉及 `run.md`、`events.jsonl`、`result.json`、`run.meta.json` 四个约定文件；业务文件和子目录保持保留。统计不递归、不读取正文。普通文件系统检查不能提供针对恶意并发路径替换的操作系统安全沙箱。
 
+## TUI 会话持久化
+
+`createSessionHistory(directory,{projectDir,maxBytes=2097152,maxEntryBytes=65536,maxPageBytes=524288,maxPendingBytes=8388608})` 从 `/sessions` 入口创建会话存储器。调用方决定本地会话目录，测试必须使用临时目录，不能写入真实 `FISHTOOLS_HOME`。会话使用严格 UUID 格式的 ID，按工作区绝对路径保存 `sessionOwner`；Windows 路径比较忽略大小写。
+
+每个会话有两个文件：`<id>.json` 保存轻量元数据和最近视图，`<id>.jsonl` 持续追加全部交互摘要。输入、反馈、运行开始和最终结果都应由 TUI 逐条追加；最近视图的条目数量限制不会删除 JSONL 中更早的交互。完整进程输出继续放在原运行日志中，会话摘要只保存有界结果预览与对应运行 ID。会话文件默认使用可直接读取的 UTF-8 JSON，不自动加密、压缩或删除历史。
+
+| 方法 | 行为 |
+| --- | --- |
+| `save(snapshot)` | 保存 `schemaVersion:1`、UUID `id`、`startedAt`、`updatedAt`、可选 `resumedFrom`、`commandHistory` 字符串数组和 `feed` 最近视图数组，并自动写入 `sessionOwner`；其余 JSON 字段同样保留 |
+| `read(id)` | 校验归属后返回当前元数据；不加载完整交互正文 |
+| `list()` | 按最近更新时间列出轻量摘要：`schemaVersion`、`id`、`sessionOwner`、`startedAt`、`updatedAt`、可选 `resumedFrom`、`commandCount`、`feedCount` |
+| `append(id,entry)` | 在已保存元数据的会话中追加一个 JSON 对象；保留条目原结构，并等待文件写入和同步完成 |
+| `page(id,{cursor=0,limit=100})` | 返回 `{entries,cursor,nextCursor,hasMore,totalBytes}`；`cursor` 是完整 JSONL 记录边界的字节位置，`limit` 是条目数，上限 200 |
+
+同一进程中，同目录、同 ID 的保存、追加和分页按调用顺序串行执行，包括多个存储器实例。保存通过独占创建临时文件、同步写入和原子替换完成；更新时间更旧的快照被跳过，同一毫秒的快照按调用顺序保存。已有会话不能改变开始时间。恢复必须新建 UUID、复制所需视图，并将旧 ID 写入 `resumedFrom`，原会话和交互日志继续保留。
+
+`maxBytes` 限制每份元数据，`maxEntryBytes` 限制每条 JSON 正文，`maxPageBytes` 限制每页 JSONL 原始字节，`maxPendingBytes` 限制尚未完成的写入队列。分页预算必须容纳单条最大记录及换行。交互日志总长度可持续增长，每次分页只读取有界窗口；不会为了查看会话把整份 JSONL 加载进内存。超限分别返回 `SESSION_METADATA_LIMIT`、`SESSION_ENTRY_LIMIT` 或 `SESSION_QUEUE_LIMIT`，不静默截断用户记录；调用方应保留错误反馈并提示用户。一次失败不会阻止后续读取或重试。
+
+元数据损坏、过大或来自其他工作区时，`list()` 跳过该会话，直接 `read()` 明确报错。损坏的已有元数据拒绝覆盖。根目录或文件链接、不安全 ID、非法游标均被拒绝；JSONL 末尾缺少换行时拒绝继续追加，避免把新输入接到未完成的旧记录后。普通文件系统检查无法替代针对恶意并发路径替换的操作系统安全沙箱。
+
 ## 维护与验证
 
 本模块负责上述职责的实现、文档与回归；跨模块接口调整需要同时检查生产者与消费者。具体维护人员尚未指定。
@@ -63,5 +84,5 @@ maxValueBytes 至少为 2，连预览本身也容不下时省略字段值并保
 在仓库根目录执行：
 
 ```sh
-node --test tests/log-streaming.test.js tests/modules.test.js tests/module-interfaces.test.js tests/run-logs.test.js tests/live-output.test.js
+node --test tests/session-history.test.js tests/log-streaming.test.js tests/modules.test.js tests/module-interfaces.test.js tests/run-logs.test.js tests/live-output.test.js
 ```

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

@@ -8,6 +8,7 @@
     ".": "./src/run-logs.js",
     "./steps": "./src/step-summaries.js",
     "./preview": "./src/run-preview.js",
+    "./sessions": "./src/session-history.js",
     "./markdown": "./src/markdown-log.js",
     "./package.json": "./package.json"
   },
@@ -18,7 +19,7 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": ">=24.15.0"
+    "node": "^22.22.2 || >=24.0.0"
   },
   "dependencies": {
     "@mytools/sdk": "0.1.0"

package/node_modules/@mytools/fst-logs/src/file-identity.js

@@ -0,0 +1,23 @@
+import {lstat,open} from 'node:fs/promises';
+
+export function sameFileIdentity(pathStat,handleStat,platform=process.platform){
+  if(pathStat.ino!==handleStat.ino)return false;
+  // 早期 libuv 的 Windows 路径查询返回 64 位卷号，句柄查询只有低 32 位。
+  // 与维护版本的 VolumeSerialNumber.LowPart 口径一致；文件 ID 仍完整比较。
+  const device=stat=>platform==='win32'?BigInt.asUintN(32,stat.dev):stat.dev;
+  return device(pathStat)===device(handleStat);
+}
+
+export async function samePathFileIdentity(file,pathStat,handleStat,platform=process.platform){
+  if(sameFileIdentity(pathStat,handleStat,platform))return true;
+  if(platform!=='win32'||pathStat.dev!==0n||pathStat.ino!==handleStat.ino)return false;
+  // 某些 Windows 文件系统的早期路径查询缺少卷号，不能直接将 0 当作通配符。
+  // 用第二个只读句柄证明当前路径与主句柄的完整身份，再确认路径仍非链接。
+  const probe=await open(file,'r');
+  try{
+    const proof=await probe.stat({bigint:true});
+    if(!proof.isFile()||proof.ino!==handleStat.ino||proof.dev!==handleStat.dev)return false;
+    const current=await lstat(file,{bigint:true});
+    return current.isFile()&&!current.isSymbolicLink()&&current.ino===pathStat.ino&&(current.dev===0n||sameFileIdentity(current,handleStat,platform));
+  }finally{await probe.close();}
+}

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

@@ -1,5 +1,5 @@
 const names={
-  'run.started':'运行开始','run.succeeded':'运行成功','run.failed':'运行失败','run.cancelled':'运行取消','run.stopped':'运行停止',
+  'run.started':'运行开始','run.input':'运行输入','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:'插件日志',
 };
@@ -28,7 +28,8 @@ function errorText(error){
 }
 
 export function markdownHeader(run){
-  return '# Fishtools 运行日志\n\n'+block(`运行 ID：${run.id}\n工作流或命令：${run.workflowId}\n开始时间：${run.startedAt}`)+'## 执行过程\n\n';
+  const kind={workflow:'工作流',action:'插件动作',command:'插件命令',shell:'系统命令'}[run.kind];
+  return '# Fishtools 运行日志\n\n'+block(`运行 ID：${run.id}\n工作流或命令：${run.workflowId}${kind?`\n执行类型：${kind}`:''}${run.sessionId?`\n启动会话：${run.sessionId}`:''}\n开始时间：${run.startedAt}`)+'## 执行过程\n\n';
 }
 
 export function markdownEvent(event){
@@ -41,7 +42,7 @@ export function markdownEvent(event){
   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.input!==undefined)output+=(event.type==='run.input'?'运行输入：\n\n':'步骤输入：\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;

package/node_modules/@mytools/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/node_modules/@mytools/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/node_modules/@mytools/fst-platform/README.md

@@ -39,7 +39,11 @@ node --test tests/modules.test.js tests/process.test.js tests/environments.test.
 
 `/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/node_modules/@mytools/fst-platform/node_modules/undici/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Matteo Collina and Undici 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.