chenchenandClaude Opus 4.8
0fe1d20d67
按桌面客户端统一方案 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>
395 lines
12 KiB
Markdown
395 lines
12 KiB
Markdown
# 13. 平台说明文档
|
||
|
||
## 文档目的
|
||
|
||
本文用于向用户、团队、客户和合作方说明 Heicode 平台是什么、由哪些部分组成、用户如何使用、各系统如何协作，以及平台如何处理模型、权限、密钥和审计。
|
||
|
||
产品说明文档重点回答“为什么需要 Heicode”；平台说明文档重点回答“Heicode 如何被使用、如何运转”。
|
||
|
||
## 一、平台概述
|
||
|
||
Heicode 是一款面向全流程智能开发的 SaaS 平台。用户注册登录后，可以从一个产品想法开始，接入自己的代码仓库、项目文档、SK 技能和云资源，由平台生成 AI 开发团队，完成需求、开发、检查、部署、观测和后续维护。
|
||
|
||
Heicode 平台由五个主要部分组成：
|
||
|
||
| 部分 | 用户理解 | 平台职责 |
|
||
|------|----------|----------|
|
||
| Heicode Manager | 浏览器辅助控制台 | 账号与安全、客户端下载、绑定资源、部署 Agent、查看状态、余额和审计 |
|
||
| Heicode 客户端 | 本地主体验和审批入口 | 登录 Heicode、输入任务、继续开发、查看反馈、接收交付结果、审批高危操作 |
|
||
| Agent 平台 | AI 开发团队执行层 | 在 AKS 上运行子 Agent，回传状态、日志、事件和指标 |
|
||
| CodeGW | 模型与用量底座 | 提供模型调用、余额、额度、用量和调用日志 |
|
||
| 密钥保管器 | 凭证托管服务 | 保存长期密钥，按审批和权限生成短期访问能力 |
|
||
|
||
用户主要使用客户端和 Manager。CodeGW、密钥保管器和 Agent 平台是底层能力，不作为普通用户日常操作后台。
|
||
|
||
## 二、平台适合谁
|
||
|
||
| 用户 | 使用场景 |
|
||
|------|----------|
|
||
| 独立开发者 | 从一个想法开始生成 MVP，并部署上线 |
|
||
| 创业团队 | 用较少人力完成产品迭代、测试和部署 |
|
||
| 企业创新团队 | 在已有代码仓库和云资源边界内使用 AI 开发 |
|
||
| 技术负责人 | 控制资源权限、模型消耗、安全审批和审计 |
|
||
| 运维负责人 | 管理部署、运行日志、资源访问和生产操作审批 |
|
||
|
||
## 三、平台核心能力
|
||
|
||
### 1. 想法输入
|
||
|
||
用户可以用自然语言描述产品想法或开发任务。平台会生成需求摘要、功能清单、原型描述、任务计划和需要的资源建议。
|
||
|
||
示例：
|
||
|
||
```text
|
||
我想做一个小团队任务管理 SaaS，
|
||
需要登录、项目、任务、评论、通知和后台管理，
|
||
希望部署到 Azure。
|
||
```
|
||
|
||
### 2. 资源绑定
|
||
|
||
用户可以把外部资源授权给 Heicode 使用。
|
||
|
||
资源类型包括：
|
||
|
||
- Git 仓库。
|
||
- SK 仓库或技能包。
|
||
- 项目文档。
|
||
- 云账号。
|
||
- 云资源，例如 VM、数据库、对象存储、Kubernetes。
|
||
|
||
资源绑定不是简单保存密钥，而是生成可分配、可撤销、可审计的资源授权基础。
|
||
|
||
### 3. AI 开发团队生成
|
||
|
||
平台根据任务目标推荐子 Agent 角色。
|
||
|
||
常见角色：
|
||
|
||
- Product Agent。
|
||
- Architect Agent。
|
||
- Frontend Agent。
|
||
- Backend Agent。
|
||
- Reviewer Agent。
|
||
- Ops Agent。
|
||
|
||
每个子 Agent 都有明确职责、可用资源、权限范围、模型配置和审计记录。
|
||
|
||
### 3.1 Agent 持续执行闭环
|
||
|
||
Heicode 不是把任务分发给 Agent 一次就结束，而是在继续开发中持续调用 Agent 完成子环节。
|
||
|
||
完整闭环应表达为：
|
||
|
||
```text
|
||
客户端输入想法或追加需求
|
||
-> Manager 准备资源和部署条件
|
||
-> Heicode 调度 Agent 执行当前子环节
|
||
-> Agent 完成需求/开发/测试/修复/部署中的一步
|
||
-> Agent 按权限调用 SK 工具
|
||
-> 中间结果和状态回传给客户端与 Manager
|
||
-> 用户继续补充、修正或审批
|
||
-> 最终由 Agent 完成交付整理和部署
|
||
```
|
||
|
||
### 4. 权限分配
|
||
|
||
Heicode 使用 Resource Grant 描述“哪个角色能用哪个资源、能做什么、是否需要审批”。
|
||
|
||
示例：
|
||
|
||
```text
|
||
Backend Agent
|
||
-> 可读项目文档
|
||
-> 可读写后端代码路径
|
||
-> 可访问开发数据库
|
||
-> 生产数据库访问需要审批
|
||
```
|
||
|
||
普通用户看到的是角色和权限摘要，高级用户可以预览 permission manifest。
|
||
|
||
### 5. 高危操作审批
|
||
|
||
高危操作必须在客户端审批。
|
||
|
||
高危操作包括：
|
||
|
||
- 生产部署。
|
||
- 云资源创建、删除、扩缩容。
|
||
- 数据库迁移或写入。
|
||
- 访问生产密钥。
|
||
- 大额模型预算消耗。
|
||
|
||
审批通过后，平台可以从密钥保管器派生短期、最小权限凭证给子 Agent 使用。
|
||
|
||
### 6. 模型与余额
|
||
|
||
Heicode 展示用户可见的模型、余额、额度、用量和调用日志。这些能力来自 CodeGW，但普通用户不需要进入 CodeGW 后台。
|
||
|
||
用户能看到：
|
||
|
||
- 可用模型。
|
||
- 当前余额。
|
||
- 当前额度。
|
||
- 今日消耗。
|
||
- 调用日志。
|
||
- 失败日志。
|
||
|
||
用户看不到：
|
||
|
||
- 渠道管理。
|
||
- 模型供应商后台配置。
|
||
- 价格配置。
|
||
- CodeGW 管理员设置。
|
||
|
||
### 7. 日志与审计
|
||
|
||
Heicode 统一展示任务执行、模型调用、资源访问、高危审批和部署记录。
|
||
|
||
审计要能回答：
|
||
|
||
```text
|
||
谁
|
||
在什么时候
|
||
为了哪个任务
|
||
让哪个子 Agent
|
||
使用了哪个资源
|
||
执行了什么操作
|
||
是否经过审批
|
||
消耗了多少模型额度
|
||
```
|
||
|
||
### 8. 部署和维护
|
||
|
||
Agent 平台负责执行开发、检查、测试、修复和部署任务。Heicode 展示部署状态、失败原因、日志、指标和审计。
|
||
|
||
上线后，用户可以继续输入维护和升级需求，平台复用已有项目上下文、资源绑定和权限规则。
|
||
|
||
## 四、用户使用流程
|
||
|
||
完整流程：
|
||
|
||
```text
|
||
登录 Heicode
|
||
-> 下载并登录客户端
|
||
-> 客户端输入产品想法
|
||
-> 查看任务草案
|
||
-> 绑定 Git / 文档 / SK / 云资源
|
||
-> 生成子 Agent 团队
|
||
-> 分配角色权限
|
||
-> 预览 permission manifest
|
||
-> 确认部署计划
|
||
-> Manager 部署 Agent
|
||
-> 客户端持续推进任务
|
||
-> 客户端审批高危操作
|
||
-> Agent 平台执行任务并调用 SK
|
||
-> Heicode 查看日志、用量、审计和交付结果
|
||
-> 后续维护和升级
|
||
```
|
||
|
||
## 五、平台组成说明
|
||
|
||
### 5.1 Heicode Manager
|
||
|
||
Heicode Manager 是浏览器辅助控制台。
|
||
|
||
用户在 Manager 中完成：
|
||
|
||
- 登录和查看首页。
|
||
- 绑定资源。
|
||
- 分配角色和权限。
|
||
- 创建或部署 Agent 任务。
|
||
- 查看模型和余额。
|
||
- 查看日志与审计。
|
||
- 下载客户端。
|
||
|
||
Manager 不应该变成 CodeGW 后台，也不应该要求用户直接管理底层密钥系统，更不应该承担网页编码主体验。
|
||
|
||
### 5.2 Heicode 客户端
|
||
|
||
客户端是用户本地交互入口。
|
||
|
||
客户端负责：
|
||
|
||
- 登录 Heicode。
|
||
- 输入对话和任务。
|
||
- 持续追加需求和修正方向。
|
||
- 展示 Heicode 提供的模型。
|
||
- 审批高危操作。
|
||
- 查看执行反馈和交付结果。
|
||
|
||
客户端不负责：
|
||
|
||
- 选择模型提供方。
|
||
- 配置 CodeGW 渠道。
|
||
- 直接访问密钥保管器。
|
||
- 保存长期云密钥。
|
||
|
||
### 5.3 Agent 平台
|
||
|
||
Agent 平台是运行时执行层。
|
||
|
||
它负责：
|
||
|
||
- 在 AKS 上部署子 Agent。
|
||
- 维护子 Agent 状态。
|
||
- 执行开发、检查、测试、修复、部署和维护任务。
|
||
- 在执行过程中按权限调用 SK 工具。
|
||
- 回传日志、事件、指标和审计数据。
|
||
- 按 Resource Grant 和运行时身份访问资源。
|
||
|
||
普通用户不直接操作 Agent 平台后台，而是在 Heicode 中查看 Agent 状态和结果。
|
||
|
||
### 5.4 CodeGW
|
||
|
||
CodeGW 是内部模型网关和计费服务。
|
||
|
||
它负责：
|
||
|
||
- 模型调用。
|
||
- 用户或 Token 维度的额度。
|
||
- 余额。
|
||
- 调用日志。
|
||
- 模型可用性。
|
||
|
||
Heicode 通过服务端调用 CodeGW，并把普通用户需要的信息展示出来。CodeGW 后台不对普通用户开放。
|
||
|
||
### 5.5 密钥保管器
|
||
|
||
密钥保管器用于保存长期凭证。当前技术实现是 Azure Key Vault。
|
||
|
||
生产环境中 Manager 使用 VM Managed Identity 访问 Azure Key Vault。用户绑定资源后，Manager 将敏感凭证写入 Key Vault，并在 Heicode 数据库中只保存 `azkv://<vault>/secrets/<name>` 形式的 `secret_ref`。
|
||
|
||
它负责：
|
||
|
||
- 保存 Git token、SSH key、云 access key、数据库密码等长期凭证。
|
||
- 为高危操作派生短期凭证。
|
||
- 支持撤销、轮换、禁用和审计。
|
||
|
||
用户不会直接看到明文密钥。Heicode 服务端数据库只保存 `secret_ref`。
|
||
|
||
## 六、任务资源上下文说明
|
||
|
||
任务资源上下文的目标是让 Heicode 安全、可审计地使用用户授权的外部资源，同时不把用户拉进资源管理后台。
|
||
|
||
任务上下文准备流程：
|
||
|
||
```text
|
||
Heicode 判断当前任务需要哪些上下文
|
||
-> 用户完成授权或连接配置
|
||
-> Heicode 保存资源元数据
|
||
-> Secret Broker 把凭证写入密钥保管器
|
||
-> Heicode 保存 secret_ref
|
||
-> 用户确认本任务允许使用的资源范围
|
||
```
|
||
|
||
云资源授权后应尽量自动发现资源。用户绑定 Azure、AWS 或 GCP 后，平台应展示可选择的 VM、数据库、对象存储、Kubernetes 或资源组，减少手工填写。
|
||
|
||
## 七、权限和审批说明
|
||
|
||
权限确认围绕当前任务和角色进行。
|
||
|
||
用户不需要手写复杂策略，只需要确认：
|
||
|
||
- 这个角色能看什么。
|
||
- 这个角色能改什么。
|
||
- 这个角色能部署到哪里。
|
||
- 哪些操作需要审批。
|
||
- 授权什么时候过期。
|
||
|
||
高危操作审批只在客户端完成。审批结果会进入任务上下文和审计记录。
|
||
|
||
## 八、模型和余额说明
|
||
|
||
用户在 Heicode 中查看模型与余额。
|
||
|
||
展示内容：
|
||
|
||
- 可用模型。
|
||
- 余额。
|
||
- 额度。
|
||
- 调用量。
|
||
- 调用日志。
|
||
- 失败日志。
|
||
|
||
子 Agent 的运行模型属于 Agent 平台部署配置，不等同于 CodeGW 后台的模型供应商配置。
|
||
|
||
## 九、密钥保管说明
|
||
|
||
长期密钥不会进入：
|
||
|
||
- Git。
|
||
- Markdown。
|
||
- 前端响应。
|
||
- 普通日志。
|
||
- 子 Agent 长期状态。
|
||
|
||
长期密钥进入密钥保管器。Heicode 保存 `secret_ref`。子 Agent 使用资源时，只获取短期、最小权限、可审计凭证。
|
||
|
||
## 十、平台边界
|
||
|
||
用户需要使用：
|
||
|
||
- Heicode。
|
||
- Heicode 客户端。
|
||
|
||
用户不需要直接使用：
|
||
|
||
- CodeGW 后台。
|
||
- Azure Key Vault 控制台。
|
||
- Agent 平台后台。
|
||
|
||
用户不应该看到：
|
||
|
||
- 模型提供方选择。
|
||
- 旧服务入口。
|
||
- 明文密钥。
|
||
- Azure Key Vault access token。
|
||
- CodeGW 管理员配置。
|
||
|
||
## 十一、常见问题
|
||
|
||
### 1. 我需要会写代码吗？
|
||
|
||
不一定。Heicode 的目标是让用户从自然语言想法开始。但如果用户已有代码仓库，平台可以更好地基于现有项目继续开发。
|
||
|
||
### 2. 我必须绑定 Git 吗？
|
||
|
||
如果要让子 Agent 修改代码，建议绑定 Git 仓库。只做产品文档或原型描述时，可以先不绑定代码仓库。
|
||
|
||
### 3. 我必须绑定云资源吗？
|
||
|
||
如果需要部署、测试环境或生产环境操作，就需要绑定云资源。只做需求、代码或本地检查时，可以先不绑定云资源。
|
||
|
||
### 4. 密钥安全吗？
|
||
|
||
平台设计上不把明文密钥保存到 Heicode 服务端数据库、Git、Markdown、日志或前端响应中。真实凭证进入密钥保管器，子 Agent 只使用短期、最小权限凭证。
|
||
|
||
### 5. 客户端必须安装吗？
|
||
|
||
客户端用于本地对话和高危操作审批。普通浏览器流程可以完成很多管理操作，但高危操作审批建议通过客户端完成。
|
||
|
||
### 6. CodeGW 是什么？
|
||
|
||
CodeGW 是 Heicode 的模型网关和计费服务。普通用户不需要进入 CodeGW 后台，只在 Heicode 中查看模型、余额、额度和调用日志。
|
||
|
||
### 7. Agent 是什么？
|
||
|
||
Agent 是平台生成的 AI 开发角色。不同 Agent 负责不同任务，例如产品、架构、前端、后端、审查和部署。
|
||
|
||
### 8. 生产部署怎么保证安全？
|
||
|
||
生产部署属于高危操作，需要客户端审批。审批通过后，平台按权限和 TTL 派生短期凭证，并记录完整审计。
|
||
|
||
### 9. 如果授权错了资源怎么办？
|
||
|
||
用户可以在任务资源上下文或权限确认卡中禁用、撤销或调整授权。撤销后，新的 permission manifest 不应再包含对应授权。
|
||
|
||
### 10. 平台会不会自动删除我的云资源？
|
||
|
||
不会默认执行高危操作。删除、生产部署、数据库写入等高危动作必须经过客户端审批。
|
||
|
||
## 十二、平台说明标准话术
|
||
|
||
> Heicode 是一个从想法到上线的软件生命周期平台。用户在 Heicode 中输入产品想法，绑定代码、文档、SK 和云资源。Heicode 生成子 Agent 团队和权限清单，客户端负责高危审批，Agent 平台负责执行开发和部署，CodeGW 提供模型和用量，密钥保管器保存长期凭证。用户只需要使用 Heicode 和客户端，不需要直接进入 CodeGW 后台或密钥保管器后台。
|