引入显式 IR 契约 + Builders 迁移到 IR maps（Clash/Surge/Singbox/Xray）+ 输入模式前端升级（链接/文本/标准化节点）+ Xray JSON 输出 + AnyTLS/规范化输入/订阅解码修复

[w31r4]

背景 / 动机

当前解析与各类 Builder（Clash/Surge/Sing-box/Xray）之间耦合较强，协议扩展会重复写“转换逻辑”。本 PR 以 显式 IR（Intermediate Representation） 作为统一契约，逐步把各 Builder 迁移为 直接消费 IR → src/ir/maps/*，从而使转化更规范、更易扩展与测试。

同时，为了匹配新的输入能力（尤其是 {version,nodes} 的标准化输入），前端输入区域升级为三种输入模式：链接 / 文本 / 标准化节点，减少用户误用与解析歧义。

主要变更

1) 引入显式 IR 契约层

• 新增 IR contract/normalize/legacy/caps：
  • src/ir/contract.js：IR 版本与基础工具
  • src/ir/normalize.js：legacy proxy → IR（容错为主），并补齐关键字段（如 tls.alpn、tcp_fast_open）
  • src/ir/legacy.js：IR → legacy proxy（用于平滑过渡/兼容未迁移组件）
  • src/ir/caps.js：按目标客户端能力降级（reality/utls 等）
  • src/ir/index.js：统一导出
• src/builders/BaseConfigBuilder.js 支持 builder “直通 IR”：
  • builder 可通过 usesIR = true 直接获取 IR 节点
  • 同时保持方案 A 的兼容路径（仍可 IR ↔ legacy）

2) Builders 迁移为 IR → maps/*

新增并使用 map 模块，减少 builder 内部协议分支与重复逻辑：

• Xray：
  • src/ir/maps/xray.js
  • src/builders/XrayConfigBuilder.js
• Surge：
  • src/ir/maps/surge.js
  • src/builders/SurgeConfigBuilder.js
• Clash：
  • src/ir/maps/clash.js
  • src/builders/ClashConfigBuilder.js
• Sing-box：
  • src/ir/maps/singbox.js
  • src/builders/SingboxConfigBuilder.js

统一流程：

1. normalizeLegacyProxyToIR()（若输入不是 IR）
2. downgradeByCaps(ir, target)
3. mapIRTo<target>(ir)

3) 前端输入框升级：三模式（链接 / 文本 / 标准化节点）

• UI：src/components/Form.jsx
  • 增加输入模式 tabs
  • 三个输入框分别用于：链接、配置/多行文本、标准化 JSON
• 逻辑：src/components/formLogic.js
  • inputMode + inputLinks/inputText/inputNormalized
  • 旧的单输入框 inputTextarea 自动迁移到新结构（并猜测模式）
  • 提交时仅使用当前模式的内容作为 config
  • 仅在“链接模式”对单行订阅 URL 做自动解析回填（减少误触）
• 文案：src/i18n/index.js
  • 新增 input mode 相关 placeholder/hint（zh/en/fa/ru）

4) 新增 Xray Config JSON 输出（API + UI 链接）

• 新增 /xray-config 端点输出 Xray JSON
• 增加短链支持（例如 /g/:code）与 resolve/redirect 兼容
• UI 生成链接时增加 xrayConfig 字段

5) 解析增强：AnyTLS + 标准化输入 + 订阅 Base64 误解码修复

• AnyTLS 协议解析：
  • src/parsers/protocols/anytlsParser.js
  • src/parsers/ProxyParser.js 注册
• 标准化输入 { version, nodes }（严格校验）：
  • src/parsers/subscription/subscriptionContentParser.js
• 修复订阅内容 Base64 误解码（避免把明文 YAML/JSON 损坏）：
  • src/parsers/subscription/httpSubscriptionFetcher.js：仅对“看起来像 Base64”内容才解码

行为变化与兼容性说明

• IR 引入遵循“方案 A：最小破坏”：
  • 未迁移的路径仍可通过 IR→legacy 维持旧行为
  • 已迁移 builder 的输出意图保持与旧逻辑一致（但结构更清晰、可维护）
• Sing-box 输出维持原约束：
  • 不输出 Clash-only 的 udp
  • alpn 只放 tls.alpn
  • packet_encoding 仍不输出（版本差异较大）
• 新增输入模式属于 UI/交互增强：后端参数仍是 config=<string>，只是由前端选择不同来源填入。

测试

• 已通过：pnpm exec vitest run（全套测试绿色）
• 新增/更新覆盖：
  • test/ir-normalize.test.js
  • test/normalized-input.test.js
  • test/anytls-link-parsing.test.js
  • test/worker.test.js（覆盖 /xray-config）
  • test/proxy-providers.test.js（fetch stub 调整）

变更范围概览（便于 Review）

• IR：src/ir/*、src/ir/maps/*
• Builders：src/builders/{Base,Clash,Surge,Singbox,Xray}ConfigBuilder.js
• 前端：src/components/Form.jsx、src/components/formLogic.js
• API/UI 路由：src/app/createApp.jsx
• 解析：src/parsers/*、src/parsers/subscription/*
• 国际化：src/i18n/index.js
• Tests：test/*

Reviewer 建议阅读顺序

1. src/ir/contract.js / src/ir/normalize.js（IR 字段与容错策略）
2. src/ir/maps/*（目标格式映射）
3. BaseConfigBuilder 的 IR 直通机制（是否影响旧链路）
4. httpSubscriptionFetcher 的 Base64 gating（避免误解码）
5. 前端输入模式（Form + logic）是否符合预期交互

设计说明：IR / CAPS（能力降级）

IR（Intermediate Representation）

IR 是一个统一的“节点契约层”，把不同来源（分享链接、Clash YAML、Sing-box JSON、Surge 等）解析出来的节点，规范到同一套字段结构中（如 kind/host/port/tags/auth/tls/transport/...）。
这样做的收益：

• 协议扩展更容易：新增协议时主要改“解析 → IR”与“IR → 各目标格式 map”，不用在每个 builder 里重复写转换分支。
• 转换逻辑更集中可测：map 变成纯函数（src/ir/maps/*），更易写单测、减少回归风险。
• 输入方式更自由：同一 IR 可以来自链接、配置文本、或标准化 {version,nodes} JSON。

CAPS（能力降级）

不同目标客户端能力不同（例如 Reality/uTLS 支持差异）。CAPS 用来描述“目标支持哪些能力”，downgradeByCaps(ir, target) 会对 IR 做不修改原对象的裁剪/降级，以避免输出到不支持的平台时出现无效字段。
扩展方式：

• 新增 target：在 src/ir/caps.js 增加 CAPS.<target>，并在 builder 中调用 downgradeByCaps(ir, '<target>')
• 新增能力开关：给 CAPS.<target> 增加字段（如将来 packetEncoding, http2），并在 downgradeByCaps 里实现相应裁剪策略
• 新增协议：扩展 normalizeLegacyProxyToIR() 与 mapIRTo<target>()，caps 只负责“同协议下的能力差异处理”

新增接口：/xray-config 与短链 /g/:code

• /xray-config：输出 Xray JSON 格式配置（便于直接导入/对接），与现有 /xray（Base64/链接型输出）互补。
• /g/:code：为 /xray-config?... 提供对应的短链入口（g = xray-config），与已有短链体系一致，方便分享/二维码/避免 URL 过长。

输入模式说明（前端）

本 PR 将输入分为三种模式，仅把“当前选中模式的内容”作为 config 参数提交给后端：

1. 链接（Links）
   • 适用：订阅链接、分享链接、短链（如 /b/xxx）
   • 特点：支持单行订阅 URL 自动解析并回填选项（规则、UA、开关等）
2. 文本（Text）
   • 适用：整段配置或多行混合文本（Clash YAML / Sing-box JSON / Surge 配置 / 多行协议链接）
   • 特点：更适合“直接粘贴一大段内容”，由解析器自动识别格式
3. 标准化节点（Normalized）
   • 适用：{ "version": "...", "nodes": [...] } 的规范化 JSON
   • 特点：结构稳定、利于长期维护与协议扩展；适合高级用户/程序化生成输入

CI / Tests

• 本地已通过：pnpm exec vitest run（18 files / 106 tests）。

[vercel]

@w31r4 is attempting to deploy a commit to the 7sageer's projects Team on Vercel.

A member of the Team first needs to authorize it.

[7Sageer]

感谢这个 PR！架构方向是对的——IR 中间层解耦解析和输出，以后扩展协议会轻松很多。

改动量比较大（28files, +1.6k lines），我会仔细 review 一下细节，可能会有一些修改建议或者讨论点。几个初步印象：

• IR 契约层设计清晰，normalize → downgradeByCaps → map 的流程很规范
• 向后兼容考虑得不错，usesIR flag 让迁移可以渐进
• 测试覆盖完整 👍

稍后会给出具体的 review comments，有些地方可能需要讨论一下再决定怎么处理。

[w31r4]

https://github.com/w31r4/sublink-worker/tree/refactor/parsers 在这个分支中我完全重构了解析流程, 但是由于改动太大一直没有推到主线上来, 先自己试用, 目前没有发现太大问题, 但是后来发现主线更新的频率有点高所以又在最新主线基础上引入了 IR 层解耦, 顺便补充了一下 Anytls 的解析和自定义节点功能, 并为拆分输入框做了一些准备, 接下来的目标是:

也就是把 links 和 Structured config 以及规划中的 Guided input 拆分开来
https://sublink-worker.zflink.site/
这是我的之前分支部署的 sublink-worker, 可以用于参考效果

[7Sageer]

看了demo，三模式输入的设计看起来很有意思！

简单和AI Review了一下发现几个需要注意的点：

1. ClashConfigBuilder.convertProxy() 缺少 downgradeByCaps() 调用，reality/utls 字段可能泄漏到 Clash 配置
2. mapIRToClashProxy() 没处理 http/https 类型，这类节点会被丢弃
3. XrayConfigBuilder 硬编码了 CN 直连 —— 这是预期行为吗？

改动量确实比较大😂，我需要再花点时间评估一下和现有架构的兼容性。