@yanglaofish/fishtools 0.1.4 → 0.3.0

package/manual/docs/roadmap.md

@@ -0,0 +1,90 @@
+# Fishtools 路线图与当前状态
+
+更新：2026-10-11，条件控制与运行观察阶段。本文是当前状态入口；早期设计和实施计划保留历史背景，发生冲突时以最新明确决策及验收记录为准。
+
+## 当前所处阶段
+
+当前增量：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 状态见验收记录。
+
+“首版功能闭环完成”不表示插件生态基础设施、所有目标系统和硬件验证均已完成。Cordis 承担服务依赖激活，适配层负责受管异步初始化与清理；第三方开发工具化仍是后续方向。
+
+## 原始实施计划：六项任务
+
+编号对应 `superpowers/plans/2026-10-09-workflow-mvp.md` 的 Task 1—6；原始设计第 10 节另有六步验证顺序，不是额外的六个版本里程碑。
+
+| 原始任务 | 当前状态 | 证据与剩余范围 |
+| --- | --- | --- |
+| 1. SDK、Host、工作流模型与执行 | 首版完成，已扩展服务管理 | `packages/sdk`、`core/src/host.js`、`runtime.js`、`engine.js`、`workflows.js`；动作/子流程、引用校验、失败停止、共享服务与受管清理 |
+| 2. 应用服务、CLI、外部插件 | 首版完成 | `application.js`、`plugins.js`、`process.js`；安装、配置、日志、取消及仓库外插件接入 |
+| 3. 官方环境检查和示例 | 首版完成，硬件验证有缺口 | `plugins/environment`、`plugins/examples`；真实 NPU 验证未完成 |
+| 4. 自包含分发 | 首版完成，已扩展 | `packages/pack`；按工作流依赖收集、Windows/Linux 包、Docker 挂载；现默认完整可编辑工具 |
+| 5. 官方离线 Web 工作台 | 首版完成，已优化易用性 | `plugins/web`；能力目录、顺序列表、表单、保存运行与导出；没有独立的完整历史检索界面 |
+| 6. 文档、跨平台验证与交付 | 按版本持续验收 | `verification.md`；历史本地、WSL、断网 Docker 与 CI 按对应提交记录，本轮控制流增量另行验收 |
+
+## 后续已完成的增量
+
+| 增量 | 状态 | 记录 |
+| --- | --- | --- |
+| 首次使用体验与窄屏 Web | 已交付 | `plans/2026-10-10-workbench-ui.md`、验收记录 |
+| `fst` TUI，斜杠、方向键、文件补全 | 已交付 | `superpowers/plans/2026-10-10-fst-terminal.md`；提交 bdd9cdf 的双平台 CI 成功 |
+| 分层便携工具、可编辑导出、内部 npm | 已交付 | `superpowers/specs/2026-10-10-portable-plugin-contract.md` |
+| 插件命令、平台声明、环境来源与资源选择 | 已交付 | 同上，`plugin-development.md` |
+| Markdown 诊断日志、TUI 历史阅读、按项目保留 N 次 | 已交付，77 项测试及双平台 CI 通过 | `superpowers/specs/2026-10-10-run-logs.md`，CI 见验收记录 |
+
+日志阶段的代码/测试提交：`e55075e`，[Windows 与 Ubuntu CI](https://github.com/yanglaofish/Fishtools/actions/runs/38053011826) 均成功。服务阶段的测试与对应 CI 单独记录在 `verification.md`。
+
+## 0.2.0 增量：本地验收通过
+
+依据 [控制流与运行观察规范](superpowers/specs/2026-10-11-control-observation.md)，当前实现包括：
+
+| 范围 | 当前源码行为 | 本轮状态 |
+| --- | --- | --- |
+| 控制流 | 保留 schemaVersion 1；增加 when、branch、parallel、stop，递归校验作用域和依赖闭包 | 本地验收通过 |
+| 插件契约 | 编排动作显式声明有效 input/output schema；可选 conditions 预设引用已声明输出字段 | 输入输出契约与旧顺序流程验证通过 |
+| 环境检查 | 原 check 未通过仍抛错；新增 report 返回 ok:false，由工作流决定后续处理 | 已实现，真实 NPU 验证仍未完成 |
+| 运行记录 | stdout/stderr 按 UTF-8 流式记录并归属到 callPath；stopped 保存原因且无 error，CLI 正常退出 | 本地验收通过 |
+| TUI | 表单编辑控制节点；/runs 切换总览、输入输出、实时日志，键盘/滚轮浏览，关闭面板后继续运行 | Windows / WSL 交互验收通过 |
+| Web | 控制节点与执行条件表单；按调用路径观察结果和日志、暂停/恢复跟随、显式取消 | 1440 / 390 宽度真实浏览器验收通过 |
+
+观察与取消的边界已明确：TUI 面板内 Esc/q/Enter/Ctrl+C 只关闭，x 后按 y 确认取消；Web 关闭观察窗口不停止任务，“停止运行”发送取消。退出整个 TUI 应用时若仍有任务，需要确认取消后退出。已完成记录继续通过 /logs 与运行日志文件阅读。
+
+尚未承诺暂停/恢复、持久化断点、多机执行或自动回滚。并行任务需要响应取消信号，插件仍对自身业务副作用与资源并发安全负责。
+
+## 当前有效决策
+
+- 名称 Fishtools，命令 `fst`；交互终端无参数启动 TUI，`fst web` 启动官方 Web。
+- 保留 Cordis。Fishtools 保留工作流、元数据、输入输出契约和打包职责，逐步把共享服务依赖与受管资源生命周期落实到 Cordis。
+- 插件的平台与架构由作者声明，核心不据此禁止加载、调用或跨目标打包，也不审核业务逻辑的平台正确性。
+- Node 始终自包含；完整便携工具含内部 npm。Python 等按声明使用宿主或作者准备的随包资源；核心不自动探测、下载或构建 Python。
+- 默认导出支持编辑与安装插件，数据放独立工作区；`--read-only` 选择精简执行包。
+- 每一层步骤按列表顺序执行；需要独立并发时显式添加并行组，条件分支和提前结束由工作流决定。TUI/Web 使用表单维护同一协议及引用。
+- 正常返回并通过输出校验即动作执行成功；业务检查字段与可选判定预设交由工作流使用。正常提前结束为 stopped，用户取消为 cancelled，异常为 failed。
+
+## 演进阶段：按依赖顺序推进
+
+以下是本次整理的新阶段编号，不能当作原始计划中已经承诺完成的功能。
+
+| 阶段 | 目标 | 当前成熟度 | 完成条件 |
+| --- | --- | --- | --- |
+| N1. Cordis 服务与生命周期 | 插件之间共享能力、依赖就绪、关闭清理与失败定位 | 已实现，本地与便携包验收通过 | 提供者/消费者示例、61 项测试、维护模式、Web 资源归属；远端 CI 见验收记录 |
+| 控制流与运行观察增量 | 条件、并行、提前结束、实时子进程日志和双界面观察 | 当前源码本地验收通过，未声明发布 | 控制协议、取消首因、递归依赖、真实界面操作及 Windows/Linux 验收与发布记录 |
+| N2. 第三方开发体验 | 可独立使用的模板、类型提示、示例和接入契约测试 | 离线手册随包、/docs 阅读与导出、零依赖示例已完成；脚手架与 lint 未完成 | 仓库外作者仅按文档完成动作插件、服务插件与打包；契约检查不承担业务平台认证 |
+| N3. 真实业务插件验证 | 用实际业务检验服务契约，例如 SSH 连接与远程检查共享 | 候选方向，具体插件待实际需求确定 | 两个独立插件复用同一服务，包含取消、错误、关闭与离线分发测试 |
+| N4. 按需求扩展 | LLM/外部 Agent、Kubernetes、多机能力等 | 方向记录，未作实施承诺 | 每个扩展单独明确场景、接口和验收，不进入核心的默认依赖 |
+
+N1 的历史验收对应提交 `061f0e4`，[Windows / Ubuntu CI](https://github.com/yanglaofish/Fishtools/actions/runs/38055698922) 均成功，不能替代当前控制流增量的验收。细化见 [Cordis 服务与生命周期设计](superpowers/specs/2026-10-10-cordis-services-design.md)。源码监听热更新、运行中无缝升级、插件市场、Alpine/ARM 不在本轮控制流增量范围内。
+
+## 文档导航
+
+- 待确认的公共内核演进研究（会话、日志、Hook、权限与界面，不代表已实现）：[研究记录](research/2026-10-11-plugin-kernel-capabilities.md)
+- 使用与安装：`../README.md`
+- 插件当前可用接口：`plugin-development.md`
+- 分发和工作区：`deployment.md`
+- 实测范围与缺口：`verification.md`
+- 历史初始设计：`superpowers/specs/2026-10-09-workflow-cli-design.md`

package/manual/docs/superpowers/plans/2026-10-09-workflow-mvp.md

@@ -0,0 +1,115 @@
+# 插件式工作流首版实施计划
+
+> 已交付的历史实施计划。当前 CLI 名称、环境来源和分发行为以 [路线图](../../roadmap.md) 及其链接的最新设计为准；下面保留当时的实施约束。
+
+> **For agentic workers:** REQUIRED SUB-SKILL: 使用 superpowers:executing-plans 在本会话逐项执行。用户已明确“没别的疑问就进入开发”，因此直接落盘并执行，不新增审批回合。
+
+**Goal:** 交付可运行的插件式工作流工具，包含离线 Web 列表编排、CLI、官方环境检查插件和按选定工作流打包。
+
+**Architecture:** Cordis Host 加载标准 JS 插件；核心公开能力目录、工作流保存/执行、日志、插件管理与打包服务。Web 和环境检查作为独立官方插件，CLI 与 Web 复用应用服务。Python 使用目标环境。
+
+**Tech Stack:** Node.js 24.15.0、JavaScript ESM、Cordis 3.18.1、Ajv、YAML、Node 内建测试；npm workspaces + lockfile。按用户复用开源要求，前端采用 React、RJSF、dnd-kit、Lucide、Vite，构建为本地静态资源，无 CDN。进程用 Execa；打包复用 Arborist、npm-packlist、Archiver。
+
+**Spec:** `docs/superpowers/specs/2026-10-09-workflow-cli-design.md`
+
+**实施状态（2026-10-10）：** 六项开发任务已完成，独立审查的重要问题已修复。实际测试、体积和平台缺口见 `docs/verification.md`；勾选开发任务不表示设计中的所有干净系统与硬件场景均已实测。Python/pip 解释器绑定采用真实环境手工验证；Docker Debian 12、Ubuntu 24.04 和 Python 3.12 容器已补测通过，真实 NPU 硬件待后续验证。
+
+## Global Constraints
+
+- 中文界面、说明和注释；Windows x64 与 Linux x64 glibc 分别出包。
+- 工作流是有序步骤列表，支持插件动作及子工作流；用户不手写 YAML 或依赖锁。
+- 必需环境检查失败终止后续步骤；Python 环境不随包安装或替换。
+- 包内携带 Node.js、所选工作流依赖闭包、脚本和资源；Linux 包可挂载进容器。
+- 官方 Web 插件标准发行默认提供，纯 CLI 运行包可不包含它。
+- 网页资源离线可用，支持堡垒机端口转发；不在本轮发布 npm 或推送远端。
+
+## Review Focus
+
+- 重排或删除前序步骤后引用失效：校验阻止运行并指明字段（任务 1、5）。
+- 中文/空格路径、不同工作目录和包外符号链接：启动定位及打包独立性（任务 2、4）。
+- 缺少 Python、pip、NPU 工具不能误判成功，检查与执行不能切换解释器（任务 3）。
+- 子流程失败、取消和大输出不能留下假成功或未关闭的受管进程（任务 1、2）。
+- Web 令牌、路径越界、离线资源和端口转发不得破坏执行边界（任务 5）。
+
+## 文件结构
+
+- `packages/sdk/`：插件定义与公共协议。
+- `packages/core/src/host.js`：Cordis 生命周期、插件动作目录。
+- `packages/core/src/workflows.js`：存取、静态校验、引用与闭包。
+- `packages/core/src/engine.js`：执行快照、顺序调用、日志和取消。
+- `packages/core/src/process.js`：无 Shell 的程序调用及回收。
+- `packages/core/src/application.js`：共用应用服务。
+- `packages/core/src/plugins.js`：安装、移除与锁定外部插件。
+- `packages/pack/`：生产依赖收集、运行时和归档，独立于执行包。
+- `packages/core/bin/flow.js`：CLI。
+- `plugins/environment/`：目标环境检查。
+- `plugins/examples/`：可组合的本地示例与 Python 调用。
+- `plugins/web/`：HTTP 适配和静态界面。
+- `examples/`：可直接运行的工作流。
+- `tests/`：真实文件、进程和 HTTP 边界测试。
+
+### Task 1: 插件目录与顺序工作流
+
+**Files:** SDK、`host.js`、`workflows.js`、`engine.js`、`tests/workflows.test.js`。
+
+**Interfaces:** `createHost({plugins,config})` 返回动作目录与 `invoke(id,input,context)`；`WorkflowStore(root)` 提供 `list/get/save/resolve`；`runWorkflow({store,host,id,input,signal,onEvent})` 返回输出。
+
+- [x] 写失败测试：真实测试插件两个动作串联得到 `{text:'HELLO'}`；子流程传参；失败后动作未执行；循环/前向引用/越界路径被拒绝。
+- [x] `node --test tests/workflows.test.js`：先因待实现模块失败。
+- [x] 实现 SDK、Cordis Host、静态模型与执行；输入输出使用 Ajv 校验，拒绝危险字段路径。
+- [x] 同一命令全部通过，再运行 `npm test`；提交任务代码。
+
+### Task 2: 共用应用服务、CLI 和外部插件
+
+**Files:** `process.js`、`plugins.js`、`application.js`、CLI、`tests/application.test.js`、`tests/process.test.js`。
+
+**Interfaces:** `createApplication({projectDir,outputDir})` 提供 `catalog/listWorkflows/saveWorkflow/startRun/getRun/cancelRun/installPlugin/removePlugin/pack/close`；`runProcess(file,args,options)` 返回退出信息。
+
+- [x] 写失败测试：带空格/中文参数真实传递；非零退出、输出上限、取消；JSONL 日志持久化；在仓库外安装本地插件并运行动作。
+- [x] 执行新增测试，确认缺失行为导致失败。
+- [x] 实现项目配置、准确插件位置、npm 安装适配与可读 CLI；安装失败不覆盖原项目状态。
+- [x] 执行 `npm test`，验证外部插件闭环，提交。
+
+### Task 3: 官方环境检查与示例
+
+**Files:** `plugins/environment/`、`plugins/examples/`、`examples/`、`tests/environment.test.js`。
+
+**Interfaces:** 环境插件公开 `check` 动作，输入为所需环境与解释器，输出为检查报告及解析后的解释器；示例插件提供文本动作和目标 Python 脚本调用。
+
+- [x] 写失败测试：不存在的解释器令检查失败且带报告；系统信息可读；pip 与指定解释器绑定；检查输出用于后续动作。
+- [x] 执行新增测试观察失败。
+- [x] 实现 Node 系统探测、目标 Python/pip 查询、NPU 命令适配及结构化报告；不安装环境。
+- [x] `npm test` 全绿；运行纯 JS 示例与可用目标 Python 示例，提交。
+
+### Task 4: 自包含分发
+
+**Files:** 打包模块、运行时下载与清单、`tests/pack.test.js`。
+
+**Interfaces:** `packApplication(app,{entries,target,outDir,includeWeb,runtimePath})` 返回目录、归档与 manifest；`verifyBundle(root)` 验证清单。
+
+- [x] 写失败测试：A 引用 B，C 不入包；重复依赖去重；可选 Web；篡改文件校验失败。
+- [x] 执行新增测试观察失败。
+- [x] 基于实际安装树按解析结果复制生产依赖，保留多版本嵌套关系且消除外部链接；锁定准确版本与哈希。
+- [x] 按平台收集经过官方校验值验证的 Node.js 与许可，生成相对路径启动器、ZIP/tar.gz；原生依赖跨目标拒绝不可靠复制。
+- [x] 脱离源码的 Windows 包实际运行；可用 Linux/容器执行验证；`npm test` 通过，记录未具备环境的验证缺口并提交。
+
+### Task 5: 官方离线 Web 工作台
+
+**Files:** `plugins/web/`、`tests/web.test.js`，必要的浏览器验证记录。
+
+**Interfaces:** Web 插件通过公开应用服务提供目录、工作流、运行、日志、插件管理与导出 API；浏览器只调用同源相对 URL。
+
+- [x] 写失败测试：真实 HTTP 下未授权请求被拒绝、工作流保存后能运行、越界静态路径被拒绝、全部静态资源本地可用。
+- [x] 执行新增测试观察失败。
+- [x] 实现令牌、请求来源检查、绑定地址与静态资源；界面包含能力/流程列表、有序步骤、参数来源选择、结果日志、插件安装与导出。
+- [x] `npm test`；浏览器实际添加、排序、引用输出、保存、运行和观察失败，修正发现的问题。
+- [x] 保存界面与 CLI 一致性验证证据，提交。
+
+### Task 6: 交付验证与文档
+
+**Files:** README、插件开发说明、部署说明、跨平台 CI 和验收记录。
+
+- [x] 运行全套测试与本机包冒烟；检查打包不携带开发工具链和外部绝对链接。
+- [x] 编写启动、插件开发、目标 Python 配置、离线部署、堡垒机端口转发和分发包使用说明。
+- [x] 全分支独立审查；对重要问题以失败测试复现后修复，再跑全套。
+- [x] 记录平台实测范围、硬件缺口、产物大小和运行方式；提交并交付可打开的 Web 界面。

package/manual/docs/superpowers/plans/2026-10-10-cordis-services.md

@@ -0,0 +1,34 @@
+# Cordis 服务与生命周期实施计划
+
+> 使用 superpowers:executing-plans 在当前会话实施。用户已审阅设计并要求继续开发；保留当前本地分支工作方式，不重复请求授权。结束时做一次独立审查。
+
+**目标：** 保持旧插件兼容，落实应用级资源归属和 Cordis 服务插件。
+**设计：** `../specs/2026-10-10-cordis-services-design.md`。
+**技术：** 锁定 Cordis 3.18.1、Node 24、现有 node:test。
+
+## 全局约束与审查重点
+
+- 不实现第二套动态服务激活机制；静态声明与打包契约由 Fishtools 校验。
+- 插件平台仅声明，不审核业务正确性；旧 actions/commands/services 协议兼容。
+- Web 开启时宿主切换不能中断控制入口；阻止活动 Web 提供者替换和移除。
+- 异步清理要等待、错误要传播；初始化失败释放已获取资源。
+- 安装/配置/关闭竞争、失效服务调用、缺失或循环声明、服务提供者打包闭包均需测试。
+
+## 任务与测试
+
+1. [x] 应用资源：新增 `core/src/resources.js`，提供 `own(factory)`、`close()`、`active`；修改 application.startWeb/close，生命周期开始关闭后拒绝新增任务。`tests/lifecycle.test.js` 验证真实端口释放、幂等关闭、异步启动与关闭竞争、失败清理。
+2. [x] 服务宿主：新增 `runtime.js` 校验 runtime.provides/inject/apply、提供者所属 dependencies 及循环；Cordis 管理注入激活。host 暴露 `runtimeStatus()`、`hasRuntime`，动作和命令上下文提供 `getService(name)`；绑定注册清理，等待异步 dispose，并传播启动/停止错误。`tests/runtime.test.js` 覆盖乱序加载、共享实例、就绪、失败/缺失/重复/循环、取消与作用域撤销。
+3. [x] 应用整合：有 runtime 插件时拒绝在线重建宿主；活动 Web 不能移除或替换。状态进入 listPlugins/TUI/CLI/Web API；pack 依赖闭包保留服务提供者。lifecycle/Web/pack 测试覆盖更新保护及导出后加载。
+4. [x] 公开示例与文档：提供可独立安装的 provider/consumer 示例，写出服务就绪后发布、getService 与 async dispose 用法；更新路线图和开发规范。
+5. [x] 验收：定向测试、构建和全套测试；一次独立审查并修复重要问题；便携包跨平台服务调用；提交推送并核对对应 CI。
+
+## 执行记录
+
+- 基线 e8672ef；分支 feat/cordis-services。本轮沿用已授权的当前工作区和连续实施。
+- 版本核查：Cordis 的 start 等待 ready 任务，但 stop/reset 不等待异步 disposer。采用受管 dispose 监听器的 Promise 收集，保持 Cordis 负责触发和撤销；不假设 stop 已释放全部资源。
+- 任务 1—3：资源关闭、服务声明/注入、失败清理、失效调用、Web 更新保护均经历失败测试后实现并通过。额外红绿测试修复关闭顺序，先释放 Web 再关闭其依赖宿主。
+- 裁定：增加进程级维护模式及 TUI 切换；只说“停止后再修改”会使下次 CLI 启动又加载服务，导致用户无从维护。维护模式关闭 runtime 激活，保留契约校验和普通插件；不写入项目配置。
+- 任务 4：提供两个可独立安装的 MIT 服务插件。service-pack 集成测试验证安装、调用、导出提供者闭包及独立启动；TUI 维护切换测试通过。
+- 独立审查一次，发现初始化撤销后的资源泄漏、旧调用穿透激活代次两项 Important；先补三项失败测试，再按每次激活跟踪初始化/清理及绑定 getService 令牌。最终本地 61/61 通过（150.5 秒）。
+- Windows 与 WSL 便携包实际调用共享服务成功；WSL 真实 TUI 进入维护、显示停止、恢复服务成功；断网只读 Debian 容器服务调用与完整性校验通过。
+- 代码提交 `061f0e4` 已推送至 main，Windows / Ubuntu CI 均通过：https://github.com/yanglaofish/Fishtools/actions/runs/38055698922 。本地保留 feat/cordis-services 分支；Windows、Linux 完整便携包位于 dist/cordis，npm 安装包位于 dist/fishtools-0.1.0.tgz。

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

@@ -0,0 +1,33 @@
+# fst 交互终端实施计划
+
+**目标：** 将启动命令改为 `fst`，无 Web 时也能通过斜杠命令、文件补全和方向键完成编排及运行。
+
+**用户意图：** 终端需要像 Claude 一样可以发现命令和选择项目，而不是要求记住全部命令行参数。产品仍叫 Fishtools，保留批处理子命令；交互终端不引入 LLM。
+
+**架构：** 使用 Pi 的 `@mariozechner/pi-tui`（MIT）提供 Editor、命令/文件补全、SelectList 和终端渲染。终端适配层调用现有 application、schema 校验和工作流格式，不绑定 Web 插件，不重复实现执行器。无参数且非 TTY 时打印帮助，不启动后台服务或挂起。
+
+## 交互设计
+
+- `fst` 默认启动终端工作台；`fst web` 显式启动 Web。
+- `/help`、`/workflows`、`/new`、`/add`、`/steps`、`/outputs`、`/save`、`/run`、`/plugins`、`/pack`、`/web`、`/exit`。
+- 所有选择列表支持上下箭头、Enter，Escape 返回。编辑和切换时保留未保存提醒；Ctrl+C 取消当前选择或运行，空闲时退出并确认未保存修改。
+- 参数由 schema 引导填写，支持固定值、前序输出、运行时填写。对象逐字段处理、数组按项编辑，复杂联合 schema 可用 JSON 输入并校验。
+- `@` 与 Tab 补全目标机器本地路径；参数中的 `@路径` 转为绝对路径，`@@` 表示字面量 @。只在 `/run [工作流ID] @文件.json` 的明确位置读取 JSON；文件内容不被隐式当成命令执行。
+- `/steps` 可改参数、上下移动、删除步骤；`/outputs` 选择最终输出；新建不要求手写 YAML。
+- 只读运行包支持浏览、参数填写与运行，禁用编排、安装和重新打包。
+- `fst run` 等原子命令继续用于自动化。npm 只注册 `fst`，不占用 Fish Shell 的 `fish`；包启动器同步改名，保留 `run`/`web` 兼容脚本。
+
+## 实施任务
+
+1. [x] 重命名 CLI、npm bin、自包含启动器和测试；增加默认非 TTY 行为测试。
+2. [x] 增加终端视图适配、schema 编辑与流程控制；测试路径解析、参数绑定、编排保存、取消和只读模式。
+3. [x] 用真实 PTY 验证 `/`、方向键、`@`、完整编排运行；跑全套测试，更新文档和许可证，生成 npm 包。
+4. [x] 独立审查后推送，等待对应提交的 Windows 与 Ubuntu CI 都完成；失败继续修复。提交 `bdd9cdf` 的 [双平台 CI](https://github.com/yanglaofish/Fishtools/actions/runs/38049659095) 已成功，本项补记已核对的状态。
+
+## 验收重点
+
+- 中文和带空格的文件路径、Windows 反斜杠、取消中途编辑不污染已保存工作流。
+- 运行时参数和前序输出引用不会被固定值表单覆盖，切换输入来源不会留下不再使用的运行必填项。
+- 无 Web 插件时能启动终端；缺少 Web 时 `/web` 明确报错并返回主提示符。
+- npm 安装端和自包含运行包都使用 `fst`，原子命令输出仍可机器读取。
+- 以远端 CI 的最终状态作为交付门槛，不能用推送成功替代检查通过。

package/manual/docs/superpowers/plans/2026-10-10-portable-plugin-contract.md

@@ -0,0 +1,35 @@
+# 分层分发与插件契约实施计划
+
+> 使用 superpowers:executing-plans 在当前会话按任务执行；用户已明确授权演进设计并继续编码。
+
+**目标：** 同一 fst 工具支持便携开发、可编辑流程导出、插件命令和声明式环境资源。
+**架构：** 复用 Node/npm/Cordis，独立插件契约、环境计划、工作区初始化与归档模块；不创建包管理器或业务兼容性检查器。
+**技术栈：** Node 24.15.0、JavaScript、Cordis、Pi TUI、npm、node-tar、Archiver。
+**设计：** ../specs/2026-10-10-portable-plugin-contract.md
+
+## 全局约束
+
+- 中文说明与注释；Windows x64 / Linux x64 glibc；相同 TUI。
+- 平台声明不阻止加载/调用；业务环境检查交给插件。
+- 包含 npm 的完整分发能安装本地插件并再次导出；不发布公共 npm。
+
+## 审查重点
+
+命令与核心入口冲突、取消交互后运行收尾、环境资源越界、工作区重复初始化与移动、隔离 PATH 后内部 npm 调用。
+
+## 任务
+
+1. [x] 契约与命令：新增 core/src/contracts.js、environments.js；扩展 host/application/terminal；测试平台声明仅提示、非法契约、命令调用与冲突、取消。先运行新增失败测试，再实现并执行相关测试。
+2. [x] 环境打包计划：新增 pack/environments.js；扩展 copyPackages 资源筛选并移除业务平台门禁；测试 host 不入包、目标 artifacts、越界、源切换。API planApplication(app,options) 返回清单与 bytes。
+3. [x] 完整运行环境与可编辑导出：扩展 runtime/index/project/CLI，新增工作区模块与共用归档；新增 portable 命令、--read-only、--workspace、--environments。测试改参持久化、只读兼容、完整性与内部 npm。
+4. [x] 统一 TUI：动态插件斜杠命令、/config、/pack 计划与来源选择；官方示例展示契约；更新接入指南及部署文档。
+5. [x] 验收交付：运行全套测试与构建、Windows/Linux/Docker 产物测试、独立审查、必要修复、推送并等待 Windows/Ubuntu CI。
+
+## 执行记录
+
+- 开始：基线 bdd9cdf，分支 feat/portable-plugin-contract。用户授权本轮直接开发，采用会话内实施和一次最终独立审查。
+
+- 本地验收：构建成功、47/47 测试通过；Windows 与 WSL 真实 TUI、Linux 归档解压、断网无 Node/npm 容器安装及再次打包通过。
+- 独立审查：2 项 Important 均修复并补回归。另修复归档执行权限和应用层依赖清单，等待远端双平台 CI。
+
+- 最终 CI：e55075e 的 Windows 与 Ubuntu 均通过，https://github.com/yanglaofish/Fishtools/actions/runs/38053011826 。后续仅归档验收文档。

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

@@ -0,0 +1,77 @@
+# 控制流与运行观察实施计划
+
+**执行方式：** 使用 superpowers:subagent-driven-development；用户已授权写明目标后直接开始。
+
+**目标：** 将已确认的控制流、并行与运行观察能力完整接入内核、TUI、Web 和开发手册。
+
+**架构：** 内核解释结构化控制节点，沿用 Cordis 调用与运行事件；界面编辑同一工作流协议，观察同一事件，不另造执行器。
+
+**技术栈：** Node.js ≥24.15、JavaScript、Cordis、Pi TUI、React、Ajv、execa。
+
+**规范：** ../specs/2026-10-11-control-observation.md
+
+## 全局约束
+
+- 中文文案、跨 Windows/Linux、保持现有顺序工作流与归档闭包兼容。
+- 条件不能执行任意脚本；声明平台不代替作者验证兼容性。
+- 首次错误后等所有子任务清理；不掩盖首因，不承诺回滚。
+- 不修改现有 tag，普通推送只测试；全量验收通过后再发布。
+
+## 任务与验证
+
+### 1. 控制协议与执行器（主代理）
+
+文件：core/src/control.js、workflows.js、engine.js、validation.js、contracts.js，官方 environment 插件与示例。
+
+- [x] 增加失败测试：严格条件、分支/跳过/结束、并行上限、兄弟引用拒绝、首因保留与清理、嵌套打包闭包。
+- [x] 实现 validateCondition/evaluateCondition、递归校验及依赖收集、受限并发执行；stopped 使用 code WORKFLOW_STOPPED、details.reason 传给应用层。
+- [x] 校验可编排动作 input/output 及 conditions 预设；增加 report 动作并保留 check 兼容。
+- [x] 运行控制流与现有 workflows/pack 相关测试，审查后提交。
+
+### 2. 实时输出与运行记录
+
+文件：process.js、host.js、application.js、markdown-log.js、cli-run.js、bin/fst.js，相关测试。
+
+- [x] 先测试 stdout/stderr 在进程结束前到达、UTF-8 分块、取消、stopped 有原因无 error。
+- [x] runProcess 增加 onOutput({stream,message})；宿主注入事件归属，应用持久化新状态，CLI 与 Markdown 明确显示停止原因。
+- [x] 跑 process/diagnostics/logs 测试并审查。
+
+### 3. TUI 控制编辑与实时观察
+
+文件：terminal/*、contracts.js 的 builtinCommands 部分、tests/terminal*、tests/log-viewer*。
+
+- [x] 先测试交互编辑分支/并行/stop/when、嵌套参数绑定和只读限制。
+- [x] 表单调用核心协议；/runs 打开运行面板，视图与步骤切换、键盘/滚轮滚动、离开后后台继续，明确取消。
+- [x] 测试整屏布局、尾部跟随、事件归属、鼠标模式恢复，并在真实 PTY 验证。
+
+### 4. Web 控制编辑与观察
+
+文件：plugins/web/src/*、相关 Web 测试。
+
+- [x] 添加可嵌套的控制节点编辑与条件字段/预设选择，维护只读行为及原动作表单。
+- [x] 运行面板显示所有步骤状态、输入输出、按路径过滤的实时日志，支持滚轮与跟随切换。
+- [x] 构建、组件模型测试、浏览器实际编辑保存并运行验证。
+
+### 5. 集成、手册与分发
+
+- [x] 更新 plugin-development、README、路线图、验收记录；声明约束和示例与代码一致。
+- [x] 运行完整测试、独立审查、Windows/WSL 交互、Docker 与自包含导出验收。
+- [x] 推送并确认双平台 CI，符合发布门槛后同步 npm/tag/Release。
+
+## 容易遗漏的验收场景
+
+1. 跳过节点后引用不存在输出：明确报错，exists 可用于防护。
+2. 并行任务先失败再收到取消：最终保留失败首因且等待清理。
+3. 分支与子流程内 stop：整个运行结束，未执行节点标明原因。
+4. 相同插件重复调用及并行日志：按 callPath 区分，不串行归属。
+5. 关闭观察面板或缩小窗口：不取消后台任务，不隐藏退出/取消操作。
+
+## 验收期间追加的已确认目标
+
+用户看到 0.1.4 的终端截图后要求参考 Claude Code / OpenCode 改进视觉；另要求仅安装 npm 包的开发者也能获取完整开发规范、接口说明和示例。这两项随本轮交付：
+
+- [x] TUI 使用紧凑块字品牌标识、青绿色强调、辅助文字层级、明确输入区与精简首页；窄屏和 NO_COLOR 可用，不削弱插件/工作流浏览及运行观察。
+- [x] 开发资料随 npm 与便携包离线提供；CLI `fst docs`、TUI `/docs` 可读，支持导出到可写目录；补全本地相对链接与可独立安装的插件示例。
+- [x] 在安装后的 npm 包、脱离源码的自包含包中验收资料定位、导出、示例接入；验证资料随再次导出保留。
+
+视觉参考为用户提供的 Claude Code 截图和 [OpenCode 首页实现](https://github.com/anomalyco/opencode/blob/dev/packages/tui/src/routes/home.tsx)，使用现有 Pi TUI 实现，不迁移终端框架。

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 独立模块保存会话事件；详细运行观察器继续复用。真实执行支持返回输入区后打开菜单或启动另一条工作流。
+- 审查发现监听器累积与整段排列遮挡较早任务的新事件，已改为单个应用订阅和事件顺序追加；管理提示也进入相同顺序。每个缺陷先添加失败测试，再修复。
+- 命令来源为内置/插件，工作流属于操作对象；为兼容已有用法，旧顶层编辑命令保留执行但隐藏默认补全。
+- 保留源文件备份，仅在隔离试用工作区与临时测试目录进行验证；发布仍需用户后续确认。
+
+## 重点检查
+
+- 插件入口名称冲突、动态卸载后命令过期，旧直达命令的兼容性。
+- 工作流编辑取消保留原内容，删除备份可恢复，嵌套子流程引用不能漏检。
+- 运行期间打开配置不结束任务、不清空输出，重复运行可区分。
+- 窄窗口主输入始终可见；普通文本误输入显示输入提示。
+- 主面板滚动不误提交输入；退出清理订阅与终端鼠标模式。