heicode/docs/HEICODE-PLAN.md

HeiCode 产品化沉淀文档

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

---

一、产品定位

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

维度	设计
用户	个人开发者
形态	Claude Code 桌面客户端 + CLI
模型来源	TaijiAICloud（自建网关，基于 new-api） + 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. 品牌剥离

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

2. Provider 预设重构

• src/server/config/providerPresets.json 仅保留：
  • official（保留为内部占位，使原 activateOfficial() 调用不破）
  • taijiaicloud（featured）
  • clawdrouter（featured）
• 第三方厂商预设（DeepSeek / Kimi / MiniMax 等）全部移除。

3. 模型自动发现

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

4. 双 Provider 登录后端

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

5. 文档

• 根 README.md 重写为 HeiCode 中文版
• 本文件（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 或 new-api /api/quota/
• 多模型快捷切换：顶部下拉选模型（已具备 /api/providers/:id/models）
• Taiji Agent 工具融合：通过 MCP 把 Taiji Agent 的工具挂载进 HeiCode

---

五、给 TaijiAICloud / ClawdRouter 的对接 SOW

TaijiAICloud（基于 new-api）

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

ClawdRouter

#	资产 / 接口	状态	说明
1	/v1/messages Anthropic 原生协议	✅	文档
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 ← 进程名兼容