@yanglaofish/fishtools 0.3.0 → 0.5.0

package/README.md

@@ -6,7 +6,7 @@
 
 交互终端支持选择能力、配置参数和流程编排；官方 Web 插件默认提供，原子 CLI 子命令用于自动化。三种入口共用应用服务。YAML、依赖锁和版本解析由系统维护，不要求普通用户手写。
 
-0.3.0 增加按对象组织的终端菜单、主面板执行摘要与插件用户输出、命令历史，并修复第三方插件进程调用和离线 Web 打包。此前 0.2.0 引入的条件控制、运行观察和离线开发手册仍可使用。发布与验证状态见 [版本记录](manual/docs/releases.md) 和 [验收记录](manual/docs/verification.md)。
+0.5.0 增加工作流复制、按工作区/插件/动作设置代理、插件权限预检，以及只重启受影响插件的更新。大量输出落盘、开发重载和隔离文件探测继续可用。发布与验证状态见 [版本记录](manual/docs/releases.md) 和 [验收记录](manual/docs/verification.md)。
 
 插件接入层使用 JavaScript/TypeScript，通过通用进程接口调用 Python 脚本和系统命令。首款官方插件负责 Python/pip、NPU 与系统环境检查，使用与第三方插件相同的公开接口，按工作流依赖选入分发包。插件声明 Python 等环境使用宿主机还是自带资源；环境检查与业务兼容性由插件作者负责。包内始终携带编排器所需的 Node，完整便携包也携带 npm。
 
@@ -19,7 +19,7 @@ npm install -g @yanglaofish/fishtools
 fst
 ```
 
-也可从 GitHub Release 下载 `.tgz` 后执行 `npm install -g ./yanglaofish-fishtools-0.3.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.0.tgz`。没有 Node/npm 的机器使用 Release 中的 Windows `.zip` 或 Linux `.tar.gz` 自包含包，解压后运行 `fst.cmd` 或 `./fst`。发布结果以 [GitHub Releases](https://github.com/yanglaofish/Fishtools/releases) 为准；当前仓库为私有，下载附件需要仓库访问权限。
 
 `fst` 在交互终端里启动终端工作台（TUI）；`fst web` 启动 Web 并打印访问地址；`fst run hello` 直接执行工作流。首次使用在 `~/.fishtools` 创建工作区，也可通过 `FISHTOOLS_HOME` 指定。安装包已包含官方插件、页面和生产依赖，不需要源码仓库或前端构建。
 
@@ -60,7 +60,7 @@ fst --project ./my-project pack hello --target linux-x64-glibc --web
 | `/logs` | 回看执行记录，运行中的任务优先；可切换总览、输入输出与日志，支持键盘或鼠标滚轮阅读 |
 | `/plugin` | 浏览已安装插件、用途及能力，进入插件配置、安装和移除操作 |
 | `/pack` | 勾选工作流并选择目标平台打包 |
-| `/config` | 配置 Fishtools：查看工作区信息，设置整个项目的日志保留次数 |
+| `/config` | 配置 Fishtools：查看工作区信息，设置日志保留次数和代理规则 |
 | `/tools` | 启动 Web 或阅读离线资料 |
 | `/help`、`/exit` | 查看帮助、退出 |
 
@@ -68,6 +68,28 @@ fst --project ./my-project pack hello --target linux-x64-glibc --web
 
 `/run` 不要求保存当前编辑草稿，也不会丢弃它。要运行尚未保存的修改，请在 `/workflows` 的编辑菜单选择“运行工作流”，再选择“保存并运行”；已有磁盘版本时也可选择“运行已保存版本”并保留草稿。“返回编辑”会留在当前工作流，不会反复弹出保存确认。只查看参数或拒绝删除步骤不会产生未保存修改。
 
+在 `/workflows` 选中一个已保存流程后可“复制工作流”，填写新名称并保存为独立副本。CLI 可用 `fst workflow duplicate 原ID --title 新名称`。修改两份流程的参数后依次运行，再到 `/logs` 对照结果；复制不会更改原流程。
+
+要让两版连续运行，可先 `fst init ./compare-demo`，再执行 `fst --project ./compare-demo workflow duplicate hello --title 参数变体 --id hello-variant`。修改副本的参数后，将以下内容保存为 `./compare-demo/workflows/compare-hello.yaml`，执行 `fst --project ./compare-demo run compare-hello`：
+
+```yaml
+schemaVersion: 1
+id: compare-hello
+title: 原版与变体连续对照
+steps:
+  - id: baseline
+    workflow: ./hello.yaml
+    with: {text: "相同的测试输入"}
+  - id: variant
+    workflow: ./hello-variant.yaml
+    with: {text: "相同的测试输入"}
+outputs:
+  baseline: {$ref: steps.baseline.output.text}
+  variant: {$ref: steps.variant.output.text}
+```
+
+运行记录会分别显示两个步骤的输出和耗时。做性能比较时请多次运行并交换两者顺序，留意首次启动和缓存可能影响结果。
+
 参数来源可选固定值、每次运行时填写或前序步骤的输出。对象逐字段编辑，数组逐项编辑；复杂 schema 可以输入 JSON 值。终端本身无需 Web 插件或 LLM。
 
 条件分支只执行命中的一侧；并行组同时执行独立步骤，可设置 1–32 的最大并发数（默认 4）。步骤的执行条件不满足时跳过。提前结束节点正常停止整个运行并保留原因，显示为 `stopped`；主动取消显示为 `cancelled`，执行异常显示为 `failed`。插件返回业务结果，由工作流决定结果不符合要求时如何处理。
@@ -183,7 +205,9 @@ npm 安装版是完整编排工具；上表为按所选流程导出的自包含
 
 完整 npm 与便携发行包携带 `manual/` 离线资料。只安装 npm 包的开发者可用 `fst docs` 查看主题，`fst docs plugins` 阅读规范，`fst docs plugins --path` 定位本地文件，或 `fst docs --export ./fishtools-manual` 导出完整资料（目标必须不存在）。TUI 使用 `/docs` 阅读。规范、源码阅读参考、许可证以及[可安装的零依赖动作插件](manual/docs/examples/action-plugin/README.md)一起分发，无需克隆仓库或另行安装内部 SDK。资料对应当前安装版本，离线安装、阅读、导出和示例接入均纳入分发验收。
 
-- 服务插件可使用 Cordis `runtime` 声明共享服务和生命周期；修改有状态插件前，TUI `/plugins` 进入维护模式，或 CLI 使用 `--maintenance`。示例见 [共享服务插件](manual/examples/service-plugins/README.md)。
+- 插件代理可在 `/config` 中设置，CLI 使用 `fst network show` 或 `fst network set 代理规则.json`。工作区、插件、动作各层可以分别继承环境代理、直连或选择代理配置；离线使用可选择直连。规则和权限声明见[插件开发文档](manual/docs/plugin-development.md)。
+- 插件可以声明普通用户、Linux root 或 Windows 管理员权限。运行前会预检；无法确认的权限需要用户明确选择继续，已确认不足会停止。移除仍被工作流引用的插件时会先提示引用位置；明确使用 `--force` 才保留工作流并卸载插件。
+- 服务插件可使用 Cordis `runtime` 声明共享服务和生命周期；插件更新只重启受影响的服务，需维护的更新会在 TUI/Web 提示并取得本次操作确认。示例见 [共享服务插件](manual/examples/service-plugins/README.md)。
 - [当前里程碑与路线图](manual/docs/roadmap.md)
 - [插件开发与公共接口](manual/docs/plugin-development.md)
 - [离线部署与堡垒机访问](manual/docs/deployment.md)
@@ -192,8 +216,12 @@ npm 安装版是完整编排工具；上表为按所选流程导出的自包含
 - [实施计划](manual/docs/superpowers/plans/2026-10-09-workflow-mvp.md)
 - [开源来源与许可证](manual/THIRD_PARTY_NOTICES.md)
 
-核心在 `packages/core`，SDK 在 `packages/sdk`，打包在 `packages/pack`，官方插件在 `plugins`。使用 npm workspaces 与提交的 lockfile 固定依赖。运行 `npm test` 验证。
+代码按十一模块划分：core、SDK、platform、logs、workflow、plugin、workspace、devtools、CLI、pack 和 Web。各模块通过 exports 声明公共入口，使用 npm workspaces 与提交的 lockfile 固定依赖。职责、依赖和定位方式见[模块架构](manual/docs/modules.md)，运行 `npm test` 验证。
 
 参与编排的插件动作必须声明有效的 input/output JSON Schema；无参数或无输出也声明空对象 schema。正常返回且输出通过校验即执行成功，可选 `conditions` 预设帮助用户选择业务判断。通过上下文 `runProcess` 执行的 stdout/stderr 会自动进入实时日志；完整协议、引用范围和并行取消规则见[插件开发文档](manual/docs/plugin-development.md)。
 
 首版优先 Windows x64 和 Linux x64 glibc。Alpine/musl、ARM、Windows 容器与分布式调度未纳入；真实 NPU 硬件验证仍待进行。
+
+## 代际演进能力
+
+十一内部模块继续通过一个 npm 产品交付。当前源码已支持大日志持续落盘与分页、`fst --watch` 开发重载，以及 `ctx.fs` 隔离文件探测。完整用法见 [能力指南](manual/docs/kernel-generation.md)，安装后可用 `fst docs generation` 离线阅读。

package/bin/fst.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-import "../node_modules/@mytools/core/bin/fst.js";
+import "../node_modules/@mytools/fst-cli/bin/fst.js";

package/manual/README.md

@@ -6,7 +6,7 @@
 
 交互终端支持选择能力、配置参数和流程编排；官方 Web 插件默认提供，原子 CLI 子命令用于自动化。三种入口共用应用服务。YAML、依赖锁和版本解析由系统维护，不要求普通用户手写。
 
-0.3.0 增加按对象组织的终端菜单、主面板执行摘要与插件用户输出、命令历史，并修复第三方插件进程调用和离线 Web 打包。此前 0.2.0 引入的条件控制、运行观察和离线开发手册仍可使用。发布与验证状态见 [版本记录](docs/releases.md) 和 [验收记录](docs/verification.md)。
+0.5.0 增加工作流复制、按工作区/插件/动作设置代理、插件权限预检，以及只重启受影响插件的更新。大量输出落盘、开发重载和隔离文件探测继续可用。发布与验证状态见 [版本记录](docs/releases.md) 和 [验收记录](docs/verification.md)。
 
 插件接入层使用 JavaScript/TypeScript，通过通用进程接口调用 Python 脚本和系统命令。首款官方插件负责 Python/pip、NPU 与系统环境检查，使用与第三方插件相同的公开接口，按工作流依赖选入分发包。插件声明 Python 等环境使用宿主机还是自带资源；环境检查与业务兼容性由插件作者负责。包内始终携带编排器所需的 Node，完整便携包也携带 npm。
 
@@ -19,7 +19,7 @@ npm install -g @yanglaofish/fishtools
 fst
 ```
 
-也可从 GitHub Release 下载 `.tgz` 后执行 `npm install -g ./yanglaofish-fishtools-0.3.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.0.tgz`。没有 Node/npm 的机器使用 Release 中的 Windows `.zip` 或 Linux `.tar.gz` 自包含包，解压后运行 `fst.cmd` 或 `./fst`。发布结果以 [GitHub Releases](https://github.com/yanglaofish/Fishtools/releases) 为准；当前仓库为私有，下载附件需要仓库访问权限。
 
 `fst` 在交互终端里启动终端工作台（TUI）；`fst web` 启动 Web 并打印访问地址；`fst run hello` 直接执行工作流。首次使用在 `~/.fishtools` 创建工作区，也可通过 `FISHTOOLS_HOME` 指定。安装包已包含官方插件、页面和生产依赖，不需要源码仓库或前端构建。
 
@@ -60,7 +60,7 @@ fst --project ./my-project pack hello --target linux-x64-glibc --web
 | `/logs` | 回看执行记录，运行中的任务优先；可切换总览、输入输出与日志，支持键盘或鼠标滚轮阅读 |
 | `/plugin` | 浏览已安装插件、用途及能力，进入插件配置、安装和移除操作 |
 | `/pack` | 勾选工作流并选择目标平台打包 |
-| `/config` | 配置 Fishtools：查看工作区信息，设置整个项目的日志保留次数 |
+| `/config` | 配置 Fishtools：查看工作区信息，设置日志保留次数和代理规则 |
 | `/tools` | 启动 Web 或阅读离线资料 |
 | `/help`、`/exit` | 查看帮助、退出 |
 
@@ -68,6 +68,28 @@ fst --project ./my-project pack hello --target linux-x64-glibc --web
 
 `/run` 不要求保存当前编辑草稿，也不会丢弃它。要运行尚未保存的修改，请在 `/workflows` 的编辑菜单选择“运行工作流”，再选择“保存并运行”；已有磁盘版本时也可选择“运行已保存版本”并保留草稿。“返回编辑”会留在当前工作流，不会反复弹出保存确认。只查看参数或拒绝删除步骤不会产生未保存修改。
 
+在 `/workflows` 选中一个已保存流程后可“复制工作流”，填写新名称并保存为独立副本。CLI 可用 `fst workflow duplicate 原ID --title 新名称`。修改两份流程的参数后依次运行，再到 `/logs` 对照结果；复制不会更改原流程。
+
+要让两版连续运行，可先 `fst init ./compare-demo`，再执行 `fst --project ./compare-demo workflow duplicate hello --title 参数变体 --id hello-variant`。修改副本的参数后，将以下内容保存为 `./compare-demo/workflows/compare-hello.yaml`，执行 `fst --project ./compare-demo run compare-hello`：
+
+```yaml
+schemaVersion: 1
+id: compare-hello
+title: 原版与变体连续对照
+steps:
+  - id: baseline
+    workflow: ./hello.yaml
+    with: {text: "相同的测试输入"}
+  - id: variant
+    workflow: ./hello-variant.yaml
+    with: {text: "相同的测试输入"}
+outputs:
+  baseline: {$ref: steps.baseline.output.text}
+  variant: {$ref: steps.variant.output.text}
+```
+
+运行记录会分别显示两个步骤的输出和耗时。做性能比较时请多次运行并交换两者顺序，留意首次启动和缓存可能影响结果。
+
 参数来源可选固定值、每次运行时填写或前序步骤的输出。对象逐字段编辑，数组逐项编辑；复杂 schema 可以输入 JSON 值。终端本身无需 Web 插件或 LLM。
 
 条件分支只执行命中的一侧；并行组同时执行独立步骤，可设置 1–32 的最大并发数（默认 4）。步骤的执行条件不满足时跳过。提前结束节点正常停止整个运行并保留原因，显示为 `stopped`；主动取消显示为 `cancelled`，执行异常显示为 `failed`。插件返回业务结果，由工作流决定结果不符合要求时如何处理。
@@ -183,7 +205,9 @@ npm 安装版是完整编排工具；上表为按所选流程导出的自包含
 
 完整 npm 与便携发行包携带 `manual/` 离线资料。只安装 npm 包的开发者可用 `fst docs` 查看主题，`fst docs plugins` 阅读规范，`fst docs plugins --path` 定位本地文件，或 `fst docs --export ./fishtools-manual` 导出完整资料（目标必须不存在）。TUI 使用 `/docs` 阅读。规范、源码阅读参考、许可证以及[可安装的零依赖动作插件](docs/examples/action-plugin/README.md)一起分发，无需克隆仓库或另行安装内部 SDK。资料对应当前安装版本，离线安装、阅读、导出和示例接入均纳入分发验收。
 
-- 服务插件可使用 Cordis `runtime` 声明共享服务和生命周期；修改有状态插件前，TUI `/plugins` 进入维护模式，或 CLI 使用 `--maintenance`。示例见 [共享服务插件](examples/service-plugins/README.md)。
+- 插件代理可在 `/config` 中设置，CLI 使用 `fst network show` 或 `fst network set 代理规则.json`。工作区、插件、动作各层可以分别继承环境代理、直连或选择代理配置；离线使用可选择直连。规则和权限声明见[插件开发文档](docs/plugin-development.md)。
+- 插件可以声明普通用户、Linux root 或 Windows 管理员权限。运行前会预检；无法确认的权限需要用户明确选择继续，已确认不足会停止。移除仍被工作流引用的插件时会先提示引用位置；明确使用 `--force` 才保留工作流并卸载插件。
+- 服务插件可使用 Cordis `runtime` 声明共享服务和生命周期；插件更新只重启受影响的服务，需维护的更新会在 TUI/Web 提示并取得本次操作确认。示例见 [共享服务插件](examples/service-plugins/README.md)。
 - [当前里程碑与路线图](docs/roadmap.md)
 - [插件开发与公共接口](docs/plugin-development.md)
 - [离线部署与堡垒机访问](docs/deployment.md)
@@ -192,8 +216,12 @@ npm 安装版是完整编排工具；上表为按所选流程导出的自包含
 - [实施计划](docs/superpowers/plans/2026-10-09-workflow-mvp.md)
 - [开源来源与许可证](THIRD_PARTY_NOTICES.md)
 
-核心在 `packages/core`，SDK 在 `packages/sdk`，打包在 `packages/pack`，官方插件在 `plugins`。使用 npm workspaces 与提交的 lockfile 固定依赖。运行 `npm test` 验证。
+代码按十一模块划分：core、SDK、platform、logs、workflow、plugin、workspace、devtools、CLI、pack 和 Web。各模块通过 exports 声明公共入口，使用 npm workspaces 与提交的 lockfile 固定依赖。职责、依赖和定位方式见[模块架构](docs/modules.md)，运行 `npm test` 验证。
 
 参与编排的插件动作必须声明有效的 input/output JSON Schema；无参数或无输出也声明空对象 schema。正常返回且输出通过校验即执行成功，可选 `conditions` 预设帮助用户选择业务判断。通过上下文 `runProcess` 执行的 stdout/stderr 会自动进入实时日志；完整协议、引用范围和并行取消规则见[插件开发文档](docs/plugin-development.md)。
 
 首版优先 Windows x64 和 Linux x64 glibc。Alpine/musl、ARM、Windows 容器与分布式调度未纳入；真实 NPU 硬件验证仍待进行。
+
+## 代际演进能力
+
+十一内部模块继续通过一个 npm 产品交付。当前源码已支持大日志持续落盘与分页、`fst --watch` 开发重载，以及 `ctx.fs` 隔离文件探测。完整用法见 [能力指南](docs/kernel-generation.md)，安装后可用 `fst docs generation` 离线阅读。

package/manual/docs/deployment.md

@@ -5,7 +5,7 @@
 完整工具支持 npm 安装，目标机器需要 Node.js 24.15.0+ 和 npm：
 
 ```sh
-npm install -g ./yanglaofish-fishtools-0.1.3.tgz
+npm install -g ./yanglaofish-fishtools-0.5.0.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.1.3.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.0.tgz` 并把 `$HOME/.local/bin` 加入 PATH。`fst` 提供斜杠命令、文件补全和方向键选择；Web 使用 `fst web`，交互容器需要分配终端（例如 `docker run -it`）。不分配终端时使用 `fst run` 等原子命令。
 
 以下章节描述按选定工作流导出的自包含运行包；它们携带 Node，运行端无需 npm。新运行包提供 `fst.cmd` / `./fst` 启动入口，兼容保留 `run.cmd` / `run.sh`。
 
@@ -26,7 +26,7 @@ Linux 无 npm 全局目录写权限时，可使用 `npm install -g --prefix "$HO
 npm run fst -- --project examples pack hello python-check --target linux-x64-glibc --web
 ```
 
-`dist` 同时保留可运行目录和压缩包。清单记录入口、工作流、插件/实际 npm 包版本、Node 信息、环境声明与文件 SHA-256。各平台分别出包；插件平台声明用于提示，不是核心审核通过的证明。原生依赖和业务兼容性由作者负责，核心不按文件后缀或平台声明阻止跨目标复制。
+`dist` 同时保留可运行目录和压缩包。清单记录入口、工作流、插件/实际 npm 包版本、Node 信息、环境与权限声明、选入插件使用的代理规则，以及文件 SHA-256。各平台分别出包；插件平台声明用于提示，不是核心审核通过的证明。原生依赖和业务兼容性由作者负责，核心不按文件后缀或平台声明阻止跨目标复制。
 
 默认完整包携带 Node 24.15.0、内部 npm、打包服务和插件生产依赖，不携带插件的 TS 编译器等开发依赖。`--read-only` 可导出不含 npm/打包服务的精简包。首次打包下载固定校验的官方运行时，后续复用 `.cache/runtimes`；完整包对同一目标再次导出可复用包内运行时，无需联网。插件开发所需额外编译器或 Agent 由其各自要求提供。
 

package/manual/docs/examples/script-plugin/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mytools contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/manual/docs/examples/script-plugin/README.md

@@ -0,0 +1,64 @@
+# Python 脚本插件示例
+
+这是可独立安装的 ESM 插件包。npm 依赖为零，包内 Python 脚本只使用标准库。它演示嵌套输入、宿主解释器选择、脚本资源定位和业务条件分支；指标是确定性的教学计算，不是硬件性能基准。
+
+## 安装与运行
+
+先确认目标机器安装了 Python 3。插件声明 `host` 环境，按顺序查找 `python3`、`python`；不会下载 Python 或将解释器打入包。复制本目录到目标机器，在 Fishtools 项目中执行：
+
+```sh
+fst plugin validate ./script-plugin
+fst --project ./my-project plugin add ./script-plugin
+```
+
+创建输入文件 `benchmark.json`：
+
+```json
+{"benchmark_config":{"samples":4,"threshold":7}}
+```
+
+将 `fishtools-python-benchmark-example:benchmark` 加入工作流，输入绑定 `benchmark_config`。如果 Python 不在 PATH 中，运行时会报告找不到 `python3`、`python`。在项目 `flow.project.json` 的 `environments` 中为该插件指定解释器绝对路径，例如：
+
+```json
+{
+  "environments": {
+    "fishtools-python-benchmark-example": {
+      "python": {"source": "host", "executable": "C:/Python312/python.exe"}
+    }
+  }
+}
+```
+
+上面仅展示相关字段；编辑已有项目文件时保留原有 `plugins`、`config` 等字段。Linux/macOS 可将路径换成 `/usr/bin/python3` 等实际位置。显式路径不可用会报错，不回退到候选命令。解释器需要 Python 3；目标环境和脚本的兼容性由部署者验证。
+
+## 业务结果与分支
+
+脚本计算 `1²` 到 `samples²` 的平均值。`samples=4` 得到 `7.5`；`threshold=7` 返回 `ok:true`，`threshold=8` 返回 `ok:false`。两种结果都表示脚本正常完成，输出包含 `metrics.samples`、`metrics.average` 和 `reason`。动作提供 `conditions.passed`，可在工作流中选择通过和未通过分支：
+
+```yaml
+schemaVersion: 1
+id: python-benchmark-example
+steps:
+  - id: measure
+    action: fishtools-python-benchmark-example:benchmark
+    with:
+      benchmark_config:
+        samples: 4
+        threshold: 8
+  - id: result
+    branch:
+      condition:
+        left: {$ref: steps.measure.output.ok}
+        op: eq
+        right: true
+      then:
+        - id: accepted
+          stop: {reason: 业务指标通过}
+      else:
+        - id: rejected
+          stop: {reason: 业务指标未通过}
+```
+
+将工作流保存为项目的 `workflows/python-benchmark-example.yaml` 后，可执行 `fst --project ./my-project workflow check python-benchmark-example` 和 `fst --project ./my-project run python-benchmark-example`。`ok:false` 应由业务分支处理；脚本非零退出或输出不是 JSON 才作为执行错误抛出。
+
+动作通过 `environments.python.executable` 取得最终解释器，通过 `resourceDir` 找包内 `scripts/benchmark.py`，再用上下文 `runProcess` 执行。宿主绑定的 `runProcess` 自动继承取消信号并将 stdout/stderr 写入运行日志。`package.json.files` 包含脚本，`npm pack` 生成的归档可独立安装。

package/manual/docs/examples/script-plugin/index.js

@@ -0,0 +1,39 @@
+import path from 'node:path';
+
+// 直接导出插件定义，不依赖尚未独立发布的内部 SDK。
+export default {
+  id:'fishtools-python-benchmark-example',version:'1.0.0',sdk:'^0.1.0',
+  title:'Python 脚本示例',description:'调用包内标准库脚本并区分业务未通过与执行失败。',
+  platforms:['win32','linux','darwin'],architectures:['x64','arm64'],
+  environments:{python:{source:'host',executable:['python3','python']}},
+  actions:{
+    benchmark:{
+      title:'计算样本指标',description:'用 Python 计算前 N 个正整数的平方均值，并与阈值比较。',
+      input:{type:'object',properties:{
+        benchmark_config:{type:'object',title:'计算配置',properties:{
+          samples:{type:'integer',minimum:1,maximum:100000,title:'样本数'},
+          threshold:{type:'number',minimum:0,title:'最低平方均值'},
+        },required:['samples','threshold'],additionalProperties:false},
+      },required:['benchmark_config'],additionalProperties:false},
+      output:{type:'object',properties:{
+        ok:{type:'boolean',title:'业务通过'},
+        metrics:{type:'object',properties:{
+          samples:{type:'integer'},average:{type:'number'},
+        },required:['samples','average'],additionalProperties:false},
+        reason:{type:'string',title:'判定原因'},
+      },required:['ok','metrics','reason'],additionalProperties:false},
+      conditions:{passed:{title:'业务通过',path:'ok',op:'eq',value:true}},
+      async run({benchmark_config},{environments,resourceDir,runProcess,signal}){
+        signal?.throwIfAborted();
+        const script=path.join(resourceDir,'scripts','benchmark.py');
+        // 宿主绑定的 runProcess 会自动继承当前调用的取消信号并记录输出。
+        const result=await runProcess(environments.python.executable,[script,JSON.stringify(benchmark_config)],{timeout:30000});
+        if(result.exitCode!==0)throw Object.assign(new Error(`Python 脚本执行失败（退出码 ${result.exitCode}）：${result.stderr}`),{
+          code:'PYTHON_FAILED',details:{exitCode:result.exitCode,stderr:result.stderr},
+        });
+        try{return JSON.parse(result.stdout);}
+        catch(cause){throw Object.assign(new Error('Python 脚本返回无效 JSON',{cause}),{code:'PYTHON_OUTPUT_INVALID'});}
+      },
+    },
+  },
+};

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

@@ -0,0 +1,9 @@
+{
+  "name": "fishtools-python-benchmark-example",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "index.js",
+  "files": ["index.js", "scripts", "README.md", "LICENSE"],
+  "license": "MIT",
+  "engines": {"node": ">=24.15.0"}
+}

package/manual/docs/examples/script-plugin/scripts/benchmark.py

@@ -0,0 +1,23 @@
+"""用 Python 标准库计算确定性的示例指标。"""
+
+import json
+import sys
+
+
+def main():
+    config = json.loads(sys.argv[1])
+    samples = config["samples"]
+    threshold = config["threshold"]
+    average = sum(value * value for value in range(1, samples + 1)) / samples
+    ok = average >= threshold
+    result = {
+        "ok": ok,
+        "metrics": {"samples": samples, "average": average},
+        "reason": "达到阈值" if ok else "平均值低于阈值",
+    }
+    # 默认 ASCII JSON 转义避免 Windows 控制台编码影响进程间协议。
+    print(json.dumps(result, ensure_ascii=True, separators=(",", ":")))
+
+
+if __name__ == "__main__":
+    main()

package/manual/docs/kernel-generation.md

@@ -0,0 +1,97 @@
+# 大日志、开发重载与隔离文件探测
+
+本阶段承接十一模块拆分，仍以 `@yanglaofish/fishtools` 一个 npm 产品交付。内部模块不单独发布，产品版本不会因本地验收自动提升。
+
+## 大量输出持续落盘
+
+普通 `ctx.runProcess` 默认保持严格缓冲模式，超过默认 4 MiB 上限返回 `OUTPUT_LIMIT`。需要解析完整 stdout JSON 的动作继续使用此模式。大量持续输出应显式选择流式模式：
+
+```js
+const result = await ctx.runProcess('程序', ['参数'], {
+  outputMode: 'stream',
+  summaryBytes: 65536,
+  timeout: 120000,
+});
+// 完整输出由上下文交给日志模块；返回 stdout/stderr 仅是有限尾部。
+return { exitCode: result.exitCode, bytes: result.outputBytes,
+  summary: result.stdout, truncated: result.outputTruncated };
+```
+
+直接调用 platform 的 `runProcess` 时，stream 必须提供 `onOutput({stream,message})`。它逐块等待消费者，两条流共享消费顺序，慢磁盘形成背压。`summaryBytes` 是每条流返回摘要的 UTF-8 字节预算（0 到 1 MiB）；`outputBytes` 统计原始输出字节，`outputTruncated` 明确标识摘要。取消、超时或消费者失败会终止执行，不把不完整结果伪装成完整输出。
+
+`ctx.log` 应被 await。未等待的调用也受写入队列预算约束；超过预算拒绝并使运行收尾失败。最终业务数据仍完整传给工作流和 CLI，不能以日志摘要代替业务数据。
+
+在 `flow.project.json` 中设置：
+
+```json
+{
+  "logs": {
+    "maxEvents": 1000,
+    "maxMemoryBytes": 1048576,
+    "maxEventBytes": 65536,
+    "maxPendingBytes": 8388608,
+    "maxDiskBytes": null,
+    "maxCachedRuns": 50,
+    "keepRuns": null
+  }
+}
+```
+
+- logs 独占完整事件、Markdown 落盘和缓存策略。事件尾部与独立步骤摘要各受 `maxEvents/maxMemoryBytes` 限制；两份缓存合计最多两倍 `maxMemoryBytes`，不含执行所必需的业务对象。
+- `eventsTruncated`、`eventCount` 和递增 `seq` 表达事件窗口；`stepSummaries` 保留步骤最新状态。步骤摘要超预算时 `stepsTruncated` 为 true，界面将无法确认的状态显示为“摘要已省略”。
+- `maxPendingBytes` 同时计算 JSONL 和 Markdown 待写字节。单条事件或最终业务结果本身超过预算也会明确报错，可按业务需要调整；它不允许任意大对象无界排队。
+- `maxDiskBytes` 限制每次运行约定日志文件总量，默认 null 不主动限制；磁盘或队列超限分别返回 `LOG_DISK_LIMIT`、`LOG_QUEUE_LIMIT`。不静默截断完整记录。
+- core 限制已结束运行缓存数量。巨大业务结果不长期留在历史缓存；历史 `result.json` 以带 `outputTruncated` 等标记的摘要存储。完整最终结果另存于 `events.jsonl` 的 `run.result` 及 Markdown。
+- `keepRuns` 沿用历史保留策略。只删除工具约定日志文件，保留插件产生的业务文件和子目录；清理失败显示维护警告，不改写已完成的业务结果。
+
+新日志增加 `run.meta.json` 归属元数据；旧记录继续兼容。过大的旧 `result.json` 读取会明确返回 `LOG_METADATA_LIMIT`，避免一次性载入巨大文件。
+
+## 完整日志分页
+
+```sh
+fst logs
+fst logs <运行ID> --cursor 0 --limit 65536 --json
+```
+
+无 ID 列出历史；有 ID 读取 Markdown 正文页。返回 `text/cursor/nextCursor/hasMore/totalBytes`，下一页使用 `nextCursor`。游标为 UTF-8 字节位置，不能落在字符中间；单页至少 4 字节、最多 256 KiB。自定义项目时每次带上 `--project`。
+
+TUI 的 `/logs` 运行详情按 **p** 打开完整分页，关闭当前正文视图后选择上一页、下一页或刷新。Web 运行结果的 **完整日志** 页签提供同样操作。实时日志和主面板只显示有限摘要；分页可以读取运行中的已落盘部分，也可在开发重载后读取原运行。
+
+应用接口为 `app.readLogPage(id,{cursor,limit})`，HTTP 接口为经过认证的 `GET /api/runs/:id/logs`。原完整读取 API 保留兼容，大日志查看应使用分页接口。
+
+## 开发源码自动重载
+
+```sh
+fst plugin link ./我的插件
+fst --watch
+fst --watch web --port 8765
+```
+
+`--watch` 显式启用；无参数模式要求真实交互终端，不支持一次性 run/pack/logs 命令或只读运行包。监督器监听 link 源目录、项目配置、插件链接状态和显式 `--config` 文件，合并连续保存，等待当前运行及管理操作结束后关闭旧应用，再启动新进程。完整 ESM 依赖图会重新加载，包括入口导入的子文件。
+
+启动失败会保留监听，修复源码后重试；关闭超时尝试终止，未确认退出前不启动新宿主。扫描在隔离进程执行，跳过链接及 node_modules、.git、.flow、dist，目录/条目/深度预算或扫描超时会明确提示未完整监听。
+
+Web 保持端口和令牌，前端自动重连、刷新能力目录，保留当前未保存草稿。TUI 重建会话，未保存草稿不跨重启保留。插件内存状态不会迁移；这是等待空闲后的开发重启，不承诺业务运行中无缝升级。
+
+## 隔离文件探测
+
+```js
+const result = await ctx.fs.readDirectory('待检查目录', { limit: 100 });
+if (result.status === 'ok') {
+  // result.value 是 [{name,type}]；incomplete 表示仍有未列出的条目。
+  return { entries: result.value, incomplete: result.incomplete };
+}
+return { status: result.status, reason: result.reason };
+```
+
+`ctx.fs.stat`、`ctx.fs.readDirectory` 在独立 Node 子进程执行。相对路径绑定项目目录，自动合并当前运行的取消信号。项目策略：
+
+```json
+{"fileAccess":{"timeout":2000,"maxConcurrent":2,"maxPending":16,"allowRemote":false}}
+```
+
+超时包含排队；状态为 `ok/missing/timedOut/cancelled/skipped/error`，另有 `incomplete/reason`。默认跳过显式 UNC/网络设备路径，需要远端探测时显式开启 `allowRemote`。目录只列一级，不读文件正文；stat 使用 lstat，不跟随符号链接。
+
+本地挂载不能仅靠路径识别，隔离进程提供超时返回和资源预算。超时或取消后尚未回收的 worker 仍占并发预算，避免不断生成新进程；app.close 回收探测器，未完全回收会明确报告。真实 NFS/SMB 故障仍需要现场验证，操作系统内核 I/O 不保证立即可杀。此能力不构成安全沙箱，也不自动改写插件直接调用 node:fs 的行为。
+
+模块接口细节见 [logs](../packages/fst-logs/README.md)、[platform](../packages/fst-platform/README.md)、[core](../packages/core/README.md)。

package/manual/docs/modules.md

@@ -0,0 +1,57 @@
+# 模块架构与维护
+
+Fishtools 在同一仓库维护十一模块，使用 npm workspaces 连接，继续以 `@yanglaofish/fishtools` 统一安装和交付。现有 core、SDK、pack、Web 包名保留；新增模块使用 `@mytools/fst-*`。这些内部包不单独发布。
+
+## 按问题定位
+
+| 模块 | 目录 | 负责的问题 |
+| --- | --- | --- |
+| core | `packages/core` | 应用装配、运行协调、取消和关闭、管理接口 |
+| SDK | `packages/sdk` | 插件协议、错误、schema、引用和条件契约 |
+| platform | `packages/fst-platform` | 子进程、环境探测、npm、通用文件读取和代理选路 |
+| logs | `packages/fst-logs` | 日志落盘、缓存、历史、保留、体积统计 |
+| workflow | `packages/fst-workflow` | 步骤执行、条件、分支、并行和提前结束语义 |
+| plugin | `packages/fst-plugin` | 插件加载、契约检查、权限预检、动作宿主、服务生命周期 |
+| workspace | `packages/fst-workspace` | 工作流持久化、模板、安装批次、租约和回收 |
+| devtools | `packages/fst-devtools` | 脚手架、validate、lint、离线资料 |
+| CLI | `packages/fst-cli` | 命令入口与交互终端 |
+| pack | `packages/pack` | 依赖闭包、环境和运行时复制、清单、归档 |
+| Web | `plugins/web` | 官方 Web 插件、HTTP、前端和页面数据投影 |
+
+各目录的 README 列出公开入口、边界和定向测试。问题单与改动说明应写明负责模块及受到影响的消费者。实际维护人员尚未分配；本次没有虚构 CODEOWNERS。
+
+## 依赖规则
+
+- SDK 为底层共享契约；主入口不加载 schema 校验器，校验器通过 `/schema` 加载。
+- platform、logs、workflow 依赖 SDK；plugin 依赖 SDK/platform；workspace 组合 plugin、workflow 与平台文件能力。
+- devtools 提供开发工具；pack 使用 platform、devtools 和 SDK。pack 通过声明快照获得工作流与插件资料，不访问活动宿主。
+- core 组合业务能力，按需加载可选 pack；CLI 使用 core 和管理工具。Web 通过服务参数接收应用接口。
+- 包的普通依赖和 peer 依赖均禁止循环。跨包只能使用 package.json 的 exports 入口，生产者和消费者都应有回归覆盖。
+
+`tests/modules.test.js` 检查内部依赖无环、入口可解析、无跨包相对导入及内部依赖声明。新增包或接口时同步该约束。
+
+## 已迁移的接口边界
+
+`createRunLogs().start(initial)` 创建运行写入器，提供 `append`、`snapshot`、`markdown`、`finish` 和 `save`。logs 拥有事件缓存和串行写入；core 保存运行控制状态。写入失败会沿 Promise 返回调用方；core 立即观察收尾拒绝，向运行查询返回 `LOG_WRITE_FAILED`，并保留原 `done` 拒绝与已有业务错误，避免只读取运行 ID 的 Web 调用导致进程退出。
+
+插件普通动作上下文默认不再附带整个 application；项目路径与只读状态独立传给宿主。服务扩展（包括 Web）继续获得应用接口。这是职责分离，不是安全沙箱。
+
+`app.exportSnapshot(options)` 返回脱离活动宿主的声明数据；`app.pack()` 和 `app.packPlan()` 保持调用方式。pack 还兼容传入提供 `exportSnapshot` 的应用对象。快照中的 CLI 根目录用于收集发行载荷，不构成 pack 对 CLI 的代码依赖。
+
+## 交付与兼容
+
+`fst` 的实现入口位于 fst-cli，npm 聚合入口和 Windows/Linux 启动器同步使用它。用户命令不变。现有 core 的 `/process`、`/bundle`、`/environments` 公共入口保留转发。
+
+普通发行携带可选 pack 依赖，支持安装后继续导出；只读发行裁剪该依赖并禁止修改与重新打包。工作区模板随 workspace 包交付。`fst docs modules` 可离线阅读本文。
+
+模块拆分没有迁移用户数据或改变工作流格式、SDK_VERSION。后续完整能力阶段扩展了日志元数据与 JSONL 结果记录，保留旧记录读取；没有提升产品版本。开发验收归档用于本地测试，不代表已发布。
+
+后续代理和权限能力沿用这十一模块：platform 负责网络策略及 HTTP/子进程代理环境；plugin 负责权限声明和执行前检查；workspace 持久化独立的工作流副本；core 保存项目设置、安排受影响插件的更新；CLI、Web 负责交互与提示。内部包仍随同一个 npm 产品交付。
+
+## 完整能力阶段
+
+- 大量输出持续落盘、有界事件及步骤摘要、UTF-8 分页、队列和磁盘预算：由 logs 主导，platform 提供可背压的 stream 输出。
+- 开发自动重载：core 的监督器等待业务空闲后重启隔离应用进程，CLI 提供 --watch，Web 自动重连；完整刷新 ESM 依赖。
+- 网络挂载卡顿的隔离探测：platform 提供带超时、取消、并发和未回收预算的只读探测，插件通过 ctx.fs 使用。
+
+三项现已落实到源码和各端入口，使用方式及边界见 [完整能力指南](kernel-generation.md)，离线可执行 `fst docs generation`。