fix: 完善移动端订阅生成并同步分流配置文档

AGENTS.md

@@ -14,6 +14,18 @@
 
 本仓库统一维护边缘 VPS 节点的部署管理与 Proxy Station 代理节点、分流规则管理平台。Web 界面管理多协议节点（VMess／Trojan／Shadowsocks／Hysteria2）与策略组、规则，向 macOS Surge、iOS ShadowRocket、Android ClashMeta 下发托管订阅。规则模板来自 [ClashConnectRules/Surge](https://github.com/ClashConnectRules/Surge)，边缘舰队的工具与私有交付记录已从原 `../edge-nodes/` 迁入本项目。
 
+### 当前生产约定（2026-10-04）
+
+最新盘点、完整组顺序与成员、节点启用范围和 Session 变更索引见 [当前生产状态](docs/CURRENT-STATE.md)。日期化体检／变更文档保留当时的数量与验证结果；维护前经管理 API 重读，不能用历史快照或初始化模板覆盖最新生产数据。
+
+- 当前登记 30 个节点，12 个启用、18 个停用；12 个启用组、21 个显式成员、130 条规则（128 启用）。停用节点保留凭据，不因文档整理、排序、部署或导入清单核对而自动启用。应用的节点启用状态不等于边缘 VPS 的运行状态。
+- 普通代理流量交给 `🚀 Proxy`，只有它引用 `⚡️ Automatic`。Automatic 为 url-test，成员依次为新加坡、美国、日本；规则不直接指向 Automatic。`🤖 AI` 为 select，成员依次为美国、新加坡、日本、`🧠 AI Nodes`，不引用 Automatic。
+- `📋 All Nodes` 与 `🧠 AI Nodes` 都是独立 select 组，开启 includeAllNodes、没有筛选正则或显式成员；AI Nodes 紧接 AI 显示。两组收纳相同的订阅范围内可用节点，各自保存客户端选择，不能用引用 All Nodes 代替独立的 AI Nodes。
+- 两组按完整节点名称字符串升序输出，保留 Direct／Warp 出口词。现有节点 sortOrder 全为默认 0，IR 按 sortOrder、name 读取；新增／导入节点保持默认值。非零权重会先于名称排序，调整它影响节点声明及其他动态列表，不只是这两个组。Web 节点页仍按站点、协议与出口展示。
+- Streaming 当前承接 Disney、Netflix、TikTok、YouTube、GoogleSearch 及欧洲／韩国／香港／台湾流媒体集合；美国／日本流媒体集合直接交给对应地区组，Emby 交给 Proxy。组显示顺序不决定规则匹配顺序。
+- 规则优先级保持：STUN 与 googlevideo UDP 防护 → Unbreak DIRECT → 启用的 AI 规则 → 业务例外／广告与其余分流 → 唯一 FINAL。FINAL 仍为 `🎯 NoAuto,dns-failed`，NoAuto → Mainland → DIRECT。保留 Google 更新／翻译直连例外；全局 PROTOCOL DOH 与 Dia 关键词规则继续停用。
+- Apple／Global Services／Speedtest／Other 及无节点的香港／台湾／韩国／英国组已删除，不因模板仍存在而恢复。App Store DIRECT、Apple News 美国、Apple Relay AI 例外继续保留。
+
 ### 节点部署管理
 
 - `edge-nodes/README.md` 是节点工作区入口；`edge-nodes/build-delivery-doc.py` 从 Git 忽略的 `edge-nodes/private/fleet.json` 读取清单并离线生成汇总交付页，不在源码里保存真实站点信息。
@@ -47,8 +59,11 @@ bash .claude/skills/deploy/scripts/deploy.sh all
 # 本机离线生成边缘舰队交付页（清单与产物均在 Git 忽略的私有目录）
 python3 edge-nodes/build-delivery-doc.py
 
-# 校验生成的 Clash 配置（最有价值的一条端到端验证）
-curl -s "http://localhost:3000/sub/<token>/clash" > /tmp/c.yaml && mihomo -t -f /tmp/c.yaml
+# 校验实际 Clash 配置；生产验收改用实际 HTTPS 入口，真实 URL 仅在本机使用
+umask 077
+check_dir="$(mktemp -d /private/tmp/proxy-station-check.XXXXXX)"
+curl -fsSL --max-time 45 "http://localhost:3000/sub/<token>/clash" -o "$check_dir/clash.yaml" && \
+  test -s "$check_dir/clash.yaml" && mihomo -t -d "$check_dir" -f "$check_dir/clash.yaml"
 ```
 
 本机开发及当前生产部署使用 Node 22。依赖使用 pnpm 与已提交的 `pnpm-lock.yaml`；不要混用 npm/yarn 或无故更新锁文件。pnpm 在无 TTY 时安装需要 `CI=true`，原生模块（better-sqlite3、esbuild、vue-demi）的构建许可写在 `pnpm-workspace.yaml` 的 `allowBuilds`。
@@ -96,7 +111,7 @@ IR 层承担三件防护，改动时不要绕过：
 
 `includeAllNodes` 与 `filterRegex` 可以共存，生成器里 **filterRegex 分支优先**：
 
-- 有 `filterRegex` → 动态筛选：Surge 保留显式节点／内置成员，全部成员组作为 `include-other-group` 来源，并可同时启用 `include-all-proxies=true`；正则只筛动态来源，不筛显式成员。Clash 用 `include-all-proxies: true` + `filter`；ShadowRocket 用 `policy-regex-filter`。新增同地区节点会自动进组
+- 有 `filterRegex` → 动态筛选：Surge 保留显式节点／内置成员，全部成员组作为 `include-other-group` 来源，并可同时启用 `include-all-proxies=true`；正则只筛动态来源，不筛显式成员。Clash 用 `include-all-proxies: true` + `filter` 并保留 `proxies` 显式成员；ShadowRocket 保留显式成员并用 `policy-regex-filter` 动态收节点。新增同地区节点会自动进组
 - 仅 `includeAllNodes` → Surge 静态展开全部节点名，Clash／ShadowRocket 仍用动态引用
 
 **地区组靠节点名称正则匹配，不看 `region` 字段**。节点命名规范与新增地区的完整步骤见 `docs/ADDING-REGIONS.md`——命名不对就进不了地区组。
@@ -111,7 +126,9 @@ Surge 不支持组级 `url=`；组的 `testUrl` 仅用于 Clash／ShadowRocket
 
 ### ShadowRocket 分两步导入
 
-ShadowRocket 的原生订阅格式只承载节点，因此拆成两个端点：`/shadowrocket`（节点 base64 URI 列表）与 `/shadowrocket-conf`（策略组与规则的 .conf）。**ShadowRocket 没有 Surge 的 `use=` 订阅引用语法**（真机验证过：`use=true` 会被当成解析不了的成员残留），策略组收节点只能靠 `policy-regex-filter` 从 App 内全部节点里筛（「收纳全部节点」输出 `policy-regex-filter=.*`），因此订阅名随意，但用户在 App 里挂的其他订阅的节点也会被筛进来。ShadowRocket 不支持 `DOMAIN-SET`／`AND`／`OR`／`NOT`／`URL-REGEX`／`PROTOCOL`，生成时跳过并回报 `skippedRules`。**ShadowRocket 的 conf 语法没有引号机制**：策略名（含空格／emoji）一律裸写，加引号会被当作名字的一部分，导致规则指向不存在的策略组而整条失效、流量落到默认行为走代理——Surge 生成器可以加引号，ShadowRocket 生成器绝不可以。
+ShadowRocket 的原生订阅格式只承载节点，因此拆成两个端点：`/shadowrocket`（节点 base64 URI 列表）与 `/shadowrocket-conf`（策略组与规则的 .conf）。节点订阅按完整名称字符串升序排列，保留出口词；该序列化器对副本排序，不修改 IR／数据库，跨客户端名称排序由上述节点权重约定保证。**ShadowRocket 没有 Surge 的 `use=` 订阅引用语法**（真机验证过：`use=true` 会被当成解析不了的成员残留），策略组动态收节点靠 `policy-regex-filter` 从 App 内全部节点里筛（「收纳全部节点」输出 `policy-regex-filter=.*`），显式成员也要保留。因此订阅名随意，但用户在 App 里挂的其他订阅的节点也会被筛进来；这些节点及 App 自定义排序不由本服务控制。本生成器当前保守跳过 `DOMAIN-SET`／`AND`／`OR`／`NOT`／`URL-REGEX`／`PROTOCOL`，并回报 `skippedRules`；这不是客户端不支持这些类型的断言。官方更新记录已确认存在逻辑规则与 QUIC 匹配，具体配置语法仍须以 App 内帮助和真机编译验证，详见 `docs/MOBILE-CLIENT-AUDIT-2026-10-04.md`。**ShadowRocket 的 conf 策略名不可用 Surge 引号机制**：策略名（含空格／emoji）一律裸写，加引号会被当作名字的一部分，导致规则指向不存在的策略组而整条失效、流量落到默认行为走代理——Surge 生成器可以加引号，ShadowRocket 生成器绝不可以。
+
+Clash 节点必须明确下发 UDP 能力：VMess／Trojan／纯 TCP SS／HY2 输出 `udp: true`，SS WS 插件仅转发 TCP，输出 false，不能假设 nginx 的同端口提供 SS UDP。VMess cipher 按 mihomo 命名映射、未知 cipher 明确排除；SS plugin 的 TLS 参数在 `plugin-opts` 内。RULE-SET 保留 no-resolve；逻辑规则逐个转换子类型，仅把 PROTOCOL TCP／UDP 映射 NETWORK，任一子条件无法表达时整条跳过。两端 url-test 保留零 tolerance，fallback 不输出 tolerance。完整体检需分别核对客户端能力与生成器范围，原生解析成功不等于设备连接或隐私验收。
 
 ### 鉴权与订阅
 
@@ -138,7 +155,9 @@ schema 变更同时更新 `shared/src/schemas.ts`／DTO（涉及对外字段时
 
 ## 初始化与已有数据
 
-`server/src/db/seed.ts` 只在策略组为空时从 `server/assets/surge-template.conf` 初始化策略组、规则和 Surge 段落。修改模板不会更新已有数据库；既有订阅仍以数据库为准。生产数据变更使用 `update-db` 技能，经管理 API 修改并先做 SQLite 在线备份，避免绕过校验和级联更新。组成员与排序 API 有全量替换语义，修改前先读取完整当前值。
+`server/src/db/seed.ts` 只在策略组为空时从 `server/assets/surge-template.conf` 初始化策略组、规则和 Surge 段落。修改模板不会更新已有数据库；既有订阅仍以数据库为准。生产数据变更使用 `update-db` 技能，经管理 API 修改并先做 SQLite 在线备份，确认备份 root 属主、600 权限，避免绕过校验和级联更新。
+
+组的 members 是整体替换；排序请求始终先读完整列表并提交全量、无重复 ids。规则 reorder API 强制校验完整性与末尾 FINAL；当前组 reorder API 只逐条写顺序，调用方须自行核对完整性。组 PUT 不更新 sortOrder，显示排序使用独立 `/api/groups/reorder`。节点 PUT 使用私有文件提交完整原字段，排序调整后重读确认除 sortOrder／updatedAt 外没有变化。
 
 `server/src/env.ts` 直接读 `process.env`，没有 dotenv 加载；仅复制 `.env.example` 成 `.env` 并不会让 `pnpm dev` 自动读取它。变量须由启动环境提供（Docker Compose 与 systemd 有各自注入方式）。相对 `DATA_DIR` 始终基于 `server/` 解析。
 
@@ -148,6 +167,8 @@ schema 变更同时更新 `shared/src/schemas.ts`／DTO（涉及对外字段时
 
 手写 Host 项优先；生成的域名 DNS 映射按连接规则顺序保留 AI 之前的非 AI 域名／规则集例外，不把 Host 当成能表达进程、协议或 IP 条件的路由系统。宽泛 AI 域名规则仍须审阅覆盖范围。
 
+Net.Coffee 的 Claude 页通过随机 `*.d.ip.net.coffee` 探测递归 DNS 出口，不直接查询 Claude 域名；使用 `DOMAIN-SUFFIX,ip.net.coffee,🤖 AI` 同时覆盖页面和探测子域。Surge 派生根域／通配 Host 到 Cloudflare DoH，并随 AI 出口。本机 Chrome＋Surge 已复测为美国 Cloudflare「未检测到泄露」，仅代表该探测路径的实际结果，不能推广为所有客户端／域名／远端解析器已验收，见 `docs/NET-COFFEE-DNS-2026-10-04.md`。
+
 规则变更先读 `docs/SURGE-CHANGES.md`。API 必须保住一条启用且末尾的 FINAL；禁止停用、删除、改类型或创建重复 FINAL，排序必须提交完整且无重复的 ids。IR 对遗留坏数据防御性补齐 FINAL，其失效策略降级 DIRECT。重置规则在事务内保留自定义规则，不重复插入原主键，也不能用 reset 代替定向调整生产规则。
 
 规则按首条匹配执行（另留意 pre-matching）。业务例外须在覆盖它的广告／通用规则集之前，特定 UDP 拦截须在对应服务域名规则之前。靠前的 IP 规则集是否加 `no-resolve` 必须按意图决定：它能避免主动解析，但会改变未解析域名的 IP 拦截覆盖。普通规则值与策略引用用 `surge-format.ts` 编码，逻辑表达式保留结构；不要手拼含逗号的正则或含换行的字段。
@@ -167,6 +188,10 @@ schema 变更同时更新 `shared/src/schemas.ts`／DTO（涉及对外字段时
 
 涉及节点、组、规则、DNS 或 Surge 段落时，在上述检查之外对实际订阅运行 `scripts/check-surge.py`；涉及规则集或顺序用 `--fetch-rulesets`，审阅域名遮蔽提示。脚本调用官方 Surge CLI，不更换活动配置；输出 OK 不表示测速、业务连接或设备隐私已验收。敏感配置用权限 600 的临时文件，不进入仓库或对话。生产写入先在线备份，再 API 更新、重读、HTTPS 拉订阅与 CLI 验证；必要时同时用 mihomo 校验受影响的 Clash 产物。
 
+取订阅后先核对下载成功、非空及预期结构，再交给原生解析器。mihomo 在目标配置不存在时可能创建默认配置并报告成功，不能用这个结果验收订阅；所有检查遇到失败即停止，避免前一步失败而最后一条命令成功掩盖错误。
+
+区分数据库、实际 HTTPS 产物、客户端活动配置与设备网络结果。用户授权的同机复测需刷新既有托管配置时，先核对托管 URL、备份并读取最新组选择，用 `surge-cli managed-profile update` 后检查 effective 配置与实际选项。组改名会改变客户端保存选择的身份；必要时仅将原选定节点及父组路径迁移到新名称，保留 All Nodes／AI Nodes 的独立选择，不擅自切换出口或活动配置。客户端模块可覆盖生成的组类型与参数，不能把本机模块效果写回生产数据库。
+
 `db/index.ts` 在模块加载时就执行 `export const db = createDb()`，包括只导入 `createDb` 的情形；临时数据库测试／启动验证应在加载模块前设置绝对路径的临时 `DATA_DIR`，不要拿本地真实 `server/data/` 做试验。现有生成器单测使用内存中的 IR；运行服务还会执行初始化。
 
 改生成器时检查节点过滤、组成员引用、规则顺序和 FINAL 兜底；Clash 可用 mihomo 校验，Surge／ShadowRocket 的客户端语法与实际连接仍需真机验收。`excluded`／`skippedRules` 是生成器返回字段，订阅 HTTP 响应只返回配置正文。