heicode-win/docs/architecture.md

Heicode 架构与关键数据流

本文用 mermaid 图示统一表达 Heicode 客户端 / Manager / Agnet / NewAPI / Secret Store 之间的边界与数据流，作为愿景与 SaaS 架构计划的视觉补充。

与文字版的对应关系：vision-heicode-full-stack-agentic-dev.md、saas-manager-agnet-architecture-plan.md。旧 Agnet API 草案若与新架构计划冲突，以新架构计划为准。

---

一、概念分层（鸟瞰）

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 主链路

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 只通过受控身份使用被授权资源

---

三、资源绑定与凭证托管

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 注入）

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/)	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

代码会演进，本文以 架构关系 为准；具体路径请以仓库当前实现为最终事实。