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 的[配置解析](https://github.com/shadowsocks/shadowsocks-rust/blob/v1.25.0/crates/shadowsocks-service/src/config.rs#L2192-L2217)：缺少 `plugin_mode` 时使用 `TcpOnly`。
- 固定版本的[地址选择](https://github.com/shadowsocks/shadowsocks-rust/blob/v1.25.0/crates/shadowsocks/src/config.rs#L712-L728)：插件模式控制 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 通信未验证，按确认的验收范围执行。