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