@yanglaofish/fishtools 0.5.1 → 0.5.3

package/README.md

@@ -6,20 +6,20 @@
 
 交互终端支持选择能力、配置参数和流程编排；官方 Web 插件默认提供，原子 CLI 子命令用于自动化。三种入口共用应用服务。YAML、依赖锁和版本解析由系统维护，不要求普通用户手写。
 
-0.5.0 增加工作流复制、按工作区/插件/动作设置代理、插件权限预检，以及只重启受影响插件的更新。大量输出落盘、开发重载和隔离文件探测继续可用。发布与验证状态见 [版本记录](manual/docs/releases.md) 和 [验收记录](manual/docs/verification.md)。
+0.5.3 修正 Node 安装兼容性与 TUI 状态提示：未修改时不产生草稿、配置备份或插件重启；删除工作流时明确选择备份后删除、直接删除或取消。`!` 系统命令透传、常用命令注册、中文快捷名称和 Shift+Enter 多行输入继续可用。发布与验证状态见 [版本记录](manual/docs/releases.md) 和 [验收记录](manual/docs/verification.md)。
 
 插件接入层使用 JavaScript/TypeScript，通过通用进程接口调用 Python 脚本和系统命令。首款官方插件负责 Python/pip、NPU 与系统环境检查，使用与第三方插件相同的公开接口，按工作流依赖选入分发包。插件声明 Python 等环境使用宿主机还是自带资源；环境检查与业务兼容性由插件作者负责。包内始终携带编排器所需的 Node，完整便携包也携带 npm。
 
 ## npm 安装与启动（Windows / Linux）
 
-安装端需要 Node.js 24.15.0 或更高版本以及 npm。已发布版本可从 npm 安装：
+安装端需要 Node.js **22.22.2+（22 系列）或 24.0.0+**，以及 npm。已发布版本可从 npm 安装：
 
 ```sh
 npm install -g @yanglaofish/fishtools
 fst
 ```
 
-也可从 GitHub Release 下载当前版本的 `.tgz` 后执行 `npm install -g ./yanglaofish-fishtools-0.5.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.5.3.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,15 +41,25 @@ fst --project ./my-project pack hello --target linux-x64-glibc --web
 
 启动 `fst` 后输入 `/` 会展开操作列表，使用上下箭头选择、Tab 补全、Enter 确认，Escape 返回。普通输入与插件命令忙碌页使用 Ctrl+C 取消；运行观察面板内 Ctrl+C 只关闭面板。在主提示符处 Ctrl+C 请求退出，有未保存修改或后台运行时会先确认。
 
+主输入框和命令编辑框使用 **Shift+Enter 换行、Enter 提交**，多行粘贴保留真实换行；终端无法区分 Shift+Enter 时使用 **Alt+Enter**。输入 `!echo hello` 可执行系统命令。`/commands` 注册常用命令，`/shortcuts` 给任意插件动作或命令设置中文快捷名，例如 `/查看本机IP`；注册动作也能加入工作流。详细用法见[命令与快捷名称](manual/docs/terminal-commands.md)，离线可用 `fst docs commands` 阅读。
+
 首页展示 FISHtools 字符标识、欢迎介绍、当前工作区以及插件和工作流数量；小窗口自动使用紧凑标题。首次使用可以输入 `/run hello`，按提示输入文本（也可保留默认值），体验“转为大写 → 追加标记 → 保存文件”。运行过程与输入输出留在主面板，期间仍可打开配置或执行其他工作流。PgUp/PgDn 或鼠标滚轮浏览会话中的过程，向下翻至末尾恢复跟随。首页只推荐当前工作区实际存在的工作流；空工作区从 `/workflows` 新建。
 
-顶部的“位置”显示主面板或当前操作入口，菜单标题显示正在操作的对象。提交的命令、菜单选择与实际操作结果保留在本次会话中；返回时只更新当前位置，不追加通用返回消息，也不清空执行过程。这些导航记录只保留在当前会话。
+顶部的“位置”显示主面板或当前操作入口，菜单标题显示正在操作的对象。提交的命令、反馈与运行结果自动保存在所属工作区；返回菜单不会清空执行过程。`/history` 可恢复旧会话并继续输入，也可分页查看完整交互记录；恢复不会重新执行旧命令或覆盖旧会话。若已有插件或快捷名使用 `history`，从 `/tools` → 历史会话进入。
 
 主面板查看当前执行，`/logs` 回看某次执行的步骤状态、输入输出和日志，也能重新打开正在运行的任务详情。查看记录不会重新执行工作流。旧 `/runs` 和 F4 仅作为兼容方式转到同一个 `/logs` 入口，不再提供独立列表。
 
-主面板默认按步骤显示“执行中／成功／失败”，每一步标明能力与插件；**Ctrl+O 展开/收起详情**，查看各步输入输出、作者日志和子进程 stdout/stderr。错误摘要与插件 `print()` 的用户提示直接展示，普通技术日志默认折叠。折叠只改变展示，不丢弃日志或结果。
+`/logs` 标明每次执行属于工作流、插件动作、插件命令或系统命令，以及本次或历史启动。可以按本次启动或调用类型筛选，先显示最近 20 条，再按需显示更多。一个工作流的子流程和内部步骤放在同一条记录中。
+
+插件生成的业务文件放在工作区可见的 `results/运行ID/`，日志放在 `.flow/runs/运行ID/`；两者隔离，业务文件即使叫 `result.json` 也不会被内核运行记录覆盖。指定 `--output 目录` 时，该目录仍保存日志，业务文件在其 `files/运行ID/`。TUI 显示实际生成文件的目录，日志保留设置不会删除业务结果，历史文件仍在原位置。
+
+普通 CLI/TUI 的 `plugin add` 与 `plugin link` 默认登记到用户级 `~/.fishtools/plugins`（设置 `FISHTOOLS_HOME` 时为其 `plugins` 子目录），安装一次，各工作区可用。各工作区单独保存工作流、插件参数和代理规则；未填写必填配置的插件显示“待配置”，其他插件仍可使用。旧工作区安装兼容读取，同名全局版本优先。全局卸载检查已登记工作区的工作流引用；其他已运行进程保留自己的代码，重启后读取新状态。离线分发包继续使用包内快照及自身可写工作区。
 
-主输入框用 **↑ / ↓** 回看本次启动中已提交的命令，向下回到底部恢复未提交草稿。补全菜单打开时，方向键仍选择候选；配置表单内容不进入命令历史。最多保留最近 100 条，相邻重复命令合并，退出后不保存。
+主面板默认按步骤显示“执行中／成功／失败”，每一步标明能力与插件，并在旁边提示 **Ctrl+O 查看详情**。展开后按插件字段标题显示输入输出；通过 `runProcess` 执行的程序会记录真实路径、逐项参数与执行目录，Shell 同时记录原始命令，插件文件目录按实际来源显示。内核无法观察插件绕过受管接口执行的任意代码或文件访问。错误摘要、系统命令输出与插件 `print()` 的用户提示直接展示，普通技术日志默认折叠。主面板和运行总览显示总耗时，运行中实时更新，结束后固定。平台声明不匹配也会直接在 TUI 中提示。
+
+主输入框用 **↑ / ↓** 回看已提交的命令，向下回到底部恢复未提交草稿。补全菜单打开时，方向键仍选择候选；配置表单内容不进入命令历史。恢复会话同时恢复最近 100 条、合计不超过 256 KiB 的输入，相邻重复命令合并；更长和更早的输入仍在完整交互记录中。未提交草稿不保存。
+
+会话保存在 `.flow/sessions/`；只读包使用可写日志目录的 `sessions/` 子目录。追加日志保存命令和反馈，快照保存有界近期面板，较大运行结果通过 `/logs` 读取原始记录；运行日志仍遵循用户设置的保留策略。会话使用本地 UTF-8 文件，首版不加密、不压缩，也不自动删除旧会话。
 
 `/plugin` 直接列出当前已加载的插件名称、版本和状态。上下选择后可查看用途、编排能力、输入输出、环境声明及斜杠命令；有配置的插件提供配置入口，自行安装的插件提供移除入口。内置插件标明来源，避免误以为没有安装。`/help` 在终端内提供可翻页的用法说明。顶层补全标明 `[内置]` 或 `[插件]`，插件能力收进插件名入口的二级菜单。
 
@@ -58,13 +68,16 @@ fst --project ./my-project pack hello --target linux-x64-glibc --web
 | `/workflows` | 浏览、新建；进入某个流程后添加/编辑步骤、设置输出、保存、运行或删除 |
 | `/run 工作流ID` | 可按 ID 或中文标题补全，填写参数后执行已保存版本；只输入 `/run` 打开已保存工作流列表 |
 | `/logs` | 回看执行记录，运行中的任务优先；可切换总览、输入输出与日志，支持键盘或鼠标滚轮阅读 |
+| `/history` | 恢复旧 TUI 会话的输入、反馈和结果，或分页查看完整交互 |
 | `/plugin` | 浏览已安装插件、用途及能力，进入插件配置、安装和移除操作 |
 | `/pack` | 勾选工作流并选择目标平台打包 |
 | `/config` | 配置 Fishtools：查看工作区信息，设置日志保留次数和代理规则 |
-| `/tools` | 启动 Web 或阅读离线资料 |
+| `/tools` | 历史会话、启动 Web 或阅读离线资料 |
 | `/help`、`/exit` | 查看帮助、退出 |
 
-旧 `/new`、`/add`、`/steps`、`/outputs`、`/save`、`/plugins`、`/docs`、`/web` 和 `/runs` 仍可直接输入，顶层补全主要呈现上表的对象入口。工作流编辑菜单返回时保留当前草稿，切换流程或退出会确认未保存修改。删除会将已保存文件移入 `.flow/deleted-workflows/工作流ID-编号.yaml`，仍被其他流程引用时拒绝删除；恢复时将备份复制回 `workflows/原工作流ID.yaml`，先确认同名文件不存在，避免覆盖。
+旧 `/new`、`/add`、`/steps`、`/outputs`、`/save`、`/plugins`、`/docs`、`/web` 和 `/runs` 仍可直接输入，顶层补全主要呈现上表的对象入口。有实际未保存修改时，工作流编辑菜单返回会保留草稿，切换流程或退出会确认是否放弃。查看后原样完成、修改后还原为已保存值不会产生草稿提示。
+
+删除时提供“备份后删除、直接删除、取消”，默认选择取消。备份后删除将已保存文件移入 `.flow/deleted-workflows/工作流ID-编号.yaml`；恢复时将备份复制回 `workflows/原工作流ID.yaml`，先确认同名文件不存在。直接删除不创建本次删除的备份；仍被其他流程引用时，两种删除方式都拒绝执行。
 
 `/run` 不要求保存当前编辑草稿，也不会丢弃它。要运行尚未保存的修改，请在 `/workflows` 的编辑菜单选择“运行工作流”，再选择“保存并运行”；已有磁盘版本时也可选择“运行已保存版本”并保留草稿。“返回编辑”会留在当前工作流，不会反复弹出保存确认。只查看参数或拒绝删除步骤不会产生未保存修改。
 
@@ -105,10 +118,11 @@ outputs:
 | `f` | 切换日志跟随 |
 | Enter | 在总览中查看所选步骤详情，不退出面板 |
 | `j` | 在易读字段与原始 JSON 诊断之间切换 |
+| `m` | 单独格式化阅读输出；插件标注的 Markdown 结果按 Markdown 呈现 |
 | Esc、q、Ctrl+C | 返回上一级，运行中的任务继续；输入 `/logs` 可重新打开 |
-| `x`，再按 `y` | 确认取消整个运行 |
+| `x`，再按 `y` | 任务仍在运行时，确认取消整个运行 |
 
-运行记录同时列出正在执行和保留的历史记录，运行中任务优先；同一个工作流的多次执行分别显示时间和记录编号。查看详情后返回列表，可以继续选择另一次执行。本次启动期间每次运行分别保存阅读位置；重启后可通过 `/logs` 查看保存的记录，主面板会话展示从新会话开始。日志保留设置在 `/config`。主提示符 `/exit` 或 Ctrl+C 遇到后台任务时，会说明退出将取消任务并请求确认，默认不退出。
+运行记录同时列出正在执行和保留的历史记录，运行中任务优先；同一个工作流的多次执行分别显示时间和记录编号。查看详情后返回列表，可以继续选择另一次执行。本次启动期间每次运行分别保存阅读位置；重启后可通过 `/logs` 查看保存的运行，`/history` 恢复旧主面板。上次退出时仍在运行且缺少最终记录的任务会明确显示“未记录最终状态”。日志保留设置在 `/config`。主提示符 `/exit` 或 Ctrl+C 遇到后台任务时，会说明退出将取消任务并请求确认，默认不退出。
 
 插件可以注册自己的命令：官方示例的 `/examples` 入口包含文本转大写与交互文本输入，`/environment` 入口包含环境检查与报告。原 `/text.upper`、`/text.ask`、`/env.check`、`/env.report` 仍可直接调用。`check` 在环境未通过时抛错；`report` 正常返回 `ok:false` 和检查明细，适合交给工作流条件判断。安装或移除插件会同步刷新 `/` 菜单；命令和工作流共用日志、取消和结果机制。
 
@@ -133,7 +147,7 @@ outputs:
 
 ### 常规源码启动
 
-开发机器安装 **Node.js 24.15.0** 和 npm，在仓库根目录执行：
+开发机器安装 **Node.js 22.22.2+（22 系列）或 24.0.0+** 和 npm，在仓库根目录执行；便携包自带的固定 Node 仍为 24.15.0：
 
 ```sh
 npm ci

package/manual/README.md

@@ -6,20 +6,20 @@
 
 交互终端支持选择能力、配置参数和流程编排；官方 Web 插件默认提供，原子 CLI 子命令用于自动化。三种入口共用应用服务。YAML、依赖锁和版本解析由系统维护，不要求普通用户手写。
 
-0.5.0 增加工作流复制、按工作区/插件/动作设置代理、插件权限预检，以及只重启受影响插件的更新。大量输出落盘、开发重载和隔离文件探测继续可用。发布与验证状态见 [版本记录](docs/releases.md) 和 [验收记录](docs/verification.md)。
+0.5.3 修正 Node 安装兼容性与 TUI 状态提示：未修改时不产生草稿、配置备份或插件重启；删除工作流时明确选择备份后删除、直接删除或取消。`!` 系统命令透传、常用命令注册、中文快捷名称和 Shift+Enter 多行输入继续可用。发布与验证状态见 [版本记录](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 安装：
+安装端需要 Node.js **22.22.2+（22 系列）或 24.0.0+**，以及 npm。已发布版本可从 npm 安装：
 
 ```sh
 npm install -g @yanglaofish/fishtools
 fst
 ```
 
-也可从 GitHub Release 下载当前版本的 `.tgz` 后执行 `npm install -g ./yanglaofish-fishtools-0.5.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.5.3.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,15 +41,25 @@ fst --project ./my-project pack hello --target linux-x64-glibc --web
 
 启动 `fst` 后输入 `/` 会展开操作列表，使用上下箭头选择、Tab 补全、Enter 确认，Escape 返回。普通输入与插件命令忙碌页使用 Ctrl+C 取消；运行观察面板内 Ctrl+C 只关闭面板。在主提示符处 Ctrl+C 请求退出，有未保存修改或后台运行时会先确认。
 
+主输入框和命令编辑框使用 **Shift+Enter 换行、Enter 提交**，多行粘贴保留真实换行；终端无法区分 Shift+Enter 时使用 **Alt+Enter**。输入 `!echo hello` 可执行系统命令。`/commands` 注册常用命令，`/shortcuts` 给任意插件动作或命令设置中文快捷名，例如 `/查看本机IP`；注册动作也能加入工作流。详细用法见[命令与快捷名称](docs/terminal-commands.md)，离线可用 `fst docs commands` 阅读。
+
 首页展示 FISHtools 字符标识、欢迎介绍、当前工作区以及插件和工作流数量；小窗口自动使用紧凑标题。首次使用可以输入 `/run hello`，按提示输入文本（也可保留默认值），体验“转为大写 → 追加标记 → 保存文件”。运行过程与输入输出留在主面板，期间仍可打开配置或执行其他工作流。PgUp/PgDn 或鼠标滚轮浏览会话中的过程，向下翻至末尾恢复跟随。首页只推荐当前工作区实际存在的工作流；空工作区从 `/workflows` 新建。
 
-顶部的“位置”显示主面板或当前操作入口，菜单标题显示正在操作的对象。提交的命令、菜单选择与实际操作结果保留在本次会话中；返回时只更新当前位置，不追加通用返回消息，也不清空执行过程。这些导航记录只保留在当前会话。
+顶部的“位置”显示主面板或当前操作入口，菜单标题显示正在操作的对象。提交的命令、反馈与运行结果自动保存在所属工作区；返回菜单不会清空执行过程。`/history` 可恢复旧会话并继续输入，也可分页查看完整交互记录；恢复不会重新执行旧命令或覆盖旧会话。若已有插件或快捷名使用 `history`，从 `/tools` → 历史会话进入。
 
 主面板查看当前执行，`/logs` 回看某次执行的步骤状态、输入输出和日志，也能重新打开正在运行的任务详情。查看记录不会重新执行工作流。旧 `/runs` 和 F4 仅作为兼容方式转到同一个 `/logs` 入口，不再提供独立列表。
 
-主面板默认按步骤显示“执行中／成功／失败”，每一步标明能力与插件；**Ctrl+O 展开/收起详情**，查看各步输入输出、作者日志和子进程 stdout/stderr。错误摘要与插件 `print()` 的用户提示直接展示，普通技术日志默认折叠。折叠只改变展示，不丢弃日志或结果。
+`/logs` 标明每次执行属于工作流、插件动作、插件命令或系统命令，以及本次或历史启动。可以按本次启动或调用类型筛选，先显示最近 20 条，再按需显示更多。一个工作流的子流程和内部步骤放在同一条记录中。
+
+插件生成的业务文件放在工作区可见的 `results/运行ID/`，日志放在 `.flow/runs/运行ID/`；两者隔离，业务文件即使叫 `result.json` 也不会被内核运行记录覆盖。指定 `--output 目录` 时，该目录仍保存日志，业务文件在其 `files/运行ID/`。TUI 显示实际生成文件的目录，日志保留设置不会删除业务结果，历史文件仍在原位置。
+
+普通 CLI/TUI 的 `plugin add` 与 `plugin link` 默认登记到用户级 `~/.fishtools/plugins`（设置 `FISHTOOLS_HOME` 时为其 `plugins` 子目录），安装一次，各工作区可用。各工作区单独保存工作流、插件参数和代理规则；未填写必填配置的插件显示“待配置”，其他插件仍可使用。旧工作区安装兼容读取，同名全局版本优先。全局卸载检查已登记工作区的工作流引用；其他已运行进程保留自己的代码，重启后读取新状态。离线分发包继续使用包内快照及自身可写工作区。
 
-主输入框用 **↑ / ↓** 回看本次启动中已提交的命令，向下回到底部恢复未提交草稿。补全菜单打开时，方向键仍选择候选；配置表单内容不进入命令历史。最多保留最近 100 条，相邻重复命令合并，退出后不保存。
+主面板默认按步骤显示“执行中／成功／失败”，每一步标明能力与插件，并在旁边提示 **Ctrl+O 查看详情**。展开后按插件字段标题显示输入输出；通过 `runProcess` 执行的程序会记录真实路径、逐项参数与执行目录，Shell 同时记录原始命令，插件文件目录按实际来源显示。内核无法观察插件绕过受管接口执行的任意代码或文件访问。错误摘要、系统命令输出与插件 `print()` 的用户提示直接展示，普通技术日志默认折叠。主面板和运行总览显示总耗时，运行中实时更新，结束后固定。平台声明不匹配也会直接在 TUI 中提示。
+
+主输入框用 **↑ / ↓** 回看已提交的命令，向下回到底部恢复未提交草稿。补全菜单打开时，方向键仍选择候选；配置表单内容不进入命令历史。恢复会话同时恢复最近 100 条、合计不超过 256 KiB 的输入，相邻重复命令合并；更长和更早的输入仍在完整交互记录中。未提交草稿不保存。
+
+会话保存在 `.flow/sessions/`；只读包使用可写日志目录的 `sessions/` 子目录。追加日志保存命令和反馈，快照保存有界近期面板，较大运行结果通过 `/logs` 读取原始记录；运行日志仍遵循用户设置的保留策略。会话使用本地 UTF-8 文件，首版不加密、不压缩，也不自动删除旧会话。
 
 `/plugin` 直接列出当前已加载的插件名称、版本和状态。上下选择后可查看用途、编排能力、输入输出、环境声明及斜杠命令；有配置的插件提供配置入口，自行安装的插件提供移除入口。内置插件标明来源，避免误以为没有安装。`/help` 在终端内提供可翻页的用法说明。顶层补全标明 `[内置]` 或 `[插件]`，插件能力收进插件名入口的二级菜单。
 
@@ -58,13 +68,16 @@ fst --project ./my-project pack hello --target linux-x64-glibc --web
 | `/workflows` | 浏览、新建；进入某个流程后添加/编辑步骤、设置输出、保存、运行或删除 |
 | `/run 工作流ID` | 可按 ID 或中文标题补全，填写参数后执行已保存版本；只输入 `/run` 打开已保存工作流列表 |
 | `/logs` | 回看执行记录，运行中的任务优先；可切换总览、输入输出与日志，支持键盘或鼠标滚轮阅读 |
+| `/history` | 恢复旧 TUI 会话的输入、反馈和结果，或分页查看完整交互 |
 | `/plugin` | 浏览已安装插件、用途及能力，进入插件配置、安装和移除操作 |
 | `/pack` | 勾选工作流并选择目标平台打包 |
 | `/config` | 配置 Fishtools：查看工作区信息，设置日志保留次数和代理规则 |
-| `/tools` | 启动 Web 或阅读离线资料 |
+| `/tools` | 历史会话、启动 Web 或阅读离线资料 |
 | `/help`、`/exit` | 查看帮助、退出 |
 
-旧 `/new`、`/add`、`/steps`、`/outputs`、`/save`、`/plugins`、`/docs`、`/web` 和 `/runs` 仍可直接输入，顶层补全主要呈现上表的对象入口。工作流编辑菜单返回时保留当前草稿，切换流程或退出会确认未保存修改。删除会将已保存文件移入 `.flow/deleted-workflows/工作流ID-编号.yaml`，仍被其他流程引用时拒绝删除；恢复时将备份复制回 `workflows/原工作流ID.yaml`，先确认同名文件不存在，避免覆盖。
+旧 `/new`、`/add`、`/steps`、`/outputs`、`/save`、`/plugins`、`/docs`、`/web` 和 `/runs` 仍可直接输入，顶层补全主要呈现上表的对象入口。有实际未保存修改时，工作流编辑菜单返回会保留草稿，切换流程或退出会确认是否放弃。查看后原样完成、修改后还原为已保存值不会产生草稿提示。
+
+删除时提供“备份后删除、直接删除、取消”，默认选择取消。备份后删除将已保存文件移入 `.flow/deleted-workflows/工作流ID-编号.yaml`；恢复时将备份复制回 `workflows/原工作流ID.yaml`，先确认同名文件不存在。直接删除不创建本次删除的备份；仍被其他流程引用时，两种删除方式都拒绝执行。
 
 `/run` 不要求保存当前编辑草稿，也不会丢弃它。要运行尚未保存的修改，请在 `/workflows` 的编辑菜单选择“运行工作流”，再选择“保存并运行”；已有磁盘版本时也可选择“运行已保存版本”并保留草稿。“返回编辑”会留在当前工作流，不会反复弹出保存确认。只查看参数或拒绝删除步骤不会产生未保存修改。
 
@@ -105,10 +118,11 @@ outputs:
 | `f` | 切换日志跟随 |
 | Enter | 在总览中查看所选步骤详情，不退出面板 |
 | `j` | 在易读字段与原始 JSON 诊断之间切换 |
+| `m` | 单独格式化阅读输出；插件标注的 Markdown 结果按 Markdown 呈现 |
 | Esc、q、Ctrl+C | 返回上一级，运行中的任务继续；输入 `/logs` 可重新打开 |
-| `x`，再按 `y` | 确认取消整个运行 |
+| `x`，再按 `y` | 任务仍在运行时，确认取消整个运行 |
 
-运行记录同时列出正在执行和保留的历史记录，运行中任务优先；同一个工作流的多次执行分别显示时间和记录编号。查看详情后返回列表，可以继续选择另一次执行。本次启动期间每次运行分别保存阅读位置；重启后可通过 `/logs` 查看保存的记录，主面板会话展示从新会话开始。日志保留设置在 `/config`。主提示符 `/exit` 或 Ctrl+C 遇到后台任务时，会说明退出将取消任务并请求确认，默认不退出。
+运行记录同时列出正在执行和保留的历史记录，运行中任务优先；同一个工作流的多次执行分别显示时间和记录编号。查看详情后返回列表，可以继续选择另一次执行。本次启动期间每次运行分别保存阅读位置；重启后可通过 `/logs` 查看保存的运行，`/history` 恢复旧主面板。上次退出时仍在运行且缺少最终记录的任务会明确显示“未记录最终状态”。日志保留设置在 `/config`。主提示符 `/exit` 或 Ctrl+C 遇到后台任务时，会说明退出将取消任务并请求确认，默认不退出。
 
 插件可以注册自己的命令：官方示例的 `/examples` 入口包含文本转大写与交互文本输入，`/environment` 入口包含环境检查与报告。原 `/text.upper`、`/text.ask`、`/env.check`、`/env.report` 仍可直接调用。`check` 在环境未通过时抛错；`report` 正常返回 `ok:false` 和检查明细，适合交给工作流条件判断。安装或移除插件会同步刷新 `/` 菜单；命令和工作流共用日志、取消和结果机制。
 
@@ -133,7 +147,7 @@ outputs:
 
 ### 常规源码启动
 
-开发机器安装 **Node.js 24.15.0** 和 npm，在仓库根目录执行：
+开发机器安装 **Node.js 22.22.2+（22 系列）或 24.0.0+** 和 npm，在仓库根目录执行；便携包自带的固定 Node 仍为 24.15.0：
 
 ```sh
 npm ci

package/manual/docs/deployment.md

@@ -2,10 +2,10 @@
 
 ## 直接在 Linux / Windows 安装 Fishtools
 
-完整工具支持 npm 安装，目标机器需要 Node.js 24.15.0+ 和 npm：
+完整工具支持 npm 安装，目标机器需要 Node.js 22.22.2+（22 系列）或 24.0.0+ 和 npm：
 
 ```sh
-npm install -g ./yanglaofish-fishtools-0.5.0.tgz
+npm install -g ./yanglaofish-fishtools-0.5.3.tgz
 fst
 fst run hello
 ```
@@ -14,7 +14,7 @@ fst run hello
 
 默认用户工作区为 `~/.fishtools`，可用 `FISHTOOLS_HOME` 覆盖。`fst init ./project` 创建独立项目，`fst --project ./project` 打开它。数据放在工作区，升级或卸载全局 npm 包不会覆盖工作流。
 
-Linux 无 npm 全局目录写权限时，可使用 `npm install -g --prefix "$HOME/.local" ./yanglaofish-fishtools-0.5.0.tgz` 并把 `$HOME/.local/bin` 加入 PATH。`fst` 提供斜杠命令、文件补全和方向键选择；Web 使用 `fst web`，交互容器需要分配终端（例如 `docker run -it`）。不分配终端时使用 `fst run` 等原子命令。
+Linux 无 npm 全局目录写权限时，可使用 `npm install -g --prefix "$HOME/.local" ./yanglaofish-fishtools-0.5.3.tgz` 并把 `$HOME/.local/bin` 加入 PATH。`fst` 提供斜杠命令、文件补全和方向键选择；Web 使用 `fst web`，交互容器需要分配终端（例如 `docker run -it`）。不分配终端时使用 `fst run` 等原子命令。
 
 以下章节描述按选定工作流导出的自包含运行包；它们携带 Node，运行端无需 npm。新运行包提供 `fst.cmd` / `./fst` 启动入口，兼容保留 `run.cmd` / `run.sh`。
 

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

@@ -5,5 +5,5 @@
   "main": "index.js",
   "files": ["index.js", "README.md", "LICENSE", "input.json"],
   "license": "MIT",
-  "engines": {"node": ">=24.15.0"}
+  "engines": {"node": "^22.22.2 || >=24.0.0"}
 }

package/manual/docs/modules.md

@@ -20,6 +20,8 @@ Fishtools 在同一仓库维护十一模块，使用 npm workspaces 连接，继
 
 各目录的 README 列出公开入口、边界和定向测试。问题单与改动说明应写明负责模块及受到影响的消费者。实际维护人员尚未分配；本次没有虚构 CODEOWNERS。
 
+0.5.2 的常用命令由官方 `@mytools/commands` 插件（`plugins/commands`）执行。与 environment、examples 一样，它使用公开的插件协议，不增加内核模块：platform 提供 Shell 调用，workspace 校验快捷名，core 保存和装配项目注册项，CLI 提供交互，logs 记录完整输出。
+
 ## 依赖规则
 
 - SDK 为底层共享契约；主入口不加载 schema 校验器，校验器通过 `/schema` 加载。

package/manual/docs/plugin-development.md

@@ -135,9 +135,13 @@ fst plugin remove my-flow-plugin
 
 `plugin add <本地目录>` 是复制安装，源文件修改不会自动反映到已安装副本；重复 `add` 即可更新，无需先 `remove`。开发时使用下述引用模式。CLI 管理命令以独立进程运行；常驻 TUI/Web 对需要重启的服务显示本次维护提示，仅更新受影响的插件及依赖它的插件。
 
-插件安装在 `.flow/installations/<随机安装批次ID>` 新目录，验证加载成功才切换状态，失败保留原配置。安装禁用 npm 生命周期脚本；TS 发布前编译，原生库及其目标平台资源由作者准备。核心不审核平台兼容性，也不自动重建原生库。工作流运行期间不能变更插件。
+普通 CLI/TUI 默认在用户级 `~/.fishtools/plugins/.flow/installations/<随机安装批次ID>` 新目录安装，设置 `FISHTOOLS_HOME` 后改为其 `plugins` 子目录；开发链接也全局登记。工作区单独保存参数、工作流和代理规则，缺少必填配置时插件显示“待配置”，配置完成后启用。旧工作区 `.flow/plugins.json` 兼容读取，同名全局版本优先；全局卸载后不复活旧本地版本。离线包继续在自身可写工作区安装和管理，不加载宿主全局插件。
 
-移除插件前会检查所有已保存工作流（含分支、并行和子工作流）的引用，并显示受影响工作流；仍被其他插件依赖时始终拒绝。确认接受工作流暂时无法运行后，可用 `fst plugin remove 插件ID --force` 跳过工作流引用保护。工作流文件不会随卸载删除，重新安装插件后仍可使用。
+升级前已经安装在工作区的插件不会自动搬移。需要在其他工作区使用时，再执行一次 `fst plugin add 包名或路径`，开发源码则使用 `fst plugin link 源码目录`，即可登记到全局库；原有配置和安装备份仍保留。
+
+验证成功才切换安装状态，失败保留原配置；前一状态存入 `plugins.previous.json`，活动代码由批次租约保护。安装禁用 npm 生命周期脚本；TS 发布前编译，原生库及其目标平台资源由作者准备。核心不审核平台兼容性，也不自动重建原生库。当前工作区运行期间不能变更插件，其他已启动进程使用其现有代码，重启后读取新状态。
+
+移除全局插件前会检查已登记工作区的已保存工作流（含分支、并行和子工作流）的引用，以及各工作区预置或旧本地插件对它的依赖；显示受影响工作区与工作流。移除旧工作区插件仅检查当前工作区。仍被其他插件依赖时始终拒绝，`--force` 不绕过插件依赖检查。确认接受工作流暂时无法运行后，可用 `fst plugin remove 插件ID --force` 跳过直接工作流引用保护。工作流文件不会随卸载删除，重新安装插件后仍可使用。
 
 业务 npm 库写入 `package.json.dependencies`，开发库写入 `devDependencies`。插件间依赖另外写在定义的 `dependencies: {'other-plugin': '^1.0.0'}`，用于宿主版本检查和打包闭包；被依赖插件也需安装并注册。
 
@@ -254,6 +258,7 @@ Linux 支持 `user/root/resource`，Windows 支持 `user/administrator/resource`
 | `signal` | 取消信号，异步动作应响应 |
 | `runId`、`stepId`、`callPath` | 运行和嵌套步骤定位 |
 | `outputDir` | 本次运行的可写结果目录 |
+| `logDir` | 本次运行的日志目录；业务文件应写入 outputDir |
 | `resourceDir` | 插件包目录，用于定位脚本 |
 | `projectDir` | 当前工作区根目录；可编辑便携包使用其包外工作区 |
 | `stateDir` | 当前插件跨运行持久目录，与 outputDir 无关；只读项目或无应用的独立宿主为 undefined |
@@ -265,6 +270,8 @@ Linux 支持 `user/root/resource`，Windows 支持 `user/administrator/resource`
 
 返回值必须可 JSON 序列化，输入输出经 Ajv 校验。插件在宿主进程中执行，属于可信代码；同步阻塞代码不能被取消信号抢占。
 
+从 0.5.3 起，普通工作区的业务文件默认写入 `results/运行ID/`，执行日志写入 `.flow/runs/运行ID/`。日志保留策略不会清理业务结果，历史文件也不会自动搬移；插件应返回或 `print()` 实际保存路径，方便用户找到文件。
+
 可写应用在调用前创建 `.flow/plugin-state/<插件ID的SHA-256十六进制摘要>/`。固定长度目录避免 scoped 包名、Windows 大小写和长文件名问题；卸载不自动删除此目录，分发也不自动携带其中数据。插件自行处理原子写入、并发和数据版本。跨插件交换业务结果使用工作流输出或公开服务，不依赖其他插件的私有目录。只读精简包不创建持久状态，需要状态的插件应提示使用可编辑工作区。
 
 `runProcess` 新增 `encoding`，默认 `utf8`，也可用 `utf16le`、`gbk` 等当前 Node TextDecoder 支持的编码；实时日志和返回文本采用同一编码，并正确处理跨块字符。示例：`runProcess('wsl',['-l','-v'],{encoding:'utf16le'})`，具体编码应以目标命令版本为准。Windows PowerShell 的编码和 CLIXML 是不同问题，宿主不自动猜编码或解析 CLIXML。输出上限仍按每个流的原始字节计量，默认 4 MiB；超限回收进程树并抛 `OUTPUT_LIMIT`，不返回伪装完整的截断结果。
@@ -277,6 +284,10 @@ Linux 支持 `user/root/resource`，Windows 支持 `user/administrator/resource`
 
 `runProcess` 默认无 Shell，参数用数组。支持 `cwd`、`env`、`signal`、`timeout`（默认 30 秒）、`maxBuffer`（stdout/stderr 各默认 4 MiB）和可选的 `onOutput({stream,message})`。普通非零退出返回 `{exitCode,stdout,stderr}`，动作应自行决定是否抛出业务错误；缺失程序、超时、取消、输出超限抛错，并等待进程树回收。不要把密码或令牌写入日志。
 
+受管 `ctx.runProcess` 在启动前自动记录实际程序、参数数组和执行目录，Shell 另记录原始指令；自定义 `onStart({file,args,cwd,script?})` 在此记录后调用。启动记录写入失败或此时取消会阻止启动子进程。插件实际来源目录也随调用记录，TUI 展开后可以阅读这些信息。通过其他方式执行的程序或任意文件访问不在该记录范围内；参数若含凭据，也会进入本地执行日志，作者应通过环境变量或其他受控渠道传递。
+
+工作流、直接动作和插件命令在执行前统一追加 `run.input`，保存本次提交的完整参数；界面及元数据仍仅持有有界预览。较大参数通过 `/logs` 的完整日志分页读取，配置表单不属于运行参数，不进入此记录。
+
 默认 buffer 模式的 `OUTPUT_LIMIT` 限制子进程返回缓冲及实时输出队列，不是 run.md 的文件体积阈值。触发后只能取得超限前已记录的部分输出，不能当作完整结果。可以按业务明确提高有限的 maxBuffer；大量连续日志可选择 `outputMode:'stream'`，完整落盘、内存只保留尾部摘要并显式标记截断。超大业务结果也可由程序写到 outputDir 内的文件，stdout 返回摘要或路径。
 
 ### 不可信路径与网络挂载
@@ -468,11 +479,13 @@ async function run({executable, text}, {resourceDir, runProcess, signal}) {
 
 ## 注册斜杠命令
 
-`commands` 的键不含 `/`，推荐使用 `插件短名.操作名`；不得与核心入口或其他插件命令重名。安装/移除后 TUI `/` 菜单立即更新，失败的安装不会替换旧宿主。
+`commands` 的键不含 `/`，支持中文及其他 Unicode 字母，推荐使用 `插件短名.操作名`；名称为 NFC 形式，以字母开头，后续可含字母、数字、下划线、点、短横线。不得与核心入口或其他插件命令重名，`commands`、`shortcuts` 为新增保留入口。安装/移除后 TUI `/` 菜单立即更新，失败的安装不会替换旧宿主。
+
+用户可通过 TUI `/shortcuts` 为任意动作或已有命令设置快捷名称及默认参数，不需要插件为每个别名注册命令；npm 包名、插件 ID 和动作 ID 不变。简单的 Shell 脚本可通过 `/commands` 注册为官方命令插件的动作；业务解析仍由业务插件负责，详见[命令与快捷名称](terminal-commands.md)。`ui.input` 可传 `{multiline:true}` 显示多行提示，Shift+Enter/Alt+Enter 换行、Enter 提交完整文本。
 
 TUI 顶层按插件归组：例如 ID `@mytools/examples` 对应 `/examples`，进入后选择具体能力，列表标明 `[插件]`、插件名称及 ID。入口取插件 ID 的末段；同名插件使用完整 ID 转为连字符名称，遇到保留名或已有命令则加 `plugin-` 前缀。以当前补全列表中的实际入口为准，不要在插件间依赖这个 UI 别名。只有注册了 `commands` 的插件才产生能力入口，纯服务/纯动作插件仍可在 `/plugin` 管理或参与工作流。原始命令名和 CLI `fst command` 协议不变，旧插件无需迁移定义。新保留入口包括 `plugin`、`tools`，作者应继续使用带插件前缀的命令名。
 
-TUI 负责展示当前工作区、操作入口、菜单标题以及提交命令和操作结果。返回时只更新当前位置，不追加通用返回消息。插件使用 `ui.input/select/show/confirm`，不要自行清屏或打印终端控制序列，以免破坏主面板中的运行过程。导航记录仅保留在本次会话，持久诊断请使用动作上下文的日志接口。`/run` 执行已保存的工作流；工作流草稿只在编辑菜单明确选择“保存并运行”后才写入，不由插件命令隐式保存。
+TUI 负责展示当前工作区、操作入口、菜单标题以及提交命令和操作结果。返回时只更新当前位置，不追加通用返回消息。插件使用 `ui.input/select/show/confirm`，不要自行清屏或打印终端控制序列，以免破坏主面板中的运行过程。主面板输入、反馈和结果关联可以通过 `/history` 恢复；配置表单和未提交草稿不保存，持久诊断继续使用动作上下文的日志接口。`/run` 执行已保存的工作流；工作流草稿只在编辑菜单明确选择“保存并运行”后才写入，不由插件命令隐式保存。
 
 ```js
 commands: {
@@ -543,7 +556,7 @@ TUI `/pack` 选择来源并展示资源字节数；CLI 支持 `--plan` 和 `--en
 ## 发布前检查清单
 
 1. **打包检查**：在插件目录运行 `npm pack --dry-run`，确认编译后的入口、脚本、资源和许可证均会进入包，未夹带凭据或开发数据；再用 `npm pack` 生成待安装的 `.tgz`。
-2. **独立安装**：在单独测试工作区用 `fst --project <测试工作区> plugin add <插件.tgz的绝对路径>` 安装，使用 `plugin list` 确认插件可加载。源码开发可将 `fst` 替换为 `npm run fst --`。
+2. **独立安装**：测试时先将 `FISHTOOLS_HOME` 设置为独立临时目录，再用 `fst --project <测试工作区> plugin add <插件.tgz的绝对路径>` 安装，使用 `plugin list` 确认插件可加载，避免影响日常用户级插件库。源码开发可将 `fst` 替换为 `npm run fst --`。
 3. **界面检查**：打开测试工作区，确认能力标题、用途、输入字段和输出说明可理解；添加动作并填写参数保存工作流。
 4. **执行检查**：分别验证正常输入、缺少必填项、错误类型、业务失败、缺少程序/依赖、超时与取消。失败必须明确报告，不得伪装为成功。没有子进程的动作不必模拟不适用的进程场景。
 5. **组合检查**：把动作输出传给下一步，确认字段和类型稳定；执行同一工作流两次，验证副作用符合说明。

package/manual/docs/releases.md

@@ -2,6 +2,52 @@
 
 产品名称 Fishtools，公共 npm 包名 `@yanglaofish/fishtools`，启动命令 `fst`。`0.x` 定位为早期可用版本。内部 `@mytools/*` 包随主包捆绑，不单独发布；内部插件 API 版本独立维护。
 
+## 版本号与发布节奏
+
+按 2026-10-13 的约定，减少零散发包，按修改的实际影响选择版本号：
+
+- 保持兼容的小修复、小优化使用补丁版本，例如 `0.5.1 → 0.5.2`；不因每次小改动增加中间一位版本号。
+- 相关修改集中完成代码审查和必要验证，确认没有待处理问题后一次发布，不按每个提交单独发包。
+- 一批明显的新能力或兼容性变化，再考虑增加中间一位，例如 `0.5.x → 0.6.0`，并在发布说明中解释升级影响。
+- 仅文档、测试或开发流程调整，且不需要用户升级已安装产品时，不单独增加产品版本或发布 npm。
+
+已发布版本不可覆盖。本轮用户明确指定新能力目标为 `0.5.2`，集中完成审查验证后发布；后续继续按实际影响和用户约定选取版本。
+
+## 0.5.3 全局插件、可读详情与会话恢复
+
+- npm 安装支持 Node 22.22.2+（22 系列）和 24.0.0+，包含 issue #4 使用的 24.11.1。生产依赖选择兼容的维护分支，生成包沿用项目的 Node 声明，严格安装验收会拒绝任何不兼容依赖。
+- 兼容性试验在 Windows/Node 22.12.0 再次导出时复现原生进程崩溃；同一测试在 22.22.2 和 24.11.1 通过，因此没有把早期 22 系列声明为支持版本。
+- 工作流没有实际修改时，复制与返回菜单不显示“未保存修改”或“草稿”；查看控制节点及修改后还原也保持准确状态。删除时选择备份后删除、直接删除或取消，默认取消，引用保护与只读保护仍生效。
+- 插件配置、代理规则/配置、日志保留设置、常用命令与快捷名称原样完成时不写文件、不创建备份、不重启插件。已有常用命令不会因进入编辑页自动添加快捷名称。
+- 可选参数仅在声明默认值时说明会使用默认值；已结束任务不显示取消入口。删除注册项只提示实际受影响的快捷名称；打包只在选中当前草稿或其父工作流时询问使用哪个版本。
+- 同步核对 TUI 的权限、定向维护、插件卸载、运行错误和日志提示，保留有实际检查结果的提醒。便携包自带 Node 24.15.0，工作流格式与插件 API 保持兼容。
+- 修复 issue #5 的业务文件覆盖风险：业务输出独立保存到工作区 `results/运行ID/`，日志保留策略只清理日志；即使业务文件叫 `result.json` 也不会被内核覆盖。
+- 普通安装、开发链接默认使用用户级共享插件库，各工作区共用代码并独立保存配置。旧工作区安装兼容读取，缺必填配置的全局插件可在 TUI 配置后启用；热重载包含全局链接。
+- 执行记录标明工作流、插件动作、插件命令和系统命令，保存启动会话，支持按本次启动及入口筛选、继续加载历史，内嵌调用仍只产生一条顶层记录。
+- 运行和步骤附近显示 Ctrl+O 展开提示。详情按字段标题展示输入输出，记录受管子进程的真实程序、参数、工作目录与原始脚本；m 格式化阅读输出，j 保留原始 JSON。
+- 主面板和详情显示执行总耗时，日志收尾后补齐真实结束时间；日志保存失败同步显示失败并保存会话反馈。完成运行的等待对象不继续持有大结果。
+- `/history` 恢复所属工作区的完整 TUI 会话：输入、执行反馈、结果关联，并支持分页阅读完整交互。近期摘要保持内存有界，恢复不会重复执行命令或覆盖旧会话；插件和快捷名称优先，重名时从 `/tools` 进入历史。
+- 插件的平台及架构声明不匹配直接显示在 TUI；Windows 简单 `!ipconfig` / `!ipconfig /all` 按系统 OEM 编码读取中文，同时保留其他命令、多行脚本、管道和重定向的执行方式。
+- 修复早期 Node 24 在 Windows 的日志文件身份误判，保留链接、文件替换及读取预算检查；打包命中有效运行时缓存时不重写，冷缓存校验后原子保存，避免并发读取半成品。
+
+验证与正式发布结果见[验收记录](verification.md)。
+
+## 0.5.2 命令注册与快捷名称
+
+- TUI 主输入框支持 `!` 后的系统命令，原样保留多行、引号、管道和重定向，纳入运行记录、取消、超时与完整日志。
+- `/commands` 注册、编辑、删除和执行常用命令，自动生成标准动作及简单参数表单，已被工作流引用的注册项受到删除保护。
+- `/shortcuts` 为任意插件动作或命令添加中文快捷名称与默认参数；插件原始命令也支持中文，失效目标明确显示原因。
+- 主输入框及命令编辑框采用 Shift+Enter 换行、Enter 提交，Alt+Enter 备用；粘贴保留换行及缩进。
+- 按 issue #4 收拢工作流复制入口：列表每个工作流只出现一次，选择工作流后在管理页复制，当前未保存参数仍可保存到副本。
+- 注册项保存前备份，防止多个实例覆盖同字段改动；离线包携带所需命令定义与快捷名，可编辑工作区支持再次导出。
+
+工作流格式、SDK_VERSION 和原动作 ID 保持兼容。命令按当前用户权限执行，使用已有代理和权限接口；外部 Shell 与程序由目标机器提供。第一版支持无需交互输入的命令。完整用法见[命令指南](terminal-commands.md)。发布状态以 GitHub Release 和验收记录为准。
+
+**2026-10-13 发布完成：** [正式发布流程](https://github.com/yanglaofish/Fishtools/actions/runs/38361266757)全部成功。
+Windows / Ubuntu 各 488 项通过、1 项平台专用跳过，零失败；自包含包与断网容器验收通过。
+npm `latest` 为 0.5.2，独立下载公开包的校验值与注册表和 [Release](https://github.com/yanglaofish/Fishtools/releases/tag/v0.5.2) 一致。
+最新 issue #4 的复制入口修正已包含在该版本。
+
 ## 0.5.1 复核修正
 
 - 动作选择直连时，外部子进程不再重新继承系统代理；所选代理配置也不会被宿主残留变量干扰。
@@ -14,6 +60,10 @@
 工作流和插件格式保持兼容。本轮基于 0.4.0 至 0.5.0 的独立双轴复核，详见
 [审查记录](superpowers/reviews/2026-10-13-0.5.0-followup-review.md)。发布结果以 GitHub Release 与[验收记录](verification.md)为准。
 
+**2026-10-13 发布完成：** [发布流程](https://github.com/yanglaofish/Fishtools/actions/runs/38329427621)全部成功，
+Windows 382 项、Ubuntu 381 项通过（1 项平台专用跳过），自包含包与断网容器验收通过。
+npm `latest` 为 0.5.1；独立下载包校验值与注册表及 [Release](https://github.com/yanglaofish/Fishtools/releases/tag/v0.5.1) 一致。
+
 ## 0.5.0 内核能力与日常操作
 
 - 大量进程输出可以完整落盘、内存只保留有限摘要；CLI、TUI、Web 支持分页查看完整日志。开发引用插件可用 `--watch` 在业务空闲后重启完整进程；网络挂载文件探测在隔离进程中执行并设置超时与资源预算。
@@ -60,7 +110,7 @@
 
 ## 发布入口
 
-**发布前先完成本地试用并取得用户确认。** 自动化测试通过只代表具备试用条件，不代替用户对交互体验的验收。交付本地启动入口、说明改动及测试结果后，等待用户明确确认本轮可以发布，才创建版本 tag、发布 npm 或 GitHub Release。普通修复提交不触发发包。
+**发布前完成代码审查、必要验证，并确认本轮发布已获用户授权。** 用户已明确要求“验证后推送和发包”时，沿用该授权；涉及交互体验的新功能先提供本地试用入口、说明改动及测试结果，自动化测试不代替用户对交互体验的验收。普通修复提交不触发发包。
 
 `npm run preview` / 根目录 `fst-preview.cmd` 继续提供独立源码预览工作区；其运行不会修改全局安装或默认工作区。0.3.0 的对象菜单、主面板运行及公共插件修复已列入本次发布范围。
 
@@ -76,20 +126,20 @@
 
 ## 准备下一个版本
 
-在开发分支完成修改、更新说明并验证后：
+在开发分支完成修改、更新说明并验证后，按上面的约定选择版本号。以下为本轮 `0.5.2` 的准备命令：
 
 ```sh
-npm version 0.1.4 --no-git-tag-version
+npm version 0.5.2 --no-git-tag-version
 git add package.json package-lock.json packages/core/src/version.js
-git commit -m "chore: prepare 0.1.4"
+git commit -m "chore: prepare 0.5.2"
 ```
 
 `npm version` 自动同步 CLI 的产品版本。合入 main 后，对经过审查的提交执行：
 
 ```sh
-git tag -a v0.1.4 -m "Fishtools 0.1.4"
+git tag -a v0.5.2 -m "Fishtools 0.5.2"
 git push origin main
-git push origin v0.1.4
+git push origin v0.5.2
 ```
 
 不要改动已经发布的 tag。主版本号尚为 0，升级前查看变更说明并备份工作区。

package/manual/docs/superpowers/plans/2026-10-13-command-shortcuts.md

@@ -0,0 +1,108 @@
+# 0.5.2 终端命令与快捷名称实现计划
+
+> **For agentic workers:** REQUIRED SUB-SKILL: 使用 superpowers:executing-plans 逐项实现；独立文件任务可按 superpowers:dispatching-parallel-agents 并行处理。
+
+**Goal:** 支持命令透传、轻量注册、任意插件能力的中文快捷名和明确的多行编辑。
+
+**Architecture:** platform 负责 Shell 调用，官方命令插件生成标准动作，core 在工作区注册项变化时装配并更新该插件。快捷名存储独立于稳定标识，TUI 复用原动作/命令表单与现有运行记录。
+
+**Tech Stack:** Node.js >=24.15.0、ESM、node:test、现有 pi-tui、JSON Schema。
+
+**Spec:** `docs/superpowers/specs/2026-10-13-command-shortcuts-design.md`
+
+## 全局约束
+
+- 产品版本目标 0.5.2；SDK_VERSION、工作流 schemaVersion 和内部包版本保持不变。
+- 文档、提示与代码注释使用中文；生产跨包调用使用声明的 exports。
+- 不新增外部依赖；执行全部经过 runProcess，流式输出由 logs 完整落盘。
+- Shift+Enter 换行、Enter 提交；Alt+Enter 备用。
+- 用户已授权直接编码、审查验证后推送和发包；本轮在 `codex/0.5.2-command-shortcuts` 分支进行。
+
+## Review Focus
+
+- 中文组合字符、控制符及与内置/插件命令重名，不能覆盖其他入口。
+- 多行 curl 的引号、反斜杠、管道和真实粘贴换行必须原样传入 Shell。
+- 删除与其他实例编辑并发发生时，工作流引用不能绕过；保存失败恢复旧注册项。
+- 同一插件的动作快捷名必须遵从动作代理和权限规则。
+- 离线归档重新启动及再次导出仍包含注册定义，缺失外部命令要明确失败。
+
+## 文件与任务
+
+### 任务 1：Shell 执行与官方轻量命令插件
+
+**Files:** 新建 `packages/fst-platform/src/shell.js`、`plugins/commands/index.js`、该插件 package.json/README/LICENSE 与 `tests/command-process.test.js`；更新 platform exports。
+
+**Interfaces:** `shellInvocation(script,{shell='auto',platform=process.platform}={}) -> {file,args}`；`runShell(script,{shell,runProcess,temporaryDir,...options}) -> result`；`createCommandsPlugin(presets={}) -> plugin`、`validateCommandPresets(presets) -> clone`、`COMMANDS_PLUGIN_ID`、`commandsPluginRoot`。
+
+- [x] 先写真实 Shell、多行、非零退出、大输出、参数环境变量、稳定 ID 与无效声明测试，运行观察缺少能力而失败。
+- [x] Windows auto 使用 PowerShell，Linux auto 使用 sh；使用受管子进程接口，保持完整脚本文本。
+- [x] 每个注册项生成标准动作，自动输入 schema、固定输出 schema；使用 stream，非零退出报错。
+- [x] 执行 `node --test tests/command-process.test.js`，确认通过并记录结果。
+
+### 任务 2：多行输入
+
+**Files:** `packages/fst-cli/src/terminal/view.js`、新建 `tests/terminal-multiline.test.js`。
+
+**Interfaces:** `TerminalView.input(message,{multiline=false,...options})` 保持 Enter 提交；Shift+Enter/Alt+Enter 换行；提示与 multiline 同步。
+
+- [x] 先写按键驱动测试：换行不提交、粘贴保留换行、Enter 提交完整文本、取消不执行、窄屏不越界。
+- [x] 观察失败后最小修改 Editor 的按键处理及提示，避免影响主面板历史和补全。
+- [x] 执行 `node --test tests/terminal-multiline.test.js tests/terminal-command-history.test.js tests/terminal.test.js`。
+
+### 任务 3：中文命令与快捷名契约
+
+**Files:** `packages/fst-plugin/src/contracts.js`、`packages/fst-workspace/src/shortcuts.js`、workspace exports、新建 `tests/shortcuts.test.js`。
+
+**Interfaces:** `validateShortcuts(shortcuts,{reservedNames=[]}={}) -> clone`；`bindShortcutCommands(shortcuts,{commands=[],previous={}}={}) -> clone`；`describeShortcuts(shortcuts,{actions=[],commands=[]}={}) -> entries`，条目包含 name、target、input、available、description、reason；命令快捷名绑定目标插件身份。
+
+- [x] 先写中文插件命令、任意动作/命令快捷名、冲突与控制字符、失效目标和默认输入测试，观察失败。
+- [x] 接受 Unicode 字母的命令名称，保持内置与重复名称拒绝；快捷名独立于插件身份。
+- [x] 执行 `node --test tests/shortcuts.test.js`。
+
+### 任务 4：应用管理、注册装配与导出
+
+**Files:** `packages/core/src/application.js`、`packages/core/src/export-snapshot.js`、`packages/pack/index.js`、core 依赖、新建 `tests/command-management.test.js`。
+
+**Interfaces:** `app.startAction(id,input={},context={})`、`app.startShell(script,options={})`、`app.listShortcuts()`、`app.configureShortcuts(value)`、`app.configureCommandPresets(value,{shortcuts,allowMaintenance}={})`。
+
+- [x] 先写工作流执行注册动作、动作/命令快捷引用、项目设置备份与重启、大输出日志、删除引用保护、并发冲突、导出快照测试。
+- [x] 自动装配标准官方命令插件；透传也纳入 executeTracked，并使用工作区代理环境、超时、取消。
+- [x] 项目注册项保存前验证候选宿主，原子落盘失败回滚；同字段编辑冲突拒绝，引用保护在变更锁内检查。
+- [x] 导出过滤所需 commandPresets 和有效插件相关 shortcuts，pack 写入 flow.project.json。
+- [x] 执行 `node --test tests/command-management.test.js tests/application.test.js tests/runtime.test.js`。
+
+### 任务 5：TUI 管理与使用说明
+
+**Files:** 新建 `packages/fst-cli/src/terminal/command-menu.js`；更新 session、navigation、builtinCommands 与 README/插件文档；新建 `tests/terminal-user-commands.test.js`。
+
+- [x] 先写 `!` 原样透传、中文快捷名执行任意动作、注册多行脚本与修改/删除交互测试。
+- [x] `/commands` 注册、编辑、删除、运行；`/shortcuts` 选择目标、设置默认输入、编辑删除。
+- [x] 复用现有输入表单、权限处理与运行观察；主提示符写明 `!`、Shift+Enter 和 Enter。
+- [x] 升级 npm 归档依赖并同步 lock；离线资料包含命令插件和新说明。
+- [x] 执行 `node --test tests/terminal-user-commands.test.js tests/terminal-navigation.test.js tests/modules.test.js`。
+
+### 任务 6：复核、双平台验收与一次发布
+
+- [x] 更新产品版本为 0.5.2、发布说明；构建真实 npm 归档，针对同一归档运行本地全量测试。
+- [x] 使用 code-review 做规范与需求的独立双向复核，修正实际问题并验证。
+- [x] 推送已审查提交；发布 tag 触发 Windows/Ubuntu、便携与断网验收，全部通过后 npm 发布。
+- [x] 核对注册表版本、完整性和 GitHub Release，记录证据。
+
+## 执行记录
+
+- 2026-10-13：完成上下文核查，起点 `68a84cdb46cdb7f022eb3bf1d77ba478c52970ab`；工作区干净，新分支已创建。
+- 按用户全局要求采用本地分支保护本轮改动，沿用当前 checkout 和现有依赖；不迁移用户项目数据。
+
+- Shell 插件专项 21 项通过，关联进程/权限回归 30 项通过；多行按键及既有输入回归 40 项通过，快捷名契约与 runtime 回归 23 项通过。
+- 应用管理/TUI/多行/导航/模块专项 86 项：85 通过、1 项 POSIX 保存失败检查在 Windows 跳过；已复现并修复另一实例改脚本后插件装配仍使用旧闭包的问题。
+- 实际自包含包在仓库外执行中文快捷名、修改命令并再次导出：1 项通过；包含原注册脚本和修改后脚本的真实执行。
+- 版本已同步为 0.5.2；构建和独立双轴复核进入发布前验收。
+- 独立审查确认并修复 Windows 长脚本超过命令行限制、运行时插件漏查命令重名、命令快捷名被其他插件同名入口接管、另一实例删除命令后旧工作流草稿仍能保存四项问题。另修复编辑脚本丢失快捷默认参数和命令闭包未更新的问题。
+- 修复后专项 `command-management`、`terminal-user-commands`、`command-process`、`shortcuts` 合计 **78 项：77 通过、0 失败、1 项 POSIX 专用跳过**；真实执行 64 KiB 多行脚本、失效快捷名与跨实例草稿检查均通过。最终全量测试和独立复审继续进行。
+- `9772186` 的全量测试 477 项中 474 通过、1 失败、2 跳过；输出超限的树回收回归发现 Execa 提前关闭管道导致父进程退出、后代未被回收。发布暂缓，保留失败证据并增加真实父子进程回归。
+- 复审补齐未绑定旧快捷名被整组保存启用，以及参数表单等待期间目标提供者改变两条身份路径。三个新增回归先全部失败，修复后关联专项 **74 项：73 通过、0 失败、1 项 POSIX 专用跳过**。最终发布验收在这些修正后重新运行。
+- 进程树回收七项新增真实回归先出现四项失败，修正后全部通过；同时验证数值缓冲边界。最终进程/流式/树回收专项 **24/24** 通过，原有严格 200 ms 心跳断言保持，真实诊断确认 taskkill 成功并在返回前回收后代。
+- `30d7472` 全量 489 项：486 通过、1 项流式超时的单字节文件大小变化失败、2 跳过。164 次追加诊断均回收进程且内容稳定，没有复现该单次变化，未据此断言原因。新增探针改为返回后立即检查后代状态并严格比较实际内容，同期输出文件大小，生产实现保持原修复，重新做全量验收。
+- `7fa6178` 的完整本地验收 **489 项：487 通过、0 失败、2 跳过**，175.1 秒；使用 9,804,373 字节、285 个生产包的真实 npm 归档，含离线全局安装、脱离源码运行、中文快捷名与再次导出。生产代码和最后探针补充分别完成独立 Standards / Spec 复审，均无遗留已确认问题。进入已授权的推送与正式发布。
+- 用户随后要求最新 issue #4 的复制入口修正也纳入 0.5.2。首次正式验收 Linux 通过，Windows 两项短路径逐字断言失败，publish 跳过且 npm/Release 未发布。合入列表去重及实际目录身份断言修正，补充独立两轴复审均通过；重新构建 9,806,640 字节、285 个生产包的归档，本地全量 **489 项：487 通过、0 失败、2 跳过**，186.3 秒。核对未发布状态后更新待发布 tag，再执行正式双平台发布验收。
+- 最终提交 `fdb62c1` 的发布流程全部成功：Windows 与 Ubuntu 各 **488/489 通过、1 项平台专用跳过、0 失败**；两平台便携包和无 Node 的断网只读容器通过。npm `latest` 为 **0.5.2**，独立下载 9,806,832 字节公开包，SHA-512 与注册表、SHA-256 与 GitHub Release 均匹配。四个发布附件完整，最新 issue #4 纳入同一版本；后续只提交验收记录，不改变发行产物。