# Plus 模式 SUB2API Session 接入策略开发方案

## 1. 文档定位

本文档只做完整开发设计，不修改功能代码。

本文档中的“开发阶段”仅表示**实施顺序和每阶段自检顺序**，不是产品分期，不表示“先做一半、后面再补”。

本方案的目标是把 `OpenAI flow + Plus 模式 + SUB2API` 的账号接入方式，从当前固定的 OAuth 尾链，扩展为一个正式的“账号接入策略”能力，并且一次性把相关联的 UI、步骤、后台状态、自动运行、测试、自检边界全部设计完整。

## 2. 分析基线

### 2.1 当前分析基线

- `codex注册扩展` 当前工作树分支名为 `feature/kiro-desktop-auth-rebuild`，但它与本地 `dev` 指向同一提交 `4aa459e`，本地 `dev` 比 `origin/dev` 还新 8 个提交，因此本次分析不需要先回退或切换到远端 `origin/dev`
- `sub2api` 已在本次分析前同步到远端最新 `main`，当前基线为 `1d78dde8`
- `GPTSession2CPAandSub2API` 已本地拉取，用于分析“session 导入类逻辑”的取精华方向，而不是复制其代码

### 2.2 已完整阅读的关联代码范围

主仓库 `codex注册扩展` 已重点阅读：

- `data/step-definitions.js`
- `core/flow-kernel/flow-capabilities.js`
- `core/flow-kernel/flow-registry.js`
- `core/flow-kernel/settings-schema.js`
- `sidepanel/sidepanel.html`
- `sidepanel/sidepanel.js`
- `background.js`
- `core/flow-kernel/runtime-state.js`
- `background/message-router.js`
- `background/panel-bridge.js`
- `background/sub2api-api.js`
- `flows/openai/background/steps/platform-verify.js`
- `flows/openai/background/steps/create-plus-checkout.js`
- `flows/openai/background/steps/fill-plus-checkout.js`
- `flows/openai/background/steps/plus-return-confirm.js`
- `flows/openai/content/plus-checkout.js`
- `tests/step-definitions-module.test.js`
- `tests/sidepanel-plus-payment-method.test.js`
- `tests/flow-capabilities-module.test.js`
- `tests/background-settings-schema-persistence.test.js`
- `tests/background-account-history-settings.test.js`
- `tests/background-message-router-module.test.js`
- `tests/background-message-router-plus-final-step.test.js`
- `tests/background-auth-chain-guard.test.js`
- `tests/auto-run-step6-restart.test.js`

接入端 `sub2api` 已重点阅读：

- `backend/internal/server/routes/admin.go`
- `backend/internal/handler/admin/account_codex_import.go`
- `frontend/src/api/admin/accounts.ts`

参考项目 `GPTSession2CPAandSub2API` 已重点阅读：

- `README.md`

## 3. 需求校准与硬边界

本方案按以下真实需求设计，不能偏离：

1. 这不是新增一个独立 flow，而是 **OpenAI flow 的 Plus 模式下，替换账号接入尾链策略**
2. Plus 流程不是固定步骤号流程，必须按**动态步骤定义**设计，不能写死“第几步一定是什么”
3. Plus 模式不能走手机号注册，本方案只围绕 **Plus + 邮箱注册 + sub2api** 设计，不再扩展任何手机号分支
4. 新功能名按你的要求设计成 **Plus 模式下的“账号接入策略”**
5. 当前只允许 `sub2api` 真正切换到 session 导入策略；`cpa / codex2api` 在 Plus 下仍固定走 OAuth，UI 上直接禁用策略切换
6. 这里说的“使用拉下来的项目逻辑”，是**借用其 session 导入思路和行为结论**，不是把外部项目代码复制进来
7. 必须走 `sub2api` 自己的账号导入逻辑，即调用其原生 `import/codex-session`，而不是扩展自己再手写一套 token 转换器
8. 方案必须把和本功能无关、但逻辑有关联的地方一并覆盖，例如：
   - 动态步骤切换
   - 设置持久化与导入导出
   - 自动运行重开
   - 最终成功节点判定
   - 固定 OAuth 文案
   - runtime 清理
   - 测试基线

## 4. 当前真实实现现状

### 4.1 Plus 步骤是动态生成的，不是固定步号

`data/step-definitions.js` 当前会根据以下条件动态生成 OpenAI 步骤集合：

- `plusModeEnabled`
- `plusPaymentMethod`
- `signupMethod`
- `phoneSignupReloginAfterBindEmailEnabled`

当前 Plus 邮箱链路的尾部不是单个“平台验证”，而是一段完整 OAuth 尾链：

- `oauth-login`
- `fetch-login-code`
- `post-login-phone-verification`
- `confirm-oauth`
- `platform-verify`

不同 Plus 支付方式的接入锚点也不同：

- PayPal：接在 `plus-checkout-return` 后
- GoPay：接在 `gopay-subscription-confirm` 后
- GPC：接在 `plus-checkout-billing` 后

因此本次改造不能说“替换第 10 步”，必须说：

- **替换 Plus 动态步骤集合中的 OAuth 尾链插槽**

### 4.2 Plus 模式当前不允许手机号注册

现有能力注册表和侧栏逻辑已经明确限制：

- Plus 开启时，手机号注册不可选
- 如果当前选中手机号，再开 Plus，会被切回邮箱注册

所以本方案不再设计任何：

- Plus 手机号注册
- Plus 手机绑定后再改邮箱
- Plus 手机验证码尾链兼容

### 4.3 当前 SUB2API 主链路是 OAuth，不是 session 导入

当前 SUB2API Plus 尾链的真实做法是：

1. 通过 `background/panel-bridge.js` 请求 `background/sub2api-api.js` 生成 OAuth URL
2. 保存 `oauthUrl / sub2apiSessionId / sub2apiOAuthState`
3. 页面完成 OAuth 回调，拿到 `localhostUrl`
4. `flows/openai/background/steps/platform-verify.js` 调 `submitOpenAiCallback`
5. SUB2API 用 `exchange-code` 交换 OAuth code，再创建账号

这条链路是“完整 OAuth 账号创建”，不是导入现有 ChatGPT Web session。

### 4.4 扩展本身已经具备读取 ChatGPT session 的能力

当前项目并不是没有 session 能力，已有代码已经能在 ChatGPT 页面读取：

- `/api/auth/session`
- `session`
- `accessToken`

现成能力位置：

- `flows/openai/content/plus-checkout.js`
- `flows/openai/background/steps/create-plus-checkout.js`

这意味着新功能不需要再发明“如何拿 session”，只需要把这份能力接到 Plus 尾链上。

### 4.5 SUB2API 已原生支持 codex session 导入

`sub2api` 当前已原生提供：

- 路由：`POST /api/v1/admin/accounts/import/codex-session`
- 前端 API：`importCodexSession`

其导入逻辑当前已支持：

- 直接导入 raw `accessToken`
- 导入完整 session JSON
- 导入 JSON 数组
- 导入多行混合内容
- 自动从 JWT claims 补 `email / account_id / plan_type`
- 忽略 `sessionToken`
- 没有 `refresh_token` 时，按 access token 过期时间处理，并开启过期自动暂停
- 默认 `update_existing = true`，同身份账号会走“更新已有账号”语义，而不是强制重复创建

这说明本次扩展应该做的是：

- 读取当前 ChatGPT Web session
- 直接调用 `sub2api` 原生导入接口

而不是：

- 在扩展里复制外部项目的 JSON 转换代码
- 在扩展里伪造一套 OAuth 账号结构

### 4.6 外部参考项目给出的结论必须正视

`GPTSession2CPAandSub2API` 的核心结论很明确：

- ChatGPT Web session 通常没有真实 `refresh_token`
- 这类导入数据主要依赖 `access_token`
- `access_token` 过期后不能自动刷新

所以本方案必须明确接受一个事实：

- **Plus 下走 session 导入策略时，导入到 SUB2API 的将是“当前 Web session 账号”，不是“可长期自动刷新的 OAuth 完整账号”**

这不是缺陷描述，而是该策略的真实工作方式，必须在设计里被明确建模，而不是模糊带过。

## 5. 最终设计

## 5.1 功能命名与策略枚举

新功能统一命名为：

- `Plus 模式 -> 账号接入策略`

新增设置字段建议命名为：

- `plusAccountAccessStrategy`

枚举值建议固定为：

- `oauth`
- `sub2api_codex_session`

命名原则：

- `oauth` 保持通用
- `sub2api_codex_session` 明确说明这是 **SUB2API + Codex Session 导入**
- 不用泛化的 `session` 或 `import`，避免以后 CPA/Codex2API 也有 session 方案时语义冲突

默认值：

- `oauth`

## 5.2 请求值与生效值分离

这里不能简单把 `plusAccountAccessStrategy` 当成“永远立即生效值”，而应沿用现有 `signupMethod` 的思路，区分：

- **用户请求值**：持久化保存在设置中的选择
- **当前生效值**：根据 flow、target、plus 开关、注册方式实时归一化后的结果

最终规则：

1. 持久化字段只保存用户偏好值
2. 当 `activeFlowId !== openai` 时，生效值强制为 `oauth`
3. 当 `plusModeEnabled !== true` 时，生效值强制为 `oauth`
4. 当 `panelMode !== sub2api` 时，生效值强制为 `oauth`
5. 当 `signupMethod !== email` 时，生效值强制为 `oauth`
6. 只有同时满足：
   - `openai`
   - `plusModeEnabled = true`
   - `panelMode = sub2api`
   - `signupMethod = email`
   时，才允许 `sub2api_codex_session` 真正生效

这样设计的好处是：

- 切到 `cpa / codex2api` 时，不会把用户原来的 sub2api strategy 偏好永久覆盖掉
- 切回 `sub2api` 时，可以恢复原来的选择
- 运行时又不会真的拿着 session strategy 去跑不支持的目标

## 5.3 侧栏 UI 设计

### 5.3.1 位置

新 UI 放在 Plus 设置组内，紧跟在：

- `Plus 模式`
- `Plus 支付`

之后。

新增行建议：

- `row-plus-account-access-strategy`
- `select-plus-account-access-strategy`
- `plus-account-access-strategy-caption`

`core/flow-kernel/flow-registry.js` 的 `openai-plus` 设置组应扩展为同时包含：

- `row-plus-mode`
- `row-plus-payment-method`
- `row-plus-account-access-strategy`

### 5.3.2 展示与禁用规则

展示规则：

1. 只有 `supportsPlusMode = true` 时显示整组 Plus 控件
2. `plusModeEnabled = false` 时隐藏“支付方式”和“账号接入策略”两行
3. `plusModeEnabled = true` 且 `panelMode = sub2api` 时，策略选择器启用
4. `plusModeEnabled = true` 且 `panelMode = cpa / codex2api` 时，策略选择器显示但禁用，视觉值固定显示 `oauth`

文案建议：

- 标签：`账号接入策略`
- 选项 1：`OAuth`
- 选项 2：`导入当前 ChatGPT 会话到 SUB2API`

禁用态说明建议：

- `当前来源仅支持 OAuth`

`sub2api` 可用态说明建议：

- `复用当前 Plus 已登录会话，直接导入到 SUB2API，不再走 OAuth 回调`

### 5.3.3 不允许继续保留的 UI 文案问题

当前代码里有多处 Plus 相关文案写死了“第 10 步 OAuth 登录”或“继续 OAuth 登录”，这些在新策略下都会变错。

本次必须统一改为：

- 通过当前动态尾链的**下一节点标题**
- 或当前**账号接入策略标签**

生成文案，不能继续写死：

- `第 10 步`
- `OAuth 登录`

尤其要覆盖：

- Plus 手动确认弹窗
- GoPay/GPC 支付完成后的 toast
- Plus 模式切换日志

## 5.4 步骤与节点设计

### 5.4.1 不新增独立 flow，只替换 Plus 尾链

本方案不创建新 flow，不额外创建“Plus-Session flow”。

最终做法是：

- 在 `data/step-definitions.js` 中，为 Plus 动态步骤集合增加 `plusAccountAccessStrategy` 维度
- 当策略为 `oauth` 时，保留现有 OAuth 尾链
- 当策略为 `sub2api_codex_session` 时，用新的 session 导入尾节点替换整段 OAuth 尾链

### 5.4.2 新尾节点设计

建议新增单节点：

- `sub2api-session-import`

标题建议：

- `导入当前 ChatGPT 会话到 SUB2API`

这里刻意设计成**单节点**，而不是再拆成“读取 session”“上传 session”两个节点，原因是：

1. 当前 session 获取能力已经是内聚能力，不值得再拆成一个对外步骤
2. 该尾链不再需要 OAuth 多步状态机
3. 节点越多，自动运行重试、成功判定、模式切换、node status 重建越复杂
4. 单节点更符合“支付完成后直接接入账号”的实际语义

### 5.4.3 替换锚点

Session 导入策略生效时，替换锚点如下：

- PayPal：`plus-checkout-return` 后接 `sub2api-session-import`
- GoPay：`gopay-subscription-confirm` 后接 `sub2api-session-import`
- GPC：`plus-checkout-billing` 后接 `sub2api-session-import`

因此这次不是“替换 platform-verify”，而是：

- **按支付链路不同，替换整段 OAuth 尾链接入口**

### 5.4.4 Plus 下不再保留任何手机号 session 分支

即使代码层面未来仍存在 phone 相关动态定义，这次策略分支也必须硬性限制为：

- 只支持 `signupMethod = email`

如果后续状态异常导致 `plusModeEnabled = true` 且 `signupMethod = phone` 同时出现，也必须在步骤解析时回退到：

- `oauth`

不能让 session strategy 意外落到 phone 分支。

## 5.5 新节点执行逻辑

建议新增后台执行器文件：

- `flows/openai/background/steps/sub2api-session-import.js`

执行器职责：

1. 定位当前 Plus 会话页对应 tab
2. 确认当前 tab 已回到 ChatGPT / OpenAI 域名页面，且可访问 `/api/auth/session`
3. 通过现有 `flows/openai/content/plus-checkout.js` 能力读取：
   - `session`
   - `accessToken`
4. 用现有 `background/sub2api-api.js` 登录 SUB2API
5. 解析当前配置的：
   - 分组
   - 默认代理
   - 优先级
6. 调用 SUB2API 的 `import/codex-session`
7. 解析返回的 created/updated 结果
8. 用 `completeNodeFromBackground('sub2api-session-import', payload)` 收尾

### 5.5.1 Tab 选择原则

该节点不应新开 tab，而应复用当前 Plus 付款结束后已经存在的 tab。

候选顺序建议：

1. `plusCheckoutTabId`
2. `plus-return-confirm` 已解析到的返回 tab
3. 当前 `plus-checkout` source 绑定 tab

如果拿到的页面不在：

- `chatgpt.com`
- `chat.openai.com`
- `openai.com`

则直接失败，不进入导入。

### 5.5.2 Session 组装原则

扩展不要自己做外部项目那种“多平台 JSON 转换器”。

扩展只做最小组装：

1. 优先传完整 `session` JSON
2. 若 `session.accessToken` 为空，但独立读到了 `accessToken`，则把 `accessToken` 补回 session payload 再提交
3. 不伪造 `refresh_token`
4. 不把 `sessionToken` 当作 `refresh_token`
5. 不生成占位 `refresh_token`
6. 不构造伪 OAuth 交换结果

### 5.5.3 SUB2API 请求体设计

建议调用 `import/codex-session` 时传：

- `content`: 完整 session JSON 字符串
- `group_ids`: 由现有 group name 配置解析出的 group id 数组
- `proxy_id`: 由现有默认代理解析出的 proxy id
- `priority`: 复用当前 `sub2apiAccountPriority`
- `auto_pause_on_expired`: `true`

可以不新增任何新配置字段。

关于导入语义，本方案明确采用：

- **沿用 sub2api 原生导入逻辑**

也就是：

- 不强制改成“永远创建新账号”
- 接受 `update_existing` 默认值为 `true`

这意味着：

- 同身份账号重复跑流程时，SUB2API 更可能更新已有账号，而不是无限重复创建

这属于该策略的既定行为，不再在扩展里另造一套“重复创建模式”。

### 5.5.4 成功判定

单条 session 导入的成功判定建议统一为：

1. HTTP 成功
2. `failed = 0`
3. `created > 0` 或 `updated > 0`

日志层面建议区分：

- `created`：新建成功
- `updated`：更新已有账号成功
- `warnings`：照常记日志，但不判失败

### 5.5.5 关于 access token 生命周期

这里必须作为功能设计的一部分明确下来：

- `sub2api_codex_session` 策略导入的是当前 Web session
- 通常只有 `access_token`，没有真实 `refresh_token`
- 因此账号生命周期取决于当前 access token
- token 过期后，SUB2API 应按其原生逻辑自动暂停

扩展侧不做以下事情：

- 不假装它是完整 OAuth 账号
- 不伪造 refresh token 续期能力
- 不偷偷降级回 OAuth 交换

## 5.6 SUB2API API 层设计

新逻辑应当落在：

- `background/sub2api-api.js`

而不是去复用旧的：

- `flows/openai/content/sub2api-panel.js`

原因：

1. 当前主链路已迁移到 `background/sub2api-api.js`
2. session 导入需要登录、查分组、查代理、发导入请求，这些都属于后台 API 编排
3. 继续往 `flows/openai/content/sub2api-panel.js` 塞逻辑会造成双实现

建议新增 API 方法：

- `importCodexSessionAccount`
- 或 `importCurrentChatGptSession`

该方法内部复用已有：

- `loginSub2Api`
- `getGroupsByNames`
- `resolveSub2ApiProxy`
- `resolveSub2ApiAccountPriority`

不要重复造这几套解析逻辑。

同时需要明确职责边界：

- `background/panel-bridge.js` 继续只负责“跨 target 的 OAuth URL 申请桥接”
- session 导入不要硬塞进 `requestOAuthUrlFromPanel`
- `flows/openai/background/steps/platform-verify.js` 继续只处理 callback 型平台验证
- `sub2api-session-import` 走独立后台执行器，不混进 `platform-verify`

## 5.7 后台总控与运行态设计

### 5.7.1 OAuth 相关总控必须按策略显式分流

当前后台总控明显带有强 OAuth 假设：

- `refreshOAuthUrlBeforeStep6`
- `AUTH_CHAIN_NODE_IDS`
- OAuth 总超时窗口
- localhost callback 捕获与恢复
- `platform-verify` 失败后的 auth-chain 重开

这些逻辑在 session strategy 下都不能继续生效。

最终要求：

1. `oauth` 策略时，保持现有行为
2. `sub2api_codex_session` 策略时：
   - 不刷新 OAuth URL
   - 不进入 AUTH_CHAIN
   - 不等待 localhost callback
   - 不启动 OAuth 总超时
   - 不走 confirm/platform-verify 的重开策略

### 5.7.2 新策略不属于 AUTH_CHAIN

`sub2api-session-import` 不能被加入：

- `AUTH_CHAIN_NODE_IDS`

原因：

1. 它不是 OAuth 过程
2. 它没有 localhost callback
3. 它的失败不应该触发“回到 oauth-login / confirm-oauth 重试”

其失败处理方式应为：

- 节点内部有限次网络重试
- 最终失败则停止当前流程，保留现场，不自动回退到支付或 OAuth 节点

这是必须明确的边界，否则会把“已支付成功的账号接入失败”错误地重开成“重新支付/重新授权类流程”。

### 5.7.3 runtime state 处理原则

这次不建议新增一套新的 session runtime 大字段组。

原因是：

- session 获取可以现读现用
- 分组、代理、优先级都来自现有设置
- 单节点完成，不需要跨多个中间节点传递临时状态

因此运行态设计应尽量简化为：

1. 新增持久化设置字段 `plusAccountAccessStrategy`
2. 不新增 OAuth 等价的 session 中间态字段
3. 切换到 session strategy 时，需要清理旧 OAuth 残留字段
4. 切回 OAuth 时，也要让旧 session 节点状态失效并重建 `nodeStatuses`

必须清理或确保失效的旧字段包括：

- `oauthUrl`
- `localhostUrl`
- `sub2apiSessionId`
- `sub2apiOAuthState`
- 以及围绕 OAuth deadline 的状态

### 5.7.4 nodeStatuses 重建规则

当前 `message-router` 已在以下变更时重建节点状态：

- `plusModeEnabled`
- `plusPaymentMethod`
- `phoneSignupReloginAfterBindEmailEnabled`

本次必须补上：

- `plusAccountAccessStrategy`

因为它直接改变尾链拓扑。

否则会出现：

- 新步骤定义已经换成 session tail
- 旧的 `oauth-login / confirm-oauth / platform-verify` 状态还残留在 `nodeStatuses`

导致自动运行、最终成功判定、跳步恢复全部错位。

## 5.8 settings schema / 持久化 / 导入导出设计

### 5.8.1 settings-schema

`core/flow-kernel/settings-schema.js` 需要在：

- `flows.openai.plus`

下新增：

- `plusAccountAccessStrategy`

并同步到扁平导出字段：

- `next.plusAccountAccessStrategy`

同时需要处理：

- 默认值
- 旧状态兼容
- 扁平导入
- `settingsState` 嵌套结构

### 5.8.2 background normalizePersistentSettingValue

`background.js` 当前有显式的持久化字段归一化开关，必须新增：

- `case 'plusAccountAccessStrategy'`

非法值一律回退到：

- `oauth`

### 5.8.3 历史记录与设置导出测试

当前已有针对以下方向的测试：

- settings 持久化
- account history 归一化
- flow settings schema 映射

因此本次不能只改 schema 而不补测试，否则很容易出现：

- UI 能选
- 但设置导出没带上
- 设置导入后丢失
- background state 恢复后策略回默认

## 5.9 flow capability 设计

### 5.9.1 不要把策略可用性写死在 UI

应扩展 `core/flow-kernel/flow-capabilities.js`，让它输出：

- `requestedPlusAccountAccessStrategy`
- `effectivePlusAccountAccessStrategy`
- `availablePlusAccountAccessStrategies`
- `canEditPlusAccountAccessStrategy`

目标能力建议定义为：

- `cpa`: 只支持 `oauth`
- `sub2api`: 支持 `oauth` 和 `sub2api_codex_session`
- `codex2api`: 只支持 `oauth`

这样可以把：

- UI 可编辑性
- 实际步骤生效值
- 后台模式归一化

统一建立在同一套 capability 结论上，避免 sidepanel / background / step-definitions 三边各写一套 if 判断。

## 5.10 message-router 设计

本方案不建议为了 session import 再新增一套复杂 `handleStepData(step, payload)` 分支。

更合理的做法是：

- `sub2api-session-import` 作为后台节点，直接在执行器内完成 session 读取和 SUB2API 导入
- 完成后直接 `completeNodeFromBackground`

这样 `message-router` 主要需要承担的是：

1. 保存新设置字段
2. 模式切换时重建 nodeStatuses
3. 最终成功节点判定不能再隐式依赖 `platform-verify`
4. Plus 相关日志、提示语不能再硬编码 OAuth

### 5.10.1 最终成功节点判定

当前已有测试说明“Plus 最终成功记录不能写死某个固定 step”。

本次需要继续泛化为：

- 以当前动态步骤集合的**最后一个节点**为准

这样 session strategy 下最后一步可以自然变为：

- `sub2api-session-import`

而不需要继续假设最后节点一定是：

- `platform-verify`

## 5.11 自动运行与重试设计

### 5.11.1 OAuth 失败重开逻辑只保留给 OAuth

当前自动运行在 Plus 后半段有大量“回到 oauth-login / confirm-oauth 重开”的逻辑。

session strategy 下这些逻辑全部不适用。

必须改为：

- **仅当当前策略生效值为 `oauth` 时，才进入原有 OAuth 重开路径**

### 5.11.2 session import 节点的重试策略

`sub2api-session-import` 节点建议只做：

- 有限次的 API 级重试

可重试错误类型：

- SUB2API 登录瞬时失败
- 分组/代理查询瞬时失败
- 导入接口的短暂网络波动

不自动重试的错误类型：

- session 为空
- access token 不可解析或已过期
- 当前 tab 不在可读 session 的域名页面
- 分组不存在
- 配置缺失
- 后端明确业务错误

最终失败后直接停止，不自动回退到支付链路，也不自动跳回 OAuth 节点。

## 6. 方案自检结论

### 6.1 是否符合需求

符合，原因如下：

- 名称已按要求设计成“Plus 模式下的账号接入策略”
- 只对 `sub2api` 真正开放 session 导入
- `cpa / codex2api` 保持 OAuth，UI 禁用
- 明确采用 `sub2api` 原生导入逻辑
- 没有再引入 Plus 手机号注册方案
- 没有再按固定步号设计

### 6.2 是否完整

完整，覆盖了：

- UI
- schema
- settings 持久化
- capability
- step definitions
- 节点执行器
- sub2api API 封装
- runtime 清理
- message-router
- auto-run
- 最终成功判定
- 文案修正
- 测试与验收

### 6.3 是否存在上下冲突

当前方案内部无冲突，关键原因：

1. “请求策略”和“生效策略”分离，避免 target 切换时既要禁用又要保留用户偏好的矛盾
2. session strategy 只在 Plus 邮箱链路下生效，避免与 phone 分支冲突
3. session strategy 不加入 AUTH_CHAIN，避免与 OAuth 重开机制冲突
4. 不新增独立 flow，只替换动态尾链，避免与现有 flow registry 冲突

### 6.4 是否存在逻辑遗漏

当前已主动补齐的高风险遗漏点有：

- Plus 手动确认弹窗的固定“第 10 步 OAuth 登录”文案
- 最终成功节点不能假设是 `platform-verify`
- `nodeStatuses` 必须把 `plusAccountAccessStrategy` 纳入重建条件
- `settings-schema` 的扁平导出与导入恢复
- `normalizePersistentSettingValue` 的新字段归一化
- 旧 OAuth runtime 字段切换时的清理
- session 导入并不具备 refresh_token 自动续期能力

### 6.5 是否存在规范不一致风险

有风险，但已在方案中明确规避路径：

1. 代码库当前存在 `background.js` 与模块文件并存的结构，修改时必须按仓库现有组织方式保持一致，不能只改其中一处
2. Plus 文案当前在多个入口分散存在，新增策略后必须统一改成基于“当前尾链/当前策略”的动态文案
3. 任何新增枚举值都必须同时同步：
   - schema
   - capability
   - sidepanel
   - background normalize
   - tests

### 6.6 是否有乱码风险

有，需要明确纳入开发自检：

1. 新增和改动文件统一使用 UTF-8
2. 新增中文文案直接写 UTF-8，不要复制外部工具里的转码残留
3. 更新测试断言时，不要引入乱码字符串快照
4. Markdown 文档、HTML 文案、JS 字符串三处都要做肉眼检查

## 7. 开发清单

以下阶段仅表示**实施顺序与每阶段自检顺序**。

## 阶段 A：设置模型、能力注册、UI 入口

### 目标

让 Plus 模式先具备正式的“账号接入策略”配置入口，并且在 `sub2api / cpa / codex2api` 三种 target 下表现正确。

### 涉及文件

- `core/flow-kernel/settings-schema.js`
- `core/flow-kernel/flow-capabilities.js`
- `core/flow-kernel/flow-registry.js`
- `sidepanel/sidepanel.html`
- `sidepanel/sidepanel.js`
- `background.js`

### 完成标准

1. 新增 `plusAccountAccessStrategy`
2. 默认值为 `oauth`
3. Plus 开启后显示策略行
4. `sub2api` 下可编辑
5. `cpa / codex2api` 下显示但禁用，运行生效值固定为 `oauth`
6. Plus 关闭时该行隐藏
7. 所有相关文案不再写死“第 10 步 OAuth”

### 阶段自检

1. 检查 schema 嵌套结构和扁平结构是否双向一致
2. 检查导入导出设置后，新字段是否保留
3. 检查 UI 显隐是否跟 `plusModeEnabled` 和 target 联动，而不是只靠写死判断
4. 检查 target 从 `sub2api` 切到 `cpa/codex2api` 时，UI 是否禁用且展示值正确
5. 检查从 `cpa/codex2api` 切回 `sub2api` 时，用户原来的偏好是否能恢复
6. 检查中文文案是否有乱码

## 阶段 B：动态步骤与节点拓扑切换

### 目标

让 Plus 模式在 session strategy 生效时，真正替换掉 OAuth 尾链，而不是只在 UI 上多一个选择框。

### 涉及文件

- `data/step-definitions.js`
- `sidepanel/sidepanel.js`
- `background.js`
- 相关 step definitions / sidepanel 测试

### 完成标准

1. `plusAccountAccessStrategy` 被纳入步骤定义选项
2. PayPal / GoPay / GPC 三条 Plus 前缀链路都能在正确锚点接入 `sub2api-session-import`
3. session strategy 下不再出现：
   - `oauth-login`
   - `fetch-login-code`
   - `post-login-phone-verification`
   - `confirm-oauth`
   - `platform-verify`
4. Plus 手机号链路不会意外生成 session tail

### 阶段自检

1. 检查三种支付方式的尾链是否都正确替换
2. 检查“步骤标题 / 最后一步 / 节点列表 / step ids”是否都随策略变化
3. 检查切换策略后 `nodeStatuses` 是否被重建
4. 检查没有任何代码还在用固定 step number 判断 Plus 尾链
5. 检查 session strategy 下的最后节点是否已经是 `sub2api-session-import`

## 阶段 C：SUB2API session 导入执行器与 API 封装

### 目标

真正接上“读取当前 ChatGPT 会话并导入到 SUB2API”的执行逻辑。

### 涉及文件

- `background/sub2api-api.js`
- `flows/openai/background/steps/sub2api-session-import.js`
- `core/flow-kernel/step-registry.js` 或后台节点注册处
- `flows/openai/content/plus-checkout.js`
- `flows/openai/background/steps/create-plus-checkout.js`

### 完成标准

1. 能从当前 Plus 会话页读出 `session/accessToken`
2. 能复用现有 SUB2API 登录、查分组、查代理逻辑
3. 能调用 `import/codex-session`
4. 能正确处理 `created / updated / warnings / failed`
5. 成功后以 `sub2api-session-import` 节点完成

### 阶段自检

1. 检查没有复制外部项目的转换代码
2. 检查没有把 `sessionToken` 当 `refresh_token`
3. 检查没有伪造 placeholder refresh token
4. 检查 group/proxy/priority 是否复用了现有设置，不新增重复配置
5. 检查 session 为空、tab 域名不对、access token 过期时是否能直接明确失败
6. 检查日志是否能区分 created 和 updated

## 阶段 D：后台总控、自动运行、状态清理

### 目标

让 session strategy 在后台真正成为一条独立于 OAuth 的 Plus 尾链，而不是继续被旧 OAuth 控制逻辑误伤。

### 涉及文件

- `background.js`
- `core/flow-kernel/runtime-state.js`
- `background/message-router.js`
- `flows/openai/background/steps/platform-verify.js`
- `background/panel-bridge.js`
- 自动运行 / auth-chain 相关测试

### 完成标准

1. session strategy 下不会再刷新 OAuth URL
2. session strategy 下不会再依赖 localhost callback
3. session strategy 下不会进入 AUTH_CHAIN
4. 切换到 session strategy 时会清理旧 OAuth 残留状态
5. 最终成功节点判定支持 `sub2api-session-import`
6. auto-run 不会把 session import 失败错误地重开到 OAuth 或支付节点

### 阶段自检

1. 检查 `AUTH_CHAIN_NODE_IDS` 是否仍然只包含 OAuth 节点
2. 检查 `refreshOAuthUrlBeforeStep6` 是否已经按策略分流
3. 检查 `oauthFlowDeadlineAt / oauthFlowDeadlineSourceUrl / localhostUrl / oauthUrl` 等状态在 session strategy 下不会继续参与流程
4. 检查 `message-router` 的 Plus 模式日志和成功判定没有写死 OAuth
5. 检查从 `oauth -> session`、`session -> oauth` 双向切换时，状态清理是否完整

## 阶段 E：测试补齐、回归验证、编码自检

### 目标

把所有会被此次设计影响的行为补成自动测试，并做最终一致性回归。

### 涉及文件

- `tests/step-definitions-module.test.js`
- `tests/sidepanel-plus-payment-method.test.js`
- `tests/flow-capabilities-module.test.js`
- `tests/background-settings-schema-persistence.test.js`
- `tests/background-account-history-settings.test.js`
- `tests/background-message-router-module.test.js`
- `tests/background-message-router-plus-final-step.test.js`
- `tests/background-auth-chain-guard.test.js`
- `tests/auto-run-step6-restart.test.js`
- 新增的 `sub2api session import` 相关测试文件

### 完成标准

1. UI、schema、步骤、后台、auto-run 都有对应测试
2. session strategy 下的最终成功节点有专门测试
3. OAuth 旧行为回归不被破坏
4. Plus 不走手机号注册的约束仍然成立

### 阶段自检

1. 检查所有新增测试都不是基于固定步号，而是基于动态 step key / last step 推导
2. 检查 `sub2api`、`cpa`、`codex2api` 三种 target 都覆盖到
3. 检查 `paypal / gopay / gpc-helper` 三种 Plus 支付方式都覆盖到
4. 检查 session strategy 下没有任何测试仍假设最后节点是 `platform-verify`
5. 检查断言文案和快照没有乱码

## 8. 验收标准

以下条件全部满足，才算本功能真正做完：

1. Plus 模式新增“账号接入策略”配置
2. `sub2api` 下可以在 `OAuth` 与 `导入当前 ChatGPT 会话到 SUB2API` 之间切换
3. `cpa / codex2api` 下该策略显示但禁用，实际始终走 OAuth
4. Plus 下仍只允许邮箱注册
5. session strategy 下，Plus 尾链不再出现 OAuth 节点
6. session strategy 下，导入逻辑走 `sub2api` 原生 `import/codex-session`
7. session strategy 下，不依赖 `oauthUrl / localhostUrl / sub2apiSessionId / sub2apiOAuthState`
8. session strategy 下，最终成功节点为 `sub2api-session-import`
9. session strategy 下失败不会误触发 OAuth auth-chain 重开
10. 设置导出、导入、恢复后，新策略不会丢失
11. 所有新增中文文案无乱码
12. 旧 OAuth Plus 路径在 `sub2api / cpa / codex2api` 下仍可正常工作

## 9. 明确禁止事项

本次开发明确禁止以下做法：

1. 复制 `GPTSession2CPAandSub2API` 的前端转换代码进入扩展
2. 在扩展里自己手搓一套 sub2api 导入 JSON 转换器来替代 `import/codex-session`
3. 把 `sessionToken` 当作 `refresh_token`
4. 伪造 placeholder `refresh_token`
5. 继续把 Plus 尾链写死为固定步骤号
6. 在 Plus 模式下再设计手机号注册兼容路径
7. 让 session strategy 继续复用 OAuth 的 localhost 回调、auth-chain 超时、step7/step9 重开逻辑
8. 只改 UI 不改后台，或者只改步骤定义不改总控

## 10. 最终结论

这项功能应该按“**Plus 模式账号接入策略**”来做，而不是“在某个固定步骤后插一个小补丁”。

从当前代码结构看，正确实现方式不是复制外部项目代码，而是：

1. 复用扩展现有的 ChatGPT session 读取能力
2. 复用 `sub2api` 原生 `import/codex-session`
3. 在 Plus 动态步骤体系里，用 `sub2api-session-import` 替换整段 OAuth 尾链
4. 把设置、能力、步骤、后台状态、自动运行、最终成功判定、测试一起改完整

只要按本方案实施，就能在不破坏现有 OAuth 方案的前提下，把 `sub2api` 的 Plus 账号接入正式扩展成一套完整、闭环、可维护的策略能力。