198 lines
20 KiB
Markdown
198 lines
20 KiB
Markdown
---
|
||
name: ARTEMIS 控制台
|
||
colors:
|
||
canvas: "#f8f9fa"
|
||
surface: "#ffffff"
|
||
text: "#1e293b"
|
||
text-strong: "#0f172a"
|
||
text-secondary: "#475569"
|
||
text-muted: "#64748b"
|
||
text-control: "#334155"
|
||
border: "#e2e8f0"
|
||
border-control: "#dbe3ec"
|
||
primary: "#1a73e8"
|
||
primary-hover: "#1557b0"
|
||
primary-soft: "#eff6ff"
|
||
exploration-action: "#4f46e5"
|
||
exploration-soft: "#eef2ff"
|
||
focus: "#a5b4fc"
|
||
success: "#047857"
|
||
success-soft: "#ecfdf5"
|
||
warning: "#92400e"
|
||
warning-soft: "#fffbeb"
|
||
error: "#b91c1c"
|
||
error-soft: "#fef2f2"
|
||
rounded:
|
||
compact: 8px
|
||
control: 10px
|
||
card: 16px
|
||
composer: 22px
|
||
spacing:
|
||
tight: 4px
|
||
icon: 6px
|
||
small: 8px
|
||
group: 12px
|
||
section: 16px
|
||
workspace: 24px
|
||
components:
|
||
model-selector:
|
||
backgroundColor: "{colors.surface}"
|
||
textColor: "{colors.text-control}"
|
||
rounded: "{rounded.control}"
|
||
demonstration-control:
|
||
height: 36px
|
||
exploration-composer:
|
||
backgroundColor: "{colors.surface}"
|
||
rounded: "{rounded.composer}"
|
||
---
|
||
|
||
# ARTEMIS 设计与交互约定
|
||
|
||
## Overview
|
||
|
||
ARTEMIS 面向使用自然语言执行、探索和复跑测试的人。当前产品包含 Flash、Pro、探索三种入口，按需调用安卓设备和电脑插件，提供批次、精选任务、历史、报告及证据。用户应能看懂当前在做什么、何时需要回答、哪些结果已有证据。
|
||
|
||
本文记录主程序的职责边界及 `apps/showcase_ui` 的视觉与交互规则，包括浅色和暗色外观。远程 SDK 的协议边界见[局部设计](packages/artemis-client/DESIGN.md)；独立插件仓库维护适配器设计和构建规则。阶段性进度见[开发快照](docs/development-handoff.md)，当前工作区版本与发布状态见[2.2.0 说明](docs/releases/2.2.0.md)。
|
||
|
||
## System architecture
|
||
|
||
| 层 | 职责与源码入口 |
|
||
| --- | --- |
|
||
| 网页、MCP、远程 SDK | 请求建模、交互与结果读取。`apps/showcase_ui`、`mcp_server`、`packages/artemis-client` 共同使用后台服务；MCP 和薄 SDK 不另启完整后台 |
|
||
| HTTP 与业务服务 | `apps/admin_console` 管理配置、统一队列、批次、收藏、历史、人工复验和导出；2.2.0 的 PC、Android、跨端任务按提交顺序串行执行，`TaskQueueService` 与跨进程共享执行锁共同准入，旧并行参数不能绕过；暂停释放执行资源，恢复时重新排队 |
|
||
| 任务与模型 | `artemis/agents`、`artemis/runtime` 执行 Flash/Pro；`artemis/exploration` 管理交流、预算、示范与用例版本；`artemis/llm`、`artemis/services/llm.py` 统一 Responses 请求 |
|
||
| 插件与证据 | `artemis/plugins` 管理安装、会话、版本固定、来源、截图、录像和附件；插件执行工具动作，宿主管理任务生命周期和最终验收 |
|
||
| 配置与交付 | `artemis/config`、两份 `artemis.jsonc` 和环境配置提供默认值；`scripts` 负责启动、镜像、独立升级和源码打包 |
|
||
|
||
请求重试、业务执行与最终验收分别处理。提交使用稳定标识；创建批次或探索草稿不自动执行，查询不产生设备动作。执行准入和恢复遵守现有资源锁，任务固定所用插件版本，不能通过另建队列绕开互斥。
|
||
|
||
设备保活是辅助服务。保活所属锁或旧保活清理目录不可访问时记录警告，不使设备连接、恢复或监控退出；未取得保活所属锁时不发送保活动作，也不创建替代锁绕过所属权。执行资源锁、主服务注册锁和队列写锁仍须成功取得。
|
||
|
||
运行时准备阶段失败记录 `initialization_failed`，批次保留详细原因并暂停未开始项，修复环境后由用户继续，已失败项不自动重跑。模型请求导致的批次暂停单独标记；模型暂停结束后恢复既定调度及失败即停止策略。用户暂停、停止全部任务和服务重启后的恢复暂停均需用户继续，不被模型恢复覆盖。Flash 与 Pro/探索 Operator 的生成失败复用统一备用模型与重试预算；不完整输出不会成为动作，已有动作不因模型切换而重放。
|
||
|
||
最终验收有独立总预算，按请求超时、重试和剩余任务时间协调，保留取证结果；完整有效的结构化结论才更新正式裁定。`completed`、工具成功、探索通过、用例提炼和复跑通过各自表达自己的状态。
|
||
|
||
Responses 消息交给工具、下游解析器或正式裁定前，必须具有服务端 `completed` 状态；工具参数的原始字符串必须是完整 JSON 对象，不能使用库自动补全的半截参数。流结束或库补出的 `last` 标记不能替代完成状态。缺少终止事件、明确未完成或失败的流丢弃预览，进入现有无效输出恢复策略，最多重新请求一次，配置为零次重试时不重试；恢复保留已有工具证据，不重新提交业务任务。非流式、结构化输出和串接解析器遵守同一检查。
|
||
|
||
普通应用启动及重试只负责启动或恢复前台，不隐式停止或重启应用；停止是独立的显式动作。焦点窗口为空时，使用已恢复活动所在任务的归属补充判断；只有可见候选任务、没有已恢复活动时继续等待。超时返回焦点与任务诊断，不升级为强制停止。
|
||
|
||
测试执行遵循用户任务指令和中途指导；明确的次数及禁止要求交给执行模型结合观察和历史遵守。执行层不额外编译自然语言约束、维护动作配额、比对提交内容指纹或请求 AI 二次审批。Flash、Pro 和插件动作经既有参数、目标及插件授权校验后调用工具；资源锁、取消与暂停、真实执行回执、输入状态观察和结果不明时不自动重发的行为继续保留。历史任务中的旧约束日志仅作为原始诊断记录，不再参与执行判定。
|
||
|
||
取消来源由拥有中断动作的运行时明确赋值，并穿过任务控制及模型等待包装层传递。用户停止、指导替换、暂停、任务或检查替换、已知外层时限，与单次请求超时、传输超时及最终验收总预算分开记录。没有来源的取消保留未知，HTTP 499 不能单独证明用户取消或代理故障；取消不进入模型重试，也不保存取消消息中的指导正文。
|
||
|
||
模型诊断复用现有 trace：自动重试保留本地请求编号，用尝试编号和上次尝试编号关联，重试及终止事件带对应尝试编号。可用的出站、服务端请求、Responses 响应及服务端链路编号随记录导出，仅采集白名单字段；历史缺失的来源及编号不补推。
|
||
|
||
任务耗时复用现有队列、工作进程控制文件与验收 trace，网页、MCP 和报告使用同一只读投影。分别列出后台排队、等待设备/资源、暂停与示范、执行与整理、最终验收及报告导出；总历时包含这些等待，不代表模型速度。缺少时间记录显示未知，不将旧任务缺失的分项补成零。运行结束后不继续累计执行耗时，报告导出单独计时。
|
||
|
||
指导接收不保证赶在终态前消费。保留接收时点、执行器消费回执及后续动作记录的区别；`consumed` 仅证明执行器已读取，不能宣称模型已应用或验收已通过。终态仍未领取的指导投影为 `unapplied`，领取后未留下消费回执的为 `unconfirmed`，不改写原始文件。网页详细查询复用原指导入口，旧数组响应保持兼容。
|
||
|
||
执行平台与证据来源分别记录。报告和证据索引从执行记录汇总来源及实际 step_id/call_id/source_id；界面、接口、文件和终端各自只能支持其观察范围，业务后台名称或网址不能推断平台。最终复核明确事实、矛盾和未验证边界；来源清单不生成新结论，不覆盖 AI 原判、有效结论或人工复验。
|
||
|
||
MCP 与单任务 HTTP 入参拒绝未知字段，校验失败不调度任务。MCP JSON 结果保留兼容文本并提供 structuredContent；任务摘要分页明确总数与 next_offset，引用实际存储编号。跨端阶段先完整初始化，再按既有阶段 id 更新状态与依据；补丁保留其他阶段、范围、资源和顺序，合并后统一校验并保存，失败不更新内存状态。
|
||
|
||
Flash 的最终 AI 判定与分析独立配置，默认关闭；首页功能配置和 MCP 共用保存的全局设置。任务开始时固定设置，尚未开始的任务使用最新值；批量、精选及提炼用例的 Flash 复跑同样遵循。关闭时跳过最终 Checker，保留正常执行、步骤、截图、报告和人工复验；结果为“执行完成 · 未做 AI 判定”，不标记“AI确认”或测试通过。Pro 与主动探索的验收规则保持不变。
|
||
|
||
示范来源保存在元数据中，贯穿分析、提问、规划、执行、验收和用例生成。补充网址不会隐式把电脑示范改到安卓；用户明确改端或提出跨端步骤时按其要求执行。证据必须对应真实来源、窗口、采集时间与操作。
|
||
|
||
录像使用用户选择的范围。人工示范的窗口模式跟随前台窗口，仅保留一路，无有效窗口时保留缺口；普通录屏在只读验收前停止。恢复操作再追加片段，时间映射以实际录像为准，不借用另一来源或时间的画面。
|
||
|
||
收藏保存独立模板与执行配置，用例复跑固定版本；删除原任务不破坏已保存模板。历史与导出的有效结论合并人工复验，不能用新裁定改写旧证据。
|
||
|
||
普通任务新安装默认 `gpt-6-luna / high`，探索单独使用 `gpt-6.1-terra / high`，保留已有配置。上下文参照上限 300k、默认历史压缩预算 80k，均不表示整条任务累计 token 限额。优化稳定前缀时保留关键文件回执、路径、校验和来源；费用收益依实际网关用量及计价判断。
|
||
|
||
普通 Pro 的计划全部完成后，执行循环返回既有收尾和最终验收流程，不要求额外设备动作；有新指导或验收反馈时先处理反馈，探索模式仍须交付完整报告。完成计划不等于测试通过。Operator 写入计划时拒绝新增或增加同名顶层里程碑，撤销该次写入并返回工具错误；局部替换不得夹带目标范围外的里程碑，已有重复项可继续整理，确需重复的阶段使用不同名称。
|
||
|
||
## Colors
|
||
|
||
浅色使用浅灰画布、白色内容面和深色正文；暗色使用深蓝灰画布、分层内容面和浅色正文。首页主要操作使用蓝色，探索发送及相关主操作保留靛色；绿色、琥珀色、红色用于结果与需要处理的状态。新控件复用所在区域的语义色。
|
||
|
||
| 用途 | 值与来源 |
|
||
| --- | --- |
|
||
| 画布 / 正文 | `#f8f9fa` / `#1e293b`，来自[全局样式](apps/showcase_ui/src/styles.scss) |
|
||
| 首页操作 / 悬停 | `#1a73e8` / `#1557b0`，来自[首页样式](apps/showcase_ui/src/app/pages/home/home.component.scss) |
|
||
| 探索操作 / 浅色状态面 | `#4f46e5` / `#eef2ff`，来自[探索面板](apps/showcase_ui/src/app/components/exploration-panel/exploration-panel.component.scss) |
|
||
| 正文层级 / 边框 | 强调 `#0f172a`、次级 `#475569`、辅助 `#64748b`；常规边框 `#e2e8f0` |
|
||
| 成功、等待、错误 | 浅色外观用深色状态文字配对应浅色面，暗色采用下方语义映射；同时给出文字、图标或说明，结论不只依靠颜色 |
|
||
|
||
全局导航使用单个太阳/月亮按钮，点击一次直接切换浅色与暗色，不使用下拉菜单。首次使用跟随系统，点击后记住当前浏览器的明确选择；首次绘制前应用，页面切换和刷新保持一致。按钮图标和可访问名称提示点击后将切换的外观。
|
||
|
||
颜色通过 `--app-*` 语义变量引用，浅色保留组件原有回退值，暗色集中定义在[主题样式](apps/showcase_ui/src/_theme.scss)。主要映射如下：
|
||
|
||
| 语义变量 | 暗色值 |
|
||
| --- | --- |
|
||
| `--app-canvas` / `--app-surface` | `#0b1220` / `#111c2e` |
|
||
| `--app-surface-soft` / `--app-surface-raised` | `#172337` / `#1e2c42` |
|
||
| `--app-text-strong` / `--app-text-control` | `#f1f5f9` / `#dbe4f0` |
|
||
| `--app-text-secondary` / `--app-text-muted` | `#bdcadd` / `#98aac1` |
|
||
| `--app-border` / `--app-border-control` | `#2b3b52` / `#3d506a` |
|
||
| `--app-primary-text` / `--app-exploration-text` | `#8ebcff` / `#b7b3ff` |
|
||
| `--app-success-text` / `--app-warning-text` / `--app-error-text` | `#6ee7b7` / `#fcd089` / `#ff9ca7` |
|
||
|
||
状态文字、状态背景、边框和高光分别引用对应变量；保留实体主按钮的色彩与白色按钮文字。截图、录像和用户文件使用原始颜色，不对页面整体施加反色滤镜。
|
||
|
||
加载、空状态、断开、未验证与失败使用明确文案。执行完成可以有完成标识，测试裁定仍需独立展示；不能让绿色完成态替代测试通过结论。
|
||
|
||
## Typography
|
||
|
||
沿用全局字体栈：`Google Sans`、`Google Sans Text`、`Inter`、系统无衬线字体；中文使用系统可用字形。代码、路径及请求诊断使用现有等宽样式，保留换行与复制能力。
|
||
|
||
`Inter`、`Outfit`、`Roboto` 及 `Material Symbols Outlined` 使用随源码分发的[本地字体](apps/showcase_ui/public/fonts/README.md)，构建和显示不依赖 Google Fonts。图标保留完整字形及 `FILL`、`GRAD`、`opsz`、`wght` 可变轴，不用文字代替缺失图标。
|
||
|
||
模型控件正文为 13px，探索输入正文为 14px，用例标题为 18px；辅助信息依现有组件使用 11–12px。保留字号、字重、留白形成的层次，不通过大段加粗堆叠状态。Markdown、表格、长链接和中文长标题应换行，不撑破容器。
|
||
|
||
计划、笔记和报告共用 Markdown 渲染，支持标题、表格与列对齐、嵌套列表、任务清单、引用、分隔线、链接、图片、删除线及围栏代码块。宽表格与代码在自身区域横向滚动，保留代码空白和字面内容。计划中的 `[/]` 进行中、`verify` / `assert@end` 和 `finding` 标识继续可辨认。原始 HTML 按文字展示，链接与图片限制安全协议，并保留 Angular 的 HTML 清理。
|
||
|
||
图标沿用 Material Symbols Outlined，常规全局尺寸 20px；组件局部按原有尺寸调整。图标与相邻文字垂直居中，独立图标按钮提供可访问名称。
|
||
|
||
## Layout
|
||
|
||
- 首页负责创建任务与访问精选模板；工作区主区域展示当前任务的交流、执行步骤和结果，底部输入框始终服务当前任务。
|
||
- 编辑、模型设置和复跑参数按需展开，默认保持任务时间线可读。精选卡片在收起状态下等高，长标题、不同状态和展开内容不会遮挡操作入口。
|
||
- 通常以 4、6、8、12、16、24px 组织内部间距；沿用组件现有网格和断点。子容器允许收缩，长内容使用 `min-width: 0` 及合适换行。
|
||
- 探索面板在 600px 以下收紧外边距并允许操作换行；模型选择控件宽度跟随容器。窄屏仍可辨认状态、选择来源和发送指导。
|
||
- 列表后台刷新保留滚动、选择和折叠状态；首次加载与静默更新分开，避免周期性加载提示挤动内容。实时连接复用现有页面可见性管理。
|
||
|
||
## Elevation
|
||
|
||
卡片使用细边框和克制的阴影区分区域。首页现有玻璃效果、渐变和按钮悬停保留在原有区域，正文、报告、表单和选项保持清晰背景及文字对比。
|
||
|
||
探索输入区沿用 `0 6px 24px #0f172a08` 的阴影；焦点反馈沿用所在控件的轮廓和浅色描边。全局 CDK overlay 层级为 1200，新增弹层先使用既有 overlay 机制，不任意叠加更大的层级。
|
||
|
||
## Shapes
|
||
|
||
模型输入与选择框圆角 10px；紧凑控件常用 8px，内容卡片按组件使用 12–16px，探索输入区为 22px。保留现有徽标、标签与胶囊形控件的局部形状；这些值不要求把全部历史控件改成同一圆角。
|
||
|
||
## Components
|
||
|
||
| 组件或状态 | 必须维持的交互与尺寸 | 实现依据 |
|
||
| --- | --- | --- |
|
||
| 模型选择 | 预设选择加自定义输入；主模型、兜底和精选任务复用同一组件。最小高度 40px、内边距 10px 12px、圆角 10px，保留焦点与禁用态 | [model-selector](apps/showcase_ui/src/app/components/model-selector/model-selector.component.ts) |
|
||
| 人工示范控件 | 来源标签与控件水平对齐，选择框及开始按钮均为 36px 高、垂直居中；窄屏可换行。准备、录制、分析分别显示 | [exploration-panel](apps/showcase_ui/src/app/components/exploration-panel/exploration-panel.component.scss) |
|
||
| 探索建议 | 推荐内容为用户口吻的可编辑回复；点击只填草稿，用户发送后才继续任务 | [探索组件](apps/showcase_ui/src/app/components/exploration-panel/exploration-panel.component.ts) |
|
||
| 历史标题与星标 | 星标只占标题，第二行状态与编号正常左对齐；状态徽标沿用 20px 高及统一内边距 | [task-history](apps/showcase_ui/src/app/components/task-history/task-history.component.ts) |
|
||
| 验收状态 | 展示准备证据、核对、生成与校验等阶段及可用的耗时、预算、重试诊断；未完成的流式文字不变为正式通过标签 | [agent-stream](apps/showcase_ui/src/app/components/agent-stream/agent-stream.component.html) |
|
||
| 插件工具回执 | 先显示窗口、控件、截图等已有关键字段与短预览；长文本、控件树及完整原始 payload 可展开查看。只调整网页呈现，保留原始证据和模型上下文 | [plugin-tool-result](apps/showcase_ui/src/app/components/plugin-tool-result/plugin-tool-result.component.ts) |
|
||
| 截图、录像与文件 | 显示真实来源和缺口；按时间定位并保留跳转前的播放/暂停状态，文件成功以真实保存回执为准 | [工作区说明](docs/automation-workspace.md) |
|
||
| 保存和错误反馈 | 配置加载、保存、空值、失败与密钥已配置状态有明确提示；空密钥保留已有值，连接测试与保存分开 | [模型配置](apps/showcase_ui/src/app/components/model-settings/model-settings.component.ts) |
|
||
| Flash 判定开关 | 切换即保存，保存中禁用，失败恢复已保存值；不顺带提交其他配置草稿。说明尚未开始的任务生效、无需重启，运行中任务保持原配置 | [功能配置](apps/showcase_ui/src/app/components/model-settings/capability-settings.component.ts) |
|
||
| 仅 PC 勾选项 | 位于首页输入区，与扩展插件控件共用配色和尺寸；默认关闭。开启后切换电脑文案与插件目标，就绪条件保留运行时和模型，排除 Android 设备、锁屏、ADB 及手机录屏工具；单任务提交使用 execution_target=computer | [首页](apps/showcase_ui/src/app/pages/home/home.component.ts) |
|
||
| 外观选择 | 所有页面共用，键盘可操作；窄屏可收起导航文字，但保留链接的可访问名称 | [导航](apps/showcase_ui/src/app/components/nav-switcher/nav-switcher.component.ts) |
|
||
|
||
这些规则对应已接受的现有行为。改动后结合实际层叠样式、渲染尺寸和相关状态检查，不能只核对一处声明。
|
||
|
||
## Do's and Don'ts
|
||
|
||
- 复用现有组件、API 类型、中文文案和状态语义。新增状态先说明它与执行、验收或人工操作的关系。
|
||
- 保持实际来源与证据一致，缺失时说明原因；不使用手机画面替代电脑操作，也不把工具成功当作业务通过。
|
||
- 保留可见焦点、禁用反馈和减少动画偏好；录制红点表示实际录制，等待或执行中使用各自文案。
|
||
- 源码已更新而页面仍旧时，先核对服务目录、构建与缓存；不通过反复增加样式覆盖掩盖旧构建问题。
|
||
- 视觉变化验证代表性宽度、长标题、加载、等待回答、错误与展开状态；文档格式检查不等于渲染验证。开发检查按[前端指南](apps/showcase_ui/AGENTS.md)执行。
|
||
|
||
## Workspace plugin extensions
|
||
|
||
工作区扩展使用声明式清单版本 3，宿主提供回放面板、人工表单、任务存储和报告接口；不运行插件页面脚本，不另建队列或结果库。纯工作区插件不加入模型执行选择。接口定义见 [工作区插件](docs/workspace-plugins.md)。
|
||
|
||
回放两侧面板默认收起、独立展开，普通浮窗和影院模式共用；插件声明期望/最小/最大宽度，宿主按视口收缩，窄屏一次展开一侧，始终保持面板位于回放的左侧或右侧。任务需求只展示本次运行最初的提示词，复用安全 Markdown 渲染。人工表单字段均可留空，不调用模型、不覆盖已有执行结论或人工复验。
|
||
|
||
评审按单次任务和插件 ID 保存版本历史；运行中只读，终态可编辑或清空。停用/卸载隐藏面板与新导出字段但保留记录，任务删除时同步清理。报告只采用已安装且启用的贡献，空值保持空白；修改记录或插件状态使后续报告缓存失效。
|