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