FlowPilot/md/plus模式-sub2api-session接入策略开发方案.md

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 账号接入正式扩展成一套完整、闭环、可维护的策略能力。