@yanglaofish/fishtools 0.1.3 → 0.2.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.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.3.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.2.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,24 +39,47 @@ 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`，按提示输入文本（也可保留默认值），体验“转为大写 → 追加标记 → 保存文件”；执行后输入 `/logs` 阅读日志。首页只推荐当前工作区实际存在的工作流，空工作区提示用 `/new` 创建。
+
+`/plugins` 直接列出当前已加载的插件名称、版本和状态。上下选择后可查看用途、编排能力、输入输出、环境声明及斜杠命令；有配置的插件提供配置入口，自行安装的插件提供移除入口。内置插件标明来源，避免误以为没有安装。`/help` 在终端内提供可翻页的用法说明。
 
 | 操作 | 功能 |
 | --- | --- |
 | `/workflows`、`/new` | 选择已有工作流，或新建流程 |
-| `/add`、`/steps` | 添加能力/子工作流，设置参数、排序、删除步骤 |
+| `/add`、`/steps` | 添加能力、子工作流、条件分支、并行组或提前结束；编辑内部步骤、参数和执行条件 |
 | `/outputs`、`/save` | 选择汇总输出，保存为 Web 可继续编辑的同一份流程 |
-| `/run` | 逐字段填写运行参数并执行，显示状态、结果和可直接阅读的 Markdown 日志路径 |
-| `/logs` | 在终端内翻页阅读历史日志，设置整个项目保留最近 N 次日志 |
-| `/plugins`、`/pack` | 安装/移除插件，勾选工作流并选择目标平台打包 |
+| `/run` | 逐字段填写运行参数并执行，打开步骤、输入输出和实时日志观察面板 |
+| `/runs` | 选择当前会话的运行，重新打开观察面板；关闭面板后任务继续 |
+| `/logs` | 用键盘或鼠标滚轮阅读持久化历史日志，设置整个项目保留最近 N 次日志 |
+| `/plugins` | 浏览已安装插件、用途及能力，进入配置、安装和移除操作 |
+| `/pack` | 勾选工作流并选择目标平台打包 |
 | `/config` | 编辑并保存插件声明的配置 |
+| `/docs` | 阅读随安装提供的开发规范、控制流说明与示例 |
 | `/web`、`/help`、`/exit` | 启动可选 Web、查看说明、退出 |
 
 参数来源可选固定值、每次运行时填写或前序步骤的输出。对象逐字段编辑，数组逐项编辑；复杂 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` | 切换日志跟随 |
+| Esc、q、Enter、Ctrl+C | 关闭面板，任务继续运行；可用 `/runs` 返回 |
+| `x`，再按 `y` | 确认取消整个运行 |
+
+`/runs` 显示当前会话的运行，包含已完成任务；重启后的历史用 `/logs` 查看。历史阅读器支持方向键、滚轮、PageUp/PageDown、Home/End，Esc、Enter 或 q 返回。主提示符 `/exit` 或 Ctrl+C 遇到后台任务时，会说明退出将取消任务并请求确认，默认不退出。
+
+插件可以注册自己的命令：官方示例提供 `/text.upper`、交互式 `/text.ask`、`/env.check` 和 `/env.report`。`check` 在环境未通过时抛错，保持旧流程行为；`report` 正常返回 `ok:false` 和检查明细，适合交给工作流条件判断。安装或移除插件会同步刷新 `/` 菜单；命令和工作流共用日志、取消和结果机制。
 
-在字符串参数中输入 `@` 可选择本地文件或目录，引用结果为绝对路径；`@@文字` 表示以 @ 开头的普通文字。`/run hello @"输入 参数.json"` 则明确读取文件中的 JSON 对象作为运行输入。文件路径相对启动时的目录（屏幕中会显示），不会自动上传文件，也不会把文件内容当作命令。路径补全无需额外安装 `fd`。
+在字符串参数中输入 `@` 可选择本地文件或目录，引用结果为绝对路径；`@@文字` 表示以 @ 开头的普通文字。`/run hello @"输入 参数.json"` 则明确读取文件中的 JSON 对象作为运行输入。文件路径相对启动时的目录（在 `/help` 中显示），不会自动上传文件，也不会把文件内容当作命令。路径补全无需额外安装 `fd`。
 
 非 TTY（例如重定向输入）直接执行 `fst` 只显示帮助；自动化请使用 `fst run`、`fst pack` 等子命令。只读运行包提供终端选流程、填写输入和运行功能。
 
@@ -72,9 +97,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
 
@@ -96,6 +123,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。没有依赖关系的其他工作流不入包。
@@ -126,15 +155,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,173 @@
+# Fishtools
+
+基于 Cordis 的插件式工作流工作台，启动命令是 **`fst`**。
+
+目标是提供轻量、可扩展的工作流工具：用户查看可用能力与现成工作流，将它们加入列表、填写输入、设置条件、选择输出并运行；也能将选定工作流及其依赖打包成可离线运行的 Windows 或 Linux 分发包。Linux 包可挂载到兼容的 Linux 容器内运行。
+
+交互终端支持选择能力、配置参数和流程编排；官方 Web 插件默认提供，原子 CLI 子命令用于自动化。三种入口共用应用服务。YAML、依赖锁和版本解析由系统维护，不要求普通用户手写。
+
+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.2.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`，按提示输入文本（也可保留默认值），体验“转为大写 → 追加标记 → 保存文件”；执行后输入 `/logs` 阅读日志。首页只推荐当前工作区实际存在的工作流，空工作区提示用 `/new` 创建。
+
+`/plugins` 直接列出当前已加载的插件名称、版本和状态。上下选择后可查看用途、编排能力、输入输出、环境声明及斜杠命令；有配置的插件提供配置入口，自行安装的插件提供移除入口。内置插件标明来源，避免误以为没有安装。`/help` 在终端内提供可翻页的用法说明。
+
+| 操作 | 功能 |
+| --- | --- |
+| `/workflows`、`/new` | 选择已有工作流，或新建流程 |
+| `/add`、`/steps` | 添加能力、子工作流、条件分支、并行组或提前结束；编辑内部步骤、参数和执行条件 |
+| `/outputs`、`/save` | 选择汇总输出，保存为 Web 可继续编辑的同一份流程 |
+| `/run` | 逐字段填写运行参数并执行，打开步骤、输入输出和实时日志观察面板 |
+| `/runs` | 选择当前会话的运行，重新打开观察面板；关闭面板后任务继续 |
+| `/logs` | 用键盘或鼠标滚轮阅读持久化历史日志，设置整个项目保留最近 N 次日志 |
+| `/plugins` | 浏览已安装插件、用途及能力，进入配置、安装和移除操作 |
+| `/pack` | 勾选工作流并选择目标平台打包 |
+| `/config` | 编辑并保存插件声明的配置 |
+| `/docs` | 阅读随安装提供的开发规范、控制流说明与示例 |
+| `/web`、`/help`、`/exit` | 启动可选 Web、查看说明、退出 |
+
+参数来源可选固定值、每次运行时填写或前序步骤的输出。对象逐字段编辑，数组逐项编辑；复杂 schema 可以输入 JSON 值。终端本身无需 Web 插件或 LLM。
+
+条件分支只执行命中的一侧；并行组同时执行独立步骤，可设置 1–32 的最大并发数（默认 4）。步骤的执行条件不满足时跳过。提前结束节点正常停止整个运行并保留原因，显示为 `stopped`；主动取消显示为 `cancelled`，执行异常显示为 `failed`。插件返回业务结果，由工作流决定结果不符合要求时如何处理。
+
+运行观察面板键位：
+
+| 按键 | 操作 |
+| --- | --- |
+| `1` / `2` / `3` | 步骤总览 / 输入输出 / 实时日志 |
+| `[` / `]` | 切换步骤调用；相同插件的不同调用分别显示 |
+| `a` | 切换当前步骤与全部日志 |
+| ↑↓、鼠标滚轮、PageUp/PageDown、Home/End | 滚动、翻页、跳转开头或尾部；手动滚动暂停日志跟随，End 恢复跟随 |
+| `f` | 切换日志跟随 |
+| Esc、q、Enter、Ctrl+C | 关闭面板，任务继续运行；可用 `/runs` 返回 |
+| `x`，再按 `y` | 确认取消整个运行 |
+
+`/runs` 显示当前会话的运行，包含已完成任务；重启后的历史用 `/logs` 查看。历史阅读器支持方向键、滚轮、PageUp/PageDown、Home/End，Esc、Enter 或 q 返回。主提示符 `/exit` 或 Ctrl+C 遇到后台任务时，会说明退出将取消任务并请求确认，默认不退出。
+
+插件可以注册自己的命令：官方示例提供 `/text.upper`、交互式 `/text.ask`、`/env.check` 和 `/env.report`。`check` 在环境未通过时抛错，保持旧流程行为；`report` 正常返回 `ok:false` 和检查明细，适合交给工作流条件判断。安装或移除插件会同步刷新 `/` 菜单；命令和工作流共用日志、取消和结果机制。
+
+在字符串参数中输入 `@` 可选择本地文件或目录，引用结果为绝对路径；`@@文字` 表示以 @ 开头的普通文字。`/run hello @"输入 参数.json"` 则明确读取文件中的 JSON 对象作为运行输入。文件路径相对启动时的目录（在 `/help` 中显示），不会自动上传文件，也不会把文件内容当作命令。路径补全无需额外安装 `fd`。
+
+非 TTY（例如重定向输入）直接执行 `fst` 只显示帮助；自动化请使用 `fst run`、`fst pack` 等子命令。只读运行包提供终端选流程、填写输入和运行功能。
+
+## 源码开发启动
+
+开发机器安装 **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/plans/2026-10-10-workbench-ui.md

@@ -0,0 +1,27 @@
+# Fishtools 工作台易用性优化
+
+> 历史实施记录。后续 TUI、便携工具及远端 CI 状态见 [当前路线图](../roadmap.md)；本文末尾的“仍待验证”仅描述该次 UI 开发阶段。
+
+## 目标
+
+首版功能验收已完成；本轮让首次使用者能直接找到已有工作流，理解添加步骤、设置参数、运行与查看结果的路径。保持离线可用和 CLI/Web 共用执行核心。
+
+## 已确定的设计
+
+- 默认进入工作流总览，展示用途、步骤数、运行输入和输出；支持搜索、打开、新建。
+- 编辑器保留能力库、顺序列表、参数检查器。窄屏时参数用可关闭的侧边弹窗展示，不落到页面最底部。
+- 每个步骤提供可聚焦的“设置参数”入口；排序和删除始终可见。
+- 使用深色文字、青绿色强调色、本地字体与轻量过渡，尊重减少动态效果设置。gpt-taste 的营销页结构、远程素材和滚动锁定与高效离线工作台不符，本轮不采用。
+- 弹窗使用浏览器原生 dialog 管理焦点和 Escape；提交错误在当前弹窗显示。
+- 保留数据、现有插件和工作流格式，不改变执行协议。
+
+## 实施与验收
+
+1. 添加首页、状态引导和简洁结果视图，整理视图组件。
+2. 重做布局、表单和窄屏参数面板，保留键盘操作。
+3. 构建，跑现有测试；浏览器实测首页、编辑、保存、运行和窄屏；检查无横向溢出。
+4. 独立代码审查，补充验收记录，更新 npm 安装包并本地提交。
+
+## 原有验收边界
+
+Windows 本机、WSL、Linux 容器和 npm 安装已验证。真实 NPU、干净 Windows 虚机和远端 CI 仍待相应环境，不声明为已验证。