ShadowsocksX-NG/docs/design/managed-cloak-plugin.md

新增 Cloak 托管插件

日期：2026-10-12。状态：实施、验证与审查完成。本文记录本次任务的需求与决定，不代表当前实现。

已确认决定

• 将 Cloak 客户端作为随应用发布的托管 SIP003 插件接入。
• 沿用现有插件选择器、通用参数编辑器与插件管理界面，不新增 Cloak 专用表单。
• 固定记录身份及打包文件名为 ck-client；服务器可引用的名称仅为 cloak、cloak-v2。
• 使用上游 v2.12.0 的官方 darwin-arm64 二进制，固定下载来源及 SHA-256；扩展现有下载脚本以支持直接二进制，沿用内嵌签名与打包验证流程。
• 本次只接入和验收 TCP，默认 tcp_only；沿用现有插件传输模式设置。Cloak UDP 选项不作为 SIP003u 支持依据。
• 用户同名覆盖、本地启动参数与服务器插件选项的边界沿用现有插件记录模型。
• 沿用现有原文透传，不增加 Cloak 专属字段校验、参数改写或配置文件管理。外部配置文件由用户维护；分享文件路径不包含文件内容，接收方自行提供对应文件。使用说明记录上游字符串解析限制。

验收范围

• 自动化验证别名解析、用户覆盖、配置生成、下载校验与打包流程，并执行适用于本次改动的仓库检查。
• 使用当前源码构建的原生界面验证插件选择、参数编辑与内置设置。
• 不运行真实 sslocal 与 ck-client 本地冒烟（启动、监听和停止清理）。用户说明已经通过用户自定义插件方式验证过；该验证属于用户提供的既有证据，不作为此次托管打包的新增验收结果。
• 本次不验收远端 Cloak 数据通信，结果标记为未验证。

实施授权

用户调用 implement 技能，授权按以上范围实施、审查并在当前分支创建本地提交。

上游依据

• v2.12.0 发布。
• 客户端入口。
• 配置解析。

现有领域术语已覆盖本次接入，不新增词条。当前已确认决定沿用既有插件模型，暂不另建 ADR；若后续改变配置所有权或验证边界，再记录相应取舍。

本次验收结果

• task test：1011 项 hostless 测试通过，0 失败、0 跳过；包括参数化共 1107 次执行。另有 5 项外部二进制下载测试与 21 项规则转换测试通过。
• 下载测试覆盖直接二进制安装、缓存命中、缓存漂移、资产哈希不符、非 Mach-O 拒绝、旧 tar 清单兼容与未知格式拒绝。测试只编译本地夹具，不运行 sslocal 或 ck-client。
• 当前源码构建的应用包含 arm64 ck-client 和 Cloak 许可证、来源、第三方声明。packaging-gate.sh 通过，覆盖 Developer ID 签名、Hardened Runtime、固定签名标识与 Helpers 文件清单。
• 当前源码插件组件的隔离原生预览通过：选择器显示 cloak、cloak-v2；选择版本别名；参数列表输入后切换原始文本；Cloak 内置设置默认 tcp_only；本地启动参数保存后重新打开保持。预览只使用临时配置与可执行占位文件，不读取实际用户配置或启动代理。
• 修改的 Swift 文件通过 swift format lint --strict；Shell 语法检查与 git diff --check 通过。全仓 SwiftLint 为 29 项警告、0 项严重违规；Xcode 的 AppIntents 元数据跳过与 IDE 启动诊断警告不阻断测试。
• 对任务起点 686fa4cd5c87c6f34fd78c3fc3f84e6d95cbe594 后的工作分别执行 Standards 与 Spec 审查，最终各 0 项可操作问题。
• 真实 sslocal 与 ck-client 本地冒烟按用户要求未运行；用户此前通过自定义插件方式验证的结果不冒充本次新增证据。远端数据通信未验证。