# 10. 前端细节说明

## 目标

本文用于指导 Heicode 和 Heicode 客户端的前端产品设计。重点不是罗列后台页面，而是明确用户如何在一个任务空间里完成“想法 -> 追问 -> 上下文授权 -> 执行 -> 审批 -> 交付”。

## 设计原则

1. 第一屏只强调“你想做什么”。
2. 主流程围绕当前任务展开，不围绕后台模块展开。
3. 资源、权限、模型、日志和审计都作为任务上下文出现。
4. 复杂配置默认由 Heicode 解释成确认卡片，高级细节可以展开。
5. 密钥永不明文展示，只展示密钥保管状态和 `secret_ref`。
6. 客户端只登录 Heicode，只展示 Heicode 提供的模型。
7. 页面状态必须覆盖空态、加载、错误、成功、撤销和过期。

## 全局体验结构

Heicode 不以后台菜单作为主体验。建议使用顶部轻量入口和主任务空间：

| 入口 | 作用 | 出现方式 |
|------|------|----------|
| 输入想法 | 创建新产品、新功能或维护任务 | 首屏主输入框 |
| 当前任务 | 查看草案、上下文、执行状态和下一步 | 首页主区域和任务详情 |
| 资源上下文 | 选择本任务可用的代码、文档、SK、云资源 | 任务准备卡片 |
| 风险确认 | 确认可用资源、禁止动作和审批规则 | 开始执行前确认卡 |
| 执行记录 | 查看日志、用量、资源访问和审计 | 任务详情抽屉 |
| 客户端下载 | 下载本地客户端并完成高危审批 | 顶部辅助入口或审批提示 |

产品面边界需要在信息架构中明确：

- Heicode 客户端是主任务驾驶舱。
- Heicode Manager 是资源、部署、状态、余额和审计的辅助控制台。
- 用户不在网页上编码，但会在网页完成辅助管理动作。

禁止普通用户体验出现：

- CodeGW 后台。
- 渠道管理。
- 模型供应商配置。
- OpenBao 控制台。
- 模型提供方选择。
- 旧服务入口。

## 视觉风格

| 元素 | 要求 |
|------|------|
| 色系 | Heicode 与客户端保持统一，专业、可信、低噪音 |
| 布局 | 任务空间优先，辅助信息以抽屉、浮层或卡片呈现 |
| 卡片 | 只用于任务、上下文、审批、交付物等明确对象 |
| 按钮 | 主按钮用于继续任务，次按钮用于查看详情或取消 |
| 状态 | 使用清晰标签：待确认、运行中、待审批、失败、已完成、已撤销 |
| 图标 | 资源、审批、日志、模型、客户端下载使用稳定图标语义 |

## 初始首页

### 目标

让用户登录后马上知道可以输入想法或继续任务。

### 内容

| 区块 | 内容 |
|------|------|
| 主输入 | “你想把什么想法变成可以上线的软件？” |
| 继续任务 | 最近任务、运行状态、待审批提示 |
| 今日焦点 | 当前最重要任务、失败任务、待确认事项 |
| 辅助入口 | 客户端下载、账户安全、最近审计 |

### 空态文案

> 输入一个产品想法，Heicode 会帮你生成任务、需要的上下文和执行计划。

## 想法输入与追问

### 目标

把用户自然语言输入转成可执行任务，而不是让用户先填完整表单。

### 初始输入

只展示一个多行输入框。用户可以说产品想法、开发任务、修复目标或维护诉求。

### Heicode 追问

Heicode 只追问影响执行路径的少量问题：

| 问题 | 选项示例 |
|------|----------|
| 是否基于已有代码 | 从零开始 / 选择已有仓库 |
| 是否需要部署 | 暂不部署 / 测试环境 / 生产环境需审批 |
| 执行风格 | 保守 / 平衡 / 主动 |
| 预算限制 | 使用默认 / 自定义预算 |

更多约束放在“继续补充要求”中，不作为第一屏表单。

## 任务卡

### 目标

让用户确认“我要做什么”和“第一版做到哪里”。

### 内容

| 区块 | 内容 |
|------|------|
| 目标 | Heicode 总结的产品或任务目标 |
| 第一版范围 | 功能清单、交付边界、暂不做事项 |
| 自动生成 | 产品说明、原型描述、开发任务、检查清单、部署步骤 |
| 待确认上下文 | 代码和文档、云资源、风险审批 |

### 交互

- 用户可以直接修改目标。
- 用户可以继续用自然语言补充要求。
- 下一步不是“去配置资源”，而是“确认任务，准备上下文”。

## 任务上下文卡

### 目标

让用户理解这个任务需要哪些上下文，并用最少操作授权。

### 卡片类型

| 卡片 | 用户看到的内容 | 系统处理 |
|------|----------------|----------|
| 代码上下文 | 选择仓库或从零开始 | 保存仓库元数据和授权引用 |
| 文档和 SK | 选择已有产品文档或 SK 仓库 | 作为任务上下文提供给执行层 |
| 云资源 | 连接云账号并自动发现资源 | 展示可用资源和风险级别 |
| 密钥保管 | 凭证将保存到密钥保管器 | 前端不展示明文密钥 |

### 简化要求

- 云账号绑定后优先自动发现 VM、数据库、对象存储、Kubernetes 或资源组。
- 不要求用户手写 VM ID、数据库 ID、AKS ID 等复杂字段。
- 对不能自动发现的资源提供“手动补充”兜底，但放在次级入口。
- 默认推荐低风险资源，高风险资源默认不选。

## 执行前确认卡

### 目标

让用户在开始前确认结果、边界和风险。

### 内容

| 区块 | 内容 |
|------|------|
| 本次会做 | 需求、代码、检查、测试部署等 |
| 本次允许使用 | 仓库、文档、SK、测试云资源 |
| 本次不会做 | 生产部署、生产数据库访问、导出长期密钥 |
| 高危规则 | 生产部署、生产密钥访问、破坏性操作必须客户端审批 |
| 预计消耗 | 模型预算或任务预算 |

### 高级展开

高级用户可以展开 manifest 预览，但默认折叠。展开后只展示：

- `resource_id`
- `resource_type`
- `allowed_actions`
- `constraints`
- `secret_ref`

不得展示明文密钥。

## 执行中的任务空间

### 目标

让用户看到任务进展、产物和下一步。

### 内容

| 区块 | 内容 |
|------|------|
| 当前子环节 | 需求、设计、后端、前端、检查、测试、部署的阶段状态 |
| Agnet 调用 | 当前角色、正在调用的 SK 工具、工具输出摘要 |
| 最新动态 | Heicode 翻译后的关键执行事件 |
| 当前产物 | 产品文档、接口草案、代码变更、检查报告 |
| 继续输入 | 用户继续追加需求或修正方向 |
| 交付回流 | 交付物、测试结果、部署结果、待审批动作 |
| 辅助查看 | 资源使用、模型消耗、审计记录、停止任务 |

### 交互要求

- 日志默认摘要化，用户需要时再展开原始日志。
- 失败必须展示可理解原因和建议动作。
- 停止任务要说明影响范围。
- 当前子环节必须可见，不能只显示“运行中”。
- 如果 Agnet 调用了 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 分钟短期凭证。请确认资源、范围和影响后再批准。

## 响应式要求

| 视口 | 要求 |
|------|------|
| 桌面 | 顶部入口 + 主任务空间 + 可选右侧上下文 |
| 平板 | 顶部入口收进更多操作，主流程保持单列 |
| 手机 | 只保留继续输入、查看状态和审批能力 |

## 状态清单

每个关键状态必须设计：

- 加载态。
- 空态。
- 成功态。
- 错误态。
- 权限不足态。
- 网络异常态。
- 撤销/禁用后的只读态。

## 文案规则

- 用“任务上下文”或“资源上下文”，不要把主流程叫成资源管理。
- 用“密钥保管器”，不用“OpenBao”作为普通用户标题。
- 用“客户端”，不用“本地模型提供方”。
- 用“模型与余额”，不用“CodeGW 后台”。
- 用“执行计划”，不用“控制面草案”。