# Kiro Flow 官方入口升级开发方案

## 1. 目标

本方案把 Kiro flow 作为独立系统升级，不再把它塞进 OpenAI flow 的注册假设里，也不再保留旧入口的兼容分支。

最终链路固定为：

1. 打开 Kiro 官方登录页 `https://app.kiro.dev/signin`
2. 在 Kiro 登录页选择 Builder ID
3. 完成 AWS Builder ID 注册页的邮箱、姓名、验证码、密码与授权确认
4. 等待回到 Kiro Web 登录完成页，建立 Kiro Web 登录态
5. 基于已有 Kiro Web / Builder ID 浏览器会话打开桌面端授权页
6. 监听 localhost callback，用授权码与 PKCE 换取桌面端 Builder ID 凭据
7. 将 `refreshToken / profileArn / clientId / clientSecret / machineId / email` 等字段上传到 `kiro.rs`

这条链路的核心判断是：能被 `kiro.rs` 稳定使用的不是注册页里某个临时结果，而是 Kiro 桌面端授权链路产生的 Builder ID 凭据。

## 2. 需求符合性分析

### 2.1 与用户要求的对应关系

- **两套 flow 分开**：Kiro flow 独立使用 `background/kiro/*`、`content/kiro/*`、`kiroRuntime` 和自己的 9 个节点，不复用 OpenAI 的页面、接码、Plus、平台绑定逻辑。
- **只抽公共能力**：Kiro 只复用邮箱服务、账户密码生成、IP 代理和 `kiro.rs` 目标配置；这些能力本身是跨 flow 基础设施，不带 OpenAI 业务语义。
- **来源与目标清晰**：Kiro 的目标固定为 `kiro-rs`；运行页面来源按 runtime source 识别，注册子链路覆盖 Kiro Web 与 Builder ID 注册页，桌面授权子链路只覆盖 Builder ID authorize 页。
- **上传到 `kiro.rs`**：上传器只按 `kiro.rs` 新增凭据接口构建 payload，并固定上传 BuilderId 的 Kiro runtime `profileArn`；不引入本地账号管理项目里的私有字段。
- **不考虑旧兼容**：设计中不保留旧字段别名、不保留旧入口回退、不保留“失败后换旧链路”的分支。

### 2.2 完整性分析

当前设计覆盖 Kiro 自动注册所需的完整闭环：

- UI 配置：Kiro flow、`kiro.rs URL`、`API Key`、共享邮箱、共享密码、共享代理。
- 注册页面：官方 Kiro 登录页、Builder ID 注册页、授权确认页、Kiro Web 登录完成页。
- 桌面授权：OIDC client 注册、PKCE、authorize URL、localhost callback、token exchange。
- 上传：`kiro.rs` baseUrl 归一化、API Key 鉴权、payload 构建、BuilderId profileArn 固定映射、machineId 计算、上传状态回写。
- 自动运行：Kiro 9 节点 linear workflow，执行范围、状态、日志、失败停止与轮次汇总走通用 runner，但节点实现完全属于 Kiro。
- 测试：覆盖状态模型、source 归属、注册页状态机、桌面授权 gate、上传器 payload、sidepanel flow 选择。

### 2.3 正确性分析

正确性边界如下：

- 步骤 1 不能直接打开 AWS 注册页；必须先进入 Kiro 官方登录页，并由页面选择 Builder ID 入口。
- 步骤 6 不能只以 AWS 授权页按钮点击成功作为完成；必须等待 Kiro Web 登录完成页，写入 `webAuth.status = signed_in`。
- 步骤 7 不能在注册页刚授权后盲目开始；必须检查 `register.status = completed` 且 `webAuth.status = signed_in`。
- 步骤 8 的 token 必须来自桌面端授权码与 PKCE 交换结果。
- 步骤 9 的上传 payload 必须与 `kiro.rs` Admin API 的新增凭据模型一致。

### 2.4 规范一致性分析

- Kiro 运行态统一放在 `kiroRuntime` 下，避免新增节点时继续向全局 state 平铺字段。
- Kiro 页面脚本放在 `content/kiro/*`，后台执行器放在 `background/kiro/*`。
- 注册子链路和桌面授权子链路用不同 runtime source，避免同域 AWS 页面被误注入到错误脚本。
- 文案与日志使用清晰中文；页面按钮文本仍保留真实网页上的中英文按钮名用于匹配。
- 持久配置走 `flows.kiro.targets["kiro-rs"]`，不再出现隐藏的 Kiro 区域、优先级、endpoint 等配置面。

## 3. 最终架构

### 3.1 运行态模型

```js
kiroRuntime: {
  session: {
    status,
    startedAt,
    completedAt,
    email
  },
  register: {
    status,
    loginUrl,
    tabId,
    email,
    currentPageState,
    completedAt
  },
  webAuth: {
    status,
    completedAt,
    hasAccessToken,
    hasSessionToken
  },
  desktopAuth: {
    status,
    state,
    redirectUri,
    clientId,
    clientSecret,
    refreshToken,
    accessToken,
    completedAt
  },
  upload: {
    status,
    targetId,
    baseUrl,
    credentialId,
    completedAt,
    error
  }
}
```

### 3.2 步骤定义

1. `kiro-open-register-page`：清理 Kiro / Builder ID cookies，打开 Kiro 官方登录页，选择 Builder ID，等待邮箱页。
2. `kiro-submit-email`：通过共享邮箱服务获取邮箱，提交到 Builder ID 注册页，等待姓名页。
3. `kiro-submit-name`：填写姓名并继续，等待验证码页。
4. `kiro-submit-verification-code`：按注册邮箱轮询验证码，填入并继续，等待密码页。
5. `kiro-submit-password`：填写共享账户密码或自动生成密码，等待授权确认页。
6. `kiro-complete-register-consent`：点击确认与允许访问，等待 Kiro Web 登录完成页。
7. `kiro-start-desktop-authorize`：在 Kiro Web 登录态已建立后创建桌面授权请求并打开授权页。
8. `kiro-complete-desktop-authorize`：确认桌面授权，捕获 localhost callback，交换 token。
9. `kiro-upload-credential`：上传桌面端 Builder ID 凭据到 `kiro.rs`。

### 3.3 Source 归属

- Kiro 注册 source：`app.kiro.dev`、`kiro.dev`、Builder ID 注册相关页面。
- Kiro 桌面授权 source：Builder ID authorize 页面。
- 邮箱 source：继续由共享邮箱 provider 注册表管理。
- 代理 source：继续由共享 IP 代理模块管理，不进入 Kiro 页面状态机。

### 3.4 `kiro.rs` 上传合同

上传字段固定为：

```js
{
  refreshToken,
  profileArn,
  clientId,
  clientSecret,
  region,
  authRegion,
  apiRegion,
  machineId,
  email,
  proxyUrl,
  proxyUsername,
  proxyPassword,
  authMethod: 'idc'
}
```

其中：

- `machineId = sha256("KotlinNativeAPI/" + refreshToken)`
- `region / authRegion / apiRegion` 使用 Kiro 默认固定值
- `profileArn` 使用 BuilderId 固定值 `arn:aws:codewhisperer:us-east-1:638616132270:profile/AAAACCCCXXXX`
- `proxy*` 仅在当前共享代理存在且可解析时上传

## 4. 设计自检

### 4.1 是否满足“不要和 OpenAI flow 扯上关系”

满足。Kiro 节点、页面脚本、运行态、上传器都在 Kiro 自己的模块内。共享邮箱、密码、代理属于基础服务，不包含 OpenAI 业务分支。

### 4.2 是否存在上下设计冲突

当前无直接冲突。需要注意的边界是：

- 通用 auto-run runner 仍负责调度所有 flow，但它只按节点执行器表调用 Kiro 节点，不理解 Kiro 内部字段。
- `source-registry` 是全局基础设施，但 Kiro 注册 source 与桌面授权 source 已分开，避免同域页面误判。
- `chrome.storage.local` 保存 Kiro 目标配置，`chrome.storage.session` 保存 Kiro 运行态；二者职责不冲突。

### 4.3 方案自身缺陷与规避

- **页面跳转期间 content script 断连**：统一使用页面恢复等待和较长加载预算，错误文案明确提示页面刚刷新或代理异常。
- **Kiro Web 登录完成但 cookie 名称变化**：运行态只保存登录态摘要，不把具体 cookie 当成后续协议输入；真正桌面授权仍以 authorize callback 与 token exchange 为准。
- **代理导致页面卡住**：Kiro flow 必须 fail-close 停止，让用户切换代理，不应自动进入下一步。
- **`kiro.rs` API Key 配置为空或未持久化**：侧栏字段必须走 settings schema 持久配置；上传前从当前配置读取并校验。
- **后续新增 Kiro 节点**：只扩展 Kiro step definitions、Kiro runner 和 Kiro runtime，不在 OpenAI flow 里加隐藏条件。

## 5. 开发清单

### 阶段 1：官方入口与 source 升级

开发内容：

- 步骤 1 打开 `https://app.kiro.dev/signin`
- content script 识别 Kiro 官方登录页并点击 Builder ID
- source registry 支持 Kiro Web 域名
- 删除旧入口启动逻辑

阶段自检：

- 搜索核心代码，不应存在旧入口启动函数与旧注册授权字段。
- 步骤 1 必须能从 Kiro 官方登录页进入 Builder ID 邮箱页。
- source 不得把桌面授权页误归为注册页，反之亦然。
- touched 文件中文不能乱码。

### 阶段 2：Kiro Web 登录态闭环

开发内容：

- 注册页状态机识别 Kiro Web 登录完成页。
- 步骤 6 等待 `kiro_web_signed_in`，不再只看授权按钮点击结果。
- `kiroRuntime.webAuth` 保存登录态摘要。

阶段自检：

- 步骤 6 未回到 Kiro Web 时不能标记成功。
- 成功后必须写入 `webAuth.status = signed_in`。
- 只保存布尔摘要，不保存敏感 cookie 值。
- 日志必须是中文且能说明正在等待 Kiro Web 登录态。

### 阶段 3：桌面授权前置 gate

开发内容：

- 步骤 7 检查 `register.completed + webAuth.signed_in`。
- 未完成 Kiro Web 登录态时直接停止并给出明确中文错误。
- 桌面授权 token 继续写入 `kiroRuntime.desktopAuth`。

阶段自检：

- 手动跳过前 6 步不能直接执行桌面授权。
- gate 不读取 OpenAI 状态。
- 上传器仍只读取桌面授权凭据，不读取注册页临时字段。

### 阶段 4：文档、全量测试与提交

开发内容：

- 更新项目完整链路说明。
- 更新项目文件结构说明。
- 更新本开发方案，确保文档与代码合同一致。
- 跑全量测试、diff 检查、提交。

阶段自检：

- 文档不再把 Kiro 描述为旧入口链路。
- `npm test` 通过。
- `git diff --check` 无空白错误。
- `git status` 只包含本次计划内文件。
- 最终提交信息清晰描述 Kiro 官方入口升级。

## 6. 最终审查清单

- Kiro flow 是否仍能上传到 `kiro.rs`。
- Kiro flow 是否没有复用 OpenAI 接码、Plus、贡献模式、平台绑定逻辑。
- Kiro 设置是否通过 `flows.kiro.targets["kiro-rs"]` 持久化。
- Kiro 自动运行是否不会跳回 OpenAI flow。
- Kiro 页面等待是否统一走足够的加载预算。
- Kiro 失败日志是否清晰中文。
- Kiro touched 文件是否无乱码。
- 测试是否覆盖入口、状态、source、桌面授权、上传器和 sidepanel。