@yanglaofish/fishtools 0.5.2 → 0.6.0

package/manual/docs/plans/2026-10-14-structured-reports.md

@@ -0,0 +1,77 @@
+# 统一业务报告协议与阅读
+
+## 目标与边界
+
+基线 `718676d`，沿用 `codex/plugin-defaults`。用户要求继续完成摘要、告警、建议、业务分组报告协议；已有授权直接编码、根据试用反馈调整。先记录设计与规范，再写失败测试并实现。本轮只改 SDK、内核展示、文档和测试，不改任何插件源码、不推送、不发包、不改版本号。
+
+插件判断业务含义，内核提供确定的校验和展示。告警等级不改变运行成功/失败状态，建议不触发命令、安装或网络请求。报告不需要 LLM。
+
+## 方案与协议
+
+采用有版本的结构化 JSON，沿用现有 output 持久化和表格排版。纯 Markdown 缺乏统一语义；仅靠输出 schema 的字段映射难以表达动态分组，因此不采用这两种作为新协议。
+
+`@mytools/sdk/reports` 提供 `reportSchema`、`createReport(content)`、`inspectReport(value)`。报告对象必填 `kind: 'fst-report'`、`version: 1`、非空 `title`；`createReport` 补齐 kind/version，复制并校验内容，不补业务默认值。其余字段可省略：
+
+- `summary`：非空文本摘要。
+- `alerts`：`{level: 'info' | 'warning' | 'error', message: 非空文本}` 数组，保留作者顺序。
+- `recommendations`：非空文本数组。
+- `sections`：分组数组；每组必填 `title`，可有 `summary`、`alerts`、`recommendations`，以及任意 JSON `data`。
+- 分组可有 `columns`（不重复的字段名数组）和 `titles`（字段名到显示标题的映射）；复用 `x-fst-table` 语义选择推荐列。复杂值、长值、未选列保留全文，窄屏回退字段阅读。
+
+v1 元数据拒绝未知字段和非法类型。业务扩展数据放在 section.data 或原输出中。报告可直接作为整个 output，也可以作为原业务 output 的 `report` 字段；后者推荐用于已有插件，避免改变工作流引用路径。报告使用普通文本，旧 Markdown 输出保持兼容。
+
+`inspectReport` 返回状态 `none`、`valid`、`invalid` 或 `unsupported` 及诊断信息，不修改值。无标记的同名普通字段不识别为报告；未来版本和损坏协议在阅读层明确提示并回退完整字段阅读，不使查看历史失败、不丢字段。通过 SDK helper 创建非法报告或声明 reportSchema 后返回非法数据时，按既有校验机制报错。
+
+## 展示与数据流
+
+SDK 只负责协议与校验；CLI 独立报告渲染器负责固定区块、文字清理、表格元信息转换。现有 readableValue 接入报告渲染器，主面板、步骤输出、详情和 m 阅读共用它。用户后续明确要求主面板直接显示报告，因此主面板默认展示标题、摘要、告警、建议、分组和表格；Ctrl+O 控制技术细节展开，m 保留专用阅读界面。过大结果仍受既有主面板内存预算控制，不再额外按 4096 字符省略报告正文。
+
+报告可从整个 output 或 output.report 识别；m 阅读时优先保留完整报告及同级业务字段，不能被旧 output.markdown 快捷路径吞掉。原始 JSON、落盘、工作流数据引用和会话恢复继续沿用现有机制，不另建报告存储。ANSI/终端控制符只在展示时清理。
+
+## 实施步骤
+
+1. SDK：新增 reports.js 与公开 exports；先测试构造复制、JSON 校验、非法字段/版本和普通对象不误判，再实现。公开 reportSchema 可直接用于动作/命令 output 或 output.properties.report。
+2. CLI：新增 report-presentation.js；readableValue 接入，原始模式不启用；复用表格，保留全文；RunViewer 的 m 优先协议；RunFeed 收起时补摘要。先测试宽窄屏、旧 Markdown、损坏/未来版本、中文和控制字符。
+3. 链路：以测试插件经真实 createApplication 执行动作、命令和工作流，校验返回、落盘重读、步骤详情及会话恢复，覆盖报告 error 告警不等于执行失败。
+4. 文档与验收：补开发规范完整示例、SDK/CLI 入口说明；定向测试、全量 npm test；以固定基线按 code-review 双轴审查，修正后记录证据并本地提交。
+
+## 审查重点
+
+- 旧对象包含 title/summary/report 不得误识别；Markdown 与报告共存不丢内容。
+- 空值、false、0、长文本和未知版本回退不丢数据；输出不被展示修改。
+- 窄屏与缩窗不破坏表格；恶意控制字符不逃逸到终端。
+- 校验与 helper 行为一致；输入 JSON 边界拒绝非 JSON 数据。
+- SDK 无界面依赖，CLI 不导入插件私有代码，不修改外部插件。
+
+## 验收记录
+
+### 执行信息与展示缩进修正（基线 16bfd83）
+
+- 用户纠正：输入、指令、用户执行了什么必须默认可见；Ctrl+O 折叠终端原始返回与内部诊断。报告结论、分组、表格等展示内容应缩进，提高层次。
+- 根因：主面板仍用 expanded 控制根输入及步骤输入，process 日志归入隐藏诊断；报告与执行标题共用左边界。默认态应展示根输入、步骤能力与输入、process 中真实程序/参数/目录/原脚本；异步 run.input 到达后更新有界输入，历史恢复仍可见。命令原文不重写、不拼接成另一条可执行命令。
+- 默认展示的报告和 print 反馈整体缩进两空格；报告结论及组标题再缩进两空格，组内数据与表格再缩进一级，表格计算扣除这些宽度。原始 JSON 不改变。宽窄屏、长内容、Ctrl+O 切换和会话恢复必须回归。
+- 所有带 stream 的 stdout/stderr（包括感叹号透传）作为原始返回由 Ctrl+O 展开；插件通过 print 提供的无 stream 用户展示继续默认可见。错误摘要仍默认可见，调用栈继续折叠。同步提示为“原始输出与诊断”，不再暗示输入或指令被隐藏。
+- 先写失败复现，修正上述边界，再双轴审查与验证；仅本地试用、不改插件、不发包。
+- 验证发现并补齐：初始/异步到达的输入摘要标记必须保留到历史恢复；输入原值阅读保留显式空值、空集合、false 和 0，不将字面字符串解析成布尔值或对象；print 的多行标量反馈整体缩进。相关新增测试均先失败再修正。
+- 全量 `npm test`：643 项，640 通过、3 个既有跳过、0 失败（`.cache/display-hierarchy-full.log`）。之后根据双轴审查修正空输入、展开后的字符串输入及标量反馈缩进；最终报告/终端/历史相关 202 项全部通过（`.cache/display-hierarchy-regression.log`）。两轴复核均无剩余问题；最后修改未重复计入此前全量测试。
+- 内核 TUI、规范和测试已更新；维持 0.5.3、本地试用，不修改插件、不推送、不发包。仍由 `fst-preview.cmd` 启动本地预览。
+
+### 主面板阅读修正（基线 1903242）
+
+- 根因：收起状态使用专用 reportSummary，主动省略分组数据。改为默认使用与详情相同的报告渲染；展开时沿用整体输出展示，避免同一区域重复报告。普通非报告结果的展示策略保持原样。
+- 先更新测试复现默认视图缺表格和长摘要被省略，再验证宽窄屏、恢复历史、超预算提示及全文。移除无人使用的摘要渲染器，同步规范。
+- 工作流步骤返回的报告也默认展示；最终输出转发相同报告时在结果区域展示一次，避免重复。新增步骤报告先失败再修正的回归。
+- 双轴审查后补齐：默认仅展示 report，同级 stdout/stderr 等技术输出由 Ctrl+O 展开；展开后转发报告也去重，以位置提示代替重复正文，保留步骤其他字段和原始记录。新增失败复现后，报告/终端/历史相关 196 项通过，最终两轴无剩余问题。
+- 本轮全量 `npm test`：639 项，636 通过、3 个既有跳过、0 失败（`.cache/report-main-full.log`）；全量启动后的审查修正已由上述 196 项相关回归验证（`.cache/report-main-regression.log`）。保持本地试用，不改插件源码、不推送、不发包。
+
+### 协议首轮实现
+
+- 协议与展示初始 5 项测试均先失败，再实现通过；新增真实命令/工作流执行、落盘重读、业务提醒与执行状态分离验证通过。
+- 嵌套报告在 41–44 列的缩窗复现表格越界，已扣除外层缩进后验证通过。
+- 大报告有界预览新增失败复现：主面板可能仅显示被截短的提醒且未指明摘要限制。已贯穿现有 `outputTruncated` / `eventTruncated`，预览残缺按摘要提示并回退阅读，不误报插件协议格式错误。报告专项现为 9 项通过。
+- 初轮报告、表格、运行阅读、模块入口及打包文件清单共 29 项通过；第一次全量 635 项：632 通过、3 跳过、0 失败。
+- Standards 审查发现 Symbol 键和数组附加属性可能在复制/落盘时丢失；已新增失败复现，改为检查自有属性及描述符，拒绝 Symbol、数组附加属性、空槽、非枚举属性和 getter。展示清理统一复用既有 `theme.cleanText`。修正后报告/终端/会话历史/模块测试 197 项通过。
+- Standards 复审补查根级 `kind/version` 访问器可能抛错的问题；新增失败测试后改为先检查属性描述符、再校验 JSON，诊断接口不执行 getter。最终报告专项 11 项通过，报告/终端/会话历史/模块回归 198 项通过。
+- Standards、Spec 双轴最终无剩余问题。演示数据的实际渲染保存于 `.cache/structured-report-preview.txt`。
+- 第二次全量 `npm test`：637 项，634 通过、3 跳过、0 失败，日志 `.cache/structured-report-final.log`。该轮启动后补入最后的根访问器诊断修正，修正后的 198 项相关回归另行通过，日志 `.cache/structured-report-regression.log`；未将新增用例计入此前全量数字。跳过项沿用既有 Windows 权限模拟及文件符号链接权限测试。
+- 全部实施步骤完成。仅本地源码与文档变更；插件代码、产品版本、工作流和日志存储格式未改。

package/manual/docs/plans/2026-10-14-unreleased-review.md

@@ -0,0 +1,47 @@
+# 未发布源码独立评审处理记录
+
+基线：a0e6396；GitHub #6–#11 正文与评论已读取，2026-10-14 读取时六项均无评论。只在本地开发，不推送、不发布、不改版本、不改插件源码、不删除现有日志或用户数据。
+
+## 已确认范围
+
+- #6：受管调用自动记录完整 argv，与旧文档“不自动记录命令参数”冲突。增加明确的 `logPolicy`：`false` 隐去参数和原始脚本；对象支持 `redactArgs: [零起算参数下标]`、`omitArgs: true`、`omitScript: true`。传入实际执行器的参数不变；有参数脱敏时原始脚本一并隐去，防止同一信息从 script 泄漏。默认仍保留普通诊断参数，不猜测业务字段是否敏感。作者必须为可能含敏感内容的调用明确声明策略。选项无效时在执行前报错。该机制只负责宿主自动记录的调用信息，不承诺清理插件主动输出、业务输入输出或已有日志。
+- #7：加载错误隔离到插件及依赖消费者，提供可管理的降级状态；见对应实施记录。
+- #8：损坏工作流目录列举与 TUI 启动容错，保留准确诊断；见对应实施记录。
+- #9：文件补全同步接口消费缓存，隔离探测异步读取并限制预算；见对应实施记录。
+- #10：解析工作流闭包时预检每个 inputs Schema，保留合法 boolean Schema；与 #8 同模块实施。
+- #11：采纳真实插件端到端验收优先级建议，不扩展通用框架。当前具备本地预览真实环境插件条件，但另一台目标机离线运行、首次用户操作时间等不能用自动测试或同机演示冒充；明确记录尚待现场验收。
+
+## 实施和验证
+
+1. 各缺陷先用临时工作区/假令牌/受控慢探测复现，随后修正并运行定向测试。
+2. 共用基线与边界，独立模块并行实施；集成后检查代码差异、跨模块消费者、完整测试。
+3. 汇合后完成独立复核与完整测试，结果见下文。
+
+### 独立代码复核
+
+以 `a0e6396` 到本地工作树为范围，分别执行 Standards（规范与模块边界）和 Spec（需求覆盖）审查。发现并修复两项遗漏：Execa 对非法 NUL 参数的同步异常包含 argv；已隔离故障插件自身的缺失依赖仍可能阻断启动。两项均先新增失败回归，再修复；复核后两个维度的遗留问题均为 0。未把审查结果解释为不存在任何未知缺陷。
+
+`tests/issue6-process-redaction.test.js` 现有 5 项回归，包含真实进程原值传递、三份持久化文件及 TUI 脱敏、禁记录、策略校验、操作系统拒绝启动和执行库同步异常。与进程执行和流式输出测试共 22 项通过。
+
+`node scripts/log-preview.mjs --prepare` 成功，现有 `fst-preview.cmd` 继续启动本地源码预览，且确认加载了真实 `fst-env-probe` 插件。
+
+## #11 真实插件验收与产品边界
+
+2026-10-14 使用外部 `fst-env-probe` 0.1.1 源码，在独立 `.cache/issue11-local-1791984632876` 工作区通过内核执行 `resolve`，未修改插件源码：
+
+- 第一轮检查 `node` 和故意不存在的 `fst_acceptance_missing_20261014`，动作正常完成，业务结果 `ok: false`，明确列出缺失工具。
+- 第二轮将参数改为 `node`、`git`，业务结果 `ok: true`，没有缺失项。
+- 用实际运行记录生成主面板文本，确认保留工具名、缺失原因和两轮执行记录。现场证据为该目录的 `acceptance.json`、`main-panel.txt` 和 `logs/`。这些仅是本机验收资料，不作为可移植测试夹具提交。
+
+这证明内核到真实插件的本地调用、修改输入重跑、记录结果链路可用。它没有替代完整 TUI 键盘操作、141 项全面检测、跨机离线包执行或首次用户体验测试，也不代表插件已采用新业务报告协议。
+
+后续现场验收沿用现有能力，依次完成：选择环境 → 执行检查 → 定位失败原因 → 修改参数重跑 → 阅读分组报告 → 在另一台目标机器离线运行。记录首次完成时间、操作步骤、需要理解的概念、失败后的恢复步骤，并与直接脚本和简单菜单比较；同时测量启动时间、峰值内存、离线包体积。没有实际测量前不填写推测数字。
+
+交互定位经用户再次确认：TUI 是主要交互入口；CLI 保留必要的直接运行、自动化、打包和故障恢复命令，不要求每个界面操作另做命令。Web 按真实使用需求演进。本轮先修已复现问题，不因产品建议新增通用执行框架。
+
+## 集成结果
+
+- `npm test`：690 项，687 通过，0 失败，3 跳过，约 221 秒。完整本地输出为 `.cache/unreleased-review-full.log`。两项跳过因当前 Windows 账户无文件符号链接权限；另一项为既有平台条件跳过。目录 junction 验证仍执行。
+- `git diff --check` 通过；`plugins/` 无代码差异，版本仍为 0.5.3。用户既有 `flow-results/` 未加入提交。
+- 规范复核与需求复核：修正后各 0 项遗留发现。开发监听回归验证故障时第三代工作台仍可访问、插件修复后第四代恢复 ready，端口及访问令牌保持一致。
+- 分支 `codex/plugin-defaults` 保存本地修复；不推送、不发布 npm，不自动评论或关闭 GitHub issue。#11 现场验收待办、真实 NFS/SMB 验收和日志脱敏边界均保留上述限制。

package/manual/docs/plugin-development.md

@@ -59,6 +59,120 @@ JSON 序列化可能丢弃对象中的 `undefined`、函数或 Symbol，并将
 
 输入与配置校验继续应用 `default`；动作和交互命令的输出校验只验证实际返回值，不补默认值。旧插件若依靠输出 schema 自动生成 `ok` 等字段，必须在 `run` 返回值中明确赋值。诊断消息和 `details[].jsonPointer` 提供完整 JSON 指针（如 `/benchmark_config/model_name`），`schemaPath` 标明约束位置；`required` 放在顶层时只能报告顶层缺失，不会猜测作者原本想放在哪个子对象。
 
+### 默认参数与开箱使用
+
+- 常规选项存在适用的合理默认值时，作者必须在输入或配置 schema 的字段中声明 `default`，例如次数、输出格式、超时和功能开关。不要让用户反复填写这些常量。
+- 只把确实无法预设的业务对象、地址、凭据或目标环境列为必填，并提供清楚的字段标题和说明。不可为了通过检查编造密码、目标路径或机器地址；也不要求每个字段都有默认值。
+- `required` 与 `default` 可以同时声明：缺失时先补默认值，再校验。`false`、`0`、空字符串和显式 `null` 不视为缺失；它们仍须满足字段约束。
+- 可选对象未传入时，不自动创建该对象或启用对应功能。只有确定需要默认启用整个对象时才给父对象声明 `default: {}`，随后才能补充其内部字段默认值。
+- 普通调用和工作区配置依靠 schema `default`。`defaultConfig` 保持公开部署配置的语义，只用于生成运行包，不能代替普通安装后的 schema 默认值；严禁放入私有凭据。
+- TUI 普通带参数的插件能力先展示当前参数（含默认值），提供“执行”“配置参数”“返回”；配置完成回到预览，执行前校验必填内容。预览按窗口宽度分为一至三列、最多四行，小窗口进一步收缩；仅在字段数量或内容确实显示不全时出现展开入口，可滚动阅读。无参数命令、完整快捷预设和显式参数文件保留直接调用。
+- 此处编辑的是本次调用参数；跨次复用固定参数可通过 `/shortcuts` 保存。插件配置继续通过 `/plugin` 保存到工作区。
+
+发布验收必须覆盖：最少必填输入可以运行、缺失参数确实需要用户提供、默认值符合字段约束、显式值覆盖默认值、可选能力不会因默认值意外启用。默认值是否适合业务由作者审查；宿主按 schema 验证实际输入，不凭参数数量警告用户。
+
+### 能力发现与历史（0.6.0 起）
+
+能力发现约定：作者注册的 `commands` 可通过非空斜杠前缀补全发现，空 `/` 的精简列表不代表全部能力。推荐用明确命名空间组织命令，例如 `envprobe.check`；命名空间唯一且无名称冲突时，`/envprobe` 可进入插件菜单。实际可执行命令名始终保留，从菜单执行后也会进入用户的命令历史。纯 `actions` 仍通过工作流和自定义快捷名称调用，不会擅自生成新的命令语法。
+
+### 参数继承与来源（0.6.0 起）
+
+固定 `default` 不能表达“跟随当前插件配置”。需要这种行为时，在输入对象的顶层字段增加 `x-fst` 声明，例如：
+
+```js
+const config = {
+  type: 'object',
+  properties: { timeoutMs: { type: 'integer', minimum: 1, default: 8000 } },
+};
+const input = {
+  type: 'object',
+  properties: {
+    timeout: {
+      type: 'integer', title: '单项超时', minimum: 1,
+      'x-fst': { fromConfig: 'timeoutMs', unit: '毫秒' },
+    },
+    tools: {
+      type: 'array', title: '检查工具', items: { type: 'string' },
+      'x-fst': { unsetLabel: '全部工具' },
+    },
+    extraPaths: {
+      type: 'array', title: '额外目录', items: { type: 'string' },
+      'x-fst': { unsetLabel: '无额外目录' },
+    },
+  },
+};
+```
+
+- `fromConfig` 是已声明的配置字段路径，例如 `network.timeoutMs`；宿主使用已校验、已应用配置默认值的实际配置。路径拼错、危险路径、格式不正确会在加载及 `plugin validate` 时报告。
+- 取值顺序为：**显式调用输入 → 插件配置 → 输入字段 default → 保持省略**。`false`、`0`、空字符串、`null` 都是显式值，仍须通过输入约束。配置值不符合输入约束时执行失败，不静默退回固定默认值。
+- `unsetLabel` 只是作者声明的省略含义，不注入业务值；插件仍负责实现“全部工具”等行为。`unit` 只用于展示，不改变类型或换算数值。
+- TUI 展示“继承插件配置：8000 毫秒（timeoutMs）”“默认值”“本次输入”，编辑时可恢复继承。查看和编辑其他参数不会将继承值保存为固定输入；之后修改插件配置，下一次执行会使用新值。工作流绑定保存原始输入/引用，执行时解析继承。
+- 当前只支持简单输入对象的顶层字段；嵌套对象内部、数组项、`$ref` 和条件/联合 schema 中的 `x-fst` 暂不支持，声明时明确报错。需要复杂结构时先保留原有 schema 与业务实现。
+- 旧插件无需改动即可继续运行；没有声明的动态规则不会被推断。可选且未提供的字段会显示“未提供（插件未声明缺省行为）”，不能将其理解为插件没有内部默认值。上述协议从 0.6.0 起支持。
+
+内核提供解析、来源展示和校验，插件负责声明真实规则及省略含义。开发验收应包含：修改配置后继承变化、显式值覆盖、恢复继承，以及显示值与实际收到的输入一致。应用接口 `app.previewInput('/命令名' 或 '插件ID:动作名', 原始输入)` 返回 `{value, fields}`；仅返回该输入引用到的配置值，不返回整份插件配置。运行记录中的输入仍为原始提交内容。
+
+### 统一业务报告（0.6.0 起）
+
+业务结论由插件生成，内核只校验和展示。SDK 的 `@mytools/sdk/reports` 提供 `createReport`、`reportSchema` 和 `inspectReport`。报告按摘要、提醒、建议、业务分组排列；提醒等级不会改变执行状态，建议不会自动执行。
+
+```js
+import {createReport, reportSchema} from '@mytools/sdk/reports';
+
+const output = {
+  type: 'object',
+  properties: {ok: {type: 'boolean'}, report: reportSchema},
+  required: ['ok', 'report'],
+  additionalProperties: false,
+};
+// 动作/命令执行函数返回此类对象，原有业务字段仍可供工作流引用。
+const result = {
+  ok: false,
+  report: createReport({
+    title: '开发环境检查',
+    summary: '检查了两个工具，其中一个尚未安装。',
+    alerts: [{level: 'warning', message: '缺少构建工具。'}],
+    recommendations: ['确认本次任务需要该工具后，再手动安装。'],
+    sections: [{
+      title: '构建工具',
+      columns: ['name', 'found'],
+      titles: {name: '工具', found: '已安装'},
+      data: [{name: '工具甲', found: true}, {name: '工具乙', found: false}],
+    }],
+  }),
+};
+```
+
+协议是普通 JSON：`kind: 'fst-report'`、`version: 1`、非空 `title` 必填，helper 自动填写前两项。可选 `summary` 是非空文本；`alerts` 是 `{level, message}` 数组，等级为 `info`、`warning`、`error`；`recommendations` 是非空文本数组。`sections` 内每组必填 `title`，可带相同的摘要/提醒/建议和任意 JSON `data`；`columns` 为唯一字段名数组，`titles` 为字段标题映射。v1 不支持递归分组，元数据不接受未知字段。纯文本中的换行保留，终端控制字符在展示时过滤。
+
+新能力可直接返回报告并声明 `output: reportSchema`；已有能力推荐保留业务输出并增加 `report` 字段。长内容和未选列保留全文，窄屏退回字段阅读；主面板默认展示报告摘要、提醒、建议、分组和表格，无需先展开详情。报告整体缩进，结论和组标题再缩进一级，组内数据和表格再缩进一级。输入和实际执行指令始终可见；Ctrl+O 展开原始输出与诊断，运行详情中的 m 保留专用阅读。原始 JSON、工作流引用和落盘数据不变。声明 schema 或调用 helper 时会校验；读取损坏或未来版本报告时提示原因并回退字段展示。超出日志内存预算时明确标注摘要，并指向 `/logs` 的 `p` 完整落盘阅读，不将残缺预览误报为协议错误。只有显式 `kind` 标记才启用协议，旧文本、Markdown 和普通对象不需要改造。
+
+### 结构化结果与表格阅读（0.6.0 起）
+
+表格布局由内核负责，无需 LLM，也无需插件打印边框字符。插件应返回结构化业务数据，并在输出 schema 中提供准确字段标题。相同字段结构、至少包含两个标量字段的记录数组或字典可自动显示为表格；异构结构保留字段阅读。可选的 `x-fst-table` 指定希望优先阅读的列及顺序：
+
+```js
+const output = {
+  type: 'array',
+  'x-fst-table': ['name', 'found', 'version'],
+  items: {
+    type: 'object',
+    properties: {
+      name: { type: 'string', title: '工具' },
+      found: { type: 'boolean', title: '已找到' },
+      version: { type: ['string', 'null'], title: '版本' },
+      details: { type: 'object', title: '详细信息' },
+    },
+  },
+};
+```
+
+字典将同样的列提示放在字典 schema 上，行字段 schema 放在 `additionalProperties` 中。该提示是非强制阅读建议；无效格式退回通用推断，非标量字段仍按正文阅读。内核按中文显示宽度排版，窄窗口回退紧凑字段格式。自动推断时，重复的字典标识列合并、相同标量集中为共有字段；`false` 和 `0` 始终保留。空字段可折叠，原始 JSON 不变。
+
+长单元格显示“见下文”，复杂值及装不下的字段在表后按条目补充全文。主面板、运行详情和 `m` 阅读随窗口宽度重排；`j` 仍可查看原始数据。表格改善对齐与横向比较，不保证所有窗口尺寸的总行数都更少。不要为了表格删减业务输出；旧插件也能获得通用表格布局，声明列提示可进一步改善阅读顺序。
+
+TUI 负责通用结果阅读：紧凑输出合并同一对象内的短字段，折叠空字符串、空值和空容器，保留 `false`、`0`、非空错误及多行正文。详情按 `j` 查看未经折叠的原始 JSON，落盘数据不受影响。插件继续返回完整结构化结果，并通过 `print` 给出业务摘要；字段含义通过 schema `title` 描述，内核不根据插件名称猜测业务。直接插件命令也使用自己的输出 schema 展示标题。
+
 无参数或无输出时，分别使用 `{type:'object', properties:{}, additionalProperties:false}`，动作返回 `{}`。JSON Schema 的布尔形式也受支持：`true` 接受任意值，`false` 拒绝所有值；为了生成字段表单与输出选择器，推荐明确声明对象和字段。缺省、`null`、数组、字符串和数值都不能代替 schema 声明。原有动作/子工作流的 `schemaVersion: 1` 格式保留；旧插件若要参与编排，需要补齐有效的 input/output 声明。正常返回且输出校验通过即执行成功，不要求返回额外的 `success:true`。
 
 ## 插件定义字段
@@ -135,9 +249,13 @@ fst plugin remove my-flow-plugin
 
 `plugin add <本地目录>` 是复制安装，源文件修改不会自动反映到已安装副本；重复 `add` 即可更新，无需先 `remove`。开发时使用下述引用模式。CLI 管理命令以独立进程运行；常驻 TUI/Web 对需要重启的服务显示本次维护提示，仅更新受影响的插件及依赖它的插件。
 
-插件安装在 `.flow/installations/<随机安装批次ID>` 新目录，验证加载成功才切换状态，失败保留原配置。安装禁用 npm 生命周期脚本；TS 发布前编译，原生库及其目标平台资源由作者准备。核心不审核平台兼容性，也不自动重建原生库。工作流运行期间不能变更插件。
+普通 CLI/TUI 默认在用户级 `~/.fishtools/plugins/.flow/installations/<随机安装批次ID>` 新目录安装，设置 `FISHTOOLS_HOME` 后改为其 `plugins` 子目录；开发链接也全局登记。工作区单独保存参数、工作流和代理规则，缺少必填配置时插件显示“待配置”，配置完成后启用。旧工作区 `.flow/plugins.json` 兼容读取，同名全局版本优先；全局卸载后不复活旧本地版本。离线包继续在自身可写工作区安装和管理，不加载宿主全局插件。
 
-移除插件前会检查所有已保存工作流（含分支、并行和子工作流）的引用，并显示受影响工作流；仍被其他插件依赖时始终拒绝。确认接受工作流暂时无法运行后，可用 `fst plugin remove 插件ID --force` 跳过工作流引用保护。工作流文件不会随卸载删除，重新安装插件后仍可使用。
+升级前已经安装在工作区的插件不会自动搬移。需要在其他工作区使用时，再执行一次 `fst plugin add 包名或路径`，开发源码则使用 `fst plugin link 源码目录`，即可登记到全局库；原有配置和安装备份仍保留。
+
+验证成功才切换安装状态，失败保留原配置；前一状态存入 `plugins.previous.json`，活动代码由批次租约保护。安装禁用 npm 生命周期脚本；TS 发布前编译，原生库及其目标平台资源由作者准备。核心不审核平台兼容性，也不自动重建原生库。当前工作区运行期间不能变更插件，其他已启动进程使用其现有代码，重启后读取新状态。
+
+移除全局插件前会检查已登记工作区的已保存工作流（含分支、并行和子工作流）的引用，以及各工作区预置或旧本地插件对它的依赖；显示受影响工作区与工作流。移除旧工作区插件仅检查当前工作区。仍被其他插件依赖时始终拒绝，`--force` 不绕过插件依赖检查。确认接受工作流暂时无法运行后，可用 `fst plugin remove 插件ID --force` 跳过直接工作流引用保护。工作流文件不会随卸载删除，重新安装插件后仍可使用。
 
 业务 npm 库写入 `package.json.dependencies`，开发库写入 `devDependencies`。插件间依赖另外写在定义的 `dependencies: {'other-plugin': '^1.0.0'}`，用于宿主版本检查和打包闭包；被依赖插件也需安装并注册。
 
@@ -168,13 +286,16 @@ fst plugin lint ./my-plugin --json
 - `MISSING_TITLE` / `MISSING_DESCRIPTION`：动作、命令缺少非空标题或描述；动作别名命令可复用目标动作元信息。递归检查 input/output 的字段标题。
 - `BOOLEAN_SCHEMA`：布尔 schema 合法，只提示字段级表单信息不足，不判定契约错误。
 - `CONSOLE_LOG`：在可达 JavaScript 中识别直接 `console.log` 调用，包括顶层及辅助函数；引导动作和命令使用 `log` / `print`。注释和字符串不作为调用。
+- `UNMANAGED_PROCESS`：定位能追溯到 `child_process`、`execa`、`cross-spawn`、`shelljs.exec` 或平台底层 `runProcess` 的直接调用，提示迁移到上下文 `ctx.runProcess`。覆盖常见 ESM 别名、CJS require、createRequire 和字面量动态 import；仅导入未调用不告警。它是迁移警告，不拒绝旧插件，不代表该代码实际执行过。动态计算、复杂别名、依赖内部及 Python/Shell 内部的执行不保证覆盖。
 - `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` 解除引用，不删除源码。分发收集源码的发布文件和生产依赖快照，不把开发路径链接带给最终用户。
+`link` 将源码绝对路径保存到插件库（普通 CLI 默认全局登记），不复制源码，不安装源码目录的 npm 依赖；需要依赖时先在插件目录自行安装。可用 `fst --watch` 在业务空闲后自动重启开发进程并重新加载完整模块图；未启用 watch 时手工重启。源码目录迁移后需要重新 link。正常 `add` 同名包可替换开发引用，`remove` 解除引用，不删除源码。分发收集源码的发布文件和生产依赖快照，不把开发路径链接带给最终用户。
+
+已安装或链接的插件出现可捕获的导入、SDK 或单插件契约错误时，插件列表显示“不可用”、来源和原因；依赖它的插件也不可用，无关流程仍可执行。可进入插件管理移除故障插件，多个故障可逐个处理。修复源码后重新启动，或由 `--watch` 重新加载。新安装和链接仍严格检查；项目预置插件、明确的跨插件图冲突、运行时初始化错误，以及模块顶层退出进程或无限循环不在此恢复范围内。
 
 ### 安装批次清理与恢复
 
@@ -214,12 +335,14 @@ fst plugin gc --apply
 
 可用 `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`；若更新与恢复都失败，当前宿主停止接受新的运行，重启前应先核对磁盘配置和插件状态。
+覆盖保存已有工作流时，原始 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)` 启动子进程；两者会应用本次动作的规则。插件直接使用其他网络库、直接创建子进程或自行覆盖代理环境时，应自行接入规则；宿主不拦截其网络调用。插件命令和服务使用插件级规则。
 
 ### 权限声明与执行前检查
 
+统一执行接口不会增加系统权限。权限声明与预检仍在动作主体执行前检查，已确认不足时直接报错，不自动调用 sudo 或请求管理员密码。没有声明的旧插件仍按兼容规则运行；规范要求作者逐步补齐声明。
+
 插件可以为所有动作声明默认权限，也可以为某个动作覆盖：
 
 ```js
@@ -254,6 +377,7 @@ Linux 支持 `user/root/resource`，Windows 支持 `user/administrator/resource`
 | `signal` | 取消信号，异步动作应响应 |
 | `runId`、`stepId`、`callPath` | 运行和嵌套步骤定位 |
 | `outputDir` | 本次运行的可写结果目录 |
+| `logDir` | 本次运行的日志目录；业务文件应写入 outputDir |
 | `resourceDir` | 插件包目录，用于定位脚本 |
 | `projectDir` | 当前工作区根目录；可编辑便携包使用其包外工作区 |
 | `stateDir` | 当前插件跨运行持久目录，与 outputDir 无关；只读项目或无应用的独立宿主为 undefined |
@@ -265,11 +389,13 @@ Linux 支持 `user/root/resource`，Windows 支持 `user/administrator/resource`
 
 返回值必须可 JSON 序列化，输入输出经 Ajv 校验。插件在宿主进程中执行，属于可信代码；同步阻塞代码不能被取消信号抢占。
 
+从 0.5.3 起，普通工作区的业务文件默认写入 `results/运行ID/`，执行日志写入 `.flow/runs/运行ID/`。日志保留策略不会清理业务结果，历史文件也不会自动搬移；插件应返回或 `print()` 实际保存路径，方便用户找到文件。
+
 可写应用在调用前创建 `.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 打印。
+主面板默认展示执行入口、步骤状态、输入和受管进程的实际程序、参数、目录、原始脚本。`fst-report` 业务报告及 print 用户反馈缩进展示；工作流步骤的报告也默认显示，最终输出转发同一报告时仅展示一次。Ctrl+O 展开或收起原始返回、内部日志和调用栈；stdout/stderr（包括感叹号透传）按原始返回处理，即使带有 `audience: 'user'` 也默认折叠。失败摘要始终直接显示。希望用户直接看到的进度或其他结果，显式使用 `await print('报告已保存', {file})`。`print` 沿用日志通道，以不带 stream 的 `type: 'log', audience: 'user'` 持久化，工作流中自动带上步骤归属。动作和交互命令都支持，不应直接用 `console.log` 向 TUI 打印。
 
 若 Python 程序的部分输出需要直接展示，可使用 `runProcess(file, args, {onOutput: ({stream,message}) => stream === 'stdout' ? print(message) : undefined})`。回调按数据块触发；作者可先缓存成完整行再选择性 print。完整进程输出仍自动保存在诊断日志，print 的用户提示另外保留。写入 stderr 本身不等同执行失败，动作仍须按退出码决定抛错。
 
@@ -277,6 +403,44 @@ Linux 支持 `user/root/resource`，Windows 支持 `user/administrator/resource`
 
 `runProcess` 默认无 Shell，参数用数组。支持 `cwd`、`env`、`signal`、`timeout`（默认 30 秒）、`maxBuffer`（stdout/stderr 各默认 4 MiB）和可选的 `onOutput({stream,message})`。普通非零退出返回 `{exitCode,stdout,stderr}`，动作应自行决定是否抛出业务错误；缺失程序、超时、取消、输出超限抛错，并等待进程树回收。不要把密码或令牌写入日志。
 
+#### 统一执行入口与并行边界
+
+动作和交互命令通过上下文 `ctx.runProcess` 执行外部程序，不直接使用 `node:child_process`、execa、cross-spawn 或 shelljs.exec；也不直接导入平台底层 runProcess。`!` 命令与插件共用内核的进程包装，统一日志、取消和回调顺序。每次调用的启动记录与 stdout/stderr 带同一个 `processId`，主面板指令和详细回显显示对应短编号；旧记录没有编号时仍可阅读。
+
+当前插件本身是 JavaScript，在宿主 Node.js 中完成的纯计算不需要新进程。Python 或其他程序仍需要启动解释器：无论解释器来自系统还是随离线包携带，均使用同一接口，例如：
+
+```js
+async function run(input, ctx) {
+  // environments 负责定位系统或随包解释器，runProcess 负责执行管理。
+  const result = await ctx.runProcess(ctx.environments.python.executable,
+    ['check.py'], {cwd: ctx.resourceDir, signal: ctx.signal});
+  if (result.exitCode !== 0) throw new Error(`检查失败，退出码 ${result.exitCode}`);
+  return {stdout: result.stdout};
+}
+```
+
+统一入口不增加全局串行队列。工作流继续用 `parallel.concurrency` 控制步骤并发；插件在单个动作里使用 Promise.all 启动多个程序时，应自行设定合理并发并 await 所有任务。每次调用的取消信号独立；运行或并行组主动取消时，仍按既有规则取消所属任务。当前没有全局进程数量限制或资源锁；同时修改相同系统资源时，插件应自行协调。
+
+动作结束前必须等待所启动的程序，不使用 detached、后台 Shell 等方式脱离管理。长期后台程序的专门执行接口尚未提供。这里是开发契约与统一管理接口，不是安全沙箱：插件仍与内核同进程，静态检查不能强制拦截所有绕行，也不能逐条审核解释器内部命令。独立提权和不可信插件隔离不在本轮范围。
+
+受管 `ctx.runProcess` 在启动前自动记录实际程序、参数数组和执行目录，Shell 另记录原始指令；自定义 `onStart({file,args,cwd,script?})` 在此记录后调用。启动记录写入失败或此时取消会阻止启动子进程。TUI 主面板默认展示这些执行指令；插件实际来源目录另随调用记录，展开诊断后可以阅读。通过其他方式执行的程序或任意文件访问不在该记录范围内；参数若含凭据，也会进入本地执行日志，作者应通过环境变量或其他受控渠道传递。
+
+敏感参数必须显式设置日志策略，实际执行参数与自动记录的展示参数分开：
+
+```js
+await ctx.runProcess('tool', ['--endpoint', endpoint, '--token', ctx.config.token], {
+  logPolicy: {redactArgs: [3]}, // 从 0 起算，将第 4 个参数显示为 [已隐藏]
+});
+// 完全隐藏参数及原始脚本，仍记录程序、目录和调用编号：
+await ctx.runProcess('tool', privateArgs, {logPolicy: false});
+```
+
+`logPolicy` 对象还支持 `omitArgs: true` 和 `omitScript: true`。隐藏任意参数时会同时隐藏原始脚本，避免同一密钥从脚本文本泄露。下标越界或策略字段无效会在执行前报错，不包含策略原值。普通调用未声明策略时仍记录参数，不自动猜测业务字段是否敏感；自定义 onStart 回调仍接收真实参数，作者不得自行把它们重新写入日志。系统拒绝启动的自动错误不再附带 Execa 的完整命令行。
+
+这只保护宿主自动记录的启动信息，不会清理插件主动 log/print、stdout/stderr、业务输入输出、自定义错误或已有日志。已有历史记录保持原样，修复不会自动清除其中的密钥；需要时由用户按日志管理流程处理。
+
+工作流、直接动作和插件命令在执行前统一追加 `run.input`，保存本次提交的完整参数；界面及元数据仍仅持有有界预览。较大参数通过 `/logs` 的完整日志分页读取，配置表单不属于运行参数，不进入此记录。
+
 默认 buffer 模式的 `OUTPUT_LIMIT` 限制子进程返回缓冲及实时输出队列，不是 run.md 的文件体积阈值。触发后只能取得超限前已记录的部分输出，不能当作完整结果。可以按业务明确提高有限的 maxBuffer；大量连续日志可选择 `outputMode:'stream'`，完整落盘、内存只保留尾部摘要并显式标记截断。超大业务结果也可由程序写到 outputDir 内的文件，stdout 返回摘要或路径。
 
 ### 不可信路径与网络挂载
@@ -291,7 +455,7 @@ Promise.race 只能让调用方停止等待，不能中断正在执行的操作
 
 当前源码已提供 `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 文件长度，包括尚未结束的运行。显示字节数、文件数、当前项目的保留次数；读取失败时明确标注统计不完整。
 
@@ -311,7 +475,7 @@ TUI `/logs` 与 `/config` 的“查看日志体积”按需统计当前日志根
 
 每次通过应用运行工作流或插件命令，都在 `.flow/runs/<runId>/` 写入 `run.md`、`events.jsonl` 与 `result.json`（指定 `--output` 时使用该目录；便携版写入可写工作区）。
 
-- **运行中直接观察**：TUI 主面板逐步更新状态，Ctrl+O 展开输入输出和诊断日志；`/logs` 可选择某次运行进入详细面板。Web 使用“查看运行”。按调用路径区分同一动作的不同调用。
+- **运行中直接观察**：TUI 主面板逐步更新状态，默认展示输入和实际指令，Ctrl+O 展开原始输出和诊断日志；`/logs` 可选择某次运行进入详细面板。Web 使用“查看运行”。按调用路径区分同一动作的不同调用。
 - **历史日志直接阅读**：TUI `/logs` 选择记录后切换总览、输入输出和日志；方向键或鼠标滚轮滚动，PageUp/PageDown 翻页，Home/End 跳转，Esc 或 q 返回，Enter 查看步骤。重启后读取磁盘历史；run.md 也可用外部 Markdown 阅读器打开。
 - **导出阅读内容**：`run.md` 按时间顺序展示步骤、作者日志、stdout/stderr、执行结果、失败原因、错误详情和调用栈，结束后附最终状态。它在执行过程中逐条追加，也可使用外部 Markdown 阅读器查看。调用栈保留原始换行。
 
@@ -320,9 +484,9 @@ TUI `/logs` 与 `/config` 的“查看日志体积”按需统计当前日志根
 - 例如调用不存在的 Python 时，运行失败，message 含具体插件及“未找到程序”，错误链包含 `ENOENT` 和 `details.executable`。无需先运行环境检查插件才能捕获此错误。
 - Python 脚本异常或依赖缺失通常通过非零退出码及 stderr 报告。作者必须检查返回值并抛错，例如 `throw Object.assign(new Error('Python 脚本失败'), {code:'PYTHON_FAILED', details:{exitCode:r.exitCode, stderr:r.stderr}})`；不要捕获后返回成功。此写法无需内部 SDK。
 - 插件可 `await log('正在检查 Python', {phase:'python-check'})` 补充业务阶段。插件自身的 `console.log`、自行启动的子进程和未 await 的后台任务不会自动进入这套日志；动作上下文 `runProcess` 的 stdout/stderr 会实时写入。
-- 核心不自动记录命令参数、环境变量和插件配置。错误消息、stderr、调用栈、作者 log 和返回结果仍可能包含敏感内容；作者应在返回或抛错前按业务脱敏。
+- 核心会记录执行输入和受管进程的程序、参数、目录、原始脚本；敏感命令参数必须用上述 logPolicy 显式隐藏。核心不主动记录完整环境变量或插件配置，但它们被放入参数、业务输入输出、错误或日志时仍可能被保存。stderr、调用栈、作者 log/print 和返回结果应由作者按业务脱敏；已有日志不会自动清除。
 
-定位顺序：按 runId 打开 run.md → 查看失败插件及步骤 → 查看原始错误码与调用栈 → 结合之前的日志和成功步骤输出复现。JSON 文件是给程序查询与界面使用的结构化记录，不要求用户通过 JSON 阅读日志。此处是运行诊断；插件加载/初始化失败发生在运行创建之前，目前由启动错误报告，不会凭空产生工作流运行目录。
+定位顺序：按 runId 打开 run.md → 查看失败插件及步骤 → 查看原始错误码与调用栈 → 结合之前的日志和成功步骤输出复现。JSON 文件是给程序查询与界面使用的结构化记录，不要求用户通过 JSON 阅读日志。此处是运行诊断；插件加载/初始化失败发生在运行创建之前，可恢复的已安装插件错误在插件列表中显示，其他启动错误仍由启动诊断报告，不会凭空产生工作流运行目录。
 
 ### 日志保留与清理
 
@@ -474,7 +638,7 @@ async function run({executable, text}, {resourceDir, runProcess, signal}) {
 
 TUI 顶层按插件归组：例如 ID `@mytools/examples` 对应 `/examples`，进入后选择具体能力，列表标明 `[插件]`、插件名称及 ID。入口取插件 ID 的末段；同名插件使用完整 ID 转为连字符名称，遇到保留名或已有命令则加 `plugin-` 前缀。以当前补全列表中的实际入口为准，不要在插件间依赖这个 UI 别名。只有注册了 `commands` 的插件才产生能力入口，纯服务/纯动作插件仍可在 `/plugin` 管理或参与工作流。原始命令名和 CLI `fst command` 协议不变，旧插件无需迁移定义。新保留入口包括 `plugin`、`tools`，作者应继续使用带插件前缀的命令名。
 
-TUI 负责展示当前工作区、操作入口、菜单标题以及提交命令和操作结果。返回时只更新当前位置，不追加通用返回消息。插件使用 `ui.input/select/show/confirm`，不要自行清屏或打印终端控制序列，以免破坏主面板中的运行过程。导航记录仅保留在本次会话，持久诊断请使用动作上下文的日志接口。`/run` 执行已保存的工作流；工作流草稿只在编辑菜单明确选择“保存并运行”后才写入，不由插件命令隐式保存。
+TUI 负责展示当前工作区、操作入口、菜单标题以及提交命令和操作结果。返回时只更新当前位置，不追加通用返回消息。插件使用 `ui.input/select/show/confirm`，不要自行清屏或打印终端控制序列，以免破坏主面板中的运行过程。主面板输入、反馈和结果关联可以通过 `/history` 恢复；配置表单和未提交草稿不保存，持久诊断继续使用动作上下文的日志接口。`/run` 执行已保存的工作流；工作流草稿只在编辑菜单明确选择“保存并运行”后才写入，不由插件命令隐式保存。
 
 ```js
 commands: {
@@ -545,7 +709,7 @@ TUI `/pack` 选择来源并展示资源字节数；CLI 支持 `--plan` 和 `--en
 ## 发布前检查清单
 
 1. **打包检查**：在插件目录运行 `npm pack --dry-run`，确认编译后的入口、脚本、资源和许可证均会进入包，未夹带凭据或开发数据；再用 `npm pack` 生成待安装的 `.tgz`。
-2. **独立安装**：在单独测试工作区用 `fst --project <测试工作区> plugin add <插件.tgz的绝对路径>` 安装，使用 `plugin list` 确认插件可加载。源码开发可将 `fst` 替换为 `npm run fst --`。
+2. **独立安装**：测试时先将 `FISHTOOLS_HOME` 设置为独立临时目录，再用 `fst --project <测试工作区> plugin add <插件.tgz的绝对路径>` 安装，使用 `plugin list` 确认插件可加载，避免影响日常用户级插件库。源码开发可将 `fst` 替换为 `npm run fst --`。
 3. **界面检查**：打开测试工作区，确认能力标题、用途、输入字段和输出说明可理解；添加动作并填写参数保存工作流。
 4. **执行检查**：分别验证正常输入、缺少必填项、错误类型、业务失败、缺少程序/依赖、超时与取消。失败必须明确报告，不得伪装为成功。没有子进程的动作不必模拟不适用的进程场景。
 5. **组合检查**：把动作输出传给下一步，确认字段和类型稳定；执行同一工作流两次，验证副作用符合说明。

package/manual/docs/releases.md

@@ -11,7 +11,45 @@
 - 一批明显的新能力或兼容性变化，再考虑增加中间一位，例如 `0.5.x → 0.6.0`，并在发布说明中解释升级影响。
 - 仅文档、测试或开发流程调整，且不需要用户升级已安装产品时，不单独增加产品版本或发布 npm。
 
-已发布版本不可覆盖。本轮用户明确指定新能力目标为 `0.5.2`，集中完成审查验证后发布；后续继续按实际影响和用户约定选取版本。
+已发布版本不可覆盖。`0.5.2` 曾按用户指定目标集中发布；本轮参数继承、报告协议与受管执行等新能力合并为 `0.6.0`，后续小修复继续使用补丁版本。
+
+## 0.6.0 参数预览、业务报告与执行恢复
+
+- 选择插件能力后展示当前有效参数，支持直接执行或配置后返回预览；参数较多时分列展示，仅在内容确实省略时提供完整参数入口。
+- 参数规则可声明继承插件配置及留空含义，预览和执行使用同一解析规则并显示来源，不用固定默认值覆盖用户配置。旧插件未声明的执行内部默认行为不会被内核猜测。
+- 新增业务报告协议，支持摘要、告警、建议、分组、表格和 Markdown；主面板默认展示业务报告并缩进，详情和格式化阅读保留完整内容。旧插件使用通用紧凑排版。
+- 输入和实际执行指令默认可见，Ctrl+O 折叠的是原始输出和技术诊断；插件菜单执行记录实际入口，输入插件名称前缀可补全插件及动作。
+- 受管进程入口统一关联日志、取消与进程编号，保持并行能力；开发质量检查提示常见绕行执行。它不构成插件沙箱，也不新增自动提权。
+- 敏感进程参数可用 `logPolicy` 显式脱敏或禁止记录，系统及执行库启动错误不再重新拼接完整参数。默认仍记录普通参数；插件作者负责标记敏感项、业务输出脱敏，已有日志不会自动清除。
+- 修复 #7/#8：已安装插件的可捕获加载或契约错误降级为不可用，无关流程仍可运行；坏工作流文件显示路径和解析错误，不阻断正常列表。卸载与删除继续保守检查引用。
+- 修复 #9：文件补全后台隔离探测、超时、取消和有界缓存；预算由整个 TUI 会话持有，反复进入输入框不会遗忘未回收进程。修复 #10：执行和打包前检查根及子流程输入 Schema，避免先执行前置动作才发现无效声明。
+
+TUI 是主要交互入口，CLI 保留必要的直接运行、自动化、打包与故障恢复能力，不要求每项 TUI 操作都提供另一套 CLI。工作流格式和 SDK_VERSION 保持兼容；新版可选协议需要插件声明才能获得完整效果，本轮未修改插件源码。
+
+已获用户本轮推送和发布授权。#11 已做有限的真实插件本机验证；跨机离线业务验收、首次用户体验、真实 NFS/SMB 故障验收仍待完成，不能由自动化门禁代替。正式发布结果见[验收记录](verification.md)。
+
+## 0.5.3 全局插件、可读详情与会话恢复
+
+- npm 安装支持 Node 22.22.2+（22 系列）和 24.0.0+，包含 issue #4 使用的 24.11.1。生产依赖选择兼容的维护分支，生成包沿用项目的 Node 声明，严格安装验收会拒绝任何不兼容依赖。
+- 兼容性试验在 Windows/Node 22.12.0 再次导出时复现原生进程崩溃；同一测试在 22.22.2 和 24.11.1 通过，因此没有把早期 22 系列声明为支持版本。
+- 工作流没有实际修改时，复制与返回菜单不显示“未保存修改”或“草稿”；查看控制节点及修改后还原也保持准确状态。删除时选择备份后删除、直接删除或取消，默认取消，引用保护与只读保护仍生效。
+- 插件配置、代理规则/配置、日志保留设置、常用命令与快捷名称原样完成时不写文件、不创建备份、不重启插件。已有常用命令不会因进入编辑页自动添加快捷名称。
+- 可选参数仅在声明默认值时说明会使用默认值；已结束任务不显示取消入口。删除注册项只提示实际受影响的快捷名称；打包只在选中当前草稿或其父工作流时询问使用哪个版本。
+- 同步核对 TUI 的权限、定向维护、插件卸载、运行错误和日志提示，保留有实际检查结果的提醒。便携包自带 Node 24.15.0，工作流格式与插件 API 保持兼容。
+- 修复 issue #5 的业务文件覆盖风险：业务输出独立保存到工作区 `results/运行ID/`，日志保留策略只清理日志；即使业务文件叫 `result.json` 也不会被内核覆盖。
+- 普通安装、开发链接默认使用用户级共享插件库，各工作区共用代码并独立保存配置。旧工作区安装兼容读取，缺必填配置的全局插件可在 TUI 配置后启用；热重载包含全局链接。
+- 执行记录标明工作流、插件动作、插件命令和系统命令，保存启动会话，支持按本次启动及入口筛选、继续加载历史，内嵌调用仍只产生一条顶层记录。
+- 运行和步骤附近显示 Ctrl+O 展开提示。详情按字段标题展示输入输出，记录受管子进程的真实程序、参数、工作目录与原始脚本；m 格式化阅读输出，j 保留原始 JSON。
+- 主面板和详情显示执行总耗时，日志收尾后补齐真实结束时间；日志保存失败同步显示失败并保存会话反馈。完成运行的等待对象不继续持有大结果。
+- `/history` 恢复所属工作区的完整 TUI 会话：输入、执行反馈、结果关联，并支持分页阅读完整交互。近期摘要保持内存有界，恢复不会重复执行命令或覆盖旧会话；插件和快捷名称优先，重名时从 `/tools` 进入历史。
+- 插件的平台及架构声明不匹配直接显示在 TUI；Windows 简单 `!ipconfig` / `!ipconfig /all` 按系统 OEM 编码读取中文，同时保留其他命令、多行脚本、管道和重定向的执行方式。
+- 修复早期 Node 24 在 Windows 的日志文件身份误判，保留链接、文件替换及读取预算检查；打包命中有效运行时缓存时不重写，冷缓存校验后原子保存，避免并发读取半成品。
+
+验证与正式发布结果见[验收记录](verification.md)。
+
+**2026-10-13 发布完成：** [正式发布流程](https://github.com/yanglaofish/Fishtools/actions/runs/38402983167)全部成功。
+Windows / Ubuntu 在四个 Node 版本执行的八组完整验收各 586 项、零失败；两平台便携包与断网只读容器通过。
+npm `latest` 为 **0.5.3**，公开包与正式实测归档逐字节相同；[Release](https://github.com/yanglaofish/Fishtools/releases/tag/v0.5.3)四个附件及服务端校验值核对完成，具体下载验收范围记入验收记录。
 
 ## 0.5.2 命令注册与快捷名称
 
@@ -24,6 +62,11 @@
 
 工作流格式、SDK_VERSION 和原动作 ID 保持兼容。命令按当前用户权限执行，使用已有代理和权限接口；外部 Shell 与程序由目标机器提供。第一版支持无需交互输入的命令。完整用法见[命令指南](terminal-commands.md)。发布状态以 GitHub Release 和验收记录为准。
 
+**2026-10-13 发布完成：** [正式发布流程](https://github.com/yanglaofish/Fishtools/actions/runs/38361266757)全部成功。
+Windows / Ubuntu 各 488 项通过、1 项平台专用跳过，零失败；自包含包与断网容器验收通过。
+npm `latest` 为 0.5.2，独立下载公开包的校验值与注册表和 [Release](https://github.com/yanglaofish/Fishtools/releases/tag/v0.5.2) 一致。
+最新 issue #4 的复制入口修正已包含在该版本。
+
 ## 0.5.1 复核修正
 
 - 动作选择直连时，外部子进程不再重新继承系统代理；所选代理配置也不会被宿主残留变量干扰。
@@ -102,20 +145,20 @@ npm `latest` 为 0.5.1；独立下载包校验值与注册表及 [Release](https
 
 ## 准备下一个版本
 
-在开发分支完成修改、更新说明并验证后，按上面的约定选择版本号。以下为本轮 `0.5.2` 的准备命令：
+在开发分支完成修改、更新说明并验证后，按上面的约定选择版本号。以下为本轮 `0.6.0` 的准备命令：
 
 ```sh
-npm version 0.5.2 --no-git-tag-version
+npm version 0.6.0 --no-git-tag-version
 git add package.json package-lock.json packages/core/src/version.js
-git commit -m "chore: prepare 0.5.2"
+git commit -m "chore: prepare 0.6.0"
 ```
 
 `npm version` 自动同步 CLI 的产品版本。合入 main 后，对经过审查的提交执行：
 
 ```sh
-git tag -a v0.5.2 -m "Fishtools 0.5.2"
+git tag -a v0.6.0 -m "Fishtools 0.6.0"
 git push origin main
-git push origin v0.5.2
+git push origin v0.6.0
 ```
 
 不要改动已经发布的 tag。主版本号尚为 0，升级前查看变更说明并备份工作区。

package/manual/docs/superpowers/plans/2026-10-13-command-shortcuts.md

@@ -85,8 +85,8 @@
 
 - [x] 更新产品版本为 0.5.2、发布说明；构建真实 npm 归档，针对同一归档运行本地全量测试。
 - [x] 使用 code-review 做规范与需求的独立双向复核，修正实际问题并验证。
-- [ ] 推送已审查提交；发布 tag 触发 Windows/Ubuntu、便携与断网验收，全部通过后 npm 发布。
-- [ ] 核对注册表版本、完整性和 GitHub Release，记录证据。
+- [x] 推送已审查提交；发布 tag 触发 Windows/Ubuntu、便携与断网验收，全部通过后 npm 发布。
+- [x] 核对注册表版本、完整性和 GitHub Release，记录证据。
 
 ## 执行记录
 
@@ -105,3 +105,4 @@
 - `30d7472` 全量 489 项：486 通过、1 项流式超时的单字节文件大小变化失败、2 跳过。164 次追加诊断均回收进程且内容稳定，没有复现该单次变化，未据此断言原因。新增探针改为返回后立即检查后代状态并严格比较实际内容，同期输出文件大小，生产实现保持原修复，重新做全量验收。
 - `7fa6178` 的完整本地验收 **489 项：487 通过、0 失败、2 跳过**，175.1 秒；使用 9,804,373 字节、285 个生产包的真实 npm 归档，含离线全局安装、脱离源码运行、中文快捷名与再次导出。生产代码和最后探针补充分别完成独立 Standards / Spec 复审，均无遗留已确认问题。进入已授权的推送与正式发布。
 - 用户随后要求最新 issue #4 的复制入口修正也纳入 0.5.2。首次正式验收 Linux 通过，Windows 两项短路径逐字断言失败，publish 跳过且 npm/Release 未发布。合入列表去重及实际目录身份断言修正，补充独立两轴复审均通过；重新构建 9,806,640 字节、285 个生产包的归档，本地全量 **489 项：487 通过、0 失败、2 跳过**，186.3 秒。核对未发布状态后更新待发布 tag，再执行正式双平台发布验收。
+- 最终提交 `fdb62c1` 的发布流程全部成功：Windows 与 Ubuntu 各 **488/489 通过、1 项平台专用跳过、0 失败**；两平台便携包和无 Node 的断网只读容器通过。npm `latest` 为 **0.5.2**，独立下载 9,806,832 字节公开包，SHA-512 与注册表、SHA-256 与 GitHub Release 均匹配。四个发布附件完整，最新 issue #4 纳入同一版本；后续只提交验收记录，不改变发行产物。