@yanglaofish/fishtools 0.1.4 → 0.3.0

package/manual/packages/core/src/host.js

@@ -0,0 +1,124 @@
+import { Context } from 'cordis';
+import semver from 'semver';
+import { SDK_VERSION, FlowError } from '@mytools/sdk';
+import { validate, emptyObject } from './validation.js';
+import {validateDeclarations,validateCommands} from './contracts.js';
+import {resolveEnvironments} from './environments.js';
+import {createRuntime} from './runtime.js';
+import {pluginError} from './diagnostics.js';
+
+export async function createHost({ plugins = [], config = {}, services = {}, environmentOverrides={},runtimeEnabled=true } = {}) {
+  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 bound={...services,...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;
+  }
+  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});
+  try{
+  for (const plugin of definitions.values()) {
+    const settings=settingsById.get(plugin.id);
+    runtime.register(plugin,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));
+      }
+    });
+  }
+  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,
+    hasRuntime:runtime.hasRuntime,
+    runtimeStatus:()=>runtime.status(),
+    commands(){return [...commands.values()].map(({run,config,...metadata})=>structuredClone(metadata));},
+    async invokeCommand(name,input,context={}){
+      runtime.assertOpen();
+      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 result=await command.run(validate(command.input??emptyObject,input,`/${name} 输入`),{...bindContext(context),getService,config:command.config,resourceDir:plugin.root,environments:resolveEnvironments(plugin,undefined,environmentOverrides[plugin.id])});
+      context.signal?.throwIfAborted();
+      return validate(command.output,JSON.parse(JSON.stringify(result??{})),`/${name} 输出`);
+      }catch(cause){throw pluginError(cause,{plugin:plugin.id,command:`/${name}`});}
+    },
+    catalog() { return [...actions.values()].map(({run,config,root,...metadata})=>structuredClone(metadata)); },
+    async invoke(id, input, context = {}) {
+      runtime.assertOpen();
+      const action = actions.get(id);
+      if (!action) throw new FlowError(`动作不存在：${id}`, {code:'VALIDATION'});
+      try{
+      const getService=runtime.bindServices(action.plugin);
+      context.signal?.throwIfAborted();
+      const result = await action.run(validate(action.input ?? emptyObject,input,`${id} 输入`), {...bindContext(context),getService, config:action.config, resourceDir:action.root,environments:resolveEnvironments(definitions.get(action.plugin),action,environmentOverrides[action.plugin])});
+      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} 输出`);
+      }catch(cause){throw pluginError(cause,{plugin:action.plugin,action:id});}
+    },
+    async service(name,options) {
+      runtime.assertOpen();
+      if (!extensions.has(name)) throw new FlowError(`未安装提供 ${name} 的插件`);
+      const extension=extensions.get(name);runtime.assertActive(extension.plugin);
+      return extension.run(services,options);
+    },
+    close:()=>runtime.close(),
+  };
+}

package/manual/packages/core/src/runtime.js

@@ -0,0 +1,135 @@
+import {FlowError} from '@mytools/sdk';
+
+// 静态声明用于诊断与打包，运行时激活仍由 Cordis inject 驱动。
+export function validateRuntimes(definitions,ctx){
+  const providers=new Map(),ordered=[],visiting=new Set(),visited=new Set();
+  for(const p of definitions.values()){
+    const r=p.runtime;if(r===undefined)continue;
+    if(!r||typeof r.apply!=='function')throw new FlowError(`${p.id} runtime 必须提供 apply`);
+    for(const key of ['provides','inject']){
+      const names=r[key]??[];
+      if(!Array.isArray(names)||names.some(n=>typeof n!=='string'||!/^\w[\w.-]*$/.test(n)||n in ctx)||new Set(names).size!==names.length)throw new FlowError(`${p.id} runtime.${key} 服务名称无效或重复`);
+    }
+    for(const name of r.provides??[]){
+      if(providers.has(name))throw new FlowError(`服务重复：${name}（${providers.get(name)}、${p.id}）`);
+      providers.set(name,p.id);
+    }
+  }
+  function visit(id){
+    if(visiting.has(id))throw new FlowError(`服务循环依赖：${[...visiting,id].join(' → ')}`);
+    if(visited.has(id))return;
+    visiting.add(id);const p=definitions.get(id);
+    for(const name of p.runtime?.inject??[]){
+      const owner=providers.get(name);
+      if(!owner)throw new FlowError(`${id} 缺少服务提供者：${name}`);
+      if(owner!==id&&!Object.hasOwn(p.dependencies??{},owner))throw new FlowError(`${id} 的 dependencies 必须声明服务 ${name} 的提供者 ${owner}`);
+      visit(owner);
+    }
+    visiting.delete(id);visited.add(id);ordered.push(id);
+  }
+  for(const id of definitions.keys())visit(id);
+  return {providers,ordered};
+}
+
+export function createRuntime(ctx,definitions,{enabled=true}={}){
+  const {providers,ordered}=validateRuntimes(definitions,ctx);
+  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)=>{
+    // 同步撤销注册，只有异步尾部进入等待集合，避免服务重激活时旧清理删掉新注册。
+    let result;try{result=callback();}catch(error){record(id,error);return;}
+    const task=Promise.resolve(result).catch(e=>record(id,e)).finally(()=>pending.delete(task));
+    pending.add(task);return task;
+  };
+  // 3.18.1 的 reset 会调用 dispose，但不等待 Promise；此适配只补齐等待和错误传播。
+  ctx.on('internal/listener',function(name,listener,options){
+    if(name!=='dispose')return;
+    const wrapped=()=>track(this.runtime.name??'host',listener),list=this.scope.disposables;
+    list[options.prepend?'unshift':'push'](wrapped);
+    return ()=>{const i=list.indexOf(wrapped);if(i>=0)list.splice(i,1);};
+  },{prepend:true,global:true});
+  ctx.on('internal/error',function(error){record(this?.runtime?.name??'host',error);},{global: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),
+    register(plugin,settings,register){
+      if(!enabled&&plugin.runtime)return;
+      const fork=ctx.plugin({name:plugin.id,inject:plugin.runtime?.inject??[],apply(scope){
+        const activation={scope,active:true,tasks:new Set(),disposers:[]};
+        scopes.set(plugin.id,activation);
+        const initialize=callback=>{
+          const task=Promise.resolve().then(callback);
+          activation.tasks.add(task);
+          return task.finally(()=>activation.tasks.delete(task));
+        };
+        scope.on('dispose',()=>{
+          activation.active=false;
+          if(scopes.get(plugin.id)===activation)scopes.delete(plugin.id);
+          return (async()=>{
+            // 初始化可能仍在取得资源；先等其结束，再执行本次激活登记的清理。
+            while(activation.tasks.size)await Promise.allSettled([...activation.tasks]);
+            for(const dispose of activation.disposers.splice(0)){
+              try{await dispose();}catch(error){record(plugin.id,error);}
+            }
+          })();
+        });
+        register(scope);
+        const managed=new Proxy(scope,{get(target,name){
+          if(name==='on')return(event,listener,options={})=>{
+            if(event==='dispose'){
+              activation.disposers[options.prepend?'unshift':'push'](listener);
+              return()=>{const i=activation.disposers.indexOf(listener);if(i>=0)activation.disposers.splice(i,1);};
+            }
+            if(event==='ready')return scope.on(event,()=>initialize(listener),options);
+            return scope.on(event,listener,options);
+          };
+          if(name==='set')return(...args)=>{
+            if(!activation.active||closing)throw new FlowError(`${plugin.id} 激活作用域已失效`);
+            return scope.set(...args);
+          };
+          return Reflect.get(target,name);
+        }});
+        if(plugin.runtime)scope.on('ready',()=>initialize(()=>plugin.runtime.apply(managed,settings)));
+      }});
+      forks.set(plugin.id,fork);
+    },
+    async 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 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=>{
+      const state=forks.get(p.id)?.runtime.status,missing=(p.runtime?.inject??[]).filter(n=>ctx.get(n)==null);
+      const error=errors.findLast(e=>e.plugin===p.id);
+      return {id:p.id,status:closing||!enabled&&p.runtime?'stopped':state===3?'failed':state===2&&forks.get(p.id)?.runtime.isActive&&!missing.length?'ready':'pending',missing,...(error?{error:error.message}:{})};
+    });},
+    assertActive(id){
+      if(closing)throw new FlowError('插件宿主已停止');
+      if(runtime.status().find(p=>p.id===id)?.status!=='ready'||!scopes.has(id))throw new FlowError(`插件 ${id} 当前不可用`,{code:'PLUGIN_RUNTIME',details:runtime.status().find(p=>p.id===id)});
+    },
+    bindServices(id){
+      runtime.assertActive(id);const activation=scopes.get(id);
+      return name=>runtime.getService(id,name,activation);
+    },
+    getService(id,name,activation){
+      if(!activation?.active||scopes.get(id)!==activation)throw new FlowError(`${id} 激活作用域已失效`);
+      runtime.assertActive(id);
+      const p=definitions.get(id);
+      if(![...(p.runtime?.inject??[]),...(p.runtime?.provides??[])].includes(name))throw new FlowError(`${id} 未声明服务：${name}`);
+      const value=activation.scope.get(name);
+      if(value==null)throw new FlowError(`${id} 服务不可用：${name}`);
+      return value;
+    },
+    assertOpen(){if(closing)throw new FlowError('插件宿主已停止');},
+    close(){
+      closing??=Promise.resolve().then(async()=>{
+        // 消费者先关闭，等待其使用完服务；注册撤销和依赖停用由 Cordis 执行。
+        for(const id of [...ordered].reverse()){forks.get(id)?.dispose();await drain();}
+        await ctx.stop();await drain();if(errors.length)throw failure();
+      });return closing;
+    },
+  };return runtime;
+}

package/manual/packages/core/src/terminal/run-feed.js

@@ -0,0 +1,78 @@
+import {readableValue,readableError,readableTimeline} from './run-presentation.js';
+import {runStatuses} from './run-viewer.js';
+
+// 主面板按事件到达顺序追加；运行快照另存，配置菜单不会清掉执行记录。
+export class RunFeed{
+  constructor(refresh){this.refresh=refresh;this.runs=new Map();this.entries=[];this.subscriptions=new Map();this.expanded=false;}
+  track({app,runId,title,input}){
+    if(this.runs.has(runId))return;
+    const record=app.getRun(runId),item={app,record,title,input,count:0,ended:false,steps:new Map(),catalog:new Map((app.catalog?.()??[]).map(action=>[action.id,action]))};
+    this.runs.set(runId,item);
+    this.entries.push({type:'start',item});
+    if(!this.subscriptions.has(app))this.subscriptions.set(app,app.subscribe(event=>{
+      const item=this.runs.get(event.runId);if(!item||item.app!==app)return;
+      this.update(item,event);this.release(app);
+      if(event.type==='log'&&!item.ended)this.scheduleRefresh();
+      else this.flushRefresh();
+    }));
+    this.update(item);this.release(app);this.refresh();
+  }
+  scheduleRefresh(){
+    if(this.refreshTimer)return;
+    this.refreshTimer=setTimeout(()=>{this.refreshTimer=null;this.refresh();},100);
+  }
+  flushRefresh(){
+    if(this.refreshTimer){clearTimeout(this.refreshTimer);this.refreshTimer=null;}
+    this.refresh();
+  }
+  update(item,event){
+    if(event?.type&&!['run.succeeded','run.failed','run.cancelled','run.stopped'].includes(event.type))item.record.events.push(event);
+    else{
+      const record=item.app.getRun(item.record.id);if(!record)return;
+      item.record={...record,events:[...(record.events??[])]};
+    }
+    const {record}=item,events=record.events.slice(item.count);item.count=record.events.length;
+    for(const event of events)if(event.type.startsWith('step.'))item.steps.set(event.callPath,{...item.steps.get(event.callPath),...event});
+    if(events.length){
+      const last=this.entries.at(-1);
+      if(last?.type==='events'&&last.item===item)last.events.push(...events);
+      else this.entries.push({type:'events',item,events});
+    }
+    if(record.status!=='running'&&!item.ended){item.ended=true;this.entries.push({type:'result',item});}
+  }
+  release(app){
+    if([...this.runs.values()].some(item=>item.app===app&&!item.ended))return;
+    this.subscriptions.get(app)?.();this.subscriptions.delete(app);
+  }
+  message(text){this.entries.push({type:'message',text});this.refresh();}
+  compactEvents(entry,seen){
+    const {item}=entry,rows=[];
+    for(const event of entry.events){
+      const key=`${item.record.id}\0${event.callPath}`;
+      if(event.type.startsWith('step.')&&!seen.has(key)){
+        seen.add(key);const latest=item.steps.get(event.callPath),action=item.catalog.get(latest.action);
+        const status=latest.type.slice(5),symbols={started:'●',succeeded:'✓',failed:'✗',cancelled:'×',skipped:'–',stopped:'■'};
+        const name=action?.title??latest.action??latest.stepId??latest.callPath;
+        rows.push(`${symbols[status]??'·'} ${name} · ${status==='started'?'执行中':runStatuses[status]??status}${latest.durationMs!==undefined?' · '+latest.durationMs+' ms':''}${action?.plugin?' · '+action.plugin:''} · ${latest.callPath}`);
+      }
+      if(event.type==='log'&&event.audience==='user')rows.push(`[${event.callPath??item.record.workflowId}] ${event.message??''}${event.data!==undefined?'\n'+readableValue(event.data):''}`);
+      if(event.type==='step.failed'&&![...item.steps.values()].some(step=>step.type==='step.failed'&&step.callPath?.startsWith(event.callPath+'/')))rows.push(`✗ ${event.callPath}\n${readableError(event.error??{message:event.message})}`);
+      if(event.type==='step.stopped'||event.type==='step.skipped')rows.push(`${event.callPath}：${event.reason??event.message??''}`);
+    }
+    return rows.length?`${item.title??item.record.workflowId} · ${item.record.id.slice(0,8)}\n${rows.join('\n')}`:'';
+  }
+  text(){const seen=new Set();return this.entries.map(entry=>{
+    if(entry.type==='message')return entry.text;
+    const {record,title,input}=entry.item,label=`${title??record.workflowId} · ${record.id.slice(0,8)}`;
+    if(entry.type==='start')return [
+      `› ${record.workflowId.startsWith('/')?record.workflowId:'/run '+record.workflowId} · ${label}`,
+      `状态：${runStatuses[record.status]??record.status}`,
+      this.expanded&&input&&Object.keys(input).length?'输入\n'+readableValue(input):'',
+    ].filter(Boolean).join('\n');
+    if(entry.type==='events')return this.expanded?`${label}\n${readableTimeline(entry.events,{values:true})}`:this.compactEvents(entry,seen);
+    return [`结果 · ${label} · ${runStatuses[record.status]??record.status}`,
+      this.expanded&&record.output!==undefined?readableValue(record.output):'',record.error&&(this.expanded||![...entry.item.steps.values()].some(step=>step.type==='step.failed'))?readableError(record.error,{details:this.expanded}):'',record.reason??'',
+    ].filter(Boolean).join('\n');
+  }).filter(Boolean).join('\n\n');}
+  close(){if(this.refreshTimer)clearTimeout(this.refreshTimer);this.refreshTimer=null;for(const unsubscribe of this.subscriptions.values())unsubscribe();this.subscriptions.clear();}
+}