chore: initial import — heicode manager + website

2026-05-20 14:07:30 +08:00
commit 2a1d8d8191
2079 changed files with 481382 additions and 0 deletions
@@ -0,0 +1,341 @@
+# 12. 口述用户操作流程
+
+## 使用场景
+
+本文用于产品演示、培训、录屏旁白和销售讲解。语气以真实用户操作为主，不讲复杂技术实现；当需要解释安全、模型、密钥和 Agnet 平台时，只讲用户需要理解的边界。
+
+## 一句话开场
+
+> 我现在打开 Heicode，从一个产品想法开始，绑定我的代码和云资源，让平台生成 AI 开发团队，并在我确认权限和高危操作后推进开发、部署和维护。
+
+## 完整口述流程
+
+### 1. 打开平台
+
+我先打开 Heicode 的平台地址：
+
+```text
+https://code.xinghanlab.com
+```
+
+这里是 Heicode 的浏览器控制台，也就是 Heicode Manager。后续我不会直接进入 CodeGW 后台，也不会直接进入密钥保管器后台。Manager 负责资源、部署、状态和审计等辅助动作；真正持续推进开发任务和高危审批，主要会回到客户端完成。
+
+### 2. 登录账号
+
+我输入账号和密码登录。
+
+登录成功后，平台会识别我的用户身份，包括用户 ID、邮箱、角色和 `channelId`。这些信息用于后续模型额度、用量和审计归属。
+
+用户不需要理解 `channelId` 的技术细节，只需要知道：我的模型余额、调用记录和任务消耗都能在 Heicode 里看到。
+
+### 3. 进入首页
+
+登录后，我首先进入首页。
+
+首页会告诉我：
+
+- 当前有没有正在运行的任务。
+- 有没有失败任务。
+- 有没有待我审批的高危操作。
+- 我绑定了哪些资源。
+- 模型余额和今日用量。
+- 客户端是否已经下载。
+
+如果我是第一次使用，首页会提示我下一步：输入产品想法、绑定资源或下载客户端。
+
+### 4. 下载客户端
+
+如果我还没有安装客户端，我会先进入“客户端下载”。
+
+这里可以看到适合我系统的安装包，比如 macOS 或 Windows。下载安装后，我打开客户端。
+
+客户端只需要登录：
+
+```text
+https://code.xinghanlab.com
+```
+
+客户端不会让我选择模型提供方，也不会出现 旧服务入口 或其他旧入口。客户端里能用什么模型，由 Heicode 提供。
+
+### 5. 输入产品想法
+
+回到 Heicode 或客户端，我输入我的产品想法。
+
+比如我输入：
+
+```text
+我想做一个小团队任务管理 SaaS，
+需要登录、项目、任务、评论、通知和后台管理，
+希望部署到 Azure。
+```
+
+我不需要一开始就写完整 PRD。Heicode 会先理解我的目标，再帮我生成需求摘要、功能清单、原型描述和需要的资源。
+
+### 6. 查看平台生成的任务草案
+
+平台会根据我的输入生成一个任务草案。
+
+我可以看到：
+
+- 这个产品要解决什么问题。
+- 第一版包含哪些功能。
+- 推荐哪些页面和接口。
+- 需要哪些代码仓库、文档、SK 和云资源。
+- 建议使用哪些子 Agnet 角色。
+- 哪些操作可能属于高危操作。
+
+如果草案不准确，我可以直接修改。确认后，Heicode 会提示我补充这个任务需要的上下文。
+
+### 7. 绑定代码仓库
+
+在任务上下文卡片里，我先授权代码仓库。
+
+如果我已有项目仓库，我可以授权 GitHub、GitLab、Gitea、Gitee 或自建 Git。平台会让我选择仓库、分支和允许访问的路径。
+
+例如：
+
+- 仓库：`repo-main`
+- 分支：`main`
+- 后端路径：`services/api/**`
+- 前端路径：`web/**`
+
+这里的重点不是把 Git token 贴在页面里，而是完成授权。真实凭证会进入密钥保管器，Heicode 只保存密钥引用。
+
+### 8. 绑定项目文档和 SK
+
+如果我有产品文档、原型描述或技能仓库，我继续绑定项目文档和 SK。
+
+项目文档可以作为 Product Agnet 和 Architect Agnet 的上下文。SK 可以作为子 Agnet 可调用的技能来源。
+
+绑定后，平台知道：
+
+- 哪些文档可以读。
+- 哪些技能可以使用。
+- 哪些路径和版本有效。
+
+### 9. 绑定云账号
+
+接下来我绑定云资源，比如 Azure、AWS 或 GCP。
+
+以 Azure 为例，我授权云账号后，平台会尽量自动发现我账号下的资源，比如：
+
+- 虚拟机。
+- 数据库。
+- 存储。
+- Kubernetes 或 AKS。
+- 资源组。
+
+我不应该手动填写一堆复杂资源 ID。正常体验应该是：平台发现资源，我选择哪些资源允许 Heicode 使用。
+
+### 10. 选择允许使用的云资源
+
+云账号授权后，我从自动发现列表里选择资源。
+
+例如：
+
+- 允许使用测试环境 AKS。
+- 允许读取开发数据库。
+- 不允许直接操作生产数据库。
+- 生产部署必须审批。
+
+保存后，这些云资源会变成 Resource Binding。
+
+### 11. 确认密钥保管状态
+
+资源绑定完成后，我能看到密钥保管状态。
+
+我看到的是：
+
+- 已托管。
+- 无需密钥。
+- 待补充。
+- 已撤销。
+- 异常。
+
+我不会看到明文密钥。平台最多展示 `secret_ref` 这种引用，让我知道凭证由密钥保管器管理。
+
+### 12. 生成子 Agnet 团队
+
+资源准备好后，Heicode 会推荐一组子 Agnet 角色。
+
+例如：
+
+- Product Agnet：负责需求和验收标准。
+- Architect Agnet：负责架构和技术方案。
+- Frontend Agnet：负责页面和交互。
+- Backend Agnet：负责 API、数据模型和服务逻辑。
+- Reviewer Agnet：负责代码检查和安全审查。
+- Ops Agnet：负责构建、部署和运行观察。
+
+我可以使用推荐团队，也可以增减角色。
+
+### 13. 分配资源权限
+
+接下来我确认每个角色可以使用哪些资源。
+
+例如：
+
+Backend Agnet 可以：
+
+- 读项目文档。
+- 读写后端代码路径。
+- 使用开发数据库。
+
+Frontend Agnet 可以：
+
+- 读项目文档。
+- 读写前端代码路径。
+
+Ops Agnet 可以：
+
+- 部署测试环境。
+- 请求生产部署审批。
+
+这一步不要求我手写复杂策略。页面应该用角色卡片告诉我：这个角色能用什么、能做什么、是否需要审批。
+
+### 14. 预览权限清单
+
+如果我想看更详细的权限，我可以打开 manifest 预览。
+
+这里会展示：
+
+- 资源 ID。
+- 资源类型。
+- 允许动作。
+- 限制条件。
+- `secret_ref`。
+
+manifest 不会显示 Git token、云 access key、SSH 私钥、数据库密码或 CodeGW key 原文。
+
+### 15. 确认开始执行
+
+在开始执行前，Heicode 会用一张确认卡展示本次任务摘要：
+
+- 本次要做什么。
+- 会启动哪些子 Agnet。
+- 每个子 Agnet 使用哪些资源。
+- 是否会访问密钥。
+- 是否会部署云资源。
+- 预计模型预算。
+- 哪些动作需要审批。
+
+确认无误后，我点击开始执行。真实部署动作仍由任务过程触发，并在高危场景下要求客户端审批。
+
+### 16. 客户端审批高危操作
+
+如果任务过程中出现高危操作，客户端会弹出审批。
+
+例如：
+
+```text
+Ops Agnet 请求部署到生产环境。
+目标资源：aks-prod
+操作：cloud:deploy
+风险等级：高
+凭证：密钥保管器将派生 15 分钟短期凭证
+```
+
+这时我可以批准或拒绝。
+
+如果我批准，平台会使用密钥保管器派生短期、最小权限凭证。子 Agnet 不会拿到长期密钥。
+
+### 17. 在客户端持续推进开发
+
+任务启动后，我不会停留在网页上编码，而是回到客户端继续推进。
+
+这里的真实闭环是：
+
+```text
+我在客户端补充要求
+-> Heicode 判断下一步要推进哪个子环节
+-> Agnet 执行需求、开发、测试、修复或部署中的当前任务
+-> Agnet 按权限调用已绑定的 SK 工具
+-> 中间结果回到客户端
+-> 我继续修正方向或批准高危动作
+-> Agnet 继续推进直到交付和部署完成
+```
+
+### 18. 查看执行状态
+
+任务启动后，我在 Heicode 里查看执行状态。
+
+我能看到：
+
+- Product Agnet 是否完成需求。
+- Backend Agnet 是否正在写代码。
+- Frontend Agnet 是否等待后端接口。
+- Reviewer Agnet 是否发现问题。
+- Ops Agnet 是否等待审批或部署中。
+
+如果失败，页面应该显示失败原因，而不是只显示一个错误码。
+
+### 19. 查看执行记录和模型用量
+
+我可以在当前任务里打开执行记录。
+
+这里能看到：
+
+- 子 Agnet 运行日志。
+- 模型调用日志。
+- 消耗了多少额度。
+- 哪个任务使用了哪个模型。
+- 哪些资源被访问。
+- 哪些高危操作被批准或拒绝。
+
+模型和余额来自 CodeGW，但我不需要进入 CodeGW 后台。Heicode 会展示用户需要知道的信息。
+
+### 19. 查看交付结果
+
+当任务完成后，我查看交付结果。
+
+结果可能包括：
+
+- 产品文档。
+- 原型描述。
+- 代码变更。
+- 测试结果。
+- 部署结果。
+- 访问地址。
+- 审计记录。
+
+如果部署到生产，我还可以看到部署时间、目标资源和审批记录。
+
+### 20. 后续维护和升级
+
+上线后，如果我想继续迭代，我可以直接输入新的需求。
+
+例如：
+
+```text
+给任务管理 SaaS 增加企业微信通知，
+并检查现有权限模型是否支持团队成员邀请。
+```
+
+Heicode 会复用之前的项目上下文、资源绑定和 Agnet 角色，生成新的开发任务。
+
+## 简短演示口述版
+
+> 我先登录 Heicode 的浏览器控制台。这里不是 CodeGW 后台，而是资源、部署、状态和审计的辅助入口。登录后，我会在客户端输入一个产品想法，比如做一个小团队任务管理 SaaS。平台会生成需求草案、推荐资源和子 Agnet 团队。接下来我绑定 Git 仓库、项目文档、SK 和云资源。真实密钥会进入密钥保管器，Heicode 只保存 secret_ref。然后我确认每个子 Agnet 的角色和权限，比如 Backend 能写后端路径，Ops 可以部署测试环境，但生产部署需要客户端审批。任务运行后，Agnet 会持续推进开发、测试和部署，并按权限调用需要的 SK 工具；我可以看到每个子 Agnet 的状态、日志、模型用量和审计记录。客户端只登录 code.xinghanlab.com，不选择模型提供方，模型由 Heicode 提供。整个流程的重点是：从一个想法开始，把产品、代码、云资源、模型、密钥和审计组织成一个完整的软件生命周期。
+
+## 极简销售口述版
+
+> Heicode 让用户从一个想法开始，接入自己的代码和云资源，由 Heicode 生成 AI 开发团队。平台负责资源授权、密钥保管、模型用量和审计；子 Agnet 负责开发、检查和部署。用户只在 Heicode 和客户端中操作，不需要进入 CodeGW 后台，也不会把长期密钥交给子 Agnet。
+
+## 口述时必须强调
+
+1. Heicode 是用户主入口。
+2. 客户端只登录 Heicode。
+3. CodeGW 是内部模型网关，不是普通用户后台。
+4. 密钥进入密钥保管器，不进入 Git、Markdown 或日志。
+5. 高危操作在客户端审批。
+6. 子 Agnet 拿短期凭证，不拿长期密钥。
+7. 资源绑定和权限分配要尽量自动化和角色化。
+
+## 口述时不要说
+
+1. 让用户去 CodeGW 后台配置模型。
+2. 让用户去 OpenBao 控制台管理密钥。
+3. 让客户端选择模型提供方。
+4. 让用户手写复杂 manifest。
+5. 把 tenant/project 当作当前产品主轴。
+6. 把 Agnet 平台说成用户控制台。