# Heicode 全栈完整调用流程图

**版本**: v1.0
**生效日期**: 2026-05-05
**目标**: 把 Heicode 整体架构里 5 个组件之间的真实调用关系画清楚，避免每次新功能上线时大家对边界理解不一致。

> 本文档是基于实际代码（heicode 仓库 + mcp-server 仓库）的核实结果，**不是设计文档**。

---

## 1. 5 个组件 + 各自定位

| 组件 | 物理形态 | 角色（按 Heicode 主线文档） | 对应代码 |
|---|---|---|---|
| **cc-haha 桌面客户端** | Tauri 桌面应用 + Bun CLI | "Heicode 客户端"（用户编程入口） | `heicode/cc-haha/` |
| **heicode web/default** | React + Rsbuild SPA | NewAPI 自带的管理 UI（普通用户进的那个） | `heicode/heicode/web/default/` |
| **heicode 后端 (Go)** | Gin + GORM | **NewAPI** —— 模型网关 + 计费 + 用户/Token/Group | `heicode/heicode/` |
| **mcp-server** | FastAPI (Python) | **Manager** —— 用户控制台 + 编排中枢 + 资源绑定 | `services/mcp-server/` |
| **agent-manager** | (待实现 12 接口) | **Agnet 平台** —— K8s 上跑子 Agent | 独立服务 |

---

## 2. 已上线的调用关系（已核实）

### 2.1 登录流程（已上线 + 实测通过）

```
┌─────────────────────────┐
│  heicode web/default    │ ← 用户在浏览器打开 https://heicode.../
│  (React SPA)            │
└──────────┬──────────────┘
           │
           │ 1. POST /api/auth/login {email, password, role:"user"}
           │    跨域调用，VITE_HEICODE_AUTH_BASE_URL=https://apimtaiji.azure-api.net/api/mcp
           ▼
┌──────────────────────────────────┐
│  mcp-server (Manager)            │
│  https://apimtaiji.azure-api.net │
│  /api/mcp                        │
└──────────┬───────────────────────┘
           │
           │ 2. 200 → {token, refreshToken, user{id, email, name, role, channelId}}
           ▼
┌─────────────────────────┐
│  heicode web/default    │
│  存 access/refresh 到   │
│  localStorage           │
└──────────┬──────────────┘
           │
           │ 3. POST /api/user/session/from-agnet {access_token, refresh_token}
           │    同源调用 heicode 后端
           ▼
┌──────────────────────────────────┐
│  heicode 后端 (Go / NewAPI)      │
│  controller.HeicodeAgnetSession  │
│  Login                           │
└──────────┬───────────────────────┘
           │
           │ 4. GET /api/auth/me  (Bearer access_token)
           │    跨服务调用 mcp-server
           ▼
┌──────────────────────────────────┐
│  mcp-server                      │
│  (401 时 heicode 后端会 fallback │
│   先调 /api/auth/refresh)        │
└──────────┬───────────────────────┘
           │
           │ 5. 200 → {id, email, name, role, channelId, status}
           ▼
┌──────────────────────────────────┐
│  heicode 后端                    │
│  - 按 email JIT 创建本地 user    │
│  - channelId → User.Group        │
│  - role 用本地白名单决定（不信任 │
│    mcp-server 的 role 字段）     │
│  - 颁发 heicode session cookie   │
└──────────┬───────────────────────┘
           │
           │ 6. 200 → {success, data{id, role, group, ...}}
           │    + Set-Cookie: heicode_session=...
           ▼
┌─────────────────────────┐
│  heicode web/default    │
│  显示已登录              │
└─────────────────────────┘
```

**关键事实**：
- heicode 前端**直接跨域**调 mcp-server 的登录接口（4 个：login/me/refresh/logout）
- heicode 后端**也调** mcp-server 的 `/me` 和 `/refresh`（用前端给的 token 验证）
- mcp-server 是**事实上的主认证源**，heicode 不维护自己独立的密码体系
- heicode 后端**不信任** mcp-server 的 role 字段（防止外部身份提升），高权限角色由本地 `HEICODE_ROOT_EMAILS`/`HEICODE_ADMIN_EMAILS` 环境变量决定

### 2.2 cc-haha 桌面客户端是否调 mcp-server？

**结论：当前不直接调**（已通过 grep 核实）。

cc-haha (`./bin/claude-haha`) 是独立的 CLI + Tauri 桌面工具，主要功能是 AI 编程辅助。它通过本地 server (`SERVER_PORT=3456 bun run src/server/index.ts`) 工作，**不直接对接 mcp-server**。

后续如果 cc-haha 要接入 Heicode 主流程（用户绑定资源 → 部署子 Agent），它会通过 heicode 后端中转，与 web/default 前端走同样的登录路径。

### 2.3 heicode 后端 → mcp-server 的依赖

代码位置：`controller/heicode_agnet_session.go`

| heicode 调用 | mcp-server 端点 | 用途 | mcp-server 端能改吗？ |
|---|---|---|---|
| `GET /api/auth/me` | ✅ 已上线 | JIT 同步用户身份 | **字段形态不能改**：id/email/name/role/channelId/status 都被 hardcode 解析 |
| `POST /api/auth/refresh` | ✅ 已上线 | access token 401 时 fallback | 字段形态不能改：data.token/refreshToken |

### 2.4 heicode 前端 → mcp-server 的依赖

代码位置：`web/default/src/features/auth/api.ts`

| heicode 前端调用 | mcp-server 端点 | 用途 |
|---|---|---|
| `POST /api/auth/login` | ✅ 已上线 | 用户登录 |
| `GET /api/auth/me` | ✅ 已上线 | 启动时校验 + 周期刷新 |
| `POST /api/auth/refresh` | ✅ 已上线 | access token 失效续期 |
| `POST /api/auth/logout` | ✅ 已上线 | 登出（与 heicode 后端 logout 双调用） |

### 2.5 mcp-server → heicode 后端的依赖（**当前 0 调用**）

mcp-server 现在**不调 heicode 后端**。

> **Heicode 团队 2026-05-07 修订（C 方案——两平台并存且各自有 product-level 模型网关）**：
>
> | 平台 | 组成 | 自家模型网关 | 服务对象 |
> |---|---|---|---|
> | **taijiagent** | mcp-server + agent-manager + LiteLLM | **LiteLLM**（产品级，不是 mcp-server 进程内细节）| 通过 mcp-server 直接部署 agent 的"原生 taijiagent 用户" |
> | **Heicode** | Heicode 客户端（桌面）+ heicode web（浏览器）+ heicode 后端（NewAPI）| **NewAPI**（产品级）| Heicode 客户端实时交互式 chat 用户 |
>
> 两个平台**共用 mcp-server 的账号体系**，**模型网关各自独立**。
>
> **四条独立的模型调用路径**（完整真实场景）：
>
> | # | 调用方 | 触发场景 | 走哪 |
> |---|---|---|---|
> | 1 | Heicode 客户端（桌面）+ heicode web 前端 | 用户实时交互式 chat / 写代码 | **Heicode NewAPI** |
> | 2 | 子 Agent Pod（**Heicode 用户部署的**） | 在 AKS 跑任务时调模型，`billing_context.provider="newapi"` | **Heicode NewAPI**（带 newapi_user_ref / newapi_group） |
> | 3 | 子 Agent Pod（**原生 taijiagent 用户部署的**） | 在 AKS 跑任务时调模型，`billing_context.provider` 默认或 = `"litellm"` | **taijiagent LiteLLM** |
> | 4 | mcp-server 进程内（embedding / 内部分类 / 系统功能） | mcp-server 自己内部使用 | **LiteLLM** |
>
> **关键事实**：
> - LiteLLM 同时承担两种角色 —— ① taijiagent 用户的 agent 模型网关（产品级）+ ② mcp-server 自己的内部工具
> - NewAPI 同时承担两种角色 —— ① Heicode 客户端用户的实时交互网关 + ② Heicode 部署的 agent 计费网关
> - 子 Agent 走哪条网关由 `billing_context.provider` 字段决定（mcp-server 在 `POST /api/agnet/deployments` payload 里设置）
> - 两个网关**互不替代**，**P4 不需要做迁移**
>
> **P4 NewAPI 解耦的真实任务**：mcp-server 在 Manager 控制台聚合费用展示时，对**Heicode 用户那部分**调用（路径 1 + 路径 2）从 NewAPI 拉元数据；对**纯 taijiagent 用户**那部分（路径 3）继续用自己的 LiteLLM 数据。聚合后展示给用户。属于**只读元数据查询 + 前端聚合**，不涉及网关迁移。

如果实施 P4 元数据查询，需要：
- mcp-server 新增 `app/heicode_client.py` 出站客户端
- 调 heicode 后端的用户视角 API（`/api/user/self`、`/api/user/self/models`、`/api/log/self/stat` 等）
- LiteLLM **保留**，不替换

---

## 3. 待实现的调用关系（按 Heicode 主线 P5）

### 3.1 部署子 Agent 流程（设计中，agent-manager 待实现 12 接口）

```
┌─────────────────────────┐
│ heicode web/default 或   │
│ cc-haha 客户端           │ ← 用户点"部署"
└──────────┬──────────────┘
           │
           │ 1. (经 heicode 后端中转 或 直接) POST /api/resources / /api/resource-grants
           │    定义资源绑定与授权
           ▼
┌──────────────────────────────────┐
│  mcp-server (Manager)            │
│  ✅ ResourceBinding/Grant 已上线 │
└──────────┬───────────────────────┘
           │
           │ 2. POST /api/agnet/deployments
           │    {orchestration_plan, user_context, billing_context, agent_runtime, resource_grants}
           │    ❌ 出站客户端待实现
           ▼
┌──────────────────────────────────┐
│  agent-manager (Agnet 平台)      │
│  ❌ 12 个新接口全部待实现         │
└──────────┬───────────────────────┘
           │
           │ 3. 创建 K8s Deployment + ServiceAccount + ConfigMap
           │    ConfigMap 含 AGENT.md / resource_context / permission_manifest
           │    ❌ Pod 启动行为待改造
           ▼
┌──────────────────────────────────┐
│  子 Agent Pod (在 AKS)           │
│  ❌ 启动后通过 Workload Identity │
│     向 Vault 拉短期凭据           │
└──────────┬───────────────────────┘
           │
           │ 4. (运行时) 调 Vault 拿 git token / cloud key
           │    ❌ Vault 部署 + Workload Identity 配置待做
           ▼
┌──────────────────────────────────┐
│  Vault / OpenBao                 │
│  ❌ 基础设施待部署                │
└──────────────────────────────────┘
```

### 3.2 子 Agent 模型调用（已工作 + 待对齐）

```
子 Agent 在 Pod 里跑
       │
       │ POST /v1/chat/completions
       │ Authorization: Bearer <heicode-token>
       ▼
heicode 后端 (NewAPI)
       │
       │ 路由到具体 provider
       ▼
OpenAI / Claude / Gemini / Azure / Bedrock / ...
```

注：子 Agent 拿到的 heicode token 由 mcp-server 在创建 Deployment 时通过 `billing_context` 传给 agent-manager，agent-manager 注入 Pod env。**现在还没这个链路**。

---

## 4. mcp-server 角色总结

mcp-server 在 Heicode 全栈里**目前**承担 3 件事：

| 角色 | 状态 | 接口 |
|---|---|---|
| **认证 IdP**（heicode 前端 + 后端的统一身份源） | ✅ 已上线 | `/api/auth/login` `/me` `/refresh` `/logout` |
| **资源绑定与授权**（用户绑定 Git/SK/云资源/项目文档；分配给子 Agent 角色）| ✅ 已上线 | `/api/resources/*` `/api/resource-grants/*` |
| **Agnet 平台编排器**（创建/查询/停止子 Agent 部署，转发给 agent-manager）| ❌ 待实现 | `/api/agnet/*`（12 个） |

mcp-server **不**承担：
- ❌ 模型调用网关（heicode 后端 = NewAPI 干这事）
- ❌ AI 提供商接入（heicode 后端的 relay/channel 干这事）
- ❌ K8s 部署执行（agent-manager 干这事）
- ❌ 凭据托管（Vault 干这事，待部署）

---

## 5. 现有 mcp-server 业务（不归 Heicode，但要知道避坑）

mcp-server 还服务 **taiji 业务**：渠道后台、超管、用户中心、Agent 管理、PayPal 充值。这些不在 Heicode 范围，但代码共用。

| taiji 业务路由 | 状态 | 与 Heicode 的关系 |
|---|---|---|
| `/api/channel/*` 渠道后台 | 在用 | 不归 Heicode，**保持不动** |
| `/api/admin/*` 超管 | 在用 | 同上 |
| `/api/user/*` 用户中心 | 在用 | 同上 |
| `/api/agents/*` Agent 管理 | 在用 | 同上 |
| `/api/auth/*` 登录 | 在用 + Heicode 复用 | **被 Heicode 共用**，字段形态绝不能改 |
| `/api/billing/*` `/api/paypal/*` 计费 | 在用 | 不归 Heicode |

---

## 6. CORS 现状与改进

**生产配置**：mcp-server 的 `cors_origins` 在 ConfigMap `taiji-config` 里**未设置**，fallback 到 `["*"]`。

**潜在问题**：
- mcp-server 设了 `allow_credentials=True` + `allow_origins=["*"]`，浏览器规范上**会拒绝**带 cookie 的跨域请求
- 但 heicode 前端用 `Authorization: Bearer` 传 token，**不依赖 cookie**，实际可用

**改进建议**（不阻塞当前对接）：
- 把 heicode 前端的真实部署域名加到 `CORS_ORIGINS`，去掉 `*`
- 例如：`CORS_ORIGINS=["https://heicode.xinghanlab.com","https://heicode-staging.xinghanlab.com"]`
- 与 heicode 团队确认其前端实际部署域名后配置

---

## 7. 已知技术债（**不阻塞**当前对接）

| 项 | 说明 | 影响 |
|---|---|---|
| Channel 登录写审计日志 FK 错 | `audit_logs.user_id` FK 与 channel.id 不匹配 | 仅 channel 角色登录有 warning，user 角色无影响 |
| `cors_origins=["*"]` + `allow_credentials=True` | 与浏览器规范冲突 | 当前无影响（heicode 用 Bearer），未来要硬化 |
| LiteLLM vs NewAPI（heicode 后端）双轨 | 模型调用走 LiteLLM，未对接 heicode | 取决于产品决策，可能要迁移 |
| 死路由清理（之前已删 11 个）| `frontend_integration.py` 仍有部分历史代码 | 不影响功能 |

---

## 8. 联调测试可执行步骤

### 步骤 1: 确认 mcp-server 4 个登录接口（已上线，无需操作）

```bash
# 用真实账号登录
curl -X POST https://apimtaiji.azure-api.net/api/mcp/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"55@55.com","password":"By@123456.","role":"user"}'

# 拿 token 调 /me
curl https://apimtaiji.azure-api.net/api/mcp/api/auth/me \
  -H "Authorization: Bearer <access_token>"
```

### 步骤 2: heicode 前端联调（heicode 团队执行）

1. 部署 heicode web/default，配置 `VITE_HEICODE_AUTH_BASE_URL=https://apimtaiji.azure-api.net/api/mcp`
2. 在登录页输入 `55@55.com` / `By@123456.`
3. 预期：成功登录，浏览器 localStorage 有 `heicode_access_token` + `heicode_refresh_token`
4. 预期：heicode 后端 session cookie 也已颁发（通过 `from-agnet` 流程）

### 步骤 3: 资源绑定联调（heicode 团队执行）

1. 用步骤 2 的 access token 调 `POST /api/resources` 创建 git 绑定
2. 调 `POST /api/resource-grants` 把 binding 授给 backend role
3. 预期：所有调用 200，DB 里有对应记录

### 步骤 4: 子 Agent 部署联调（**等 agent-manager 实现 12 接口后**）

待 agent-manager 团队实现接口后再做。

---

## 9. 文档导航

| 文档 | 受众 | 内容 |
|---|---|---|
| **本文档** | 全员 | 整体调用关系、组件定位 |
| `Docs/Heicode-接口契约文档.md` | heicode 前后端开发 | 13 个 mcp-server 已上线接口的详细契约 |
| `Docs/Heicode-对接进度与待办.md` | PM / Lead | 进度盘点 + 待决策 |
| `Docs/Agent-Manager-Heicode对接需求文档.md` | agent-manager 团队 | 12 个新接口要求 + Pod 改造 + AKS 基础设施 |
| `Docs/Heicode-登录接口对接文档.md` | （旧版，已被超集化）| 登录单接口；建议转看接口契约文档 |

---

## 10. 修订记录

| 版本 | 日期 | 变更 |
|---|---|---|
| v1.0 | 2026-05-05 | 初版：基于代码核实结果绘制 |