Update plugin 系统管家 v0.2.1

plugins/system-manager/CHANGELOG.md

@@ -1,5 +1,20 @@
 # 更新日志
 
+## 0.2.1 - 2026-08-03
+
+### 修复
+
+- 监听 ZTools 插件退出生命周期，运行中升级时拒绝新的副作用请求，并等待当前 Agent journal 在有限窗口内收敛。
+- 为应用卸载与启动项变更增加受限、原子写入的本地恢复记录；重新进入时核对未完成批次，不自动重试系统写操作。
+- 恢复跨会话启动项撤销记录到根 MCP runtime，确保新会话仍可安全调用 `undo_startup_change`。
+- 将 Linux CNI、容器、虚拟化和 VPN 接口识别为受限网络接口；无法确认类型的非典型接口默认要求用户确认。
+- 要求 Agent 在 `prepare_lan_scan` 中显式确认受限接口，防止执行阶段绕过虚拟/VPN/未知接口的二次确认。
+
+### 优化
+
+- 接入 ZTools 3.0.2 注入的 `--plugin-primary-color`，保持警告、危险和成功状态颜色的语义独立。
+- 补充运行中升级、恢复记录、虚拟接口确认和主题色变量测试与安全说明。
+
 ## 0.2.0 - 2026-07-31
 
 ### 新增

plugins/system-manager/README.md

@@ -14,6 +14,8 @@
 
 五个 Feature 均显式支持 macOS、Windows 和 Linux。实际可见项目和系统命令仍受当前平台、权限与桌面环境影响。
 
+插件升级或退出时会先进入关闭状态：新的 Agent 副作用请求会返回 `SHUTTING_DOWN`，已开始的请求最多等待 200ms；应用卸载和启动项修改会把中断进度写入受限恢复记录，下一次进入只核对状态，不会自动重试。垃圾清理仍只把项目移入可恢复的系统废纸篓，局域网扫描有 12 秒上限且可取消，系统诊断 helper 也有独立超时与进程树清理；升级边界之外若已有底层系统调用，结果以模块返回值或恢复记录为准。
+
 ## 单插件结构
 
 ```text
@@ -24,7 +26,7 @@ system-manager/
 ├── tests/                   # workspace、路由和最终发布物整合测试
 ├── CHANGELOG.md             # 面向插件升级审核的版本更新记录
 ├── dist/                    # 单一 ZTools 发布目录（构建生成）
-└── release/system-manager-0.2.0.zip
+└── release/system-manager-0.2.1.zip
 ```
 
 最终 `dist` 只保留根 `plugin.json`。模块发布物位于 `dist/modules/<feature-code>/`，其嵌套 manifest 会在组装时删除。每个模块 HTML 都会注入位于文档流首部的统一 SuiteBar，共用 `_system-manager/navigation.js` 和 `_system-manager/navigation.css`。
@@ -44,6 +46,8 @@ window.systemManagerAgentAccess.revoke()
 
 Agent 工具要求 **ZTools 2.4 或更高版本**。宿主从 `plugin.json.tools` 读取声明，通过根 preload 的 `window.ztools.registerTool(name, handler)` 同步注册；对外名称由宿主自动加上 `system_manager_` 前缀。旧版宿主会安全跳过工具注册，图形界面与模块路由仍可使用。冷启动只需加载根 preload；22 个 handler 会在宿主的 5 秒等待窗口内完成注册，五个业务模块直到对应工具或页面实际使用时才按需加载。
 
+已针对 **ZTools 3.0.2** 验证：主题色变量动态注入、单一 `onPluginOut` 生命周期回调、插件运行中升级，以及更新入口不会改变现有 MCP 注册和页面路由。3.0.2 目前没有要求系统管家迁移到新的用户资料、文件剪贴板或截图参数 API；这些能力仍按插件现有边界保持未使用。
+
 工具默认是只读的：能力查询、诊断采集/渲染、应用/启动项/垃圾清单及局域网接口查询均不需要授权。产生写入或主动网络流量前，用户必须在系统管家 dashboard 明确授予以下一个或多个 scope：
 
 | Scope | 允许的副作用 |
@@ -54,7 +58,7 @@ Agent 工具要求 **ZTools 2.4 或更高版本**。宿主从 `plugin.json.tools
 | `system_cleanup` | 仅将白名单内、复验通过且属于当前用户的垃圾项目移入废纸篓 |
 | `lan_scan` | 在选定接口上发送有界 ICMP；最多每 15 秒启动一次，可选 DNS 解析默认关闭，不做端口、公网或漏洞扫描 |
 
-scope 授权最长 10 分钟，可随时撤销，并且只保存在当前 dashboard renderer 的内存中；离开或刷新 dashboard、重启插件都会立即失效。应用处理、新的启动项启停、垃圾清理与 LAN 扫描还必须先调用对应 `prepare_*` 工具取得带摘要与摘要指纹的单次 `actionId`；action 90 秒后失效，执行时会再次复验。启动项撤销则只接受最近一次成功变更返回且仍有效的 `operationId`。副作用调用要求 8–128 字符的 `idempotencyKey`；当前 renderer 会话内最近 10 分钟最多保留 100 条执行记录，可用 `get_operation_result` 查询且不会重放操作。`get_capabilities` 与查询结果都会返回 `runtimeSessionId`；刷新、导航或重启后该值变化，旧会话的操作结果与撤销元数据无法恢复。授权不足或 LAN 限速这类 action 消费前失败不会占用幂等键，action 一旦消费，其成功或失败结果都会保持稳定。
+scope 授权最长 10 分钟，可随时撤销，并且只保存在当前 dashboard renderer 的内存中；离开或刷新 dashboard、重启插件都会立即失效。应用处理、新的启动项启停、垃圾清理与 LAN 扫描还必须先调用对应 `prepare_*` 工具取得带摘要与摘要指纹的单次 `actionId`；action 90 秒后失效，执行时会再次复验。启动项撤销则只接受最近一次成功变更返回且仍有效的 `operationId`。副作用调用要求 8–128 字符的 `idempotencyKey`；当前 renderer 会话内最近 10 分钟最多保留 100 条执行记录，可用 `get_operation_result` 查询且不会重放操作。`get_capabilities` 与查询结果都会返回 `runtimeSessionId`；根 MCP 结果仍是会话内存数据，但启动项 rollback 与应用卸载逐项 operation/result 会在 preload 私有 journal 中短暂持久化并在新会话 reconcile/核对。授权不足或 LAN 限速这类 action 消费前失败不会占用幂等键，action 一旦消费，其成功或失败结果都会保持稳定。
 
 ZTools 的 `registerTool` 当前不提供逐调用宿主审批提示，因此系统管家不把注册本身当作用户同意。安全补偿包括：dashboard 短时 scope、默认只读、90 秒预览 action、执行前复验、幂等日志、有界缓存/分页/数组、固定平台 allowlist、错误脱敏，以及应用处理和清理仅移入可人工恢复的废纸篓。`copyText`、`revealPath`/`reveal` 和 `cancelScan` 仍是 UI-only 辅助能力，不注册为 Agent 业务工具。
 

plugins/system-manager/SECURITY.md

@@ -13,6 +13,7 @@
 - 开机启动：只修改 Linux/Windows 上明确支持且可回滚的用户级项目；macOS、系统级与未知来源项目保持只读。扫描、修改和撤销全局串行，避免跨项目并发放大本地校验或子进程调用。
 - 垃圾清理：只扫描白名单缓存、日志和临时目录；近期项目仍可预览但默认不选择，符号链接、其他用户内容、系统目录或无法完整复验的项目会安全跳过。
 - 局域网发现：只读取邻居表并发送有界 ICMP Echo；禁止端口扫描、服务识别、漏洞探测和公网扫描。
+- 升级/退出生命周期：ZTools 3.0.2 的单一 `onPluginOut` 回调由套件根 preload 统一协调；进入关闭状态后拒绝新的 Agent 写入，最多等待 200ms。应用卸载与启动项修改使用带 TTL 的原子恢复记录并在新会话中只核对不重试；垃圾清理的废纸篓移动、LAN 的可取消限时扫描和诊断 helper 的进程树清理分别按模块边界收敛，升级中断后需以页面结果或恢复记录为准。
 
 ## Agent / MCP 边界
 
@@ -22,7 +23,7 @@ Agent 工具要求 ZTools 2.4+。根 preload 在冷启动时同步注册 manifes
 
 默认授权状态为关闭，所有读取工具保持只读。有副作用能力被拆成五个独立 scope：`report_export`、`application_removal`、`startup_changes`、`system_cleanup`、`lan_scan`。只能由用户在系统管家 dashboard 授予，最长 10 分钟且可立即撤销；授权只保存在当前 dashboard renderer 的内存中，不写入 `dbStorage` 或业务结果。离开或刷新 dashboard、renderer 重建和插件重启都会立即清除授权，任何调用都不会延长过期时间。
 
-应用处理、新的启动项启停、垃圾清理和 LAN 扫描使用 prepare/execute 两阶段协议。prepare 返回绑定规范化参数的 `actionId`、`actionDigest`、摘要与过期时间，90 秒后失效且单次消费；execute 重新检查 scope、action、快照及底层文件/接口状态。启动项撤销只接受最近一次成功变更返回且仍有效的 `operationId`。副作用调用使用 8–128 字符 `idempotencyKey`；当前 renderer 会话内最多 100 条结果保留 10 分钟，重复键不会重放操作，`get_operation_result` 仅查询既有状态。`runtimeSessionId` 用于识别刷新、导航或重启造成的会话重建；旧会话 journal 与撤销元数据不会持久化，也无法恢复。授权不足或 LAN 限速发生在 action 消费前时不保留临时 journal 记录，条件恢复后可用同键重试；action 一旦消费，可能已产生副作用的成功或失败结果都会固定保留。诊断报告最多缓存 3 份、5 分钟。
+应用处理、新的启动项启停、垃圾清理和 LAN 扫描使用 prepare/execute 两阶段协议。prepare 返回绑定规范化参数的 `actionId`、`actionDigest`、摘要与过期时间，90 秒后失效且单次消费；execute 重新检查 scope、action、快照及底层文件/接口状态。启动项撤销只接受最近一次成功变更返回且仍有效的 `operationId`。副作用调用使用 8–128 字符 `idempotencyKey`；当前 renderer 会话内最多 100 条结果保留 10 分钟，重复键不会重放操作，`get_operation_result` 仅查询既有状态。`runtimeSessionId` 用于识别刷新、导航或重启造成的会话重建；根 MCP journal 仍为会话内存数据。启动项 preload 会在写入前将单条 rollback journal 原子保存到隔离 `dbStorage`（无该能力时使用用户目录受限文件），新会话扫描时按权威状态 reconcile，凭据 10 分钟后清理；应用卸载则逐项保存 operation/result，最多保留一条且 10 分钟后清理，重启后只报告需核对状态，不会自动重试。授权不足或 LAN 限速发生在 action 消费前时不保留临时 journal 记录，条件恢复后可用同键重试；action 一旦消费，可能已产生副作用的成功或失败结果都会固定保留。诊断报告最多缓存 3 份、5 分钟。
 
 具体副作用仍受模块边界约束：导出只接受缓存 `reportId` 并打开系统保存对话框，不接收任意路径或正文；应用/残留与垃圾项目仅移入可人工恢复的系统废纸篓；启动项只操作受支持的用户项并可能立即启停用户服务；LAN 只对已复验接口执行最多本机 /24 的 ICMP、最多每 15 秒启动一次，DNS 默认关闭。剪贴板复制、路径 reveal 和扫描 cancel 是 UI-only 辅助接口，不注册为 Agent 业务工具。
 

plugins/system-manager/modules/application-uninstaller/README.md

@@ -23,7 +23,7 @@ Windows 不使用 `Win32_Product`，避免它触发 MSI 自修复；注册表扫
 7. 目录使用 `opendir` 流式生成递归内容摘要，并限制 50,000 项、64 层、5 秒和同一设备；任一限制触发即不可自动删除。预览后任意深度的新建、删除或元数据变化都会阻止整体处理。
 8. 符号链接、根目录、Home 本身、系统目录、共享容器和越界路径均拒绝自动处理。
 9. 文件优先进入系统废纸篓/回收站，不使用 `rm -rf` 或等价命令。
-10. preload 只暴露 `scanApps`、`inspectApp`、`executePlan`、`revealPath` 四个业务接口；扫描异常通过结构化 warning 显示，不伪装成“0 个应用”。
+10. preload 只暴露 `scanApps`、`inspectApp`、`executePlan`、`revealPath` 四个业务接口及生命周期用的 `shutdown`；扫描异常通过结构化 warning 显示，不伪装成“0 个应用”。
 11. macOS 与 Linux 应用枚举共享约 15 秒总预算；每次目录读取、元数据读取和外部解析都只使用剩余预算，超时返回已完成的部分结果及 warning。
 12. 用户可写的 `Info.plist` 与 `.desktop` 必须是非符号链接普通文件且不超过 1 MiB；两者都通过文件句柄有界读取并检测读取期变化。macOS `plutil` 只解析已捕获的 stdin 字节，不再按路径二次打开；保留到应用目录中的字段会截断并强制复制，避免短字符串继续引用超大元数据缓冲区。