taijibaga/heicode-mananger
9
0
Fork 0
Code Issues 12 Pull Requests Actions Packages Projects 1 Releases Wiki Activity

feat(agent): unify agnet→agent and implement client/runtime unification spec v0.1 core

Browse Source 
按桌面客户端统一方案 v0.1 + agent_management Sub Mode Runtime 对接,强制全量统一,不留兼容。

命名统一(强制,无兼容):
- 全仓 agnet/Agnet/AGNET → agent/Agent/AGENT:后端 Go(路由 /api/agent/*、env AGENT_*、
  结构体/函数、19 个文件改名)、前端(agent-console/agent-hub、/api/agent 调用、i18n)、
  DB(表 agent_*、列 agent_id)、compose/.env、文档、脚本。
- DB 加幂等迁移 renameAgnetTablesToAgent():启动时 rename 老 agnet_* 表/列,保住生产数据。

统一方案核心(10 项):
- callback 统一 /api/agent/callbacks/runtime-events(路由/广播URL/函数名)。
- artifact 兜底判定改用 Runtime 权威信号 metadata.synthesized(§7.2)+ 结构化 artifact_type。
- Manager→Runtime 路径对齐 /api/agent/sub-agile/deployments(§2.2),{deployment_id} 回退 swarm_id。
- 状态裁决 display_status:Manager 唯一裁判,completed 无有效产物→needs_codegen/
  completed_without_deliverable(§10.6),接入 detail/timeline/workflow。
- GET /api/heicode/capabilities 能力发现(§6)。
- 模型策略 per_role(role_models)+ 收集 allowed_model_ids(§9)。
- resource_binding_id→secret_ref 服务端解析,客户端不再 inline secret_ref(§17.6)。
- 客户端统一路由层 /api/heicode/sub-agile|swarm/*(task≡deployment,复用控制面)+ workflow 投影。
- 日志分层 user_logs/debug_logs(§13)。

验证:go build ./... + go test(controller/router/model/middleware)全绿;前端 tsc -b + rsbuild build 通过。
待部署:VM .env 的 AGNET_*→AGENT_*;启动迁移自动 rename 表;其他三仓库需同步切到 /api/agent。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
chenchen
2026-06-01 23:45:10 +08:00
co-authored by Claude Opus 4.8
parent 12602ebcd6
commit 0fe1d20d67
112 changed files with 4305 additions and 3139 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/heicode.md
+32 -32
View File
@@ -21,54 +21,54 @@ Heicode 的最终形态是一款覆盖软件生命周期的智能开发 Code 工
| 系统 | 定位 | 负责内容 |
|------|------|----------|
| Heicode Manager | SaaS 用户控制台与编排中枢 | 用户输入、资源绑定、权限分配、Agnet 部署、审计、模型与余额展示 |
| Agnet 平台 | 执行与状态平台 | 在 AKS 上部署子 Agnet、运行任务、维护状态、事件、日志和执行元数据 |
| Heicode Manager | SaaS 用户控制台与编排中枢 | 用户输入、资源绑定、权限分配、Agent 部署、审计、模型与余额展示 |
| Agent 平台 | 执行与状态平台 | 在 AKS 上部署子 Agent、运行任务、维护状态、事件、日志和执行元数据 |
| NewAPI | 内部模型网关与计费服务 | 模型渠道、模型调用、额度、余额、调用日志；后台不对普通用户开放 |
| Secret Store | 凭证保管库 | 保存 Git token、云密钥、SSH key、数据库密码等真实凭证 |
Manager 是用户操作入口；Agnet 是运行时执行层；NewAPI 是模型能力服务；Secret Store 是安全凭证底座。
Manager 是用户操作入口；Agent 是运行时执行层；NewAPI 是模型能力服务；Secret Store 是安全凭证底座。
## 三、不可破坏的原则
1. 在需求和边界没有想清楚前，不改代码。
2. NewAPI 保持独立服务，不继续改造成 Manager 的内嵌后台。
3. NewAPI 后台不开放给普通 SaaS 用户，模型管理由内部人员完成。
4. Manager 只补 NewAPI 没有的后端能力：用户输入编排、资源绑定、权限、Agnet 部署、审计和生命周期管理。
5. 用户绑定的是 Agnet 可用资源，不只是 Git 来源。
4. Manager 只补 NewAPI 没有的后端能力：用户输入编排、资源绑定、权限、Agent 部署、审计和生命周期管理。
5. 用户绑定的是 Agent 可用资源，不只是 Git 来源。
6. 密钥不能进入 Git、Markdown、前端、部署摘要或日志。
7. Manager 负责资源绑定、权限分配和凭证托管能力；真实密钥放入 Secret Store。
8. 子 Agnet 不保存长期密钥，只接收角色、资源元数据、AGENT.md 和受控访问方式。
9. Agnet 平台在 AKS 上负责运行时身份、隔离、状态、事件和审计回传。
10. 高危操作审批只在客户端完成；审批通过后可以把密钥保管器派生的短期、最小权限凭证注入子 Agnet，但不能注入长期密钥。
11. 子 Agnet 的运行模型是 Agnet 平台的部署配置，独立于 NewAPI 的用户、Token、Group 扣费映射。
8. 子 Agent 不保存长期密钥，只接收角色、资源元数据、AGENT.md 和受控访问方式。
9. Agent 平台在 AKS 上负责运行时身份、隔离、状态、事件和审计回传。
10. 高危操作审批只在客户端完成；审批通过后可以把密钥保管器派生的短期、最小权限凭证注入子 Agent，但不能注入长期密钥。
11. 子 Agent 的运行模型是 Agent 平台的部署配置，独立于 NewAPI 的用户、Token、Group 扣费映射。
## 四、Manager 的核心功能
1. 绑定 GitHub、GitLab、Gitea、Gitee、自建 Git 等代码来源。
2. 绑定云资源，例如 AWS、Azure、GCP、虚拟机、数据库、对象存储、Kubernetes 集群。
3. 确认项目仓库、SK 仓库、项目文档仓库或二合一仓库。
4. 按敏捷或瀑布方法分配子 Agnet 角色。
5. 为每个子 Agnet 配置 AGENT.md、可用工具、Git 范围、云资源范围、模型和预算。
6. 部署子 Agnet，设置数量、模型和运行环境。
7. 观察子 Agnet 活动状态、失败原因、事件和运行日志。
4. 按敏捷或瀑布方法分配子 Agent 角色。
5. 为每个子 Agent 配置 AGENT.md、可用工具、Git 范围、云资源范围、模型和预算。
6. 部署子 Agent，设置数量、模型和运行环境。
7. 观察子 Agent 活动状态、失败原因、事件和运行日志。
8. 查看审计日志和模型调用日志。
9. 查看可用模型、余额、额度和使用情况。
10. 展示 NewAPI 对普通用户有意义的能力，隐藏渠道、价格、模型后台管理等管理员能力。
## 五、资源绑定与密钥托管
绑定不是保存一串密钥，而是创建面向登录用户、绑定 Git/SK/云资源和子 Agnet 角色的 Resource Grant。
绑定不是保存一串密钥，而是创建面向登录用户、绑定 Git/SK/云资源和子 Agent 角色的 Resource Grant。
```text
用户授权 Heicode 使用外部资源
-> Manager 记录资源元数据
-> Manager 的 Secret Broker 把真实凭证写入 Secret Store
-> Manager 生成可审计、可撤销、可分配给子 Agnet 的资源授权
-> Manager 生成可审计、可撤销、可分配给子 Agent 的资源授权
```
资源类型：
| 类型 | 示例 | 子 Agnet 可见内容 |
| 类型 | 示例 | 子 Agent 可见内容 |
|------|------|------------------|
| Git 资源 | GitHub repo、自建 Git、SK repo | repo URL、ref、允许路径、读写范围 |
| 云账号 | Azure subscription、AWS account、GCP project | account/project/subscription 元数据、允许动作 |
@@ -87,11 +87,11 @@ Resource Binding 建议字段：
| 字段 | 含义 | 约束 |
|------|------|------|
| `id` | 资源绑定 ID | Manager 内部生成 |
| `user_id` | 登录用户 ID | 来自 Heicode/Agnet 登录体系的 `user.id` 或 JWT `sub` |
| `user_id` | 登录用户 ID | 来自 Heicode/Agent 登录体系的 `user.id` 或 JWT `sub` |
| `type` | 资源类型 | `git`、`sk`、`project_doc`、`cloud_account`、`cloud_resource` |
| `name` | 用户可见名称 | 不包含密钥 |
| `external_ref` | 外部资源定位 | repo URL、subscription ID、resource ID、文档引用等非密钥标识 |
| `metadata` | 子 Agnet 可见元数据 | 只包含 ref、允许路径、环境、网络边界等非密钥信息 |
| `metadata` | 子 Agent 可见元数据 | 只包含 ref、允许路径、环境、网络边界等非密钥信息 |
| `permission_scope` | 可授权动作范围 | 例如 `read`、`write`、`deploy`、`approve_required` |
| `constraints` | 使用限制 | 路径、分支、环境、网络、审批要求、TTL 等 |
| `secret_ref` | Secret Store 引用 | 可为空；有凭证时只保存引用，不保存原文 |
@@ -105,8 +105,8 @@ Resource Grant 建议字段：
| `id` | 授权 ID | Manager 内部生成 |
| `user_id` / `binding_scope` | 授权归属 | 来自登录用户、绑定 Git/SK/云资源和角色范围 |
| `resource_id` | 被授权资源 | 指向 Resource Binding |
| `role` | 子 Agnet 角色 | 例如 product、frontend、backend、reviewer、ops |
| `agent_id` | 子 Agnet 标识 | 可为空；为空表示授予该项目角色下的下一次部署 |
| `role` | 子 Agent 角色 | 例如 product、frontend、backend、reviewer、ops |
| `agent_id` | 子 Agent 标识 | 可为空；为空表示授予该项目角色下的下一次部署 |
| `allowed_actions` | 本次授权动作 | 必须是 `permission_scope` 的子集 |
| `constraints` | 本次授权限制 | 不得放宽 Resource Binding 的限制 |
| `status` | 授权状态 | `active`、`suspended`、`revoked`、`expired` |
@@ -146,7 +146,7 @@ SaaS 场景下，凭证不能转嫁给用户手工管理。用户负责授权，
| 方案 | 判断 |
|------|------|
| HashiCorp Vault | 优先选择。Kubernetes Auth、Policy、TTL、动态密钥、审计能力成熟，适合 AKS 中的子 Agnet 运行时授权 |
| HashiCorp Vault | 优先选择。Kubernetes Auth、Policy、TTL、动态密钥、审计能力成熟，适合 AKS 中的子 Agent 运行时授权 |
| Infisical | 可选方案。产品体验较好，但需要验证 SaaS 多用户隔离策略和运行时授权能力 |
| Azure Key Vault | 适合 Azure 优先部署，也可以作为 Secret Provider 的一种实现 |
@@ -160,9 +160,9 @@ Secret Broker 负责：
- 轮换、撤销、禁用凭证。
- 避免密钥进入日志、前端响应、Markdown 和 Git。
## 七、AKS 上的 Agnet 凭证访问
## 七、AKS 上的 Agent 凭证访问
Agnet 平台底层是 AKS，因此运行时权限应和 Kubernetes 身份绑定。
Agent 平台底层是 AKS，因此运行时权限应和 Kubernetes 身份绑定。
推荐流程：
@@ -170,13 +170,13 @@ Agnet 平台底层是 AKS，因此运行时权限应和 Kubernetes 身份绑定
用户在 Manager 授权资源
-> Manager Secret Broker 写入 Secret Store
-> Manager 记录 Resource Grant
-> Manager 请求 Agnet 平台部署
-> Agnet 平台为 deployment / role 创建 K8s ServiceAccount
-> Agnet 平台绑定 Vault policy 或 Workload Identity
-> 子 Agnet Pod 运行时只能访问被授权的 secret
-> Manager 请求 Agent 平台部署
-> Agent 平台为 deployment / role 创建 K8s ServiceAccount
-> Agent 平台绑定 Vault policy 或 Workload Identity
-> 子 Agent Pod 运行时只能访问被授权的 secret
```
子 Agnet 拿到的是角色、目标、AGENT.md、resource context 和 permission manifest，不拿长期密钥。
子 Agent 拿到的是角色、目标、AGENT.md、resource context 和 permission manifest，不拿长期密钥。
运行时访问分两类：
@@ -209,7 +209,7 @@ Manager 不展示：
- 系统管理员用户管理。
- NewAPI 原生管理后台入口。
用户登录 Manager，不直接登录 NewAPI。Manager User 复用 Heicode/Agnet 登录体系，并维护 `user.id`、`channelId` 到 NewAPI 用户、Token、Group、quota 或 usage 的映射。当前不要把 Manager tenant/project 作为扣费和团队开发控制主轴；团队开发控制优先由绑定 Git、路径范围、资源授权和 Agnet 角色表达。子 Agnet 的模型选择、模型 profile 和实例数属于 Agnet 平台部署配置，不放进 NewAPI 扣费对象里。
用户登录 Manager，不直接登录 NewAPI。Manager User 复用 Heicode/Agent 登录体系，并维护 `user.id`、`channelId` 到 NewAPI 用户、Token、Group、quota 或 usage 的映射。当前不要把 Manager tenant/project 作为扣费和团队开发控制主轴；团队开发控制优先由绑定 Git、路径范围、资源授权和 Agent 角色表达。子 Agent 的模型选择、模型 profile 和实例数属于 Agent 平台部署配置，不放进 NewAPI 扣费对象里。
## 九、Markdown 与权限清单
@@ -217,7 +217,7 @@ Manager 不展示：
Markdown 可包含：
- 子 Agnet 角色。
- 子 Agent 角色。
- 目标任务。
- 项目背景。
- AGENT.md 来源。
@@ -240,7 +240,7 @@ Manager 应生成两类产物：
| 产物 | 用途 |
|------|------|
| AGENT.md / resource context | 给子 Agnet 的启动上下文，说明角色和可用资源 |
| permission manifest | 给 Agnet 平台和审计系统的结构化权限清单 |
| AGENT.md / resource context | 给子 Agent 的启动上下文，说明角色和可用资源 |
| permission manifest | 给 Agent 平台和审计系统的结构化权限清单 |
Markdown 面向模型理解，manifest 面向系统强制执行。