ShadowsocksX-NG/docs/design/user-plugin-mapping-commit-spec.md

用户插件映射提交回归（候选 3）

本文件记录 2026-10-05 用户确认的任务范围，基线为 e74f8df，仅作任务历史，不代表后续代码现状。

已定范围

保留 PluginCatalog 为映射提交 module，通过其 commit interface 验证验证、原子保存、发布、重校验与后续运行收敛。目录工作流和运行控制器作为集成观察面，不新增提交框架或进程启动 adapter。

• 保存失败不得改变已提交映射、代次或目录投影，也不得触发运行应用。
• 运行应用失败不得撤销保存；重建目录后仍恢复用户保存的映射。
• 连续 A→B 保存以 B 为最终意图；尚未开始的旧任务不得应用 A，已在运行的旧任务不得覆盖 B 的最终运行状态或契约。
• 映射变化立即重校验配置组成员；无效成员不参与运行，仍有有效成员时保留活动组目标。
• 无关映射变化与相同映射提交不得重启健康且契约一致的代理。
• 同一快照指同一已提交映射代次；文件可用性在每次激活或运行派生时重新检查。

只修复回归揭示的问题。不增加文件监听、文件替换自动重启、逐次映射保存的应用结果记录或管理 UI。运行失败继续由既有控制器状态呈现。

验证

采用进程私有临时目录、真实映射和运行文件存储、注入的 LaunchAgent 与可控健康探测。测试不会运行用户插件或修改真实系统代理。新增测试默认 Swift Testing；异步交错用已有 gate，不使用任意等待。