YANG JIANKUAN
5326c572a2
迁入通用节点部署工具、离线交付页生成器和共用技能，隔离真实配置与交付产物。统一 Codex 与 Claude Code 开发约定，补充节点迁移与运维文档。 完善 FINAL、策略组引用、输入校验、Surge 字段编码与 AI DNS 例外保护，增加隔离测试和订阅验证工具。 验证：全量类型检查、44 项单测、前端构建、脚本语法、技能入口与凭据隔离检查均通过。
3.8 KiB
Surge 订阅变更与验证
2026-10-03 的缺陷与证据见 体检报告。后续节点、组、规则和设置变更使用本文件的检查；具体 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，然后运行：
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 和业务连接仍需设备侧验证。