@yanglaofish/fishtools 0.4.0 → 0.5.0

package/manual/packages/fst-plugin/src/host.js

@@ -0,0 +1,232 @@
+import { Context } from 'cordis';
+import semver from 'semver';
+import { SDK_VERSION, FlowError } from '@mytools/sdk';
+import { validate, emptyObject } from '@mytools/sdk/schema';
+import {validateDeclarations,validateCommands} from './contracts.js';
+import {prepareEnvironments,platformWarnings} from '@mytools/fst-platform/environments';
+import path from 'node:path';
+import {mkdir} from 'node:fs/promises';
+import {createHash} from 'node:crypto';
+import {createRuntime} from './runtime.js';
+import {pluginError} from '@mytools/sdk/diagnostics';
+import {validateNetworkPolicy,resolveNetworkPolicy,createHttpClient,buildProcessEnv} from '@mytools/fst-platform/network';
+import {resolvePrivilegeRequirement,resolvePrivilegePreflight,checkStaticPrivilege,runPrivilegePreflight} from './privileges.js';
+
+export async function createHost({ plugins = [], config = {}, services = {}, project,network,environmentOverrides={},runtimeEnabled=true,allowUnknownPrivileges=false } = {}) {
+  const currentNetwork=()=>typeof network==='function'?network():network;
+  validateNetworkPolicy(currentNetwork());
+  const ctx = new Context();
+  const actions = new Map();
+  const definitions = new Map();
+  const extensions = new Map();
+  const serviceNames = new Set();
+  const commandNames=new Set(),commands=new Map();
+  function bindContext(context){
+    const {application:ignored,...capabilities}=services;
+    const bound={...capabilities,...context},execute=bound.runProcess;
+    // 面向用户的输出与诊断日志共用持久化通道，只区分默认可见性。
+    bound.print=(message,data)=>Promise.resolve(bound.log?.(message,data,{audience:'user'}));
+    if(typeof execute==='function')bound.runProcess=(file,args,options={})=>{
+      const signal=context.signal&&options.signal?AbortSignal.any([context.signal,options.signal]):context.signal??options.signal;
+      return execute(file,args,{...options,signal,onOutput:async({stream,message})=>{
+        await bound.log?.(message,undefined,{stream});
+        await options.onOutput?.({stream,message});
+      }});
+    };
+    return bound;
+  }
+  async function pluginContext(plugin,action,context){
+    const bound=bindContext(context);
+    const projectDir=project?.directory??services.application?.projectDir;
+    if(bound.fs){
+      const probe=bound.fs,resolve=file=>typeof file==='string'&&!/^[/\\]{2}/.test(file)?path.resolve(projectDir??process.cwd(),file):file;
+      const options=value=>({...value,signal:context.signal&&value?.signal?AbortSignal.any([context.signal,value.signal]):context.signal??value?.signal});
+      bound.fs={stat:(file,value)=>probe.stat(resolve(file),options(value)),readDirectory:(file,value)=>probe.readDirectory(resolve(file),options(value))};
+    }
+    // 固定长度摘要避免 scoped 包名分隔符、大小写碰撞及合法长包名超出文件名上限。
+    const readOnly=project?.readOnly??services.application?.project?.readOnly;
+    const stateDir=projectDir&&!readOnly?path.join(projectDir,'.flow','plugin-state',createHash('sha256').update(plugin.id).digest('hex')):undefined;
+    if(stateDir)await mkdir(stateDir,{recursive:true});
+    for(const message of platformWarnings(plugin))await bound.log?.(message,{code:'PLATFORM_MISMATCH'},{audience:'user'});
+    const environments=await prepareEnvironments(plugin,action,environmentOverrides[plugin.id],{cwd:projectDir??process.cwd()});
+    context.signal?.throwIfAborted();
+    const policy=context.networkPolicy??currentNetwork();
+    const actionName=action?.id?.slice(plugin.id.length+1);
+    const resolved=resolveNetworkPolicy(policy,{pluginId:plugin.id,actionId:actionName});
+    if(policy?.default||policy?.plugins?.[plugin.id])await bound.log?.('网络代理规则',{mode:resolved.mode,...(resolved.profile?{profile:resolved.profile}:{})});
+    const http=createHttpClient(resolved,{signal:context.signal});
+    if(typeof bound.runProcess==='function'){
+      const execute=bound.runProcess;
+      bound.runProcess=(file,args,options={})=>execute(file,args,{...options,env:buildProcessEnv(resolved,{overrides:options.env})});
+    }
+    bound.http={fetch:(input,options)=>http.fetch(input,options)};
+    return {capabilities:{...bound,projectDir,stateDir,environments},close:()=>http.close()};
+  }
+  async function checkPrivilege(plugin,actionName,input,context,fs){
+    const requirement=resolvePrivilegeRequirement(plugin,actionName);
+    if(!requirement.declared)return requirement;
+    const staticResult=checkStaticPrivilege(requirement);
+    let result=staticResult;
+    if(staticResult.status==='unknown')result=await runPrivilegePreflight(resolvePrivilegePreflight(plugin,actionName),input,{signal:context.signal,fs});
+    context.signal?.throwIfAborted();
+    if(result.status==='blocked')throw new FlowError(`权限不足：${result.reason??requirement.reason??plugin.id}`,{code:'INSUFFICIENT_PRIVILEGE',details:{plugin:plugin.id,action:actionName,requirement,result}});
+    if(result.status==='unknown'&&!context.allowUnknownPrivileges)throw new FlowError(`权限尚未确认：${result.reason??requirement.reason??plugin.id}`,{code:'PRIVILEGE_UNVERIFIED',details:{plugin:plugin.id,action:actionName,requirement,result}});
+    if(result.status==='unknown')await context.log?.('权限状态未确认，按本次选择继续运行',{plugin:plugin.id,action:actionName,reason:result.reason},{audience:'user'});
+    return requirement;
+  }
+  for (const entry of plugins) {
+    const plugin = entry.plugin ?? entry;
+    validateDeclarations(plugin);validateCommands(plugin,commandNames);
+    if (!plugin.id || definitions.has(plugin.id)) throw new FlowError(`插件标识缺失或重复：${plugin.id}`, {code:'VALIDATION'});
+    if (!semver.satisfies(SDK_VERSION, plugin.sdk ?? '^0.1.0')) throw new FlowError(`插件 ${plugin.id} 与 SDK ${SDK_VERSION} 不兼容`, {code:'VALIDATION'});
+    for(const [name,action] of Object.entries(plugin.actions??{})){
+      if(typeof action?.run!=='function')throw new FlowError(`动作 ${plugin.id}:${name} 缺少执行函数`);
+    }
+    for(const [name,extension] of Object.entries(plugin.services??{})){
+      if(serviceNames.has(name))throw new FlowError(`服务重复：${name}`);
+      if(typeof extension!=='function')throw new FlowError(`服务 ${name} 缺少执行函数`);
+      serviceNames.add(name);
+    }
+    definitions.set(plugin.id, {...plugin, root:entry.root});
+  }
+  const settingsById=new Map();
+  for (const plugin of definitions.values()) {
+    for (const [id, range] of Object.entries(plugin.dependencies ?? {})) {
+      if (!definitions.has(id) || !semver.satisfies(definitions.get(id).version,range)) throw new FlowError(`插件 ${plugin.id} 缺少兼容依赖 ${id}@${range}`,{code:'VALIDATION'});
+    }
+    const settings = validate(plugin.config, config[plugin.id] ?? {}, `${plugin.id} 配置`);
+    settingsById.set(plugin.id,settings);
+  }
+  const runtime=createRuntime(ctx,definitions,{enabled:runtimeEnabled});
+  let unusable=false;
+  const assertReadable=()=>{
+    if(unusable)throw new FlowError('插件更新和恢复均失败，请重启应用',{code:'PLUGIN_RUNTIME_UNUSABLE'});
+  };
+  const assertHealthy=()=>{runtime.assertOpen();assertReadable();};
+  function registerPlugin(plugin,settings){
+    const registered=plugin.runtime?{...plugin,runtime:{...plugin.runtime,apply:async(scope,value)=>{
+      await checkPrivilege(plugin,undefined,{}, {allowUnknownPrivileges},services.fs);
+      return plugin.runtime.apply(scope,value);
+    }}}:plugin;
+    runtime.register(registered,settings,scope=>{
+    for(const [name,command] of Object.entries(plugin.commands??{})){
+      const action=command.action?plugin.actions[command.action]:command;
+      commands.set(name,{...command,name,plugin:plugin.id,input:action.input,output:action.output,description:command.description??action.description??action.title??name,config:settings});
+      scope.on('dispose',()=>commands.delete(name));
+    }
+      for (const [name, action] of Object.entries(plugin.actions ?? {})) {
+        const id = `${plugin.id}:${name}`;
+        if (typeof action.run !== 'function') throw new FlowError(`动作 ${id} 缺少执行函数`);
+        actions.set(id, {...action, id, plugin:plugin.id, config:settings, root:plugin.root});
+        scope.on('dispose', () => actions.delete(id));
+      }
+      for (const [name, extension] of Object.entries(plugin.services ?? {})) {
+        if (extensions.has(name)) throw new FlowError(`服务重复：${name}`);
+        extensions.set(name, {run:extension,plugin:plugin.id});
+        scope.on('dispose',()=>extensions.delete(name));
+      }
+    });
+  }
+  try{
+  for (const plugin of definitions.values())registerPlugin(plugin,settingsById.get(plugin.id));
+  await runtime.start();
+  }catch(error){
+    try{await runtime.close();}catch(cleanup){if(cleanup.message!==error.message)throw new AggregateError([error,cleanup],`${error.message}；${cleanup.message}`);}
+    throw error;
+  }
+  return {
+    definitions, actions,
+    assertHealthy,
+    invalidate(){unusable=true;},
+    get warnings(){return [...definitions.values()].flatMap(plugin=>platformWarnings(plugin).map(message=>({plugin:plugin.id,message})));},
+    get hasRuntime(){return runtime.hasRuntime;},
+    runtimeStatus:()=>runtime.status(),
+    async replace({plugins:nextEntries,config:nextConfig={},affected=[]}){
+      assertHealthy();
+      const selected=new Set(affected);
+      // 候选宿主只做声明、依赖、配置和服务图校验，不激活候选 runtime。
+      const candidate=await createHost({plugins:nextEntries,config:nextConfig,services,project,network,environmentOverrides,runtimeEnabled:false,allowUnknownPrivileges});
+      const next=new Map(candidate.definitions);
+      await candidate.close();
+      const oldDefinitions=new Map([...definitions].filter(([id])=>selected.has(id)));
+      const oldSettings=new Map([...settingsById].filter(([id])=>selected.has(id)));
+      const switchDefinitions=async(targets,settings)=>{
+        await runtime.remove(selected);
+        for(const id of selected){definitions.delete(id);settingsById.delete(id);}
+        for(const [id,plugin] of targets)if(selected.has(id)){
+          definitions.set(id,plugin);
+          settingsById.set(id,settings.get(id));
+        }
+        runtime.reindex();
+        for(const [id,plugin] of definitions)if(selected.has(id))registerPlugin(plugin,settingsById.get(id));
+        await runtime.ready();
+      };
+      const nextSettings=new Map();
+      for(const [id,plugin] of next)if(selected.has(id))nextSettings.set(id,validate(plugin.config,nextConfig[id]??{},`${id} 配置`));
+      try{await switchDefinitions(next,nextSettings);}
+      catch(error){
+        try{
+          runtime.clearErrors();
+          await switchDefinitions(oldDefinitions,oldSettings);
+        }catch(recovery){unusable=true;throw new AggregateError([error,recovery],`插件更新失败且恢复失败：${error.message}；${recovery.message}`);}
+        throw error;
+      }
+    },
+    commands(){assertReadable();return [...commands.values()].map(({run,preflight,config,...metadata})=>structuredClone(metadata));},
+    async invokeCommand(name,input,context={}){
+      assertHealthy();
+      const command=commands.get(name);if(!command)throw new FlowError(`命令不存在：/${name}`);
+      if(command.action)return this.invoke(`${command.plugin}:${command.action}`,input,context);
+      if(!context.ui)throw new FlowError(`交互命令 /${name} 需要在 TUI 中调用`);
+      const plugin=definitions.get(command.plugin);
+      try{
+      const getService=runtime.bindServices(plugin.id);
+      context.signal?.throwIfAborted();
+      const checked=validate(command.input??emptyObject,input,`/${name} 输入`);
+      const bound=await pluginContext(plugin,undefined,context);
+      let result;
+      try{
+        await checkPrivilege(plugin,undefined,checked,context,bound.capabilities.fs);
+        result=await command.run(checked,{...bound.capabilities,getService,config:command.config,resourceDir:plugin.root});
+      }finally{await bound.close();}
+      context.signal?.throwIfAborted();
+      return validate(command.output,JSON.parse(JSON.stringify(result??{})),`/${name} 输出`,{useDefaults:false});
+      }catch(cause){throw pluginError(cause,{plugin:plugin.id,command:`/${name}`});}
+    },
+    catalog() { assertReadable();return [...actions.values()].map(({run,preflight,config,root,...metadata})=>structuredClone(metadata)); },
+    async invoke(id, input, context = {}) {
+      assertHealthy();
+      const action = actions.get(id);
+      if (!action) throw new FlowError(`动作不存在：${id}`, {code:'VALIDATION'});
+      try{
+      const getService=runtime.bindServices(action.plugin);
+      context.signal?.throwIfAborted();
+      const checked=validate(action.input ?? emptyObject,input,`${id} 输入`);
+      const plugin=definitions.get(action.plugin),bound=await pluginContext(plugin,action,context);
+      let result;
+      try{
+        await checkPrivilege(plugin,id.slice(plugin.id.length+1),checked,context,bound.capabilities.fs);
+        result=await action.run(checked,{...bound.capabilities,getService, config:action.config, resourceDir:action.root});
+      }finally{await bound.close();}
+      context.signal?.throwIfAborted();
+      // 通过 JSON 边界验证返回值，避免函数、循环引用等进入工作流状态。
+      const encoded = JSON.stringify(result);
+      if (encoded === undefined) throw new FlowError(`${id} 输出必须可 JSON 序列化`);
+      return validate(action.output, JSON.parse(encoded),`${id} 输出`,{useDefaults:false});
+      }catch(cause){throw pluginError(cause,{plugin:action.plugin,action:id});}
+    },
+    async service(name,options) {
+      assertHealthy();
+      if (!extensions.has(name)) throw new FlowError(`未安装提供 ${name} 的插件`);
+      const extension=extensions.get(name);runtime.assertActive(extension.plugin);
+      const plugin=definitions.get(extension.plugin),bound=await pluginContext(plugin,undefined,{});
+      try{
+        await checkPrivilege(plugin,undefined,{}, {allowUnknownPrivileges},bound.capabilities.fs);
+        const result=await extension.run({...services,...bound.capabilities,application:services.application},options);
+        if(typeof result?.close!=='function'){await bound.close();return result;}
+        return {...result,close:async()=>{try{await result.close();}finally{await bound.close();}}};
+      }catch(error){await bound.close();throw error;}
+    },
+    close:()=>runtime.close(),
+  };
+}

package/manual/packages/fst-plugin/src/loader.js

@@ -0,0 +1,21 @@
+import {createRequire} from 'node:module';
+import {pathToFileURL} from 'node:url';
+import {access} from 'node:fs/promises';
+import path from 'node:path';
+import {readJson} from '@mytools/fst-platform/json';
+export async function loadPlugin(spec,base) {
+  const req=createRequire(path.join(base,'package.json'));
+  let entry;
+  if(path.isAbsolute(spec) || spec.startsWith('.')) {
+    const root=path.resolve(base,spec), pkg=await readJson(path.join(root,'package.json'));
+    entry=path.resolve(root,pkg.main??'index.js');
+  } else {
+    try {entry=req.resolve(spec);} catch {entry=createRequire(import.meta.url).resolve(spec);}
+  }
+  let root=path.dirname(entry);
+  while(root!==path.dirname(root)) {
+    try {await access(path.join(root,'package.json'));break;} catch {root=path.dirname(root);}
+  }
+  const module=await import(pathToFileURL(entry).href);
+  return {plugin:module.default,root};
+}

package/manual/packages/fst-plugin/src/privileges.js

@@ -0,0 +1,91 @@
+// 权限声明按平台逐项覆盖；返回纯数据，避免把插件函数带入元数据。
+export function resolvePrivilegeRequirement(plugin,actionName,platform=process.platform){
+  const action=actionName===undefined?undefined:plugin.actions?.[actionName];
+  const actionRequirement=action?.requirements?.privilege?.[platform];
+  const pluginRequirement=plugin.requirements?.privilege?.[platform];
+  const requirement=actionRequirement??pluginRequirement;
+  if(!requirement)return {declared:false,platform,source:null,level:null};
+  const result={declared:true,platform,source:actionRequirement?'action':'plugin',level:requirement.level};
+  if(requirement.reason!==undefined)result.reason=requirement.reason;
+  if(requirement.remediation!==undefined)result.remediation=requirement.remediation;
+  return result;
+}
+
+// 动作探针优先，插件探针可为动作提供默认实现。
+export function resolvePrivilegePreflight(plugin,actionName){
+  return (actionName===undefined?undefined:plugin.actions?.[actionName]?.preflight)??plugin.preflight;
+}
+
+export function checkStaticPrivilege(requirement,options={}){
+  if(!requirement?.declared)return {status:'unknown',reason:'未声明权限要求'};
+  if(requirement.level==='user')return {status:'ok'};
+  if(requirement.level==='root'&&requirement.platform==='linux'){
+    const uid=Object.hasOwn(options,'uid')?options.uid:process.getuid?.();
+    if(uid===0)return {status:'ok'};
+    if(Number.isInteger(uid)&&uid>0)return {status:'blocked',reason:requirement.reason,remediation:requirement.remediation};
+  }
+  if(requirement.level==='administrator'&&requirement.platform==='win32'){
+    if(options.isAdministrator===true)return {status:'ok'};
+    if(options.isAdministrator===false)return {status:'blocked',reason:requirement.reason,remediation:requirement.remediation};
+  }
+  return {status:'unknown',reason:requirement.reason,remediation:requirement.remediation};
+}
+
+function normalizeResult(result){
+  if(!result||typeof result!=='object'||Array.isArray(result)||!['ok','blocked','unknown'].includes(result.status))return {status:'unknown',reason:'权限预检返回无效结果'};
+  const normalized={status:result.status};
+  for(const field of ['reason','remediation']){
+    if(result[field]===undefined)continue;
+    if(typeof result[field]!=='string'||!result[field].trim())return {status:'unknown',reason:'权限预检返回无效结果'};
+    normalized[field]=result[field];
+  }
+  return normalized;
+}
+
+function readOnlyProbe(fs,signal){
+  if(!fs)return undefined;
+  const result={};
+  for(const name of ['stat','readDirectory']){
+    if(typeof fs[name]!=='function')continue;
+    result[name]=(file,options={})=>{
+      const combined=options?.signal?AbortSignal.any([signal,options.signal]):signal;
+      return fs[name](file,{...options,signal:combined});
+    };
+  }
+  return Object.freeze(result);
+}
+
+function preflightFailure(error){
+  let detail;
+  try{detail=String(error?.message??error);}catch{detail='未知错误';}
+  return {status:'unknown',reason:`权限预检失败：${detail}`};
+}
+
+// 探针错误与超时都收敛为待确认；同步死循环无法由计时器强制中断。
+export async function runPrivilegePreflight(preflight,input,{platform=process.platform,signal,fs,timeoutMs=5000}={}){
+  if(typeof preflight!=='function')return {status:'unknown',reason:'未提供权限预检'};
+  if(signal?.aborted)return {status:'unknown',reason:'权限预检已取消'};
+  const controller=new AbortController();
+  const duration=Number.isFinite(timeoutMs)&&timeoutMs>0?timeoutMs:5000;
+  let timer,abortHandler;
+  const interrupted=new Promise(resolve=>{
+    timer=setTimeout(()=>{
+      controller.abort(new Error('权限预检超时'));
+      resolve({status:'unknown',reason:'权限预检超时'});
+    },duration);
+    if(signal){
+      abortHandler=()=>{
+        controller.abort(signal.reason);
+        resolve({status:'unknown',reason:'权限预检已取消'});
+      };
+      signal.addEventListener('abort',abortHandler,{once:true});
+      if(signal.aborted)abortHandler();
+    }
+  });
+  const work=Promise.resolve().then(()=>preflight(input,{platform,signal:controller.signal,fs:readOnlyProbe(fs,controller.signal)})).then(normalizeResult).catch(preflightFailure);
+  try{return await Promise.race([work,interrupted]);}
+  finally{
+    clearTimeout(timer);
+    if(signal&&abortHandler)signal.removeEventListener('abort',abortHandler);
+  }
+}

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

@@ -32,7 +32,9 @@ export function validateRuntimes(definitions,ctx){
 }
 
 export function createRuntime(ctx,definitions,{enabled=true}={}){
-  const {providers,ordered}=validateRuntimes(definitions,ctx);
+  // 动态更新时 ctx 已含运行服务；声明检查始终以 Cordis 原生名称为准。
+  const reservedContext=new ctx.constructor();
+  let graph=validateRuntimes(definitions,reservedContext);
   const forks=new Map(),scopes=new Map(),errors=[],pending=new Set();let closing;
   const record=(id,error)=>errors.push({plugin:id,message:error?.message??String(error)});
   const track=(id,callback)=>{
@@ -52,7 +54,7 @@ export function createRuntime(ctx,definitions,{enabled=true}={}){
   const drain=async()=>{while(pending.size)await Promise.all([...pending]);};
   const failure=()=>new FlowError(`插件生命周期失败：${errors.map(e=>`${e.plugin}: ${e.message}`).join('；')}`,{code:'PLUGIN_RUNTIME',details:{errors:structuredClone(errors)}});
   const runtime={
-    hasRuntime:[...definitions.values()].some(p=>p.runtime),
+    get hasRuntime(){return [...definitions.values()].some(p=>p.runtime);},
     register(plugin,settings,register){
       if(!enabled&&plugin.runtime)return;
       const fork=ctx.plugin({name:plugin.id,inject:plugin.runtime?.inject??[],apply(scope){
@@ -95,10 +97,24 @@ export function createRuntime(ctx,definitions,{enabled=true}={}){
       forks.set(plugin.id,fork);
     },
     async start(){
+      await ctx.start();await runtime.ready();
+    },
+    reindex(){graph=validateRuntimes(definitions,reservedContext);},
+    clearErrors(){errors.length=0;},
+    async remove(ids){
+      // 先撤销消费者再撤销提供者；旧作用域清理结束后才能注册新作用域。
+      const selected=new Set(ids);
+      for(const id of [...graph.ordered].reverse())if(selected.has(id)){
+        forks.get(id)?.dispose();forks.delete(id);await drain();
+      }
+      if(errors.length)throw failure();
+    },
+    async ready(){
+      // 动态注册后的 ready 监听尚未消费；Cordis start 会取出新监听并等待任务。
       await ctx.start();await drain();
       if(errors.length)throw failure();
       if(!enabled)return;
-      for(const [name,id] of providers)if(ctx.get(name)==null)throw new FlowError(`${id} 未提供声明的服务：${name}`,{code:'PLUGIN_RUNTIME'});
+      for(const [name,id] of graph.providers)if(ctx.get(name)==null)throw new FlowError(`${id} 未提供声明的服务：${name}`,{code:'PLUGIN_RUNTIME'});
       for(const p of runtime.status())if(p.status!=='ready')throw new FlowError(`${p.id} 服务尚未就绪：${p.missing.join(', ')}`,{code:'PLUGIN_RUNTIME'});
     },
     status(){return [...definitions.values()].map(p=>{
@@ -127,7 +143,7 @@ export function createRuntime(ctx,definitions,{enabled=true}={}){
     close(){
       closing??=Promise.resolve().then(async()=>{
         // 消费者先关闭，等待其使用完服务；注册撤销和依赖停用由 Cordis 执行。
-        for(const id of [...ordered].reverse()){forks.get(id)?.dispose();await drain();}
+        for(const id of [...graph.ordered].reverse()){forks.get(id)?.dispose();await drain();}
         await ctx.stop();await drain();if(errors.length)throw failure();
       });return closing;
     },

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

@@ -0,0 +1,28 @@
+# 工作流模块
+
+包名：`@mytools/fst-workflow`。内部 workspace 包，随 `@yanglaofish/fishtools` 统一交付。
+
+## 职责与边界
+
+步骤执行、控制流和条件语义。工作流文件和闭包解析由 workspace 负责，运行管理由 core 负责。
+
+内部依赖：`@mytools/sdk`。
+## 公开入口
+
+| 导入路径 | 实现位置 |
+| --- | --- |
+| `@mytools/fst-workflow` | `./src/engine.js` |
+| `@mytools/fst-workflow/control` | `./src/control.js` |
+| `@mytools/fst-workflow/package.json` | `./package.json` |
+
+仅依赖 exports 声明的入口，禁止消费者跨包读取 src/bin 私有文件。入口路径由本模块维护，修改协议时同步消费方回归。
+
+## 维护与验证
+
+本模块负责上述职责的实现、文档与回归；跨模块接口调整需要同时检查生产者与消费者。具体维护人员尚未指定。
+
+在仓库根目录执行：
+
+```sh
+node --test tests/modules.test.js tests/workflows.test.js tests/control-flow.test.js
+```

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

@@ -0,0 +1,24 @@
+{
+  "name": "@mytools/fst-workflow",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/engine.js",
+  "exports": {
+    ".": "./src/engine.js",
+    "./control": "./src/control.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "dependencies": {
+    "@mytools/sdk": "0.1.0"
+  }
+}

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

@@ -1,8 +1,9 @@
 import {isDeepStrictEqual} from 'node:util';
 import {FlowError} from '@mytools/sdk';
-import {bind,references} from './validation.js';
+import {bind,references} from '@mytools/sdk/schema';
 
-export const conditionOperators=['eq','ne','gt','gte','lt','lte','contains','exists'];
+import {conditionOperators} from '@mytools/sdk/conditions';
+export {conditionOperators};
 const invalid=message=>{throw new FlowError(message,{code:'VALIDATION'});};
 export function validateCondition(condition,visit=()=>{},depth=0){
   if(depth>32||!condition||typeof condition!=='object'||Array.isArray(condition))invalid('条件必须是有限深度的结构化对象');

package/manual/packages/{core → fst-workflow}/src/engine.js

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { FlowError } from '@mytools/sdk';
-import { bind, validate, emptyObject } from './validation.js';
-import {errorRecord} from './diagnostics.js';
+import { bind, validate, emptyObject } from '@mytools/sdk/schema';
+import {errorRecord} from '@mytools/sdk/diagnostics';
 import {evaluateCondition,childLists} from './control.js';
 
 export async function runWorkflow({store,host,id,input={},signal,onEvent=()=>{},runId=randomUUID(),context={}}) {

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

@@ -0,0 +1,32 @@
+# 工作区模块
+
+包名：`@mytools/fst-workspace`。内部 workspace 包，随 `@yanglaofish/fishtools` 统一交付。
+
+## 职责与边界
+
+项目初始化、模板、工作流文件、插件安装批次、租约、开发引用及便携工作区。插件执行由 plugin 负责，系统调用由 platform 负责。
+
+内部依赖：`@mytools/sdk`、`@mytools/fst-platform`、`@mytools/fst-plugin`、`@mytools/fst-workflow`。
+## 公开入口
+
+| 导入路径 | 实现位置 |
+| --- | --- |
+| `@mytools/fst-workspace` | `./src/index.js` |
+| `@mytools/fst-workspace/workflows` | `./src/workflows.js` |
+| `@mytools/fst-workspace/project` | `./src/project.js` |
+| `@mytools/fst-workspace/plugins` | `./src/plugins.js` |
+| `@mytools/fst-workspace/installations` | `./src/plugin-installations.js` |
+| `@mytools/fst-workspace/bundles` | `./src/bundle-workspace.js` |
+| `@mytools/fst-workspace/package.json` | `./package.json` |
+
+仅依赖 exports 声明的入口，禁止消费者跨包读取 src/bin 私有文件。入口路径由本模块维护，修改协议时同步消费方回归。
+
+## 维护与验证
+
+本模块负责上述职责的实现、文档与回归；跨模块接口调整需要同时检查生产者与消费者。具体维护人员尚未指定。
+
+在仓库根目录执行：
+
+```sh
+node --test tests/modules.test.js tests/bundle-workspace.test.js tests/plugin-development-cycle.test.js tests/project-config-concurrency.test.js
+```

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

@@ -0,0 +1,34 @@
+{
+  "name": "@mytools/fst-workspace",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./workflows": "./src/workflows.js",
+    "./project": "./src/project.js",
+    "./plugins": "./src/plugins.js",
+    "./installations": "./src/plugin-installations.js",
+    "./bundles": "./src/bundle-workspace.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "templates",
+    "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",
+    "@mytools/fst-workflow": "0.1.0",
+    "tar": "7.5.22",
+    "yaml": "2.9.1"
+  }
+}

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

@@ -5,7 +5,7 @@ import {constants} from 'node:fs';
 import {randomUUID} from 'node:crypto';
 import {setTimeout} from 'node:timers/promises';
 import {FlowError} from '@mytools/sdk';
-import {readJson} from './plugins.js';
+import {readJson} from '@mytools/fst-platform/json';
 
 export async function prepareBundleWorkspace(bundleRoot,requested){
   bundleRoot=path.resolve(bundleRoot);

package/manual/packages/fst-workspace/src/index.js

@@ -0,0 +1,3 @@
+export {WorkflowStore} from './workflows.js';
+export {initializeProject,resolveProject} from './project.js';
+export {prepareBundleWorkspace} from './bundle-workspace.js';