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>
10 KiB
10 KiB
10. 前端细节说明
目标
本文用于指导 Heicode 和 Heicode 客户端的前端产品设计。重点不是罗列后台页面，而是明确用户如何在一个任务空间里完成“想法 -> 追问 -> 上下文授权 -> 执行 -> 审批 -> 交付”。
设计原则
- 第一屏只强调“你想做什么”。
- 主流程围绕当前任务展开，不围绕后台模块展开。
- 资源、权限、模型、日志和审计都作为任务上下文出现。
- 复杂配置默认由 Heicode 解释成确认卡片，高级细节可以展开。
- 密钥永不明文展示，只展示密钥保管状态和
secret_ref。 - 客户端只登录 Heicode，只展示 Heicode 提供的模型。
- 页面状态必须覆盖空态、加载、错误、成功、撤销和过期。
全局体验结构
Heicode 不以后台菜单作为主体验。建议使用顶部轻量入口和主任务空间：
| 入口 | 作用 | 出现方式 |
|---|---|---|
| 输入想法 | 创建新产品、新功能或维护任务 | 首屏主输入框 |
| 当前任务 | 查看草案、上下文、执行状态和下一步 | 首页主区域和任务详情 |
| 资源上下文 | 选择本任务可用的代码、文档、SK、云资源 | 任务准备卡片 |
| 风险确认 | 确认可用资源、禁止动作和审批规则 | 开始执行前确认卡 |
| 执行记录 | 查看日志、用量、资源访问和审计 | 任务详情抽屉 |
| 客户端下载 | 下载本地客户端并完成高危审批 | 顶部辅助入口或审批提示 |
产品面边界需要在信息架构中明确：
- Heicode 客户端是主任务驾驶舱。
- Heicode Manager 是资源、部署、状态、余额和审计的辅助控制台。
- 用户不在网页上编码，但会在网页完成辅助管理动作。
禁止普通用户体验出现：
- CodeGW 后台。
- 渠道管理。
- 模型供应商配置。
- Azure Key Vault 控制台。
- 模型提供方选择。
- 旧服务入口。
视觉风格
| 元素 | 要求 |
|---|---|
| 色系 | Heicode 与客户端保持统一，专业、可信、低噪音 |
| 布局 | 任务空间优先，辅助信息以抽屉、浮层或卡片呈现 |
| 卡片 | 只用于任务、上下文、审批、交付物等明确对象 |
| 按钮 | 主按钮用于继续任务，次按钮用于查看详情或取消 |
| 状态 | 使用清晰标签：待确认、运行中、待审批、失败、已完成、已撤销 |
| 图标 | 资源、审批、日志、模型、客户端下载使用稳定图标语义 |
初始首页
目标
让用户登录后马上知道可以输入想法或继续任务。
内容
| 区块 | 内容 |
|---|---|
| 主输入 | “你想把什么想法变成可以上线的软件？” |
| 继续任务 | 最近任务、运行状态、待审批提示 |
| 今日焦点 | 当前最重要任务、失败任务、待确认事项 |
| 辅助入口 | 客户端下载、账户安全、最近审计 |
空态文案
输入一个产品想法，Heicode 会帮你生成任务、需要的上下文和执行计划。
想法输入与追问
目标
把用户自然语言输入转成可执行任务，而不是让用户先填完整表单。
初始输入
只展示一个多行输入框。用户可以说产品想法、开发任务、修复目标或维护诉求。
Heicode 追问
Heicode 只追问影响执行路径的少量问题：
| 问题 | 选项示例 |
|---|---|
| 是否基于已有代码 | 从零开始 / 选择已有仓库 |
| 是否需要部署 | 暂不部署 / 测试环境 / 生产环境需审批 |
| 执行风格 | 保守 / 平衡 / 主动 |
| 预算限制 | 使用默认 / 自定义预算 |
更多约束放在“继续补充要求”中，不作为第一屏表单。
任务卡
目标
让用户确认“我要做什么”和“第一版做到哪里”。
内容
| 区块 | 内容 |
|---|---|
| 目标 | Heicode 总结的产品或任务目标 |
| 第一版范围 | 功能清单、交付边界、暂不做事项 |
| 自动生成 | 产品说明、原型描述、开发任务、检查清单、部署步骤 |
| 待确认上下文 | 代码和文档、云资源、风险审批 |
交互
- 用户可以直接修改目标。
- 用户可以继续用自然语言补充要求。
- 下一步不是“去配置资源”，而是“确认任务，准备上下文”。
任务上下文卡
目标
让用户理解这个任务需要哪些上下文，并用最少操作授权。
卡片类型
| 卡片 | 用户看到的内容 | 系统处理 |
|---|---|---|
| 代码上下文 | 选择仓库或从零开始 | 保存仓库元数据和授权引用 |
| 文档和 SK | 选择已有产品文档或 SK 仓库 | 作为任务上下文提供给执行层 |
| 云资源 | 连接云账号并自动发现资源 | 展示可用资源和风险级别 |
| 密钥保管 | 凭证将保存到密钥保管器 | 前端不展示明文密钥 |
简化要求
- 云账号绑定后优先自动发现 VM、数据库、对象存储、Kubernetes 或资源组。
- 不要求用户手写 VM ID、数据库 ID、AKS ID 等复杂字段。
- 对不能自动发现的资源提供“手动补充”兜底，但放在次级入口。
- 默认推荐低风险资源，高风险资源默认不选。
执行前确认卡
目标
让用户在开始前确认结果、边界和风险。
内容
| 区块 | 内容 |
|---|---|
| 本次会做 | 需求、代码、检查、测试部署等 |
| 本次允许使用 | 仓库、文档、SK、测试云资源 |
| 本次不会做 | 生产部署、生产数据库访问、导出长期密钥 |
| 高危规则 | 生产部署、生产密钥访问、破坏性操作必须客户端审批 |
| 预计消耗 | 模型预算或任务预算 |
高级展开
高级用户可以展开 manifest 预览，但默认折叠。展开后只展示：
resource_idresource_typeallowed_actionsconstraintssecret_ref
不得展示明文密钥。
执行中的任务空间
目标
让用户看到任务进展、产物和下一步。
内容
| 区块 | 内容 |
|---|---|
| 当前子环节 | 需求、设计、后端、前端、检查、测试、部署的阶段状态 |
| Agent 调用 | 当前角色、正在调用的 SK 工具、工具输出摘要 |
| 最新动态 | Heicode 翻译后的关键执行事件 |
| 当前产物 | 产品文档、接口草案、代码变更、检查报告 |
| 继续输入 | 用户继续追加需求或修正方向 |
| 交付回流 | 交付物、测试结果、部署结果、待审批动作 |
| 辅助查看 | 资源使用、模型消耗、审计记录、停止任务 |
交互要求
- 日志默认摘要化，用户需要时再展开原始日志。
- 失败必须展示可理解原因和建议动作。
- 停止任务要说明影响范围。
- 当前子环节必须可见，不能只显示“运行中”。
- 如果 Agent 调用了 SK 工具，前端要展示“调用了什么、产出了什么、是否失败”。
- 交付和部署结果必须回到客户端任务空间，而不是只留在后台日志里。
任务用量与审计
目标
回答“本任务用了什么模型、访问了什么资源、谁批准了什么”。
呈现方式
默认作为任务详情里的抽屉或浮层，不作为主体验。
内容
| 类型 | 示例 |
|---|---|
| 模型用量 | 任务、模型、消耗、状态、失败原因 |
| 资源访问 | 仓库、文档、云资源、动作、角色 |
| 审批记录 | 批准、拒绝、过期、有效期 |
| 安全记录 | 密钥轮换、短期凭证租约、撤销 |
交付结果
目标
让用户看到完成结果、质量证明和下一步。
内容
| 区块 | 内容 |
|---|---|
| 交付物 | 产品说明、代码变更、测试环境、部署链接 |
| 质量结果 | 代码检查、安全检查、测试结果 |
| 可信记录 | 使用资源、模型消耗、高危审批 |
| 继续动作 | 继续迭代、发起维护任务、查看完整记录 |
客户端下载
目标
让用户清楚下载哪个客户端，以及安装后只登录 Heicode。
内容
| 区块 | 内容 |
|---|---|
| 推荐版本 | 根据系统提示 macOS 或 Windows |
| 下载列表 | macOS arm64、Windows |
| 安装说明 | macOS 安全提示、Windows 安装说明 |
| 登录说明 | 只登录 https://code.xinghanlab.com |
| 版本信息 | 版本号、构建时间、校验值 |
账户与安全
目标
管理账号基础信息、安全设置和通知。
禁止
- 不自动生成无法解释的普通密钥。
- 若未来需要 API 令牌，命名为“Heicode API 访问令牌”，并说明用途、权限、过期时间和撤销方式。
- 无用途的 Token 入口应删除。
客户端前端细节
登录
只保留：
- Heicode 品牌。
- Heicode 登录按钮。
- 登录地址说明：
https://code.xinghanlab.com。 - 登录失败提示。
不出现：
- 模型提供方卡片。
- 旧服务入口。
- 第三方路由入口。
- Claude 默认模型说明。
主对话
显示：
- 当前任务。
- 输入框。
- Heicode 提供的模型列表。
- 文件和资源上下文。
- 执行状态。
高危审批
字段：
- 操作名称。
- 风险等级。
- 目标资源。
- 请求角色。
- 有效期。
- 是否需要短期凭证。
- 批准/拒绝按钮。
文案示例：
Heicode 请求在生产环境执行数据库迁移。该操作将使用密钥保管器派生的 15 分钟短期凭证。请确认资源、范围和影响后再批准。
响应式要求
| 视口 | 要求 |
|---|---|
| 桌面 | 顶部入口 + 主任务空间 + 可选右侧上下文 |
| 平板 | 顶部入口收进更多操作，主流程保持单列 |
| 手机 | 只保留继续输入、查看状态和审批能力 |
状态清单
每个关键状态必须设计：
- 加载态。
- 空态。
- 成功态。
- 错误态。
- 权限不足态。
- 网络异常态。
- 撤销/禁用后的只读态。
文案规则
- 用“任务上下文”或“资源上下文”，不要把主流程叫成资源管理。
- 用“密钥保管器”，不要用具体实现名作为普通用户标题。
- 用“客户端”，不用“本地模型提供方”。
- 用“模型与余额”，不用“CodeGW 后台”。
- 用“执行计划”，不用“控制面草案”。