# HeiCode 产品化沉淀文档

> 这份文档把"为什么这么改、改了什么、还差什么"沉淀下来，**作为后续开发与平台对接的唯一权威**。

---

## 一、产品定位

**HeiCode = 开箱即用的 Claude Code**，用户登录平台账号后直接用，不接触 API Key。

| 维度 | 设计 |
|---|---|
| 用户 | 个人开发者 |
| 形态 | Claude Code 桌面客户端 + CLI |
| 模型来源 | TaijiAICloud（自建网关，基于 heicode） + ClawdRouter（聚合网关） |
| 计费 | 完全在平台侧（不在 HeiCode 内做任何计费） |
| 中台 | **不需要**。客户端 → 平台直连。|
| 私有化 | **不做**。HeiCode 只对外销售客户端，平台是你公司运营的 SaaS。|

---

## 二、用户登录流程（最终形态）

```
启动 HeiCode
   ↓
看到登录页（仅 2 个入口，无第三选项）：
   ┌───────────────────────┐  ┌──────────────────────┐
   │ TaijiAICloud          │  │ ClawdRouter          │
   │ • 浏览器跳转 OAuth    │  │ • 浏览器跳转 OAuth   │
   │ • 粘贴 API Key        │  │ • 粘贴 API Key       │
   └───────────────────────┘  └──────────────────────┘
   ↓
登录成功
   ↓
HeiCode 自动 /v1/models 拉模型列表 → 注入 ANTHROPIC_DEFAULT_*_MODEL
   ↓
正常使用 Claude Code TUI / 桌面端
```

---

## 三、已完成（S0 阶段）

### 1. 品牌剥离
- [x] `package.json` `name` → `heicode` (`bin: heicode + claude-haha 兼容)
- [x] `bin/heicode` 新可执行入口；`bin/claude-haha` 改为兼容 shim
- [x] `desktop/package.json` `name` → `heicode-desktop`
- [x] `desktop/src-tauri/Cargo.toml` `name` → `heicode-desktop`，`lib.name` → `heicode_desktop_lib`
- [x] `desktop/src-tauri/src/main.rs` 调用更新
- [x] `desktop/src-tauri/tauri.conf.json` `productName: HeiCode`，`identifier: com.heicode.desktop`，updater endpoint 清空（避免误连上游 release）
- [x] `desktop/src-tauri/tauri.macos.conf.json` / `tauri.windows.conf.json` 窗口标题改为 HeiCode
- [x] `desktop/src-tauri/windows-installer-hooks.nsh` 卸载钩子兼容 `heicode-desktop.exe`

### 2. Provider 预设重构
- [x] `src/server/config/providerPresets.json` **仅保留**：
  - `official`（保留为内部占位，使原 `activateOfficial()` 调用不破）
  - `taijiaicloud`（featured）
  - `clawdrouter`（featured）
- 第三方厂商预设（DeepSeek / Kimi / MiniMax 等）全部移除。

### 3. 模型自动发现
- [x] `ProviderService.fetchProviderModels()`：
  - 优先 `GET <baseUrl>/v1/models`
  - 兼容 `GET <baseUrl>/models`
  - 同时带 `Authorization: Bearer` 和 `x-api-key`，兼容两种平台
  - 智能解析 `data` / `models` / 数组三种返回结构
- [x] `GET /api/providers/:id/models` — 已保存的 Provider 拉模型
- [x] `POST /api/providers/models` — 临时 baseUrl + apiKey 拉模型（登录前用）

### 4. 双 Provider 登录后端
- [x] 新建 `src/server/api/heicode-auth.ts`，路由挂在 `/api/heicode-auth/*`
- [x] `GET /api/heicode-auth/providers` — 列 2 个登录入口（含 OAuth 启用状态）
- [x] `POST /api/heicode-auth/login` — 粘贴 API Key 登录：校验 → 拉模型 → 保存 → 激活
- [x] `GET /api/heicode-auth/status` — 当前登录态
- [x] `POST /api/heicode-auth/logout` — 登出
- [x] `POST /api/heicode-auth/oauth/start` — OAuth 启动（**占位**）
- [x] `GET /api/heicode-auth/oauth/callback` — OAuth 回跳（**占位**）

### 5. 文档
- [x] 根 `README.md` 重写为 HeiCode 中文版
- [x] 本文件（`docs/HEICODE-PLAN.md`）

---

## 四、待完成

### S1 阶段（前端 UI 层）

#### 桌面端
- [ ] 替换现有 `desktop/src/pages/Settings.tsx` 的 Provider 区域为「双卡片登录」UI
- [ ] 卡片内：① 浏览器登录按钮（disabled 直到 OAuth 就绪） ② 粘贴 API Key 表单（直接调 `/api/heicode-auth/login`）
- [ ] 登录成功后：自动跳到模型选择页 → 调 `GET /api/providers/:id/models` 渲染下拉
- [ ] 顶部状态栏显示当前 Provider + 模型 + （未来）配额

#### CLI（Ink TUI）
- [ ] 替换 `src/components/Onboarding.tsx` 中的 OAuth 步骤为 HeiCode 登录
- [ ] 把 `ConsoleOAuthFlow` 替换为 `HeicodeProviderPicker` 组件（双卡片）
- [ ] `src/commands/login/login.tsx` 同步替换

> ⚠️ CLI 部分的限制：当前 `src/main.tsx` 是上游 805KB 预构建包，这块 UI 改动需要从源头改并重新走 build pipeline。**第一阶段建议把 CLI 的 onboarding 标记成"先用 desktop 完成登录，CLI 自动读取已登录态"**，等真正打 release 时再把 CLI UI 重 build。

### S2 阶段（OAuth 真实接入）

等 TaijiAICloud / ClawdRouter 平台开放 OAuth 端点后，把 `handleOAuthStart` / `handleOAuthCallback` 占位实装：

需要平台提供（OAuth2 Authorization Code + PKCE）：
1. **Authorize endpoint**：`GET <platform>/oauth/authorize?response_type=code&client_id=heicode-desktop&redirect_uri=...&code_challenge=...&state=...&scope=models:read,messages:write`
2. **Token endpoint**：`POST <platform>/oauth/token` 接受 `grant_type=authorization_code&code=...&code_verifier=...&client_id=...`
3. **(可选) Refresh endpoint**：`grant_type=refresh_token`
4. **Redirect URI 白名单**：允许 `http://127.0.0.1:<port>/api/heicode-auth/oauth/callback?providerId=<id>` 中的 127.0.0.1 任意端口（参考 Claude Code / GitHub CLI 做法）

实装位置：`src/server/api/heicode-auth.ts` 中的 `handleOAuthStart` / `handleOAuthCallback`，可以参考已存在的 `src/server/services/hahaOAuthService.ts`（Claude.ai OAuth 实现）抽取通用逻辑。

### S3 阶段（差异化）

- [ ] **配额状态栏**：拉平台 `/v1/usage` 或 heicode `/api/quota/`
- [ ] **多模型快捷切换**：顶部下拉选模型（已具备 `/api/providers/:id/models`）
- [ ] **Taiji Agent 工具融合**：通过 MCP 把 Taiji Agent 的工具挂载进 HeiCode

---

## 五、给 TaijiAICloud / ClawdRouter 的对接 SOW

### TaijiAICloud（基于 heicode）

| # | 资产 / 接口 | 状态 | 说明 |
|---|---|---|---|
| 1 | `/v1/messages` Anthropic 原生协议 | **必须确认** | heicode 配置项: 启用 Claude Messages 转发 |
| 2 | `/v1/models` | 应已就绪 | heicode 默认提供 |
| 3 | OAuth2 Authorization Code + PKCE | **待开发** | 见 S2 阶段 |
| 4 | 子 Token 管理（限定 model 白名单 / 每日额度 / 过期） | heicode 自带 | 平台直接复用 |
| 5 | 调用日志 / 审计（≥180天） | heicode 自带 | `/api/log/` |
| 6 | (可选) Webhook 额度告警 | 待开发 | heicode 原生没有 |

### ClawdRouter

| # | 资产 / 接口 | 状态 | 说明 |
|---|---|---|---|
| 1 | `/v1/messages` Anthropic 原生协议 | ✅ | [文档](https://www.clawdrouter.com/docs/) |
| 2 | `/v1/chat/completions` OpenAI 协议 | ✅ | 同上 |
| 3 | `/v1/models` | **待确认** | 文档未明示，需要平台确认或补 |
| 4 | OAuth2 端点 | **待开发** | 见 S2 阶段 |
| 5 | 管理面 API（创建/吊销子 Key、用量查询） | 待开发 | 用于 HeiCode 自动颁发 token |
| 6 | `Request-Id` 自定义头 | ✅ | HeiCode 调用时带 `Request-Id: <user>:<session>:<uuid>` 做归属审计 |

---

## 六、目录与命令速查

```
# 启动桌面端联调
cd cc-haha
bun install
SERVER_PORT=3456 bun run src/server/index.ts &
cd desktop && bun run dev --host 127.0.0.1 --port 2024

# 测登录后端 (粘贴 token 模式)
curl -X POST http://127.0.0.1:3456/api/heicode-auth/login \
  -H 'Content-Type: application/json' \
  -d '{"providerId":"taijiaicloud","apiKey":"sk-xxx"}'

curl http://127.0.0.1:3456/api/heicode-auth/status
```

---

## 七、变更清单（git 友好）

```
新增:
  src/server/api/heicode-auth.ts        ← 双 Provider 登录后端
  bin/heicode                          ← 新 CLI 入口
  README.md                            ← 完全重写
  docs/HEICODE-PLAN.md                 ← 本文件

修改:
  package.json                         ← name: heicode
  bin/claude-haha                      ← 改为兼容 shim
  src/server/api/providers.ts          ← 加 /models 端点
  src/server/services/providerService.ts ← 加 fetchProviderModels
  src/server/router.ts                 ← 注册 heicode-auth 路由
  src/server/config/providerPresets.json ← 重写为 2 个 preset
  desktop/package.json                 ← name: heicode-desktop
  desktop/src-tauri/Cargo.toml         ← name + lib.name
  desktop/src-tauri/src/main.rs        ← lib 名同步
  desktop/src-tauri/tauri.conf.json    ← productName + identifier + updater 清空
  desktop/src-tauri/tauri.macos.conf.json   ← 窗口标题
  desktop/src-tauri/tauri.windows.conf.json ← 窗口标题
  desktop/src-tauri/windows-installer-hooks.nsh ← 进程名兼容
```