feat: 合并边缘节点运维并完善 Surge 配置安全

迁入通用节点部署工具、离线交付页生成器和共用技能，隔离真实配置与交付产物。统一 Codex 与 Claude Code 开发约定，补充节点迁移与运维文档。完善 FINAL、策略组引用、输入校验、Surge 字段编码与 AI DNS 例外保护，增加隔离测试和订阅验证工具。验证：全量类型检查、44 项单测、前端构建、脚本语法、技能入口与凭据隔离检查均通过。
2026-10-03 23:19:59 +08:00
parent 7358008936
commit 5326c572a2
93 changed files with 6780 additions and 320 deletions
--- a/docs/AI-COLLABORATION.md
+++ b/docs/AI-COLLABORATION.md
@@ -0,0 +1,62 @@
+# Codex 与 Claude Code 协作
+
+项目开发约定以根目录 `AGENTS.md` 为唯一来源。原 `CLAUDE.md` 中的架构、协议适配、前端设计、数据与部署约定已迁入，并根据当前代码补充了初始化、环境变量、AI DNS 与验证说明。
+
+## 指令入口
+
+| 工具 | 项目指令 | 项目技能 |
+|---|---|---|
+| Codex | 原生读取根目录 `AGENTS.md` | `.agents/skills/<name>/SKILL.md` |
+| Claude Code | `CLAUDE.md` 中的 `@AGENTS.md` 导入 | `.claude/skills/<name>/SKILL.md` |
+
+Claude Code v2.1.277 起支持直接读取 `AGENTS.md`，但默认在当前目录或祖先目录已有 `CLAUDE.md`／`CLAUDE.local.md` 时优先读取 Claude 文件。保留 `CLAUDE.md` 的显式导入，使支持导入的旧版本与新版本都能读取同一份规则；无需修改用户全局配置。原生支持不可用的部分旧版本会话也可通过导入加载。
+
+文件名使用大写、复数的 `AGENTS.md`。不要新增 `agent.md`、`AGENT.md` 或复制一份独立的 Codex 规则。Claude 的 `@path` 是其导入语法，Codex 项目入口本身包含完整规则，无须依赖此语法。
+
+新开会话时从仓库根目录启动工具。Claude Code 可用 `/memory` 或 `/context` 检查项目指令；Codex 可询问当前项目约定，并用 `/skills` 查看发现的技能。若当前会话未发现新技能，重开会话；不需要额外安装项目技能。全局个人指令与机器设置继续由各工具管理，不写入本仓库。
+
+## 共用技能
+
+保留现有 `.claude/skills/` 作为技能源目录，Codex 入口使用相对目录符号链接。Codex 官方支持扫描符号链接指向的技能目录，脚本及评估样例因此也共用一份：
+
+```text
+.claude/skills/
+├── deploy/                   # SKILL.md 与 scripts/deploy.sh
+├── update-db/                # SKILL.md、scripts/api.sh 与 evals/
+└── edge-node-multi-protocol/  # 节点部署脚本、参考资料与交付模板
+.agents/skills/
+├── deploy -> ../../.claude/skills/deploy
+├── update-db -> ../../.claude/skills/update-db
+└── edge-node-multi-protocol -> ../../.claude/skills/edge-node-multi-protocol
+```
+
+| 任务 | 技能 | Codex 显式调用 | Claude Code 显式调用 |
+|---|---|---|---|
+| 部署前端／后端到 LA | `deploy` | `$deploy` | `/deploy` |
+| 线上数据盘点、导入预览或修改 | `update-db` | `$update-db` | `/update-db` |
+| 边缘 VPS 部署、重建、协议维护与交付 | `edge-node-multi-protocol` | `$edge-node-multi-protocol` | `/edge-node-multi-protocol` |
+
+自然语言请求也可以匹配技能。技能提供操作方法，具体外部操作范围仍以用户任务授权为准；阅读部署文档或修改代码不会自动触发上线。
+
+脚本示例统一保留已有 `.claude/skills/` 路径，两种工具都可在仓库根目录执行。同一脚本也可从 `.agents/skills/` 链接路径执行。新增技能时只写一份源目录，并在 `.agents/skills/` 增加相对链接。
+
+Git 应保存这些目录链接；在 Windows 上克隆时需要启用符号链接支持，推荐 WSL。若 checkout 将链接变成文本文件，Codex 无法自动发现技能，应恢复目录链接；不要复制出第二份技能。
+
+## 维护与接续
+
+- 架构或业务约束改动更新 `AGENTS.md`；较长的专题说明放入 `docs/` 并按任务引用。
+- 运维流程改动更新 `.claude/skills/<name>/SKILL.md` 及其脚本；`.agents/skills/` 只维护链接。
+- 节点与应用在本仓库统一维护，节点目录与当前舰队见 `edge-nodes/README.md`。通用工具可入库，真实配置／交付产物放 `edge-nodes/private/` 并用受控备份转交；原 `../edge-nodes/` 仅保留迁移前备份。旧工程指令保存在私有归档中，不作为当前约定。
+- 普通开发从 `shared` 的类型／校验、`server` 的 API 与 IR、`web` 的状态与页面定位改动。新增客户端先扩展客户端类型与能力矩阵，再增加独立生成器和订阅端点。
+- 修改规则模板只影响初始化，已有库的配置更新走管理 API；代码部署与数据更新分别执行。
+- 本地验证按改动范围选择类型检查、单测或构建。临时启动与数据库验证在进程启动前设置临时 `DATA_DIR`，避免触碰真实节点数据。
+- 交接说明记录已完成改动、验证结果与未完成项；可复用的认识写入项目文件，不依赖某个工具的私有会话记忆。
+
+## 官方依据
+
+- [Codex：AGENTS.md 加载规则](https://developers.openai.com/codex/guides/agents-md)
+- [Codex：技能目录与符号链接支持](https://developers.openai.com/codex/skills)
+- [Claude Code：AGENTS.md 支持与共用导入](https://code.claude.com/docs/en/memory#agentsmd)
+- [Claude Code：项目技能](https://code.claude.com/docs/en/skills)
+
+支持行为核对于 2026-10-03；若工具升级后入口行为变化，按上述官方文档重新核对。
--- a/docs/DEPLOY.md
+++ b/docs/DEPLOY.md
@@ -2,6 +2,8 @@

 服务器资源有限（1 核／1.9G），采用 Node 直跑 + systemd 守护，前端在本机构建后由服务端静态托管，反向代理与证书由 aaPanel 管理。

+本文描述 Proxy Station 应用发布。边缘 VPS 的部署、重建与协议维护已合入本仓库，见 [节点工作区](../edge-nodes/README.md) 与 `edge-node-multi-protocol` 技能；其私有资料不随应用部署上传。LA 同时承载节点与本应用，维护 nginx、证书或 WARP 时需核对共享服务影响。
+
 ## 拓扑

 ```
@@ -22,7 +24,7 @@

 ## 更新代码

-日常更新用项目级 Skill `deploy`（对 Claude 说「部署」即可触发），也可直接跑脚本：
+日常更新用 Codex／Claude Code 共用的项目级技能 `deploy`（说「部署」即可匹配；也可分别用 `$deploy`／`/deploy` 显式调用），也可在仓库根目录直接跑脚本：

 ```bash
 bash .claude/skills/deploy/scripts/deploy.sh all      # 前后端一起（默认）
@@ -47,7 +49,7 @@ ssh la 'systemctl stop proxy-station && install -m 644 -o proxy-station -g proxy
 ## 反向代理注意点

 - aaPanel 的反代模板不带 `X-Forwarded-Proto`／`X-Forwarded-Host`，已手工补进反代配置。服务端 `routes/sub.ts` 的 `baseUrl()` 依赖这两个头还原外部地址，缺失时 Surge 的 `#!MANAGED-CONFIG` 与 Clash 的 provider URL 会变成 `http://`。
- 站点通过面板类 `AddSite`／`SetSSL`／`CreateProxy`／`HttpToHttps` 创建（脚本模式见 edge-nodes 的 `09-aapanel-sites.py`），不要手写 vhost，否则面板里看不到。
+- 站点通过面板类 `AddSite`／`SetSSL`／`CreateProxy`／`HttpToHttps` 创建（脚本模式见本仓库 `.claude/skills/edge-node-multi-protocol/scripts/09-aapanel-sites.py`），不要手写 vhost，否则面板里看不到。
 - 泛域名 `*.la.njcqtechaicoding.com` 的 DNS 已指向服务器，新子域无需单独加记录。
 - acme.sh 的 `--reloadcmd` 要把新站点加进复制循环，且证书源路径必须写死（原先引用未定义的 `$SRC`，续期后不会重新部署证书）。

--- a/docs/SEEDING.md
+++ b/docs/SEEDING.md
@@ -1,21 +1,34 @@
 # 节点导入指引

-proxy-station 不直接读取 edge-nodes 工作区（那里全是真实凭据，保持解耦），节点通过 Web 界面批量粘贴分享链接导入。
+节点部署管理已迁入本仓库的 `edge-nodes/`，真实配置与交付产物位于 Git 忽略的 `edge-nodes/private/`。Proxy Station 应用运行时不自动读取该目录，节点仍通过 Web 界面批量粘贴分享链接导入。工作区说明见 [edge-nodes/README.md](../edge-nodes/README.md)。

-## 从 edge-nodes 交付文档导入
+## 从本仓库私有交付文档导入

-每个节点目录 `<id>-edge-node-docs/` 已生成好分享链接：
+每个节点目录 `edge-nodes/private/<id>-edge-node-docs/` 已生成好分享链接；以当前部署的 `scripts/node-links/` 为准，避免同时混入旧交付链接与重复副本。RN 当前使用 `rn2-edge-node-docs/`，旧 `rn-edge-node-docs/` 只作历史记录。

- `<proto>-<egress>.link`——VMess／Trojan 的分享链接文件（`vmess://`、`trojan://`）
- Shadowsocks 线路没有通用分享链接，用 sing-box JSON（`ss-*-singbox.json`）里的参数手动添加，或按 SIP002 + v2ray-plugin 格式自拼：
+- `<proto>-<egress>.link`——VMess／Trojan／Shadowsocks 的分享链接文件（`vmess://`、`trojan://`、`ss://`）；当前生成器会生成本系统可解析的 Xray 风格 SS over WS 链接
+- 旧交付若只有 Shadowsocks sing-box JSON（`ss-*-singbox.json`），用其中参数手动添加，或按 SIP002 + v2ray-plugin 格式自拼：
  `ss://base64url(chacha20-poly1305:密码)@域名:443?plugin=v2ray-plugin%3Btls%3Bmode%3Dwebsocket%3Bhost%3D域名%3Bpath%3D%2F路径#名称`
- Hysteria2 线路在 `scripts/node-links/` 下有 `hysteria2://` 链接（含 `obfs=salamander&obfs-password=…`）
+- Hysteria2 线路在 `scripts/node-links/` 下有 `hy2://` 或 `hysteria2://` 链接（含 `obfs=salamander&obfs-password=…`），两种 scheme 均可解析

 操作：

-1. 在 edge-nodes 侧汇总链接：`cat ~/Development/Fusion/Projects/edge-nodes/*-edge-node-docs/*.link`
+1. 在仓库根目录收集当前舰队支持的链接（输出含凭据，只在本机使用）：
+
+   ```bash
+   for site in sg la rn2 jp; do
+     for proto in vmess trojan ss hy2; do
+       for egress in direct warp; do
+         link="edge-nodes/private/$site-edge-node-docs/scripts/node-links/$proto-$egress.link"
+         [ ! -f "$link" ] || cat "$link"
+       done
+     done
+   done
+   ```
+
+   也可从 `edge-nodes/private/边缘节点交付文档.html` 挑选对应线路。
 2. 打开 proxy-station「节点」页 →「批量导入」→ 粘贴（每行一条）→「解析预览」确认字段 →「导入」
-3. SOCKS5 线路为内部使用，不要导入本系统
+3. TUIC／SOCKS5 线路不属于本系统当前支持的类型，单独使用，不导入。线上数据任务按 `update-db` 技能先备份再走管理 API

 ## 命名建议（影响地区组归类）

--- a/docs/SURGE-AUDIT-2026-10-03.evidence.json
+++ b/docs/SURGE-AUDIT-2026-10-03.evidence.json
--- a/docs/SURGE-AUDIT-2026-10-03.md
+++ b/docs/SURGE-AUDIT-2026-10-03.md
@@ -0,0 +1,224 @@
+# Surge macOS 订阅体检：2026-10-03
+
+本文保留修复前的体检结论；其中行号指体检时的源码与订阅快照。已实施的代码／生产修复和后续验证见 [修复记录](SURGE-FIX-2026-10-03.md)。
+
+实际订阅通过 Surge 6.9.1 的原生语法校验，生产数据与当前生成器一致。但存在规则被遮蔽、DNS 与连接策略不一致，以及管理 API 能接受最终导致无效配置或丢失规则的数据操作。
+
+本次只查询生产管理 API、盘点数据库行数、读取 HTTPS 订阅和公开规则集；没有修改生产节点、规则、设置，没有部署、重启或切换本机活动配置。订阅 GET 按现有业务逻辑正常更新访问计数和访问时间（`server/src/routes/sub.ts:30`）。所有 API 写入复现都使用 `/private/tmp/` 下的隔离数据库与占位凭据。
+
+## 范围与证据
+
+| 项目 | 实际结果 |
+|---|---|
+| 生产节点 | 30 个，均启用；Surge 输出 22 个，排除 8 个 SS over WS |
+| 生产策略组 | 14 个，均启用；无循环引用；地区组有效候选为美国 10、新加坡 6、日本 6 |
+| 生产规则 | 116 条，其中 115 条启用；旧 `PROTOCOL,DOH,AI` 已停用 |
+| 最终订阅规则 | 118 条：115 条数据库规则 + 3 条生成的 DNS 出口规则 |
+| 生产规则集 | 数据库登记 62 个；当前配置引用 60 个不同远程 URL |
+| 生产订阅 | 1 个启用订阅，节点范围为空数组，即全部启用节点 |
+| 原生语法校验 | Surge Mac 6.9.1（12290），`surge-cli --check` 返回 `OK`、退出码 0 |
+| 代码与生产一致性 | 用生产 API 快照重建 IR，由本地实际生成器输出；与 HTTPS 订阅逐字节相同 |
+| 远程依赖 | 60/60 URL 本次返回 HTTP 200，合计 166,028 个非空、非注释条目，无 FINAL 条目 |
+| 使用本次规则集快照的校验 | 将远程 URL 替换为临时本地文件，再用官方 CLI 校验：`OK` |
+
+配置指纹、规则集指纹和复现结果见 [脱敏证据](SURGE-AUDIT-2026-10-03.evidence.json)。报告中的 `seq` 是数据库从 0 起算的顺序；“配置第 N 行”对应本次实际 HTTPS 响应。报告和证据不包含订阅 token、真实节点密码、UUID、节点地址或私有 Host IP。
+
+校验能力以 [Surge 官方 CLI 文档](https://manual.nssurge.com/tools/cli.html) 为依据。CLI 返回 OK 证明配置可解析，不能证明每个规则都会被命中，也不能代替节点连接、解锁或泄漏测试。
+
+P1 表示可导致配置不可用、规则丢失或重要控制失效；P2 表示行为偏差或需要修正的兼容性问题。静态推导的网络影响和依赖设备开关的风险明确另行说明。
+
+## 已确认的业务代码缺陷
+
+### C1 · P1：重置规则在存在自定义规则时失败，并先删除模板规则
+
+`server/src/routes/rules.ts:60` 调用 `seedRulesFromTemplate(db, { keepCustom: true })`。`server/src/db/seed.ts:52` 读取自定义规则后只删除模板规则，随后在第 63 行把仍在表中的自定义规则再次 INSERT。自定义规则主键重复，且这些操作没有事务包裹。
+
+隔离数据库复现结果：
+
+```text
+首次初始化：89 条模板规则
+新增自定义规则：HTTP 201，合计 90 条
+POST /api/rules/reset：HTTP 500
+错误：UNIQUE constraint failed: rules.id
+操作后：模板规则 0 条，自定义规则 1 条
+```
+
+生产快照中存在自定义规则，具备触发条件。**本次没有在生产调用 reset**，没有认定生产发生过此故障。
+
+修复建议：把整个重置过程放入事务；保留自定义规则时更新其顺序，或在事务内明确删除后重插，避免重复主键；同时明确“重置”究竟是否保留自定义规则。现有 update-db 技能描述为清掉自定义规则，与当前代码的 `keepCustom: true` 意图不一致，需要一起纠正。
+
+### C2 · P1：FINAL 并未得到完整保护，普通操作可使全部订阅无效
+
+`server/src/services/ir.ts:102` 先过滤 `enabled=true`；后面的 FINAL 特判只处理策略引用失效，不能保住已被停用、删除或改成其他类型的 FINAL。`server/src/routes/rules.ts:83` 和第 92 行允许停用及删除唯一 FINAL，排序接口也没有校验末尾位置或完整 ids。
+
+隔离 API 复现：创建 FINAL 返回 201，停用返回 200，生成器输出中 FINAL 数量变为 0；官方 CLI 返回：
+
+```text
+Rules must end with FINAL
+```
+
+当前生产恰有一条启用的 FINAL，位于末尾，因此当前配置通过校验。问题在后续编辑入口。官方要求规则以启用的 FINAL 结束；`dns-failed` 只是 DNS 失败时选用其策略，不会补回缺失的 FINAL。[FINAL 规范](https://manual.nssurge.com/rules/final.html)
+
+修复建议：在写入时保护唯一末尾 FINAL，完整校验排序，拒绝产生无效状态的修改；生成侧再验证，不要仅靠注释声称“永远保留”。
+
+### C3 · P1：输入与序列化允许合法 API 请求生成无效 Surge 配置
+
+`shared/src/schemas.ts:6` 对节点名只校验长度；`server/src/services/generators/surge.ts:51` 直接拼接声明名。规则值在第 117 行直接拼接；`quoteName()` 只为策略引用加引号，没有完整处理引号／反斜线。
+
+实际路由的隔离复现：
+
+| 请求 | API 结果 | 官方 CLI 结果 |
+|---|---|---|
+| 新建名为 `Bad = Name` 的 VMess 节点 | 201 | `Unknown proxy type: Name = vmess` |
+| 新建 URL-REGEX，值为 `^https://example.com/(a\|b),?c` | 201 | 把 `?c` 误当策略名，拒绝配置 |
+
+表中正则的 `\|` 仅为 Markdown 表格转义；实际测试值使用普通 `|`。
+
+Surge 对含逗号的正则值要求引用；新版本还有明确的引号、反斜线转义规则。这是已用官方解析器复现的错误，不是按自建解析器猜测。[HTTP 规则](https://manual.nssurge.com/rules/http.html)、[配置引用格式](https://manual.nssurge.com/profile/format.html)
+
+修复建议：区分声明名、策略引用、普通规则值、逻辑规则表达式的编码规则；拒绝不能安全表达的名称和换行输入。逻辑规则内部的逗号不能简单按普通字符串一律引用。
+
+### C4 · P1：策略组循环可通过 API 写入，导致整个配置被拒绝
+
+`server/src/routes/groups.ts:21`、第 38 行和第 77 行没有图循环检查。隔离测试建立 `A → B → A`，两次新建均返回 201，IR 保留这些引用；官方 CLI 拒绝：
+
+```text
+Loop reference is found in the policy group: A.
+```
+
+当前生产 14 个组没有循环。修复建议：新建、修改成员与改名时，在事务内校验引用存在、类型正确及图无环；不能把存在性检查当成循环检查。
+
+### C5 · P2：filterRegex 分支丢弃显式成员，只保留第一个来源组
+
+`server/src/services/generators/surge.ts:85` 在存在正则时不输出 `memberNames`，非 includeAllNodes 情形也只取第一个 group 成员。
+
+占位 IR 复现：输入组同时有显式 `DIRECT`、`includeAllNodes=true` 和正则，输出只有动态来源与正则，DIRECT 被丢弃。官方规定正则只作用于动态导入的成员，显式成员不受过滤；`include-other-group` 可包含多个来源组。[策略成员导入](https://manual.nssurge.com/policy-groups/policy-including.html)
+
+当前生产的三个地区组没有显式成员，暂不触发。修复建议：完整保留显式成员和多个动态来源，分别应用 Surge 规定的语义。
+
+### C6 · P2：VMess 参数映射不完整
+
+`server/src/services/generators/surge.ts:13` 没有输出 VMess 的 `skipCertVerify`，忽略 `security`，并无条件输出 `vmess-aead=true`。占位测试确认 `skipCertVerify=true` 不出现在结果中；`alterId=64` 也仍输出 AEAD。
+
+官方要求 AEAD 设置与服务端匹配，并支持 TLS 证书校验参数及指定的加密方式。当前生产 VMess 均为 `alterId=0`、`security=auto`、`skipCertVerify=false`，没有证据表明现有节点因此连接失败。[VMess 规范](https://manual.nssurge.com/policies/vmess.html)、[TLS 参数](https://manual.nssurge.com/policies/tls.html)
+
+修复建议：在能力层拒绝无法表达的旧协议组合，或按官方参数转换；不能让用户输入被静默忽略。所有输入字段都应有明确的支持／转换／拒绝行为。
+
+## 当前生产配置中的行为问题
+
+### D1 · P1：两条例外规则被更早的拦截集覆盖
+
+本次下载的 `https://ruleset.skk.moe/List/non_ip/reject.conf` 含有对 `amplitude.com` 的 DOMAIN-SUFFIX，以及对 `appsflyer` 的 DOMAIN-KEYWORD。
+
+| 域名 | 更早匹配 | 后面的例外规则 |
+|---|---|---|
+| `api.amplitude.com` | seq 11，REJECT | seq 94，Automatic |
+| `inapps.appsflyer.com` | seq 11，REJECT | seq 66，Bybit |
+
+现有例外不会覆盖早先的匹配。结论针对 Rule-Based 模式及本次规则集快照中的域名匹配；生产规则没有 pre-matching 标记，客户端资源可能存在缓存差异，未宣称已观察到设备上的请求失败。官方规则顺序是首条匹配决定策略。[规则顺序](https://manual.nssurge.com/rules/overview.html)
+
+修复建议：先确定这两项是需要放行的业务例外，还是需要保持阻断的跟踪服务，再决定是否提前。不能自动为全部跟踪域名放行。
+
+### D2 · P2：YouTube UDP 拦截被提前的 YouTube 规则集遮蔽
+
+数据库 seq 37／配置第 135 行的 YouTube 规则集含 `DOMAIN-SUFFIX,googlevideo.com`，策略为 Streaming；seq 110／配置第 208 行才是：
+
+```ini
+AND,((PROTOCOL,UDP), (DOMAIN-SUFFIX,googlevideo.com)),REJECT-NO-DROP
+```
+
+对携带 googlevideo.com 主机名的普通 UDP 请求，先前的 DOMAIN-SUFFIX 已匹配，后面的 AND 不会生效。STUN 请求另有更前的拦截，所以不能由此认定 STUN 保护失效。逻辑表达式本身通过官方语法校验。[逻辑规则](https://manual.nssurge.com/rules/logical.html)、[规则顺序](https://manual.nssurge.com/rules/overview.html)
+
+修复建议：若确实要让这类视频流量回落 TCP，把特定 UDP 规则放到相关服务域名规则之前；不要无依据地扩大为全局 UDP 拦截。
+
+### D3 · P2：AI DNS 映射忽略更早的连接例外，且 googleapis 覆盖整个服务族
+
+`server/src/services/generators/surge-ai-dns.ts:13` 收集所有指向 AI 的规则，并把结果整体放在数据库 Host 原文之前，不计算其他策略的更早例外。
+
+本次可确认的例子：
+
+```text
+连接策略：seq 8 的 Unbreak 集匹配 update.googleapis.com → DIRECT
+AI 域名规则：seq 30，DOMAIN-SUFFIX,googleapis.com → AI
+Host 第 224 行：*.googleapis.com → Cloudflare DoH
+Host 第 253 行：update.googleapis.com → 原来的国内 DNS
+```
+
+Host 首条匹配生效，所以后面的精确 DNS 设置被前面的通配覆盖；连接仍明确直连，而 Surge 自己解析该域名时按 AI Host 项处理。`youtube.googleapis.com` 也被 seq 30 送到 AI，而不会使用后面的 YouTube Streaming 策略。后一项是否符合业务意图需要确认。
+
+官方允许 Host 绑定规则集，当前语法没有问题；问题是两个独立的有序匹配系统没有同样的例外优先级。[Host 映射](https://manual.nssurge.com/dns/local-dns-mapping.html)
+
+修复建议：明确 Google AI 与其他 Google API 的范围，并在生成 Host 时保留需要优先的精确例外。对于连接规则中的 IP、进程或复杂表达式，不能承诺 Host 能完全复刻。
+
+### D4 · P2：靠前的 IP 拦截在业务域名规则前触发 DNS
+
+seq 12／配置第 110 行加载 `https://ruleset.skk.moe/List/ip/reject.conf`，位于 AI、YouTube、Bybit 等规则之前。本次文件含 778 条 IP／ASN 条目，其中 736 条没有 `no-resolve`。
+
+按官方执行语义，没有在更前规则被决定、且目标还是域名的请求会在这些 IP 条目处触发解析；DNS 失败时转到 FINAL 的策略，不继续匹配后面的业务域名规则。这是规范推导的控制流影响，未测量延迟或宣称已抓到泄漏。[IP 与 DNS 规则](https://manual.nssurge.com/rules/ip.html)
+
+修复建议：先确定 IP 黑名单是否应当主动解析所有域名；可考虑在该 RULE-SET 上加 `no-resolve`，或调整域名与 IP 规则顺序。前者会改变对未解析域名的 IP 拦截覆盖，不能当成无代价优化。
+
+### D5 · P2：三个地区测速地址在 Surge 中实际未生效
+
+数据库三个 url-test 组的 `testUrl` 为 Cloudflare 的 HTTP 204 地址，配置第 83–85 行输出为组参数 `url=`。全局 `proxy-test-url` 却为 Apple 的地址，节点没有 `test-url`。
+
+当前官方规范明确组上的旧 `url=` 无效，测速以节点 `test-url` 或全局地址为准。因此 UI 中组级测速地址与 Surge 实际测试依据不一致。[自动测速组](https://manual.nssurge.com/policy-groups/url-test.html)
+
+修复建议：把可用的设置模型改为官方支持的节点／全局测试参数；不要仅在组编辑界面保留一个看似可用但不会生效的字段。
+
+### D6 · P1（取决于设备可达性）：控制接口使用全接口监听和模板默认口令
+
+生产 General 同时配置 Remote Controller 和 HTTP API，均绑定 `0.0.0.0`，认证值与公开模板一致，并开启 Web Dashboard。模板本身也在仓库中，因此这些认证值不能视为私密、独立的设备凭据。订阅生成器原样透传 General。
+
+这表示网络可达的控制接口存在风险；没有检查设备防火墙或公网端口，**不认定当前已暴露互联网**。官方说明这两个入口具有控制 Surge 的能力，HTTPS 不能弥补已知认证值的问题。[控制接口规范](https://manual.nssurge.com/profile/general.html)
+
+修复建议：无远程控制需求时移除；本机需求绑定回环；有局域网控制需求时使用独立凭据与访问限制，避免所有订阅设备共享模板口令。
+
+### D7 · P2（取决于设备开关）：MITM 关闭服务端证书验证
+
+实际订阅有 `skip-server-cert-verify=true` 和 5 个 MITM hostname，但没有 CA 内容或 Keystore 引用。官方说明此项会在 MITM 时关闭真实目标服务器的证书验证；HTTPS 重写需要 MITM 开启和受信任证书。[MITM 规范](https://manual.nssurge.com/http/mitm.html)
+
+未检查设备是否关联其他包含 CA 的本地配置、模块或证书设置，因此不能宣称现在的 HTTPS 重写有效，也不能宣称已经发生 MITM 安全事件。修复建议：若需要 MITM，保留上游验证并在设备侧核实证书与开关；若仅需要代理分流，评估是否应移除不需要的 MITM 与重写配置。
+
+## 需要明确业务意图的配置
+
+这些项目有官方支持，不直接判为错误：
+
+| 项目 | 当前实际行为 | 需要明确的意图 |
+|---|---|---|
+| `⚡️ Automatic` | 实际类型是 select，默认第一项 Singapore，不跨地区自动选最快 | 名称是否应改，或者确实需要跨地区自动选择 |
+| `🎯 NoAuto` | 首项 Mainland → DIRECT；FINAL 指向它并带 dns-failed | 新设备／无保存选择时，未知流量与 DNS 失败是否应默认直连 |
+| `🪙 Bybit` | 首项 DIRECT | 是否希望交易业务默认直连，还是应固定所选出口 |
+| `📋 All Nodes` 与地区组 | Direct 和 Warp 节点混在一起，地区 url-test 可切换出口 | AI／交易业务是否需要限制出口类型及切换范围 |
+| FFSB 的进程直连 | App Bundle 写法有效，但规则在所有服务／通用集合之后 | 是只对未被前面规则匹配的请求直连，还是要整个 App 强制直连 |
+| `DOMAIN-KEYWORD,byb` | 对任何包含该短字符串的域名匹配 | 是否可以缩小为已知域名，降低误收范围 |
+| SMTP 相关直连 | `DOMAIN-SUFFIX,smtp` 匹配域名后缀；`URL-REGEX,(Subject\|HELO\|SMTP)` 检查 HTTP URL | 是否原本想匹配邮件协议；这两条不会识别邮件正文或 SMTP 命令 |
+
+select 的首项是未选过或保存的选择已失效时的默认；不能据此断言用户当前选中的出口。[手动选择组](https://manual.nssurge.com/policy-groups/select.html)
+
+`PROCESS-NAME,/Applications/FFSB.app/` 的首尾斜线属于官方 App Bundle 前缀匹配模式，不应误报为非法目录规则。[进程规则](https://manual.nssurge.com/rules/process.html)
+
+URL-REGEX 的作用对象是经过 HTTP 引擎处理的 URL，HTTPS 还取决于 MITM；正则中出现 SMTP／HELO 不会使它变成邮件协议匹配规则。[HTTP 规则范围](https://manual.nssurge.com/rules/http.html)
+
+## 已核实正常与验证边界
+
+- HTTPS 订阅的 `#!MANAGED-CONFIG` self URL 与实际请求完全一致；没有回落到内网 URL。当前 `interval=86400, strict=true` 受官方支持，但更新间隔不是推送保证，strict 也意味着更新失败时的可用性取舍。[托管配置](https://manual.nssurge.com/profile/managed-profile.html)
+- 生产三个地区正则能收纳当前 22 个可用节点，组引用无环，没有悬空规则策略，FINAL 位于末尾。
+- 8 个 SS over WS 排除符合 Surge 的能力范围；不要为了使节点数相同强行输出。[Shadowsocks](https://manual.nssurge.com/policies/shadowsocks.html)
+- Hysteria2 的 `salamander-password` 受支持，但官方注明需要 Mac 6.4.3+；实际检查使用 6.9.1。Host 规则集映射需要 Mac 5.10.0+。[Hysteria2](https://manual.nssurge.com/policies/hysteria2.html)
+- 60 个外部资源本次均可下载。`global_plus.conf` 只有注释，没有有效条目；这是零覆盖，不是失效 HTTP 响应。资源可动态更新，设备缓存内容可能不同。
+- 官方允许规则集中的非法行被跳过并记录警告。因此本次快照检查和 CLI 返回 OK，不能证明全部 166,028 个条目均已被客户端接受；逐条加载警告仍需设备侧检查。[规则集规范](https://manual.nssurge.com/rules/ruleset.html)
+- 现有 STUN 拦截的类型、关键字、顺序可用。生产没有全局 PROTOCOL,UDP,REJECT；`udp-policy-not-supported-behaviour=REJECT` 仅是匹配到不支持 UDP 的策略后的回落，不是全局禁用 UDP。[协议规则](https://manual.nssurge.com/rules/protocol-and-network.html)
+- Host 的 `server:` 映射只管 Surge 自己的 DNS 客户端，不会因 `use-local-host-item-for-proxy=true` 而改变远端代理的解析器；该开关只作用于 IP 映射。[Host 代理行为](https://manual.nssurge.com/dns/local-dns-mapping.html)
+- 当前四个站点的节点域名都有显式 Host IP 映射。没有因此假设永远不会出现 DNS 引导回退；仍需核对所选节点与设备日志。[加密 DNS 引导与回退](https://manual.nssurge.com/dns/encrypted-dns.html)
+- 没有切换本机配置、修改保存的策略选择、发起节点测速／带宽测试、导入 MITM CA 或抓取设备业务流量。
+
+## 建议处理顺序
+
+1. 修复 C1–C4：事务、FINAL、字段编码与循环校验，防止普通管理操作毁掉订阅。
+2. 明确业务例外后修正规则顺序：D1、D2；同时处理 D3 的 DNS 例外、D4 的主动 DNS 与 FINAL 失败策略。
+3. 收紧实际需要的控制入口与 MITM 参数：D6、D7。
+4. 对齐测速与节点映射：D5、C5、C6，再明确跨地区／出口选择策略。
+5. 对修复后的配置重复官方校验，然后在保留用户选择的前提下进行设备侧请求匹配、DNS、节点连接和业务回归。
+
+本报告完成体检与复现，未实施以上修复。后续修改应分别列出业务代码变更和生产 API 数据变更；当前不要通过 reset 路径更新生产规则。
--- a/docs/SURGE-CHANGES.md
+++ b/docs/SURGE-CHANGES.md
@@ -0,0 +1,33 @@
+# Surge 订阅变更与验证
+
+2026-10-03 的缺陷与证据见 [体检报告](SURGE-AUDIT-2026-10-03.md)。后续节点、组、规则和设置变更使用本文件的检查；具体 API 与生产备份操作见 update-db 技能。
+
+## 写入前
+
+- 获取最新全量节点、组、规则和设置，明确改动对象及受影响订阅范围。保留策略选择和出口语义；名称正则、节点范围、客户端排除不能只按数据库行数检查。
+- 节点／组名称不能包含配置分隔符、控制字符或与内置策略及另一类实体冲突。导入预览先验证字段；组更新替换完整 members，校验存在性、成员类型及完整图无环。
+- 保住唯一启用、末尾 FINAL；完整排序，不通过停用／删除 FINAL 处理兜底。不用 reset 调整生产；reset 的真实含义是事务内恢复模板并保留自定义规则。
+- 用官方规则顺序检查业务例外与广告／服务规则集的遮蔽，协议规则不放在提前覆盖其目标的域名规则后。IP 黑名单的 `no-resolve` 会改变未解析目标的拦截覆盖，要记录取舍。
+- DNS 对照连接规则、手写 Host、加密 DNS 出口和 FINAL 的 dns-failed 行为。Host 不能表达进程／协议／IP 路由，远端代理解析和浏览器自带 DoH 也不是同一条路径。
+- Surge 测速用节点 `test-url` 或 General 的 `proxy-test-url`，不用组级 `url=`。共享订阅不传播默认控制口令，MITM 保留上游证书验证。
+
+## 本地与生产验证
+
+代码修改运行相关单测与类型检查；共享字段或 IR 修改运行全量类型检查及单测，页面修改再构建。数据库／管理 API 测试必须在导入 db 模块之前设置绝对临时 DATA_DIR。
+
+将候选配置存到私有临时目录，文件权限 600，然后运行：
+
+```bash
+python3 scripts/check-surge.py /private/tmp/<profile>.conf
+python3 scripts/check-surge.py /private/tmp/<profile>.conf --fetch-rulesets
+```
+
+脚本先调用本机官方 `surge-cli --check`，再检查 FINAL、无效组级 url、公开控制口令和 MITM 参数。第二条下载当前规则集，以临时本地快照再次调用官方 CLI，并提示更早不同策略对后面域名规则样例的覆盖。提示需要结合业务审阅，不能自动将所有广告域名放行。它不模拟 IP／协议／进程或客户端缓存，规则集非法行也可能被 Surge 跳过；有疑点时查看设备资源加载警告及请求匹配日志。
+
+生产变更先在线备份，经管理 API 逐条核对状态，失败停止；在新代码防护部署后再写需要新防护的数据。写入后重读变更对象、核对数量与完整顺序，从实际 HTTPS 入口拉订阅并核对 MANAGED-CONFIG 的 self URL，然后重复以上校验。通过回环 API 拉的订阅可能带内网 self URL，不能拿它替代实际 HTTPS 验收。配置中的 token、密码、UUID、Host IP 不落仓库或共享日志。
+
+Clash 受影响时，用独立临时目录运行 `mihomo -t -d <临时目录> -f <配置>`；不要覆盖正在使用的配置或启动代理服务。没有客户端 CLI 的产物用对应单测和结构检查，明确尚缺的真机验收。
+
+不主动切换活动 Surge 配置、修改保存的组选择或导入 CA。CLI 成功只证明解析；节点连接、测速结果、DNS／WebRTC 和业务连接仍需设备侧验证。
+
+依据：[匹配与 DNS](https://manual.nssurge.com/rules/overview.html)、[FINAL](https://manual.nssurge.com/rules/final.html)、[成员导入](https://manual.nssurge.com/policy-groups/policy-including.html)、[测速](https://manual.nssurge.com/policy-groups/url-test.html)、[Host](https://manual.nssurge.com/dns/local-dns-mapping.html)、[引用格式](https://manual.nssurge.com/profile/format.html)、[CLI](https://manual.nssurge.com/tools/cli.html)。
--- a/docs/SURGE-FIX-2026-10-03.md
+++ b/docs/SURGE-FIX-2026-10-03.md
@@ -0,0 +1,54 @@
+# Surge 订阅修复与验证：2026-10-03
+
+本次完成 [体检报告](SURGE-AUDIT-2026-10-03.md) 中已确认缺陷的代码修复和生产定向调整。原体检报告保留为修复前证据，后续变更流程见 [Surge 变更验证](SURGE-CHANGES.md)。
+
+## 修复结果
+
+| 原问题 | 已实施的处理 |
+|---|---|
+| C1 重置丢失规则 | 事务内恢复模板，更新保留自定义规则的顺序，不重新 INSERT 原主键；自定义 FINAL 不与模板重复；故障注入证明失败整体回滚 |
+| C2 FINAL 缺乏保护 | API 拒绝停用、删除、改类型、重复创建、缺失／重复／不完整排序；IR 防御性保证唯一末尾 FINAL；页面关闭无效操作 |
+| C3 配置字段编码 | 节点／组名称与控制字符校验，导入预览和写入一致；Surge 值、规则参数转义；逻辑表达式校验结构、无策略子规则和嵌套深度 |
+| C4 组循环引用 | 写入前验证完整图、引用存在性与成员类型；组与成员替换、改名级联使用事务；节点／组／内置策略禁止名称冲突 |
+| C5 丢成员及单来源 | 保留显式节点和内置成员；包含全部成员组来源；全节点展开去重且显式成员先于自动补充成员 |
+| C6 VMess 映射 | 输出 TLS skip-cert-verify 与受支持 cipher；Surge 排除非零 alterId 和不支持 cipher 的 VMess，回报原因；当前生产节点不受额外排除 |
+| D1 业务例外遮蔽 | 将 AppsFlyer／Amplitude 既有例外放到广告集合之前，保留原策略 |
+| D2 视频 UDP 遮蔽 | googlevideo UDP 拦截移到 STUN 后、业务域名集合前，未扩大为全局 UDP 阻断 |
+| D3 DNS 例外冲突 | 手写 Host 优先；按规则顺序保留 AI 之前的非 AI 域名／规则集 DNS 例外；update.googleapis.com 的原精确 DNS 映射不再被覆盖 |
+| D4 提前主动解析 | 生产 IP reject RULE-SET 加 no-resolve；对尚未解析域名不再主动查 IP，已解析／IP 字面量仍可按黑名单处理 |
+| D5 测速地址无效 | 删除 Surge 无效组级 url=；生产 General 的 proxy-test-url 改为 Cloudflare 204；UI 标明组级地址仅用于 Clash／ShadowRocket；fallback 不输出 tolerance |
+| D6 默认控制口令 | 生产与初始化模板移除默认控制接口、Dashboard 及相关 TLS 参数；API／CLI 检查拒绝公开默认口令（包括带引号的写法）；恢复 LAN 访问限制 |
+| D7 MITM 上游验证 | 生产与模板改为 skip-server-cert-verify=false；API／CLI 检查阻止重新关闭上游验证 |
+
+`scripts/check-surge.py` 是新增的只读本地验证入口：官方 Surge CLI、FINAL、测速与安全参数、当前规则集快照，以及静态域名遮蔽提示。update-db helper 新增 `--body-file`，敏感 JSON 不进入命令参数，并校验／引用请求路径。它通过 mock SSH 验证 stdin 正文、URL 引用及危险路径拒绝。
+
+## 生产变更
+
+在线备份：`/opt/proxy-station/data/backups/before-surge-audit-fix-20261003-223218.db`，SQLite `PRAGMA quick_check` 返回 `ok`，备份含 116 条规则。
+
+在最新快照上预演三项管理 API 操作，执行前再次确认节点、组、规则、规则集与设置未被其他修改。三个 PUT 均返回 200：IP 黑名单参数、完整规则排序、Surge 设置。没有调用生产 reset、直接写 SQLite 或改动节点凭据、组成员和订阅范围。
+
+变更后盘点保持：30 个节点、14 个组、32 个成员、116 条规则（115 启用）、62 个规则集、1 个订阅、6 个设置。Surge 仍输出 22 个节点，8 个 SS over WS 按能力排除。
+
+前后端已部署；前端／源码指纹、systemd active、公网健康和无 token 管理接口 401 均通过。工作区尚未提交，没有创建 git 提交或推送。
+
+## 验证证据
+
+- 全量类型检查通过，44 项 Vitest 通过；隔离 SQLite 验证真实 API、事务回滚、重置与 FINAL／循环／非法输入保护。
+- 本机 Surge Mac 6.9.1（12290）实际校验六组占位配置，覆盖带逗号正则与密码、引号／反斜线、动态成员、TLS 与 cipher、逻辑规则及通知参数、缺失 FINAL 防御。
+- 前端 production build 通过。
+- 生产 API 快照中的 160 个节点／组／规则对象通过新 schema；候选操作在隔离数据库通过实际 API 路由执行。
+- 真实 HTTPS 的 Surge、Clash 和 ShadowRocket conf 均返回 200，并与已验证候选逐字节一致。
+- Surge 实际配置官方 CLI：OK；60/60 当前远程资源下载成功，替换为本地快照后官方 CLI：OK，静态域名遮蔽提示 0。
+- Clash 实际配置在独立临时目录下 `mihomo -t` 通过；没有启动代理或覆盖活动配置。
+- 技能 frontmatter、相对引用、符号链接、脚本语法及 git diff 空白检查通过。技能校验器缺少 PyYAML，使用项目现有 YAML 库适配其解析接口运行原校验规则，没有安装全局依赖。
+
+Surge HTTPS 正文 SHA-256：`0c12a56f72bbc0e1b116570bbcccd2208cdd1ca06568391a7769728ae5499caf`。脱敏校验结果见 [验证数据](SURGE-FIX-2026-10-03.verification.json)。原始 API 快照和含凭据配置仅在权限受限的临时目录，不进入仓库或报告。
+
+## 保留的业务选择与验收边界
+
+Automatic 仍为手动 select，Bybit 与 FINAL 的原默认直连语义、googleapis 的 AI 路由范围、Direct／Warp 混合候选、FFSB 和 SMTP 相关规则未擅自改成其他业务策略。googleapis 范围若要缩小，应另以业务域名范围为依据调整；本次修复其 DNS 例外优先级。
+
+no-resolve 会降低对未解析域名的 IP 黑名单覆盖，这是避免提前主动 DNS 的明确取舍。控制接口默认移除；需要远程控制的设备应在设备侧配置独立凭据与访问限制。设备需更新订阅后应用配置；托管订阅并非即时推送。
+
+本次没有切换设备活动配置、改变保存的组选择、测速连接、导入 CA 或抓取业务流量。CLI 成功不证明实际节点连通、测速结果、业务解锁、MITM 开关／CA 或 DNS／WebRTC 无泄漏；这些仍属于设备侧验收。
--- a/docs/SURGE-FIX-2026-10-03.verification.json
+++ b/docs/SURGE-FIX-2026-10-03.verification.json
@@ -0,0 +1,68 @@
+{
+  "surge": {
+    "httpStatus": 200,
+    "candidateExactByteMatch": true,
+    "bytes": 24963,
+    "sha256": "0c12a56f72bbc0e1b116570bbcccd2208cdd1ca06568391a7769728ae5499caf",
+    "nativeExitCode": 0,
+    "rulesetSnapshotCliExitCode": 0
+  },
+  "clash": {
+    "httpStatus": 200,
+    "candidateExactByteMatch": true,
+    "bytes": 25971,
+    "sha256": "98ff38b94544315bea8782344fa7a547c209be876653382fb3ebe78f45a002dd",
+    "nativeExitCode": 0
+  },
+  "shadowrocket-conf": {
+    "httpStatus": 200,
+    "candidateExactByteMatch": true,
+    "bytes": 12426,
+    "sha256": "90684cac8b1fb99df6b22b3629f5fab81a72f1bbf39e5fed4351494d819b783a"
+  },
+  "backup": {
+    "file": "before-surge-audit-fix-20261003-223218.db"
+  },
+  "schemaVersion": 1,
+  "date": "2026-10-03",
+  "client": {
+    "SurgeMac": "6.9.1",
+    "build": "12290"
+  },
+  "checks": {
+    "typecheck": "all packages passed",
+    "vitestPassed": 44,
+    "nativeSyntheticProfiles": 6,
+    "webBuild": "passed",
+    "schemaValidatedObjects": 160,
+    "rulesetDownloads": 60,
+    "domainShadowingWarnings": 0,
+    "skillValidation": "passed",
+    "apiHelperMockValidation": "passed"
+  },
+  "productionCounts": {
+    "nodes": 30,
+    "groups": 14,
+    "members": 32,
+    "rules": 116,
+    "enabledRules": 115,
+    "rulesets": 62,
+    "tokens": 1,
+    "settings": 6,
+    "surgeNodes": 22,
+    "excludedShadowsocksWebSocket": 8
+  },
+  "apiWrites": [
+    200,
+    200,
+    200
+  ],
+  "backupQuickCheck": "ok",
+  "deployment": {
+    "workingTreeUncommitted": true,
+    "gitHeadBasis": "7358008",
+    "frontendFingerprintPrefix": "e11cf89c7ea8",
+    "backendFingerprintPrefix": "062622032ebd"
+  },
+  "deviceTrafficValidated": false
+}
--- a/docs/SURGE-PRIVACY.md
+++ b/docs/SURGE-PRIVACY.md
@@ -12,13 +12,13 @@ DOMAIN,doh.pub,DIRECT
 DOMAIN,dns.alidns.com,DIRECT
 ```

-AI Host 映射使用 `server:https://1.1.1.1/dns-query`，放在普通 Host 映射之前。选择其他 AI 线路后 Cloudflare 查询也跟随同一策略组。该 IP 规则也会将访问 1.1.1.1 的其他连接交给 AI 组。
+AI Host 映射使用 `server:https://1.1.1.1/dns-query`。手写 Host 项在前，保留精确 DNS 例外；随后按连接规则顺序生成至最后一条 AI 域名规则的映射，先前非 AI 域名／规则集使用 General 的普通 DNS。这样 Unbreak 等先前例外不会被后面的宽泛 AI 映射覆盖。选择其他 AI 线路后 Cloudflare 查询也跟随同一策略组。该 IP 规则也会将访问 1.1.1.1 的其他连接交给 AI 组。

 本功能控制 Surge 自己执行的 DNS 查询。代理目标域名可能由远端代理解析；官方说明 use-local-host-item-for-proxy 仅适用于 IP 映射，不适用于 server: 映射，因此不能声称远端代理的解析器被改为 Cloudflare。浏览器自带 DoH 也不自动按 AI 域名匹配这些 Host 项。

 代理服务器域名的解析可能触发加密 DNS 循环依赖，需核对 Surge 日志。线上保留已验证的节点 Host IP 映射供引导使用；节点 IP 变化后更新映射，私有节点 IP 不提交仓库。

-数据库 settings/rules 是已有订阅的来源，模板仅首次初始化导入。修改默认 DNS 时使用 update-db 技能备份并经管理 API 更新；不重置规则。移除上一版全局 PROTOCOL,DOH,AI；保留 STUN 阻断及 UDP REJECT，不影响已授权的 WebRTC 防护。
+数据库 settings/rules 是已有订阅的来源，模板仅首次初始化导入。修改默认 DNS 时使用 update-db 技能备份并经管理 API 更新；不重置规则。全局 PROTOCOL,DOH,AI 已停用；保留 STUN 阻断，特定 googlevideo UDP 拦截放在服务域名规则之前。生产没有全局 UDP 拦截，不把 UDP 回落参数误认为全局阻断。

 导入时关联 General、Proxy、Proxy Group、Rule、Host，并开启增强模式。无需 MITM 证书。更新后清除 DNS 缓存并复测 Surge DNS 请求日志；生成配置验证不是设备泄漏测试。