@yanglaofish/fishtools 0.2.0 → 0.3.0

package/manual/docs/research/2026-10-11-plugin-kernel-capabilities.md

@@ -0,0 +1,167 @@
+# 插件内核公共能力研究：会话、执行、Hook 与授权
+
+日期：2026-10-11。状态：研究与设计建议，**不是已实现的接口规范或发布承诺**。
+
+Fishtools 核对基线：`838d572f0eff85f759b3c1118abb9dda616a4113`。
+
+## 1. 来源与研究边界
+
+- 用户提供的 [pengchengneo/Claude-Code](https://github.com/pengchengneo/Claude-Code) 自述为 npm source map 还原的非官方源码，README 声明源码版权归 Anthropic。查询时 GitHub 未识别到许可证；不能按 MIT 组件直接融合。
+- 本次固定读取快照 `b78dd22a091b717c8938ab98c736bc04825a8ee8`。Git 克隆连接失败后，改用 GitHub API 读取关键文件；没有运行该仓库的脚本、依赖或二进制，没有把其代码复制进产品。
+- 官方公开文档用于核对受支持的扩展机制；官方当前文档与还原快照不是同一版本，不能互相证明所有实现细节。
+- 下文“建议”均为 Fishtools 的设计判断；具体 API 名称仍需设计确认。当前可用接口以 [插件开发规范](../plugin-development.md) 为准。
+
+## 2. 值得借鉴的机制
+
+| 观察到的机制 | 源码或官方证据 | 对 Fishtools 的意义 |
+| --- | --- | --- |
+| 工具契约涵盖执行、输入输出、进度、权限与展示 | [Tool.ts](https://github.com/pengchengneo/Claude-Code/blob/b78dd22a091b717c8938ab98c736bc04825a8ee8/src/Tool.ts) | 插件动作除了能调用，还应能被统一展示、取消和审核；不把模型提示词、React 节点放进我们的通用动作契约 |
+| 调用管线串起校验、前置 Hook、权限、执行及后置 Hook | [toolExecution.ts](https://github.com/pengchengneo/Claude-Code/blob/b78dd22a091b717c8938ab98c736bc04825a8ee8/src/services/tools/toolExecution.ts) | 工作流、斜杠命令与未来 Agent 调用同一能力时，应经过同一条受管调用路径 |
+| 会话文件在首条用户/助手消息时才创建，之前缓存元数据 | [sessionStorage.ts](https://github.com/pengchengneo/Claude-Code/blob/b78dd22a091b717c8938ab98c736bc04825a8ee8/src/utils/sessionStorage.ts#L973) | 支持用户提出的空会话不落盘；Fishtools 的触发点应改为首次实质操作，不能照搬聊天消息标准 |
+| 执行任务和观察界面有独立状态 | [task/framework.ts](https://github.com/pengchengneo/Claude-Code/blob/b78dd22a091b717c8938ab98c736bc04825a8ee8/src/utils/task/framework.ts) | 返回菜单不结束运行；日志、主面板及运行详情查看同一执行记录 |
+| 权限有独立决策对象和交互组件 | [permissions.ts](https://github.com/pengchengneo/Claude-Code/blob/b78dd22a091b717c8938ab98c736bc04825a8ee8/src/utils/permissions/permissions.ts)、[PermissionRequest.tsx](https://github.com/pengchengneo/Claude-Code/blob/b78dd22a091b717c8938ab98c736bc04825a8ee8/src/components/permissions/PermissionRequest.tsx) | 判断结果不能只是一行文本；应有带请求 ID、操作范围、理由和有效期的决定，再由界面收集用户选择 |
+| 官方 Mods 提供同进程 JavaScript/TypeScript 扩展 | [Mods overview](https://code.claude.com/docs/en/plugins/mods/overview) | 公开接口也能覆盖命令、界面和执行拦截；同进程扩展仍可直接访问宿主，不构成沙箱 |
+| 官方事件接口区分观察、改写和接管，允许等待用户输入 | [React to events](https://code.claude.com/docs/en/plugins/mods/events) | 借鉴事件契约与异步交互；首版不必开放任意替换执行结果、自动重试或完整接管调用的能力 |
+| 官方 API 将命令、工具和受管资源集中提供；界面文档区分多种状态生命周期 | [Mods API](https://code.claude.com/docs/en/plugins/mods/api)、[UI 与状态](https://code.claude.com/docs/en/plugins/mods/interface) | 分开运行临时数据、会话扩展状态和持久插件数据；由宿主管理交互焦点，避免插件互相抢占终端 |
+
+该快照的权限界面仍有按内置工具对象选择组件的分支。Fishtools 应提供通用展示协议和默认渲染器，避免为第三方插件增加内核分支。源码中出现的隐藏特性不作为我们的产品目标。
+
+## 3. 先明确四个对象
+
+| 对象 | 定义 | 生命周期 |
+| --- | --- | --- |
+| 工作区 Workspace | 工作流、插件配置、会话记录和结果的归属位置 | 跨启动保留；不是权限沙箱 |
+| 会话 Session | 用户这一次连续工作的记录，可含多个工作流和直接插件调用 | 启动产生临时会话；有实际操作才保存；可从历史重新打开 |
+| 执行 Run | 一次工作流或一次独立插件能力调用 | 有独立 ID、状态、输出和日志；固定归属启动它的会话 |
+| 调用 Invocation | Run 内某一步插件调用或嵌套子调用 | 有调用路径、父调用、输入输出、进度及取消信号 |
+
+由此确定入口分工：
+
+- `/history`：查找、打开会话；恢复该会话主面板、执行记录和阅读位置。
+- `/logs`：浏览当前会话内的执行，进一步查看某一步诊断。它是同一批记录的另一种视图。
+- 主面板：按会话连续展示操作与执行摘要；配置菜单只是临时界面，不销毁运行过程。
+- ↑↓：输入命令回溯，和会话历史是不同功能。
+
+恢复历史不等于重跑工作流，也不等于恢复已经退出的 Python/Node 进程。LLM 插件可以恢复自己的对话状态；恢复何种模型上下文由该插件决定。
+
+这也符合官方会话文档对“恢复记录”和“重新运行中断调用”的区分；具体保留策略仍由 Fishtools 自己定义。参见 [恢复会话的范围](https://code.claude.com/docs/en/sessions#what-a-resumed-session-restores)。
+
+## 4. 公共能力清单与当前差距
+
+“部分已有”只表示具备基础实现，不表示新接口已可调用。
+
+| 公共能力 | 当前状态及证据 | 建议补齐的契约 |
+| --- | --- | --- |
+| 插件加载、依赖、生命周期和共享服务 | 已有：[host.js](../../packages/core/src/host.js)、[runtime.js](../../packages/core/src/runtime.js) | 继续使用 Cordis；新增订阅、Hook、面板注册也跟随插件作用域注销 |
+| 动作发现、调用与结果校验 | 已有 catalog、invoke、commands、input/output：[host.js](../../packages/core/src/host.js) | 稳定的第三方调用门面；身份和调用归属由内核赋值，统一经过 Hook/授权/日志 |
+| 顺序、分支、并行、条件停止 | 已有：[engine.js](../../packages/core/src/engine.js) | 沿用现有控制节点和状态，不为 LLM 另造一套编排协议 |
+| 会话与插件状态存储 | 尚无持久会话；[terminal/view.js](../../packages/core/src/terminal/view.js) 的命令历史在内存中 | 延迟落盘、会话索引、恢复、按插件命名空间存储数据和版本；工作区状态与会话状态分开 |
+| 执行记录、日志和用户输出 | 已有 run、events、run.md、log/print：[application.js](../../packages/core/src/application.js)、[run-feed.js](../../packages/core/src/terminal/run-feed.js) | 统一事件版本与顺序号；进度更新、结果摘要、产物引用；历史与实时使用相同渲染输入 |
+| 公共交互与界面扩展 | 插件交互命令已有 input/select/show/confirm：[terminal/session.js](../../packages/core/src/terminal/session.js) | 能力查询、结构化确认/表单/详情；由内核仲裁并发提问和焦点；动作与 Hook 可通过统一请求通道交互 |
+| 执行 Hook | 仅有生命周期回调和运行事件订阅 | 注册前置决策与后置通知；过滤范围、超时、取消、顺序、异常归属和注销契约 |
+| 授权请求、模式和审计 | 尚无统一机制 | 操作与资源范围声明、允许/拒绝/询问/无意见、用户规则与可选决策插件、真实 TUI 请求 |
+| 受管进程与后台工作 | 已有 runProcess、取消/超时、stdout/stderr；运行可在主面板持续显示 | 给受管操作接入权限与调用归属；长期后台任务句柄随后按实际需要增加，不立刻建设新调度系统 |
+| 分发和第三方开发支持 | 已有按工作流依赖打包、平台/环境声明、随包手册与示例 | 每项新契约同步类型、离线说明、仓库外插件示例和接入验收；不能只让内置插件使用 |
+
+当前 [SDK](../../packages/sdk/index.js) 很小，且未作为独立公共 npm SDK 发布。不能把内部存在某个函数等同于第三方已经拥有稳定 API。
+
+## 5. 会话、日志和持久化
+
+以下是把已讨论方向落实为契约的建议：
+
+1. `fst` 启动只产生内存中的临时会话。浏览帮助、插件列表、历史不会制造空记录；直接打开旧会话丢弃这个临时对象。
+2. 第一次请求实际执行时，在可能发生副作用之前保存会话与请求。失败、取消和权限拒绝也有诊断意义。工作流保存/配置修改算作实质操作并记录摘要，是本次建议，仍需确认。
+3. 每个运行在创建时固定 sessionId。用户之后切换历史页面，后台事件仍写回原会话，不能读一个可变的“当前会话”决定归属。
+4. 会话记录引用其全部 Run；事件原始数据只保存一份，主面板、执行详情、Markdown 导出从中构建视图。保留 run.md 方便离线阅读，TUI 不直接展示原始 Markdown 标记。
+5. 建议以整会话为日志保留单位，替代“整个项目最近 10 个 Run”。保留的会话不能被独立 Run 清理掏空；活动会话/执行不参加清理，业务产物仍不随日志自动删除。
+6. 旧记录先兼容读取并标注“旧版执行记录”。迁移先备份、可回退，不在首次启动时直接删除旧文件；保留数量也不静默把 10 次解释成 10 个会话。
+7. 序列化和追加写入是内部持久化方法，用户仍看可读内容。增量写入、崩溃后的末尾损坏处理、多个 fst 同时写入的锁/版本策略都需要明确。
+8. 重启后未正常结束的本地执行显示“中断”，不伪装仍在执行。没有插件明确支持的恢复协议，就只恢复记录。
+
+LLM 插件可以在自身会话命名空间保存消息、模型配置引用、压缩状态。内核只管理归属、读写、版本和清理，不解释 token 或提示词。敏感配置不应随日志和分发包无意传播；日志字段需提供显式隐藏/脱敏声明，不能宣称能识别所有任意文本中的秘密。
+
+## 6. Hook 与权限需要分开
+
+### 6.1 Hook 是执行扩展点
+
+建议先有少量事件族：会话开始/恢复/结束；Run 开始/结束；动作执行前/成功/失败/取消；权限请求/决定。
+
+- 通知 Hook 用于观察、统计、保存插件状态。异常需要记录，不能把已经成功的动作改成“没有执行”。
+- 前置决策 Hook 可阻止或请求确认。声明为必要的决策 Hook 超时/失败时，该操作不能继续冒充已审核。
+- 插件只能注册自己作用域内的 Hook，卸载自动注销；顺序固定并可诊断，不能依赖竞速最先返回的结果。
+- 首版建议不开放任意输入改写/结果替换/自动重试。后续若支持改写，必须重新校验最终输入、重新评估权限并记录差异；后置 Hook 无法撤销已发生的副作用。
+- 事件订阅只是观察通道；不能把目前 `application.subscribe` 更名成 Hook 就算完成执行拦截。
+
+官方存在设置型 Hook 与同进程 Mods 两种机制；Fishtools 先做一种公共 JS 注册契约即可。运行脚本、HTTP 或 LLM 审核可通过插件实现，不必都进入内核。参见 [官方 Hooks](https://code.claude.com/docs/en/hooks) 与 [Mods 事件](https://code.claude.com/docs/en/plugins/mods/events)。
+
+### 6.2 权限是受管操作的决策
+
+建议的受管调用顺序：
+
+```text
+工作流 / 插件命令 / 第三方调用门面
+  → 创建调用身份并记录请求
+  → 校验输入
+  → 执行前决策 Hook
+  → 收集操作范围并进行权限决策
+  → 需要时排队显示交互确认
+  → 执行动作（受管子进程仍检查其具体操作）
+  → 校验输出并记录成功/失败/取消
+  → 后置通知
+```
+
+若前置 Hook 拒绝，也记录拒绝及来源，并走统一收尾。避免一个嵌套调用对相同、已授权范围重复弹窗，但新增路径/参数/目的地必须重新判断。
+
+操作类别从文件读取、写入、删除、进程启动、网络访问等小集合起步；请求包含插件、动作、实际目标、参数、cwd 和目的。插件声明描述自己的操作，**不能据此给自己授予权限**。`rm -f` 只是某种命令表达，不能用几个字符串匹配代替所有删除请求。
+
+规则裁决建议：用户明确拒绝优先；用户明确要求询问的操作不能被普通自动模式绕过；匹配允许范围后执行；其他请求按模式处理。可选审核插件必须由用户选择启用作为决策提供者，不能因安装了一个业务插件就让它审批其他插件。
+
+| 建议模式 | 未命中明确规则时 | 无交互终端时 |
+| --- | --- | --- |
+| 确认 | 展示 TUI 确认 | 返回需要授权的结构化结果，不等待 stdin |
+| 自动 | 本地规则/用户启用的审核插件给出决定；无结论则询问 | 无法完成审批则拒绝此次操作并说明原因 |
+| 宽松 | 自动允许普通受管请求；仍保留明确拒绝和必须询问规则 | 按用户明确选择的同一策略处理 |
+
+这是 Fishtools 的候选语义，**不等同 Claude 的同名模式**。[官方权限模式](https://code.claude.com/docs/en/permission-modes) 用于比较，不逐项照搬。预览执行计划单独提供：显示已知步骤、条件、依赖和权限，未知运行值标记未知；不靠真实执行插件来“预览”。
+
+确认界面应显示操作和范围，提供“允许本次 / 本会话允许此范围 / 拒绝”，以拒绝为安全默认；↑↓、Enter、Esc 可操作。会话授权不会无提示变为永久授权。每条请求有 ID；多步骤并行时由界面依次展示，后台输出继续记录。请求取消或用户切换权限模式后，旧审核结果不得批准已经失效的请求。恢复旧会话不静默恢复过去的宽松授权。
+
+无沙箱的边界保持明确：以上约束公共调用路径。插件直接使用 Node fs、网络或 child_process 可以绕开受管接口。我们不因此限制用户安装谁的插件，也不声称能强制隔离任意插件代码。官方同进程 Mods 文档同样明确了宿主权限访问边界；这是架构条件，不是官方审核要求。
+
+## 7. 展示与交互也必须是公共能力
+
+建议沿用现有 `log` / `print`，补充以下语义而非让每个插件自己控制终端：
+
+| 信息 | 默认展示 | 展开详情/持久化 |
+| --- | --- | --- |
+| 动作状态 | 插件与能力名称、执行中/等待确认/结果、耗时 | 输入输出、调用路径 |
+| 进度 | 更新同一条进度；无百分比时显示阶段 | 保留必要的阶段事件，避免每帧刷一条日志 |
+| log、stdout/stderr | 折叠 | Ctrl+O / 执行详情查看、可滚动 |
+| print | 直接显示，保持调用归属 | 同样可在历史重读 |
+| 错误 | 直接显示原因和所属插件 | 堆栈、退出码、stderr、建议处理信息 |
+| 产物 | 文件/报告名称和位置 | 结构化引用，和日志清理分开 |
+
+声明式表单、选择、确认、结果字段、详情块是第一步；自定义面板/状态栏插槽可以后补。TUI/Web 各有适配器，CLI 无交互时返回明确结果。插件查询当前支持哪些交互，不导入内核私有组件，不直接抢 stdin 或清屏。
+
+默认输出 schema 足以提供基本结果展示，复杂插件再注册可选展示元数据。不把“为每个插件写 React 渲染器”变成接入门槛。审批内容由宿主统一显示，业务插件不自行伪装内核授权面板。
+
+## 8. 内核、插件与暂缓范围
+
+**内核公共服务：** 插件注册与 Cordis 生命周期、动作契约、编排执行、会话/Run/事件归属、日志与产物引用、Hook 调度、权限决策机制、交互请求协议、打包闭包和手册。
+
+**由插件实现：** 环境探测、Python 业务逻辑、LLM 模型与对话循环、LLM 审核提供者、MCP/外部 Agent 适配、SSH/Kubernetes 执行、具体报告和可选界面扩展。
+
+**当前不扩张到：** 不可信代码沙箱、企业组织权限后台、多机内核调度、任意动作自动回滚、崩溃后继续旧进程、全能任意代码审计、复制 Claude 全套前端或隐藏功能。
+
+继续复用已有 Cordis、pi-tui、Execa、Ajv。第三方源码组件仅在明确许可和实际需要下引入；这次研究不增加依赖、不换 UI 框架。
+
+## 9. 建议实施顺序与验收
+
+本节是下一阶段的候选目标，不覆盖已完成里程碑，也不表示用户已批准每个 API 细节。
+
+1. **会话与记录统一。** 实现延迟落盘、history/logs 分工、主面板恢复、会话归属及保留策略。验收：空启动→恢复不产生新文件；一会话多个工作流；失败记录保留；重启阅读原位置；后台事件不串会话；旧日志有备份与迁移回退。
+2. **公共展示与交互。** 补进度/产物/确认请求协议，所有第三方通过公共接口使用。验收：独立插件的 print、log、错误、进度在 Windows/WSL/无 Node 的便携 Linux 包中一致；切菜单不丢记录；并发提问不抢焦点。
+3. **Hook 与权限闭环。** 在统一受管调用处接入前置决策、后置通知、授权和审计。验收：工作流/命令/外部调用行为一致；明确 deny 不被模式覆盖；更改目标重新审批；Hook 超时/取消和无 TTY 可预测；注销后不残留回调。
+4. **第三方扩展验证。** 仓库外做业务插件和审核插件，再用一个最小 LLM/Agent 适配样例验证 catalog、调用、会话状态与交互是否足够。核心中不能出现对该插件 ID 的特殊判断。长期后台任务接口有真实需要时再扩展。
+
+每阶段同步随包离线手册、类型说明和可安装示例；新方法只有在文档、实现和仓库外接入验收一致后才标记为可用。先本地 `fst-preview` 试用，用户确认后再讨论发布。

package/manual/docs/roadmap.md

@@ -4,6 +4,10 @@
 
 ## 当前所处阶段
 
+当前增量：TUI 日志阅读与导航修复，处于**本地试用、待用户体验确认**阶段。首页 F4 进入统一运行记录，支持多个工作流的多次执行；不使用 `/resume`，避免与未来 LLM 会话恢复混淆。实时与历史使用同一阅读面板，默认简洁结果/错误，完整诊断按需查看。试用方式见 README，用户确认前不发布新版本。
+
+后续交互调整：`/workflows` 收纳新建、编辑、保存和可恢复删除；`/config` 配置工具，`/plugin` 管理插件及插件配置，插件名进入二级能力菜单。`/run` 补全工作流，执行过程留在主面板，多任务与配置操作共存；F4/日志页供详细回看。仍为本地试用，未发布。
+
 既有版本已交付顺序编排、第三方插件安装、CLI/TUI/Web、日志和选定工作流自包含导出，随后加入完整便携工具、独立可写工作区、插件斜杠命令、环境声明、共享服务生命周期，以及 Markdown 诊断日志和按项目保留数量。各历史版本的测试和 CI 结果见验收记录。
 
 0.2.0 源码已实现条件分支、步骤执行条件、受限并发、正常提前结束、stdout/stderr 实时日志，以及 TUI/Web 的控制节点编辑和运行观察。本地 Windows 全量 143 项测试、Windows 便携包、WSL 真实 TUI、浏览器及断网 Docker 验收已通过。远端 CI 与 npm/Release 状态见验收记录。
@@ -78,6 +82,7 @@ N1 的历史验收对应提交 `061f0e4`，[Windows / Ubuntu CI](https://github.
 
 ## 文档导航
 
+- 待确认的公共内核演进研究（会话、日志、Hook、权限与界面，不代表已实现）：[研究记录](research/2026-10-11-plugin-kernel-capabilities.md)
 - 使用与安装：`../README.md`
 - 插件当前可用接口：`plugin-development.md`
 - 分发和工作区：`deployment.md`

package/manual/docs/superpowers/plans/2026-10-11-control-observation.md

@@ -56,7 +56,7 @@
 
 - [x] 更新 plugin-development、README、路线图、验收记录；声明约束和示例与代码一致。
 - [x] 运行完整测试、独立审查、Windows/WSL 交互、Docker 与自包含导出验收。
-- [ ] 推送并确认双平台 CI，符合发布门槛后同步 npm/tag/Release。
+- [x] 推送并确认双平台 CI，符合发布门槛后同步 npm/tag/Release。
 
 ## 容易遗漏的验收场景
 

package/manual/docs/superpowers/plans/2026-10-11-public-plugin-fixes.md

@@ -0,0 +1,40 @@
+# 公共插件契约缺陷修复计划
+
+> 执行方式：使用 superpowers:executing-plans 逐项实施，先写失败回归，再修复。完成后独立审查。
+
+**目标：** 修复核心审查确认的三项 P2，让第三方插件遵循公开契约完成进程调用、安装升级和 Web 打包。
+
+**架构：** 保留现有公共接口。进程查找以调用 cwd 为基准；打包按服务声明选择 Web 提供者并计算依赖闭包；schema 编译隔离不同定义的注册表，保留按对象缓存。
+
+**技术：** Node.js、which/execa、Ajv、node:test。
+
+**依据：** docs/plugin-development.md，docs/verification.md 中核心公开接入审查记录，以及用户本轮明确修复要求。
+
+## 约束
+
+- 分支 fix/public-plugin-contracts；仅本地试用，不发布 npm/tag/Release。
+- 不修改 history/logs 产品边界、不迁移用户数据；集成验证用独立临时目录。
+- 官方和第三方 Web 提供者同等处理；未选中但被依赖的插件仍进入闭包。
+
+## 任务与验收
+
+1. `packages/core/src/process.js`、`tests/process.test.js`：先复现相对 executable 与 cwd 不一致；验证含空格目录、相对 PATH、绝对程序、缺失程序、取消和超时。修复只影响查找基准，不修改全局 cwd。
+2. `packages/pack/index.js`、`tests/service-pack.test.js`：外部 Web 插件加传递依赖；验证选中 Web 导出、便携包含/不包含 Web、工作流确实依赖 Web 时保留；生成独立包并实际加载调用服务，缺失提供者仍给明确错误。
+3. `packages/core/src/validation.js`、`tests/application.test.js`：真实安装带 $id 的配置插件、升级、安装无关插件及移除；验证新旧同 ID schema 不串用、嵌套本地 $ref 仍有效、无效值仍拒绝。
+4. 跑相关回归及 Windows/WSL 验证，独立审查修复 diff；更新文档与验收记录，提交本地分支。
+
+## 审查重点
+
+- 相对路径按子进程 cwd 查找，不能通过 process.chdir 影响并发调用。
+- 同一个 $id 在不同插件或升级前后可以有不同约束，不能复用旧版校验器。
+- Web 提供者自身的插件依赖必须递归打包，不能只添加入口插件。
+- includeWeb=false 不得剔除工作流或其他插件真正需要的依赖。
+- 回归失败需来自业务断言，而不是缺少测试资源或语法错误。
+
+## 执行记录
+
+- [x] 三项核心缺陷的五项新增回归先失败后通过，专项 14/14。
+- [x] 补查发现 TUI pack 同类官方 ID 残留；裁定将其纳入 Web 缺陷修复，避免只修后端。新增 TUI 测试复现 TypeError 后通过。
+- [x] 全量 181/181；最后 TUI 与文档 66/66；增强外部导出运行、依赖保留及含空格 cwd 后，进程与服务打包 9/9。
+- [x] WSL 插件安装升级及进程 12/12；增强后的进程 7/7。
+- [x] 独立审查无 P1/P2；非阻断的两项覆盖建议均已补验。文档已同步，保持本地未发布。

package/manual/docs/superpowers/plans/2026-10-11-terminal-hierarchy.md

@@ -0,0 +1,40 @@
+# TUI 命令层级与主面板运行记录实施计划
+
+> 执行方式：当前任务内逐项实现，使用 superpowers:executing-plans 与测试先行。
+
+**目标：** 按用户确认的对象层级组织操作，执行工作流后实时输入输出留在主面板，管理配置不丢失执行过程。
+
+**设计依据：** `/config` 配置 Fishtools；`/workflows` 浏览、创建、进入编辑和删除；`/run 工作流ID` 补全并执行；`/pack` 打包；`/logs` 阅读日志；`/plugin` 管理插件；插件自己的入口进入二级能力菜单。工具操作可合并。一个会话有多次工作流执行。
+
+**技术：** 继续使用 Cordis、Pi TUI、已有 YAML 工作流及运行记录，不新增依赖。Windows/Linux 一致。仅本地试用，未获本轮发布确认前不推送 tag/npm/Release。
+
+## 实现边界
+
+- `terminal/navigation.js`：顶层可发现命令、插件分组及入口生成，内置/插件来源标签。旧命令保留兼容执行，不出现在顶层补全。
+- `terminal/workflow-menu.js`：工作流列表及编辑子菜单，复用已有字段编辑方法。
+- `workflows.js`/`application.js`：删除前拒绝仍被其他流程引用的工作流，移入项目 `.flow/deleted-workflows` 备份目录；不删除执行产物。可从备份复制 YAML 回 workflows 恢复。
+- `terminal/view.js`：主面板保留每次运行的事件与输入输出、滚动阅读；配置菜单不清除运行内容。详细日志继续复用 RunViewer。
+- `terminal/session.js`：运行非阻塞返回主输入区；连接生命周期及退出时取消确认；工具配置与插件配置分开。
+- 工具配置本轮提供已有日志保留设置与工作区信息，不虚构尚未实现的设置。
+
+## 步骤与验收
+
+- [x] 补失败测试：顶层命令与插件分组、/run 补全、配置归属。
+- [x] 实现分层与工作流编辑菜单；补删除备份、引用保护、只读与取消测试。
+- [x] 主面板追踪运行、跨菜单保留、并行多次执行和翻页；补终端尺寸与订阅清理测试。
+- [x] 更新 README、插件规范及试用说明；专项测试和 Windows/WSL 真终端验收。
+
+## 实施记录
+
+- 主面板采用 RunFeed 独立模块保存会话事件；详细运行观察器继续复用。真实执行支持返回输入区后打开菜单或启动另一条工作流。
+- 审查发现监听器累积与整段排列遮挡较早任务的新事件，已改为单个应用订阅和事件顺序追加；管理提示也进入相同顺序。每个缺陷先添加失败测试，再修复。
+- 命令来源为内置/插件，工作流属于操作对象；为兼容已有用法，旧顶层编辑命令保留执行但隐藏默认补全。
+- 保留源文件备份，仅在隔离试用工作区与临时测试目录进行验证；发布仍需用户后续确认。
+
+## 重点检查
+
+- 插件入口名称冲突、动态卸载后命令过期，旧直达命令的兼容性。
+- 工作流编辑取消保留原内容，删除备份可恢复，嵌套子流程引用不能漏检。
+- 运行期间打开配置不结束任务、不清空输出，重复运行可区分。
+- 窄窗口主输入始终可见；普通文本误输入显示输入提示。
+- 主面板滚动不误提交输入；退出清理订阅与终端鼠标模式。

package/manual/docs/superpowers/specs/2026-10-11-collapsed-plugin-output.md

@@ -0,0 +1,23 @@
+# 多插件执行摘要与用户输出
+
+## 目标
+
+同一工作流可以顺序调用不同插件，前一步的结构化输出绑定到后一步输入。默认主面板明确展示每一步的能力、所属插件、调用路径和执行状态，避免用户只能看到最终结果或被技术日志刷屏。
+
+## 展示规则
+
+- 默认折叠：显示步骤执行中、成功、失败、取消、跳过或停止状态。普通输入输出、作者 log、受管子进程 stdout/stderr 收入详情。
+- 主面板 Ctrl+O 切换本次会话所有运行的摘要/详情，不提交或修改输入框草稿。详情可以翻页；管理菜单不清除运行内容。
+- 执行失败直接展示错误摘要。嵌套失败传播不重复打印父节点与根运行的同一错误；完整错误链仍在详情和持久日志中。
+- 插件 `await print(message,data?)` 表示面向用户的内容，折叠时仍实时展示；`await log(...)` 表示诊断内容。两者均落盘，print 在 log 事件上标记 `audience: user`，沿用现有订阅和日志保留机制。
+- 不读取或生成所谓模型内部思考。未来 LLM 插件可用相同接口提供进度说明与诊断摘要。
+
+## 插件契约
+
+动作和交互命令获得相同的 print 能力。Python 等子进程默认写诊断日志；作者希望特定输出直接可见时，在 runProcess 的 onOutput 回调中调用 print。print 不直接写终端控制台，也不允许覆盖执行器固定的步骤归属。旧插件无需改动，仍完整记录 log 和返回值。
+
+## 本地验收
+
+`preview-pipeline` 调用三个不同插件：文本准备示例 → 基础示例转大写 → 报告保存示例。两个新增示例提供可安装目录和 MIT 许可证。文本与演示等待时间可修改，实际写出 report.txt，并通过 print 显示位置。既有试用工作流只在不存在时创建，不覆盖用户修改。
+
+验证跨插件结果传递、运行中的状态变化、Ctrl+O 与输入草稿、折叠时错误和 print 的可见性、完整日志落盘，并验证 Windows/WSL 真实终端。仅交付本地试用，不发布。

package/manual/docs/verification.md

@@ -1,5 +1,56 @@
 # 首版验收记录
 
+## 0.3.0 发布前验证（2026-10-12）
+
+- 以 `v0.2.0` 为基线审查本轮代码和需求；修复离线手册缺失源码链接、并行取消测试时序、主面板密集日志重复全量快照与重绘，以及展开详情缺少完整错误链。
+- Windows 本机使用 Node.js 24.15.0、npm 11.15.0：`npm run build` 成功；`npm test` 为 **184/184 通过**；`npm run dist:npm` 生成 `yanglaofish-fishtools-0.3.0.tgz`。归档内核对了 `package.json` 版本、运行面板代码、离线研究文档及其源码引用。
+- npm 官方注册表在发布前只有 `latest: 0.2.0`，`0.3.0` 尚不存在。跨平台测试、自包含包与 Docker 检查由版本 tag 的发布工作流再次执行；本地通过不代替远端发布结果。
+
+## 合并执行回看入口（2026-10-11，本地试用，未发布）
+
+- 用户再次试用后认为 F4 没有独立价值：主面板查看当前执行，统一通过 `/logs` 回看步骤、输入输出和日志。删除独立运行列表实现，旧 `/runs` 与 F4 仅兼容转入同一入口；界面不再推荐 F4。
+- `/logs` 显示工作流标题，正在运行的任务排在前面；历史持久记录、从详情返回列表、切换其他执行和原有日志保留策略保持可用。
+- 先复现旧实现三个场景失败，修订后 **31/31 通过**：`node --test tests/log-readability.test.js tests/run-logs.test.js tests/terminal-location.test.js tests/terminal-theme.test.js tests/terminal-navigation.test.js`。本节取代下方 F4 与日志双入口设计；未发布、未推送。
+
+## 精简返回反馈与 F4 说明（2026-10-11，本地试用，未发布）
+
+- 用户反馈通用“已返回主面板”消息重复：现在返回只更新顶部位置，保留命令与实际结果，不新增返回记录。下方早期验收中“保留返回提示”的描述由本节取代。
+- F4 标为“运行列表”，首页和列表说明用于选择一次执行，查看步骤、输入输出与日志；`/logs` 使用同一套记录但默认打开日志页。移除试用标记和滚动状态行里的重复 F4 提示。
+- 导航、窄屏、F4 输入草稿保留、历史详情和主面板专项 **25/25 通过**：`node --test tests/terminal-location.test.js tests/terminal-theme.test.js tests/log-readability.test.js tests/terminal-navigation.test.js`。两项返回场景先复现失败再通过。
+- 未发布、未推送，重新启动 `fst-preview.cmd` 使用本地修订；全局 fst 不变。
+
+## 运行草稿与导航反馈（2026-10-11，本地试用，未发布）
+
+- 分支 `fix/run-navigation-feedback`。目标：`/run` 不被编辑草稿阻挡；菜单返回有清楚的去向，命令记录和运行过程始终可回看。
+- 复现：参数页只查看后完成、拒绝删除步骤都曾被无条件标记为未保存；运行拒绝保存后，编辑菜单仍误判为已启动。先补失败测试，再修复真实修改判断及运行返回值。
+- `/run` 选择已保存的工作流，`/run ID` 执行磁盘版本并保留任何草稿。编辑菜单单独提供保存并运行、运行已保存版本、返回编辑；取消留在编辑页，未创建运行。
+- 顶部采用青绿字符标识与产品信息并排，持续显示工作区和当前位置；操作菜单增加分隔和标题。命令、菜单选择、返回主面板提示按顺序保留，本次会话内可翻页；不替代持久化运行日志。
+- 相关测试 **82/82 通过**：`node --test tests/terminal*.test.js tests/log-readability.test.js tests/log-viewer.test.js tests/run-logs.test.js tests/workflows.test.js`。包含新增 6 个草稿/执行场景与 2 个真实组件导航场景。
+- 首次完整 `npm test`：164/167 通过，三个旧 TUI 测试仍按“裸 /run 直接执行”编写，其中等待输入的测试被终止。已调整为指定工作流 ID，上述 82 项复验包含这三个测试且全部通过；未将首次全量结果标记为全绿。npm 归档测试仅使用离线 dry-run，没有发布。
+- Windows 真实 PTY：临时工作区预置脏草稿，裸 `/run` 选择并执行已保存版本，输出 SAVED；编辑菜单运行选择返回后仍留在编辑菜单，草稿保留。WSL 真实 PTY：实时输出、执行中打开配置、返回、并发执行、翻页、插件入口和工作流编辑、退出恢复通过。
+- 已检查真实组件渲染的首页、插件菜单、返回主面板预览；此轮只修改本地源码和本地试用入口，未更新全局 fst、未推送、未打 tag、未发布。
+
+## 对象菜单与主面板运行（2026-10-11，本地试用，未发布）
+
+- 分支 `feat/terminal-command-hierarchy`，试用入口仍为根目录 `fst-preview.cmd` / `npm run preview`。
+- 按用户指定职责分层：`/workflows` 管理与编辑，`/run` 工作流 ID/标题补全，`/plugin` 管理插件，插件名入口选择能力，`/config` 工具设置，`/tools` Web/资料。旧直达命令兼容执行，减少顶层补全数量，来源明确标注。
+- 工作流删除移入 `.flow/deleted-workflows`，保留可复制恢复的 YAML；有嵌套引用或只读项目时拒绝删除。测试只使用临时项目，不删除用户已有数据。
+- 主面板按事件到达顺序保留多次执行、输入输出与管理提示。配置操作不丢执行内容，滚轮/PgUp/PgDn 回看。普通文本误输入改为“输入提示”，移除重复的输入标题并修复小高度溢出。
+- Windows 真 PTY 验证工作流补全、主面板持续 stdout、执行中打开/返回配置、执行完成与正常退出。WSL 100×24 真 PTY 验证持续输出、执行中配置、并发另一个工作流、回看翻页、插件二级菜单、工作流编辑菜单及退出恢复；记录 `.cache/hierarchy-wsl.ansi`。初次脚本在主输入就绪前发键，调整为等待主输入提示后复验通过。
+- 独立审查复现完成任务监听器积累与并发/管理提示遮挡最新输出，均补失败测试后修复：每个应用只保留一个活跃订阅，所有主面板事件统一追加顺序，结束后解除订阅。
+- 本地相关测试 **91/91 通过**，包括导航、主面板、详细日志、编辑、插件契约、控制流、删除引用保护与原有日志保留测试；独立复核中的 9 项导航专项也通过。
+- 此轮未发布、未推送，等待用户本地试用确认；未重复运行完整发行构建或 npm 发布验收。
+
+## 日志阅读与运行记录入口（2026-10-11，本地试用，未发布）
+
+- 分支 `fix/readable-run-logs`。使用 `npm run preview` 或根目录 `fst-preview.cmd`；隔离的 `.cache/log-preview-平台` 工作区提供成功、故意缺少解释器、持续输出三个示例，不升级全局安装或修改用户默认工作区。
+- 首页 F4 打开运行记录；支持多工作流、多次执行，运行中任务优先，详情返回列表，每次运行分别保存本次启动期间的阅读位置。重启可读取持久化记录，不承诺恢复上次进程的滚动位置。
+- 实时和历史共用结构化阅读面板。默认展示结果与错误摘要，按 j 查看原始 JSON 和完整错误链；Enter 查看详情而非关闭。独立终端屏幕避免旧面板与首页混排。
+- 本地专项测试 **51/51 通过**：`log-readability`、`terminal-runs`、`terminal`、`terminal-theme`、`log-viewer`、`run-logs`。覆盖 F4 草稿保留、多运行选择、历史读取、阅读位置、流输出合并、错误摘要、终端清理与已有编辑/日志保留行为。此轮未重新执行完整发行包构建与发布验收。
+- Windows 真实 PTY 已验证首页 F4、历史失败记录、Enter 查看输入输出、q 返回运行列表、Esc 返回首页及正常退出。
+- WSL 真实 100×24 PTY 已验证 F4、历史失败摘要、Enter 详情、实时 stdout、鼠标滚轮暂停跟随、后台继续执行、返回同次阅读位置、切换成功记录、退出取消确认及独立屏幕恢复。证据 `.cache/log-preview-wsl.ansi`；脚本 `.cache/log-preview-pty.py`。首次验证因跨文件系统启动耗时与过早发送按键未完成，调整等待到首页输入就绪后复验通过。
+- 另外检查了真实组件输出生成的 100×24 彩色预览。自动化及终端验证不代替用户体验确认；此轮未创建 tag、npm 版本或 Release，等待用户本地试用反馈。
+
 ## fst 交互终端（2026-10-10，当前入口）
 
 本节取代下方早期 `fish` 默认启动 Web 的记录。产品仍为 Fishtools，命令改为 `fst`：交互终端默认进入 TUI，`fst web` 显式启动 Web，原子子命令继续支持自动化。
@@ -167,6 +218,32 @@ MiB = 1,048,576 字节。以下为本机单次测量，不是性能保证；运
 代码与测试提交 e55075e 的 [Windows / Ubuntu CI](https://github.com/yanglaofish/Fishtools/actions/runs/38053011826) 均通过；Windows 5 分 13 秒、Ubuntu 1 分 27 秒。验收文档归档提交不改变已验证代码。
 # 2026-10-11 TUI 上手体验修正
 
+## 2026-10-11 本地后续验收：跨插件执行摘要与用户输出（未发布）
+
+- 分支 `feat/collapsed-plugin-execution`，基线 `21eea07`。主面板默认展示每一步的插件、动作、状态和耗时；Ctrl+O 展开输入输出与诊断日志。错误及插件 `await print(...)` 输出默认可见，完整事件仍落盘。
+- 新增 `preview-pipeline`：文本准备、转大写、保存报告分别由三个不同插件执行，验证结果逐步传递，输入文本与演示等待时间可调整。通过 `fst-preview.cmd` 启动后执行 `/run preview-pipeline`，仅使用隔离试用工作区。
+- 本地终端、流程、插件契约、日志、进程、诊断和文档相关测试 **119/119** 通过；这不是新一轮完整发行包验收。Windows 与 WSL 真实 PTY 验证参数表、运行中状态、三插件成功、用户输出、Ctrl+O 展开/折叠与正常退出；WSL 另外验证返回配置菜单后继续运行，以及折叠状态直接显示缺失程序错误。
+- 真实 TerminalView 渲染截图检查摘要状态、用户输出和快捷键提示。独立审查未发现 P1/P2 阻断问题，补跑终端相关 **13/13** 通过，并实测嵌套并行失败、交错运行、兄弟取消与子工作流输出绑定失败的显示归属和错误去重。
+- 本轮未发布 npm、tag 或 Release，未升级全局 fst；新增 `print` 契约已在插件手册注明尚未发布。
+
+## 本地后续：核心公开接入审查与命令历史（未发布）
+
+- 以 `bf4b983` 为审查快照，扩大检查插件加载、安装、生命周期、编排、日志及打包公开契约。核心相关测试 55/55 通过；从仓库外临时目录实际执行 CLI 导出手册、安装三个独立插件、重新加载、跨插件传值、print/log 展示与插件命令，链路通过。
+- 审查时确认三项 P2：`runProcess` 相对程序路径不遵循 `cwd`；Web 打包选项限定官方插件 ID；共享 Ajv 重复注册配置 schema 的 `$id`，导致外部插件升级或后续安装失败。后续修复与验收见下节。
+- 分支 `fix/terminal-command-history` 修复主输入缺少命令历史：会话内最多 100 条，连续重复合并，↑/↓ 浏览，回到底部恢复草稿。补全选择优先，多行保留光标移动，参数表单及取消输入不记录，退出后不持久化。
+- 三项新增回归测试先失败后通过，终端相关 61/61 通过；Windows 真实 PTY 验证 `/config` 返回后 ↑ 取回、Enter 再执行。未发布或更新全局安装。
+
+## 公共插件契约三项缺陷修复（本地未发布）
+
+- 分支 `fix/public-plugin-contracts`，基线 `eecba28`。相对程序路径及相对 PATH 以子进程 cwd 查找；不改变进程全局目录。Windows 和 WSL 均验证了含中文、空格目录中的程序调用。
+- Web 打包和 TUI 环境选择按 `services.web` 的实际提供者查找，包含其传递插件依赖。关闭可选 Web 时，工作流或其他插件真正依赖的提供者仍保留。外部安装的第三方 Web 插件已导出，并使用包内 Node 与包内核心在仓库外成功调用服务。
+- 每份 schema 独立编译，保留 WeakMap 缓存，隔离 `$id` 注册。真实 npm 安装回归覆盖带 `$id` 配置的插件首次安装、安装其他插件、移除其他插件、升级、拒绝旧版非法配置、重启与卸载；内部 `$ref` 保留，新旧约束不串用。
+- 新增五项回归断言先失败后通过，专项 14/14；后续发现 TUI 同类官方包名残留，追加失败测试后修复。全量 `npm test` 181/181 通过（194.6 秒）；TUI 修复后终端与文档 66/66 通过。最终增强打包子进程及依赖保留断言后，进程与打包 9/9 通过。
+- WSL 进程与插件安装升级 12/12 通过；随后补强含空格目录用例，WSL 进程专项 7/7 通过。首次 WSL 启动命令因 PATH 含空格发生 shell 解析错误，改用脚本启动后完成验证；不将启动失败计为产品回归。
+- 独立审查未发现 P1/P2 阻断；其建议的含空格 cwd 和普通插件依赖 Web 两项边界已补验。开发手册同步契约说明。本轮未改变 history/logs 语义，未发布、推送或升级全局安装。
+
+## 首次上手体验验收详情（历史）
+
 - 修正首页缺少产品介绍、示例入口以及插件清单不显眼的问题：显示 FISHtools 字符标识、欢迎语、当前工作区、数量和真实工作流示例。
 - `/plugins` 直接列出已有插件，详情展示声明的动作、输入输出、环境、配置及命令；维护模式仍保留说明，仅隐藏不可执行的命令入口。
 - 完整页面按终端高度分配空间；80×24、52×24、40×20 自动化渲染检查覆盖首页和可滚动插件列表。
@@ -185,3 +262,9 @@ MiB = 1,048,576 字节。以下为本机单次测量，不是性能保证；运
 - npm 与便携包包含 `manual/`；`fst docs`、`fst docs plugins`、`fst docs --export <新目录>` 与 TUI `/docs` 均可离线访问。文档测试 **4/4**，验证相对 Markdown 链接、拒绝覆盖、脱离源码定位和再次导出。SDK 尚未独立发布；示例使用标准对象，不依赖内部 SDK 的在线安装。
 - 验收脚本复用旧临时工作区曾被项目归属校验拒绝；脚本现为每次解压生成独立工作区，重新验收通过。没有放宽归属或完整性检查。
 - 本记录为本地验收结果；远端 CI 与 npm/tag/Release 结果在发布完成后追加。
+
+- 提交 `4956cc0` 的 [Windows / Ubuntu 全量 CI](https://github.com/yanglaofish/Fishtools/actions/runs/38075609079) 均通过，各 **143/143**；Windows 6 分 17 秒、Ubuntu 2 分 8 秒。
+
+- `v0.2.0` 的[正式发布验收](https://github.com/yanglaofish/Fishtools/actions/runs/38076094907)中，两平台各 **143/143**、Windows/Linux 自包含包及 Docker 检查全部通过。npm 于北京时间 2026-10-11 02:37 接受上传，随后注册表可见性等待超过五分钟，首次发布任务因此失败，当时尚未完成公开 Release。维护者[只读状态查询](https://github.com/yanglaofish/Fishtools/actions/runs/38077080952)返回 HTTP 200、`validating`；不是鉴权失败，当时不能将此次上传宣称为已可在线安装。随后注册表可见，核对同一归档后重跑原任务的失败步骤完成同步。
+
+- 最终 npm 官方注册表的 `latest` 为 **0.2.0**，版本元数据与已验收归档 SHA-512 完全一致，tarball 可下载；[发布流程](https://github.com/yanglaofish/Fishtools/actions/runs/38076094907)重试后成功。[v0.2.0 Release](https://github.com/yanglaofish/Fishtools/releases/tag/v0.2.0) 已公开于本仓库访问范围，包含 npm `.tgz`、Windows `.zip`、Linux `.tar.gz` 与 `SHA256SUMS`。没有改动 tag 或重复上传不同归档。