@yanglaofish/fishtools 0.1.4 → 0.3.0

package/README.md

@@ -2,9 +2,11 @@
 
 基于 Cordis 的插件式工作流工作台，启动命令是 **`fst`**。
 
-目标是提供轻量、可扩展的顺序工作流工具：用户查看可用能力与现成工作流，将它们加入有序列表、填写输入、选择输出并运行；也能将选定工作流及其依赖打包成可离线运行的 Windows 或 Linux 分发包。Linux 包可挂载到兼容的 Linux 容器内运行。
+目标是提供轻量、可扩展的工作流工具：用户查看可用能力与现成工作流，将它们加入列表、填写输入、设置条件、选择输出并运行；也能将选定工作流及其依赖打包成可离线运行的 Windows 或 Linux 分发包。Linux 包可挂载到兼容的 Linux 容器内运行。
 
-交互终端支持选择能力、配置参数和顺序编排；官方 Web 插件默认提供，原子 CLI 子命令用于自动化。三种入口共用应用服务。YAML、依赖锁和版本解析由系统维护，不要求普通用户手写。
+交互终端支持选择能力、配置参数和流程编排；官方 Web 插件默认提供，原子 CLI 子命令用于自动化。三种入口共用应用服务。YAML、依赖锁和版本解析由系统维护，不要求普通用户手写。
+
+0.3.0 增加按对象组织的终端菜单、主面板执行摘要与插件用户输出、命令历史，并修复第三方插件进程调用和离线 Web 打包。此前 0.2.0 引入的条件控制、运行观察和离线开发手册仍可使用。发布与验证状态见 [版本记录](manual/docs/releases.md) 和 [验收记录](manual/docs/verification.md)。
 
 插件接入层使用 JavaScript/TypeScript，通过通用进程接口调用 Python 脚本和系统命令。首款官方插件负责 Python/pip、NPU 与系统环境检查，使用与第三方插件相同的公开接口，按工作流依赖选入分发包。插件声明 Python 等环境使用宿主机还是自带资源；环境检查与业务兼容性由插件作者负责。包内始终携带编排器所需的 Node，完整便携包也携带 npm。
 
@@ -17,7 +19,7 @@ npm install -g @yanglaofish/fishtools
 fst
 ```
 
-也可从 GitHub Release 下载 `.tgz` 后执行 `npm install -g ./yanglaofish-fishtools-0.1.4.tgz`。没有 Node/npm 的机器使用 Release 中的 Windows `.zip` 或 Linux `.tar.gz` 自包含包，解压后运行 `fst.cmd` 或 `./fst`。发布结果以 [GitHub Releases](https://github.com/yanglaofish/Fishtools/releases) 为准；当前仓库为私有，下载附件需要仓库访问权限。
+也可从 GitHub Release 下载 `.tgz` 后执行 `npm install -g ./yanglaofish-fishtools-0.3.0.tgz`。没有 Node/npm 的机器使用 Release 中的 Windows `.zip` 或 Linux `.tar.gz` 自包含包，解压后运行 `fst.cmd` 或 `./fst`。发布结果以 [GitHub Releases](https://github.com/yanglaofish/Fishtools/releases) 为准；当前仓库为私有，下载附件需要仓库访问权限。
 
 `fst` 在交互终端里启动终端工作台（TUI）；`fst web` 启动 Web 并打印访问地址；`fst run hello` 直接执行工作流。首次使用在 `~/.fishtools` 创建工作区，也可通过 `FISHTOOLS_HOME` 指定。安装包已包含官方插件、页面和生产依赖，不需要源码仓库或前端构建。
 
@@ -37,27 +39,56 @@ fst --project ./my-project pack hello --target linux-x64-glibc --web
 
 ## 交互终端：无需记住全部参数
 
-启动 `fst` 后输入 `/` 会展开操作列表，使用上下箭头选择、Tab 补全、Enter 确认，Escape 返回，Ctrl+C 取消当前输入或运行。在主提示符处 Ctrl+C 退出，有未保存修改时会先确认。
+启动 `fst` 后输入 `/` 会展开操作列表，使用上下箭头选择、Tab 补全、Enter 确认，Escape 返回。普通输入与插件命令忙碌页使用 Ctrl+C 取消；运行观察面板内 Ctrl+C 只关闭面板。在主提示符处 Ctrl+C 请求退出，有未保存修改或后台运行时会先确认。
+
+首页展示 FISHtools 字符标识、欢迎介绍、当前工作区以及插件和工作流数量；小窗口自动使用紧凑标题。首次使用可以输入 `/run hello`，按提示输入文本（也可保留默认值），体验“转为大写 → 追加标记 → 保存文件”。运行过程与输入输出留在主面板，期间仍可打开配置或执行其他工作流。PgUp/PgDn 或鼠标滚轮浏览会话中的过程，向下翻至末尾恢复跟随。首页只推荐当前工作区实际存在的工作流；空工作区从 `/workflows` 新建。
+
+顶部的“位置”显示主面板或当前操作入口，菜单标题显示正在操作的对象。提交的命令、菜单选择与实际操作结果保留在本次会话中；返回时只更新当前位置，不追加通用返回消息，也不清空执行过程。这些导航记录只保留在当前会话。
 
-首页展示 FISHtools 字符标识、欢迎介绍、当前工作区以及插件和工作流数量；小窗口自动使用紧凑标题。首次使用可以输入 `/run hello`，按提示输入文本（也可保留默认值），体验“转为大写 → 追加标记 → 保存文件”；执行后输入 `/logs` 阅读日志。首页只推荐当前工作区实际存在的工作流，空工作区提示用 `/new` 创建。
+主面板查看当前执行，`/logs` 回看某次执行的步骤状态、输入输出和日志，也能重新打开正在运行的任务详情。查看记录不会重新执行工作流。旧 `/runs` 和 F4 仅作为兼容方式转到同一个 `/logs` 入口，不再提供独立列表。
 
-`/plugins` 直接列出当前已加载的插件名称、版本和状态。上下选择后可查看用途、编排能力、输入输出、环境声明及斜杠命令；有配置的插件提供配置入口，自行安装的插件提供移除入口。内置插件标明来源，避免误以为没有安装。`/help` 在终端内提供可翻页的用法说明。
+主面板默认按步骤显示“执行中／成功／失败”，每一步标明能力与插件；**Ctrl+O 展开/收起详情**，查看各步输入输出、作者日志和子进程 stdout/stderr。错误摘要与插件 `print()` 的用户提示直接展示，普通技术日志默认折叠。折叠只改变展示，不丢弃日志或结果。
+
+主输入框用 **↑ / ↓** 回看本次启动中已提交的命令，向下回到底部恢复未提交草稿。补全菜单打开时，方向键仍选择候选；配置表单内容不进入命令历史。最多保留最近 100 条，相邻重复命令合并，退出后不保存。
+
+`/plugin` 直接列出当前已加载的插件名称、版本和状态。上下选择后可查看用途、编排能力、输入输出、环境声明及斜杠命令；有配置的插件提供配置入口，自行安装的插件提供移除入口。内置插件标明来源，避免误以为没有安装。`/help` 在终端内提供可翻页的用法说明。顶层补全标明 `[内置]` 或 `[插件]`，插件能力收进插件名入口的二级菜单。
 
 | 操作 | 功能 |
 | --- | --- |
-| `/workflows`、`/new` | 选择已有工作流，或新建流程 |
-| `/add`、`/steps` | 添加能力/子工作流，设置参数、排序、删除步骤 |
-| `/outputs`、`/save` | 选择汇总输出，保存为 Web 可继续编辑的同一份流程 |
-| `/run` | 逐字段填写运行参数并执行，显示状态、结果和可直接阅读的 Markdown 日志路径 |
-| `/logs` | 在终端内翻页阅读历史日志，设置整个项目保留最近 N 次日志 |
-| `/plugins` | 浏览已安装插件、用途及能力，进入配置、安装和移除操作 |
+| `/workflows` | 浏览、新建；进入某个流程后添加/编辑步骤、设置输出、保存、运行或删除 |
+| `/run 工作流ID` | 可按 ID 或中文标题补全，填写参数后执行已保存版本；只输入 `/run` 打开已保存工作流列表 |
+| `/logs` | 回看执行记录，运行中的任务优先；可切换总览、输入输出与日志，支持键盘或鼠标滚轮阅读 |
+| `/plugin` | 浏览已安装插件、用途及能力，进入插件配置、安装和移除操作 |
 | `/pack` | 勾选工作流并选择目标平台打包 |
-| `/config` | 编辑并保存插件声明的配置 |
-| `/web`、`/help`、`/exit` | 启动可选 Web、查看说明、退出 |
+| `/config` | 配置 Fishtools：查看工作区信息，设置整个项目的日志保留次数 |
+| `/tools` | 启动 Web 或阅读离线资料 |
+| `/help`、`/exit` | 查看帮助、退出 |
+
+旧 `/new`、`/add`、`/steps`、`/outputs`、`/save`、`/plugins`、`/docs`、`/web` 和 `/runs` 仍可直接输入，顶层补全主要呈现上表的对象入口。工作流编辑菜单返回时保留当前草稿，切换流程或退出会确认未保存修改。删除会将已保存文件移入 `.flow/deleted-workflows/工作流ID-编号.yaml`，仍被其他流程引用时拒绝删除；恢复时将备份复制回 `workflows/原工作流ID.yaml`，先确认同名文件不存在，避免覆盖。
+
+`/run` 不要求保存当前编辑草稿，也不会丢弃它。要运行尚未保存的修改，请在 `/workflows` 的编辑菜单选择“运行工作流”，再选择“保存并运行”；已有磁盘版本时也可选择“运行已保存版本”并保留草稿。“返回编辑”会留在当前工作流，不会反复弹出保存确认。只查看参数或拒绝删除步骤不会产生未保存修改。
 
 参数来源可选固定值、每次运行时填写或前序步骤的输出。对象逐字段编辑，数组逐项编辑；复杂 schema 可以输入 JSON 值。终端本身无需 Web 插件或 LLM。
 
-插件可以注册自己的命令：官方示例提供 `/text.upper`、交互式 `/text.ask` 和 `/env.check`。安装或移除插件会同步刷新 `/` 菜单；命令和工作流共用日志、取消和结果机制。
+条件分支只执行命中的一侧；并行组同时执行独立步骤，可设置 1–32 的最大并发数（默认 4）。步骤的执行条件不满足时跳过。提前结束节点正常停止整个运行并保留原因，显示为 `stopped`；主动取消显示为 `cancelled`，执行异常显示为 `failed`。插件返回业务结果，由工作流决定结果不符合要求时如何处理。
+
+运行观察面板键位：
+
+| 按键 | 操作 |
+| --- | --- |
+| `1` / `2` / `3` | 步骤总览 / 输入输出 / 实时日志 |
+| `[` / `]` | 切换步骤调用；相同插件的不同调用分别显示 |
+| `a` | 切换当前步骤与全部日志 |
+| ↑↓、鼠标滚轮、PageUp/PageDown、Home/End | 滚动、翻页、跳转开头或尾部；手动滚动暂停日志跟随，End 恢复跟随 |
+| `f` | 切换日志跟随 |
+| Enter | 在总览中查看所选步骤详情，不退出面板 |
+| `j` | 在易读字段与原始 JSON 诊断之间切换 |
+| Esc、q、Ctrl+C | 返回上一级，运行中的任务继续；输入 `/logs` 可重新打开 |
+| `x`，再按 `y` | 确认取消整个运行 |
+
+运行记录同时列出正在执行和保留的历史记录，运行中任务优先；同一个工作流的多次执行分别显示时间和记录编号。查看详情后返回列表，可以继续选择另一次执行。本次启动期间每次运行分别保存阅读位置；重启后可通过 `/logs` 查看保存的记录，主面板会话展示从新会话开始。日志保留设置在 `/config`。主提示符 `/exit` 或 Ctrl+C 遇到后台任务时，会说明退出将取消任务并请求确认，默认不退出。
+
+插件可以注册自己的命令：官方示例的 `/examples` 入口包含文本转大写与交互文本输入，`/environment` 入口包含环境检查与报告。原 `/text.upper`、`/text.ask`、`/env.check`、`/env.report` 仍可直接调用。`check` 在环境未通过时抛错；`report` 正常返回 `ok:false` 和检查明细，适合交给工作流条件判断。安装或移除插件会同步刷新 `/` 菜单；命令和工作流共用日志、取消和结果机制。
 
 在字符串参数中输入 `@` 可选择本地文件或目录，引用结果为绝对路径；`@@文字` 表示以 @ 开头的普通文字。`/run hello @"输入 参数.json"` 则明确读取文件中的 JSON 对象作为运行输入。文件路径相对启动时的目录（在 `/help` 中显示），不会自动上传文件，也不会把文件内容当作命令。路径补全无需额外安装 `fd`。
 
@@ -65,6 +96,21 @@ fst --project ./my-project pack hello --target linux-x64-glibc --web
 
 ## 源码开发启动
 
+### 源码预览
+
+已有源码依赖时，在仓库根目录运行 `npm run preview`；Windows 也可双击 `fst-preview.cmd`。首页标识“本地源码预览”。工作区位于 `.cache/log-preview-win32` 或 `.cache/log-preview-linux`，不会升级全局 `fst`，也不会改动用户默认工作区。
+
+- 输入 **`/logs`**，查看已生成的成功、缺少解释器失败示例。
+- 输入 `/run preview-pipeline`，体验三个不同插件“准备文本 → 转大写 → 保存报告”。文本和演示等待时间可以调整；默认查看步骤状态，Ctrl+O 展开输入输出，保存位置由插件直接展示。
+- 输入 `/run preview-stream`，Tab 补全、Enter 执行，Ctrl+O 展开后查看持续输出；用 PgUp/PgDn 或滚轮回看。
+- 输出期间输入 `/config` 查看工具设置，Esc 返回后过程仍在；再执行 `/run preview-success`，体验同一会话里的多个工作流。
+- `/workflows` 进入管理与编辑；`/examples` 或 `/local-log-preview` 进入插件能力菜单。
+- `/logs` 选择某次执行后，`1/2/3` 切换总览、输入输出、日志；`j` 查看原始诊断，`q` 返回。
+
+示例流程只在首次启动时创建，之后保留本地修改；故意失败示例不检查或改变机器的实际 Python 安装。
+
+### 常规源码启动
+
 开发机器安装 **Node.js 24.15.0** 和 npm，在仓库根目录执行：
 
 ```sh
@@ -77,9 +123,11 @@ npm run web
 
 使用 Web 时，打开终端打印的完整地址（含 `#token=...`）。界面、图标、表单资源均本地提供。开发依赖安装需要联网；导出的运行包不需要 Node/npm 或联网安装依赖。
 
-源码启动的默认项目是 `examples`。首次打开进入工作流总览，可以搜索并打开现成流程，或点击“新建工作流”。编辑器中点击“添加步骤”选择能力，再点击步骤设置固定输入、运行时输入或前序步骤输出；小窗口会就近打开参数弹窗。支持拖动和上下箭头排序；引用失效时阻止运行。“工作流输出”区域选择最终返回的数据，运行后可直接阅读文本结果或展开各步骤详情。
+源码启动的默认项目是 `examples`。首次打开进入工作流总览，可以搜索并打开现成流程，或点击“新建工作流”。编辑器中点击“添加步骤”选择能力、子工作流，或进入“流程控制”添加分支、并行组和提前结束；点击节点用表单设置参数、执行条件、并发数、结束原因及内部步骤。输入可来自固定值、运行时输入或前序步骤输出；小窗口会就近打开参数弹窗。支持拖动和上下箭头排序；引用失效时阻止运行。“工作流输出”区域选择最终返回的数据。
+
+保存后点击“运行工作流”。“查看运行”面板提供步骤总览、输入输出、实时日志，并按调用路径筛选；stdout/stderr 在受管子进程执行期间持续显示。向上滚动日志会暂停跟随，点击“恢复自动跟随”可继续看尾部。关闭观察窗口后任务继续，点击“停止运行”才发送取消请求。只读运行包允许观察和运行，不允许编辑流程。
 
-运行 `npm run dist:npm` 生成当前版本的 `dist/yanglaofish-fishtools-版本号.tgz`。使用 [npm 原生 bundleDependencies](https://docs.npmjs.com/cli/configuring-npm/package-json/#bundledependencies) 打包安装依赖。推送 `v版本号` tag 后，GitHub Actions 验证跨平台安装和运行，再发布 npm 并生成带自包含附件的 Release；流程和重试规则见[发布说明](docs/releases.md)。
+运行 `npm run dist:npm` 生成当前版本的 `dist/yanglaofish-fishtools-版本号.tgz`。使用 [npm 原生 bundleDependencies](https://docs.npmjs.com/cli/configuring-npm/package-json/#bundledependencies) 打包安装依赖。推送 `v版本号` tag 后，GitHub Actions 验证跨平台安装和运行，再发布 npm 并生成带自包含附件的 Release；流程和重试规则见[发布说明](manual/docs/releases.md)。
 
 ## CLI
 
@@ -101,6 +149,8 @@ npm run fst -- --project examples pack hello python-check --target linux-x64-gli
 
 Windows 路径在 JSON 中写成 `"F:\\miniconda\\python.exe"`。请使用实际解释器路径；后续步骤使用环境检查返回的解释器执行脚本。
 
+`fst run` 和 `fst command` 遇到正常提前结束时，以退出码 0 返回 `{status:'stopped', reason:'结束原因'}`。此前成功步骤的输入输出、实时日志和停止原因仍保存在运行记录中。
+
 ## 自包含打包
 
 Web 中点击“打包”，选择工作流、目标平台、是否含 Web。工具自动收集子工作流、插件、生产 npm 依赖、脚本和 Node.js。没有依赖关系的其他工作流不入包。
@@ -131,15 +181,19 @@ npm 安装版是完整编排工具；上表为按所选流程导出的自包含
 
 ## 文档与开发
 
-- 服务插件可使用 Cordis `runtime` 声明共享服务和生命周期；修改有状态插件前，TUI `/plugins` 进入维护模式，或 CLI 使用 `--maintenance`。示例见 [共享服务插件](examples/service-plugins/README.md)。
-- [当前里程碑与路线图](docs/roadmap.md)
-- [插件开发与公共接口](docs/plugin-development.md)
-- [离线部署与堡垒机访问](docs/deployment.md)
-- [验收记录与限制](docs/verification.md)
-- [目标与设计](docs/superpowers/specs/2026-10-09-workflow-cli-design.md)
-- [实施计划](docs/superpowers/plans/2026-10-09-workflow-mvp.md)
-- [开源来源与许可证](THIRD_PARTY_NOTICES.md)
+完整 npm 与便携发行包携带 `manual/` 离线资料。只安装 npm 包的开发者可用 `fst docs` 查看主题，`fst docs plugins` 阅读规范，`fst docs plugins --path` 定位本地文件，或 `fst docs --export ./fishtools-manual` 导出完整资料（目标必须不存在）。TUI 使用 `/docs` 阅读。规范、源码阅读参考、许可证以及[可安装的零依赖动作插件](manual/docs/examples/action-plugin/README.md)一起分发，无需克隆仓库或另行安装内部 SDK。资料对应当前安装版本，离线安装、阅读、导出和示例接入均纳入分发验收。
+
+- 服务插件可使用 Cordis `runtime` 声明共享服务和生命周期；修改有状态插件前，TUI `/plugins` 进入维护模式，或 CLI 使用 `--maintenance`。示例见 [共享服务插件](manual/examples/service-plugins/README.md)。
+- [当前里程碑与路线图](manual/docs/roadmap.md)
+- [插件开发与公共接口](manual/docs/plugin-development.md)
+- [离线部署与堡垒机访问](manual/docs/deployment.md)
+- [验收记录与限制](manual/docs/verification.md)
+- [目标与设计](manual/docs/superpowers/specs/2026-10-09-workflow-cli-design.md)
+- [实施计划](manual/docs/superpowers/plans/2026-10-09-workflow-mvp.md)
+- [开源来源与许可证](manual/THIRD_PARTY_NOTICES.md)
 
 核心在 `packages/core`，SDK 在 `packages/sdk`，打包在 `packages/pack`，官方插件在 `plugins`。使用 npm workspaces 与提交的 lockfile 固定依赖。运行 `npm test` 验证。
 
+参与编排的插件动作必须声明有效的 input/output JSON Schema；无参数或无输出也声明空对象 schema。正常返回且输出通过校验即执行成功，可选 `conditions` 预设帮助用户选择业务判断。通过上下文 `runProcess` 执行的 stdout/stderr 会自动进入实时日志；完整协议、引用范围和并行取消规则见[插件开发文档](manual/docs/plugin-development.md)。
+
 首版优先 Windows x64 和 Linux x64 glibc。Alpine/musl、ARM、Windows 容器与分布式调度未纳入；真实 NPU 硬件验证仍待进行。

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

@@ -0,0 +1,199 @@
+# Fishtools
+
+基于 Cordis 的插件式工作流工作台，启动命令是 **`fst`**。
+
+目标是提供轻量、可扩展的工作流工具：用户查看可用能力与现成工作流，将它们加入列表、填写输入、设置条件、选择输出并运行；也能将选定工作流及其依赖打包成可离线运行的 Windows 或 Linux 分发包。Linux 包可挂载到兼容的 Linux 容器内运行。
+
+交互终端支持选择能力、配置参数和流程编排；官方 Web 插件默认提供，原子 CLI 子命令用于自动化。三种入口共用应用服务。YAML、依赖锁和版本解析由系统维护，不要求普通用户手写。
+
+0.3.0 增加按对象组织的终端菜单、主面板执行摘要与插件用户输出、命令历史，并修复第三方插件进程调用和离线 Web 打包。此前 0.2.0 引入的条件控制、运行观察和离线开发手册仍可使用。发布与验证状态见 [版本记录](docs/releases.md) 和 [验收记录](docs/verification.md)。
+
+插件接入层使用 JavaScript/TypeScript，通过通用进程接口调用 Python 脚本和系统命令。首款官方插件负责 Python/pip、NPU 与系统环境检查，使用与第三方插件相同的公开接口，按工作流依赖选入分发包。插件声明 Python 等环境使用宿主机还是自带资源；环境检查与业务兼容性由插件作者负责。包内始终携带编排器所需的 Node，完整便携包也携带 npm。
+
+## npm 安装与启动（Windows / Linux）
+
+安装端需要 Node.js 24.15.0 或更高版本以及 npm。已发布版本可从 npm 安装：
+
+```sh
+npm install -g @yanglaofish/fishtools
+fst
+```
+
+也可从 GitHub Release 下载 `.tgz` 后执行 `npm install -g ./yanglaofish-fishtools-0.3.0.tgz`。没有 Node/npm 的机器使用 Release 中的 Windows `.zip` 或 Linux `.tar.gz` 自包含包，解压后运行 `fst.cmd` 或 `./fst`。发布结果以 [GitHub Releases](https://github.com/yanglaofish/Fishtools/releases) 为准；当前仓库为私有，下载附件需要仓库访问权限。
+
+`fst` 在交互终端里启动终端工作台（TUI）；`fst web` 启动 Web 并打印访问地址；`fst run hello` 直接执行工作流。首次使用在 `~/.fishtools` 创建工作区，也可通过 `FISHTOOLS_HOME` 指定。安装包已包含官方插件、页面和生产依赖，不需要源码仓库或前端构建。
+
+```sh
+fst web --port 8765
+fst workflow list
+fst run hello
+fst init ./my-project
+fst --project ./my-project
+fst --project ./my-project run hello
+fst --project ./my-project pack hello --target linux-x64-glibc --web
+```
+
+优先使用 `--project`，其次当前目录的项目，再使用用户默认工作区。已有项目不会被初始化覆盖。Linux 无桌面环境可直接使用终端界面，也可以通过端口转发访问 `fst web`。
+
+启动命令已从 `fish` 改为 `fst`，避免占用 Fish Shell 的命令。npm 包名为 `@yanglaofish/fishtools`；新安装包只注册 `fst`。升级旧版时请先卸载旧安装版再安装新包。
+
+## 交互终端：无需记住全部参数
+
+启动 `fst` 后输入 `/` 会展开操作列表，使用上下箭头选择、Tab 补全、Enter 确认，Escape 返回。普通输入与插件命令忙碌页使用 Ctrl+C 取消；运行观察面板内 Ctrl+C 只关闭面板。在主提示符处 Ctrl+C 请求退出，有未保存修改或后台运行时会先确认。
+
+首页展示 FISHtools 字符标识、欢迎介绍、当前工作区以及插件和工作流数量；小窗口自动使用紧凑标题。首次使用可以输入 `/run hello`，按提示输入文本（也可保留默认值），体验“转为大写 → 追加标记 → 保存文件”。运行过程与输入输出留在主面板，期间仍可打开配置或执行其他工作流。PgUp/PgDn 或鼠标滚轮浏览会话中的过程，向下翻至末尾恢复跟随。首页只推荐当前工作区实际存在的工作流；空工作区从 `/workflows` 新建。
+
+顶部的“位置”显示主面板或当前操作入口，菜单标题显示正在操作的对象。提交的命令、菜单选择与实际操作结果保留在本次会话中；返回时只更新当前位置，不追加通用返回消息，也不清空执行过程。这些导航记录只保留在当前会话。
+
+主面板查看当前执行，`/logs` 回看某次执行的步骤状态、输入输出和日志，也能重新打开正在运行的任务详情。查看记录不会重新执行工作流。旧 `/runs` 和 F4 仅作为兼容方式转到同一个 `/logs` 入口，不再提供独立列表。
+
+主面板默认按步骤显示“执行中／成功／失败”，每一步标明能力与插件；**Ctrl+O 展开/收起详情**，查看各步输入输出、作者日志和子进程 stdout/stderr。错误摘要与插件 `print()` 的用户提示直接展示，普通技术日志默认折叠。折叠只改变展示，不丢弃日志或结果。
+
+主输入框用 **↑ / ↓** 回看本次启动中已提交的命令，向下回到底部恢复未提交草稿。补全菜单打开时，方向键仍选择候选；配置表单内容不进入命令历史。最多保留最近 100 条，相邻重复命令合并，退出后不保存。
+
+`/plugin` 直接列出当前已加载的插件名称、版本和状态。上下选择后可查看用途、编排能力、输入输出、环境声明及斜杠命令；有配置的插件提供配置入口，自行安装的插件提供移除入口。内置插件标明来源，避免误以为没有安装。`/help` 在终端内提供可翻页的用法说明。顶层补全标明 `[内置]` 或 `[插件]`，插件能力收进插件名入口的二级菜单。
+
+| 操作 | 功能 |
+| --- | --- |
+| `/workflows` | 浏览、新建；进入某个流程后添加/编辑步骤、设置输出、保存、运行或删除 |
+| `/run 工作流ID` | 可按 ID 或中文标题补全，填写参数后执行已保存版本；只输入 `/run` 打开已保存工作流列表 |
+| `/logs` | 回看执行记录，运行中的任务优先；可切换总览、输入输出与日志，支持键盘或鼠标滚轮阅读 |
+| `/plugin` | 浏览已安装插件、用途及能力，进入插件配置、安装和移除操作 |
+| `/pack` | 勾选工作流并选择目标平台打包 |
+| `/config` | 配置 Fishtools：查看工作区信息，设置整个项目的日志保留次数 |
+| `/tools` | 启动 Web 或阅读离线资料 |
+| `/help`、`/exit` | 查看帮助、退出 |
+
+旧 `/new`、`/add`、`/steps`、`/outputs`、`/save`、`/plugins`、`/docs`、`/web` 和 `/runs` 仍可直接输入，顶层补全主要呈现上表的对象入口。工作流编辑菜单返回时保留当前草稿，切换流程或退出会确认未保存修改。删除会将已保存文件移入 `.flow/deleted-workflows/工作流ID-编号.yaml`，仍被其他流程引用时拒绝删除；恢复时将备份复制回 `workflows/原工作流ID.yaml`，先确认同名文件不存在，避免覆盖。
+
+`/run` 不要求保存当前编辑草稿，也不会丢弃它。要运行尚未保存的修改，请在 `/workflows` 的编辑菜单选择“运行工作流”，再选择“保存并运行”；已有磁盘版本时也可选择“运行已保存版本”并保留草稿。“返回编辑”会留在当前工作流，不会反复弹出保存确认。只查看参数或拒绝删除步骤不会产生未保存修改。
+
+参数来源可选固定值、每次运行时填写或前序步骤的输出。对象逐字段编辑，数组逐项编辑；复杂 schema 可以输入 JSON 值。终端本身无需 Web 插件或 LLM。
+
+条件分支只执行命中的一侧；并行组同时执行独立步骤，可设置 1–32 的最大并发数（默认 4）。步骤的执行条件不满足时跳过。提前结束节点正常停止整个运行并保留原因，显示为 `stopped`；主动取消显示为 `cancelled`，执行异常显示为 `failed`。插件返回业务结果，由工作流决定结果不符合要求时如何处理。
+
+运行观察面板键位：
+
+| 按键 | 操作 |
+| --- | --- |
+| `1` / `2` / `3` | 步骤总览 / 输入输出 / 实时日志 |
+| `[` / `]` | 切换步骤调用；相同插件的不同调用分别显示 |
+| `a` | 切换当前步骤与全部日志 |
+| ↑↓、鼠标滚轮、PageUp/PageDown、Home/End | 滚动、翻页、跳转开头或尾部；手动滚动暂停日志跟随，End 恢复跟随 |
+| `f` | 切换日志跟随 |
+| Enter | 在总览中查看所选步骤详情，不退出面板 |
+| `j` | 在易读字段与原始 JSON 诊断之间切换 |
+| Esc、q、Ctrl+C | 返回上一级，运行中的任务继续；输入 `/logs` 可重新打开 |
+| `x`，再按 `y` | 确认取消整个运行 |
+
+运行记录同时列出正在执行和保留的历史记录，运行中任务优先；同一个工作流的多次执行分别显示时间和记录编号。查看详情后返回列表，可以继续选择另一次执行。本次启动期间每次运行分别保存阅读位置；重启后可通过 `/logs` 查看保存的记录，主面板会话展示从新会话开始。日志保留设置在 `/config`。主提示符 `/exit` 或 Ctrl+C 遇到后台任务时，会说明退出将取消任务并请求确认，默认不退出。
+
+插件可以注册自己的命令：官方示例的 `/examples` 入口包含文本转大写与交互文本输入，`/environment` 入口包含环境检查与报告。原 `/text.upper`、`/text.ask`、`/env.check`、`/env.report` 仍可直接调用。`check` 在环境未通过时抛错；`report` 正常返回 `ok:false` 和检查明细，适合交给工作流条件判断。安装或移除插件会同步刷新 `/` 菜单；命令和工作流共用日志、取消和结果机制。
+
+在字符串参数中输入 `@` 可选择本地文件或目录，引用结果为绝对路径；`@@文字` 表示以 @ 开头的普通文字。`/run hello @"输入 参数.json"` 则明确读取文件中的 JSON 对象作为运行输入。文件路径相对启动时的目录（在 `/help` 中显示），不会自动上传文件，也不会把文件内容当作命令。路径补全无需额外安装 `fd`。
+
+非 TTY（例如重定向输入）直接执行 `fst` 只显示帮助；自动化请使用 `fst run`、`fst pack` 等子命令。只读运行包提供终端选流程、填写输入和运行功能。
+
+## 源码开发启动
+
+### 源码预览
+
+已有源码依赖时，在仓库根目录运行 `npm run preview`；Windows 也可双击 `fst-preview.cmd`。首页标识“本地源码预览”。工作区位于 `.cache/log-preview-win32` 或 `.cache/log-preview-linux`，不会升级全局 `fst`，也不会改动用户默认工作区。
+
+- 输入 **`/logs`**，查看已生成的成功、缺少解释器失败示例。
+- 输入 `/run preview-pipeline`，体验三个不同插件“准备文本 → 转大写 → 保存报告”。文本和演示等待时间可以调整；默认查看步骤状态，Ctrl+O 展开输入输出，保存位置由插件直接展示。
+- 输入 `/run preview-stream`，Tab 补全、Enter 执行，Ctrl+O 展开后查看持续输出；用 PgUp/PgDn 或滚轮回看。
+- 输出期间输入 `/config` 查看工具设置，Esc 返回后过程仍在；再执行 `/run preview-success`，体验同一会话里的多个工作流。
+- `/workflows` 进入管理与编辑；`/examples` 或 `/local-log-preview` 进入插件能力菜单。
+- `/logs` 选择某次执行后，`1/2/3` 切换总览、输入输出、日志；`j` 查看原始诊断，`q` 返回。
+
+示例流程只在首次启动时创建，之后保留本地修改；故意失败示例不检查或改变机器的实际 Python 安装。
+
+### 常规源码启动
+
+开发机器安装 **Node.js 24.15.0** 和 npm，在仓库根目录执行：
+
+```sh
+npm ci
+npm run build
+npm start
+# 或启动 Web
+npm run web
+```
+
+使用 Web 时，打开终端打印的完整地址（含 `#token=...`）。界面、图标、表单资源均本地提供。开发依赖安装需要联网；导出的运行包不需要 Node/npm 或联网安装依赖。
+
+源码启动的默认项目是 `examples`。首次打开进入工作流总览，可以搜索并打开现成流程，或点击“新建工作流”。编辑器中点击“添加步骤”选择能力、子工作流，或进入“流程控制”添加分支、并行组和提前结束；点击节点用表单设置参数、执行条件、并发数、结束原因及内部步骤。输入可来自固定值、运行时输入或前序步骤输出；小窗口会就近打开参数弹窗。支持拖动和上下箭头排序；引用失效时阻止运行。“工作流输出”区域选择最终返回的数据。
+
+保存后点击“运行工作流”。“查看运行”面板提供步骤总览、输入输出、实时日志，并按调用路径筛选；stdout/stderr 在受管子进程执行期间持续显示。向上滚动日志会暂停跟随，点击“恢复自动跟随”可继续看尾部。关闭观察窗口后任务继续，点击“停止运行”才发送取消请求。只读运行包允许观察和运行，不允许编辑流程。
+
+运行 `npm run dist:npm` 生成当前版本的 `dist/yanglaofish-fishtools-版本号.tgz`。使用 [npm 原生 bundleDependencies](https://docs.npmjs.com/cli/configuring-npm/package-json/#bundledependencies) 打包安装依赖。推送 `v版本号` tag 后，GitHub Actions 验证跨平台安装和运行，再发布 npm 并生成带自包含附件的 Release；流程和重试规则见[发布说明](docs/releases.md)。
+
+## CLI
+
+```sh
+npm run fst -- --project examples workflow list
+npm run fst -- --project examples run hello
+npm run fst -- --project examples run system-check
+npm run fst -- --project examples run python-check --input python-input.json
+npm run fst -- --project examples plugin add /absolute/path/to/my-plugin
+npm run fst -- --project examples pack hello system-check --target win32-x64 --web
+npm run fst -- --project examples pack hello python-check --target linux-x64-glibc --web
+```
+
+`python-input.json` 示例：
+
+```json
+{"executable":"/usr/bin/python3","text":"hello"}
+```
+
+Windows 路径在 JSON 中写成 `"F:\\miniconda\\python.exe"`。请使用实际解释器路径；后续步骤使用环境检查返回的解释器执行脚本。
+
+`fst run` 和 `fst command` 遇到正常提前结束时，以退出码 0 返回 `{status:'stopped', reason:'结束原因'}`。此前成功步骤的输入输出、实时日志和停止原因仍保存在运行记录中。
+
+## 自包含打包
+
+Web 中点击“打包”，选择工作流、目标平台、是否含 Web。工具自动收集子工作流、插件、生产 npm 依赖、脚本和 Node.js。没有依赖关系的其他工作流不入包。
+
+| 目标 | 产物 | 解压后启动 |
+| --- | --- | --- |
+| Windows x64 | ZIP | `fst.cmd` 进入终端，`fst.cmd run hello` 直接运行；含 Web 时可用 `fst.cmd web` |
+| Linux x64 glibc | tar.gz | `./fst` 进入终端，`./fst run hello` 直接运行；含 Web 时可用 `./fst web` |
+| 兼容 Linux 容器 | 挂载 Linux 包目录 | `/opt/flow/fst run hello` |
+
+默认导出完整工具及选中工作流、插件，携带 Node 和内部 npm，目标机无需另装 Node/npm。首次启动把初始工作流复制到独立可写工作区，以后可在同一 TUI 修改固定参数、保存插件配置、安装插件和再次导出；分发包原文件保持不变。私有配置不默认复制，目标端用 `/config`、`fst configure` 或 `--config` 提供。首次打包下载经过校验的固定版本 Node.js 并缓存。
+
+```sh
+# 导出当前全部插件和工作流，作为完整便携工具
+fst portable --target linux-x64-glibc
+# 选择部分工作流；先查看环境资源计划
+fst pack hello --target linux-x64-glibc --plan
+# 可选：导出只有执行能力的精简包，不含 npm/打包工具
+fst pack hello --target linux-x64-glibc --read-only
+# 便携版指定可写工作区
+./fst --workspace /srv/fishtools-workspace
+export PATH="/opt/fishtools/bin:$PATH"
+```
+
+默认工作区位于 `~/.fishtools/workspaces/<包ID>`，也可设置 `FISHTOOLS_WORKSPACE`。Linux 容器可只读挂载包、单独挂载工作区。Python、驱动等由插件声明使用宿主环境或携带作者准备的资源；`/pack` 可切换作者允许的来源，CLI 使用 `--environments 文件.json`。声明支持的平台由插件作者负责，核心不做业务兼容性审核。
+
+npm 安装版是完整编排工具；上表为按所选流程导出的自包含运行包。旧的 `run.sh`/`run.cmd`、`web.sh`/`web.cmd` 入口仍保留。内部 `@mytools/*` 插件标识和 `flow.project.json` 格式继续兼容已有项目。
+
+## 文档与开发
+
+完整 npm 与便携发行包携带 `manual/` 离线资料。只安装 npm 包的开发者可用 `fst docs` 查看主题，`fst docs plugins` 阅读规范，`fst docs plugins --path` 定位本地文件，或 `fst docs --export ./fishtools-manual` 导出完整资料（目标必须不存在）。TUI 使用 `/docs` 阅读。规范、源码阅读参考、许可证以及[可安装的零依赖动作插件](docs/examples/action-plugin/README.md)一起分发，无需克隆仓库或另行安装内部 SDK。资料对应当前安装版本，离线安装、阅读、导出和示例接入均纳入分发验收。
+
+- 服务插件可使用 Cordis `runtime` 声明共享服务和生命周期；修改有状态插件前，TUI `/plugins` 进入维护模式，或 CLI 使用 `--maintenance`。示例见 [共享服务插件](examples/service-plugins/README.md)。
+- [当前里程碑与路线图](docs/roadmap.md)
+- [插件开发与公共接口](docs/plugin-development.md)
+- [离线部署与堡垒机访问](docs/deployment.md)
+- [验收记录与限制](docs/verification.md)
+- [目标与设计](docs/superpowers/specs/2026-10-09-workflow-cli-design.md)
+- [实施计划](docs/superpowers/plans/2026-10-09-workflow-mvp.md)
+- [开源来源与许可证](THIRD_PARTY_NOTICES.md)
+
+核心在 `packages/core`，SDK 在 `packages/sdk`，打包在 `packages/pack`，官方插件在 `plugins`。使用 npm workspaces 与提交的 lockfile 固定依赖。运行 `npm test` 验证。
+
+参与编排的插件动作必须声明有效的 input/output JSON Schema；无参数或无输出也声明空对象 schema。正常返回且输出通过校验即执行成功，可选 `conditions` 预设帮助用户选择业务判断。通过上下文 `runProcess` 执行的 stdout/stderr 会自动进入实时日志；完整协议、引用范围和并行取消规则见[插件开发文档](docs/plugin-development.md)。
+
+首版优先 Windows x64 和 Linux x64 glibc。Alpine/musl、ARM、Windows 容器与分布式调度未纳入；真实 NPU 硬件验证仍待进行。

package/manual/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,32 @@
+# 开源复用与来源
+
+本项目通过固定版本的 npm 依赖复用以下组件。准确版本与传递依赖见 `package-lock.json`。许可证以各包附带文件为准；没有将其他许可证统一改写为 MIT。
+
+| 项目 | 用途 | 许可证 | 上游 |
+| --- | --- | --- | --- |
+| Cordis 3.18.1 | 插件生命周期 | MIT | https://github.com/cordiverse/cordis |
+| Ajv | 输入输出校验 | MIT | https://github.com/ajv-validator/ajv |
+| YAML | 工作流文件解析 | ISC | https://github.com/eemeli/yaml |
+| Commander | CLI 参数与帮助 | MIT | https://github.com/tj/commander.js |
+| Pi TUI 0.50.0 | 终端渲染、编辑器、补全与方向键选择 | MIT | https://github.com/badlogic/pi-mono/tree/main/packages/tui |
+| Execa | 跨平台程序调用 | MIT | https://github.com/sindresorhus/execa |
+| tree-kill | 受管子进程回收 | MIT | https://github.com/pkrumins/node-tree-kill |
+| which、semver | 可执行文件发现与版本检查 | ISC | https://github.com/npm/cli |
+| Arborist、npm-packlist、make-fetch-happen | npm 依赖树、发布文件与下载 | ISC | https://github.com/npm/cli |
+| Archiver | ZIP、tar.gz 归档 | MIT | https://github.com/archiverjs/node-archiver |
+| node-tar | 官方 Node.js Linux 归档解压 | BlueOak-1.0.0 | https://github.com/isaacs/node-tar |
+| React | Web 视图 | MIT | https://github.com/facebook/react |
+| react-jsonschema-form | 根据插件元数据生成表单 | Apache-2.0 | https://github.com/rjsf-team/react-jsonschema-form |
+| dnd-kit | 步骤列表拖拽与键盘排序 | MIT | https://github.com/clauderic/dnd-kit |
+| Geist（Fontsource 本地分发） | 离线英文字体 | OFL-1.1 | https://github.com/fontsource/font-files/tree/main/fonts/google/geist |
+| Lucide | 界面图标 | ISC | https://github.com/lucide-icons/lucide |
+| Express | HTTP、JSON 与静态文件服务 | MIT | https://github.com/expressjs/express |
+| Vite | 开发阶段构建离线前端资源 | MIT | https://github.com/vitejs/vite |
+
+标准运行包保留生产依赖内的 LICENSE/NOTICE，并附带 Node.js 官方完整许可文件。Web 构建将安装树中的许可证汇总到静态资源 `THIRD_PARTY_NOTICES.txt`，一并进入含 Web 的运行包。
+
+终端采用固定版本 `@mariozechner/pi-tui@0.50.0`：此版本提供所需交互且无原生二进制依赖，便于 Windows 上导出 Linux 包。上游后续迁移到 `@earendil-works/pi-tui` 并引入原生平台组件，升级时需重新验收跨平台分发。Fishtools 仅添加宿主交互适配及不依赖外部 `fd` 的目录补全，没有复制 Pi Agent 或 LLM 层代码。
+
+用户指定的 [dsh-skill-manager](https://github.com/yanglaofish/dsh-skill-manager) 已使用 `gh repo clone` 克隆到被 Git 忽略的 `.cache/references/` 目录，用于研究公开的插件入口、依赖声明与 Host/Web 分工。本次没有复制该仓库的源代码，也不声称其插件可直接安装进本项目。
+
+DSH 的插件化开发范式作为架构参考。本项目只实现普通顺序编排，不引入 DSH 的 LLM/Agent 应用层。后续若复制其他仓库中的代码，应在此记录文件、上游提交、修改说明，并保留原许可证与版权声明。

package/manual/docs/examples/action-plugin/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/docs/examples/action-plugin/README.md

@@ -0,0 +1,38 @@
+# 可安装的离线动作插件
+
+本目录是完整的插件包，使用标准对象定义与 Node.js，不需要下载额外 SDK，也没有 npm 依赖。请先安装包含本手册版本的 Fishtools。
+
+## 安装与调用
+
+在可写目录执行；导出目录必须尚不存在：
+
+```sh
+fst docs --export ./fishtools-manual
+fst --maintenance plugin add ./fishtools-manual/docs/examples/action-plugin
+fst command offline.greet --input ./fishtools-manual/docs/examples/action-plugin/input.json
+```
+
+结果为 `{"text":"你好，离线用户"}`。也可启动 `fst`，输入 `/offline.greet` 并填写姓名。首次使用默认工作区，已有项目则使用当前项目；用全局 `--project <目录>` 明确选择项目。只读便携包不能安装插件，请使用完整便携包或 npm 安装版。
+
+## 修改与编排
+
+复制本目录，修改 `package.json` 的 `name/version` 和 `index.js` 的同名字段。动作必须声明有效的 `input/output` JSON Schema；字段类型、必填项和条件预设遵守[插件开发规范](../../plugin-development.md)。示例的 `greet` 无业务通过/未通过判定，正常返回且输出校验通过即执行成功。
+
+将以下内容保存到所选项目的 `workflows/offline-greeting.yaml`，运行 `fst workflow check offline-greeting` 后执行 `fst run offline-greeting`：
+
+```yaml
+schemaVersion: 1
+id: offline-greeting
+steps:
+  - id: greeting
+    action: fishtools-offline-greeting:greet
+    with:
+      name: 离线用户
+outputs:
+  text:
+    $ref: steps.greeting.output.text
+```
+
+长任务应响应上下文 `signal`；使用 `await log(message,data)` 记录日志，避免输出令牌或密码。调用外部程序时使用上下文 `runProcess` 并传递 `signal`，stdout/stderr 会实时记录。新增文件应放入 `package.json.files`，安装与分发才能携带。
+
+可将本目录交给另一台机器上的 `fst plugin add <目录>`，或使用本机 npm 的 `npm pack` 生成插件归档。Fishtools 内部使用的 `@mytools/sdk` 不要求已单独发布到公共 npm；本示例不依赖它。服务生命周期与依赖注入另见[服务插件示例](../../../examples/service-plugins/README.md)。

package/manual/docs/examples/action-plugin/index.js

@@ -0,0 +1,18 @@
+// 直接导出标准定义对象，不需要安装额外 SDK。
+export default {
+  id:'fishtools-offline-greeting',version:'1.0.0',sdk:'^0.1.0',
+  title:'离线问候示例',description:'可直接安装的零依赖动作插件。',
+  commands:{'offline.greet':{description:'生成问候文本',action:'greet'}},
+  actions:{
+    greet:{
+      title:'生成问候',description:'使用输入姓名生成文本；只写运行日志，不修改外部文件。',
+      input:{type:'object',required:['name'],properties:{name:{type:'string',minLength:1,title:'姓名'}},additionalProperties:false},
+      output:{type:'object',required:['text'],properties:{text:{type:'string',title:'问候文本'}},additionalProperties:false},
+      async run({name},{log,signal}){
+        signal.throwIfAborted();
+        await log('正在生成问候',{name});
+        return {text:`你好，${name}`};
+      },
+    },
+  },
+};

package/manual/docs/examples/action-plugin/input.json

@@ -0,0 +1 @@
+{"name":"离线用户"}

package/manual/docs/examples/action-plugin/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "fishtools-offline-greeting",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "index.js",
+  "files": ["index.js", "README.md", "LICENSE", "input.json"],
+  "license": "MIT",
+  "engines": {"node": ">=24.15.0"}
+}

package/manual/docs/examples/pipeline-reader/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/docs/examples/pipeline-reader/index.js

@@ -0,0 +1,14 @@
+import {setTimeout} from 'node:timers/promises';
+
+export default {
+  id:'fishtools-example-reader',version:'0.1.0',title:'文本准备示例',platforms:['win32','linux'],
+  actions:{prepare:{
+    title:'准备文本',description:'整理输入文本，输出给另一个插件处理。等待时间仅用于观察执行状态，可设为 0。',
+    input:{type:'object',required:['text'],properties:{text:{type:'string',title:'待处理文本'},delayMs:{type:'integer',minimum:0,maximum:10000,default:1000,title:'演示等待毫秒数'}}},
+    output:{type:'object',required:['text'],properties:{text:{type:'string'}}},
+    async run({text,delayMs=1000},{log,signal}){
+      await log('准备文本参数',{characters:text.length,delayMs});
+      await setTimeout(delayMs,undefined,{signal});return {text:text.trim()};
+    },
+  }},
+};

package/manual/docs/examples/pipeline-reader/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "fishtools-example-reader",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "index.js",
+  "license": "MIT"
+}

package/manual/docs/examples/pipeline-writer/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.