gongzhiyong
1f21309597
Remove user-facing new-api naming; Docker/network/container names use heicode. Go imports updated; Dockerfiles and workflows ldflags fixed. Made-with: Cursor
192 lines
8.8 KiB
Markdown
192 lines
8.8 KiB
Markdown
# 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 ← 进程名兼容
|
||
```
|