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>
5.2 KiB
5.2 KiB
03. 用户旅程与核心流程
旅程目标
用户从“我有一个想法”开始，不需要先学习 Agent、CodeGW、密钥保管器或部署系统。Heicode 应该用一个连续流程带用户完成：
想法
-> 资源
-> 团队
-> 权限
-> 执行
-> 上线
-> 维护
用户旅程总览
| 阶段 | 用户动作 | 平台动作 | 输出 |
|---|---|---|---|
| 1. 登录 | 注册或登录 Heicode | 获取用户身份和 channelId | 用户会话 |
| 2. 输入想法 | 描述要做的产品或任务 | 生成需求摘要和任务草案 | 需求草案 |
| 3. 绑定资源 | 授权 Git、文档、SK、云资源 | 保存资源元数据和 secret_ref |
Resource Binding |
| 4. 生成团队 | 确认开发方法和角色 | 推荐子 Agent 角色 | 角色方案 |
| 5. 分配权限 | 确认每个角色能用什么 | 生成 Resource Grant | 权限清单 |
| 6. 审批高危操作 | 在客户端确认高危动作 | 记录 approval | 审批记录 |
| 7. 执行任务 | 持续追加需求、查看进度 | Agent 平台运行子 Agent，按子环节推进开发 | 状态、日志、事件 |
| 8. SK 工具调用 | 允许平台使用技能能力 | Agent 按权限调用 SK 工具和外部能力 | 中间产物、检查结果 |
| 9. 交付上线 | 确认部署结果 | Agent 完成交付整理、部署并回写审计 | 生产服务 |
| 10. 维护升级 | 提出迭代或修复 | 复用上下文和权限再次进入 Agent 闭环 | 新版本计划 |
关键任务状态流程
1. 初始入口
用户看到：
- 当前任务。
- 任务上下文状态。
- 模型余额和用量。
- 最近失败或待审批项。
- 客户端下载入口。
页面目标：
- 让用户知道下一步该做什么。
- 避免用户先进入复杂配置页。
2. 想法输入与追问
用户输入：
- 产品想法。
- 目标用户。
- 功能范围。
- 已有代码或是否从零开始。
- 部署目标。
- 风险和约束。
平台输出：
- 需求摘要。
- 产品文档草案。
- 原型描述。
- 推荐资源需求。
- 推荐子 Agent 角色。
3. 任务上下文准备
用户应该看到简化路径：
Heicode 判断本任务缺少哪些上下文
-> 用户授权代码、文档、SK 或云账号
-> 平台自动发现资源
-> 用户确认本任务允许使用的资源范围
-> Heicode 保存元数据和 secret_ref
任务上下文不要设计成大量裸字段表单。云账号授权后，应尽量自动展示已发现的 VM、数据库、对象存储、Kubernetes 或资源组。
4. 风险和权限确认卡
默认展示角色视角：
Backend Agent
- 可读写：后端代码路径
- 可读：项目文档
- 可部署：测试环境
- 生产部署：需要审批
高级用户可以打开 manifest 预览，但普通流程不应要求用户手写 manifest。
5. 开始执行前确认
展示：
- 本次目标。
- 子 Agent 数量和角色。
- 每个角色使用的资源。
- 是否会访问密钥。
- 是否会部署云资源。
- 预计模型预算。
- 审批项。
用户确认后，Heicode 生成 Agent 平台 payload。
6. 执行中的任务空间
展示：
- 子 Agent 活跃状态。
- 当前步骤。
- 最近日志。
- 失败原因。
- 模型用量。
- 资源访问记录。
- 审批记录。
用户可以：
- 暂停任务。
- 停止任务。
- 查看日志。
- 撤销资源授权。
- 发起修复或继续迭代。
7. Agent 执行闭环
Heicode 不是只把任务丢给 Agent 一次就结束，而是会在开发过程中持续调用 Agent 完成子环节。
闭环应表达为：
客户端输入目标或追加需求
-> Heicode 生成下一步任务
-> Agent 执行需求/设计/开发/测试/修复中的当前子环节
-> Agent 按需要调用已授权的 SK 工具
-> Heicode 回传中间结果给客户端
-> 用户继续追问、修正或审批
-> Agent 继续下一子环节
-> 最终由 Agent 完成交付整理与部署
这意味着用户看到的不是一次性“已部署 Agent”，而是一个可连续推进的开发循环。
简化原则
- 用户先表达目标，再补资源。
- 用户选择资源，不手写底层配置。
- 用户选择角色权限，不手写策略。
- 高危操作单独审批，不埋在复杂表单里。
- 技术细节可展开，但默认隐藏。
- 所有资源、权限、模型、日志都回到同一个任务视角。
复杂度拆解
资源绑定复杂度来自三类问题：
| 复杂点 | 简化方式 |
|---|---|
| 云资源字段多 | 绑定云账号后自动发现资源 |
| 权限动作多 | 使用角色模板和推荐权限 |
| 密钥安全难理解 | 用户只看“密钥保管器已托管”，不看明文 |
MVP 用户路径
MVP 最小路径：
- 用户登录 Heicode。
- 下载并登录客户端。
- 输入一个产品想法。
- 绑定一个 Git 仓库。
- 绑定一个云账号或导入云资源。
- 选择推荐角色。
- 确认资源权限。
- 预览 manifest。
- 创建 Agent 部署占位任务。
- 在客户端持续推进子环节开发与测试。
- 查看任务状态、日志、审计和交付结果。
当前唯一可延期项：Heicode 到 Agent 平台真实部署 API 的完整联调。