diff --git a/cc-haha/README.sync-conflict-20260430-013912-GVADS2N.md b/cc-haha/README.sync-conflict-20260430-013912-GVADS2N.md deleted file mode 100644 index 489e257..0000000 --- a/cc-haha/README.sync-conflict-20260430-013912-GVADS2N.md +++ /dev/null @@ -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 超时与降级策略（提升桌面端可用性） diff --git a/docs/README.md b/docs/README.md index 3c5d0d8..a5c7f98 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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) diff --git a/docs/architecture.md b/docs/architecture.md index a80eb83..23e0891 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -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["人机入口
官网 · 控制台 · CLI · Desktop"] - manager["Heicode Manager
(heicode)"] + manager["Heicode Manager
SaaS 控制台"] client["Heicode 客户端
(cc-haha)"] - agnet["Agnet 平台
(角色模板 · 执行单元)"] + agnet["Agnet 平台
AKS 执行与状态"] + newapi["NewAPI
模型网关 · 余额 · 日志"] + secret["Secret Store
Vault / Infisical / Key Vault"] assets["资产与环境
仓库 · 流水线 · 运行时"] 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 /
OpenAI Chat 调用"| manager - manager -->|"模型路由 / 计费 / RBAC"| manager + newapi["NewAPI
模型网关 / 额度 / 调用日志"] + secret["Secret Store
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
资源元数据与授权"] + broker["Secret Broker"] + store["Secret Store
Vault / Infisical / Key Vault"] + agnet["Agnet 平台"] + pod["子 Agnet Pod
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 调用日志 | 调用日志、余额 | 提供事件流、指标导出 | 提供密钥访问审计 | --- diff --git a/docs/glossary.md b/docs/glossary.md index 73a8b63..164796a 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -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 为快照锚点 diff --git a/docs/integration/README.md b/docs/integration/README.md index 25e5454..273ca24 100644 --- a/docs/integration/README.md +++ b/docs/integration/README.md @@ -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 身份受控使用 | ## 与里程碑的关系 diff --git a/docs/integration/agnet-platform-api-design.md b/docs/integration/agnet-platform-api-design.md index 6eb0b86..8075e27 100644 --- a/docs/integration/agnet-platform-api-design.md +++ b/docs/integration/agnet-platform-api-design.md @@ -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 为准。* \ No newline at end of file +*本文档随里程碑评审更新；实现细节以 Agnet 与 Heicode 联合 RFC 为准。* diff --git a/docs/integration/agnet-user-deployment-flow.md b/docs/integration/agnet-user-deployment-flow.md index a3a66ae..2532ea3 100644 --- a/docs/integration/agnet-user-deployment-flow.md +++ b/docs/integration/agnet-user-deployment-flow.md @@ -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 仓库 diff --git a/docs/integration/orchestration-plan-contract.md b/docs/integration/orchestration-plan-contract.md index 04646a2..2e24f58 100644 --- a/docs/integration/orchestration-plan-contract.md +++ b/docs/integration/orchestration-plan-contract.md @@ -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`，并通过事件流持续反馈执行状态 - diff --git a/docs/milestones/README.md b/docs/milestones/README.md index 9a53ddd..3bc2730 100644 --- a/docs/milestones/README.md +++ b/docs/milestones/README.md @@ -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 解耦方案重写。 --- diff --git a/docs/milestones/STATUS.md b/docs/milestones/STATUS.md index 1d9bebf..7669a7c 100644 --- a/docs/milestones/STATUS.md +++ b/docs/milestones/STATUS.md @@ -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`：代码已落地并经过基本验证 diff --git a/docs/saas-manager-agnet-architecture-plan.md b/docs/saas-manager-agnet-architecture-plan.md new file mode 100644 index 0000000..4430348 --- /dev/null +++ b/docs/saas-manager-agnet-architecture-plan.md @@ -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 的缝合后台。 diff --git a/heicode/README.sync-conflict-20260430-014104-GVADS2N.md b/heicode/README.sync-conflict-20260430-014104-GVADS2N.md deleted file mode 100644 index 7c7a51b..0000000 --- a/heicode/README.sync-conflict-20260430-014104-GVADS2N.md +++ /dev/null @@ -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` 仅为历史路径），遵循对应许可证要求。企业使用前请完成内部合规审查。