docs: define saas manager agnet architecture
This commit is contained in:
gongzhiyong
@@ -1,73 +0,0 @@
|
||||
# Heicode（源码目录 `cc-haha`）
|
||||
|
||||
本目录实现 **Heicode** 终端与桌面客户端（CLI + Desktop + 本地服务）。目录名 `cc-haha` 为历史工程名；对外产品与文档统一称 **Heicode**（与 **Heicode Manager** 区分时亦称「Heicode 客户端」）。目标是把终端编程体验产品化，并对接企业模型平台。
|
||||
|
||||
## 你能得到什么
|
||||
|
||||
- 一个可运行的 CLI + Desktop 客户端
|
||||
- 双平台登录入口（TaijiAICloud / ClawdRouter）
|
||||
- 动态模型拉取，不写死模型名单
|
||||
- 适配企业交付的品牌化 UI
|
||||
|
||||
## 核心能力
|
||||
|
||||
- **登录流程**：优先浏览器 OAuth，兼容平台令牌登录
|
||||
- **模型发现**：通过 provider API 拉全量模型，不强绑定某一家模型
|
||||
- **运行方式**：同一套 provider 配置可在 CLI 与 Desktop 复用
|
||||
- **本地 sidecar**：桌面端通过本地服务层与 provider 通信，便于状态管理和扩展
|
||||
|
||||
## 目录速览
|
||||
|
||||
```text
|
||||
cc-haha/
|
||||
├── bin/ # 启动入口（heicode、兼容别名）
|
||||
├── src/
|
||||
│ ├── server/ # 本地 API/WS 服务
|
||||
│ │ ├── api/heicode-auth.ts # 登录相关接口
|
||||
│ │ ├── api/providers.ts # 模型拉取与 provider API
|
||||
│ │ └── config/providerPresets.*
|
||||
│ └── ... # CLI 逻辑
|
||||
├── desktop/ # Tauri + React 桌面端
|
||||
└── docs/ # 产品和技术文档
|
||||
```
|
||||
|
||||
## 快速启动
|
||||
|
||||
```bash
|
||||
# 安装依赖
|
||||
bun install
|
||||
|
||||
# 启动本地服务
|
||||
bun run src/server/index.ts
|
||||
|
||||
# 启动桌面端（新终端）
|
||||
cd desktop
|
||||
bun run tauri dev
|
||||
```
|
||||
|
||||
本地联调 TaijiAICloud：
|
||||
|
||||
```bash
|
||||
HEICODE_TAIJIAICLOUD_BASE_URL=http://localhost:3000 bun run src/server/index.ts
|
||||
```
|
||||
|
||||
## 开发约定
|
||||
|
||||
- `providerPresets` 只保留产品确定的 provider
|
||||
- UI 不暴露无关配置项（例如已移除 Providers 菜单）
|
||||
- 模型来源以 provider 实际返回为准
|
||||
- 认证相关改动优先保持“零配置”用户体验
|
||||
|
||||
## 已完成改造（本分支）
|
||||
|
||||
- 品牌统一为 `Heicode`
|
||||
- 登录页去除 API Key 输入区域及相关提示文案
|
||||
- 设置页移除 Providers 菜单
|
||||
- 侧边栏和 About 移除 GitHub 链接与图标
|
||||
- 模型选择器按 provider API 动态拉取模型，修复无 Claude provider 仍展示 Claude 模型的问题
|
||||
|
||||
## 下一步建议
|
||||
|
||||
- 增加登录与模型发现的 E2E 冒烟测试
|
||||
- 将 OAuth 流程状态可视化（处理中/失败原因/重试）
|
||||
- 增加 provider 超时与降级策略（提升桌面端可用性）
|
||||
+4
-3
@@ -7,6 +7,7 @@
|
||||
| 文档 | 用途 |
|
||||
|------|------|
|
||||
| [`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) | SaaS Manager / NewAPI / Agnet / Secret Store 的新边界与实施计划 |
|
||||
| [`glossary.md`](./glossary.md) | 术语表：Heicode / Manager / 客户端 / 子 agent / SK 等 |
|
||||
| [`architecture.md`](./architecture.md) | 架构图与关键数据流（mermaid） |
|
||||
| [`sk-lifecycle.md`](./sk-lifecycle.md) | SK（Skill 资产）单点真相：来源、快照、刷新、写权边界 |
|
||||
@@ -25,11 +26,11 @@
|
||||
|
||||
适合实现 Agnet 平台侧、与 Heicode 对接编排或事件流的工程师。
|
||||
|
||||
1. [`glossary.md`](./glossary.md) → [`architecture.md`](./architecture.md)
|
||||
1. [`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md) → [`glossary.md`](./glossary.md) → [`architecture.md`](./architecture.md)
|
||||
2. [`integration/README.md`](./integration/README.md)：集成方阅读地图
|
||||
3. [`sk-lifecycle.md`](./sk-lifecycle.md)：SK 边界（Heicode 端写、Agnet 只读快照）
|
||||
4. [`integration/agnet-platform-api-design.md`](./integration/agnet-platform-api-design.md)：详细 API 设计
|
||||
5. [`integration/agnet-user-deployment-flow.md`](./integration/agnet-user-deployment-flow.md)：用户绑定 Git / 云权限到部署子 Agnet 的产品流程
|
||||
4. [`integration/agnet-platform-api-design.md`](./integration/agnet-platform-api-design.md)：历史 API 草案，若与新架构计划冲突，以新架构计划为准
|
||||
5. [`integration/agnet-user-deployment-flow.md`](./integration/agnet-user-deployment-flow.md)：历史用户流程草案，若与新架构计划冲突，以新架构计划为准
|
||||
6. [`integration/heicode-oauth-flow.md`](./integration/heicode-oauth-flow.md)：HeiCode 客户端 ↔ Manager 浏览器登录流程
|
||||
7. 落地节奏：[`milestones/README.md`](./milestones/README.md)（M3–M5）+ [`milestones/STATUS.md`](./milestones/STATUS.md)
|
||||
|
||||
|
||||
+61
-20
@@ -1,8 +1,8 @@
|
||||
# Heicode 架构与关键数据流
|
||||
|
||||
本文用 mermaid 图示统一表达 **Heicode 客户端 / Manager / Agnet** 之间的边界与数据流，作为愿景与集成 API 设计的视觉补充。
|
||||
本文用 mermaid 图示统一表达 **Heicode 客户端 / Manager / Agnet / NewAPI / Secret Store** 之间的边界与数据流，作为愿景与 SaaS 架构计划的视觉补充。
|
||||
|
||||
> 与文字版的对应关系：[`vision-heicode-full-stack-agentic-dev.md`](./vision-heicode-full-stack-agentic-dev.md) 第五节、[`integration/agnet-platform-api-design.md`](./integration/agnet-platform-api-design.md) §1.1 / §5 / §6 / §7。
|
||||
> 与文字版的对应关系：[`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 草案若与新架构计划冲突，以新架构计划为准。
|
||||
|
||||
---
|
||||
|
||||
@@ -11,24 +11,30 @@
|
||||
```mermaid
|
||||
flowchart TD
|
||||
entry["人机入口<br/>官网 · 控制台 · CLI · Desktop"]
|
||||
manager["Heicode Manager<br/>(heicode)"]
|
||||
manager["Heicode Manager<br/>SaaS 控制台"]
|
||||
client["Heicode 客户端<br/>(cc-haha)"]
|
||||
agnet["Agnet 平台<br/>(角色模板 · 执行单元)"]
|
||||
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 与客户端
|
||||
- 编排细节归 Agnet 内部；Heicode 关注 **契约、体验与安全边界**
|
||||
- 资产层（仓库 / 流水线 / 运行时）是被动载体
|
||||
- **Manager 是 SaaS 用户、租户、资源、权限与部署控制台**
|
||||
- **NewAPI 是独立模型服务**，普通用户不进入 NewAPI 后台
|
||||
- **Secret Store 保存真实密钥**，Manager DB 只保存 `secret_ref`
|
||||
- **Agnet 在 AKS 上执行**，按 Manager 下发的 Resource Grant 和运行身份使用资源
|
||||
|
||||
---
|
||||
|
||||
@@ -44,20 +50,54 @@ flowchart LR
|
||||
user --> desktop
|
||||
desktop -->|"OAuth: /heicode/oauth/*"| manager
|
||||
desktop -->|"Anthropic Messages /<br/>OpenAI Chat 调用"| manager
|
||||
manager -->|"模型路由 / 计费 / RBAC"| 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 路由
|
||||
- 客户端 **不直连** 模型供应商，模型能力经 Manager / NewAPI 提供
|
||||
- Manager 用 **服务账号 / 用户委派令牌** 调 Agnet
|
||||
- 客户端按 [`integration/agnet-platform-api-design.md`](./integration/agnet-platform-api-design.md) §6.4 订阅会话内子 agent 输出流
|
||||
- 密钥不进入 Git、Markdown、前端或日志；子 Agnet 只通过受控身份使用被授权资源
|
||||
|
||||
---
|
||||
|
||||
## 三、SK 数据流（Git / Upload → 快照 → 子 agent 注入）
|
||||
## 三、资源绑定与凭证托管
|
||||
|
||||
```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
|
||||
@@ -87,7 +127,7 @@ flowchart TB
|
||||
|
||||
---
|
||||
|
||||
## 四、事件流双轨（平台运行态 vs 会话子代理输出）
|
||||
## 五、事件流双轨（平台运行态 vs 会话子代理输出）
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
@@ -105,15 +145,16 @@ flowchart LR
|
||||
|
||||
---
|
||||
|
||||
## 五、模块关注点对照
|
||||
## 六、模块关注点对照
|
||||
|
||||
| 关注点 | Heicode 客户端 (`cc-haha/`) | Heicode Manager (`heicode/`) | Agnet 平台 |
|
||||
|--------|------------------------------|-------------------------------|------------|
|
||||
| 用户身份 | 浏览器登录 / API Key 兼容 | OAuth 提供方、Token 颁发与吊销 | 接收 M2M JWT 与用户委派令牌 |
|
||||
| 模型调用 | 不直连模型，请求经 Manager | 路由、计费、RBAC | 不参与基础模型调用 |
|
||||
| 编排 | 触发部署、订阅子 agent 输出 | 一键部署入口、Webhook 注册 | 实际执行编队、维护实例生命周期 |
|
||||
| SK | 唯一编辑入口（写 Git / 上传） | 展开 `sk_sources`、刷新策略 | 拉取快照、运行时只读注入 |
|
||||
| 观测 | 会话内子 agent 输出 | 平台运行态聚合 | 提供事件流、指标导出 |
|
||||
| 关注点 | 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 调用日志 | 调用日志、余额 | 提供事件流、指标导出 | 提供密钥访问审计 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
+24
-3
@@ -3,7 +3,7 @@
|
||||
本术语表是 Heicode 仓库内 **跨文档共享的命名标准**。任意文档涉及以下名称时，请相对链接回本文件锚点，避免规则漂移。
|
||||
|
||||
> 与代号相关的方向性来源：[`vision-heicode-full-stack-agentic-dev.md`](./vision-heicode-full-stack-agentic-dev.md)。
|
||||
> 与 API 字段相关的来源：[`integration/agnet-platform-api-design.md`](./integration/agnet-platform-api-design.md)。
|
||||
> 与 SaaS 架构相关的来源：[`saas-manager-agnet-architecture-plan.md`](./saas-manager-agnet-architecture-plan.md)。
|
||||
|
||||
## 产品级代号
|
||||
|
||||
@@ -11,7 +11,7 @@
|
||||
仓库与产品族的总称。在区分产品形态时，亦称 **Heicode 客户端**。
|
||||
|
||||
### Heicode Manager
|
||||
账户、模型策略、渠道、计费与平台管控的服务端，源码目录 `heicode/`。在文档中亦称 **Manager**。
|
||||
SaaS 用户控制台与编排中枢，源码目录 `heicode/`。负责用户、租户、项目、资源绑定、权限分配、Agnet 部署、审计，以及面向普通用户展示模型、余额和调用日志。
|
||||
|
||||
### Heicode 客户端
|
||||
面向开发者的 CLI（Ink）+ 桌面应用（Tauri + React）+ 本地 HTTP/WS 服务，源码目录 `cc-haha/`。
|
||||
@@ -20,7 +20,16 @@
|
||||
**子智能体编排与团队模板** 所在平台的概念名。它是一个抽象代号，用以保持愿景叙事不绑死在某个厂商。落地形态可对应 Agnet。
|
||||
|
||||
### Agnet
|
||||
当前实际接入的编排平台名称。规范上 Heicode 与 Agnet 通过 [`integration/agnet-platform-api-design.md`](./integration/agnet-platform-api-design.md) 中定义的契约通信。
|
||||
当前实际接入的编排平台名称。Agnet 底层运行在 AKS，负责部署子 Agnet、维护执行状态、事件和日志，并按 Manager 下发的 Resource Grant 使用受控资源。
|
||||
|
||||
### NewAPI
|
||||
独立的模型网关和计费服务。它提供模型渠道、模型调用、额度、余额和调用日志；普通 SaaS 用户不进入 NewAPI 后台，Manager 后端通过服务凭据调用 NewAPI。
|
||||
|
||||
### Secret Store
|
||||
真实凭证的保管库，例如 HashiCorp Vault、Infisical 或 Azure Key Vault。Manager 数据库只保存 `secret_ref`，不保存 Git token、云密钥、SSH 私钥和数据库密码。
|
||||
|
||||
### Secret Broker
|
||||
Manager 后端中负责凭证写入、轮换、撤销、路径生成、策略创建和审计的边界模块。业务代码不应绕过 Secret Broker 直接操作 Secret Store。
|
||||
|
||||
## 编排相关
|
||||
|
||||
@@ -41,6 +50,18 @@
|
||||
### SK（Skill 资产）
|
||||
为子 agent 提供运行时只读上下文的说明类正文，多为 Markdown。详见 [`sk-lifecycle.md`](./sk-lifecycle.md)。
|
||||
|
||||
### 资源绑定 (`resource binding`)
|
||||
用户授权 Heicode 使用某个外部资源的动作与结果。资源可以是 Git 仓库、SK 仓库、项目文档、Azure/AWS/GCP 账号、VM、数据库、对象存储或 AKS 集群。绑定产生资源元数据和 `secret_ref`，不产生可暴露的明文密钥。
|
||||
|
||||
### Resource Grant
|
||||
Manager 中把某个资源授权给特定租户、项目、子 Agnet 角色和权限范围的记录。部署时，Manager 将 Resource Grant 转换为 permission manifest 发送给 Agnet 平台。
|
||||
|
||||
### permission manifest
|
||||
面向系统强制执行的结构化权限清单，描述每个子 Agnet 可用的资源、动作、路径、环境和限制。它和 AGENT.md / resource context 配套使用。
|
||||
|
||||
### resource context
|
||||
面向模型理解的启动上下文，通常可以生成为 Markdown。它描述角色、目标、可用资源和禁止事项，但不得包含任何真实密钥。
|
||||
|
||||
### `sk_sources`
|
||||
SK 的来源数组。每个元素声明其来源类型：
|
||||
- `git`：以 commit SHA 为快照锚点
|
||||
|
||||
+15
-14
@@ -8,25 +8,26 @@
|
||||
2. 二者之间走 **什么协议、什么字段**（API 契约）
|
||||
3. 这些能力 **何时落地**（与里程碑对齐）
|
||||
|
||||
## 当前主线
|
||||
|
||||
2026-05-02 之后，Manager / NewAPI / Agnet / Secret Store 的主边界以 [`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.md) 为准。
|
||||
本目录中的旧接口草案可作为历史参考；如果出现冲突，优先采用新架构计划。
|
||||
|
||||
## 推荐阅读顺序
|
||||
|
||||
|
||||
| 步骤 | 文档 | 你将得到 |
|
||||
| --- | ----------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
|
||||
| 1 | `[../glossary.md](../glossary.md)` | 统一术语：Heicode / Manager / 客户端 / 子 agent / SK / 标识符等 |
|
||||
| 2 | `[../architecture.md](../architecture.md)` | 整体架构与数据流（mermaid） |
|
||||
| 3 | `[./agnet-platform-api-design.md](./agnet-platform-api-design.md)` §1.1 | Manager 与客户端在 Agnet 可视化中的职责划分 |
|
||||
| 1 | `[../saas-manager-agnet-architecture-plan.md](../saas-manager-agnet-architecture-plan.md)` | 新主线：SaaS Manager、NewAPI、Agnet、Secret Store 的职责边界 |
|
||||
| 2 | `[../glossary.md](../glossary.md)` | 统一术语：Heicode / Manager / 客户端 / 子 agent / SK / 标识符等 |
|
||||
| 3 | `[../architecture.md](../architecture.md)` | 整体架构与数据流（mermaid） |
|
||||
| 4 | `[../sk-lifecycle.md](../sk-lifecycle.md)` | SK 来源、快照、写权边界（**单点真相**） |
|
||||
| 5 | `[./agnet-platform-api-design.md](./agnet-platform-api-design.md)` §2–§3 | 身份、调用方式、RBAC |
|
||||
| 6 | `[./agnet-platform-api-design.md](./agnet-platform-api-design.md)` §4 | 多租户与隔离 |
|
||||
| 7 | `[./agnet-platform-api-design.md](./agnet-platform-api-design.md)` §5 | 一键部署、`sk_sources`、**运行时绑定**、**SK 访问策略**、控制面 API |
|
||||
| 8 | `[./agnet-user-deployment-flow.md](./agnet-user-deployment-flow.md)` | 用户从绑定 Git / 云权限到部署子 Agnet 的产品流程 |
|
||||
| 9 | `[./orchestration-plan-contract.md](./orchestration-plan-contract.md)` | 模型提案对象与平台裁决规则 |
|
||||
| 10 | `[./agnet-platform-api-design.md](./agnet-platform-api-design.md)` §6–§7 | 运行态、聚合视图、事件流（双轨） |
|
||||
| 11 | `[./Heicode-登录接口对接文档.md](./Heicode-登录接口对接文档.md)` | 已上线认证接口契约（login / me / refresh / logout） |
|
||||
| 12 | `[./heicode-oauth-flow.md](./heicode-oauth-flow.md)` | 客户端浏览器登录到 Manager 的完整流程 |
|
||||
| 13 | `[./acceptance-matrix.md](./acceptance-matrix.md)` | 集成验收最小测试矩阵 |
|
||||
| 14 | `[../milestones/README.md](../milestones/README.md)` + `[../milestones/STATUS.md](../milestones/STATUS.md)` | 落地节奏与现状 |
|
||||
| 5 | `[./agnet-platform-api-design.md](./agnet-platform-api-design.md)` | 历史 API 草案：需按新主线重写后才能作为实现契约 |
|
||||
| 6 | `[./agnet-user-deployment-flow.md](./agnet-user-deployment-flow.md)` | 历史用户流程草案：Git 来源和云权限应升级为统一资源绑定 |
|
||||
| 7 | `[./orchestration-plan-contract.md](./orchestration-plan-contract.md)` | 历史编排提案草案：需补齐 Resource Grant、Secret Broker 与平台代理 |
|
||||
| 8 | `[./Heicode-登录接口对接文档.md](./Heicode-登录接口对接文档.md)` | 已上线认证接口契约（login / me / refresh / logout） |
|
||||
| 9 | `[./heicode-oauth-flow.md](./heicode-oauth-flow.md)` | 客户端浏览器登录到 Manager 的完整流程 |
|
||||
| 10 | `[./acceptance-matrix.md](./acceptance-matrix.md)` | 集成验收最小测试矩阵，后续需要按新主线更新 |
|
||||
|
||||
|
||||
## 边界速览
|
||||
@@ -38,7 +39,7 @@
|
||||
| 模型策略与计费 | 路由 / RBAC / 计费 | 调用 Manager | 不参与 |
|
||||
| 子 agent 输出展示 | 平台运行态汇总 | 会话内增量展示 | 提供 SSE/WS 流 |
|
||||
| SK 正文写入 | **不允许** | 唯一编辑入口 | **不允许**（仅只读快照） |
|
||||
| 凭据（Git/云 SA）写入 | 持久化与轮换 | 发起授权 | 按租户使用 |
|
||||
| 凭据（Git/云 SA）写入 | 通过 Secret Broker 托管、轮换、撤销 | 发起授权 | 运行时按 Resource Grant 和 K8s 身份受控使用 |
|
||||
|
||||
|
||||
## 与里程碑的关系
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Agnet 平台 ↔ Heicode 集成接口设计（草案）
|
||||
|
||||
> Deprecated: 本文是早期接口草案。2026-05-02 之后，Manager / NewAPI / Agnet / Secret Store 的主边界以 [`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.md) 为准。本文如与新架构计划冲突，以新架构计划为准。
|
||||
|
||||
本文描述 **Agnet 平台**应向 **Heicode（Manager / 客户端 / 自动化服务）** 暴露的 **控制面、数据面隔离、权限模型与可视化/事件接口**。
|
||||
路径、字段名为 **设计意图**；落地时可等价映射为 gRPC 或 GraphQL，但**语义与隔离边界**应保持一致。
|
||||
|
||||
@@ -487,4 +489,4 @@ Tenant（租户）
|
||||
|
||||
---
|
||||
|
||||
*本文档随里程碑评审更新；实现细节以 Agnet 与 Heicode 联合 RFC 为准。*
|
||||
*本文档随里程碑评审更新；实现细节以 Agnet 与 Heicode 联合 RFC 为准。*
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Agnet 用户部署流程
|
||||
|
||||
> Deprecated: 本文是早期用户流程草案。2026-05-02 之后，资源绑定、凭证托管、NewAPI 解耦和 Agnet AKS 运行身份以 [`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.md) 为准。本文如与新架构计划冲突，以新架构计划为准。
|
||||
|
||||
本文记录 Heicode Manager 中用户从绑定仓库、授权云资源，到部署子 Agnet 的目标流程。它描述产品语义和交互顺序，具体 API 字段以 [`agnet-platform-api-design.md`](./agnet-platform-api-design.md) 与 [`orchestration-plan-contract.md`](./orchestration-plan-contract.md) 为准。
|
||||
|
||||
## 一、绑定代码与 SK 仓库
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# 编排提案契约（`orchestration_plan`）
|
||||
|
||||
> Deprecated: 本文是早期编排提案草案。2026-05-02 之后，正式计划需要补齐 Resource Grant、Secret Broker、Secret Store、AKS 运行身份和平台代理语义；主参考见 [`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.md)。
|
||||
|
||||
本文定义「模型提案、平台裁决」模式下的最小编排对象，供 Heicode / Manager / Agnet 三方对齐。
|
||||
|
||||
## 1. 决策边界
|
||||
@@ -118,4 +120,3 @@ Agnet 在执行前必须做下列校验：
|
||||
- `orchestration_plan` 建议由 Manager **无损映射**为 Agnet `POST /deployments` 标准 payload；**`runtime_execution` / `sk_access_policy` 不得在进入部署链路时丢弃**，否则子 agent 无法获得用户在 Manager 配置的权限与 SK 边界
|
||||
- 拒绝时应返回 `error.code` + `request_id` + `correlation_id`
|
||||
- 接受后返回 `deployment_id`，并通过事件流持续反馈执行状态
|
||||
|
||||
|
||||
@@ -2,13 +2,14 @@
|
||||
|
||||
> 导航：[`../README.md`](../README.md) · [`../glossary.md`](../glossary.md) · [`../architecture.md`](../architecture.md) · [`./STATUS.md`](./STATUS.md)
|
||||
|
||||
本目录将整体交付拆成**可验收、可并行准备**的里程碑事件；每个文件定义**完成定义（DoD）**、**依赖**与**与 Agnet 平台的衔接点**。
|
||||
全局范式仍以 [`../vision-heicode-full-stack-agentic-dev.md`](../vision-heicode-full-stack-agentic-dev.md) 为准；当前实现状态见 [`./STATUS.md`](./STATUS.md)。
|
||||
本目录保存早期 M1-M5 里程碑草案。2026-05-02 之后，SaaS Manager、NewAPI、Agnet 和 Secret Store 的落地节奏以 [`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.md) 第十节为准。
|
||||
本目录可作为历史参考；后续需要把 M1-M5 重写为 P0-P5 后再作为正式交付计划使用。
|
||||
|
||||
## 推荐阅读顺序
|
||||
|
||||
| 顺序 | 文档 | 摘要 |
|
||||
|------|------|------|
|
||||
| 0 | [SaaS Manager 与 Agnet 平台架构计划](../saas-manager-agnet-architecture-plan.md) | 当前主计划：P0-P5 |
|
||||
| 1 | [M1-契约与身份对齐](./M1-contract-identity.md) | Heicode Manager ↔ 客户端最小契约；登录与令牌语义 |
|
||||
| 2 | [M2-本地端到端闭环](./M2-local-e2e.md) | 单环境跑通：登录、模型发现、对话、一次发布链路（示意） |
|
||||
| 3 | [M3-Agnet-编排集成](./M3-agnet-orchestration-bridge.md) | 拉起编队、执行单元生命周期与回调 Heicode |
|
||||
@@ -21,7 +22,7 @@ Agnet 平台应对外暴露的 **HTTP/gRPC 契约、事件流与隔离模型**
|
||||
|
||||
**[`../integration/agnet-platform-api-design.md`](../integration/agnet-platform-api-design.md)**
|
||||
|
||||
里程碑 **M3～M5** 分别对应集成文档中的「编排 API」「安全与隔离」「观测与可视化 API」的落地节奏。
|
||||
早期里程碑 **M3～M5** 曾对应集成文档中的「编排 API」「安全与隔离」「观测与可视化 API」。这些内容需要按新的 Manager 资源绑定、Secret Broker、AKS 运行身份和 NewAPI 解耦方案重写。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 里程碑现状对齐
|
||||
|
||||
本文以仓库当前代码为依据，对 M1–M5 的 DoD 项做粗粒度盘点，便于例会与评审快速对齐。**不替代** 各里程碑文档的 DoD 原文。
|
||||
本文以仓库当前代码为依据，对早期 M1-M5 的 DoD 项做粗粒度盘点，便于例会与评审快速对齐。2026-05-02 之后，正式计划以 [`../saas-manager-agnet-architecture-plan.md`](../saas-manager-agnet-architecture-plan.md) 第十节 P0-P5 为准；本文保留为历史现状参考。
|
||||
|
||||
> 状态图例：
|
||||
> - `done`：代码已落地并经过基本验证
|
||||
|
||||
@@ -0,0 +1,312 @@
|
||||
# Heicode SaaS Manager 与 Agnet 平台架构计划
|
||||
|
||||
本文记录 2026-05-02 讨论后确认的新边界：Heicode 的最终形态是一款覆盖软件生命周期的智能开发 Code 工具。用户注册后，用自然语言描述想法，平台应能逐步完成团队生成、产品文档、原型描述、代码开发、代码检查、生产部署、定期维护和升级。
|
||||
|
||||
本文是后续 Manager / NewAPI / Agnet / 凭证托管方案的主参考。旧的 Agnet 接口草案如与本文冲突，以本文为准。
|
||||
|
||||
## 一、核心判断
|
||||
|
||||
Heicode 不是 NewAPI 的二次开发项目，也不是单纯的 Agent 控制台。产品边界应拆成四层：
|
||||
|
||||
| 层 | 定位 | 主要职责 |
|
||||
|----|------|----------|
|
||||
| Heicode Manager | SaaS 用户控制台与编排中枢 | 用户、租户、项目、资源绑定、权限分配、Agnet 部署、审计、余额与模型可见性 |
|
||||
| Agnet 平台 | 执行与状态平台 | 在 AKS 上部署子 Agnet、运行任务、维护状态、事件、日志和执行元数据 |
|
||||
| NewAPI | 内部模型网关与计费服务 | 模型渠道、模型列表、模型调用、额度、余额、调用日志；后台不开放给普通用户 |
|
||||
| Secret Store | 凭证保管库 | 保存 Git token、云密钥、SSH key、数据库密码等真实凭证 |
|
||||
|
||||
Manager 是用户操作入口；Agnet 是运行时执行层；NewAPI 是模型能力服务；Secret Store 是安全凭证底座。
|
||||
|
||||
## 二、不可破坏的原则
|
||||
|
||||
1. 在需求和边界没有想清楚前，不改代码。
|
||||
2. NewAPI 保持独立服务，不继续改造成 Manager 的内嵌后台。
|
||||
3. NewAPI 后台不开放给普通 SaaS 用户，模型管理由内部人员完成。
|
||||
4. Manager 只补 NewAPI 没有的后端能力：项目、资源、权限、Agnet 部署、审计和生命周期管理。
|
||||
5. 用户绑定的是 Agnet 可用资源，不只是 Git 来源。
|
||||
6. 密钥不能进入 Git、Markdown、前端、部署摘要或日志。
|
||||
7. Manager 负责资源绑定、权限分配和凭证托管能力；真实密钥放入 Secret Store。
|
||||
8. 子 Agnet 不保存长期密钥，只接收角色、资源元数据、AGENT.md 和受控访问方式。
|
||||
9. Agnet 平台在 AKS 上负责运行时身份、隔离、状态、事件和审计回传。
|
||||
10. 高危生产权限优先走平台代理或审批，不直接把长期密钥注入子 Agnet。
|
||||
|
||||
## 三、Manager 的产品主线
|
||||
|
||||
Manager 面向普通用户展示的是一条从想法到交付的控制流程，而不是 NewAPI 管理后台。
|
||||
|
||||
核心功能：
|
||||
|
||||
1. 绑定 GitHub、GitLab、Gitea、Gitee、自建 Git 等代码来源。
|
||||
2. 绑定云资源，例如 AWS、Azure、GCP、虚拟机、数据库、对象存储、Kubernetes 集群。
|
||||
3. 确认项目仓库、SK 仓库、项目文档仓库或二合一仓库。
|
||||
4. 按敏捷或瀑布方法分配子 Agnet 角色。
|
||||
5. 为每个子 Agnet 配置 AGENT.md、可用工具、Git 范围、云资源范围、模型和预算。
|
||||
6. 部署子 Agnet，设置数量、模型和运行环境。
|
||||
7. 观察子 Agnet 活动状态、失败原因、事件和运行日志。
|
||||
8. 查看审计日志和模型调用日志。
|
||||
9. 查看可用模型、余额、额度和使用情况。
|
||||
10. 展示 NewAPI 对普通用户有意义的能力，隐藏渠道、价格、模型后台管理等管理员能力。
|
||||
|
||||
## 四、资源绑定模型
|
||||
|
||||
“绑定”不是保存一串密钥，而是创建租户级 Resource Grant。
|
||||
|
||||
```text
|
||||
某个用户/租户授权 Heicode 使用某个外部资源
|
||||
-> Manager 记录资源元数据
|
||||
-> Manager 的 Secret Broker 把真实凭证写入 Secret Store
|
||||
-> Manager 生成可审计、可撤销、可分配给子 Agnet 的资源授权
|
||||
```
|
||||
|
||||
资源类型建议统一建模为：
|
||||
|
||||
| 类型 | 示例 | 子 Agnet 可见内容 |
|
||||
|------|------|------------------|
|
||||
| Git 资源 | GitHub repo、自建 Git、SK repo | repo URL、ref、允许路径、读写范围 |
|
||||
| 云账号 | Azure subscription、AWS account、GCP project | account/project/subscription 元数据、允许动作 |
|
||||
| 单项云资源 | VM、DB、Bucket、AKS namespace | 资源 ID、环境、网络边界、允许动作 |
|
||||
| 项目文档 | 产品文档、原型说明、需求库 | 文档引用、版本、可读范围 |
|
||||
| SK 资源 | 技能仓库、上传的技能包 | SK 来源、版本、允许/禁止策略 |
|
||||
|
||||
Manager 数据库保存资源元数据和授权关系，不保存明文密钥：
|
||||
|
||||
```text
|
||||
resources:
|
||||
id
|
||||
tenant_id
|
||||
provider
|
||||
type
|
||||
display_name
|
||||
external_id
|
||||
metadata_json
|
||||
secret_ref
|
||||
status
|
||||
|
||||
resource_grants:
|
||||
id
|
||||
tenant_id
|
||||
project_id
|
||||
resource_id
|
||||
agnet_role
|
||||
permissions_json
|
||||
constraints_json
|
||||
|
||||
secret_bindings:
|
||||
id
|
||||
tenant_id
|
||||
resource_id
|
||||
secret_provider
|
||||
secret_ref
|
||||
version
|
||||
status
|
||||
last_rotated_at
|
||||
```
|
||||
|
||||
## 五、开源 Secret Store 架构
|
||||
|
||||
SaaS 场景下，凭证不能转嫁给用户手工管理。用户负责授权，平台负责托管、隔离、轮换、撤销和审计。
|
||||
|
||||
推荐抽象：
|
||||
|
||||
```text
|
||||
Manager API
|
||||
-> Secret Broker
|
||||
-> Secret Provider
|
||||
-> Vault / Infisical / Azure Key Vault
|
||||
```
|
||||
|
||||
开源优先方案：
|
||||
|
||||
| 方案 | 适用判断 |
|
||||
|------|----------|
|
||||
| HashiCorp Vault | 优先选择。Kubernetes Auth、Policy、TTL、动态密钥、审计能力成熟，适合 AKS 中的子 Agnet 运行时授权 |
|
||||
| Infisical | 产品体验较好，适合作为可选 Secret Provider，需要进一步验证多租户策略和运行时授权能力 |
|
||||
| SOPS + KMS | 适合配置文件密钥，不适合作为 SaaS 动态资源绑定主方案 |
|
||||
|
||||
Secret Broker 负责：
|
||||
|
||||
- 接收 OAuth / GitHub App / 云授权回调后的凭证。
|
||||
- 生成租户隔离的 secret path。
|
||||
- 写入 Vault / Infisical / Key Vault。
|
||||
- 创建或更新 policy。
|
||||
- 保存 secret_ref 到 Manager DB。
|
||||
- 轮换、撤销、禁用凭证。
|
||||
- 避免密钥进入日志、前端响应、Markdown 和 Git。
|
||||
|
||||
Vault 路径示例：
|
||||
|
||||
```text
|
||||
secret/heicode/tenants/{tenant_id}/resources/{resource_id}/github
|
||||
secret/heicode/tenants/{tenant_id}/resources/{resource_id}/azure
|
||||
secret/heicode/tenants/{tenant_id}/projects/{project_id}/deployments/{deployment_id}
|
||||
```
|
||||
|
||||
## 六、AKS 上的 Agnet 凭证访问
|
||||
|
||||
Agnet 平台底层是 AKS，因此运行时权限应和 Kubernetes 身份绑定。
|
||||
|
||||
推荐流程：
|
||||
|
||||
```text
|
||||
用户在 Manager 授权资源
|
||||
-> Manager Secret Broker 写入 Secret Store
|
||||
-> Manager 记录 Resource Grant
|
||||
-> Manager 请求 Agnet 平台部署
|
||||
-> Agnet 平台为 deployment / role 创建 K8s ServiceAccount
|
||||
-> Agnet 平台绑定 Vault policy 或 Workload Identity
|
||||
-> 子 Agnet Pod 运行时只能访问被授权的 secret
|
||||
```
|
||||
|
||||
子 Agnet 拿到的是：
|
||||
|
||||
```text
|
||||
你是 backend-agent
|
||||
你可以访问 project-main-repo
|
||||
权限是 read_repo / write_branch / create_pr
|
||||
凭证由运行环境提供
|
||||
禁止输出、持久化或提交任何凭证
|
||||
```
|
||||
|
||||
子 Agnet 不应拿到：
|
||||
|
||||
```text
|
||||
github_pat_xxx
|
||||
azure_client_secret_xxx
|
||||
ssh_private_key
|
||||
database_password
|
||||
```
|
||||
|
||||
运行时访问分两种模式：
|
||||
|
||||
| 模式 | 用法 | 适用场景 |
|
||||
|------|------|----------|
|
||||
| 受控注入 | Pod 通过 Vault Agent、Kubernetes Auth、CSI 或 Workload Identity 读取短期凭证 | Git clone、开发/测试环境、低风险资源 |
|
||||
| 平台代理 | 子 Agnet 请求 Manager / Agnet Platform 代执行资源动作 | 生产部署、数据库写入、高危云操作、需要审批的动作 |
|
||||
|
||||
推荐混合策略：普通开发资源可受控注入，生产云资源和高危操作走平台代理或审批。
|
||||
|
||||
## 七、NewAPI 的边界
|
||||
|
||||
NewAPI 不作为普通用户后台开放。Manager 后端通过服务凭据调用 NewAPI，对用户展示必要信息。
|
||||
|
||||
Manager 可展示：
|
||||
|
||||
- 可用模型。
|
||||
- 当前租户或项目额度。
|
||||
- 余额。
|
||||
- 调用量。
|
||||
- 调用日志。
|
||||
- 失败日志。
|
||||
- 模型可用状态。
|
||||
|
||||
Manager 不展示：
|
||||
|
||||
- 渠道管理。
|
||||
- 模型供应商后台配置。
|
||||
- 价格配置。
|
||||
- 系统管理员用户管理。
|
||||
- NewAPI 原生管理后台入口。
|
||||
|
||||
用户登录 Manager，不直接登录 NewAPI。Manager 需要维护用户 / 租户 / 项目到 NewAPI 用户、key 或 quota 的映射。
|
||||
|
||||
## 八、认证与权限统一策略
|
||||
|
||||
不要求三套系统完全统一登录，但必须统一租户、项目、角色、资源授权语义。
|
||||
|
||||
| 系统关系 | 建议 |
|
||||
|----------|------|
|
||||
| Manager ↔ NewAPI | 服务端对服务端调用。用户不直接进入 NewAPI 后台。Manager 按租户映射 NewAPI key、额度和日志 |
|
||||
| Manager ↔ Agnet | 必须共享 tenant / project / deployment / role / resource grant 语义。使用 M2M token 或受控委托令牌 |
|
||||
| Agnet ↔ Secret Store | 通过 AKS ServiceAccount、Vault Kubernetes Auth、Workload Identity 或平台代理访问 |
|
||||
| 用户 ↔ Manager | Manager 是 SaaS 登录和用户体验入口 |
|
||||
|
||||
因此，可行方案是：Manager 统一用户体验和资源权限，Agnet 统一执行身份和运行隔离，NewAPI 只提供模型服务能力。
|
||||
|
||||
## 九、启动上下文与 Markdown
|
||||
|
||||
绑定的资源最终可以生成 Markdown，但 Markdown 是上下文和规则，不是凭证载体。
|
||||
|
||||
Markdown 可包含：
|
||||
|
||||
- 子 Agnet 角色。
|
||||
- 目标任务。
|
||||
- 项目背景。
|
||||
- AGENT.md 来源。
|
||||
- 可使用的 Git 资源。
|
||||
- 可使用的云资源。
|
||||
- 可使用的 SK。
|
||||
- 允许和禁止动作。
|
||||
- 审计要求。
|
||||
|
||||
Markdown 不得包含：
|
||||
|
||||
- Git token。
|
||||
- 云 access key。
|
||||
- refresh token。
|
||||
- SSH 私钥。
|
||||
- 数据库密码。
|
||||
- NewAPI key 原文。
|
||||
|
||||
建议 Manager 生成两类产物：
|
||||
|
||||
| 产物 | 用途 |
|
||||
|------|------|
|
||||
| AGENT.md / resource context | 给子 Agnet 的启动上下文，说明角色和可用资源 |
|
||||
| permission manifest | 给 Agnet 平台和审计系统的结构化权限清单 |
|
||||
|
||||
Markdown 面向模型理解，manifest 面向系统强制执行。
|
||||
|
||||
## 十、实施 Plan
|
||||
|
||||
### P0：文档和边界收敛
|
||||
|
||||
- 清理废弃或冲突的旧文档入口。
|
||||
- 确认本文为 Manager / NewAPI / Agnet / Secret Store 的主参考。
|
||||
- 更新术语表：资源绑定、Resource Grant、Secret Broker、Secret Store、平台代理。
|
||||
- 明确代码修改铁律：边界未讨论清楚前不改代码。
|
||||
|
||||
### P1：Manager 资源模型
|
||||
|
||||
- 将当前“Git 来源”抽象为资源绑定模型。
|
||||
- 增加资源类型：Git、SK、项目文档、云账号、单项云资源。
|
||||
- 增加 resource_grants，用于把资源分配给项目、角色和子 Agnet。
|
||||
- 前端从“填 JSON”升级为“绑定资源 -> 分配角色 -> 部署确认”的向导。
|
||||
|
||||
### P2：Secret Broker 与开源 Secret Store
|
||||
|
||||
- 选型 Vault 作为首个开源 Secret Provider。
|
||||
- 在 Manager 后端实现 Secret Broker。
|
||||
- 支持写入、读取引用、轮换、撤销、禁用。
|
||||
- DB 只保存 secret_ref，不保存明文密钥。
|
||||
- 增加密钥泄露防护：日志脱敏、前端响应过滤、Markdown 生成过滤。
|
||||
|
||||
### P3：Agnet 平台 AKS 身份接入
|
||||
|
||||
- Agnet 平台支持 deployment / role 到 Kubernetes ServiceAccount 的映射。
|
||||
- 支持 Vault Kubernetes Auth 或等价 Workload Identity。
|
||||
- 支持按 tenant / project / role 生成 Vault policy。
|
||||
- 子 Agnet 运行时只能访问被授权的 secret。
|
||||
- 生产云操作支持平台代理或审批。
|
||||
|
||||
### P4：NewAPI 解耦
|
||||
|
||||
- NewAPI 保持独立服务。
|
||||
- Manager 通过服务凭据调用 NewAPI。
|
||||
- Manager 展示普通用户需要的模型、余额、额度、调用日志。
|
||||
- 隐藏 NewAPI 管理员后台能力。
|
||||
- 建立 Manager tenant / user / project 与 NewAPI key / quota / usage 的映射。
|
||||
|
||||
### P5：部署和审计闭环
|
||||
|
||||
- Manager 生成 AGENT.md / resource context / permission manifest。
|
||||
- Agnet 平台部署子 Agnet 后回传 deployment、agent instance、状态和事件。
|
||||
- Manager 展示活动状态、失败原因、资源使用记录、模型调用记录和审计日志。
|
||||
- 对高危权限增加审批、撤销和运行中失效机制。
|
||||
|
||||
## 十一、当前不做
|
||||
|
||||
- 不把云密钥写入 Markdown。
|
||||
- 不把 NewAPI 后台开放给普通用户。
|
||||
- 不让 Agnet 平台成为长期密钥明文存储地。
|
||||
- 不在边界未确认时继续堆功能。
|
||||
- 不把 Manager 继续改造成 NewAPI 的缝合后台。
|
||||
@@ -1,70 +0,0 @@
|
||||
# Heicode Manager（源码目录 `heicode`）
|
||||
|
||||
本目录实现 **Heicode Manager**：网关与管理控制台（账号、渠道、模型策略、计费等）。目录名 `heicode` 为历史工程名；对外产品与文档统一称 **Heicode Manager**。目标是支撑 **Heicode 客户端**「浏览器登录后即用模型」。
|
||||
|
||||
## 本仓库角色
|
||||
|
||||
- 作为模型统一入口，管理渠道、用户、令牌、计费策略
|
||||
- 提供 Heicode 需要的授权桥接接口
|
||||
- 输出标准模型发现能力（`/v1/models`）给客户端
|
||||
|
||||
## Heicode 相关新增能力
|
||||
|
||||
### 1) 浏览器登录授权入口
|
||||
|
||||
- `GET /heicode/oauth/authorize`
|
||||
- `GET /heicode/oauth/session`
|
||||
|
||||
行为说明：
|
||||
|
||||
- 校验 `redirect_uri` 必须是 loopback（`127.0.0.1` / `localhost` / `::1`）
|
||||
- 若用户未登录平台控制台，先引导登录
|
||||
- 登录后签发或复用 Heicode 专用 token
|
||||
- 回跳本地客户端并携带 `state` 与 `token`
|
||||
|
||||
### 2) 客户端模型发现
|
||||
|
||||
- Heicode 通过 `GET /v1/models` 拉取可用模型集合
|
||||
- 客户端不再依赖硬编码模型列表
|
||||
|
||||
## 快速运行（本地 Docker）
|
||||
|
||||
```bash
|
||||
cd heicode
|
||||
docker compose -f docker-compose.yml -f docker-compose.override.yml up --build -d
|
||||
```
|
||||
|
||||
查看服务状态：
|
||||
|
||||
```bash
|
||||
docker compose ps
|
||||
docker compose logs -f heicode
|
||||
```
|
||||
|
||||
默认访问地址：`http://localhost:3000`
|
||||
|
||||
## Heicode 联调检查清单
|
||||
|
||||
- 平台已可正常登录 Web 控制台
|
||||
- `GET /heicode/oauth/authorize` 返回流程可达
|
||||
- `GET /heicode/oauth/session` 可反映登录态
|
||||
- `GET /v1/models` 返回模型列表不为空
|
||||
- Heicode 客户端登录后可直接发起模型请求
|
||||
|
||||
## 目录关注点
|
||||
|
||||
- `controller/heicode_oauth.go`：Heicode 授权与会话检测核心逻辑
|
||||
- `router/heicode-router.go`：Heicode OAuth 路由注册
|
||||
- `router/main.go`：总路由接入点
|
||||
- `docker-compose.override.yml`：本地开发构建入口
|
||||
|
||||
## 生产建议
|
||||
|
||||
- 强制 HTTPS 与可信证书
|
||||
- 设置稳定的会话密钥与持久化存储
|
||||
- 对授权回调、token 签发、模型探活增加审计日志
|
||||
- 配置限流与告警，避免异常流量冲击
|
||||
|
||||
## 许可证与来源
|
||||
|
||||
本工程在开源网关上游基础上演进（目录名 `heicode` 仅为历史路径），遵循对应许可证要求。企业使用前请完成内部合规审查。
|
||||
Reference in New Issue
Block a user