FlowPilot/docs/多Flow根治性统一重构方案.md

# 多Flow根治性统一重构方案

## 1. 背景

当前项目已经完成过多轮从单一 OpenAI 注册链路向多 flow 架构的重构，但现在的状态仍然属于“骨架已多 flow 化，核心 contract 仍保留 `openai + kiro` 双分支”。

这会带来三个持续性问题：

- 每新增一个 flow，都需要继续修改 core 语义，而不是只新增 flow 自己的模块。
- 文件命名、状态命名、配置命名仍带有明显历史负担，读代码和改代码都累。
- 每次重构都只能修表层，无法保证第三个 flow 接入时不再次爆炸。

本方案的目标不是“再修一轮兼容”，而是一次性把多 flow 架构收口成稳定合同，后续新增 flow 时不再改 core 语义。

## 2. 总目标

本次重构完成后，项目必须达到以下目标：

- 新增一个 flow 时，只新增该 flow 目录和注册项，不再修改 core 的配置合同、运行态合同和侧栏核心语义。
- 所有 flow 都使用同一套配置结构、同一套运行态结构、同一套 source/driver 注册模型。
- OpenAI 与 Kiro 的代码组织、文件命名、步骤命名、source 命名、driver 命名全部统一到同一规范。
- 删除长期存在的历史别名和双轨字段，避免后续维护继续被旧命名拖住。
- 旧配置不再作为运行时输入；旧数据只允许通过导入转换器映射到新 canonical 结构后进入系统。

## 3. 当前根问题

### 3.1 配置模型仍然是双轨

当前 `settings-schema` 只内建 `flows.openai` 和 `flows.kiro` 两套显式结构，同时继续派生：

- `openaiIntegrationTargetId`
- `kiroTargetId`
- `panelMode`

这不是多 flow 通用合同，而是两个 flow 的并排硬编码。第三个 flow 接入时，只能继续增加第三套特判。

### 3.2 运行态模型是裂开的

当前运行态存在两条体系：

- OpenAI 使用 `runtimeState.flowState.openai`
- Kiro 使用独立 `kiroRuntime`

这意味着“flow 私有运行态放哪里”没有统一答案。后续新增 flow 时，要么复制第三套运行态入口，要么继续在 core 写例外分支。

### 3.3 source / driver 仍未彻底注册化

虽然已经有 `flow-registry` 与 `source-registry`，但 core 里仍直接识别：

- OpenAI host
- Kiro host
- OpenAI / Kiro source family

这说明 source 系统还不是“flow 自带定义，core 只消费注册表”，而是“core 知道两个 flow 的页面事实”。

### 3.4 sidepanel 还是默认 flow 分支思维

当前 sidepanel 很多判断仍然是：

- 默认 flow 视为 OpenAI
- 非默认 flow 基本按 Kiro 处理

例如 target 读取、target 持久化、贡献页 target 解析、flow 切换后的字段同步，都带着明显的 `openai / kiro` 条件分支。

### 3.5 “按 flow 执行范围”表面通用，内部仍是双 flow 特判

`stepExecutionRangeByFlow` 在 UI 侧已经接近通用，但写回持久配置时仍只处理：

- `openai`
- `kiro`

这类设计最危险，因为它会制造“表面支持多 flow，实际只有两个 flow 真能落盘”的假通用。

### 3.6 文件和命名仍带历史语义

当前仍大量存在下列混合命名：

- `signup-page`
- `open-chatgpt`
- `platform-verify`
- `plus-checkout`
- `kiro-*`
- `vps-panel`

这些名字有的看起来像通用名，实际是 OpenAI 专属；有的则直接带品牌。继续保留会让后续架构再度滑回历史分支。

## 4. 重构原则

### 4.1 不做旧配置兼容，只做导入转换

本次不保留“先兼容着跑”的中间态。新系统上线后，运行时、持久化读写、sidepanel 消息、background 内部状态全部只认新合同。

原则是：

- 旧配置、旧账号记录、旧 flow 产物只能通过导入器转换
- 导入器是单向转换器，不是长期桥接层
- 导入完成后的数据必须完全符合新合同
- 除导入器外，任何模块都不再直接读写 `panelMode`、`openaiIntegrationTargetId`、`kiroTargetId`、`kiroRuntime` 等旧字段

### 4.2 通用层只负责“怎么跑一个 flow”

core 只解决这些问题：

- flow 注册
- source 注册
- driver 注册
- workflow 运行
- 状态存储
- sidepanel 动态渲染
- 通用服务接入

core 不再知道任何 OpenAI 或 Kiro 业务步骤语义。

### 4.3 flow 私有能力留在 flow 内部

以下能力继续保留为 flow 私有：

- OpenAI 的 OAuth、Plus、接码、平台绑定
- Kiro 的 Builder ID、桌面授权、`kiro.rs` 上传
- 任意新 flow 的站点特有页面状态机、验证码规则、成功判定和产物结构

### 4.4 命名必须先统一，再谈长期可维护性

如果 contract 抽象了，但目录和文件名还保留历史语义，后续阅读成本依然很高。本次重构必须把命名一并统一。

## 5. 第一层功能边界：公共能力与私有能力

这一层只回答一个问题：哪些能力应该是扩展级公共能力，哪些能力必须收回到各 flow 自己内部。

本层结论确定后，后续所有 contract、目录结构和配置模型都必须服从这条边界，不允许再反向把 flow 私有语义塞回公共层。

### 5.1 扩展级公共能力

当前项目真正应保留为全局公共能力的只有四块：

- 项目壳层
- 邮箱服务
- 账户密码
- IP 代理

其中：

- `项目壳层` 只包括顶部容器、flow 切换、开始/停止/重试、日志与运行态展示这些外层承载能力。
- `邮箱服务` 是跨 flow 的身份与收件基础设施。
- `账户密码` 指侧栏中的“账户密码”文本框，它的语义是“注册目标账号时使用的共享密码”。
- `IP 代理` 是扩展级环境能力，不属于任何单独 flow。

### 5.2 邮箱服务需要继续重构统一

邮箱服务值得保留为公共层，但必须从历史 OpenAI 语义中继续剥离。

它在功能上只应该负责三类事情：

- 生成注册邮箱
- 提供收件与轮询能力
- 维护当前轮次的邮箱身份

邮箱服务不应该继续承接这些内容：

- 某个 flow 的验证码命中规则
- 某个 flow 的页面跳转语义
- 某个 flow 的身份保留分支
- 某个 flow 的注册成功或失败判断

因此邮箱层应拆成两部分：

- `公共邮箱服务`
  负责邮箱生成、收件、轮询、当前邮箱身份维护
- `flow 私有邮件规则`
  负责某个 flow 在某一步认哪封邮件、提取什么内容、何时算命中

结论：

- 邮箱服务是公共能力
- 邮件规则不是公共能力

### 5.3 “账户密码”是共享注册密码，不是公共凭据服务

当前侧栏的“账户密码”文本框，其真实产品语义已经确认：

- 它不是平台后台登录密码
- 它不是某个管理接口凭据
- 它不是统一的凭据中心配置
- 它只是“注册出来的目标账号要设置成什么密码”

因此这里不应再抽象出“公共凭据服务”。

正确做法是：

- 保留一个全局公共的 `共享注册密码`
- 各 flow 自己决定是否使用这份密码
- 各 flow 自己决定在哪一步使用
- 如果某个 flow 没有设置密码步骤，则直接忽略

这意味着：

- `账户密码` 是公共输入能力
- `凭据结构` 不是公共能力
- `凭据产物字段` 不是公共能力

### 5.4 凭据与账号产物必须保持 flow 私有

虽然不做公共凭据服务，但每个 flow 仍然会生成自己的账号产物。

例如：

- OpenAI 可能产出邮箱、密码、session、OAuth 结果、平台接入结果
- Kiro 可能产出邮箱、密码、refresh token、clientId、clientSecret、上传结果

这里允许公共的只有“外层展示容器”或“记录壳层”，不允许公共化的内容包括：

- 主身份字段
- token 字段
- 上传字段
- 绑定字段
- 各类平台回调字段

结论：

- 账号产物展示容器可以公共
- 账号产物字段结构必须 flow 私有

### 5.5 IP 代理属于扩展级环境能力

IP 代理应直接定义为：

- 扩展级公共能力
- 与 flow 无关
- 由 flow 声明“可用/必需/禁用”，但不拥有它

flow 最多只能声明：

- 当前 flow 是否允许代理
- 当前 flow 的哪些页面需要代理约束
- 当前 flow 是否需要代理检测或 fail-close 策略

但代理配置、切换、应用、检测、诊断，都不属于 flow 私有模型。

### 5.6 第一层最终边界

本次重构在功能边界上最终固定为：

#### 全局公共能力

- 项目壳层
- 邮箱服务
- 共享注册密码
- IP 代理

#### 仅允许公共容器，不允许公共字段语义

- 账号记录容器
- 产物展示容器

#### flow 私有能力

- 账号主身份模型
- 邮件命中规则
- 验证码规则
- 注册步骤
- 登录步骤
- OAuth / callback
- 支付
- 上传
- flow 最终凭据与产物字段结构

后续所有重构如果与这条边界冲突，以这条边界为准，不允许再为了省事把 flow 私有字段上提为公共模型。

## 6. 第二层产品模型：flow 与 target

这一层只回答两个问题：

- flow 在产品上到底是什么
- target 在产品上到底是什么

如果这一层不先定死，后面配置模型、侧栏模型和运行态模型就会继续在 `panelMode / integrationTarget / targetId` 之间摇摆。

### 6.1 flow 的产品定义

每个 flow 都应被定义为一条独立的“账号生产链路”。

它至少具备以下特征：

- 有独立入口
- 有独立步骤顺序
- 有独立成功判定
- 有独立最终产物
- 只按需消费公共能力，例如邮箱、共享注册密码、IP 代理

因此，flow 不是“几步流程的组合”，而是一个完整产品单元。

结论：

- `openai` 是一个完整 flow
- `kiro` 是一个完整 flow
- 未来新站点也必须是完整 flow
- 不允许再把新站点业务塞进现有 flow 里做条件分支

### 6.2 target 的产品定义

target 不应继续被理解为历史意义上的 `panelMode`。

正确的产品语义应该是：

- target 是这个 flow 最终产物的去向
- target 是这个 flow 最终服务的目标系统

例如：

- OpenAI flow 的 target 可以是 `CPA / SUB2API / Codex2API`
- Kiro flow 的 target 可以是 `kiro-rs`

因此：

- `flow` 回答“怎么产出账号或产物”
- `target` 回答“产出后要交给谁使用”

这两个概念必须严格分层，不允许再混用。

### 6.3 每个 flow 都必须自带 target 模型

以后不再允许：

- 只有 OpenAI flow 有 target
- Kiro flow 走另一套特殊 target 字段
- 默认 flow 使用 `panelMode`，其他 flow 使用 `targetId`

统一要求如下：

- 每个 flow 都必须有 `selectedTarget`
- 每个 flow 都必须有 `targets`
- 单 target flow 只是“只有一个 target”，不是“没有 target 概念”

即使某个 flow 当前只有一个 target，模型里也必须保留 target 层，只是在 UI 上可以隐藏选择器。

这样做的原因是：

- 未来该 flow 如果新增第二个 target，不需要再次改核心模型
- sidepanel 和 settings 不需要区分“哪个 flow 才有 target”

### 6.4 flow 的产品结构

从功能角度，每个 flow 都应至少包含以下部分：

- flow 基本信息
- flow 对公共能力的依赖声明
- flow 私有配置
- flow targets
- flow 产物定义

进一步展开：

- `flow 基本信息`
  - 名称
  - 说明
  - 是否可自动化
- `公共能力依赖声明`
  - 是否使用邮箱
  - 是否使用共享注册密码
  - 是否允许代理
- `flow 私有配置`
  - 仅该 flow 自己理解的设置
- `flow targets`
  - 一个或多个目标系统
- `flow 产物定义`
  - 该 flow 最终生成什么结果

### 6.5 第二层最终结论

本次重构在产品模型上最终固定为：

- `flow = 独立账号生产产品线`
- `target = flow 产物去向`
- 每个 flow 都必须天然支持自己的 target 模型
- 全局只保留“当前选中的 flow”
- 当前 target 永远从当前 flow 自己内部读取

由此带来的直接结果是：

- `panelMode` 只允许存在于导入器输入映射里
- `openaiIntegrationTargetId / kiroTargetId` 不再是长期 canonical 配置
- sidepanel 不再需要围绕“默认 flow 是 OpenAI”建立逻辑

后续所有设计如果与这层产品模型冲突，以这层定义为准。

## 7. 第三层运行模型：统一节点承载，不统一阶段语义

这一层只回答一个问题：

- 多 flow 体系下，到底应该统一什么样的运行流程模型

本层最终结论是：

- 统一节点承载方式
- 不统一跨 flow 的阶段语义

也就是说，core 只负责“如何承载一个 flow 的内部流程”，不负责替每个 flow 规定必须长成同一种产品流程形状。

### 7.1 不强制统一阶段

本次重构不再要求所有 flow 都映射到一套固定阶段，例如：

- 准备
- 进入
- 验证
- 成型
- 接入
- 交付

这种抽象在文档上容易显得整齐，但对真实多 flow 来说约束过强，后续会重新形成“表面通用、实际不好用”的壳层。

因此：

- OpenAI 保持自己的内部流程形状
- Kiro 保持自己的内部流程形状
- 新 flow 也不需要被迫套进统一阶段模型

### 7.2 真正需要统一的是节点运行模型

虽然不统一阶段语义，但所有 flow 仍然必须共享同一套“节点承载方式”。

每个 flow 的内部流程都应被理解为：

- 一组有顺序的节点
- 节点之间存在前后关系
- 每个节点都有清晰输入和结果
- 节点可以被手动执行、自动执行、停止和重试

也就是说，core 只统一：

- 节点是什么
- 节点如何排序
- 节点如何连接
- 节点如何汇报状态

而不统一：

- 节点一定属于哪个阶段
- 某个数字步骤在所有 flow 里都代表什么

### 7.3 数字步骤只表示 flow 内部显示顺序

以后数字步骤只允许表达：

- 当前 flow 内部的展示顺序

不再允许表达：

- 跨 flow 的固定语义
- 全局共享的产品阶段
- 某个历史 OpenAI 10 步链路的编号意义

这意味着：

- `Step 4` 不再天然等于“验证码步骤”
- `Step 7` 不再天然等于“OAuth”
- `Step 9` 不再天然等于“平台验证”

这些语义都必须下沉为 flow 私有流程定义。

### 7.4 节点的最小公共合同

从产品功能角度，每个节点只需要满足以下最小公共合同：

- 有名称
- 有顺序
- 有前后关系
- 有明确成功结果
- 有明确失败结果
- 可以手动执行
- 可以自动执行
- 可以停止
- 可以重试

节点不应该再承载这些“假通用”要求：

- 必须属于固定阶段
- 必须服从跨 flow 的相同命名
- 必须让不同 flow 共享同一种页面语义

### 7.5 外层统一状态，不统一流程内容

扩展外层只需要理解统一运行状态，不需要理解每个 flow 的内部阶段。

建议外层只保留以下状态集合：

- 未开始
- 运行中
- 等待中
- 需人工处理
- 已停止
- 已失败
- 已完成

这些状态只服务于：

- 侧栏展示
- 自动运行控制
- 停止 / 重试入口
- 日志与记录

它们不应反过来要求 flow 把内部步骤硬映射成统一业务阶段。

### 7.6 执行范围绑定当前 flow 的节点顺序

`执行范围` 这个能力未来仍然保留，但其产品定义应明确为：

- 对当前 flow 可见节点顺序的执行限制

它不再代表：

- 全局统一步骤范围
- 跨 flow 的阶段范围
- OpenAI 历史编号的范围

也就是说，执行范围始终只作用于“当前 flow 自己的节点序列”。

### 7.7 第三层最终结论

本层最终固定为：

- 不统一所有 flow 的阶段语义
- 不统一所有 flow 的产品流程形状
- 每个 flow 自己定义内部流程
- core 只统一节点承载方式
- 数字步骤只代表当前 flow 的显示顺序
- 扩展外层只理解统一运行状态
- 执行范围只绑定当前 flow 的节点顺序

后续如果有设计要求把所有 flow 再次硬映射成一套跨 flow 固定阶段，以本层结论为准，默认不采纳。

## 8. 第四层界面分工：公共壳层与 flow 工作面

这一层只回答一个问题：

- sidepanel 到底哪些界面必须永远公共，哪些界面必须彻底交给 flow 自己

如果这层不先定死，后续所有 flow 接入都会继续把 `openai / kiro / new-flow` 的条件分支堆进侧栏主文件。

### 8.1 只保留两层界面

本次重构后，sidepanel 只保留两层界面：

- 公共壳层
- flow 工作面

不再增加第三层“伪通用业务面板”。

原因很简单：

- 公共壳层负责承载扩展级操作
- flow 工作面负责承载 flow 私有配置与流程内容

这样结构最稳，也最不容易重新膨胀。

### 8.2 公共壳层放什么

公共壳层只允许放扩展级公共入口与全局控制入口，包括：

- flow 选择
- target 选择
- 开始 / 停止 / 重试 / 自动
- 当前运行状态
- 日志区
- 账号记录入口
- 文档 / 引导 / 更新提示入口
- 贡献 / 使用教程按钮
- 公共能力入口
- 邮箱服务
- 共享注册密码
- IP 代理

这里的“贡献 / 使用教程”按钮属于公共壳层入口，但其功能逻辑必须按当前 flow 适配。

也就是说：

- 按钮入口位置是公共的
- 点击后的目标页面、说明内容、贡献适配逻辑由当前 flow 决定

不允许再把它写成某一个默认 flow 的固定行为。

### 8.3 flow 工作面放什么

flow 工作面只允许承载该 flow 自己的内容，包括：

- flow 私有配置
- flow 私有步骤列表
- flow 私有运行态展示
- flow 私有人工补位入口
- flow 私有产物展示字段

例如：

- OpenAI 的 Plus、OAuth、平台接入、手机验证，只能放在 OpenAI 工作面
- Kiro 的桌面授权、上传到 `kiro.rs`，只能放在 Kiro 工作面

未来新增 flow 也必须遵守同样规则。

### 8.4 步骤列表属于 flow 私有界面

步骤列表不属于公共界面。

公共壳层最多只负责：

- 放置步骤列表容器
- 提供统一骨架样式
- 提供统一按钮状态和颜色规则

但以下内容都必须由 flow 自己决定：

- 有哪些步骤
- 步骤叫什么
- 步骤显示什么说明
- 哪些步骤可执行
- 哪些步骤可跳过
- 哪些步骤需要人工补位

### 8.5 账号记录采用“公共入口 + 私有内容”

账号记录建议固定为：

- 公共入口
- flow 私有内容

也就是说：

- 记录页或记录弹层入口是公共的
- 分页、筛选、基础容器可以公共
- 每条记录里显示哪些字段，按当前 flow 决定

这样既保留统一入口，也避免为了统一记录展示而把所有 flow 的产物字段重新揉成一个假通用结构。

### 8.6 公共能力入口的边界

公共区可以保留三类公共能力入口：

- 邮箱服务
- 共享注册密码
- IP 代理

但这些公共入口只负责：

- 配置
- 当前状态展示
- 基础校验

它们不负责：

- 解释某个 flow 的业务步骤
- 解释某个 flow 的页面语义
- 承载某个 flow 的专属运行逻辑

这意味着：

- OpenAI 专属邮箱模式说明，应回到 OpenAI 工作面
- Kiro 专属密码说明，应回到 Kiro 工作面
- 某个 flow 的代理特殊策略，也应由该 flow 自己声明和解释

### 8.7 target 选择器仍属于公共壳层

target 虽然属于当前 flow 的内部模型，但从用户交互角度，它属于“开跑前的全局决策”。

因此：

- target 选择器放在公共壳层
- target 的可选项由当前 flow 决定
- target 的说明文案也由当前 flow 决定

这样用户能在统一入口完成“跑哪个 flow、产物交给谁”的全局决策。

### 8.8 第四层最终结论

本层最终固定为：

- sidepanel 只保留“公共壳层 + flow 工作面”两层
- 公共壳层承载扩展级入口和全局控制
- flow 工作面承载 flow 私有配置、步骤、运行态和产物
- 步骤列表属于 flow 私有界面
- 账号记录采用“公共入口 + 私有内容”
- 贡献 / 使用教程按钮属于公共壳层入口，但功能逻辑必须按当前 flow 适配
- 不允许再把任何 OpenAI / Kiro / 新 flow 的专属业务配置继续堆进公共区

## 9. 目标架构

建议收口为以下目录形态：

```txt
core/
  flow-kernel/
    flow-registry.js
    source-registry.js
    driver-registry.js
    settings-schema.js
    runtime-state.js
    workflow-engine.js
    step-registry.js
    tab-runtime.js
    logging-status.js

flows/
  index.js

  openai/
    flow.js
    settings.js
    state.js
    sources.js
    drivers.js
    steps/
    content/
    mail/
      rules.js
    contribution/

  kiro/
    flow.js
    settings.js
    state.js
    sources.js
    drivers.js
    steps/
    content/
    contribution/

imports/
  legacy/
    settings-importer.js
    account-records-importer.js
    flow-artifacts/
      openai.js
      kiro.js
```

第一阶段可以不强制先物理移动到 `core/flow-kernel/`，但逻辑上必须先收成这套边界。

补充要求：

- `imports/legacy/` 是全仓库唯一允许理解旧字段、旧结构、旧命名的目录。
- `core/` 与 `flows/` 不再保留任何旧字段回写逻辑。

## 10. 统一合同

### 10.1 配置合同

唯一 canonical 配置结构：

```js
settingsState = {
  schemaVersion,
  activeFlowId,
  services: {
    account,
    email,
    proxy,
  },
  flows: {
    [flowId]: {
      selectedTargetId,
      targets: {
        [targetId]: {}
      },
      autoRun: {
        stepExecutionRange,
      },
      ui: {},
      features: {},
    }
  }
}
```

要求：

- `selectedTargetId + targets[targetId]` 是唯一 target 入口。
- 不再以 `openaiIntegrationTargetId`、`kiroTargetId` 作为 canonical 字段。
- `panelMode` 不再作为内部真实配置语义，也不再出现在 sidepanel payload、background 持久化写入路径和运行时配置读取路径中。
- 每个 flow 都必须使用 `selectedTargetId + targets[targetId]` 组合。
- target 专属字段只能挂在对应 `targets[targetId]` 下，不再允许提升到 flow 顶层或全局顶层。
- 旧配置文件不能被直接加载运行，只能先经过导入转换器。

### 10.2 运行态合同

唯一 canonical 运行态结构：

```js
runtimeState = {
  activeFlowId,
  activeRunId,
  currentNodeId,
  nodeStatuses,
  sharedState: {},
  serviceState: {
    account: {},
    email: {},
    proxy: {},
  },
  flowState: {
    [flowId]: {
      session: {},
      nodes: {},
      artifacts: {},
      ui: {},
    }
  }
}
```

要求：

- 删除独立 `kiroRuntime` 作为长期入口。
- OpenAI、Kiro、未来新 flow 的私有运行态全部进入 `runtimeState.flowState[flowId]`。
- 顶层不再持久化任何 flow 私有扁平字段。
- 运行态不做旧快照导入；导入只处理持久配置与持久产物，导入完成后从新运行态起跑。
- 如需便捷读取视图，只能从 canonical `flowState` 派生，不能再反向写出独立运行态入口。

### 10.3 flow 定义合同

每个 flow 统一导出：

```js
{
  id,
  label,
  services,
  capabilities,
  settingsGroups,
  targets,
  settingsShape,
  runtimeStateShape,
  sources,
  drivers,
  workflow,
  artifactSchema,
  importers,
  contributionAdapters,
}
```

要求：

- `flow-registry` 只合并 flow 定义。
- `settings-schema`、`source-registry`、`driver-registry`、`step-registry` 都只消费 flow 导出的定义。
- flow 私有导入转换规则也由 flow 自己提供，core 只负责分发到对应 importer。
- core 不再直接声明某个 flow 的 target、source、driver。

### 10.4 source 合同

每个 source 至少声明：

- `id`
- `flowId`
- `kind`
- `label`
- `hostPatterns`
- `familyMatcher`
- `injectFiles`
- `readyPolicy`
- `cleanupScopes`
- `tabReusePolicy`

要求：

- host 判断由 flow source 定义驱动。
- `unknown-source` 仅做诊断，不自动回退到任意业务 source。
- callback cleanup 必须由 `cleanupScope -> ownerSource` 注册表驱动。

### 10.5 driver 合同

每个 driver 至少声明：

- `id`
- `sourceId`
- `commands`
- `injectFiles`

要求：

- driver 负责“页面能做什么”
- source 负责“页面是什么、如何识别、如何复用、如何清理”

### 10.6 step 合同

每个 step 统一使用：

- `id`
- `order`
- `key`
- `title`
- `sourceId`
- `driverId`
- `command`
- `mailRuleId`

要求：

- `step key` 只表达 flow 内语义，不再混入历史平台词和伪通用词。
- `background/steps/*.js` 这种共享目录最终要消失，改由各 flow 自己维护 `steps/`。

## 11. 命名统一方案

### 11.1 flow 目录命名

- `flows/openai/`
- `flows/kiro/`

未来新增 flow 一律使用 `flows/<flow-id>/`

### 11.2 source 命名

统一格式：

```txt
<flow-id>-<page-role>
mail-<provider>
panel-<target>
```

例如：

- `openai-auth`
- `openai-entry`
- `openai-checkout`
- `openai-paypal`
- `openai-gopay`
- `kiro-register`
- `kiro-desktop-authorize`
- `panel-sub2api`
- `panel-cpa`
- `mail-gmail`

### 11.3 driver 命名

统一格式：

```txt
flows/<flow-id>/content/<page-role>.js
flows/<flow-id>/steps/<step-role>.js
```

不再使用历史伪通用名作为全局 driver 语义。

### 11.4 OpenAI 文件重命名建议

以下文件建议统一迁移：

- `flows/openai/content/openai-auth.js` -> `flows/openai/content/openai-auth.js`
- `flows/openai/content/plus-checkout.js` -> `flows/openai/content/checkout-page.js`
- `flows/openai/content/paypal-flow.js` -> `flows/openai/content/paypal-page.js`
- `flows/openai/content/gopay-flow.js` -> `flows/openai/content/gopay-page.js`
- `flows/openai/content/sub2api-panel.js` -> `flows/openai/content/sub2api-panel-page.js`
- `flows/openai/content/vps-panel.js` -> `flows/openai/content/cpa-panel-page.js`

- `flows/openai/background/steps/open-chatgpt.js` -> `flows/openai/steps/open-entry.js`
- `flows/openai/background/steps/submit-signup-email.js` -> `flows/openai/steps/submit-identifier.js`
- `flows/openai/background/steps/fill-password.js` -> `flows/openai/steps/submit-password.js`
- `flows/openai/background/steps/fetch-signup-code.js` -> `flows/openai/steps/submit-signup-code.js`
- `flows/openai/background/steps/fill-profile.js` -> `flows/openai/steps/submit-profile.js`
- `flows/openai/background/steps/wait-registration-success.js` -> `flows/openai/steps/wait-register-complete.js`
- `flows/openai/background/steps/oauth-login.js` -> `flows/openai/steps/start-oauth-login.js`
- `flows/openai/background/steps/fetch-login-code.js` -> `flows/openai/steps/submit-login-code.js`
- `flows/openai/background/steps/confirm-oauth.js` -> `flows/openai/steps/confirm-oauth-consent.js`
- `flows/openai/background/steps/platform-verify.js` -> `flows/openai/steps/complete-platform-bind.js`

### 11.5 Kiro 文件重命名建议

以下文件建议统一迁移：

- `flows/kiro/background/register-runner.js` -> `flows/kiro/steps/register-flow.js`
- `flows/kiro/background/desktop-authorize-runner.js` -> `flows/kiro/steps/desktop-authorize-flow.js`
- `flows/kiro/background/publisher-kiro-rs.js` -> `flows/kiro/steps/upload-credential.js`
- `flows/kiro/background/state.js` -> `flows/kiro/state.js`
- `flows/kiro/content/register-page.js` -> `flows/kiro/content/register-page.js`
- `flows/kiro/content/desktop-authorize-page.js` -> `flows/kiro/content/desktop-authorize-page.js`

## 12. 替换式升级与导入转换策略

### 阶段 1：先定 canonical contract 与最终目录边界

目标：

- 定义统一的 settings、runtime、flow、source、driver、step 合同
- 定义 `core/`、`flows/`、`imports/legacy/` 三层边界
- 明确旧字段只允许出现在导入器中

产出：

- 更新设计文档
- 明确迁移边界

完成标准：

- 不再允许出现“新 flow 以后再看放哪”这种模糊点

### 阶段 2：统一配置模型

目标：

- 让所有 flow 都走 `settingsState.flows[flowId]`
- 停止所有新代码对旧配置字段的直接读写

动作：

- 重写 `core/flow-kernel/settings-schema.js`
- 把 `selectedTargetId` 作为统一 target 入口
- 改写 `background.js` 中 `buildSettingsStatePatchFromFlatUpdates`、`buildAutoRunFreshResetSettingsState`、`buildFreshAutoRunKeepState`
- 改写 `background/message-router.js` 与 `sidepanel/sidepanel.js` 的设置写入路径，只提交 canonical patch
- 将 `panelMode / openaiIntegrationTargetId / kiroTargetId` 从运行时和持久化写入路径移除

完成标准：

- 任意 flow 都可通过相同 API 读取当前 target 和 flow 设置
- 正常保存、导出、恢复流程里不再出现旧 target 字段

### 阶段 3：统一运行态模型

目标：

- 把 `kiroRuntime` 并入 `runtimeState.flowState.kiro`
- 让 OpenAI 与 Kiro 都按同一种 flow 私有运行态承载方式工作

动作：

- 重写 `core/flow-kernel/runtime-state.js`
- 把 `flows/kiro/background/state.js` 合并或迁入 `flows/kiro/state.js`
- 给 OpenAI 与 Kiro 都定义 flow 私有状态 shape 与 reset 规则
- 删除独立 Kiro 运行态主入口
- 停止持久化所有 flow 私有顶层扁平字段

完成标准：

- core 不再区分“OpenAI 私有状态”与“Kiro 私有状态”的存储方式
- 自动运行、fresh reset、日志回写都只消费统一运行态结构

### 阶段 4：建立单向导入转换器

目标：

- 让旧数据只能通过导入器进入新系统
- 明确“导入”与“运行时兼容”是两件不同的事

动作：

- 新建 `imports/legacy/settings-importer.js`
- 新建 `imports/legacy/account-records-importer.js`
- 按需新增 `flows/openai/importers/*` 与 `flows/kiro/importers/*` 用于旧产物字段映射
- 导入器负责识别 `panelMode`、`openaiIntegrationTargetId`、`kiroTargetId`、`stepExecutionRangeByFlow`、`kiroRuntime` 以及旧账号记录结构
- 导入结果统一输出为新 `settingsState`、新账号记录结构、新 flow 产物结构
- 明确不导入旧运行态快照

完成标准：

- 旧配置文件只能通过“导入”按钮进入系统，不能被直接加载运行
- 导入完成后，系统内部不再保留旧字段副本

### 阶段 5：统一 flow 注册与 source/driver 注册

目标：

- 让 flow 目录自带 source、driver、workflow、state、settings 定义

动作：

- 新建 `flows/index.js`
- 把 flow 相关定义从 `core/flow-kernel/flow-registry.js`、`core/flow-kernel/source-registry.js`、`core/flow-kernel/flow-capabilities.js`、`data/step-definitions.js`、`core/flow-kernel/step-registry.js` 拆到各 flow 内
- `source-registry` 改为只做合并与查询
- `workflow-engine` 与 step registry 改为只消费 flow 导出定义

完成标准：

- 新增 flow 时只新增 flow 定义，不改 core host 判断语义

### 阶段 6：统一 sidepanel 驱动方式

目标：

- sidepanel 完全按 registry 驱动，而不是按 `openai / kiro` 条件分支

动作：

- 重写 `sidepanel/sidepanel.js`
- 调整 `sidepanel/contribution-mode.js`、`sidepanel/account-records-manager.js`、相关 flow 私有展示逻辑
- flow selector、target selector、visible groups、capability 全部从 registry 派生
- `stepExecutionRange` 改成真正按当前 flow 通用读写
- 账号记录区改成“公共列表壳层 + flow 私有渲染器”

完成标准：

- sidepanel 不再依赖默认 flow 是 OpenAI 的假设
- sidepanel 不再直接处理 `panelMode` 与 `kiroTargetId` 两套并列写法

### 阶段 7：统一目录与文件命名

目标：

- 把 OpenAI 与 Kiro 都迁入 `flows/<flow-id>/`

动作：

- 重命名文件
- 更新所有 import / `importScripts` / 注入列表 / 测试引用
- 删除历史伪通用文件名
- 将 `content/*.js`、`background/steps/*.js`、`background/kiro/*` 分别迁入对应 flow 目录

完成标准：

- 新人看目录时能立即分清 core 与 flow 私有实现

### 阶段 8：删除旧兼容层与旧字段路径

目标：

- 删除所有只为迁移存在的旧字段、旧别名、旧路径和旧命名

动作：

- 删除 `signup-page -> openai-auth` 长期别名
- 删除 `kiroRuntime` 独立入口
- 删除 `panelMode` 作为内部真实 target 语义
- 删除 `background.js`、`background/message-router.js`、`background/navigation-utils.js`、`background/auto-run-controller.js` 里所有核心旧字段桥接逻辑
- 删除所有 `activeFlowId === 'kiro'` / `activeFlowId === DEFAULT_ACTIVE_FLOW_ID` 的核心结构分支
- 用新的 canonical contract 测试替换旧兼容写回测试；旧字段只保留导入器测试

完成标准：

- 仓库里只有 `imports/legacy/` 与其测试还认识旧字段
- core 只理解“某个已注册 flow”，不理解“OpenAI 还是 Kiro”

## 13. 实施顺序要求

为了避免第三次半重构，本次必须按顺序推进：

1. 先收口 contract
2. 再统一 settings
3. 再统一 runtime
4. 再建立导入转换器
5. 再拆 flow registry/source/driver
6. 再统一 sidepanel
7. 再迁目录和文件名
8. 最后删旧字段与旧桥接逻辑

禁止的做法：

- 先新增第三个 flow，再回头修 core
- 先重命名文件，但 contract 仍旧双轨
- 为了快，继续在 sidepanel 或 background 增加新的 `openai / kiro / new-flow` 三分支
- 一边写 canonical 结构，一边继续保留旧字段双写
- 让旧配置在启动时被直接读取并“尽量凑合可用”

## 14. 完成判定

本次重构只有在满足以下条件时才算完成：

- 新增一个新 flow 时，不需要修改 `settings-schema` 核心结构。
- 新增一个新 flow 时，不需要修改 `runtime-state` 核心结构。
- 新增一个新 flow 时，不需要在 sidepanel 主逻辑中增加 flow 名称判断分支。
- 新增一个新 flow 时，不需要在 `source-registry` core 里写新 host 判断。
- OpenAI 与 Kiro 都已经迁入统一命名体系。
- `background.js`、`background/message-router.js`、`sidepanel/sidepanel.js` 的正常运行路径不再读写 `panelMode`、`openaiIntegrationTargetId`、`kiroTargetId`、`kiroRuntime`。
- 旧配置文件不能直接运行，只能通过导入转换器进入新结构。
- 旧运行态快照不再支持恢复。
- 历史旧字段只允许存在于 `imports/legacy/` 及其测试中。

## 15. 非目标

本方案当前不解决：

- 新增具体第三个 flow 的业务实现
- OpenAI 私有流程本身的业务优化
- Kiro 私有流程本身的业务优化
- 所有公共工具立即物理迁移到 `core/` 目录
- 旧配置的自动无感兼容启动
- 旧运行态快照的兼容恢复

本方案只解决“以后再加 flow 时，不要再从根上出结构问题”。

## 16. 最终结论

这次重构必须被当成一次“彻底替换式升级”，不是普通功能开发。

如果继续在现有 `openai + kiro` 双轨基础上补第三个 flow，后续仍会再次进入：

- core 继续膨胀
- 命名继续污染
- 兼容层继续叠加
- 每次改动都更累

因此本次必须一次性完成：

- 统一 contract
- 统一命名
- 统一目录边界
- 删除长期双轨
- 取消旧配置运行时兼容
- 只保留单向导入转换器

完成后，后续 flow 才能真正变成“新增模块”，而不是“继续改核心”；旧世界也只能通过导入器进入新世界，而不能再反向定义新系统的结构。