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 发布](https://github.com/cbeuw/Cloak/releases/tag/v2.12.0)。
- [客户端入口](https://github.com/cbeuw/Cloak/blob/v2.12.0/cmd/ck-client/ck-client.go)。
- [配置解析](https://github.com/cbeuw/Cloak/blob/v2.12.0/internal/client/state.go)。

现有领域术语已覆盖本次接入，不新增词条。当前已确认决定沿用既有插件模型，暂不另建 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 本地冒烟按用户要求未运行；用户此前通过自定义插件方式验证的结果不冒充本次新增证据。远端数据通信未验证。