@yanglaofish/fishtools 0.5.0 → 0.5.2

package/README.md

@@ -6,7 +6,7 @@
 
 交互终端支持选择能力、配置参数和流程编排；官方 Web 插件默认提供，原子 CLI 子命令用于自动化。三种入口共用应用服务。YAML、依赖锁和版本解析由系统维护，不要求普通用户手写。
 
-0.5.0 增加工作流复制、按工作区/插件/动作设置代理、插件权限预检，以及只重启受影响插件的更新。大量输出落盘、开发重载和隔离文件探测继续可用。发布与验证状态见 [版本记录](manual/docs/releases.md) 和 [验收记录](manual/docs/verification.md)。
+0.5.2 增加 `!` 系统命令透传、常用命令注册、任意插件能力的中文快捷名称，以及 Shift+Enter 多行输入。工作流复制、动作代理、权限预检、大量输出落盘与开发重载继续可用。发布与验证状态见 [版本记录](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.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.2.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,6 +41,8 @@ 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` 新建。
 
 顶部的“位置”显示主面板或当前操作入口，菜单标题显示正在操作的对象。提交的命令、菜单选择与实际操作结果保留在本次会话中；返回时只更新当前位置，不追加通用返回消息，也不清空执行过程。这些导航记录只保留在当前会话。

package/manual/README.md

@@ -6,7 +6,7 @@
 
 交互终端支持选择能力、配置参数和流程编排；官方 Web 插件默认提供，原子 CLI 子命令用于自动化。三种入口共用应用服务。YAML、依赖锁和版本解析由系统维护，不要求普通用户手写。
 
-0.5.0 增加工作流复制、按工作区/插件/动作设置代理、插件权限预检，以及只重启受影响插件的更新。大量输出落盘、开发重载和隔离文件探测继续可用。发布与验证状态见 [版本记录](docs/releases.md) 和 [验收记录](docs/verification.md)。
+0.5.2 增加 `!` 系统命令透传、常用命令注册、任意插件能力的中文快捷名称，以及 Shift+Enter 多行输入。工作流复制、动作代理、权限预检、大量输出落盘与开发重载继续可用。发布与验证状态见 [版本记录](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.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.2.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,6 +41,8 @@ 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` 新建。
 
 顶部的“位置”显示主面板或当前操作入口，菜单标题显示正在操作的对象。提交的命令、菜单选择与实际操作结果保留在本次会话中；返回时只更新当前位置，不追加通用返回消息，也不清空执行过程。这些导航记录只保留在当前会话。

package/manual/docs/deployment.md

@@ -5,7 +5,7 @@
 完整工具支持 npm 安装，目标机器需要 Node.js 24.15.0+ 和 npm：
 
 ```sh
-npm install -g ./yanglaofish-fishtools-0.5.0.tgz
+npm install -g ./yanglaofish-fishtools-0.5.2.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.2.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/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

@@ -468,7 +468,9 @@ 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`，作者应继续使用带插件前缀的命令名。
 

package/manual/docs/releases.md

@@ -2,6 +2,44 @@
 
 产品名称 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.2 命令注册与快捷名称
+
+- TUI 主输入框支持 `!` 后的系统命令，原样保留多行、引号、管道和重定向，纳入运行记录、取消、超时与完整日志。
+- `/commands` 注册、编辑、删除和执行常用命令，自动生成标准动作及简单参数表单，已被工作流引用的注册项受到删除保护。
+- `/shortcuts` 为任意插件动作或命令添加中文快捷名称与默认参数；插件原始命令也支持中文，失效目标明确显示原因。
+- 主输入框及命令编辑框采用 Shift+Enter 换行、Enter 提交，Alt+Enter 备用；粘贴保留换行及缩进。
+- 按 issue #4 收拢工作流复制入口：列表每个工作流只出现一次，选择工作流后在管理页复制，当前未保存参数仍可保存到副本。
+- 注册项保存前备份，防止多个实例覆盖同字段改动；离线包携带所需命令定义与快捷名，可编辑工作区支持再次导出。
+
+工作流格式、SDK_VERSION 和原动作 ID 保持兼容。命令按当前用户权限执行，使用已有代理和权限接口；外部 Shell 与程序由目标机器提供。第一版支持无需交互输入的命令。完整用法见[命令指南](terminal-commands.md)。发布状态以 GitHub Release 和验收记录为准。
+
+## 0.5.1 复核修正
+
+- 动作选择直连时，外部子进程不再重新继承系统代理；所选代理配置也不会被宿主残留变量干扰。
+- 插件更新遇到旧资源或失败的新资源清理失败时，不再重新启动另一份资源；应用明确要求重启。
+- TUI 大型并行或子流程的步骤摘要淘汰后可安全显示，不再读取缺失状态报错。
+  步骤缓存与最终结果、输入、错误均使用 logs 模块的有界预览；完整日志和业务返回值保持完整。
+- 非 root 用户可正常执行会提前退出的工作流，分支、并行和子流程内的 stop 不再引起后续权限误拦。
+  真正到达需要 root 的动作时仍会在执行前阻止。
+
+工作流和插件格式保持兼容。本轮基于 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` 在业务空闲后重启完整进程；网络挂载文件探测在隔离进程中执行并设置超时与资源预算。
@@ -48,7 +86,7 @@
 
 ## 发布入口
 
-**发布前先完成本地试用并取得用户确认。** 自动化测试通过只代表具备试用条件，不代替用户对交互体验的验收。交付本地启动入口、说明改动及测试结果后，等待用户明确确认本轮可以发布，才创建版本 tag、发布 npm 或 GitHub Release。普通修复提交不触发发包。
+**发布前完成代码审查、必要验证，并确认本轮发布已获用户授权。** 用户已明确要求“验证后推送和发包”时，沿用该授权；涉及交互体验的新功能先提供本地试用入口、说明改动及测试结果，自动化测试不代替用户对交互体验的验收。普通修复提交不触发发包。
 
 `npm run preview` / 根目录 `fst-preview.cmd` 继续提供独立源码预览工作区；其运行不会修改全局安装或默认工作区。0.3.0 的对象菜单、主面板运行及公共插件修复已列入本次发布范围。
 
@@ -64,20 +102,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,107 @@
+# 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 做规范与需求的独立双向复核，修正实际问题并验证。
+- [ ] 推送已审查提交；发布 tag 触发 Windows/Ubuntu、便携与断网验收，全部通过后 npm 发布。
+- [ ] 核对注册表版本、完整性和 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，再执行正式双平台发布验收。

package/manual/docs/superpowers/reviews/2026-10-13-0.5.0-followup-review.md

@@ -0,0 +1,70 @@
+# 0.5.0 全代际代码复核与修正
+
+用户要求使用 `code-review` 再次审查并立即修正问题，沿用验证后推送和发包的授权。
+固定基线为 0.4.0 提交 `f5292449afcb28adfa98f19ce6586e0a72846080`，审查版本为
+`d26a0eecc791e50211f8a5cf89c6235413659688`，独立分支 `codex/review-0.5.0-followup`。
+比较命令：`git diff f5292449afcb28adfa98f19ce6586e0a72846080...d26a0eecc791e50211f8a5cf89c6235413659688`。
+
+此范围覆盖 0.4.0 之后的十一模块拆分、完整日志、开发重载、隔离探测、代理、权限、复制删除与定向维护。
+两个独立只读审查分别依据仓库模块规范与已批准设计；没有用测试通过代替代码阅读。
+
+## Standards
+
+原审查报告 2 项，修补复审另确认 1 项，共 3 项，最高 P1；没有确认需要单独处理的新增 code smell。
+
+1. **P1：TUI 主面板在摘要淘汰后崩溃。** 固定版本 `fst-cli/src/terminal/run-feed.js:38/62/78`
+   更新旧步骤时不刷新 Map 顺序。`a.started、b.started、a.succeeded、c.started` 在两条预算下
+   淘汰了 a，但事件窗口仍有 a；渲染读取不存在的 `latest.action` 抛出 TypeError。
+   违反 `docs/kernel-generation.md:41` 与 `fst-cli/README.md:54` 的有界显示和省略状态规则。
+2. **P2：TUI 步骤缓存绕过字节预算。** 同一实现缓存整条事件和 input/output，仅限制条数。
+   50 条约 60 KB 输出会形成约 3 MB 步骤缓存，而事件窗口已限到约 1 MB；历史运行会继续累计。
+   违反 `docs/kernel-generation.md:40` 与 `fst-logs/README.md:36` 的轻量摘要及双预算规则。
+3. **P2：TUI 完成后仍保存完整大结果。** 修补复审通过真实应用确认，动作返回 2 MiB 字符串，
+   core 已释放大结果缓存，磁盘已保存摘要，但主面板 record.output 仍保存 2,097,163 字节，超过 1 MiB 预算。
+   同样违反有界主面板缓存要求；运行输入与错误等字段也应使用 logs 提供的结果投影。
+
+## Spec
+
+原审查报告共 3 项，最高 P1；没有发现明确的无需求范围扩大。
+
+1. **P1：直连子进程重新继承宿主代理。** 固定版本 `fst-platform/src/process.js:37` 使用 Execa
+   默认环境合并，将网络规则已删除的 HTTP_PROXY 等重新引入；Linux 小写变量也可能干扰 profile。
+   违反 `action-network-policy-design.md:42` 的 direct 清理与 profile 注入约定。
+2. **P1：旧 runtime 清理失败仍被重新启动。** `fst-plugin/src/host.js:169/170` 清空生命周期错误后
+   恢复旧作用域。清理抛错而未释放资源时，starts/live 从 1/1 增为 2/2，动作仍可调用。
+   违反 `runtime-maintenance-granularity-design.md:27/29` 的等待清理及半更新不可运行约定。
+3. **P2：提前结束后的 root 动作误判为必经。** `core/src/application.js:309-313` 不传播嵌套分支、
+   并行和子流程的 stop。普通 Linux 用户的流程本应安全停止，却在开始前报权限不足。
+   违反 `plugin-readiness-design.md:11`：可能跳过的动作提示，实际执行前检查。
+
+## 修正与回归
+
+- 代理：增加明确的 `extendEnv` 控制，普通 runProcess 保留默认继承；插件宿主构造完整环境后禁止再次扩展。
+  真实子进程验证 direct、profile、inherit 并发隔离，宿主环境不变；修复前 direct 回归确实失败。
+- runtime：启动错误与清理错误分开记录，只允许清理成功后的启动失败恢复。
+  旧资源或失败的新资源清理失败时，停止恢复，宿主标记不可运行。
+  两个真实生命周期回归修复前都出现二次启动，修复后保持一次；正常配置恢复仍通过。
+- TUI：由 logs 的公开 `/steps` 入口统一提供轻量、按最近更新排序且有双预算的缓存，日志写入器也复用。
+  缺失摘要显示省略提示，保留事件中可查询的错误；主面板不在步骤缓存中复制业务正文。
+  交错步骤与大输出两个回归在修复前分别报 TypeError、越过预算。
+  追加 `/preview` 入口，历史元数据与主面板共用有界结果投影；裁去不使用的步骤快照副本。
+  真实 2 MiB 输入/输出回归在修复前确认主面板超预算，修复后只留摘要；业务 done 与 JSONL run.result 仍保留全文。
+- 权限：嵌套 stop 传播到后续步骤；可能被 stop 取消的并行兄弟也不当作必经。
+  隔离测试进程模拟 Linux UID 1000，验证分支、并行和子流程正常停止，以及真正执行时仍拒绝 root 动作。
+  无条件 root 动作保持启动前拦截；修复前嵌套步骤的 mandatory 断言失败。
+
+## 修补后的独立复审与完整验证
+
+- Spec 独立复审确认 3 项修正符合设计：完整代理环境、清理失败不可恢复、stop 的权限传播；没有遗留或新增阻断问题。
+- Standards 独立复审确认步骤缓存与结果投影都已受限，新 exports、依赖声明和锁文件同步；没有遗留或新增阻断问题。
+- 定向验证覆盖真实子进程、真实插件生命周期、真实 2 MiB 业务结果与完整 JSONL，以及隔离普通用户工作流。
+  每项主修复都先执行失败回归，再修正并通过；不是仅增加会通过的测试。
+- `npm run dist:npm` 成功，0.5.1 本地归档 9,757,761 字节、284 个生产包。
+  使用该实际归档设置 `FISHTOOLS_TEST_NPM_ARCHIVE` 后，完整 `npm test` 382 项：381 通过、0 失败、1 跳过，166.0 秒。
+  跳过项为 Windows 当前无文件 symlink 权限，目录 junction 测试实际执行；离线安装、脱离源码运行与再次导出通过。
+- 发布 tag 与 CLI/package 版本同步检查通过。远端双平台、便携包和 npm 发布结果见[验收记录](../../verification.md)。
+- 发布提交 `1fff499` 的[正式发布流程](https://github.com/yanglaofish/Fishtools/actions/runs/38329427621)全部成功：Windows 382/382、Ubuntu 381/382（1 项平台专用跳过），
+  便携包与断网无 Node 容器通过；0.5.1 已在 npm latest 与 [GitHub Release](https://github.com/yanglaofish/Fishtools/releases/tag/v0.5.1)交付。
+  独立下载公开 npm tarball，SHA-512 与注册表、SHA-256 与 Release 一致。此后只追加验收文档，不改动发行 tag。
+
+汇总：Standards 3 项（最高 P1），Spec 3 项（最高 P1），6 项均已修正；修补复审无剩余阻断问题。

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

@@ -0,0 +1,63 @@
+# 0.5.2 命令注册与快捷名称审查
+
+用户已授权直接实现并在审查验证后推送发包，最后明确要求 Shift+Enter 换行、Enter 提交。
+本轮在 `codex/0.5.2-command-shortcuts` 分支开展，以主分支 `68a84cdb46cdb7f022eb3bf1d77ba478c52970ab` 为固定基线。
+首次审查版本 `f44e8e7c0fdef1407a09093487065c1b98969ab3`，第一次修补复审版本 `977218678613a09beb3c901b638138a16d765398`。
+比较命令：`git diff 68a84cdb46cdb7f022eb3bf1d77ba478c52970ab...HEAD`。
+
+按 code-review 使用两个独立只读审查分别处理 Standards 与 Spec。
+规范来源包括各模块 README、`docs/modules.md` 与代码风格规则；需求来源为
+[设计](../specs/2026-10-13-command-shortcuts-design.md)、[计划](../plans/2026-10-13-command-shortcuts.md)和用户本轮按键要求。
+
+## Standards
+
+确认 3 项，最高 P1。
+
+1. **P1：运行时插件安装漏查命令重名。** core 安装时从未启用 runtime 的候选宿主读取 commands，漏掉运行时插件声明；安装成功后快捷名冲突导致下次启动失败。修正为统一读取静态声明，启动、注册保存、安装都复用同一个收集函数。真实安装失败后，原工作区仍可重启。
+2. **P2：Windows 长脚本超过命令行限制。** PowerShell 的 UTF-16/Base64 传输让约 13 KiB 文本就超过 Windows 参数长度限制。增加 `runShell`，把唯一临时脚本写入输出目录，用受管进程执行并在结束后删除；PowerShell 文件带 UTF-8 BOM，POSIX 使用原文。真实 64 KiB 脚本、取消、超时和清理覆盖通过。
+3. **P2：参数表单等待后仍可执行其他插件的同名命令。** TUI 首次检查快捷名身份后，表单和权限确认有异步等待，最后只按命令名称启动。修正为等待结束后再检查 command/plugin，并把 expectedPlugin 传给 core 在实际调用前再次检查。目标已移除时也明确失败。
+
+初审判断性 possible Duplicated Code：多处命令声明收集逻辑产生差异。已统一为 `declaredCommands`；不作为独立硬违规计数。
+
+## Spec
+
+确认 3 项，最高 P2；未发现其他已确认的范围扩大。
+
+1. **P2：旧命令快捷名被新插件同名能力接管。** 原配置只保存 command 名称，原插件卸载后另一插件可接管入口，违反稳定目标身份与失效引用约定。配置、展示、运行和导出同时使用 command/plugin 匹配；同插件升级仍保持有效，不同插件同名入口不可执行。
+2. **P2：跨实例旧工作流草稿能保存已删除命令。** 删除只检查已落盘工作流，另一实例随后保存或复制旧草稿会产生悬空引用。保存和复制现在在变更锁内核对最新项目注册项，覆盖 branch/parallel；已存在的其他插件缺失引用仍允许用户修复或删除。
+3. **P2：保存无关设置会自动启用未绑定的旧命令别名。** 整组保存时给所有 command 项补齐提供者，删除另一别名或编辑无关注册项都会启用旧导入项，违反“需重新选择目标”的设计。绑定函数现在接收 previous，只对明确的新目标补齐；旧未绑定项修改默认输入、重命名仍失效，界面重新选择或明确提供 plugin 后才恢复。
+
+## 补充验证发现与修正
+
+- 编辑命令和快捷名称时保留已有默认 input；真实菜单回归先失败再修正。
+- 命令脚本更新通过摘要纳入插件变更检测，修复另一实例修改脚本后安装无关插件仍使用旧闭包的问题。
+- 全量测试发现缓冲输出超限后后代仍写文件。真实诊断确认 Execa 先关闭输出管道，父进程因 EPIPE 提前退出，taskkill 找不到父 PID 而留下后代。平台关闭 Execa 的内部缓冲，自行有限收集字节；停止期间排空并丢弃输出，等待整棵树回收。stream 模式也避免提前关闭管道。保留原严格心跳断言，新增独立后代进程回归，未放宽断言。
+- 三个追加身份回归先全部失败，修正后应用、TUI、快捷名及既有终端专项 74 项：73 通过、0 失败、1 项 POSIX 专用跳过。
+- `maxBuffer` 明确接受非负数值（含 0 和 Infinity），拒绝对象、NaN、负数等，避免切换为平台缓冲后无意绕过上限；对应两项边界回归通过。
+- 原进程、流式进程及新树回收专项 **24/24** 通过；同一诊断脚本修复后 taskkill 成功、返回时后代已退出，心跳没有继续增长。
+- 随后全量 489 项中流式超时出现一次文件大小增加 1 字节。164 次 CPU/文件 I/O 并发诊断均未复现，实际内容保持稳定；不能认定原因是元信息延迟或异步终止。增强探针在返回后立即检查后代状态、严格比较前后内容，并同时记录大小，生产实现不再根据未验证假设修改。Windows 内核 pending I/O 的严格等待不在本次能力承诺内。
+
+## 最终复审与发布验收
+
+生产代码最终复审范围为固定基线至 `30d7472a36f342ac45b2e010a499182612a92a0a`，Standards 与 Spec 均通过，无遗留已确认问题。
+随后对 `7fa617814bb7fcfa70c3a76e959beda0f9e9dfbc` 的探针与记录改动分别复审，两轴均通过，生产代码未变；没有把未复现的文件大小变化认定为已查明原因。
+
+`npm run dist:npm` 成功；本地真实 npm 归档为 9,804,373 字节、285 个生产包。
+指定该归档后完整 `npm test` **489 项：487 通过、0 失败、2 跳过**，175.1 秒。
+跳过项分别为 POSIX 保存失败注入及本机未开放权限的文件符号链接；目录 junction 仍执行。
+原严格心跳断言和新增进程状态、实际内容检查均通过。正式双平台与发布结果记录在[验收记录](../../verification.md)。
+
+汇总：Standards 3 项（最高 P1），Spec 3 项（最高 P2），六项已修正；最终独立复审均通过。
+
+## Issue #4 与首次双平台验收补充
+
+用户明确要求把最新复制入口反馈合入 0.5.2。新增固定范围 `8223bad...c567534` 的独立 Standards 与 Spec 复审均通过，新增确认问题均为 0。
+TUI 列表每个工作流只枚举一次，选择后进入管理页复制；原版、未保存参数、只读限制及副本打开行为保持。
+
+首次正式 Windows 验收两项 cwd 断言失败，实际目录为 `runneradmin`，测试字面路径为 `RUNNER~1`；生产运行目录没有改变。
+真实短路径诊断复现 `C:\PROGRA~1` 展开为 `C:\Program Files`，两者 `realpath` 相同；测试现在严格比较实际目录身份。
+相关专项 **51 项：50 通过、0 失败、1 POSIX 跳过**；复制、导航、草稿、CLI 与存储专项 **26/26**。
+首次发布任务被跳过，npm 0.5.2 与 GitHub Release 尚不存在；保留失败记录，再次构建与验收合入后的 0.5.2。
+
+合入后重新构建的本地 npm 归档为 **9,806,640 字节、285 个生产包**；指定该归档完整验收 **489 项：487 通过、0 失败、2 跳过**，186.3 秒。
+待发布 tag 更新前再次核对注册表无该版本、仓库无该 Release，以及旧 tag 对象，避免覆盖已发布版本。

package/manual/docs/superpowers/specs/2026-10-12-workflow-variation-design.md

@@ -10,7 +10,7 @@
 
 新文件使用排他创建，发现同名文件立即拒绝，不能通过现有可覆盖的 `save()` 写入。写入失败只清理本次尚未成功创建的新文件，不能触碰来源。返回完整的新定义及路径。只读运行包拒绝复制。`core.app.duplicateWorkflow` 是唯一应用层入口，并对输出的新工作流再次执行结构校验；复制后的正常编辑沿用现有保存接口。
 
-TUI 的工作流编辑菜单加入“复制为新工作流”。该操作以屏幕当前草稿为来源，询问新名称，成功后打开已保存副本继续编辑；复制之前的未保存修改不会写回原文件。工作流列表也能直接复制已保存版本。CLI 增加 `fst workflow duplicate <source> --title <name> [--id <id>]`，Web 工作流列表和编辑器提供相同操作，编辑器的未保存内容也可另存为副本。界面在切换后清楚显示新 ID 和原工作流仍在。
+TUI 的工作流编辑菜单加入“复制为新工作流”。该操作以屏幕当前草稿为来源，询问新名称，成功后打开已保存副本继续编辑；复制之前的未保存修改不会写回原文件。依据 2026-10-13 的 [issue #4](https://github.com/yanglaofish/Fishtools/issues/4) 评论修正入口：工作流列表每个工作流仅出现一次，选择工作流后在管理页提供复制选项，不再为每个工作流额外枚举一条复制入口。CLI 增加 `fst workflow duplicate <source> --title <name> [--id <id>]`，Web 工作流列表和编辑器提供相同操作，编辑器的未保存内容也可另存为副本。界面在切换后清楚显示新 ID 和原工作流仍在。
 
 ## 连续运行与结果
 

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

@@ -0,0 +1,56 @@
+# 0.5.2 终端命令与快捷名称设计
+
+## 目标与授权
+
+用户希望临时执行系统命令，也能把常用命令注册为可编排动作；任意插件动作和已有插件命令都能拥有用户自定义的中文快捷名称。长命令允许多行编辑，主输入框和注册对话框统一为 **Shift+Enter 换行、Enter 提交**，提供 Alt+Enter 备用换行，并明确显示提示。
+
+本设计承接用户 2026-10-13 的“可以，那就是 5.2 的目标”及之前直接编码、审查验证后推送发包的授权。产品目标为 **0.5.2**，不因为本轮增加功能改为 0.6.0。保持原有工作流格式、插件 ID、动作 ID 和 SDK_VERSION。
+
+## 职责
+
+- CLI 接受 `!` 后的原始命令文本，保留换行、引号、管道和重定向；不经斜杠命令分词器重新组装。
+- platform 将完整文本交给明确选择的 Shell。默认 Windows 为 PowerShell，Linux 为 sh，可显式选 powershell、pwsh、sh、bash。仍通过既有受管进程接口执行。
+- 官方 `@mytools/commands` 插件提供轻量命令动作，复用权限、代理、取消与完整日志。core 将工作区注册项装配为这个插件的稳定动作；不另建工作流执行器。
+- workspace 提供快捷名校验和引用状态；core 保存项目设置并协调定向更新；TUI 提供注册、编辑、删除与快捷名管理。
+- 插件作者仍负责业务解析，通用命令默认返回文本，不猜测 IP 等业务字段。
+
+## 数据与接口
+
+`flow.project.json` 可增加 `commandPresets`、`shortcuts`，默认均为 `{}`。示例：
+
+```json
+{
+  "commandPresets": {
+    "local-ip": {"title":"查看本机IP","script":"ifconfig","shell":"auto"}
+  },
+  "shortcuts": {
+    "查看本机IP": {"action":"@mytools/commands:local-ip"},
+    "问候": {"command":"demo.greet","plugin":"my-demo-plugin"}
+  }
+}
+```
+
+命令注册 ID 使用稳定 ASCII 标识；标题和快捷名称可以中文。注册项包含 title、script、shell、可选 timeout 与 parameters。参数是简单字段声明（string/number/boolean，标题、默认值与是否必填），自动生成 schema，并通过 `FST_INPUT_字段名` 环境变量传递，避免把参数拼进 Shell 源码。Linux 脚本使用 `$FST_INPUT_name`，PowerShell 使用 `$env:FST_INPUT_name`。root 需求可显式声明，沿用执行前预检；不会自动提权。
+
+动作 ID 为 `@mytools/commands:注册ID`；输入默认空对象，输出固定包含 exitCode、stdout、stderr、outputBytes、outputTruncated。stdout/stderr 为有界尾部，完整输出落盘。非零退出默认抛出明确执行错误，停止所在工作流；不把失败伪装为成功。Shell 解释器缺失、超时和取消保持原有错误语义。
+
+快捷名称仅改用户入口，不修改 npm 包名或原有动作 ID。支持 Unicode 字母开头，后续可含字母、数字、下划线、点、连字符；拒绝空白、斜杠、控制符、内置入口和已有命令冲突。原插件 `commands` 同步支持中文名称。快捷目标选择 action 或 command 之一，可保存固定输入默认值；命令目标同时保存 plugin，锁定提供者身份，同一插件升级保持入口。用户明确配置时 API 可自动补齐该标识；未绑定的手工导入项需重新选择目标。失效引用继续显示原因，不静默删除，也不执行其他同名能力。
+
+## 操作
+
+- 主输入框 `!echo hello` 或多行 `!` 命令启动受管运行，输出和状态出现在主面板，`/logs` 回看完整内容。使用工作区目录和当前用户权限，继承工作区代理规则。
+- `/commands` 管理轻量命令：新建、编辑、删除、直接运行。新建只要求名称、命令文本，Shell 默认按系统选择；高级设置提供超时、参数和 Linux root 需求。
+- `/shortcuts` 管理快捷名称：目标从任意已加载动作或插件命令选择，可编辑默认输入和删除别名。别名出现在 `/` 补全中，运行时复用原动作或命令输入表单。
+- 修改注册项保持动作 ID；删除被已保存工作流引用的注册项时列出引用并拒绝，先调整工作流再删除。别名删除不卸载插件。
+- 输入框支持软换行和真实多行粘贴；Shift+Enter/Alt+Enter 添加换行，Enter 提交全部内容。命令编辑输入框展示实际按键提示，窄屏长内容也不越界。
+- 第一版运行非交互命令；需要 stdin 或全屏终端的程序不承诺终端接管。
+
+## 持久化与导出
+
+修改前备份项目原文件到 `.flow/backups/`。使用既有项目变更锁、同字段冲突检查、临时文件原子替换；保留其他实例刚更新的无关设置。涉及动作更新时先验证候选宿主，运行期间拒绝修改；落盘失败恢复旧定义，恢复失败要求重启。
+
+导出携带所需命令注册项及所选插件相关快捷名。官方命令插件作为标准包进入闭包，离线运行和再次导出可重新装配。外部程序仍由目标机器提供；定义不假装包含系统命令或解释器。只读运行包可执行，但不能修改注册项或别名。
+
+## 验收
+
+覆盖真实 Shell 内置命令、多行、管道、引号、中文输出、非零退出、取消、超时；大输出完整落盘而内存摘要有界。覆盖任意动作和命令的中文别名、重名拒绝、失效目标、固定输入及运行日志。覆盖修改/删除备份、并发冲突与保存失败恢复、工作流引用删除保护、打包后注册项与别名仍可使用。Windows 和 Ubuntu 全量验证通过后集中发布 0.5.2。

package/manual/docs/superpowers/specs/2026-10-13-issue-4-workflow-menu.md

@@ -0,0 +1,28 @@
+# Issue #4：工作流复制入口
+
+## 问题核对
+
+[Issue #4「复制太奇怪了」](https://github.com/yanglaofish/Fishtools/issues/4)的[完整评论](https://github.com/yanglaofish/Fishtools/issues/4#issuecomment-6139946691)要求进入工作流后的管理页增加复制选项，而非在列表中枚举复制入口。
+对应源码确实对全部工作流再生成一组 `duplicate:<id>` 行；管理页本来已经有复制选项，因此每增加一个工作流就多一条重复入口。
+问题成立，采纳该评论。判断依据是已读取的评论与对应源码；独立图片访问返回 404，没有据此推断截图中的其他问题。
+
+## 修改范围
+
+- 工作流列表每个工作流只出现一次，继续保留新建、草稿与返回入口。
+- 选择工作流后进入原管理页，在那里执行“复制为新工作流”。
+- 复制已保存版本与当前未保存参数均保留，成功后打开已保存副本，原版不被覆盖。
+- 只读项目继续隐藏复制操作。
+
+## 验证与发布安排
+
+固定基线为 `8223bad9eab8ca51fd4c44b89da545e812e60790`；在 `codex/issue-4-workflow-menu` 独立分支修正。
+已有真实菜单集成测试先因重复复制入口失败，再修正列表；验证多工作流枚举、进入管理页复制、草稿和只读行为。
+
+用户随后明确要求把修正合入 0.5.2。旧 tag 对应的正式验收已经结束：Linux 全部通过，Windows 因两项短路径逐字比较断言失败；发布任务被跳过，npm 0.5.2 与 GitHub Release 均不存在。
+核对该未发布状态后，将复制入口与路径身份断言修正一起纳入 0.5.2，重新构建归档和验收；更新待发布 tag 时核对旧对象，保留首次失败的流程记录，不覆盖任何已发布版本。
+
+Windows 路径诊断使用 `C:\PROGRA~1` 实际执行，Shell 输出 `C:\Program Files`，两者经 `realpath` 核对为同一目录。
+两项 cwd 测试改为比较实际目录身份，仍然要求命令在目标目录执行，生产 Shell 实现不因这个测试误判而变更。
+
+补充范围 `8223bad...c567534` 的独立 Standards 与 Spec 复审均通过，新增确认问题均为 0。
+合入后的真实 npm 归档为 9,806,640 字节、285 个生产包；完整本地验收 489 项：487 通过、0 失败、2 跳过，186.3 秒。

package/manual/docs/terminal-commands.md

@@ -0,0 +1,64 @@
+# 系统命令、常用命令与快捷名称
+
+## 临时执行命令
+
+在 TUI 主输入框输入 `!` 后接完整命令，例如 `!echo hello`。运行结果留在主面板，`/logs` 可查看完整日志及取消运行。命令使用当前工作区目录、当前用户权限和工作区默认代理规则。默认 30 秒超时；长任务可注册为常用命令后调整超时时间。
+
+Windows 默认使用 Windows PowerShell，Linux 默认使用 sh。命令按照所选 Shell 的语法解释；管道、引号、重定向和换行保持原样。此入口适合无需交互输入的命令，暂不接管需要 stdin 或全屏界面的程序。
+
+## 多行编辑
+
+| 按键 | 行为 |
+| --- | --- |
+| Shift+Enter | 插入换行 |
+| Alt+Enter | 插入换行，作为终端兼容备用 |
+| Enter | 提交全部内容；补全菜单打开时先确认补全 |
+| Ctrl+C / Esc | 取消当前编辑 |
+
+以上规则适用于主输入框和常用命令文本编辑框。长行会按窗口宽度显示，粘贴多行时保留换行、缩进和制表符。末尾反斜杠也不会改变 Enter 的提交行为。部分终端把 Shift+Enter 编码成普通 Enter，应用无法识别，此时改用 Alt+Enter。
+
+例如 Linux 下可输入以下内容，使用 Shift+Enter 换行，完成后按 Enter：
+
+```sh
+!curl 'https://example.com' \
+  -H 'Accept: application/json' \
+  --max-time 10
+```
+
+Windows PowerShell 请使用其续行符反引号或括号语法，也可粘贴完整的多行脚本。
+
+## 注册常用命令
+
+输入 `/commands` → **注册常用命令**，填写名称和命令文本，选择保存即可。名称合法时自动建立同名快捷入口。例如 Linux 中注册“查看本机IP”，文本填 `ifconfig`，以后输入 `/查看本机IP` 就能运行。目标机器需已经安装 `ifconfig`；也可注册机器实际具备的 `ip address` 或 Windows `ipconfig`。
+
+高级设置可选择 Shell、超时时间、参数及 Linux root 权限要求。超时时间为秒，`0` 表示不限时。root 需求会在执行前检查，工具不会自动提权。修改命令仍保留原有动作 ID，已保存工作流继续引用它；被工作流使用的命令不能直接删除，需先调整引用。
+
+不填写参数时无需编写输入 schema，也不会弹出空 JSON 输入框。需要参数时添加简单字段（文本、数字、是/否，可设置默认值及必填），脚本通过环境变量读取：
+
+```sh
+# Linux sh/bash，参数名为 name
+printf '%s\n' "$FST_INPUT_name"
+```
+
+```powershell
+# PowerShell，参数名为 name
+Write-Output $env:FST_INPUT_name
+```
+
+字段值不会拼入脚本源码；引用环境变量仍应遵循 Shell 的引号规则。通用命令输出包含 `exitCode`、`stdout`、`stderr`、`outputBytes`、`outputTruncated`，可以通过工作流表单传给后续步骤。stdout/stderr 各保留最多 64 KiB 的尾部摘要，完整输出持续落盘；非零退出使动作失败。如果需要把文本解析成业务字段，例如 IP 地址数组，应由业务插件实现。
+
+## 给已有插件设置快捷名称
+
+输入 `/shortcuts` → **添加快捷名称**，填写中文或英文名称，从已加载的任意动作或插件命令中选择目标。可设置默认参数；参数尚未填写完整时，运行会打开原能力的输入表单。
+
+快捷名出现在 `/` 补全中。名称允许 Unicode 字母开头，后续可包含字母、数字、下划线、点和短横线；不能包含空格、斜杠、控制字符，也不能与内置入口或插件原始命令重名。npm 包名及动作 ID 继续使用稳定标识，快捷名称可以随时改。
+
+卸载目标插件或删除注册动作后，相关快捷名标为失效，显示原因；不会误执行其他插件的同名能力。同一插件升级可以继续使用。删除快捷名只删除这个入口，插件和工作流不受影响。权限预检及动作级代理继续按原能力的规则执行。
+
+## 保存与离线使用
+
+常用命令和快捷名称保存在 `flow.project.json` 的 `commandPresets`、`shortcuts` 字段。修改前原文件备份到 `.flow/backups/`，同一字段被其他实例改动时拒绝覆盖并提示重新打开工作区。
+
+命令快捷项由界面同时保存 `command` 与目标 `plugin` 标识，以免同名能力接管入口；填写参数和确认权限后，执行前再次核对提供者身份。配置 API 可为新建或改变目标的快捷名补齐当前提供者；手工导入却未提供 `plugin` 的旧项需重新选择目标，修改名称、默认参数或保存其他设置都不会顺带启用它。保存或复制工作流草稿时也会核对最新注册项，避免另一实例删除命令后保存悬空引用。
+
+导出选定工作流时携带其使用的命令定义和相关快捷名称；便携工作台携带全部注册能力。导出后的可编辑工作区可修改并再次导出；只读运行包可以执行，不能修改。外部程序和 Shell 需由目标机器提供，不会因为注册命令就把它们包含在包内。