@yanglaofish/fishtools 0.3.0 → 0.5.0

package/manual/docs/plugin-development.md

@@ -4,6 +4,10 @@
 
 `print()` 用户输出接口、主面板默认折叠和 Ctrl+O 展开从 0.3.0 起纳入发行包；0.2.0 不包含这些能力。
 
+从 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)。无需克隆源码仓库：
@@ -18,7 +22,7 @@ fst docs --export ./fishtools-manual
 
 `fst docs <主题>` 输出正文，`--path` 输出本地路径；`--export` 导出全部资料到新目录，已有目标会拒绝覆盖。资料按当前安装版本定位，不依赖当前工作目录，不启动插件或服务。TUI 中通过 `/docs` 选择主题，在内置阅读器查看。
 
-导出目录保留相对链接，可离线浏览规范与示例。`plugins/`、`packages/`、`tests/` 中附带的源码仅供阅读，保留其 LICENSE；它们不是另一份可执行宿主或完整源码工作区。实际可安装示例位于 `docs/examples/action-plugin` 和 `examples/service-plugins`。内部 SDK 不承诺已作为独立公共 npm 包发布，首次开发可直接使用零依赖示例。
+导出目录保留相对链接，可离线浏览规范与示例。`plugins/`、`packages/`、`tests/` 中附带的源码仅供阅读，保留其 LICENSE；它们不是另一份可执行宿主或完整源码工作区。实际可安装示例位于 `docs/examples/action-plugin`、`docs/examples/script-plugin` 和 `examples/service-plugins`。内部 SDK 不承诺已作为独立公共 npm 包发布，首次开发可直接使用零依赖示例。
 
 ## 0.2.0：条件控制与运行观察
 
@@ -37,7 +41,7 @@ fst docs --export ./fishtools-manual
 
 | 约束 | 开发者要求 | 当前宿主检查 |
 | --- | --- | --- |
-| 标识与版本 | `id` 必须等于 npm 包名，`version` 必须等于包版本并使用 semver；升级时保持已有动作标识稳定 | 检查 ID 非空、重复；检查 SDK 和已声明插件依赖的版本兼容性；尚未自动比对包名/包版本 |
+| 标识与版本 | `id` 必须等于 npm 包名，`version` 必须等于包版本并使用 semver；升级时保持已有动作标识稳定 | 宿主检查 ID 非空、重复和 SDK/依赖兼容性；`plugin validate` 比对包名/版本，开发引用也要求身份一致 |
 | 能力元数据 | 每个公开动作必须提供清楚的 `title`、`description`、`input`、`output`、`run` | 检查 `run` 是函数；编排前检查 input/output schema；标题和描述的质量由作者负责 |
 | 输入输出 | 显式提供有效的 JSON Schema，推荐对象形式声明类型、必填项、默认值和字段说明；无参数或无输出也要声明空对象 schema | 编排前校验 schema 声明，调用时用 Ajv 验证实际输入输出；返回值经过 JSON 序列化边界 |
 | 判定预设 | `conditions` 提供标题、相对输出路径、比较符和值；不提供可执行判定函数 | 加载时检查格式、比较符、危险路径及已声明的输出字段 |
@@ -53,6 +57,8 @@ JSON 序列化可能丢弃对象中的 `undefined`、函数或 Symbol，并将
 
 每份 schema 独立编译并缓存，`$id` 不会在不同插件或安装批次之间共享注册。插件升级可以保留相同 `$id` 并调整约束；定义内部的 `$ref` 正常解析，不支持隐式引用另一个插件曾注册的 schema。
 
+输入与配置校验继续应用 `default`；动作和交互命令的输出校验只验证实际返回值，不补默认值。旧插件若依靠输出 schema 自动生成 `ok` 等字段，必须在 `run` 返回值中明确赋值。诊断消息和 `details[].jsonPointer` 提供完整 JSON 指针（如 `/benchmark_config/model_name`），`schemaPath` 标明约束位置；`required` 放在顶层时只能报告顶层缺失，不会猜测作者原本想放在哪个子对象。
+
 无参数或无输出时，分别使用 `{type:'object', properties:{}, additionalProperties:false}`，动作返回 `{}`。JSON Schema 的布尔形式也受支持：`true` 接受任意值，`false` 拒绝所有值；为了生成字段表单与输出选择器，推荐明确声明对象和字段。缺省、`null`、数组、字符串和数值都不能代替 schema 声明。原有动作/子工作流的 `schemaVersion: 1` 格式保留；旧插件若要参与编排，需要补齐有效的 input/output 声明。正常返回且输出校验通过即执行成功，不要求返回额外的 `success:true`。
 
 ## 插件定义字段
@@ -67,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 解析不属于当前公开接入契约。
 
@@ -125,14 +133,121 @@ fst plugin remove my-flow-plugin
 
 也支持 npm 包标识或本地 `.tgz`；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'}`，用于宿主版本检查和打包闭包；被依赖插件也需安装并注册。
 
+### 创建、校验与开发引用
+
+```sh
+fst plugin create my-plugin ./my-plugin
+fst plugin validate ./my-plugin
+fst plugin validate ./my-plugin --json
+fst --project ./test-project plugin link ./my-plugin
+```
+
+脚手架生成 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`。
+
+- `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 内置模块。
+
+源码扫描从 `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` 解除引用，不删除源码。分发收集源码的发布文件和生产依赖快照，不把开发路径链接带给最终用户。
+
+### 安装批次清理与恢复
+
+```sh
+fst plugin gc
+fst plugin gc --apply
+```
+
+默认只预览。执行清理会重新核对状态，并在 `.flow/installation-backups/` 创建每个候选批次的 `.tgz` 备份后删除该批次。当前批次、上一批次及活动宿主的租约批次保留；未知目录和链接不清理。`.flow/plugins.previous.json` 保存上一次成功切换前的状态。备份也占用空间，应在确认不再需要恢复后自行删除。
+
+恢复时先退出该工作区所有 fst 进程，将对应备份解压回 `.flow/installations/`（归档自带批次子目录）；需要退回上次插件列表时先另存当前 `plugins.json`，再用 `plugins.previous.json` 替换它。源码引用不包含源码副本，恢复前还需确保源码路径可访问。旧版 0.3.0 不登记租约，清理前必须退出旧版宿主。异常退出遗留 `.flow/plugin-mutation.lock` 时，确认没有活动修改进程再手工移除该空锁目录。
+
 ## 动作上下文
 
 服务插件的 `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 验证并填入默认值的插件配置 |
@@ -140,6 +255,8 @@ fst plugin remove my-flow-plugin
 | `runId`、`stepId`、`callPath` | 运行和嵌套步骤定位 |
 | `outputDir` | 本次运行的可写结果目录 |
 | `resourceDir` | 插件包目录，用于定位脚本 |
+| `projectDir` | 当前工作区根目录；可编辑便携包使用其包外工作区 |
+| `stateDir` | 当前插件跨运行持久目录，与 outputDir 无关；只读项目或无应用的独立宿主为 undefined |
 | `getService(name)` | 获取本插件 runtime.inject/provides 声明的已就绪服务；未声明或不可用时抛错 |
 | `environments` | 按声明和来源选择解析的环境；包含解释器路径，随包环境另有资源根目录 |
 | `runProcess(file,args,options)` | 通用进程调用，自动关联当前日志与取消信号 |
@@ -148,6 +265,10 @@ fst plugin remove my-flow-plugin
 
 返回值必须可 JSON 序列化，输入输出经 Ajv 校验。插件在宿主进程中执行，属于可信代码；同步阻塞代码不能被取消信号抢占。
 
+可写应用在调用前创建 `.flow/plugin-state/<插件ID的SHA-256十六进制摘要>/`。固定长度目录避免 scoped 包名、Windows 大小写和长文件名问题；卸载不自动删除此目录，分发也不自动携带其中数据。插件自行处理原子写入、并发和数据版本。跨插件交换业务结果使用工作流输出或公开服务，不依赖其他插件的私有目录。只读精简包不创建持久状态，需要状态的插件应提示使用可编辑工作区。
+
+`runProcess` 新增 `encoding`，默认 `utf8`，也可用 `utf16le`、`gbk` 等当前 Node TextDecoder 支持的编码；实时日志和返回文本采用同一编码，并正确处理跨块字符。示例：`runProcess('wsl',['-l','-v'],{encoding:'utf16le'})`，具体编码应以目标命令版本为准。Windows PowerShell 的编码和 CLIXML 是不同问题，宿主不自动猜编码或解析 CLIXML。输出上限仍按每个流的原始字节计量，默认 4 MiB；超限回收进程树并抛 `OUTPUT_LIMIT`，不返回伪装完整的截断结果。
+
 主面板默认展示步骤状态，Ctrl+O 展开或收起各步输入输出和技术日志。普通 `log` 与子进程 stdout/stderr 默认折叠；失败摘要始终直接显示。希望用户直接看到的进度或结果，显式使用 `await print('报告已保存', {file})`。`print` 沿用日志通道，以 `type: 'log', audience: 'user'` 持久化，工作流中自动带上步骤归属。动作和交互命令都支持，不应直接用 `console.log` 向 TUI 打印。
 
 若 Python 程序的部分输出需要直接展示，可使用 `runProcess(file, args, {onOutput: ({stream,message}) => stream === 'stdout' ? print(message) : undefined})`。回调按数据块触发；作者可先缓存成完整行再选择性 print。完整进程输出仍自动保存在诊断日志，print 的用户提示另外保留。写入 stderr 本身不等同执行失败，动作仍须按退出码决定抛错。
@@ -156,6 +277,28 @@ fst plugin remove my-flow-plugin
 
 `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 本身不会把运行改成失败。
@@ -321,7 +464,7 @@ async function run({executable, text}, {resourceDir, runProcess, signal}) {
 
 ## 平台声明与责任边界
 
-插件可声明 `platforms: ['win32', 'linux']` 和 `architectures: ['x64', 'arm64']`；未声明的旧插件继续可用。声明由作者负责，核心不据此拒绝加载、调用或导出；导出时显示声明不匹配的提示。核心检查接口、依赖收集与运行错误，不静态分析路径、系统 API，也不替开发者测试业务兼容性。
+插件可声明 `platforms: ['win32', 'linux']` 和 `architectures: ['x64', 'arm64']`；未声明的旧插件继续可用。声明由作者负责，核心不据此拒绝加载、调用或导出；CLI 启动、运行日志及导出计划都会提示对应的平台不匹配。核心检查接口、依赖收集与运行错误，不静态分析路径、系统 API，也不替开发者测试业务兼容性。
 
 ## 注册斜杠命令
 
@@ -359,7 +502,7 @@ environments: {
   python: {
     source: 'host',
     allowedSources: ['host', 'bundled'],
-    executable: 'python3',
+    executable: ['python3', 'python'],
     version: '>=3.11',
     packages: { numpy: '2.x' },
     artifacts: {
@@ -377,12 +520,14 @@ environments: {
 ```
 
 - `host`：目标机器或容器内部提供；不携带 artifacts，也不自动检查/安装依赖。插件负责检查版本、库、设备和错误提示。
-- `bundled`：作者提供完整、可迁移的目标环境目录（包括所需库与许可证），工具按目标收集；目录和 executable 均为使用 `/` 分隔的相对路径。缺少所选资源、越界或目录循环时报打包错误。核心不自动下载 Python 或运行 pip。
+- `bundled`：作者提供完整、可迁移的目标环境目录（包括所需库与许可证），工具按目标收集；目录和 executable 均为使用 `/` 分隔的相对路径。默认采用 bundled 时必须声明非空 `artifacts`；静态校验检查各目标项的字段和包内路径，但不要求包含开发机平台。实际导出缺少所选资源或遇到目录循环时仍会报错。核心不自动下载 Python 或运行 pip。
 - `tool`：首版只允许环境名 `node`，使用 Fishtools 自带的 Node。
 - `version`、`packages` 为作者元数据；宿主不将它们当作已验证的事实。`allowedSources` 决定导出时可以切换哪些来源，缺省只能使用 source。
 
 动作使用上下文 `environments.python.executable` 获得最终解释器路径，随包环境另有 `root`。继续通过 `runProcess(executable, args, {signal})` 调用。声明不会替换插件代码里自行写死的命令。
 
+host 来源可声明有序候选数组，调用前按当前工作区和 PATH 选择第一个存在的程序，返回其绝对路径；不承诺该程序版本满足业务要求。单字符串声明继续透传。用户可在 `flow.project.json` 设置 `environments: {"插件ID": {"python": {"executable": "F:/miniconda/envs/example/python.exe"}}}`；显式覆盖只用于 host，找不到就报错，不回退到其他 Python。`source` 覆盖仍可单独使用。候选在目标机调用时解析，打包不会固化本机候选解析结果。
+
 完整插件的所有动作和命令随插件保留，所以其动作声明的环境均参与计划。不同动作的同名环境可以有不同资源，但导出时同一个插件/环境名的来源覆盖统一生效；允许来源取交集。相同资源路径只复制一次，不自动合并不同 Python 环境或推断版本兼容性。
 
 TUI `/pack` 选择来源并展示资源字节数；CLI 支持 `--plan` 和 `--environments 来源.json`：
@@ -405,17 +550,18 @@ TUI `/pack` 选择来源并展示资源字节数；CLI 支持 `--plan` 和 `--en
 6. **部署检查**：导出包含该动作的工作流，在包外目录运行；验证路径中有空格和中文、包目录只读且结果目录可写的情况。声明支持 Windows 和 Linux 时，应分别实测；依赖设备或驱动的能力注明所需环境和未验证项。
 7. **文档检查**：插件 README 写清支持平台、环境前提、配置示例、输入输出、错误行为、副作用、许可证与兼容范围。改变既有输入输出或行为时说明迁移方式并合理升级版本。
 
-插件无需伪装成跨平台：仅适用 Linux 的 NPU 检查可以明确声明 Linux 前提，在其他平台给出可理解的错误。首版没有通用的 `platforms` 元数据执行门禁，不要添加一个未经宿主实现的字段后假定平台限制会自动生效。
+发布前先运行 `fst plugin validate <目录>`，再按平台声明逐项实际测试。仅适用 Linux 的 NPU 插件应明确声明 Linux；宿主对声明不匹配给出告警并记录到运行日志，继续允许执行。没有声明的旧插件继续兼容；不会根据描述中的 NPU、驱动等关键词猜测兼容性，也没有 `reject/allow/warn` 配置门禁。
 
 ## 参考实现与当前边界
 
 - [基础动作插件](../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)：嵌套输入、解释器候选、业务不通过、异常和条件预设。
 
-当前已有接入文档、可参考实现和运行时校验；尚未提供 `fst plugin create` 脚手架、`fst plugin lint` 命令、独立的完整插件定义 schema 或插件市场审核流程。SDK 也尚未独立发布到公共 npm；不要把仓库内部包名理解为已经可以在线安装。
+当前源码提供 `plugin create`、`plugin validate`、`plugin lint`、开发引用和批次回收；`--watch` 在业务空闲后重启整个开发进程，不迁移运行中的插件内存状态。没有插件市场审核流程。SDK 尚未独立发布到公共 npm；独立插件使用普通 ESM 默认导出即可。
 
 ## Cordis 共享服务与生命周期
 
@@ -447,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`，可包含缺失服务及错误信息。
 
@@ -456,12 +603,16 @@ Fishtools 等待 `ctx.on('dispose', async () => ...)` 的清理完成并报告
 
 ### 维护与 Web 资源
 
-- 有 runtime 插件时，安装、移除或修改插件配置会要求先进入维护模式，避免同时打开两套连接。
-- TUI `/plugins` 可进入维护模式并恢复服务；CLI 使用 `fst --maintenance plugin add ...`、`fst --maintenance configure ...`。维护模式不持久化，默认重启恢复服务。
-- 维护模式停止 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,29 @@
 
 产品名称 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`：生成零依赖插件、离线检查声明、引用开发源码、预览并备份清理旧安装批次。源码修改后需重启宿主。
+- schema 路径校验统一支持带类型的动态字段；错误给出完整 JSON 指针和约束位置。动作及命令输出只验证，不再填充默认值；输入和配置保留默认值。
+- `runProcess` 支持显式编码并统一实时日志与返回文本。`host` 环境支持有序解释器候选及显式路径覆盖；显式路径不存在时不回退。
+- 插件获得按工作区及 ID 隔离的 `stateDir`，平台不匹配给告警；独立 CLI 管理命令自动使用维护模式。新增可安装的 Python 脚本插件和中文开发说明。
+
+升级时退出旧版宿主，再使用批次清理；旧版 0.3.0 不登记活动安装租约。若插件依赖输出 schema 的 `default`，请在动作返回值中明确填写对应字段。工作流格式和内部 SDK 版本不变；没有加入运行中热重载或平台强制拒绝策略。
+
+用户已于 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 终端交互与插件输出
 
 - 终端顶层按工作流、插件、工具和配置组织；命令历史保留未提交草稿，工作流编辑与执行互不覆盖。

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

@@ -52,12 +52,12 @@ Fishtools 核对基线：`838d572f0eff85f759b3c1118abb9dda616a4113`。
 
 | 公共能力 | 当前状态及证据 | 建议补齐的契约 |
 | --- | --- | --- |
-| 插件加载、依赖、生命周期和共享服务 | 已有：[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 可通过统一请求通道交互 |
+| 插件加载、依赖、生命周期和共享服务 | 已有：[host.js](../../packages/fst-plugin/src/host.js)、[runtime.js](../../packages/fst-plugin/src/runtime.js) | 继续使用 Cordis；新增订阅、Hook、面板注册也跟随插件作用域注销 |
+| 动作发现、调用与结果校验 | 已有 catalog、invoke、commands、input/output：[host.js](../../packages/fst-plugin/src/host.js) | 稳定的第三方调用门面；身份和调用归属由内核赋值，统一经过 Hook/授权/日志 |
+| 顺序、分支、并行、条件停止 | 已有：[engine.js](../../packages/fst-workflow/src/engine.js) | 沿用现有控制节点和状态，不为 LLM 另造一套编排协议 |
+| 会话与插件状态存储 | 尚无持久会话；[terminal/view.js](../../packages/fst-cli/src/terminal/view.js) 的命令历史在内存中 | 延迟落盘、会话索引、恢复、按插件命名空间存储数据和版本；工作区状态与会话状态分开 |
+| 执行记录、日志和用户输出 | 已有 run、events、run.md、log/print：[application.js](../../packages/core/src/application.js)、[run-feed.js](../../packages/fst-cli/src/terminal/run-feed.js) | 统一事件版本与顺序号；进度更新、结果摘要、产物引用；历史与实时使用相同渲染输入 |
+| 公共交互与界面扩展 | 插件交互命令已有 input/select/show/confirm：[terminal/session.js](../../packages/fst-cli/src/terminal/session.js) | 能力查询、结构化确认/表单/详情；由内核仲裁并发提问和焦点；动作与 Hook 可通过统一请求通道交互 |
 | 执行 Hook | 仅有生命周期回调和运行事件订阅 | 注册前置决策与后置通知；过滤范围、超时、取消、顺序、异常归属和注销契约 |
 | 授权请求、模式和审计 | 尚无统一机制 | 操作与资源范围声明、允许/拒绝/询问/无意见、用户规则与可选决策插件、真实 TUI 请求 |
 | 受管进程与后台工作 | 已有 runProcess、取消/超时、stdout/stderr；运行可在主面板持续显示 | 给受管操作接入权限与调用归属；长期后台任务句柄随后按实际需要增加，不立刻建设新调度系统 |

package/manual/docs/roadmap.md

@@ -1,9 +1,19 @@
 # Fishtools 路线图与当前状态
 
-更新：2026-10-11，条件控制与运行观察阶段。本文是当前状态入口；早期设计和实施计划保留历史背景，发生冲突时以最新明确决策及验收记录为准。
+更新：2026-10-12，第三方插件开发体验阶段。本文是当前状态入口；早期设计和实施计划保留历史背景，发生冲突时以最新明确决策及验收记录为准。
 
 ## 当前所处阶段
 
+### Issue #3 本轮增量与后续演进（2026-10-12，尚未发布）
+
+- 本轮实现：有限 `plugin lint`、`validate` 的运行返回值边界提示、`/logs` 与 `/config` 按需查看日志文件体积。补充不可信路径、网络挂载、异步取消与进程输出上限的开发约定。完整范围和验收见 [验收记录](verification.md)。
+- 不采纳：将合法布尔 schema 判错、关键词猜平台、自动补空标题/平台或 additionalProperties:false。Windows CP936 中文乱码尚未在本地受支持 Node 版本复现，不自动改为 GBK 输出。
+- **大日志治理**：现已由 logs 统一负责完整落盘、有界事件/步骤摘要、历史分页、写入队列和磁盘预算；platform 的显式 stream 模式关闭完整缓冲并提供背压。依赖完整 stdout 的业务保持严格缓冲模式。
+- **开发自动重载**：现已提供 `fst --watch` 与 `fst --watch web`，合并源码修改、等待任务空闲、关闭旧宿主并启动新进程；支持完整 ESM 依赖刷新、启动失败修复恢复、关闭预算和 Web 重连。运行中无缝替换和插件内存迁移仍不在本阶段范围内。
+- **隔离文件探测**：现已实现 `ctx.fs.stat/readDirectory`，独立 Node 进程执行 I/O，支持超时/取消、并发和排队预算、远程路径策略及结构化诊断。未确认回收的 worker 继续占预算。真实故障挂载仍需现场验证，底层不可中断 I/O 不保证立即回收。
+
+0.4.0 已发布，包含 GitHub #1/#2 的插件创建、校验、源码引用、批次回收、状态目录、环境候选及编码/契约修复。见[本轮规范](superpowers/specs/2026-10-12-plugin-developer-experience.md)、[实施计划](superpowers/plans/2026-10-12-plugin-developer-experience.md)与[验收记录](verification.md)，发布结果见[版本记录](releases.md)。运行时热重载、长度条件、截断模式及平台拒绝策略留待后续。以下“本地试用”描述记录之前日志阶段的历史过程。
+
 当前增量：TUI 日志阅读与导航修复，处于**本地试用、待用户体验确认**阶段。首页 F4 进入统一运行记录，支持多个工作流的多次执行；不使用 `/resume`，避免与未来 LLM 会话恢复混淆。实时与历史使用同一阅读面板，默认简洁结果/错误，完整诊断按需查看。试用方式见 README，用户确认前不发布新版本。
 
 后续交互调整：`/workflows` 收纳新建、编辑、保存和可恢复删除；`/config` 配置工具，`/plugin` 管理插件及插件配置，插件名进入二级能力菜单。`/run` 补全工作流，执行过程留在主面板，多任务与配置操作共存；F4/日志页供详细回看。仍为本地试用，未发布。
@@ -20,7 +30,7 @@
 
 | 原始任务 | 当前状态 | 证据与剩余范围 |
 | --- | --- | --- |
-| 1. SDK、Host、工作流模型与执行 | 首版完成，已扩展服务管理 | `packages/sdk`、`core/src/host.js`、`runtime.js`、`engine.js`、`workflows.js`；动作/子流程、引用校验、失败停止、共享服务与受管清理 |
+| 1. SDK、Host、工作流模型与执行 | 首版完成，已扩展服务管理和模块拆分 | `packages/sdk`、`fst-plugin`、`fst-workflow`、`fst-workspace`；动作/子流程、引用校验、失败停止、共享服务与受管清理；[模块架构](modules.md) |
 | 2. 应用服务、CLI、外部插件 | 首版完成 | `application.js`、`plugins.js`、`process.js`；安装、配置、日志、取消及仓库外插件接入 |
 | 3. 官方环境检查和示例 | 首版完成，硬件验证有缺口 | `plugins/environment`、`plugins/examples`；真实 NPU 验证未完成 |
 | 4. 自包含分发 | 首版完成，已扩展 | `packages/pack`；按工作流依赖收集、Windows/Linux 包、Docker 挂载；现默认完整可编辑工具 |
@@ -74,7 +84,7 @@
 | --- | --- | --- | --- |
 | N1. Cordis 服务与生命周期 | 插件之间共享能力、依赖就绪、关闭清理与失败定位 | 已实现，本地与便携包验收通过 | 提供者/消费者示例、61 项测试、维护模式、Web 资源归属；远端 CI 见验收记录 |
 | 控制流与运行观察增量 | 条件、并行、提前结束、实时子进程日志和双界面观察 | 当前源码本地验收通过，未声明发布 | 控制协议、取消首因、递归依赖、真实界面操作及 Windows/Linux 验收与发布记录 |
-| N2. 第三方开发体验 | 可独立使用的模板、类型提示、示例和接入契约测试 | 离线手册随包、/docs 阅读与导出、零依赖示例已完成；脚手架与 lint 未完成 | 仓库外作者仅按文档完成动作插件、服务插件与打包；契约检查不承担业务平台认证 |
+| N2. 第三方开发体验 | 可独立使用的模板、示例和接入契约测试 | 离线手册、脚手架、validate/lint、link 开发重载均已实现；类型声明仍待单独规划 | 仓库外作者仅按文档完成动作插件、服务插件与打包；契约检查不承担业务平台认证 |
 | N3. 真实业务插件验证 | 用实际业务检验服务契约，例如 SSH 连接与远程检查共享 | 候选方向，具体插件待实际需求确定 | 两个独立插件复用同一服务，包含取消、错误、关闭与离线分发测试 |
 | N4. 按需求扩展 | LLM/外部 Agent、Kubernetes、多机能力等 | 方向记录，未作实施承诺 | 每个扩展单独明确场景、接口和验收，不进入核心的默认依赖 |
 
@@ -88,3 +98,6 @@ N1 的历史验收对应提交 `061f0e4`，[Windows / Ubuntu CI](https://github.
 - 分发和工作区：`deployment.md`
 - 实测范围与缺口：`verification.md`
 - 历史初始设计：`superpowers/specs/2026-10-09-workflow-cli-design.md`
+## 当前完整能力阶段
+
+承接十一模块拆分，大日志流式落盘与有界缓存/分页、源码监听开发重载、隔离文件探测现已落实到源码。CLI/TUI/Web 已接入。详细行为与边界见 [完整能力指南](kernel-generation.md)，本地验收记录见 [verification](verification.md)。运行中无缝升级、真实故障 NFS/SMB 现场验证、远端 CI 和正式发布分别记录，不从本地实现推定完成。

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

@@ -34,12 +34,12 @@
 ## 文件结构
 
 - `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/fst-plugin/src/host.js`：Cordis 生命周期、插件动作目录。
+- `packages/fst-workspace/src/workflows.js`：存取、静态校验、引用与闭包。
+- `packages/fst-workflow/src/engine.js`：执行快照、顺序调用、日志和取消。
+- `packages/fst-platform/src/process.js`：无 Shell 的程序调用及回收。
 - `packages/core/src/application.js`：共用应用服务。
-- `packages/core/src/plugins.js`：安装、移除与锁定外部插件。
+- `packages/fst-workspace/src/plugins.js`：安装、移除与锁定外部插件。
 - `packages/pack/`：生产依赖收集、运行时和归档，独立于执行包。
 - `packages/core/bin/flow.js`：CLI。
 - `plugins/environment/`：目标环境检查。

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

@@ -18,9 +18,9 @@
 
 ## 任务与验收
 
-1. `packages/core/src/process.js`、`tests/process.test.js`：先复现相对 executable 与 cwd 不一致；验证含空格目录、相对 PATH、绝对程序、缺失程序、取消和超时。修复只影响查找基准，不修改全局 cwd。
+1. `packages/fst-platform/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 仍有效、无效值仍拒绝。
+3. `packages/sdk/validation.js`、`tests/application.test.js`：真实安装带 $id 的配置插件、升级、安装无关插件及移除；验证新旧同 ID schema 不串用、嵌套本地 $ref 仍有效、无效值仍拒绝。
 4. 跑相关回归及 Windows/WSL 验证，独立审查修复 diff；更新文档与验收记录，提交本地分支。
 
 ## 审查重点

package/manual/docs/superpowers/plans/2026-10-12-kernel-generation.md

@@ -0,0 +1,22 @@
+# 完整内核代际演进实施计划
+
+**目标：** 完成大日志、开发自动重载、隔离文件探测三个子项目，并贯通 CLI/TUI/Web 与分发。
+
+**规范：** [完整能力阶段设计](../specs/2026-10-12-kernel-generation-design.md)。用户已要求完整继续实施；按既有授权推进。
+
+**执行：** 使用 dispatching-parallel-agents 分配彼此不重叠的底层模块，主执行者负责进程流和应用/界面整合；每项先运行失败测试再实现。最终一次独立整分支审查。
+
+**约束：** 中文文档和注释；保留原 buffer 语义；不删除用户数据；十一模块单向依赖；新接口通过 exports；Node 24.15.0；生产输出不能静默截断。
+
+## 任务与文件
+
+- [x] 日志：`packages/fst-logs/src/run-logs.js` 及私有辅助文件，`tests/log-streaming.test.js`。实现 bounded cache、受限写入队列、磁盘预算与 `page`。只改本模块与自身测试/README。兼容现有日志测试。
+- [x] 文件探测：`packages/fst-platform/src/file-probe.js`、`file-probe-worker.js`，`tests/file-probe.test.js`、fixture。实现隔离 I/O、并发/排队/超时/取消/回收预算；公开 `/fs`。只改这些文件和平台 manifest。
+- [x] 开发监听：新增 `packages/core/src/development.js` 和私有 worker/support、`packages/fst-cli/src/development.js`，修改 CLI 入口；`tests/development-watch.test.js`。监督进程等待 idle 后重启、失败恢复与回收；不直接修改 application.js，约定读取 app.developmentStatus()。
+- [x] 主线进程与应用：`fst-platform/src/process.js`、core/application.js、fst-plugin/host.js；进程 stream 背压、ctx.fs、日志策略/分页接口、历史缓存预算与 developmentStatus。新增集成测试。
+- [x] 界面：TUI 有界 RunFeed 与完整日志分页入口；Web 日志分页和开发重连；CLI logs 查询。测试真实功能和保留现有交互。
+- [x] 验收：各任务定向测试、全量测试、npm 构建及离线验收、整分支独立审查、文档更新和本地提交。
+
+## 审查重点
+
+生产环境慢写入导致队列增长；超大单条事件；UTF-8 分页切断；超时但未退出的 worker；用户关闭时排队请求；业务运行中的多次源码修改；启动错误后修复；CLI/TUI/Web 同时复用日志策略；新 worker 进入 npm 文件清单。

package/manual/docs/superpowers/plans/2026-10-12-modular-kernel.md

@@ -0,0 +1,40 @@
+# FST 模块化内核实施计划
+
+> 执行方式：使用 superpowers:executing-plans 在当前会话逐项实施，完成后进行独立整分支审查。用户已授权开始演进；保留当前工作目录，在专用 Git 分支实施。
+
+**目标：** 建立十一模块的职责与单向依赖，迁移实际实现和测试，保持产品交付兼容。
+
+**架构：** SDK 共享契约；platform/logs/workflow/plugin/workspace 提供能力；core 组合；CLI/Web 展示；devtools/pack 负责开发与发行。
+
+**技术栈：** Node >=24.15.0、ESM、npm workspaces、node:test，保留现有依赖版本。
+
+**设计：** [模块化内核](../specs/2026-10-12-modular-kernel-design.md)
+
+## 全局约束
+
+中文文档与注释；不改 SDK_VERSION、用户配置格式、日志格式或公开 npm 包名；不删除用户数据；内部包禁止循环与跨包私有路径导入。
+
+## 审查重点
+
+从已安装聚合包再次导出时的模块根目录解析；只读包对打包工具的裁剪；Web 生命周期与服务调用兼容；日志落盘失败和并发关闭；模板与离线文档资源路径。
+
+## 任务
+
+- [x] 1. 包结构与架构约束：新增 tests/modules.test.js，观察缺少新包/错误依赖时失败；迁移文件并为各包设置 exports、生产依赖和中文 README；同步 lock。
+- [x] 2. 真实职责迁移：日志模块提供运行写入器与快照；core 移除写日志细节；插件宿主接受独立项目上下文；pack 接受受限导出视图和发行根。新增真实行为测试，先失败后实现。
+- [x] 3. 消费者和交付迁移：CLI、Web、测试、脚本改走公开入口；CLI 启动器、模板、离线文档与许可收集同步更新。保留已有 core 公开子入口。
+- [x] 4. 运行定向和完整测试、构建 npm 开发归档、离线安装与再次导出；独立审查整分支，补回归并修复。记录验收与模块维护规则，提交本地分支。
+
+## 执行记录
+
+- 已建立基线：上一阶段提交 2d3316b，完整 241 项测试通过。本轮先执行架构失败测试再迁移。
+- 架构约束先因缺包和 exports 失败；迁移 36 个实现文件、建立十一模块后通过。接口测试先失败后实现；日志与应用行为定向 34/34，CLI/开发插件/文档定向 20/20，打包与依赖定向 7/7 通过。
+- 第一次 npm 构建和完整回归 247/247 通过；独立审查发现日志保存失败可能导致 Web 进程退出、Web model 发布文件缺失。两项先复现，再修复，定向 29/29 通过。详见[审查记录](../reviews/2026-10-12-modular-kernel-review.md)。
+- 修复后重新构建 npm 归档，284 个生产包；以该归档完成最终全量 **250/250**，零失败、零跳过，153.0 秒。全部任务完成，本地分支保留，未推送或发布。
+
+## 实施裁定
+
+- core 对 pack 使用可选 peer 依赖，普通聚合包包含 pack，只读包省略该依赖边。原因：保持只读裁剪和可编辑包再导出能力。代价：需要真实归档与安装测试维护依赖配置。
+- core 向 pack 提供声明快照及 CLI 发行根目录，pack 不依赖 CLI 实现。原因：避免包依赖循环。代价：发行布局改变时同步快照根目录及交付测试。
+- 保留原目录的专用分支，并在验证后整体提交实现。原因：跨包迁移、依赖和消费方同步才能形成可运行提交；设计已独立提交。
+- 日志保存失败的未处理拒绝虽有历史成因，本阶段主动修复。原因：本轮明确要求写入失败可观察且不能产生未处理拒绝；core 负责运行状态，logs 负责写入失败传播。

package/manual/docs/superpowers/plans/2026-10-12-plugin-developer-experience.md

@@ -0,0 +1,50 @@
+# 第三方插件开发体验实施计划
+
+> 执行方式：使用测试先行；独立模块按 superpowers:dispatching-parallel-agents 并行实施，宿主集成在当前会话完成。用户已经授权实施。
+
+**目标：** 修复两个 issue 的明确缺陷，补齐第三方插件创建、校验、开发引用及宿主公共能力。
+
+**架构：** schema 路径与校验共用一个契约层；开发工具复用加载契约且不启动服务；应用层管理插件批次与工作区状态。保持现有动作、工作流及 Cordis 生命周期结构。
+
+**技术栈：** Node.js >=24.15.0、ESM、Ajv、Execa、Cordis、node:test。
+
+**规范：** ../specs/2026-10-12-plugin-developer-experience.md
+
+## 全局约束与审查重点
+
+中文文档及注释。保持 utf8 默认、维护模式保护和输出上限；不实现运行时热重载、长度伪字段、输出截断及关键词平台推断。只在受控临时工作区测试数据操作。重点检查动态键嵌套类型、显式解释器不回退、Scoped npm ID 状态目录、失效源码链接、清理时恢复批次和多进程安全。
+
+## 任务 1：契约与诊断
+
+文件：validation.js、contracts.js、workflows.js、新 schema-path.js 及契约测试。
+接口：validate(schema,value,label,{useDefaults=true})；共用 schema 路径解析。
+- [x] 增加动态字段、非法嵌套、完整字段路径、输出不补默认值的失败测试。
+- [x] 实现共用解析与校验策略，定向测试通过。
+
+## 任务 2：进程编码
+
+文件：process.js、tests/process.test.js。
+接口：runProcess(file,args,{encoding='utf8',...})。
+- [x] 增加 UTF16LE 分块及编码一致性的失败测试。
+- [x] 实现统一解码，验证取消/超时/字节限制回归。
+
+## 任务 3：插件工具
+
+文件：新 plugin-tools.js、fst.js、开发工具测试。
+接口：validatePluginDirectory(directory)、createPlugin(name,directory)。
+- [x] 添加身份/schema/平台诊断、无 runtime 副作用和脚手架可安装的失败测试。
+- [x] 实现 validate/create 与 CLI 输出及退出码，验证生成插件。
+
+## 任务 4：宿主和开发循环
+
+文件：plugins.js、application.js、host.js、environments.js、fst.js、pack 及测试。
+- [x] 添加源码引用重启、状态隔离、候选解释器、CLI 管理模式和安全批次清理的失败测试。
+- [x] 实现 link、受控清理预览/执行、CLI 管理模式、stateDir、平台告警与环境解析。
+- [x] 验证依赖加载、失败状态保持和分发快照。
+
+## 任务 5：文档与整体验收
+
+文件：plugin-development.md、roadmap.md、verification.md、docs/examples 新真实脚本插件及离线文档收集。
+- [x] 补齐公开契约、迁移说明、开发循环和脚本示例。
+- [x] 完整 npm test、npm run build、npm run dist:npm，审阅所有差异。
+- [x] 在功能分支提交并报告结果、后置能力与实际验证范围。

package/manual/docs/superpowers/reviews/2026-10-12-kernel-generation-review.md

@@ -0,0 +1,27 @@
+# 完整内核演进审查
+
+基线 `4d34df6`，分支 `codex/kernel-generation-complete`；依据[完整能力规范](../specs/2026-10-12-kernel-generation-design.md)进行 Standards / Spec 双轴独立评审，覆盖工作树新增文件。
+
+## Standards
+
+最终独立静态评审未发现阻断的硬规则问题：公开 exports、依赖方向、中文注释文档和本地分支符合约束。
+
+一个非阻断判断项：CLI 开发入口直接操作 TerminalSession 的 exiting/dirty 和 TerminalView 的 pending，与现有退出协调存在耦合。建议后续由会话暴露区分主动退出和开发重启的接口；本轮保留两者不同取消策略，有关闭失败、等待空闲和界面清理回归。
+
+首轮审查发现 journal.finish 后自动清理失败会再次 append，触发 LOG_CLOSED 并将成功业务标成失败。已先复现，再改为保存 LOG_PRUNE_FAILED 维护警告，TUI/Web 可见，业务结果保留。
+
+## Spec
+
+最终独立静态评审未发现新的重要需求偏差。核对 stream 背压与超时、日志缓存/队列/磁盘预算、开发进程等待空闲与失败恢复、ctx.fs 取消及关闭归属。
+
+主线复核额外完成回归修复：并发输出淘汰后的 TUI 空转录块增长；步骤事件被淘汰后误报待执行；巨大事件预览丢失序号；日志保存失败的运行未执行缓存预算；子进程退出后的最后一个流式消费者失去超时保护。独立步骤摘要受预算限制，无法确认时明确显示“摘要已省略”。
+
+启动期间关闭监督器的静态疑虑经真实子进程验证未复现，未据此增加重复重启逻辑。
+
+## 验证与限制
+
+完整测试 308 项：307 通过、0 失败、1 Windows 文件符号链接权限跳过，168.3 秒。包含 npm 离线发布预演、空缓存安装、新 worker 文件检查、安装后真实隔离探测、CLI 分页和再次导出。
+
+真实浏览器验证长日志分页、成功步骤状态、源码更新后的连接恢复、草稿保留和读取原运行日志。目录 junction 和模拟不可回收 worker 测试实际执行；真实故障 NFS/SMB、远端 Linux CI 不作为本地证据声称通过。
+
+汇总：Standards 已确认回归 1 项已修，保留非阻断维护建议 1 项；Spec 最终重要未解决问题 0 项。