@yanglaofish/fishtools 0.4.0 → 0.5.0

package/README.md

@@ -6,7 +6,7 @@
 
 交互终端支持选择能力、配置参数和流程编排；官方 Web 插件默认提供，原子 CLI 子命令用于自动化。三种入口共用应用服务。YAML、依赖锁和版本解析由系统维护，不要求普通用户手写。
 
-0.4.0 增加插件创建、离线校验、源码引用和安装批次回收，支持解释器候选、插件状态目录与输出编码，并改善 schema 诊断。输出不再按 schema 补默认值，插件须明确返回业务字段。此前版本的终端菜单、执行摘要、条件控制和离线开发手册继续可用。发布与验证状态见 [版本记录](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.4.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.4.0 增加插件创建、离线校验、源码引用和安装批次回收，支持解释器候选、插件状态目录与输出编码，并改善 schema 诊断。输出不再按 schema 补默认值，插件须明确返回业务字段。此前版本的终端菜单、执行摘要、条件控制和离线开发手册继续可用。发布与验证状态见 [版本记录](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.4.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/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`。

package/manual/docs/plugin-development.md

@@ -6,6 +6,8 @@
 
 从 0.4.0 起包含下文的 `plugin create/validate/link/gc`、编码选项、插件状态目录和环境候选能力；0.3.0 不包含这些新增接口。源码试用时将 `fst` 替换为 `npm run fst --`。0.4.0 的输出校验停止补默认值，迁移说明见下文。发布结果见[版本记录](releases.md)。
 
+从 0.5.0 起提供 `plugin lint`、代理规则、权限预检和按影响范围更新插件；开发引用可用 `--watch` 自动重启。旧插件仍能加载，但建议逐步补齐权限声明。
+
 ## 从已安装的工具查阅规范
 
 完整 npm 与便携发行包随附离线资料，包含本文、控制流规范、服务示例和可安装的[零依赖动作插件](examples/action-plugin/README.md)。无需克隆源码仓库：
@@ -71,6 +73,8 @@ JSON 序列化可能丢弃对象中的 `undefined`、函数或 Symbol，并将
 | `defaultConfig` | 可选的公开部署默认配置，生成运行包时使用；机密配置由目标机器另行提供 |
 | `dependencies` | 可选的插件 ID → semver 范围字典；被依赖插件必须另行安装并注册 |
 | `services` | 高级服务扩展；普通业务插件不需要使用。服务名在宿主内必须唯一，官方 Web 插件使用 `web` 服务 |
+| `requirements.privilege` | 可声明各平台的普通用户、管理员或目标资源权限；动作级声明覆盖插件级默认值 |
+| `preflight` | 对无法静态确认的权限进行只读预检，返回 `ok`、`blocked` 或 `unknown` |
 
 动作名建议只用字母、数字、下划线和短横线。输入输出优先采用对象，字段设置 `title` 和 `description`，需要严格拒绝额外字段时设置 `additionalProperties: false`。首版 Web 表单适合标准 JSON Schema；自定义字段组件、任意插件页面和外部 schema 解析不属于当前公开接入契约。
 
@@ -129,10 +133,12 @@ fst plugin remove my-flow-plugin
 
 也支持 npm 包标识或本地 `.tgz`；Web“插件管理”提供相同入口。本地路径以服务器所在机器为准。
 
-`plugin add <本地目录>` 是复制安装，源文件修改不会自动反映到已安装副本；重复 `add` 即可更新，无需先 `remove`。开发时使用下述引用模式。安装、移除、开发引用和 CLI 配置命令自动在管理模式下运行，不启动 runtime 服务；常驻 TUI/Web 保持维护模式保护。
+`plugin add <本地目录>` 是复制安装，源文件修改不会自动反映到已安装副本；重复 `add` 即可更新，无需先 `remove`。开发时使用下述引用模式。CLI 管理命令以独立进程运行；常驻 TUI/Web 对需要重启的服务显示本次维护提示，仅更新受影响的插件及依赖它的插件。
 
 插件安装在 `.flow/installations/<随机安装批次ID>` 新目录，验证加载成功才切换状态，失败保留原配置。安装禁用 npm 生命周期脚本；TS 发布前编译，原生库及其目标平台资源由作者准备。核心不审核平台兼容性，也不自动重建原生库。工作流运行期间不能变更插件。
 
+移除插件前会检查所有已保存工作流（含分支、并行和子工作流）的引用，并显示受影响工作流；仍被其他插件依赖时始终拒绝。确认接受工作流暂时无法运行后，可用 `fst plugin remove 插件ID --force` 跳过工作流引用保护。工作流文件不会随卸载删除，重新安装插件后仍可使用。
+
 业务 npm 库写入 `package.json.dependencies`，开发库写入 `devDependencies`。插件间依赖另外写在定义的 `dependencies: {'other-plugin': '^1.0.0'}`，用于宿主版本检查和打包闭包；被依赖插件也需安装并注册。
 
 ### 创建、校验与开发引用
@@ -144,11 +150,31 @@ fst plugin validate ./my-plugin --json
 fst --project ./test-project plugin link ./my-plugin
 ```
 
-脚手架生成 ESM 包、嵌套输入动作、业务判定、`node:test`、README 和 MIT LICENSE，不依赖内部 SDK，拒绝覆盖已有目录。按实际支持范围调整平台和架构声明。
+脚手架生成 ESM 包、嵌套输入动作、普通用户权限声明、业务判定、`node:test`、README 和 MIT LICENSE，不依赖内部 SDK，拒绝覆盖已有目录。按实际支持范围调整平台、架构和权限声明。
+
+`validate` 检查包身份、SDK 范围、schema、动作/命令、条件、环境和权限等声明，不安装依赖、不执行动作或 `runtime.apply`。它会导入模块，因此模块顶层代码会执行，只校验可信插件。错误返回退出码 1；警告不改变成功退出码。未声明平台/架构/权限、当前平台不匹配、同层未声明的 required 字段给出警告。JSON Schema 允许开放字段，因此 required 的位置提示不自动判定 schema 无效。校验无法代替硬件和业务环境测试。
+
+报告的 `notes` 明确提示“输出 required 字段是否实际返回无法静态确认”。文本模式显示说明，`--json` 将说明放在 JSON 内；不会因这条固定说明新增错误或警告。插件模块顶层应避免输出，防止导入时自行打印的内容污染 CLI 输出。
+
+### 插件质量检查
+
+```sh
+fst plugin lint ./my-plugin
+fst plugin lint ./my-plugin --json
+```
+
+`lint` 先扫描源码，再执行与 `validate` 相同的声明检查；同样只用于可信插件，会导入模块顶层，不执行动作或服务初始化。声明错误退出码为 1，质量警告退出码为 0。报告保留 `valid`、`plugin`、`diagnostics`，说明放在 `notes`。
 
-`validate` 检查包身份、SDK 范围、schema、动作/命令、条件和环境等声明，不安装依赖、不执行动作或 `runtime.apply`。它会导入模块，因此模块顶层代码会执行，只校验可信插件。错误返回退出码 1；警告不改变成功退出码。未声明平台/架构、当前平台不匹配、同层未声明的 required 字段给出警告。JSON Schema 允许开放字段，因此 required 的位置提示不自动判定 schema 无效。校验无法代替硬件和业务环境测试。
+- `MISSING_TITLE` / `MISSING_DESCRIPTION`：动作、命令缺少非空标题或描述；动作别名命令可复用目标动作元信息。递归检查 input/output 的字段标题。
+- `BOOLEAN_SCHEMA`：布尔 schema 合法，只提示字段级表单信息不足，不判定契约错误。
+- `CONSOLE_LOG`：在可达 JavaScript 中识别直接 `console.log` 调用，包括顶层及辅助函数；引导动作和命令使用 `log` / `print`。注释和字符串不作为调用。
+- `UNDECLARED_DEPENDENCY`：检查字面量 import、export-from、动态 import、CommonJS require，以及 ESM 中由 `node:module` 的 `createRequire(import.meta.url)` 建立的加载器。认可 package.json 的 dependencies、optionalDependencies、peerDependencies，devDependencies 不替代运行依赖；跳过 Node 内置模块。
 
-`link` 将源码绝对路径保存到当前工作区，不复制源码，不安装源码目录的 npm 依赖；需要依赖时先在插件目录自行安装。源码修改后退出并重新启动 fst，TUI/Web 随新宿主读取修改；当前进程的模块缓存不会热更新。工作区迁移后需要重新 link。正常 `add` 同名包可替换开发引用，`remove` 解除引用，不删除源码。分发收集源码的发布文件和生产依赖快照，不把开发路径链接带给最终用户。
+源码扫描从 `package.json.main`（默认 index.js）沿本地依赖访问 `.js/.mjs/.cjs`，不执行扫描到的函数、不遍历无关测试文件、不跟随到包外或 node_modules。源码位置含行列号。特殊模块映射、解析失败或无法访问的本地文件给出检查不完整的警告；`.js` 按插件 ESM 契约解析。保守跳过文件内有局部重名或重赋值的 console/require，可能漏报其他作用域里的调用；动态拼接依赖和函数别名不保证识别。它不是完整依赖分析或安全扫描。
+
+不提供 `--fix`；不会自动补平台、空标题或 additionalProperties:false，不猜测硬件关键词，不检查 run 的真实返回值。开放对象是合法契约，自动封闭可能破坏业务输入。
+
+`link` 将源码绝对路径保存到当前工作区，不复制源码，不安装源码目录的 npm 依赖；需要依赖时先在插件目录自行安装。可用 `fst --watch` 在业务空闲后自动重启开发进程并重新加载完整模块图；未启用 watch 时手工重启。工作区迁移后需要重新 link。正常 `add` 同名包可替换开发引用，`remove` 解除引用，不删除源码。分发收集源码的发布文件和生产依赖快照，不把开发路径链接带给最终用户。
 
 ### 安装批次清理与恢复
 
@@ -165,6 +191,63 @@ fst plugin gc --apply
 
 服务插件的 `runtime` 初始化和生命周期见本文末尾；普通动作插件无需添加此字段。
 
+### 网络代理
+
+工作区在 `flow.project.json` 的 `network` 下保存代理规则。优先级为动作、插件、工作区；规则缺省时继承运行进程的代理环境变量。每层可选择 `inherit`（继承环境）、`direct`（直连）或 `profile`（指定代理配置）。例如仅让一个插件使用代理，其中一个动作直连：
+
+```json
+{
+  "network": {
+    "profiles": {
+      "office": {"httpEnv": "HTTP_PROXY", "httpsEnv": "HTTPS_PROXY", "noProxy": "localhost,127.0.0.1"}
+    },
+    "default": {"mode": "direct"},
+    "plugins": {
+      "my-flow-plugin": {
+        "default": {"mode": "profile", "profile": "office"},
+        "actions": {"local-check": {"mode": "direct"}}
+      }
+    }
+  }
+}
+```
+
+可用 `fst network show` 查看当前规则、`fst network set 规则.json` 保存；TUI 的 `/config` 和 Web 设置页也可编辑。TUI/Web 会列出已安装插件与动作最终采用的模式，并提示指向已删除插件或动作的规则。保存代理、插件或日志设置前，会在 `.flow/backups/` 备份原 `flow.project.json`，界面和命令会显示具体路径；需要恢复时先关闭项目，再将备份复制回 `flow.project.json`。其他实例已修改代理规则时，旧实例会拒绝覆盖，重新读取后再保存。代理地址可写 `httpUrl`/`httpsUrl`，含账号密码的地址只能用 `httpEnv`/`httpsEnv` 引用环境变量，避免把凭据写入项目文件。可用 `noProxy` 或 `noProxyEnv` 排除地址。代理按每次动作调用解析；分发包只携带所选插件使用的规则和配置引用，不携带环境变量的值，目标机需自行提供。离线场景可设 `direct`。
+
+覆盖保存已有工作流时，原始 YAML 会先写入 `.flow/workflow-backups/工作流ID-编号.yaml`；若要恢复，先停止项目并确认目标文件，再将备份复制回 `workflows/工作流ID.yaml`。删除工作流会把原文件移入 `.flow/deleted-workflows/`，可按同样方式复制回去。插件状态切换保留 `.flow/plugins.previous.json`；若更新与恢复都失败，当前宿主停止接受新的运行，重启前应先核对磁盘配置和插件状态。
+
+动作通过 `ctx.http.fetch(url, options)` 发起 HTTP 请求，或通过 `ctx.runProcess(file,args,options)` 启动子进程；两者会应用本次动作的规则。插件直接使用其他网络库、直接创建子进程或自行覆盖代理环境时，应自行接入规则；宿主不拦截其网络调用。插件命令和服务使用插件级规则。
+
+### 权限声明与执行前检查
+
+插件可以为所有动作声明默认权限，也可以为某个动作覆盖：
+
+```js
+export default {
+  id: 'my-flow-plugin',
+  requirements: {
+    privilege: {
+      linux: {level: 'user'},
+      win32: {level: 'user'}
+    }
+  },
+  actions: {
+    systemCheck: {
+      requirements: {
+        privilege: {
+          linux: {level: 'root', reason: '读取受限系统状态', remediation: '以有权限的账号执行'}
+        }
+      },
+      // 其余动作声明略
+    }
+  }
+};
+```
+
+Linux 支持 `user/root/resource`，Windows 支持 `user/administrator/resource`。高权限和资源要求必须填写 `reason` 与 `remediation`；`resource` 和 Windows `administrator` 还需提供插件或动作的 `preflight(input,{platform,signal,fs})`，返回 `{status:'ok'|'blocked'|'unknown',reason?,remediation?}`。预检应只做检查，使用 `fs.stat`/`fs.readDirectory` 等只读探测，并响应取消；超时或异常会成为 `unknown`。旧插件没有声明仍可运行，开发工具会提醒补充声明。
+
+`fst workflow check 工作流ID --json` 可预览权限要求。已确认缺少的权限会在运行前阻止；预检无法确认时，TUI/Web 会询问用户，CLI 可为本次调用加 `--allow-unverified-privileges`。这不会绕过已确认不足的权限，也不代替插件作者在执行时处理系统拒绝访问。
+
 | 字段 | 用途 |
 | --- | --- |
 | `config` | 经配置 schema 验证并填入默认值的插件配置 |
@@ -194,6 +277,28 @@ fst plugin gc --apply
 
 `runProcess` 默认无 Shell，参数用数组。支持 `cwd`、`env`、`signal`、`timeout`（默认 30 秒）、`maxBuffer`（stdout/stderr 各默认 4 MiB）和可选的 `onOutput({stream,message})`。普通非零退出返回 `{exitCode,stdout,stderr}`，动作应自行决定是否抛出业务错误；缺失程序、超时、取消、输出超限抛错，并等待进程树回收。不要把密码或令牌写入日志。
 
+默认 buffer 模式的 `OUTPUT_LIMIT` 限制子进程返回缓冲及实时输出队列，不是 run.md 的文件体积阈值。触发后只能取得超限前已记录的部分输出，不能当作完整结果。可以按业务明确提高有限的 maxBuffer；大量连续日志可选择 `outputMode:'stream'`，完整落盘、内存只保留尾部摘要并显式标记截断。超大业务结果也可由程序写到 outputDir 内的文件，stdout 返回摘要或路径。
+
+### 不可信路径与网络挂载
+
+插件与宿主运行在同一进程。对 PATH、用户输入、HOME 或外部设备目录等不可信路径，不要使用 readdirSync/statSync 等同步 FS API：阻塞会占住宿主事件循环。异步 FS 能避免这一类主线程阻塞，但异常挂载仍可能长期占用 I/O 线程和资源。
+
+探测插件应限制扫描目录、深度和并发；在访问前识别已知 UNC、映射网络盘、远程挂载及自动挂载目录，默认跳过或要求用户显式选择。不要仅为识别网络路径就先递归遍历或 realpath 目标；识别策略应尽量使用本地挂载元信息，并承认符号链接、挂载变化及不同平台实现会导致遗漏。不要把所有 FUSE 或 9p 文件系统直接等同于网络文件系统。
+
+记录 skippedRemote、timedOut、incompleteScan 和具体 warnings，将“没有扫描”与“工具不存在”区分。检查上下文 signal，在取消或超时后停止安排新任务，限制仍未结束的请求数量，不无限重试。
+
+Promise.race 只能让调用方停止等待，不能中断正在执行的操作系统文件访问；即使 readFile 支持 AbortSignal，也不保证取消单个底层 I/O 请求，见 [Node 文件系统说明](https://nodejs.org/docs/latest-v24.x/api/fs.html#fspromisesreadfilepath-options)。NFS hard 挂载默认可无限重试；“所有 NFS 调用都无法被 SIGKILL 中断”并不准确，具体受内核与操作状态影响，见 [Linux NFS 手册](https://man7.org/linux/man-pages/man5/nfs.5.html)。
+
+当前源码已提供 `ctx.fs.stat/readDirectory` 隔离只读探测，独立进程执行 I/O，超时/取消返回结构化状态，未回收进程继续占并发预算。它不替代插件直接使用的任意文件 I/O，也不保证内核 I/O 立即可中断。`runProcess` 的可执行文件查找仍可能访问 PATH 中的挂载目录，当前超时从进程启动后开始，不构成文件访问隔离。请将工作区、插件与日志目录放在可靠的本地存储上；接口见[完整能力指南](kernel-generation.md)。
+
+### 查看日志体积（当前开发分支，尚未发布）
+
+TUI `/logs` 与 `/config` 的“查看日志体积”按需统计当前日志根目录下 UUID 运行目录中的 run.md、events.jsonl、result.json、run.meta.json 文件长度，包括尚未结束的运行。显示字节数、文件数、当前项目的保留次数；读取失败时明确标注统计不完整。
+
+不读取日志正文、不递归业务目录、不跟随目录或文件链接、不删除任何文件。共享输出目录会统计其他项目的同类文件；它不是项目独占体积，也不是磁盘实际分配空间。运行中数值可能继续增长。
+
+默认 keepRuns:null，不自动清理；按次数清理仅作用于已结束运行。当前源码另提供 maxDiskBytes 单次运行磁盘预算、有界事件/步骤摘要和分页读取；配置与三端入口见[完整能力指南](kernel-generation.md)。
+
 相对程序路径及 `PATH` 中的相对目录以传入的 `cwd` 为基准；未传 `cwd` 时使用宿主当前目录。例如 `runProcess('./tools/check', [], {cwd: resourceDir})` 调用插件资源目录内的工具，不改变其他并发动作的工作目录。
 
 通过动作上下文调用时，stdout/stderr 在子进程执行期间自动产生 `type:'log'` 事件，`stream` 为 `stdout` 或 `stderr`，工作流事件保留 `stepId` 和 `callPath`。例如同一动作分别位于 `main/group/left`、`main/group/right`，日志按各自调用归属显示。写入 stderr 本身不会把运行改成失败。
@@ -452,11 +557,11 @@ TUI `/pack` 选择来源并展示资源字节数；CLI 支持 `--plan` 和 `--en
 - [基础动作插件](../plugins/examples/index.js)：文本处理、结果文件和 Python 调用。
 - [官方环境检查插件](../plugins/environment/index.js)：目标环境前提与诊断报告。
 - [SDK](../packages/sdk/index.js)：`definePlugin`、`FlowError` 与 SDK 版本。
-- [宿主校验](../packages/core/src/host.js)：加载、依赖、配置、动作输入输出和服务名检查。
+- [宿主校验](../packages/fst-plugin/src/host.js)：加载、依赖、配置、动作输入输出和服务名检查。
 - [外部插件接入测试](../tests/application.test.js)：仓库外插件安装、运行与移除。
 - [完整 Python 脚本插件](examples/script-plugin/README.md)：嵌套输入、解释器候选、业务不通过、异常和条件预设。
 
-当前源码提供 `plugin create`、`plugin validate`、开发引用和批次回收；没有单独的 `plugin lint`、运行中热重载、插件市场审核流程。SDK 尚未独立发布到公共 npm；独立插件使用普通 ESM 默认导出即可。
+当前源码提供 `plugin create`、`plugin validate`、`plugin lint`、开发引用和批次回收；`--watch` 在业务空闲后重启整个开发进程，不迁移运行中的插件内存状态。没有插件市场审核流程。SDK 尚未独立发布到公共 npm；独立插件使用普通 ESM 默认导出即可。
 
 ## Cordis 共享服务与生命周期
 
@@ -488,6 +593,7 @@ export default {
 | `provides` | 可选服务名数组，默认空；名称须唯一，推荐 `插件前缀.能力`，不能覆盖 Cordis 内建属性 |
 | `inject` | 可选必需服务名数组，默认空；提供者必须在本插件的 dependencies 中直接声明 |
 | `apply(ctx, config)` | 必需函数；ctx 为锁定版本的 Cordis 上下文的受管视图，config 已经校验；在应用 ready 阶段执行，可返回 Promise |
+| `updatePolicy` | `automatic` 允许在空闲时定向重启，`maintenance` 要求本次更新得到维护确认；缺省为 `maintenance` |
 
 服务缺失、重复、循环、初始化错误或声明后未发布，会使宿主启动失败并给出插件定位。输入列表顺序不决定就绪顺序，依赖激活由 Cordis 管理。插件列表中的 `runtime.status` 为 `pending/ready/failed/stopped`，可包含缺失服务及错误信息。
 
@@ -497,12 +603,16 @@ Fishtools 等待 `ctx.on('dispose', async () => ...)` 的清理完成并报告
 
 ### 维护与 Web 资源
 
-- 有 runtime 插件时，安装、移除或修改插件配置会要求先进入维护模式，避免同时打开两套连接。
-- TUI `/plugins` 可进入维护模式并恢复服务；CLI 的 add/remove/link/configure 自动使用管理模式，也兼容显式 `--maintenance`。维护模式不持久化，默认重启恢复服务。
-- 维护模式停止 runtime 插件的动作和命令，普通插件仍可使用；声明校验仍执行，不能借维护模式加载无效插件定义。
+- 安装、移除或修改配置时，宿主只重启变更插件及依赖它的插件。工作流运行期间仍拒绝变更。受影响的 runtime 若采用 `maintenance` 策略，TUI/Web 会显示名单并要求本次操作确认；无关的 runtime 保持连接。
+- CLI 的 add/remove/link/configure 使用独立管理进程，兼容显式 `--maintenance`。TUI 仍可手动进入全局维护模式，供需要完全停服的操作使用；退出维护模式后恢复服务。
+- 候选定义先完成校验，重启失败会尝试恢复旧作用域。作者仍须正确实现 dispose，外部业务副作用不由宿主自动回滚。
 - 现有 `services.web` 仍为兼容的启动工厂；应用持有其返回的 close 句柄。`app.close()` 先关闭这些句柄，再关闭业务宿主，重复关闭安全。
 - 打包选择包含 Web 时，按 `services.web` 声明选取实际提供者，连同其传递插件依赖一起导出，不要求官方包名。完整便携包关闭 Web 选项时，仅省略非必需的 Web 提供者；工作流或其他插件确实依赖它时仍保留。
 - 活动 Web 提供者不能移除、替换或修改配置；TUI 插件管理可先停止 Web。普通插件更新不会关闭标准发行版中的 Web 管理入口。外部安装的 Web 提供者若被 npm 重新生成到新目录，也需先停止。
-- 没有实现运行中无缝热替换。服务撤销后消费者动作/命令被撤销；恢复后按 Cordis 生命周期重新激活。
+- 定向更新不是运行中无缝热替换。服务撤销后消费者动作/命令被撤销；恢复后按 Cordis 生命周期重新激活。
 
 完整的两个独立插件见 [服务示例](../examples/service-plugins/README.md)，验证见 `tests/runtime.test.js`、`tests/lifecycle.test.js`、`tests/service-pack.test.js`。
+
+## 新增内核能力
+
+大输出动作可显式使用 `ctx.runProcess(...,{outputMode:'stream'})`，保留完整落盘内容并返回有限尾部；普通调用保持严格缓冲语义。文件探测使用 `ctx.fs.stat/readDirectory`，开发链接插件使用 `fst --watch` 自动重启完整模块图。配置、例子及资源预算见 [完整能力指南](kernel-generation.md)。

package/manual/docs/releases.md

@@ -2,6 +2,16 @@
 
 产品名称 Fishtools，公共 npm 包名 `@yanglaofish/fishtools`，启动命令 `fst`。`0.x` 定位为早期可用版本。内部 `@mytools/*` 包随主包捆绑，不单独发布；内部插件 API 版本独立维护。
 
+## 0.5.0 内核能力与日常操作
+
+- 大量进程输出可以完整落盘、内存只保留有限摘要；CLI、TUI、Web 支持分页查看完整日志。开发引用插件可用 `--watch` 在业务空闲后重启完整进程；网络挂载文件探测在隔离进程中执行并设置超时与资源预算。
+- 已保存工作流可复制为独立副本，便于修改参数后串行运行并对照日志；覆盖保存及删除流程均保留恢复备份。卸载仍被工作流引用的插件会列出引用并要求明确强制操作，并发工作流编辑不能绕过检查；插件间依赖与活动 Web 仍受保护。
+- 代理策略可按工作区、插件、动作分别选择继承环境、直连或代理配置。TUI/Web 显示每个已安装动作最终采用的模式及失效引用；插件通过 `ctx.http.fetch` 和 `ctx.runProcess` 使用相应规则。代理凭据通过环境变量引用，导出包只携带选中插件需要的规则。
+- 插件可声明 Linux root、Windows 管理员或目标资源权限，并提供只读预检。已确认不足的权限会阻止运行并留下失败日志；无法确认时由用户决定是否仅本次继续。Web 插件详情展示原因与处理提示，开发工具对缺少声明给出警告。
+- 插件更新仅重启变更插件及依赖它的插件。有状态插件可声明自动更新或本次维护确认；更新失败尝试恢复旧实例。TUI 和 Web 显示受影响插件，未改动的服务继续运行。
+
+工作流格式和内部 SDK 版本保持兼容；旧插件无需立即补权限声明。设置代理后应在目标环境验证连通性，使用 Windows 管理员或具体资源权限的插件应实现自己的预检。完整使用说明见[插件开发](plugin-development.md)与[内核能力](kernel-generation.md)。
+
 ## 0.4.0 第三方插件开发体验
 
 - 增加 `fst plugin create/validate/link/gc`：生成零依赖插件、离线检查声明、引用开发源码、预览并备份清理旧安装批次。源码修改后需重启宿主。
@@ -13,6 +23,8 @@
 
 用户已于 2026-10-12 授权审查、验证后推送和发布；是否发布完成以本版本 GitHub Release 与验收记录为准。
 
+**发布完成：** [v0.4.0 发布流程](https://github.com/yanglaofish/Fishtools/actions/runs/38206420406)全部成功，Windows/Ubuntu 各 230 项测试、自包含包及断网 Docker 检查通过。npm 官方注册表 `latest` 为 `0.4.0`，公开 tarball 与已验收归档校验值一致；[GitHub Release](https://github.com/yanglaofish/Fishtools/releases/tag/v0.4.0)包含三个归档及 `SHA256SUMS`。发布 tag 固定于 `f529244`，后续验收记录提交不改变发行产物。
+
 ## 0.3.0 终端交互与插件输出
 
 - 终端顶层按工作流、插件、工具和配置组织；命令历史保留未提交草稿，工作流编辑与执行互不覆盖。