FlowPilot/docs/ip-proxy-module.md

IP Proxy 模块说明（Ultra1 集成版）

1. 模块定位

IP Proxy 是扩展内的网络出口接管模块，用于把自动化流程的页面访问链路切到指定代理节点，并在侧边栏内可视化展示当前代理与出口状态。

本模块目标是解决三件事：

1. 在扩展内统一配置和切换代理，而不是依赖浏览器外部全局代理。
2. 对“代理已配置但未真正接管/未真正出站”的情况进行显式诊断。
3. 在自动化流程中可控地切换出口，降低单节点波动影响。

2. 代码结构

2.1 Background（核心逻辑）

• background/ip-proxy-core.js
  • 代理池解析与运行态管理
  • 应用/清除代理配置
  • 出口探测与状态诊断
  • SYNC/NEXT/CHANGE/PROBE 主流程
• background/ip-proxy-provider-711proxy.js
  • Provider 级别参数处理（当前重点是 711 账号串 token 规则）
• background/message-router.js
  • 暴露消息接口：
    • REFRESH_IP_PROXY_POOL
    • SWITCH_IP_PROXY
    • CHANGE_IP_PROXY_EXIT
    • PROBE_IP_PROXY_EXIT
• background.js
  • 持久化字段定义与默认值
  • 启动恢复时的代理状态接管
  • 自动运行成功后的代理切换钩子

2.2 Sidepanel（界面与交互）

• sidepanel/ip-proxy-panel.js
  • 代理 UI 状态渲染
  • 按钮行为（同步/下一条/Change/检测出口）
  • 运行态文案和诊断详情展示
  • 711 账号参数双向同步（session/sessTime/region）
• sidepanel/ip-proxy-provider-711proxy.js
  • Provider 级输入辅助（地区推断）
• sidepanel/sidepanel.html
  • 代理区块 UI
• sidepanel/sidepanel.css
  • 代理区块样式
• sidepanel/sidepanel.js
  • 与设置保存流整合、事件绑定

3. 当前功能范围（本 PR）

3.1 基础能力

1. 启用/禁用代理接管（PAC + 认证回填）。
2. 固定账号模式（Host/Port/Username/Password/Region）。
3. 出口探测与状态卡（当前代理、当前出口、诊断详情）。
4. 四个动作按钮：
   • 同步：应用当前配置并刷新运行态
   • 下一条：切到下一个可用节点
   • Change：保持 session 的前提下重绑并换出口（711）
   • 检测出口：只做出口复测，不改节点
5. 检查IP：打开 https://ipinfo.io/what-is-my-ip

3.2 711 账号串参数联动

支持从用户名中识别并回填：

• session-xxxx
• sessTime-xx（兼容 life-xx）
• region-XX

支持从表单回写到用户名：

• 修改会话值 -> 更新 session-*
• 修改时长 -> 更新 sessTime-*
• 修改地区 -> 更新 region-*

3.3 同步后的自动复测

为避免“同步后还要手动点检测出口”：

• 同步/下一条/Change 执行完成后，自动追加一次静默 检测出口。

4. 当前发布策略（为了稳定）

本 PR 是“先可用，再扩展”的第一阶段：

1. 服务商主路径按 711 优先。
2. API 模式在 UI 中保留但禁用（暂未开放）。
3. 账号列表模式目前关闭（防止多条目与鉴权缓存复用带来的不稳定）。

对应开关位于：

• sidepanel/sidepanel.js：IP_PROXY_API_MODE_ENABLED = false
• sidepanel/sidepanel.js：IP_PROXY_ACCOUNT_LIST_ENABLED = false
• background.js：IP_PROXY_ACCOUNT_LIST_ENABLED = false

5. 使用方式（操作步骤）

1. 打开侧边栏 IP代理 开关。
2. 选择账号模式，填写：
   • Host
   • Port
   • Username
   • Password
   • Region（可选）
3. 点击 同步。
4. 查看状态卡：
   • 当前代理
   • 当前出口
   • 是否有校验提示
5. 需要换出口时：
   • 711 + session 场景优先用 Change
   • 或使用 下一条
6. 需要手动复核时点击 检测出口 或 检查IP。

6. 已知限制

1. 某些代理链路不会返回标准 407，扩展无法触发认证回填，这类链路可能不稳定。
2. 地区“期望值”和“实际出口”不一致时，模块会保留接管并提示校验告警（不直接判定全失败）。
3. 不同探测源（页面探测/后台兜底）在网络波动时可能短时出现差异，状态卡会显示来源与诊断。

7. 回归建议

建议至少覆盖以下场景：

1. 固定账号：启用 -> 同步 -> 出口检测成功。
2. 固定账号：session/sessTime/region 双向同步正确。
3. 固定账号：同步/下一条/Change 后无需手动点检测即可刷新出口状态。
4. 非标准链路失败时，诊断信息可读且不误报“已接管成功”。