taiji-AI-PAD/Docs/Heicode-完整调用流程图.md

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 个登录接口（已上线，无需操作）

# 用真实账号登录
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	初版：基于代码核实结果绘制