heicode/docs/product-package/13-platform-description.md

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. 想法输入

用户可以用自然语言描述产品想法或开发任务。平台会生成需求摘要、功能清单、原型描述、任务计划和需要的资源建议。

示例：

我想做一个小团队任务管理 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 完成子环节。

完整闭环应表达为：

客户端输入想法或追加需求
-> Manager 准备资源和部署条件
-> Heicode 调度 Agent 执行当前子环节
-> Agent 完成需求/开发/测试/修复/部署中的一步
-> Agent 按权限调用 SK 工具
-> 中间结果和状态回传给客户端与 Manager
-> 用户继续补充、修正或审批
-> 最终由 Agent 完成交付整理和部署

4. 权限分配

Heicode 使用 Resource Grant 描述“哪个角色能用哪个资源、能做什么、是否需要审批”。

示例：

Backend Agent
-> 可读项目文档
-> 可读写后端代码路径
-> 可访问开发数据库
-> 生产数据库访问需要审批

普通用户看到的是角色和权限摘要，高级用户可以预览 permission manifest。

5. 高危操作审批

高危操作必须在客户端审批。

高危操作包括：

• 生产部署。
• 云资源创建、删除、扩缩容。
• 数据库迁移或写入。
• 访问生产密钥。
• 大额模型预算消耗。

审批通过后，平台可以从密钥保管器派生短期、最小权限凭证给子 Agent 使用。

6. 模型与余额

Heicode 展示用户可见的模型、余额、额度、用量和调用日志。这些能力来自 CodeGW，但普通用户不需要进入 CodeGW 后台。

用户能看到：

• 可用模型。
• 当前余额。
• 当前额度。
• 今日消耗。
• 调用日志。
• 失败日志。

用户看不到：

• 渠道管理。
• 模型供应商后台配置。
• 价格配置。
• CodeGW 管理员设置。

7. 日志与审计

Heicode 统一展示任务执行、模型调用、资源访问、高危审批和部署记录。

审计要能回答：

谁
在什么时候
为了哪个任务
让哪个子 Agent
使用了哪个资源
执行了什么操作
是否经过审批
消耗了多少模型额度

8. 部署和维护

Agent 平台负责执行开发、检查、测试、修复和部署任务。Heicode 展示部署状态、失败原因、日志、指标和审计。

上线后，用户可以继续输入维护和升级需求，平台复用已有项目上下文、资源绑定和权限规则。

四、用户使用流程

完整流程：

登录 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 安全、可审计地使用用户授权的外部资源，同时不把用户拉进资源管理后台。

任务上下文准备流程：

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 后台或密钥保管器后台。