@yanglaofish/fishtools 0.4.0 → 0.5.1

package/manual/packages/fst-devtools/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-devtools/README.md

@@ -0,0 +1,28 @@
+# 开发工具模块
+
+包名：`@mytools/fst-devtools`。内部 workspace 包，随 `@yanglaofish/fishtools` 统一交付。
+
+## 职责与边界
+
+插件脚手架、validate、lint、离线文档发现与导出。不管理常驻宿主或用户运行状态。
+
+内部依赖：`@mytools/sdk`、`@mytools/fst-platform`、`@mytools/fst-plugin`。
+## 公开入口
+
+| 导入路径 | 实现位置 |
+| --- | --- |
+| `@mytools/fst-devtools` | `./src/plugin-tools.js` |
+| `@mytools/fst-devtools/documentation` | `./src/documentation.js` |
+| `@mytools/fst-devtools/package.json` | `./package.json` |
+
+仅依赖 exports 声明的入口，禁止消费者跨包读取 src/bin 私有文件。入口路径由本模块维护，修改协议时同步消费方回归。
+
+## 维护与验证
+
+本模块负责上述职责的实现、文档与回归；跨模块接口调整需要同时检查生产者与消费者。具体维护人员尚未指定。
+
+在仓库根目录执行：
+
+```sh
+node --test tests/modules.test.js tests/plugin-tools.test.js tests/plugin-lint.test.js tests/documentation.test.js
+```

package/manual/packages/fst-devtools/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@mytools/fst-devtools",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/plugin-tools.js",
+  "exports": {
+    ".": "./src/plugin-tools.js",
+    "./documentation": "./src/documentation.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.15.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",
+    "acorn": "8.19.0"
+  }
+}

package/{node_modules/@mytools/core → manual/packages/fst-devtools}/src/documentation.js

@@ -9,10 +9,12 @@ const topics=[
   ['services','服务插件示例','examples/service-plugins/README.md'],
   ['example','可安装的零依赖动作插件','docs/examples/action-plugin/README.md'],
   ['roadmap','路线图','docs/roadmap.md'],
+  ['modules','模块架构与维护','docs/modules.md'],
+  ['generation','大日志、开发重载与隔离文件探测','docs/kernel-generation.md'],
   ['readme','Fishtools 使用说明','README.md'],
 ];
 // 保留文档链接所需的目录布局；参考代码仅供阅读，不是第二份运行时。
-const assets=['README.md','LICENSE','THIRD_PARTY_NOTICES.md','docs','examples/service-plugins','plugins/examples','plugins/environment','packages/sdk','packages/core/src/host.js','packages/core/src/runtime.js','packages/core/src/engine.js','packages/core/src/application.js','packages/core/src/terminal/view.js','packages/core/src/terminal/run-feed.js','packages/core/src/terminal/session.js','packages/core/LICENSE','tests/application.test.js'];
+const assets=['README.md','LICENSE','THIRD_PARTY_NOTICES.md','docs','examples/service-plugins','plugins/examples','plugins/environment','plugins/web/README.md','packages/sdk','packages/core','packages/pack','packages/fst-logs','packages/fst-platform','packages/fst-workflow','packages/fst-plugin','packages/fst-workspace','packages/fst-devtools','packages/fst-cli','tests/application.test.js'];
 const excluded=new Set(['node_modules','dist','.git','.cache','__pycache__','.pytest_cache','coverage','public']);
 const inside=(parent,child)=>{const relative=path.relative(parent,child);return relative===''||(!relative.startsWith(`..${path.sep}`)&&relative!=='..'&&!path.isAbsolute(relative));};
 

package/manual/packages/fst-devtools/src/plugin-quality.js

@@ -0,0 +1,136 @@
+import path from 'node:path';
+import {readFile,realpath} from 'node:fs/promises';
+import {isBuiltin,createRequire} from 'node:module';
+import {fileURLToPath,pathToFileURL} from 'node:url';
+import {parse} from 'acorn';
+
+const nonempty=value=>typeof value==='string'&&value.trim().length>0;
+function inspectSchema(schema,location,warning,seen=new WeakSet()){
+  if(typeof schema==='boolean'){
+    warning('BOOLEAN_SCHEMA','布尔 schema 合法，但无法提供字段级表单提示；建议按业务需要描述字段',location);return;
+  }
+  if(!schema||typeof schema!=='object'||seen.has(schema))return;
+  seen.add(schema);
+  if(Array.isArray(schema)){schema.forEach((child,index)=>inspectSchema(child,`${location}[${index}]`,warning,seen));return;}
+  for(const key of ['properties','patternProperties','$defs','definitions','dependencies']){
+    for(const [name,child] of Object.entries(schema[key]??{})){
+      const at=`${location}.${key}.${name}`;
+      if(['properties','patternProperties'].includes(key)&&!nonempty(child?.title))warning('MISSING_TITLE','字段缺少非空 title',`${at}.title`);
+      inspectSchema(child,at,warning,seen);
+    }
+  }
+  for(const key of ['items','additionalItems','contains','propertyNames','additionalProperties','not','if','then','else']){
+    // additionalProperties 等布尔约束是正常用法，不作为表单质量提示。
+    if(typeof schema[key]==='object')inspectSchema(schema[key],`${location}.${key}`,warning,seen);
+  }
+  for(const key of ['allOf','anyOf','oneOf','prefixItems']){
+    if(Array.isArray(schema[key]))schema[key].forEach((child,index)=>inspectSchema(child,`${location}.${key}[${index}]`,warning,seen));
+  }
+}
+
+export function inspectMetadata(plugin,warning){
+  for(const collection of ['actions','commands']){
+    for(const [name,item] of Object.entries(plugin[collection]??{})){
+      if(!item||typeof item!=='object')continue;
+      const location=`plugin.${collection}.${name}`;
+      // 动作别名命令可以复用动作元信息。
+      const target=collection==='commands'&&item.action?plugin.actions?.[item.action]:undefined;
+      for(const key of ['title','description']){
+        if(!nonempty(item[key]??target?.[key]))warning(`MISSING_${key.toUpperCase()}`,`缺少非空 ${key}`,`${location}.${key}`);
+      }
+      if(!target)for(const key of ['input','output'])inspectSchema(item[key],`${location}.${key}`,warning);
+    }
+  }
+}
+
+function walk(node,visit){
+  if(!node||typeof node!=='object')return;
+  if(typeof node.type==='string')visit(node);
+  for(const value of Object.values(node)){
+    if(Array.isArray(value))for(const child of value)walk(child,visit);
+    else if(value&&typeof value==='object')walk(value,visit);
+  }
+}
+
+function bindingNames(pattern,result){
+  if(!pattern)return;
+  if(pattern.type==='Identifier')result.set(pattern.name,(result.get(pattern.name)??0)+1);
+  else if(pattern.type==='RestElement')bindingNames(pattern.argument,result);
+  else if(pattern.type==='AssignmentPattern')bindingNames(pattern.left,result);
+  else if(pattern.type==='ObjectPattern')for(const p of pattern.properties)bindingNames(p.type==='RestElement'?p.argument:p.value,result);
+  else if(pattern.type==='ArrayPattern')for(const p of pattern.elements)bindingNames(p,result);
+}
+
+function sourceReferences(ast,commonjs,warning,location){
+  const bindings=new Map(),references=[],factories=new Set(),loaders=new Set();
+  walk(ast,node=>{
+    if(node.type==='VariableDeclarator')bindingNames(node.id,bindings);
+    if(['FunctionDeclaration','FunctionExpression','ArrowFunctionExpression'].includes(node.type)){
+      bindingNames(node.id,bindings);for(const p of node.params)bindingNames(p,bindings);
+    }
+    if(node.type==='ClassDeclaration'||node.type==='ClassExpression')bindingNames(node.id,bindings);
+    if(node.type==='CatchClause')bindingNames(node.param,bindings);
+    if(node.type==='ImportDeclaration')for(const p of node.specifiers){
+      bindingNames(p.local,bindings);
+      if(['node:module','module'].includes(node.source.value)&&p.imported?.name==='createRequire')factories.add(p.local.name);
+    }
+    // 重赋值也跳过，避免把可变的局部函数当作 require。
+    if(node.type==='AssignmentExpression')bindingNames(node.left,bindings);
+  });
+  walk(ast,node=>{
+    const base=node.init?.arguments?.[0];
+    if(node.type==='VariableDeclarator'&&node.id.type==='Identifier'&&bindings.get(node.id.name)===1&&node.init?.type==='CallExpression'&&
+      node.init.callee.type==='Identifier'&&factories.has(node.init.callee.name)&&bindings.get(node.init.callee.name)===1&&
+      base?.type==='MemberExpression'&&!base.computed&&base.property.name==='url'&&base.object.type==='MetaProperty'&&base.object.meta.name==='import')loaders.add(node.id.name);
+  });
+  // 保守跳过文件内重名绑定；不把局部对象当作 Node 全局对象。
+  walk(ast,node=>{
+    const at=`${location}:${node.loc.start.line}:${node.loc.start.column+1}`;
+    if(['ImportDeclaration','ExportNamedDeclaration','ExportAllDeclaration','ImportExpression'].includes(node.type)&&typeof node.source?.value==='string'){
+      references.push({specifier:node.source.value,at,commonjs:false});
+    }
+    if(node.type!=='CallExpression')return;
+    const callee=node.callee;
+    if(callee.type==='Identifier'&&((commonjs&&!bindings.has('require')&&callee.name==='require')||loaders.has(callee.name))&&typeof node.arguments[0]?.value==='string'){
+      references.push({specifier:node.arguments[0].value,at,commonjs:true});
+    }
+    if(!bindings.has('console')&&callee.type==='MemberExpression'&&callee.object.type==='Identifier'&&callee.object.name==='console'&&
+      (callee.computed?callee.property.value:callee.property.name)==='log')warning('CONSOLE_LOG','直接 console.log 可能干扰终端或 JSON 输出；动作和命令内请使用上下文 log / print',at);
+  });
+  return references;
+}
+
+export async function inspectSources(directory,pkg,warning){
+  const root=await realpath(directory),seen=new Set(),declared=new Set([pkg.name,...Object.keys(pkg.dependencies??{}),...Object.keys(pkg.peerDependencies??{}),...Object.keys(pkg.optionalDependencies??{})]);
+  const within=file=>{const relative=path.relative(root,file);return relative!== '..'&&!relative.startsWith(`..${path.sep}`)&&!path.isAbsolute(relative)&&!relative.split(path.sep).includes('node_modules');};
+  async function scan(file){
+    let actual;
+    try{actual=await realpath(file);}catch(cause){warning('SOURCE_UNREADABLE',`无法扫描本地模块：${cause.message}`,path.relative(root,file));return;}
+    if(!within(actual)){warning('SOURCE_OUTSIDE_PACKAGE','跳过包目录外或 node_modules 中的源码',path.relative(root,file));return;}
+    if(seen.has(actual))return;seen.add(actual);
+    const extension=path.extname(actual);
+    if(extension==='.json'||extension==='.node')return;
+    if(!['.js','.mjs','.cjs'].includes(extension)){warning('SOURCE_UNSUPPORTED','仅扫描 .js/.mjs/.cjs 源码',path.relative(root,actual));return;}
+    let ast;
+    const location=path.relative(root,actual),commonjs=extension==='.cjs';
+    try{ast=parse(await readFile(actual,'utf8'),{ecmaVersion:'latest',sourceType:commonjs?'commonjs':'module',locations:true});}
+    catch(cause){warning('SOURCE_PARSE_FAILED',`无法完成源码检查：${cause.message}`,location);return;}
+    for(const ref of sourceReferences(ast,commonjs,warning,location)){
+      const spec=ref.specifier;
+      if(isBuiltin(spec))continue;
+      if(spec.startsWith('.')){
+        try{
+          const target=ref.commonjs?createRequire(actual).resolve(spec):fileURLToPath(new URL(spec,pathToFileURL(actual)));
+          await scan(target);
+        }catch(cause){warning('SOURCE_UNREADABLE',`无法解析本地模块 ${spec}：${cause.message}`,ref.at);}
+      }else if(spec.startsWith('#')||spec.includes(':')||path.isAbsolute(spec)){
+        warning('DEPENDENCY_UNCHECKED',`未检查特殊模块引用 ${spec}`,ref.at);
+      }else{
+        const name=spec.startsWith('@')?spec.split('/').slice(0,2).join('/'):spec.split('/')[0];
+        if(!declared.has(name))warning('UNDECLARED_DEPENDENCY',`运行时引用 ${name}，但 package.json 的 dependencies / optionalDependencies / peerDependencies 未声明它`,ref.at);
+      }
+    }
+  }
+  if(typeof (pkg.main??'index.js')!=='string'){warning('SOURCE_UNREADABLE','package.json.main 必须是入口路径','package.json.main');return;}
+  await scan(path.resolve(root,pkg.main??'index.js'));
+}

package/{node_modules/@mytools/core → manual/packages/fst-devtools}/src/plugin-tools.js

@@ -3,10 +3,10 @@ import {readFile,writeFile,mkdir,mkdtemp,rename,rm,access} from 'node:fs/promise
 import semver from 'semver';
 import validateNpmPackageName from 'validate-npm-package-name';
 import {SDK_VERSION} from '@mytools/sdk';
-import {loadPlugin} from './plugins.js';
-import {validateDeclarations,validateCommands} from './contracts.js';
-import {assertSchema} from './validation.js';
-import {platformWarnings} from './environments.js';
+import {loadPlugin} from '@mytools/fst-plugin/loader';
+import {validateDeclarations,validateCommands} from '@mytools/fst-plugin/contracts';
+import {assertSchema} from '@mytools/sdk/schema';
+import {platformWarnings} from '@mytools/fst-platform/environments';
 
 const validNpmName=name=>typeof name==='string'&&validateNpmPackageName(name).validForNewPackages===true;
 const hasOwn=(value,key)=>Object.hasOwn(value,key);
@@ -28,7 +28,20 @@ function inspectRequired(schema,location,warning,seen=new WeakSet()){
   }
 }
 
+const validationNotes=()=>[{code:'RUNTIME_OUTPUT_UNVERIFIED',message:'输出 required 字段是否实际返回无法静态确认；请按发布清单执行一次工作流验证。'}];
+
 export async function validatePluginDirectory(directory){
+  return {...await inspectPluginDirectory(directory),notes:validationNotes()};
+}
+
+export async function lintPluginDirectory(directory){
+  const quality=await import('./plugin-quality.js');
+  return {...await inspectPluginDirectory(directory,quality),notes:[...validationNotes(),
+    {code:'STATIC_SCAN_LIMITS',message:'源码检查仅覆盖入口可达的本地 JavaScript 和字面量依赖；动态加载、别名调用和局部重名可能无法识别。质量警告不会修改文件，也不代表运行结果或安全保证。'},
+  ]};
+}
+
+async function inspectPluginDirectory(directory,quality){
   const root=path.resolve(directory),diagnostics=[];
   const report=(severity,code,message,location)=>diagnostics.push({severity,code,message,...(location?{path:location}:{})});
   const error=(code,message,location)=>report('error',code,message,location);
@@ -40,10 +53,12 @@ export async function validatePluginDirectory(directory){
   if(!validNpmName(pkg.name))error('INVALID_PACKAGE_NAME','package.json 的 name 必须是合法 npm 包名','package.json.name');
   if(!semver.valid(pkg.version))error('INVALID_PACKAGE_VERSION','package.json 的 version 必须是 semver 版本','package.json.version');
   if(pkg.type!=='module')error('ESM_REQUIRED','插件必须声明 type: module','package.json.type');
+  if(quality)await quality.inspectSources(root,pkg,warning);
   try{({plugin}=await loadPlugin('.',root));}
   catch(cause){error('PLUGIN_LOAD_FAILED',`无法导入插件：${cause.message}`,'package.json.main');return {valid:false,plugin:{},diagnostics};}
   if(!plugin||typeof plugin!=='object'||Array.isArray(plugin)){error('INVALID_PLUGIN','默认导出必须是插件定义对象','plugin');return {valid:false,plugin:{},diagnostics};}
   const identity={id:plugin.id,version:plugin.version};
+  if(quality)quality.inspectMetadata(plugin,warning);
   if(!validNpmName(plugin.id))error('INVALID_PLUGIN_ID','插件 id 必须是合法 npm 包名','plugin.id');
   else if(plugin.id!==pkg.name)error('PLUGIN_ID_MISMATCH',`插件 id ${plugin.id} 与包名 ${pkg.name} 不一致`,'plugin.id');
   if(!semver.valid(plugin.version))error('INVALID_PLUGIN_VERSION','插件 version 必须是 semver 版本','plugin.version');
@@ -54,6 +69,10 @@ export async function validatePluginDirectory(directory){
     if(plugin[key]===undefined)warning(`${key.toUpperCase()}_UNDECLARED`,`${key} 未声明，请明确插件支持范围`,location);
   }
   try{validateDeclarations(plugin);}catch(cause){error('INVALID_DECLARATION',cause.message,cause.details?.path??'plugin');}
+  if((plugin.runtime||Object.keys(plugin.services??{}).length||Object.values(plugin.commands??{}).some(command=>!command.action))&&!plugin.requirements?.privilege)
+    warning('MISSING_PRIVILEGE_DECLARATION','插件服务或独立命令未声明权限要求；请说明普通用户是否可运行','plugin.requirements.privilege');
+  for(const [name,action] of Object.entries(plugin.actions??{}))if(!action?.requirements?.privilege&&!plugin.requirements?.privilege)
+    warning('MISSING_PRIVILEGE_DECLARATION',`动作 ${name} 未声明权限要求；请说明普通用户是否可运行`,`plugin.actions.${name}.requirements.privilege`);
   if(['platforms','architectures'].every(key=>plugin[key]===undefined||Array.isArray(plugin[key]))) {
     for(const message of platformWarnings(plugin))warning('PLATFORM_MISMATCH',message,message.includes('架构')?'plugin.architectures':'plugin.platforms');
   }
@@ -107,7 +126,7 @@ export async function validatePluginDirectory(directory){
 
 function scaffold(name){
   const packageJson={name,version:'1.0.0',type:'module',main:'index.js',files:['index.js','test','README.md','LICENSE'],scripts:{test:'node --test'},license:'MIT',engines:{node:'>=24.15.0'}};
-  const plugin=`// 直接导出插件定义，无需安装内部 SDK。\nexport default {\n  id:${JSON.stringify(name)},version:'1.0.0',sdk:'^0.1.0',\n  title:'嵌套输入示例',description:'演示业务结果、嵌套输入和判定预设。',\n  platforms:['win32','linux','darwin'],architectures:['x64','arm64'],\n  actions:{\n    check:{\n      title:'检查请求',description:'根据嵌套请求生成业务结果。',\n      input:{type:'object',properties:{request:{type:'object',properties:{name:{type:'string',minLength:1,title:'姓名'},enabled:{type:'boolean',title:'启用'}},required:['name','enabled'],additionalProperties:false}},required:['request'],additionalProperties:false},\n      output:{type:'object',properties:{ok:{type:'boolean'},message:{type:'string'}},required:['ok','message'],additionalProperties:false},\n      conditions:{passed:{title:'业务通过',path:'ok',op:'eq',value:true}},\n      async run({request},{signal}={}){\n        signal?.throwIfAborted?.();\n        return request.enabled?{ok:true,message:\`你好，\${request.name}\`}:{ok:false,message:'已禁用'};\n      },\n    },\n  },\n};\n`;
+  const 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`;
   const license=`MIT License\n\nCopyright (c) ${new Date().getFullYear()} ${name}\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the "Software"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n`;

package/manual/packages/fst-logs/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-logs/README.md

@@ -0,0 +1,67 @@
+# 日志模块
+
+包名：`@mytools/fst-logs`。内部 workspace 包，随 `@yanglaofish/fishtools` 统一交付。
+
+## 职责与边界
+
+运行日志写入器、串行落盘、有界事件缓存、快照、历史分页、保留和体积统计。运行调度由 core 负责。
+
+内部依赖：`@mytools/sdk`。
+## 公开入口
+
+| 导入路径 | 实现位置 |
+| --- | --- |
+| `@mytools/fst-logs` | `./src/run-logs.js` |
+| `@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/package.json` | `./package.json` |
+
+仅依赖 exports 声明的入口，禁止消费者跨包读取 src/bin 私有文件。入口路径由本模块维护，修改协议时同步消费方回归。
+
+## 日志策略与完整记录
+
+`createRunLogs(directory,{projectDir,allowLegacy=false,...policy})` 接受以下字节预算：
+
+| 字段 | 默认值 | 含义 |
+| --- | --- | --- |
+| maxEvents | 1000 | 内存尾部事件条数 |
+| maxMemoryBytes | 1048576 | 尾部事件 JSON 数组总字节，至少 2 |
+| maxEventBytes | 65536 | 单条预览 JSON 字节，至少 256 |
+| maxPendingBytes | 8388608 | 尚未完成的写入任务字节预算 |
+| maxDiskBytes | null | 每次运行所有约定日志文件总字节；null 不主动限制磁盘 |
+
+`start(initial,{onEvent})` 返回 `append(event)`、`finish(state)`、`save(state)`、`snapshot(state)` 与原有 `markdown(state)`。完整事件（含 output）持续顺序写入 `events.jsonl`，完整 Markdown 持续追加到 `run.md`。完成时额外写入完整可解析的 `run.result` JSONL 记录；此记录不重复广播或加入缓存。运行 ID 的归属在开始时写入 `run.meta.json`，结束信息写入 `result.json`。
+
+`onEvent` 与 `snapshot().events` 提供有界预览，巨大字段带 `eventTruncated:true`。每条追加事件有递增 `seq`，缓存被淘汰后消费者仍可识别新事件。快照增加 `eventCount`（包括最终 run.result）、`eventBytes` 和 `eventsTruncated`。快照中的业务 input/output 保持完整，不能以事件摘要替代工作流数据。历史 result.json 对巨大字段保存摘要及对应 `outputTruncated`、`inputTruncated` 等标记；完整最终 output 可从 JSONL 的 run.result 或 Markdown 取得。小字段保持原结构。
+
+快照与历史元数据另有 `stepSummaries`、`stepSummaryBytes`、`stepsTruncated`。步骤摘要按 callPath（缺少时按 stepId）保留最新状态，仅包含类型、定位、动作、时间、序号、耗时及有界原因/错误，不缓存 input/output。步骤摘要使用独立的 maxEvents/maxMemoryBytes 预算，因此两份缓存合计最多为两倍 maxMemoryBytes；单条步骤摘要仍受 maxEventBytes 限制。普通日志淘汰不影响步骤状态；步骤本身超预算淘汰时 stepsTruncated 为 true，展示端应把无法确认的步骤显示为未知状态。
+
+`createStepSummaries(policy)` 从 `/steps` 入口提供同一套摘要缓存，日志写入器与 TUI 共用。
+`append(event)` 更新状态并刷新淘汰顺序；`get(callPath)`、`values()` 和 `snapshot()` 返回副本。
+`snapshot()` 包含上述三个步骤摘要字段，`size` 为保留条数。
+
+`previewRun(record,{maxValueBytes=65536})` 从 `/preview` 入口提供展示与历史元数据共用的结果投影。
+input/output、error、reason 等字段转为有界 JSON 预览，过大时标记 `<字段>Truncated:true`；业务数据对象不变。
+定位字段与 events/stepSummaries 保留，后两者由各自缓存预算负责；展示端应裁去不使用的缓存副本。
+maxValueBytes 至少为 2，连预览本身也容不下时省略字段值并保留截断标记。
+
+队列预算在追加时检查。未等待 append 的插件同样受到预算约束；超限返回 `LOG_QUEUE_LIMIT` 拒绝，并使 finish 失败。拒绝已安装内部处理，调用方仍可 await 观察失败，不会产生未处理拒绝。`LOG_DISK_LIMIT` 表示可选磁盘预算不足，拒绝完整追加而不静默截断。磁盘预算与队列预算都计算 JSONL 和 Markdown。建议插件等待 append，以便磁盘写入形成背压。
+
+`read`/`list` 仅读取受限的 result.json 元数据，运行中的 read 回退到归属元数据；不加载 JSONL 或 Markdown 正文。巨大旧 result.json 超过读取预算时，read 明确返回 `LOG_METADATA_LIMIT`，list 跳过该记录。旧版本缺少归属信息时仅在 `allowLegacy:true` 下可读。
+
+## 分页与文件保护
+
+`page(id,{cursor=0,limit=65536})` 返回 `{text,cursor,nextCursor,hasMore,totalBytes}`，cursor 为 UTF-8 字节位置。limit 至少 4，最大 262144；页尾退回完整字符边界，下一页使用 nextCursor。落在字符内部、负数或超出正文长度的 cursor 返回 `LOG_CURSOR_INVALID`。运行中的分页同样验证项目归属；旧日志没有 Markdown 时使用有界元数据生成正文后分页。分页只读取当前页，原 `markdown(id)` 保留完整读取兼容接口，查看巨大日志应使用 page。
+
+拒绝日志根目录、运行目录或正文文件链接，已有同 ID 日志拒绝覆盖。体积统计和保留策略仅涉及 `run.md`、`events.jsonl`、`result.json`、`run.meta.json` 四个约定文件；业务文件和子目录保持保留。统计不递归、不读取正文。普通文件系统检查不能提供针对恶意并发路径替换的操作系统安全沙箱。
+
+## 维护与验证
+
+本模块负责上述职责的实现、文档与回归；跨模块接口调整需要同时检查生产者与消费者。具体维护人员尚未指定。
+
+在仓库根目录执行：
+
+```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
+```

package/manual/packages/fst-logs/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@mytools/fst-logs",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/run-logs.js",
+  "exports": {
+    ".": "./src/run-logs.js",
+    "./steps": "./src/step-summaries.js",
+    "./preview": "./src/run-preview.js",
+    "./markdown": "./src/markdown-log.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "dependencies": {
+    "@mytools/sdk": "0.1.0"
+  }
+}

package/manual/packages/fst-logs/src/log-bounds.js

@@ -0,0 +1,91 @@
+import {FlowError} from '@mytools/sdk';
+
+export const defaults={maxEvents:1000,maxMemoryBytes:1024*1024,maxEventBytes:64*1024,maxPendingBytes:8*1024*1024,maxDiskBytes:null};
+export function logPolicy(options){
+  const policy={};
+  for(const [key,value] of Object.entries(defaults)){
+    policy[key]=options[key]??value;
+    if(key==='maxDiskBytes'&&policy[key]===null)continue;
+    if(!Number.isSafeInteger(policy[key])||policy[key]<1)throw new FlowError(`日志 ${key} 必须为正整数`);
+  }
+  if(policy.maxEventBytes<256)throw new FlowError('日志 maxEventBytes 至少为 256 字节');
+  if(policy.maxMemoryBytes<2)throw new FlowError('日志 maxMemoryBytes 至少为 2 字节');
+  return policy;
+}
+
+export function utf8Prefix(text,bytes){
+  // 先按字符截取，使临时 Buffer 也受预算限制。
+  const buffer=Buffer.from(text.slice(0,bytes));
+  let end=Math.min(bytes,buffer.length);
+  if(end<buffer.length)while(end>0&&(buffer[end]&0xc0)===0x80)end--;
+  return buffer.subarray(0,end).toString('utf8');
+}
+
+// 估算完整 JSON 的字节量，超预算立即停止；避免为超大消息先复制整份字符串。
+export function jsonSize(value,limit){
+  const seen=new Set();let bytes=0;
+  function count(value){
+    if(bytes>limit)return;
+    if(typeof value==='string'){
+      bytes+=2;
+      for(let i=0;i<value.length&&bytes<=limit;i++){
+        const code=value.charCodeAt(i);
+        if(code<32)bytes+=([8,9,10,12,13].includes(code)?2:6);
+        else if(code===34||code===92)bytes+=2;
+        else if(code<128)bytes++;
+        else if(code<2048)bytes+=2;
+        else if(code>=0xd800&&code<=0xdbff&&value.charCodeAt(i+1)>=0xdc00&&value.charCodeAt(i+1)<=0xdfff){bytes+=4;i++;}
+        else bytes+=(code>=0xd800&&code<=0xdfff)?6:3;
+      }
+    }else if(value===null)bytes+=4;
+    else if(typeof value==='number')bytes+=String(value).length;
+    else if(typeof value==='boolean')bytes+=value?4:5;
+    else if(typeof value==='bigint')throw new TypeError('日志不能序列化 BigInt');
+    else if(value&&typeof value==='object'){
+      if(seen.has(value))throw new TypeError('日志不能序列化循环引用');
+      seen.add(value);bytes+=2;
+      if(Array.isArray(value)){for(const item of value){count(item===undefined?null:item);bytes++;if(bytes>limit)break;}}
+      else for(const key of Object.keys(value)){
+        if(value[key]===undefined||typeof value[key]==='function'||typeof value[key]==='symbol')continue;
+        count(key);bytes+=2;count(value[key]);if(bytes>limit)break;
+      }
+      seen.delete(value);
+    }
+  }
+  count(value);return bytes;
+}
+
+export function preview(value,maxBytes){
+  if(jsonSize(value,maxBytes)<=maxBytes){const text=JSON.stringify(value);if(Buffer.byteLength(text)<=maxBytes)return {value:JSON.parse(text),truncated:false};}
+  let remaining=Math.max(0,maxBytes-64);
+  function copy(item,depth=0){
+    if(remaining<16||depth>12)return undefined;
+    if(typeof item==='string'){
+      const size=jsonSize(item,remaining);
+      if(size<=remaining){remaining-=size;return item;}
+      const text=utf8Prefix(item,Math.max(0,Math.floor((remaining-2)/6)));
+      remaining-=Buffer.byteLength(JSON.stringify(text));return text;
+    }
+    if(item===null||typeof item==='number'||typeof item==='boolean'){remaining-=16;return item;}
+    if(!item||typeof item!=='object')return undefined;
+    remaining-=2;const result=Array.isArray(item)?[]:{};
+    for(const key of Object.keys(item)){
+      const cost=Buffer.byteLength(JSON.stringify(key))+2;
+      if(cost+16>remaining)break;remaining-=cost;
+      const child=copy(item[key],depth+1);if(child!==undefined)result[key]=child;
+    }
+    return result;
+  }
+  return {value:copy(value)??null,truncated:true};
+}
+
+export function eventPreview(event,maxBytes){
+  // 增量序号、类型和归属优先，消息随后；巨大正文不能挤掉路由信息。
+  const ordered={seq:event.seq,type:event.type,runId:event.runId,time:event.time};
+  for(const key of ['callPath','stepId','action','stream'])if(event[key]!==undefined)ordered[key]=event[key];
+  if(event.message!==undefined)ordered.message=event.message;
+  for(const key of Object.keys(event))if(!(key in ordered))ordered[key]=event[key];
+  const result=preview(ordered,maxBytes);
+  if(result.truncated)result.value.eventTruncated=true;
+  return result.value;
+}