@yanglaofish/fishtools 0.1.3 → 0.2.0

package/manual/docs/superpowers/specs/2026-10-11-control-observation.md

@@ -0,0 +1,37 @@
+# 条件控制、并行编排与运行观察
+
+## 已确认目标
+
+插件负责完成能力并返回符合声明的结果；正常返回表示执行成功，业务结果是否符合要求由工作流判断。提供可编排动作必须声明 input/output（无参数或无输出使用空对象 schema）；业务检测返回 passed/ok/count 等结构化字段。判定预设可选，普通大小写转换无需重复声明“执行成功”。
+
+用户在 TUI 与 Web 的列表中添加条件分支、并行组、提前结束，也可给步骤设置执行条件。运行中可在步骤总览、输入输出、实时日志间切换，按步骤调用路径区分同一插件的多次调用。支持键盘翻页和鼠标滚轮，离开观察页面不终止任务，停止操作显式取消。
+
+## 控制流协议（兼容 schemaVersion: 1 的既有顺序步骤）
+
+每个步骤有 id、可选 title、可选 when，以下五种执行目标必须恰有一种：
+
+- `{action, with}`：调用插件。
+- `{workflow, with}`：调用子工作流。
+- `{branch: {condition, then: [步骤], else: [步骤]}}`：只执行命中的分支。
+- `{parallel: {steps: [步骤], concurrency: 2}}`：并发执行独立子步骤；concurrency 为 1–32 整数，默认 4。
+- `{stop: {reason: '环境不满足'}}`：正常提前结束整个顶层运行，状态 stopped，保留原因和之前的步骤事件。可以带 when 决定是否触发。
+
+条件为 `{left: {$ref: 'steps.check.output.ok'}, op: 'eq', right: true}`；支持 eq/ne/gt/gte/lt/lte/contains/exists，以及 `{all:[条件]}`、`{any:[条件]}`、`{not:条件}`。严格按类型比较，不执行 JS。缺失字段在 exists 中为 false，其他比较也为 false；非法引用在执行前拒绝。when 为 false 记 step.skipped，不调用插件。
+
+判定预设：动作上的 `conditions: {passed: {title:'检查通过', path:'ok', op:'eq', value:true}}`，path 相对于本动作输出，界面将其展开为条件节点。核心检查格式与已声明输出字段。检查插件增加独立 report 动作返回 ok:false；保留旧 check 动作失败即抛错以兼容旧工作流。
+
+嵌套序列可读取外层已完成步骤及本层前序步骤；并行兄弟之间不可互相引用。节点 id 在同一工作流内唯一。分支/并行组输出为实际执行完成的子步骤 id → 输出对象，外部通过 `steps.group.output.child.field` 引用。跳过/未选中节点无输出；普通绑定读取缺失字段仍明确报错，作者可通过条件/分支避免读取。并行组必须等待所有启动任务清理完成；首个失败或提前结束会停止调度，取消已启动兄弟，保留首个原因。不保证回滚业务副作用。嵌套停止传播到顶层。
+
+## 运行事件与界面合同
+
+- 保留现有事件，增加 step.skipped、step.stopped、workflow.stopped、run.stopped。
+- step.started 携带解析后的 input、action（如有）、callPath；事件以 callPath 归属步骤。
+- runProcess 输出产生 `{type:'log', stream:'stdout'|'stderr', message, callPath, stepId}` 事件；仍返回 exitCode/stdout/stderr，保留超时、取消、进程树回收和输出上限。UTF-8 分块正确解码。
+- app.getRun/readRun 返回 status、events、output/error、可选 reason；stopped 无 error。CLI stopped 正常退出并打印原因。
+- TUI 新增 /runs，运行后打开可切换视图的观察面板；可关闭面板返回工作台，后台运行继续。/logs 保留已结束日志。滚轮仅在可滚动面板接管，并在关闭后恢复终端鼠标模式。
+- Web 运行面板使用同一事件显示待执行/运行中/已跳过/成功/失败/停止；详情按调用路径过滤日志，滚动离开底部时暂停自动跟随。
+- 所有条件与分组编辑提供表单，不要求手写 JSON/YAML；只读包允许观察和运行，不允许改流程。
+
+## 验收与范围
+
+覆盖条件分支、正常结束、并发上限、取消清理、嵌套依赖闭包导出、实时 stdout/stderr、鼠标与键盘浏览以及 TUI/Web 编辑保存再运行。Windows/Linux 保持一致。暂停恢复、持久化断点、多机分布式执行、自动回滚不在本次范围。

package/{docs → manual/docs}/verification.md

@@ -165,3 +165,23 @@ MiB = 1,048,576 字节。以下为本机单次测量，不是性能保证；运
 ## 分层便携包阶段远端结果（历史）
 
 代码与测试提交 e55075e 的 [Windows / Ubuntu CI](https://github.com/yanglaofish/Fishtools/actions/runs/38053011826) 均通过；Windows 5 分 13 秒、Ubuntu 1 分 27 秒。验收文档归档提交不改变已验证代码。
+# 2026-10-11 TUI 上手体验修正
+
+- 修正首页缺少产品介绍、示例入口以及插件清单不显眼的问题：显示 FISHtools 字符标识、欢迎语、当前工作区、数量和真实工作流示例。
+- `/plugins` 直接列出已有插件，详情展示声明的动作、输入输出、环境、配置及命令；维护模式仍保留说明，仅隐藏不可执行的命令入口。
+- 完整页面按终端高度分配空间；80×24、52×24、40×20 自动化渲染检查覆盖首页和可滚动插件列表。
+- 本地终端与 Markdown 阅读器共 26 项测试通过；Windows 与 WSL 真实 PTY 检查首页、插件列表和详情返回。本地 npm 安装、再次导出及包内插件调用验证通过。
+- 提交 `4c6bdc5` 的 [Windows/Linux 全量 CI](https://github.com/yanglaofish/Fishtools/actions/runs/38071024230) 各 91 项通过；[v0.1.4 发布验收](https://github.com/yanglaofish/Fishtools/actions/runs/38071614758) 的双平台测试、自包含归档解压运行、无 Node Docker 检查及发布全部成功。npm 官方注册表已提供 `@yanglaofish/fishtools@0.1.4`，[Release](https://github.com/yanglaofish/Fishtools/releases/tag/v0.1.4) 已附三个归档及 SHA256SUMS。
+- 修复 npm 发布预演依赖远端版本状态的问题：仅预演采用离线独立空缓存，实际发布继续检查注册表版本和归档校验值。
+
+## 2026-10-11 0.2.0 控制流、运行观察与离线开发资料
+
+- 本地最终 `npm test` **143/143** 通过，180.2 秒；涵盖真实 npm 离线全局安装、再次导出、资料定位和归档完整性。Web 构建通过，无新增运行时依赖。
+- 独立审查发现并修复：嵌套并行首因可能被取消覆盖、空分组与最后跳过节点漏检取消、null schema 绕过声明、失败后用户取消覆盖最终状态；分别有失败复现和回归测试。服务示例补齐严格输出声明。
+- WSL Linux 运行控制流、实时输出和旧工作流专项 **29/29** 通过。Windows 完整便携 ZIP 解压后清空 PATH，使用包内 Node 执行 hello、control-demo、正常停止、离线手册阅读及导出成功。
+- Windows 导出的同一 Linux tar.gz 在 WSL Ubuntu 24.04 中解压，通过 80×24 真实 PTY 验证彩色首页、/docs 阅读/翻页/鼠标滚轮、control-demo 运行、输入输出与日志视图、关闭面板、/runs 重新观察及正常退出。Windows 真实 PTY 已验证文档阅读、插件详情和退出；终端专项 **44/44** 通过，包含 40×20 窄屏、NO_COLOR 与安全文本渲染。
+- Linux 包只读挂载到 Debian 12 slim 容器；容器断网、根文件系统只读、移除 capabilities、基础环境无 Node/npm。手册导出后实际安装零依赖示例，offline.greet 返回“你好，离线用户”；条件并行与提前结束、配置保存、参数修改、完整性检查及再次导出全部通过。复现入口 `scripts/portable-smoke.sh`。
+- Chrome 真实浏览器 1440 与 390 宽度验证嵌套控制节点编辑保存、输入引用、执行结果、日志暂停/恢复跟随、关闭面板后台继续、Esc 焦点及只读管理；无横向溢出或 console error。终态 cancelled / stopped 与未完成状态分别显示；Web 模型 **6/6** 通过。
+- npm 与便携包包含 `manual/`；`fst docs`、`fst docs plugins`、`fst docs --export <新目录>` 与 TUI `/docs` 均可离线访问。文档测试 **4/4**，验证相对 Markdown 链接、拒绝覆盖、脱离源码定位和再次导出。SDK 尚未独立发布；示例使用标准对象，不依赖内部 SDK 的在线安装。
+- 验收脚本复用旧临时工作区曾被项目归属校验拒绝；脚本现为每次解压生成独立工作区，重新验收通过。没有放宽归属或完整性检查。
+- 本记录为本地验收结果；远端 CI 与 npm/tag/Release 结果在发布完成后追加。

package/manual/examples/service-plugins/README.md

@@ -0,0 +1,20 @@
+# 可独立安装的服务插件示例
+
+`provider` 提供 `demo.connection`，`consumer` 提供 `/demo.read` 和可编排动作。两者是标准 npm 插件目录，无需修改核心代码；MIT 许可证随目录保留。
+
+已安装 fst 后，使用 `fst docs --export ./fishtools-manual` 导出资料，再进入导出目录执行以下命令。源码开发也可直接从仓库根目录执行：
+
+```sh
+fst --maintenance plugin add ./examples/service-plugins/provider
+fst --maintenance plugin add ./examples/service-plugins/consumer
+fst command demo.read
+fst
+```
+
+在 TUI 输入 `/demo.read`，或将“使用共享连接”添加到工作流。两个动作共享同一个连接实例；每次启动应用创建新实例，调用计数不会跨进程保留。
+
+`dependencies` 声明提供者的插件 ID 和版本，使导出消费者工作流时自动包含提供者；`runtime.inject` 声明运行时服务就绪要求。它们与 package.json 的 npm 库依赖承担不同职责。
+
+示例不连接真实网络。实际 SSH/数据库插件应在 ready 中完成连接后再 `ctx.set()`，在 `ctx.on('dispose', async () => ...)` 中关闭；不要提前发布未就绪的连接。
+
+修改有状态插件前，在 TUI `/plugins` 进入维护模式，修改完成后选择恢复服务；原子 CLI 使用 `--maintenance`。维护模式是本进程选项，不写入项目文件。按默认方式再次启动即恢复服务。

package/manual/examples/service-plugins/consumer/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/examples/service-plugins/consumer/index.js

@@ -0,0 +1,14 @@
+export default {
+  id:'fishtools-demo-consumer',version:'1.0.0',title:'共享服务调用示例',
+  dependencies:{'fishtools-demo-connection':'^1.0.0'},
+  runtime:{inject:['demo.connection'],apply(){}},
+  commands:{'demo.read':{action:'read',description:'使用共享连接读取文本'}},
+  actions:{read:{
+    title:'使用共享连接',
+    input:{type:'object',properties:{text:{type:'string',default:'hello'}},additionalProperties:false},
+    output:{type:'object',properties:{text:{type:'string'},uses:{type:'integer',minimum:1}},required:['text','uses'],additionalProperties:false},
+    async run(input,{getService,signal}){
+      signal?.throwIfAborted();return getService('demo.connection').read(input.text);
+    },
+  }},
+};

package/manual/examples/service-plugins/consumer/package.json

@@ -0,0 +1 @@
+{"name":"fishtools-demo-consumer","version":"1.0.0","type":"module","main":"index.js","files":["index.js","LICENSE"],"license":"MIT"}

package/manual/examples/service-plugins/provider/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/examples/service-plugins/provider/index.js

@@ -0,0 +1,19 @@
+export default {
+  id:'fishtools-demo-connection',version:'1.0.0',title:'共享连接示例',
+  runtime:{
+    provides:['demo.connection'],
+    apply(ctx){
+      let connection;
+      ctx.on('dispose',async()=>{await connection?.close();});
+      ctx.on('ready',async()=>{
+        // 实际插件可在此连接 SSH 或数据库；就绪后才发布服务。
+        let uses=0,closed=false;
+        connection={
+          read(text){if(closed)throw Error('连接已关闭');return {text:`connection:${text}`,uses:++uses};},
+          async close(){closed=true;},
+        };
+        ctx.set('demo.connection',connection);
+      });
+    },
+  },
+};

package/manual/examples/service-plugins/provider/package.json

@@ -0,0 +1 @@
+{"name":"fishtools-demo-connection","version":"1.0.0","type":"module","main":"index.js","files":["index.js","LICENSE"],"license":"MIT"}

package/manual/packages/core/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/core/src/host.js

@@ -0,0 +1,122 @@
+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;
+    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/sdk/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/sdk/index.js

@@ -0,0 +1,14 @@
+export const SDK_VERSION = '0.1.0';
+
+export function definePlugin(plugin) {
+  return Object.freeze({ sdk: '^0.1.0', actions: {}, ...plugin });
+}
+
+export class FlowError extends Error {
+  constructor(message, { code = 'EXECUTION_FAILED', details, cause } = {}) {
+    super(message, { cause });
+    this.name = 'FlowError';
+    this.code = code;
+    this.details = details;
+  }
+}

package/manual/packages/sdk/package.json

@@ -0,0 +1 @@
+{"name":"@mytools/sdk","version":"0.1.0","type":"module","main":"index.js","exports":"./index.js","files":["index.js","README.md"],"license":"MIT"}

package/manual/plugins/environment/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/plugins/environment/index.js

@@ -0,0 +1,92 @@
+import os from 'node:os';
+import { readFile } from 'node:fs/promises';
+import semver from 'semver';
+import { definePlugin, FlowError } from '@mytools/sdk';
+
+const pythonProbe=String.raw`import sys,json,importlib.metadata,importlib.util
+names=json.loads(sys.argv[1])
+packages=[]
+for item in names:
+    name=item['name']
+    try:
+        version=importlib.metadata.version(name)
+        module=item.get('module')
+        if module: __import__(module)
+        packages.append({'name':name,'version':version,'ok':True})
+    except Exception as e:
+        packages.append({'name':name,'ok':False,'error':str(e)})
+print(json.dumps({'executable':sys.executable,'version':sys.version.split()[0],'prefix':sys.prefix,'packages':packages}))`;
+
+const plugin={
+  id:'@mytools/environment',version:'0.1.0',title:'环境检查',description:'检查目标机器的系统、Python/pip 与昇腾 NPU 环境，缺失必需条件时停止工作流。',
+  platforms:['win32','linux'],commands:{'env.check':{description:'检查系统、Python/pip 或 NPU',action:'check'}},
+  actions:{
+    check:{
+      title:'检查目标环境',description:'始终报告系统信息；按需检查指定 Python 及其软件包、pip 和 NPU。只检查，不安装或修改环境。',
+      input:{type:'object',properties:{
+        python:{type:'object',title:'Python 环境',required:['executable'],properties:{
+          executable:{type:'string',title:'解释器路径',description:'填写目标环境的 python/python.exe 绝对路径'},
+          version:{type:'string',title:'Python 版本要求',default:'>=3.9'},
+          pip:{type:'boolean',title:'要求 pip 可用',default:false},
+          packages:{type:'array',title:'要求的软件包',default:[],items:{type:'object',required:['name'],properties:{name:{type:'string',title:'包名'},version:{type:'string',title:'版本范围'},module:{type:'string',title:'需要尝试导入的模块（可选）'}}}},
+        }},
+        npu:{type:'boolean',title:'检查昇腾 NPU',default:false},
+        npuCommand:{type:'string',title:'npu-smi 路径',default:'npu-smi'},
+      },additionalProperties:false},
+      output:{type:'object',properties:{ok:{type:'boolean',title:'检查通过'},system:{type:'object',title:'系统信息'},python:{type:'object',title:'Python 环境',properties:{executable:{type:'string',title:'已检查的解释器'},version:{type:'string',title:'Python 版本'}}},checks:{type:'array',title:'检查明细',items:{type:'object'}}},required:['ok','system','checks']},
+      async run(input,{runProcess,signal}) {
+        const report={ok:true,system:{platform:os.platform(),architecture:os.arch(),kernel:os.release()},checks:[]};
+        if(process.platform==='linux'){
+          try{report.system.distribution=await readFile('/etc/os-release','utf8');}catch{}
+        }
+        const add=(name,ok,actual,status='error',expected)=>{report.checks.push({name,status:ok?'available':status,actual,expected});if(!ok)report.ok=false;};
+        const probe=async(file,args)=>runProcess(file,args,{signal,timeout:15000});
+        if(input.python){
+          const requested=input.python;
+          try {
+            const result=await probe(requested.executable,['-c',pythonProbe,JSON.stringify(requested.packages??[])]);
+            if(result.exitCode!==0)throw new Error(result.stderr||'Python 查询失败');
+            report.python=JSON.parse(result.stdout);
+            const parsed=semver.coerce(report.python.version);
+            const compatible=!!parsed && semver.satisfies(parsed,requested.version??'>=3.9');
+            add('python',compatible,report.python.version,'incompatible',requested.version??'>=3.9');
+            for(const pkg of report.python.packages){
+              const range=requested.packages.find(p=>p.name===pkg.name)?.version;
+              const version=semver.coerce(pkg.version??'');
+              add(`python.package:${pkg.name}`,pkg.ok&&(!range||(version&&semver.satisfies(version,range))),pkg.version??pkg.error,pkg.ok?'incompatible':'not_found',range);
+            }
+            if(requested.pip){
+              const pip=await probe(report.python.executable,['-m','pip','--version']);
+              add('pip',pip.exitCode===0,pip.stdout||pip.stderr,'not_found');
+            }
+          } catch(error){
+            if(signal?.aborted)throw error;
+            add('python',false,error.message,error.code==='ENOENT'?'not_found':'error','目标机可用解释器');
+          }
+        }
+        if(input.npu){
+          if(process.platform!=='linux')add('npu',false,'当前 NPU 适配仅支持 Linux','unsupported');
+          else try{
+            const r=await probe(input.npuCommand??'npu-smi',['info','-l']);
+            const count=r.stdout.match(/Total\s+NPU\s+count\s*:\s*(\d+)/i);
+            add('npu',r.exitCode===0&&Number(count?.[1])>0,r.stdout||r.stderr,r.exitCode===0?'not_found':'error','当前进程可见的昇腾 NPU');
+          }catch(error){if(signal?.aborted)throw error;add('npu',false,error.message,error.code==='ENOENT'?'not_found':'error');}
+        }
+        if(!report.ok)throw new FlowError('目标环境检查未通过，请根据检查明细处理后重试',{code:'ENVIRONMENT_FAILED',details:report});
+        return report;
+      },
+    },
+  },
+};
+// 报告模式将“检测完成”与“检测通过”分开；旧 check 保持失败即终止的兼容语义。
+plugin.actions.report={
+  ...plugin.actions.check,
+  title:'生成环境报告',description:'返回结构化检测结果；未通过时返回 ok:false，由工作流条件决定是否继续。',
+  conditions:{passed:{title:'环境检查通过',path:'ok',op:'eq',value:true}},
+  async run(input,context){
+    try{return await plugin.actions.check.run(input,context);}
+    catch(error){if(error.code==='ENVIRONMENT_FAILED')return error.details;throw error;}
+  },
+};
+plugin.commands['env.report']={description:'检测环境并返回报告（不因检查未通过抛错）',action:'report'};
+export default definePlugin(plugin);

package/manual/plugins/environment/package.json

@@ -0,0 +1 @@
+{"name":"@mytools/environment","version":"0.1.0","type":"module","main":"index.js","files":["index.js"],"license":"MIT","dependencies":{"@mytools/sdk":"0.1.0","semver":"7.7.4"}}

package/manual/plugins/examples/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/plugins/examples/index.js

@@ -0,0 +1,23 @@
+import { definePlugin, FlowError } from '@mytools/sdk';
+import { writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const text={type:'string',title:'文本'};
+const textInput={type:'object',required:['text'],properties:{text},additionalProperties:false};
+export default definePlugin({
+  id:'@mytools/examples',version:'0.1.0',title:'基础示例',description:'文本处理、文件输出和目标 Python 调用示例，用于组合第一个工作流。',
+  platforms:['win32','linux'],architectures:['x64','arm64'],
+  commands:{
+    'text.upper':{description:'将文本转为大写',action:'uppercase'},
+    'text.ask':{description:'交互输入文本并转大写',async run(_input,{ui,signal}){const text=await ui.input('输入文本');signal.throwIfAborted();return {text:text.toUpperCase()};}},
+  },
+  actions:{
+    uppercase:{title:'文本转大写',description:'将输入文本中的英文字母转成大写，输出可以继续传给其他步骤。',input:textInput,output:textInput,async run({text}){return {text:text.toUpperCase()};}},
+    append:{title:'追加文本',description:'在一段文本末尾追加内容。',input:{type:'object',required:['text','suffix'],properties:{text,suffix:{type:'string',title:'追加内容',default:' ✓'}},additionalProperties:false},output:textInput,async run({text,suffix}){return {text:text+suffix};}},
+    save:{title:'保存文本文件',description:'把文本保存到本次运行的结果目录，输出文件路径。',input:textInput,output:{type:'object',properties:{path:{type:'string',title:'结果文件路径'}},required:['path']},async run({text},{outputDir}){const file=path.join(outputDir,'result.txt');await writeFile(file,text,'utf8');return {path:file};}},
+    pythonEcho:{title:'调用 Python 脚本',description:'使用目标环境解释器执行随插件分发的 Python 脚本，返回解释器和处理结果。',input:{type:'object',required:['executable','text'],properties:{executable:{type:'string',title:'Python 解释器',description:'建议选择环境检查步骤输出的 python.executable'},text},additionalProperties:false},output:{type:'object',properties:{text,executable:{type:'string',title:'实际解释器'},version:{type:'string',title:'Python 版本'}},required:['text','executable','version']},async run({executable,text},{runProcess,signal,resourceDir}){
+      const r=await runProcess(executable,[path.join(resourceDir,'scripts','echo.py'),text],{signal});
+      if(r.exitCode!==0)throw new FlowError(`Python 脚本失败：${r.stderr}`);return JSON.parse(r.stdout);
+    }},
+  },
+});

package/manual/plugins/examples/package.json

@@ -0,0 +1 @@
+{"name":"@mytools/examples","version":"0.1.0","type":"module","main":"index.js","files":["index.js","scripts"],"license":"MIT","dependencies":{"@mytools/sdk":"0.1.0"}}

package/manual/plugins/examples/scripts/echo.py

@@ -0,0 +1,5 @@
+import json
+import sys
+
+# 由插件显式指定目标环境解释器；脚本只使用 Python 标准库。
+print(json.dumps({"text": sys.argv[1].upper(), "executable": sys.executable, "version": sys.version.split()[0]}))

package/manual/tests/application.test.js

@@ -0,0 +1,45 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdir, writeFile, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { createApplication } from '../packages/core/src/application.js';
+import { temporary, testPlugin, object } from './helpers.js';
+
+test('运行快照独立于之后保存，状态与日志持久化',async t=>{
+  const projectDir=await temporary(t);
+  const app=await createApplication({projectDir,plugins:[testPlugin()]}); t.after(()=>app.close());
+  const w={id:'hello',schemaVersion:1,title:'示例',inputs:object(),steps:[{id:'convert',action:'@test/text:upper',with:{text:'hello'}}],outputs:{text:{$ref:'steps.convert.output.text'}}};
+  await app.saveWorkflow(w);
+  const run=await app.startRun('hello',{});
+  await app.saveWorkflow({...w,steps:[{...w.steps[0],with:{text:'changed'}}]});
+  await run.done;
+  assert.equal(app.getRun(run.id).status,'succeeded');
+  assert.deepEqual(app.getRun(run.id).output,{text:'HELLO'});
+  const events=(await readFile(path.join(app.outputDir,run.id,'events.jsonl'),'utf8')).trim().split('\n').map(JSON.parse);
+  assert.ok(events.some(e=>e.type==='run.succeeded'));
+  assert.ok(!events.some(e=>Object.hasOwn(e,'output')));
+});
+
+test('仓库外本地插件可以安装、加载并执行，移除后目录同步',async t=>{
+  const root=await temporary(t), pluginDir=path.join(root,'外部插件'),projectDir=path.join(root,'project');
+  await mkdir(pluginDir,{recursive:true});
+  await writeFile(path.join(pluginDir,'package.json'),JSON.stringify({name:'external-flow-test',version:'1.0.0',type:'module',main:'index.js'}));
+  await writeFile(path.join(pluginDir,'index.js'),`export default {id:'external-flow-test',version:'1.0.0',sdk:'^0.1.0',actions:{hello:{title:'外部动作',input:{type:'object'},output:{type:'object'},run:async()=>({value:42})}}};`);
+  const app=await createApplication({projectDir,plugins:[]});t.after(()=>app.close());
+  await app.installPlugin(pluginDir);
+  assert.ok(app.catalog().some(a=>a.id==='external-flow-test:hello'));
+  await app.saveWorkflow({id:'external',schemaVersion:1,inputs:object(),steps:[{id:'hello',action:'external-flow-test:hello',with:{}}],outputs:{answer:{$ref:'steps.hello.output.value'}}});
+  const run=await app.startRun('external',{});await run.done;
+  assert.deepEqual(app.getRun(run.id).output,{answer:42});
+  await app.removePlugin('external-flow-test');
+  assert.ok(!app.catalog().some(a=>a.id==='external-flow-test:hello'));
+});
+
+test('外部配置覆盖项目值并在调用前验证',async t=>{
+  const projectDir=await temporary(t);
+  await writeFile(path.join(projectDir,'flow.project.json'),JSON.stringify({config:{configured:{prefix:'项目'}}}));
+  const plugin={id:'configured',version:'1.0.0',config:{type:'object',properties:{prefix:{type:'string'}},required:['prefix'],additionalProperties:false},actions:{show:{input:object(),output:object({prefix:{type:'string'}},['prefix']),run:async(_input,{config})=>config}}};
+  const app=await createApplication({projectDir,plugins:[plugin],config:{configured:{prefix:'目标'}}});t.after(()=>app.close());
+  assert.deepEqual(await app.host.invoke('configured:show',{}),{prefix:'目标'});
+  await assert.rejects(createApplication({projectDir,plugins:[plugin],config:{configured:{prefix:42}}}),/配置/);
+});