ShadowsocksX-NG/docs/design/plugin-transport-mode.md

插件记录的传输模式

日期：2026-10-11。状态：实施与验收完成。本文记录本次设计，不代表当前代码行为。

需求与已确认决定

• 插件记录增加 plugin_mode，候选值仅为 tcp_only 和 tcp_and_udp。
• 默认值为 tcp_only；生成 sslocal 配置时省略该值。
• tcp_and_udp 使 TCP 与 UDP 经过插件，用于用户自行配置支持 SIP003u 的插件。应用不探测支持情况，不维护支持清单。
• 用户与内置插件记录均可以配置传输模式。同一记录的别名共享模式；用户覆盖使用用户记录自己的模式。
• 模式仅保存在本机插件配置，不进入服务器资料、分享或订阅。
• 旧文件缺少字段时使用 tcp_only；未知值使读取失败，保留原文件，并沿用读取失败时阻止修改的行为。
• 保存成功后发布目录快照，并更新活动运行配置。保存失败不发布；运行更新失败不撤销成功保存的配置。
• 本次验收包含配置与源码构建的界面，不包含真实 SIP003u 通信。

界面

• 编辑器新增「插件传输模式」，选项原样显示 tcp_only 与 tcp_and_udp。
• 内置记录入口从「启动参数」改为「设置」，编辑器标题改为「内置插件设置」。
• 将内置记录的「清空参数」从设置列表移入编辑器的「本地启动参数」区域。
• 「清空参数」只清空当前编辑草稿的启动参数，保留传输模式；点击「保存」才写入配置，点击「取消」放弃草稿。参数为空时禁用按钮。
• 不增加列表模式摘要或单独的恢复默认操作。

验收

• 新记录默认使用 tcp_only；旧 v1、v2 文件可以读取，缺少模式时保持原行为。
• 两种模式保存后可以重新读取；未知模式触发读取失败。
• tcp_only 的 sslocal 服务器配置省略 plugin_mode；tcp_and_udp 写入 plugin_mode: "tcp_and_udp"；无插件时省略全部插件字段。
• 用户记录、内置记录、同记录别名与用户覆盖使用正确模式。
• 保存失败不发布新模式；保存成功触发既有运行更新流程。
• 源码构建的界面验证模式选择、草稿清空、取消与保存行为，并验证列表不再显示「清空参数」。
• 真实 SIP003u 通信标记为未验证。

上游依据

• 固定 shadowsocks-rust v1.25.0 的配置解析：缺少 plugin_mode 时使用 TcpOnly。
• 固定版本的地址选择：插件模式控制 TCP 与 UDP 是否使用插件地址。tcp_only 不关闭本地 SOCKS5 UDP 中继；tcp_and_udp 不保证插件自身支持 UDP。

本次验收结果

• 定向插件测试：22 项通过，0 失败，0 跳过。
• task test：1007 项 hostless 测试通过，0 失败，0 跳过；规则转换测试 21 项通过。该命令构建当前 app、Core 与 Agent。
• 现有真实 sslocal 插件进程冒烟测试：1 项通过；只验证默认 TCP 插件进程启动、监听与退出，不代表 SIP003u 通信验收。
• 修改文件的 swift format lint --strict 与 git diff --check 通过；全仓 SwiftLint 为 29 项警告，0 严重违规。
• 当前仓库源码编译的隔离原生预览通过：列表入口、两种模式、保存后重新打开、清空草稿、取消保留原参数、保存清空后保留模式、用户记录默认模式。夹具使用临时目录，不读取实际用户插件配置。
• Standards 审查：0 项标准违规；将内置编辑入口改名为 beginManagedSettings，对应当前职责。Spec 审查：0 项缺陷。
• 真实 SIP003u 通信未验证，按确认的验收范围执行。