168 lines
6.6 KiB
Markdown
168 lines
6.6 KiB
Markdown
# Heicode 架构与关键数据流
|
||
|
||
本文用 mermaid 图示统一表达 **Heicode 客户端 / Manager / Agnet / NewAPI / Secret Store** 之间的边界与数据流，作为愿景与 SaaS 架构计划的视觉补充。
|
||
|
||
> 与文字版的对应关系：[`vision-heicode-full-stack-agentic-dev.md`](./vision-heicode-full-stack-agentic-dev.md)、[`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md)。旧 Agnet API 草案若与新架构计划冲突，以新架构计划为准。
|
||
|
||
---
|
||
|
||
## 一、概念分层（鸟瞰）
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
entry["人机入口<br/>官网 · 控制台 · CLI · Desktop"]
|
||
manager["Heicode Manager<br/>SaaS 控制台"]
|
||
client["Heicode 客户端<br/>(cc-haha)"]
|
||
agnet["Agnet 平台<br/>AKS 执行与状态"]
|
||
newapi["NewAPI<br/>模型网关 · 余额 · 日志"]
|
||
secret["Secret Store<br/>Vault / Infisical / Key Vault"]
|
||
assets["资产与环境<br/>仓库 · 流水线 · 运行时"]
|
||
|
||
entry --> manager
|
||
entry --> client
|
||
manager <--> client
|
||
manager --> agnet
|
||
manager --> newapi
|
||
manager --> secret
|
||
agnet --> secret
|
||
client -. "会话子 agent 输出" .- agnet
|
||
agnet --> assets
|
||
manager --> assets
|
||
```
|
||
|
||
要点：
|
||
- **Manager 是 SaaS 用户、租户、资源、权限与部署控制台**
|
||
- **NewAPI 是独立模型服务**，普通用户不进入 NewAPI 后台
|
||
- **Secret Store 保存真实密钥**，Manager DB 只保存 `secret_ref`
|
||
- **Agnet 在 AKS 上执行**，按 Manager 下发的 Resource Grant 和运行身份使用资源
|
||
|
||
---
|
||
|
||
## 二、HeiCode 客户端 ↔ Manager ↔ Agnet 主链路
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
user["开发者"]
|
||
desktop["Heicode 客户端<br/>(Desktop / CLI + 本地服务)"]
|
||
manager["Heicode Manager"]
|
||
agnet["Agnet 平台"]
|
||
|
||
user --> desktop
|
||
desktop -->|"OAuth: /heicode/oauth/*"| manager
|
||
desktop -->|"Anthropic Messages /<br/>OpenAI Chat 调用"| manager
|
||
newapi["NewAPI<br/>模型网关 / 额度 / 调用日志"]
|
||
secret["Secret Store<br/>Vault / Infisical / Key Vault"]
|
||
|
||
manager -->|"模型、余额、调用日志"| newapi
|
||
manager -->|"资源绑定 / secret_ref"| secret
|
||
manager -->|"M2M JWT · 部署/查询编队"| agnet
|
||
agnet -->|"运行时受控读取密钥"| secret
|
||
agnet -->|"webhook / events"| manager
|
||
agnet -.->|"sub_agent.output (SSE/WS)"| desktop
|
||
```
|
||
|
||
关键边界：
|
||
- 客户端 **不直连** 模型供应商，模型能力经 Manager / NewAPI 提供
|
||
- Manager 用 **服务账号 / 用户委派令牌** 调 Agnet
|
||
- 密钥不进入 Git、Markdown、前端或日志；子 Agnet 只通过受控身份使用被授权资源
|
||
|
||
---
|
||
|
||
## 三、资源绑定与凭证托管
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
user["用户"]
|
||
manager["Heicode Manager"]
|
||
registry["Resource Registry<br/>资源元数据与授权"]
|
||
broker["Secret Broker"]
|
||
store["Secret Store<br/>Vault / Infisical / Key Vault"]
|
||
agnet["Agnet 平台"]
|
||
pod["子 Agnet Pod<br/>AKS ServiceAccount"]
|
||
|
||
user -->|"OAuth / GitHub App / 云授权"| manager
|
||
manager --> registry
|
||
manager --> broker
|
||
broker -->|"写入真实凭证"| store
|
||
manager -->|"Resource Grant / permission manifest"| agnet
|
||
agnet -->|"创建运行身份 / policy"| pod
|
||
pod -->|"按最小权限读取短期凭证"| store
|
||
```
|
||
|
||
要点：
|
||
- 用户完成授权，平台负责托管、轮换、撤销和审计
|
||
- Manager DB 保存资源元数据、授权关系和 `secret_ref`
|
||
- Secret Broker 是唯一写入真实凭证的后端边界
|
||
- 子 Agnet 不保存长期密钥
|
||
|
||
---
|
||
|
||
## 四、SK 数据流（Git / Upload → 快照 → 子 agent 注入）
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
authoring["SK 编辑入口<br/>仅 Heicode 客户端"]
|
||
git["Git 仓库<br/>(SK 事实源)"]
|
||
upload["上传制品<br/>(对象存储 / artifact_id)"]
|
||
manager["Heicode Manager<br/>展开 sk_sources 与刷新策略"]
|
||
agnet["Agnet 平台"]
|
||
snapshot["不可变快照<br/>commit_sha · artifact 版本"]
|
||
subAgent["Agnet 子 agent<br/>(运行时只读)"]
|
||
|
||
authoring -->|"git push"| git
|
||
authoring -->|"上传 / 替换"| upload
|
||
manager -->|"声明 sk_sources"| agnet
|
||
git -->|"fetch + checkout ref"| agnet
|
||
upload -->|"只读获取"| agnet
|
||
agnet --> snapshot
|
||
snapshot -->|"注入"| subAgent
|
||
```
|
||
|
||
要点：
|
||
- SK **写入路径单一**：经 Heicode 客户端到 Git，或经 Heicode 上传入口
|
||
- Agnet 与 Manager **不得提供 SK 正文写 API**
|
||
- 运行注入仅使用解析出的 **不可变快照**，避免「执行中偷偷换版本」
|
||
|
||
详见 [`sk-lifecycle.md`](./sk-lifecycle.md)。
|
||
|
||
---
|
||
|
||
## 五、事件流双轨（平台运行态 vs 会话子代理输出）
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
agnet["Agnet 平台"]
|
||
manager["Heicode Manager<br/>控制台与 Dashboard"]
|
||
client["Heicode 客户端<br/>编码会话面板"]
|
||
|
||
agnet -->|"phase / health / metrics<br/>(SSE · WS · webhook)"| manager
|
||
agnet -->|"sub_agent.output<br/>(SSE · WS)"| client
|
||
```
|
||
|
||
两类事件 **同源端点可复用**，但 `event` / `type` 必须可区分：
|
||
- 面向 Manager 的：`deployment.*`、`instance.*`、`phase_changed`、`health_changed`
|
||
- 面向客户端的：`sub_agent.output`、`sub_agent.tool_result`、`output_delta`
|
||
|
||
---
|
||
|
||
## 六、模块关注点对照
|
||
|
||
| 关注点 | Heicode 客户端 (`cc-haha/`) | Heicode Manager (`heicode/`) | NewAPI | Agnet 平台 | Secret Store |
|
||
|--------|------------------------------|-------------------------------|--------|------------|--------------|
|
||
| 用户身份 | 浏览器登录 / API Key 兼容 | SaaS 登录、租户、项目、角色 | 后台服务身份 | 接收 M2M JWT 与委托令牌 | 接收服务身份 / K8s 身份 |
|
||
| 模型调用 | 不直连模型，请求经 Manager | 展示模型、余额、日志 | 模型网关、额度、调用日志 | 不参与基础模型调用 | 不参与 |
|
||
| 资源绑定 | 发起本地工作流 | Git / 云 / 文档 / SK 资源绑定与 Resource Grant | 不参与 | 接收授权后的运行引用 | 保存真实凭证 |
|
||
| 编排 | 触发部署、订阅子 agent 输出 | 一键部署入口、permission manifest、审计 | 不参与 | 实际执行编队、维护实例生命周期 | 按策略提供密钥 |
|
||
| SK | 主要编辑入口（写 Git / 上传） | 展开 `sk_sources`、刷新策略 | 不参与 | 拉取快照、运行时只读注入 | 可保存访问凭证 |
|
||
| 观测 | 会话内子 agent 输出 | 平台运行态聚合、NewAPI 调用日志 | 调用日志、余额 | 提供事件流、指标导出 | 提供密钥访问审计 |
|
||
|
||
---
|
||
|
||
## 六、相关代码索引
|
||
|
||
- 客户端登录：`cc-haha/src/server/api/heicode-auth.ts`
|
||
- 客户端 Provider 预设：`cc-haha/src/server/config/providerPresets.ts`
|
||
- Manager OAuth：`heicode/controller/heicode_oauth.go`、`heicode/router/heicode-router.go`
|
||
|
||
> 代码会演进，本文以 **架构关系** 为准；具体路径请以仓库当前实现为最终事实。
|