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
4.8 KiB
4.8 KiB
Heicode 架构与关键数据流
本文用 mermaid 图示统一表达 Heicode 客户端 / Manager / Agnet 之间的边界与数据流，作为愿景与集成 API 设计的视觉补充。
与文字版的对应关系：
vision-heicode-full-stack-agentic-dev.md第五节、integration/agnet-platform-api-design.md§1.1 / §5 / §6 / §7。
一、概念分层（鸟瞰）
flowchart TD
entry["人机入口<br/>官网 · 控制台 · CLI · Desktop"]
manager["Heicode Manager<br/>(heicode)"]
client["Heicode 客户端<br/>(cc-haha)"]
agnet["Agnet 平台<br/>(角色模板 · 执行单元)"]
assets["资产与环境<br/>仓库 · 流水线 · 运行时"]
entry --> manager
entry --> client
manager <--> client
manager --> agnet
client -. "会话子 agent 输出" .- agnet
agnet --> assets
manager --> assets
要点：
- 同一身份与策略边界 跨越 Manager 与客户端
- 编排细节归 Agnet 内部；Heicode 关注 契约、体验与安全边界
- 资产层（仓库 / 流水线 / 运行时）是被动载体
二、HeiCode 客户端 ↔ Manager ↔ Agnet 主链路
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
manager -->|"模型路由 / 计费 / RBAC"| manager
manager -->|"M2M JWT · 部署/查询编队"| agnet
agnet -->|"webhook / events"| manager
agnet -.->|"sub_agent.output (SSE/WS)"| desktop
关键边界：
- 客户端 不直连 模型供应商，所有调用经 Manager 路由
- Manager 用 服务账号 / 用户委派令牌 调 Agnet
- 客户端按
integration/agnet-platform-api-design.md§6.4 订阅会话内子 agent 输出流
三、SK 数据流（Git / Upload → 快照 → 子 agent 注入）
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。
四、事件流双轨（平台运行态 vs 会话子代理输出）
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/) |
Agnet 平台 |
|---|---|---|---|
| 用户身份 | 浏览器登录 / API Key 兼容 | OAuth 提供方、Token 颁发与吊销 | 接收 M2M JWT 与用户委派令牌 |
| 模型调用 | 不直连模型，请求经 Manager | 路由、计费、RBAC | 不参与基础模型调用 |
| 编排 | 触发部署、订阅子 agent 输出 | 一键部署入口、Webhook 注册 | 实际执行编队、维护实例生命周期 |
| SK | 唯一编辑入口（写 Git / 上传） | 展开 sk_sources、刷新策略 |
拉取快照、运行时只读注入 |
| 观测 | 会话内子 agent 输出 | 平台运行态聚合 | 提供事件流、指标导出 |
六、相关代码索引
- 客户端登录：
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
代码会演进，本文以 架构关系 为准；具体路径请以仓库当前实现为最终事实。