@yanglaofish/fishtools 0.2.0 → 0.3.0

package/README.md

@@ -6,7 +6,7 @@
 
 交互终端支持选择能力、配置参数和流程编排；官方 Web 插件默认提供，原子 CLI 子命令用于自动化。三种入口共用应用服务。YAML、依赖锁和版本解析由系统维护，不要求普通用户手写。
 
-0.2.0 增加条件分支、并行组、提前结束、实时运行观察，以及随安装提供的离线开发手册。本文对应此版本源码；发布与验证状态见 [版本记录](manual/docs/releases.md) 和 [验收记录](manual/docs/verification.md)。
+0.3.0 增加按对象组织的终端菜单、主面板执行摘要与插件用户输出、命令历史，并修复第三方插件进程调用和离线 Web 打包。此前 0.2.0 引入的条件控制、运行观察和离线开发手册仍可使用。发布与验证状态见 [版本记录](manual/docs/releases.md) 和 [验收记录](manual/docs/verification.md)。
 
 插件接入层使用 JavaScript/TypeScript，通过通用进程接口调用 Python 脚本和系统命令。首款官方插件负责 Python/pip、NPU 与系统环境检查，使用与第三方插件相同的公开接口，按工作流依赖选入分发包。插件声明 Python 等环境使用宿主机还是自带资源；环境检查与业务兼容性由插件作者负责。包内始终携带编排器所需的 Node，完整便携包也携带 npm。
 
@@ -19,7 +19,7 @@ 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) 为准；当前仓库为私有，下载附件需要仓库访问权限。
+也可从 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` 指定。安装包已包含官方插件、页面和生产依赖，不需要源码仓库或前端构建。
 
@@ -41,23 +41,32 @@ fst --project ./my-project pack hello --target linux-x64-glibc --web
 
 启动 `fst` 后输入 `/` 会展开操作列表，使用上下箭头选择、Tab 补全、Enter 确认，Escape 返回。普通输入与插件命令忙碌页使用 Ctrl+C 取消；运行观察面板内 Ctrl+C 只关闭面板。在主提示符处 Ctrl+C 请求退出，有未保存修改或后台运行时会先确认。
 
-首页展示 FISHtools 字符标识、欢迎介绍、当前工作区以及插件和工作流数量；小窗口自动使用紧凑标题。首次使用可以输入 `/run hello`，按提示输入文本（也可保留默认值），体验“转为大写 → 追加标记 → 保存文件”；执行后输入 `/logs` 阅读日志。首页只推荐当前工作区实际存在的工作流，空工作区提示用 `/new` 创建。
+首页展示 FISHtools 字符标识、欢迎介绍、当前工作区以及插件和工作流数量；小窗口自动使用紧凑标题。首次使用可以输入 `/run hello`，按提示输入文本（也可保留默认值），体验“转为大写 → 追加标记 → 保存文件”。运行过程与输入输出留在主面板，期间仍可打开配置或执行其他工作流。PgUp/PgDn 或鼠标滚轮浏览会话中的过程，向下翻至末尾恢复跟随。首页只推荐当前工作区实际存在的工作流；空工作区从 `/workflows` 新建。
 
-`/plugins` 直接列出当前已加载的插件名称、版本和状态。上下选择后可查看用途、编排能力、输入输出、环境声明及斜杠命令；有配置的插件提供配置入口，自行安装的插件提供移除入口。内置插件标明来源，避免误以为没有安装。`/help` 在终端内提供可翻页的用法说明。
+顶部的“位置”显示主面板或当前操作入口，菜单标题显示正在操作的对象。提交的命令、菜单选择与实际操作结果保留在本次会话中；返回时只更新当前位置，不追加通用返回消息，也不清空执行过程。这些导航记录只保留在当前会话。
+
+主面板查看当前执行，`/logs` 回看某次执行的步骤状态、输入输出和日志，也能重新打开正在运行的任务详情。查看记录不会重新执行工作流。旧 `/runs` 和 F4 仅作为兼容方式转到同一个 `/logs` 入口，不再提供独立列表。
+
+主面板默认按步骤显示“执行中／成功／失败”，每一步标明能力与插件；**Ctrl+O 展开/收起详情**，查看各步输入输出、作者日志和子进程 stdout/stderr。错误摘要与插件 `print()` 的用户提示直接展示，普通技术日志默认折叠。折叠只改变展示，不丢弃日志或结果。
+
+主输入框用 **↑ / ↓** 回看本次启动中已提交的命令，向下回到底部恢复未提交草稿。补全菜单打开时，方向键仍选择候选；配置表单内容不进入命令历史。最多保留最近 100 条，相邻重复命令合并，退出后不保存。
+
+`/plugin` 直接列出当前已加载的插件名称、版本和状态。上下选择后可查看用途、编排能力、输入输出、环境声明及斜杠命令；有配置的插件提供配置入口，自行安装的插件提供移除入口。内置插件标明来源，避免误以为没有安装。`/help` 在终端内提供可翻页的用法说明。顶层补全标明 `[内置]` 或 `[插件]`，插件能力收进插件名入口的二级菜单。
 
 | 操作 | 功能 |
 | --- | --- |
-| `/workflows`、`/new` | 选择已有工作流，或新建流程 |
-| `/add`、`/steps` | 添加能力、子工作流、条件分支、并行组或提前结束；编辑内部步骤、参数和执行条件 |
-| `/outputs`、`/save` | 选择汇总输出，保存为 Web 可继续编辑的同一份流程 |
-| `/run` | 逐字段填写运行参数并执行，打开步骤、输入输出和实时日志观察面板 |
-| `/runs` | 选择当前会话的运行，重新打开观察面板；关闭面板后任务继续 |
-| `/logs` | 用键盘或鼠标滚轮阅读持久化历史日志，设置整个项目保留最近 N 次日志 |
-| `/plugins` | 浏览已安装插件、用途及能力，进入配置、安装和移除操作 |
+| `/workflows` | 浏览、新建；进入某个流程后添加/编辑步骤、设置输出、保存、运行或删除 |
+| `/run 工作流ID` | 可按 ID 或中文标题补全，填写参数后执行已保存版本；只输入 `/run` 打开已保存工作流列表 |
+| `/logs` | 回看执行记录，运行中的任务优先；可切换总览、输入输出与日志，支持键盘或鼠标滚轮阅读 |
+| `/plugin` | 浏览已安装插件、用途及能力，进入插件配置、安装和移除操作 |
 | `/pack` | 勾选工作流并选择目标平台打包 |
-| `/config` | 编辑并保存插件声明的配置 |
-| `/docs` | 阅读随安装提供的开发规范、控制流说明与示例 |
-| `/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。
 
@@ -72,12 +81,14 @@ fst --project ./my-project pack hello --target linux-x64-glibc --web
 | `a` | 切换当前步骤与全部日志 |
 | ↑↓、鼠标滚轮、PageUp/PageDown、Home/End | 滚动、翻页、跳转开头或尾部；手动滚动暂停日志跟随，End 恢复跟随 |
 | `f` | 切换日志跟随 |
-| Esc、q、Enter、Ctrl+C | 关闭面板，任务继续运行；可用 `/runs` 返回 |
+| Enter | 在总览中查看所选步骤详情，不退出面板 |
+| `j` | 在易读字段与原始 JSON 诊断之间切换 |
+| Esc、q、Ctrl+C | 返回上一级，运行中的任务继续；输入 `/logs` 可重新打开 |
 | `x`，再按 `y` | 确认取消整个运行 |
 
-`/runs` 显示当前会话的运行，包含已完成任务；重启后的历史用 `/logs` 查看。历史阅读器支持方向键、滚轮、PageUp/PageDown、Home/End，Esc、Enter 或 q 返回。主提示符 `/exit` 或 Ctrl+C 遇到后台任务时，会说明退出将取消任务并请求确认，默认不退出。
+运行记录同时列出正在执行和保留的历史记录，运行中任务优先；同一个工作流的多次执行分别显示时间和记录编号。查看详情后返回列表，可以继续选择另一次执行。本次启动期间每次运行分别保存阅读位置；重启后可通过 `/logs` 查看保存的记录，主面板会话展示从新会话开始。日志保留设置在 `/config`。主提示符 `/exit` 或 Ctrl+C 遇到后台任务时，会说明退出将取消任务并请求确认，默认不退出。
 
-插件可以注册自己的命令：官方示例提供 `/text.upper`、交互式 `/text.ask`、`/env.check` 和 `/env.report`。`check` 在环境未通过时抛错，保持旧流程行为；`report` 正常返回 `ok:false` 和检查明细，适合交给工作流条件判断。安装或移除插件会同步刷新 `/` 菜单；命令和工作流共用日志、取消和结果机制。
+插件可以注册自己的命令：官方示例的 `/examples` 入口包含文本转大写与交互文本输入，`/environment` 入口包含环境检查与报告。原 `/text.upper`、`/text.ask`、`/env.check`、`/env.report` 仍可直接调用。`check` 在环境未通过时抛错；`report` 正常返回 `ok:false` 和检查明细，适合交给工作流条件判断。安装或移除插件会同步刷新 `/` 菜单；命令和工作流共用日志、取消和结果机制。
 
 在字符串参数中输入 `@` 可选择本地文件或目录，引用结果为绝对路径；`@@文字` 表示以 @ 开头的普通文字。`/run hello @"输入 参数.json"` 则明确读取文件中的 JSON 对象作为运行输入。文件路径相对启动时的目录（在 `/help` 中显示），不会自动上传文件，也不会把文件内容当作命令。路径补全无需额外安装 `fd`。
 
@@ -85,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

package/manual/README.md

@@ -6,7 +6,7 @@
 
 交互终端支持选择能力、配置参数和流程编排；官方 Web 插件默认提供，原子 CLI 子命令用于自动化。三种入口共用应用服务。YAML、依赖锁和版本解析由系统维护，不要求普通用户手写。
 
-0.2.0 增加条件分支、并行组、提前结束、实时运行观察，以及随安装提供的离线开发手册。本文对应此版本源码；发布与验证状态见 [版本记录](docs/releases.md) 和 [验收记录](docs/verification.md)。
+0.3.0 增加按对象组织的终端菜单、主面板执行摘要与插件用户输出、命令历史，并修复第三方插件进程调用和离线 Web 打包。此前 0.2.0 引入的条件控制、运行观察和离线开发手册仍可使用。发布与验证状态见 [版本记录](docs/releases.md) 和 [验收记录](docs/verification.md)。
 
 插件接入层使用 JavaScript/TypeScript，通过通用进程接口调用 Python 脚本和系统命令。首款官方插件负责 Python/pip、NPU 与系统环境检查，使用与第三方插件相同的公开接口，按工作流依赖选入分发包。插件声明 Python 等环境使用宿主机还是自带资源；环境检查与业务兼容性由插件作者负责。包内始终携带编排器所需的 Node，完整便携包也携带 npm。
 
@@ -19,7 +19,7 @@ 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) 为准；当前仓库为私有，下载附件需要仓库访问权限。
+也可从 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` 指定。安装包已包含官方插件、页面和生产依赖，不需要源码仓库或前端构建。
 
@@ -41,23 +41,32 @@ fst --project ./my-project pack hello --target linux-x64-glibc --web
 
 启动 `fst` 后输入 `/` 会展开操作列表，使用上下箭头选择、Tab 补全、Enter 确认，Escape 返回。普通输入与插件命令忙碌页使用 Ctrl+C 取消；运行观察面板内 Ctrl+C 只关闭面板。在主提示符处 Ctrl+C 请求退出，有未保存修改或后台运行时会先确认。
 
-首页展示 FISHtools 字符标识、欢迎介绍、当前工作区以及插件和工作流数量；小窗口自动使用紧凑标题。首次使用可以输入 `/run hello`，按提示输入文本（也可保留默认值），体验“转为大写 → 追加标记 → 保存文件”；执行后输入 `/logs` 阅读日志。首页只推荐当前工作区实际存在的工作流，空工作区提示用 `/new` 创建。
+首页展示 FISHtools 字符标识、欢迎介绍、当前工作区以及插件和工作流数量；小窗口自动使用紧凑标题。首次使用可以输入 `/run hello`，按提示输入文本（也可保留默认值），体验“转为大写 → 追加标记 → 保存文件”。运行过程与输入输出留在主面板，期间仍可打开配置或执行其他工作流。PgUp/PgDn 或鼠标滚轮浏览会话中的过程，向下翻至末尾恢复跟随。首页只推荐当前工作区实际存在的工作流；空工作区从 `/workflows` 新建。
 
-`/plugins` 直接列出当前已加载的插件名称、版本和状态。上下选择后可查看用途、编排能力、输入输出、环境声明及斜杠命令；有配置的插件提供配置入口，自行安装的插件提供移除入口。内置插件标明来源，避免误以为没有安装。`/help` 在终端内提供可翻页的用法说明。
+顶部的“位置”显示主面板或当前操作入口，菜单标题显示正在操作的对象。提交的命令、菜单选择与实际操作结果保留在本次会话中；返回时只更新当前位置，不追加通用返回消息，也不清空执行过程。这些导航记录只保留在当前会话。
+
+主面板查看当前执行，`/logs` 回看某次执行的步骤状态、输入输出和日志，也能重新打开正在运行的任务详情。查看记录不会重新执行工作流。旧 `/runs` 和 F4 仅作为兼容方式转到同一个 `/logs` 入口，不再提供独立列表。
+
+主面板默认按步骤显示“执行中／成功／失败”，每一步标明能力与插件；**Ctrl+O 展开/收起详情**，查看各步输入输出、作者日志和子进程 stdout/stderr。错误摘要与插件 `print()` 的用户提示直接展示，普通技术日志默认折叠。折叠只改变展示，不丢弃日志或结果。
+
+主输入框用 **↑ / ↓** 回看本次启动中已提交的命令，向下回到底部恢复未提交草稿。补全菜单打开时，方向键仍选择候选；配置表单内容不进入命令历史。最多保留最近 100 条，相邻重复命令合并，退出后不保存。
+
+`/plugin` 直接列出当前已加载的插件名称、版本和状态。上下选择后可查看用途、编排能力、输入输出、环境声明及斜杠命令；有配置的插件提供配置入口，自行安装的插件提供移除入口。内置插件标明来源，避免误以为没有安装。`/help` 在终端内提供可翻页的用法说明。顶层补全标明 `[内置]` 或 `[插件]`，插件能力收进插件名入口的二级菜单。
 
 | 操作 | 功能 |
 | --- | --- |
-| `/workflows`、`/new` | 选择已有工作流，或新建流程 |
-| `/add`、`/steps` | 添加能力、子工作流、条件分支、并行组或提前结束；编辑内部步骤、参数和执行条件 |
-| `/outputs`、`/save` | 选择汇总输出，保存为 Web 可继续编辑的同一份流程 |
-| `/run` | 逐字段填写运行参数并执行，打开步骤、输入输出和实时日志观察面板 |
-| `/runs` | 选择当前会话的运行，重新打开观察面板；关闭面板后任务继续 |
-| `/logs` | 用键盘或鼠标滚轮阅读持久化历史日志，设置整个项目保留最近 N 次日志 |
-| `/plugins` | 浏览已安装插件、用途及能力，进入配置、安装和移除操作 |
+| `/workflows` | 浏览、新建；进入某个流程后添加/编辑步骤、设置输出、保存、运行或删除 |
+| `/run 工作流ID` | 可按 ID 或中文标题补全，填写参数后执行已保存版本；只输入 `/run` 打开已保存工作流列表 |
+| `/logs` | 回看执行记录，运行中的任务优先；可切换总览、输入输出与日志，支持键盘或鼠标滚轮阅读 |
+| `/plugin` | 浏览已安装插件、用途及能力，进入插件配置、安装和移除操作 |
 | `/pack` | 勾选工作流并选择目标平台打包 |
-| `/config` | 编辑并保存插件声明的配置 |
-| `/docs` | 阅读随安装提供的开发规范、控制流说明与示例 |
-| `/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。
 
@@ -72,12 +81,14 @@ fst --project ./my-project pack hello --target linux-x64-glibc --web
 | `a` | 切换当前步骤与全部日志 |
 | ↑↓、鼠标滚轮、PageUp/PageDown、Home/End | 滚动、翻页、跳转开头或尾部；手动滚动暂停日志跟随，End 恢复跟随 |
 | `f` | 切换日志跟随 |
-| Esc、q、Enter、Ctrl+C | 关闭面板，任务继续运行；可用 `/runs` 返回 |
+| Enter | 在总览中查看所选步骤详情，不退出面板 |
+| `j` | 在易读字段与原始 JSON 诊断之间切换 |
+| Esc、q、Ctrl+C | 返回上一级，运行中的任务继续；输入 `/logs` 可重新打开 |
 | `x`，再按 `y` | 确认取消整个运行 |
 
-`/runs` 显示当前会话的运行，包含已完成任务；重启后的历史用 `/logs` 查看。历史阅读器支持方向键、滚轮、PageUp/PageDown、Home/End，Esc、Enter 或 q 返回。主提示符 `/exit` 或 Ctrl+C 遇到后台任务时，会说明退出将取消任务并请求确认，默认不退出。
+运行记录同时列出正在执行和保留的历史记录，运行中任务优先；同一个工作流的多次执行分别显示时间和记录编号。查看详情后返回列表，可以继续选择另一次执行。本次启动期间每次运行分别保存阅读位置；重启后可通过 `/logs` 查看保存的记录，主面板会话展示从新会话开始。日志保留设置在 `/config`。主提示符 `/exit` 或 Ctrl+C 遇到后台任务时，会说明退出将取消任务并请求确认，默认不退出。
 
-插件可以注册自己的命令：官方示例提供 `/text.upper`、交互式 `/text.ask`、`/env.check` 和 `/env.report`。`check` 在环境未通过时抛错，保持旧流程行为；`report` 正常返回 `ok:false` 和检查明细，适合交给工作流条件判断。安装或移除插件会同步刷新 `/` 菜单；命令和工作流共用日志、取消和结果机制。
+插件可以注册自己的命令：官方示例的 `/examples` 入口包含文本转大写与交互文本输入，`/environment` 入口包含环境检查与报告。原 `/text.upper`、`/text.ask`、`/env.check`、`/env.report` 仍可直接调用。`check` 在环境未通过时抛错；`report` 正常返回 `ok:false` 和检查明细，适合交给工作流条件判断。安装或移除插件会同步刷新 `/` 菜单；命令和工作流共用日志、取消和结果机制。
 
 在字符串参数中输入 `@` 可选择本地文件或目录，引用结果为绝对路径；`@@文字` 表示以 @ 开头的普通文字。`/run hello @"输入 参数.json"` 则明确读取文件中的 JSON 对象作为运行输入。文件路径相对启动时的目录（在 `/help` 中显示），不会自动上传文件，也不会把文件内容当作命令。路径补全无需额外安装 `fd`。
 
@@ -85,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

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.

package/manual/docs/examples/pipeline-writer/index.js

@@ -0,0 +1,17 @@
+import {writeFile} from 'node:fs/promises';
+import {setTimeout} from 'node:timers/promises';
+import path from 'node:path';
+
+export default {
+  id:'fishtools-example-writer',version:'0.1.0',title:'报告保存示例',platforms:['win32','linux'],
+  actions:{save:{
+    title:'保存报告',description:'把上个插件的结果写入文件，通过 print 告诉用户保存位置。',
+    input:{type:'object',required:['text'],properties:{text:{type:'string',title:'报告文本'},delayMs:{type:'integer',minimum:0,maximum:10000,default:1000,title:'演示等待毫秒数'}}},
+    output:{type:'object',required:['file','text'],properties:{file:{type:'string'},text:{type:'string'}}},
+    async run({text,delayMs=1000},{log,print,outputDir,signal}){
+      const file=path.join(outputDir,'report.txt');await log('写入报告',{file,characters:text.length});
+      await setTimeout(delayMs,undefined,{signal});await writeFile(file,text,'utf8');
+      await print('报告已保存',{file});return {file,text};
+    },
+  }},
+};

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

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

package/manual/docs/plugin-development.md

@@ -2,6 +2,8 @@
 
 本文是 Fishtools 的公共插件接入规范，面向第三方开发者。普通动作插件与官方环境检查插件使用同一套契约；不要求依赖 Web 前端，也不要求开发者直接操作 Cordis。
 
+`print()` 用户输出接口、主面板默认折叠和 Ctrl+O 展开从 0.3.0 起纳入发行包；0.2.0 不包含这些能力。
+
 ## 从已安装的工具查阅规范
 
 完整 npm 与便携发行包随附离线资料，包含本文、控制流规范、服务示例和可安装的[零依赖动作插件](examples/action-plugin/README.md)。无需克隆源码仓库：
@@ -49,6 +51,8 @@ fst docs --export ./fishtools-manual
 
 JSON 序列化可能丢弃对象中的 `undefined`、函数或 Symbol，并将非有限数字转为 `null`；不能把“能够序列化”当作完整的类型保证。请给输出写明确的 schema，不返回循环引用、BigInt、函数或依赖隐式转换的对象。
 
+每份 schema 独立编译并缓存，`$id` 不会在不同插件或安装批次之间共享注册。插件升级可以保留相同 `$id` 并调整约束；定义内部的 `$ref` 正常解析，不支持隐式引用另一个插件曾注册的 schema。
+
 无参数或无输出时，分别使用 `{type:'object', properties:{}, additionalProperties:false}`，动作返回 `{}`。JSON Schema 的布尔形式也受支持：`true` 接受任意值，`false` 拒绝所有值；为了生成字段表单与输出选择器，推荐明确声明对象和字段。缺省、`null`、数组、字符串和数值都不能代替 schema 声明。原有动作/子工作流的 `schemaVersion: 1` 格式保留；旧插件若要参与编排，需要补齐有效的 input/output 声明。正常返回且输出校验通过即执行成功，不要求返回额外的 `success:true`。
 
 ## 插件定义字段
@@ -140,11 +144,20 @@ fst plugin remove my-flow-plugin
 | `environments` | 按声明和来源选择解析的环境；包含解释器路径，随包环境另有资源根目录 |
 | `runProcess(file,args,options)` | 通用进程调用，自动关联当前日志与取消信号 |
 | `log(message,data,meta?)` | 写结构化日志并返回落盘 Promise；常规调用保持 `log(message,data)` |
+| `print(message,data?)` | 面向用户输出，默认主面板直接显示；同样返回落盘 Promise |
 
 返回值必须可 JSON 序列化，输入输出经 Ajv 校验。插件在宿主进程中执行，属于可信代码；同步阻塞代码不能被取消信号抢占。
 
+主面板默认展示步骤状态，Ctrl+O 展开或收起各步输入输出和技术日志。普通 `log` 与子进程 stdout/stderr 默认折叠；失败摘要始终直接显示。希望用户直接看到的进度或结果，显式使用 `await print('报告已保存', {file})`。`print` 沿用日志通道，以 `type: 'log', audience: 'user'` 持久化，工作流中自动带上步骤归属。动作和交互命令都支持，不应直接用 `console.log` 向 TUI 打印。
+
+若 Python 程序的部分输出需要直接展示，可使用 `runProcess(file, args, {onOutput: ({stream,message}) => stream === 'stdout' ? print(message) : undefined})`。回调按数据块触发；作者可先缓存成完整行再选择性 print。完整进程输出仍自动保存在诊断日志，print 的用户提示另外保留。写入 stderr 本身不等同执行失败，动作仍须按退出码决定抛错。
+
+跨插件示例源码：[文本准备插件](examples/pipeline-reader/index.js)、[报告保存插件](examples/pipeline-writer/index.js)。它们与基础示例的转大写动作组成 `preview-pipeline`，通过前一步输出绑定下一步输入；每个目录都是独立插件包，可参考现有安装方法接入。
+
 `runProcess` 默认无 Shell，参数用数组。支持 `cwd`、`env`、`signal`、`timeout`（默认 30 秒）、`maxBuffer`（stdout/stderr 各默认 4 MiB）和可选的 `onOutput({stream,message})`。普通非零退出返回 `{exitCode,stdout,stderr}`，动作应自行决定是否抛出业务错误；缺失程序、超时、取消、输出超限抛错，并等待进程树回收。不要把密码或令牌写入日志。
 
+相对程序路径及 `PATH` 中的相对目录以传入的 `cwd` 为基准；未传 `cwd` 时使用宿主当前目录。例如 `runProcess('./tools/check', [], {cwd: resourceDir})` 调用插件资源目录内的工具，不改变其他并发动作的工作目录。
+
 通过动作上下文调用时，stdout/stderr 在子进程执行期间自动产生 `type:'log'` 事件，`stream` 为 `stdout` 或 `stderr`，工作流事件保留 `stepId` 和 `callPath`。例如同一动作分别位于 `main/group/left`、`main/group/right`，日志按各自调用归属显示。写入 stderr 本身不会把运行改成失败。
 
 输出按 UTF-8 解码，跨数据块的中文和 emoji 不会被拆坏；回调消息是流数据块，不保证一条消息就是一整行。可选 `onOutput` 在自动日志落盘后执行，不需要再手动 `log` 同一份输出。回调可以返回 Promise，`runProcess` 会等待；回调抛错或拒绝会终止受管进程并向调用方报告错误。完整 stdout/stderr 返回缓冲仍受输出上限约束。不要启动未等待的回调后台任务。
@@ -155,8 +168,8 @@ fst plugin remove my-flow-plugin
 
 每次通过应用运行工作流或插件命令，都在 `.flow/runs/<runId>/` 写入 `run.md`、`events.jsonl` 与 `result.json`（指定 `--output` 时使用该目录；便携版写入可写工作区）。
 
-- **运行中直接观察**：TUI 运行工作流后打开观察面板，或通过 `/runs` 选择当前会话的运行；Web 使用“查看运行”。两者提供步骤总览、输入输出和实时日志，按调用路径查看同一动作的不同调用。
-- **历史日志直接阅读**：TUI `/logs` 选择记录后在终端内阅读 Markdown；方向键或鼠标滚轮滚动，PageUp/PageDown 翻页，Home/End 跳转，Esc、Enter 或 q 返回。重启后读取磁盘历史；旧版本只有 result.json 时从事件快照生成内容。
+- **运行中直接观察**：TUI 主面板逐步更新状态，Ctrl+O 展开输入输出和诊断日志；`/logs` 可选择某次运行进入详细面板。Web 使用“查看运行”。按调用路径区分同一动作的不同调用。
+- **历史日志直接阅读**：TUI `/logs` 选择记录后切换总览、输入输出和日志；方向键或鼠标滚轮滚动，PageUp/PageDown 翻页，Home/End 跳转，Esc 或 q 返回，Enter 查看步骤。重启后读取磁盘历史；run.md 也可用外部 Markdown 阅读器打开。
 - **导出阅读内容**：`run.md` 按时间顺序展示步骤、作者日志、stdout/stderr、执行结果、失败原因、错误详情和调用栈，结束后附最终状态。它在执行过程中逐条追加，也可使用外部 Markdown 阅读器查看。调用栈保留原始换行。
 
 - `events.jsonl` 按顺序记录启动、步骤成功/失败/跳过/停止、作者日志、进程流输出和运行结束。`step.started` 含解析后的 input；失败事件包含插件 ID、动作或命令、错误码、message，以及 `error` 中的 stack 和 cause 链。工作流还有 stepId、callPath、耗时。
@@ -259,7 +272,7 @@ outputs:
 
 TUI `/add` 选择动作、子工作流、条件分支、并行组或提前结束；`/steps` 可进入分支/并行组编辑内部步骤，设置执行条件、并发数和结束原因。条件表单支持选择字段或预设，也支持且、或、取反。`/save` 保存后，Web 可继续编辑同一份工作流。
 
-TUI `/run` 启动工作流后打开观察面板，`/runs` 可重新选择当前会话的运行（包括已完成运行）。跨重启历史通过 `/logs` 阅读。
+TUI `/run 工作流ID` 支持 ID 和中文标题补全，执行过程、步骤输入输出与最终结果留在主面板。运行期间可继续输入命令或配置工具；多次执行分别记录，PgUp/PgDn 或鼠标滚轮回看。F4 或 `/runs` 打开详细观察面板，`/logs` 直接查看某次运行的日志；包括跨重启保留下来的记录。
 
 | 面板键位 | 行为 |
 | --- | --- |
@@ -268,10 +281,12 @@ TUI `/run` 启动工作流后打开观察面板，`/runs` 可重新选择当前
 | `a` | 切换本步骤日志与全部日志 |
 | ↑↓、鼠标滚轮、PageUp/PageDown、Home | 滚动或跳到开头；手动滚动暂停日志跟随 |
 | End / `f` | End 跳至尾部并恢复跟随；f 切换跟随状态 |
-| Esc、q、Enter、Ctrl+C | 关闭观察面板，任务继续运行 |
+| Enter | 在总览查看所选步骤详情 |
+| `j` | 切换可读字段与原始 JSON / 完整诊断 |
+| Esc、q、Ctrl+C | 返回上一级，运行中任务继续 |
 | `x`，再按 `y` | 确认取消整个运行；确认提示中其他键返回 |
 
-关闭观察面板不等于退出应用。主提示符 `/exit` 或 Ctrl+C 遇到后台运行时，会提示退出将取消这些任务，默认不退出。普通参数输入和插件命令忙碌页仍使用原有 Ctrl+C 取消行为。鼠标模式只在阅读面板中启用，关闭后恢复。
+关闭观察面板不等于退出应用。主提示符 `/exit` 或 Ctrl+C 遇到后台运行时，会提示退出将取消这些任务，默认不退出。普通参数输入和插件命令忙碌页仍使用原有 Ctrl+C 取消行为。鼠标滚轮用于主面板和详细阅读面板；参数输入或菜单按各自的键盘提示操作，退出应用时恢复终端鼠标模式。
 
 Web 通过“添加步骤 → 流程控制”添加分支、并行组或提前结束，点击节点填写条件、并发数、原因及内部步骤；普通步骤也可设置执行条件。保存后点击“运行工作流”，运行面板提供“步骤总览 / 输入输出 / 实时日志”和调用路径筛选。向上滚动日志会暂停跟随，可以点击“恢复自动跟随”继续查看尾部。关闭观察窗口后任务继续，顶部“查看运行”可重新打开；“停止运行”发送取消请求。只读运行包允许运行和观察，不允许修改流程。
 
@@ -302,7 +317,7 @@ async function run({executable, text}, {resourceDir, runProcess, signal}) {
 {"my-flow-plugin":{"endpoint":"http://127.0.0.1:9000"}}
 ```
 
-私有配置不默认入包，`defaultConfig` 只放公开默认值。TUI `/config` 根据配置 schema 编辑并保存工作区配置；CLI `fst configure 插件ID 配置.json` 提供相同能力。调用时 `--config` 优先于工作区配置，不自动回写或导出。
+私有配置不默认入包，`defaultConfig` 只放公开默认值。TUI `/plugin` → 选择插件 → 设置插件配置，根据 schema 编辑并保存；`/config` 专用于 Fishtools 自身设置。CLI `fst configure 插件ID 配置.json` 继续配置插件。调用时 `--config` 优先于工作区配置，不自动回写或导出。
 
 ## 平台声明与责任边界
 
@@ -312,6 +327,10 @@ async function run({executable, text}, {resourceDir, runProcess, signal}) {
 
 `commands` 的键不含 `/`，推荐使用 `插件短名.操作名`；不得与核心入口或其他插件命令重名。安装/移除后 TUI `/` 菜单立即更新，失败的安装不会替换旧宿主。
 
+TUI 顶层按插件归组：例如 ID `@mytools/examples` 对应 `/examples`，进入后选择具体能力，列表标明 `[插件]`、插件名称及 ID。入口取插件 ID 的末段；同名插件使用完整 ID 转为连字符名称，遇到保留名或已有命令则加 `plugin-` 前缀。以当前补全列表中的实际入口为准，不要在插件间依赖这个 UI 别名。只有注册了 `commands` 的插件才产生能力入口，纯服务/纯动作插件仍可在 `/plugin` 管理或参与工作流。原始命令名和 CLI `fst command` 协议不变，旧插件无需迁移定义。新保留入口包括 `plugin`、`tools`，作者应继续使用带插件前缀的命令名。
+
+TUI 负责展示当前工作区、操作入口、菜单标题以及提交命令和操作结果。返回时只更新当前位置，不追加通用返回消息。插件使用 `ui.input/select/show/confirm`，不要自行清屏或打印终端控制序列，以免破坏主面板中的运行过程。导航记录仅保留在本次会话，持久诊断请使用动作上下文的日志接口。`/run` 执行已保存的工作流；工作流草稿只在编辑菜单明确选择“保存并运行”后才写入，不由插件命令隐式保存。
+
 ```js
 commands: {
   'demo.greet': { description: '生成问候', action: 'greet' },
@@ -441,6 +460,7 @@ Fishtools 等待 `ctx.on('dispose', async () => ...)` 的清理完成并报告
 - TUI `/plugins` 可进入维护模式并恢复服务；CLI 使用 `fst --maintenance plugin add ...`、`fst --maintenance configure ...`。维护模式不持久化，默认重启恢复服务。
 - 维护模式停止 runtime 插件的动作和命令，普通插件仍可使用；声明校验仍执行，不能借维护模式加载无效插件定义。
 - 现有 `services.web` 仍为兼容的启动工厂；应用持有其返回的 close 句柄。`app.close()` 先关闭这些句柄，再关闭业务宿主，重复关闭安全。
+- 打包选择包含 Web 时，按 `services.web` 声明选取实际提供者，连同其传递插件依赖一起导出，不要求官方包名。完整便携包关闭 Web 选项时，仅省略非必需的 Web 提供者；工作流或其他插件确实依赖它时仍保留。
 - 活动 Web 提供者不能移除、替换或修改配置；TUI 插件管理可先停止 Web。普通插件更新不会关闭标准发行版中的 Web 管理入口。外部安装的 Web 提供者若被 npm 重新生成到新目录，也需先停止。
 - 没有实现运行中无缝热替换。服务撤销后消费者动作/命令被撤销；恢复后按 Cordis 生命周期重新激活。
 

package/manual/docs/releases.md

@@ -2,6 +2,15 @@
 
 产品名称 Fishtools，公共 npm 包名 `@yanglaofish/fishtools`，启动命令 `fst`。`0.x` 定位为早期可用版本。内部 `@mytools/*` 包随主包捆绑，不单独发布；内部插件 API 版本独立维护。
 
+## 0.3.0 终端交互与插件输出
+
+- 终端顶层按工作流、插件、工具和配置组织；命令历史保留未提交草稿，工作流编辑与执行互不覆盖。
+- 主面板按步骤展示跨插件执行摘要；`Ctrl+O` 展开输入输出和诊断。插件可用 `print()` 发送用户可见内容，展开详情包含完整错误链。
+- `/logs` 统一回看实时和历史运行；修复第三方插件进程调用、Web 依赖打包和 JSON Schema 升级。
+- 离线手册补齐新增研究文档引用的源码，长日志刷新合并处理。
+
+本版本沿用 0.2.0 的工作流格式与插件 API 版本；第三方插件可按需使用新增 `print()`。发布验收结果记录在下方及[验收记录](verification.md)。
+
 ## 0.2.0 控制流与运行观察
 
 - 增加执行条件、条件分支、并行组、提前结束；TUI/Web 均可通过表单编辑嵌套步骤与参数引用。
@@ -16,6 +25,10 @@
 
 ## 发布入口
 
+**发布前先完成本地试用并取得用户确认。** 自动化测试通过只代表具备试用条件，不代替用户对交互体验的验收。交付本地启动入口、说明改动及测试结果后，等待用户明确确认本轮可以发布，才创建版本 tag、发布 npm 或 GitHub Release。普通修复提交不触发发包。
+
+`npm run preview` / 根目录 `fst-preview.cmd` 继续提供独立源码预览工作区；其运行不会修改全局安装或默认工作区。0.3.0 的对象菜单、主面板运行及公共插件修复已列入本次发布范围。
+
 普通 push / PR 只验证代码。推送 `v版本号` tag 触发 `.github/workflows/release.yml`：
 
 1. 检查 tag、根 package.json 和 CLI 版本一致。
@@ -51,7 +64,8 @@ git push origin v0.1.4
 - Secret `NPM` 仅传入最后的发布步骤。需要有创建/发布 `@yanglaofish/fishtools` 的权限，以及 npm 自动发布要求的 Bypass 2FA 配置。缺失或权限不足时保留失败状态，修正 Secret 后重跑失败任务。
 - npm 与 GitHub 不能进行同一个原子事务。若 npm 已成功、GitHub 暂时失败，使用 Actions 的 **Re-run failed jobs**；同版本归档 SHA-512 一致才跳过 npm 并继续 GitHub 发布。不同内容必须增加版本，不能覆盖。
 - npm 首次发布可能先返回成功并提示正在处理，而注册表暂时仍返回 404。发布后会等待最多约 5 分钟再核对 SHA-512；若仍未可见，等待 `npm view @yanglaofish/fishtools@版本号` 能查询到后，再重跑失败任务，避免在处理阶段重复提交。
-- GitHub Release 先创建草稿，附件齐备后公开；重试可补齐草稿。已公开 Release 不自动覆盖附件。
+- GitHub Release 先创建草稿，附件齐备且 npm 可见后公开；重试可补齐草稿。已公开 Release 不自动覆盖附件。
+- 若 npm 处理持续较久，可手动运行 `查询 npm 版本状态`（`npm-status.yml`）并填写版本。此工作流使用现有 Secret 只读查询官方生命周期接口，只记录状态字段，不输出凭据、不上传包。`validating` 表示仍在校验，需等注册表可见后再重跑发布。
 - 也可使用 `gh workflow run release.yml --ref v0.1.3` 针对现有 tag 重新触发。由于完整重建可能产生不同归档，优先重跑失败任务，以复用原始已验证产物。
 - 仓库当前为 private，Release 也沿用仓库访问权限；npm 包公开发布。未启用要求公开源码仓库的 npm provenance，不改变仓库可见性。
 
@@ -74,3 +88,7 @@ git push origin v0.1.4
 `v0.1.3` 的 Windows/Linux 全量测试、自包含包执行和 Docker 验收全部通过。npm 于 2026-10-10 23:18（北京时间）接受 `@yanglaofish/fishtools@0.1.3`，首次发布后的处理延迟曾导致注册表返回 404。待注册表可见后重跑原发布任务，核对相同归档并跳过重复上传，于 23:24 完成 [GitHub Release](https://github.com/yanglaofish/Fishtools/releases/tag/v0.1.3)，包含 npm、Windows、Linux 三个归档及 SHA256SUMS。[发布流程](https://github.com/yanglaofish/Fishtools/actions/runs/38062508265) 全部成功；后续发布脚本已增加有上限的注册表可见性等待。
 
 首次发布时第三方 npm 镜像可能尚未同步归档。若遇到镜像 404，可指定官方源安装：`npm install -g @yanglaofish/fishtools --registry=https://registry.npmjs.org`。
+
+## 0.2.0 发布结果
+
+2026-10-11：双平台各 143 项测试、自包含归档与断网 Docker 验收通过。npm 接受上传后，生命周期状态为 `validating`，超过首次五分钟等待上限；注册表可见后核对相同 SHA-512，重跑原任务的失败步骤完成同步。当前官方注册表 `latest` 为 0.2.0，[发布流程](https://github.com/yanglaofish/Fishtools/actions/runs/38076094907)成功，[Release](https://github.com/yanglaofish/Fishtools/releases/tag/v0.2.0) 已包含全部三个归档和校验文件。