Artemis-Eapil/DESIGN.md

name, colors, rounded, spacing, components

name	colors	rounded	spacing	components
ARTEMIS 控制台	canvas surface text text-strong text-secondary text-muted text-control border border-control primary primary-hover primary-soft exploration-action exploration-soft focus success success-soft warning warning-soft error error-soft #f8f9fa #ffffff #1e293b #0f172a #475569 #64748b #334155 #e2e8f0 #dbe3ec #1a73e8 #1557b0 #eff6ff #4f46e5 #eef2ff #a5b4fc #047857 #ecfdf5 #92400e #fffbeb #b91c1c #fef2f2	compact control card composer 8px 10px 16px 22px	tight icon small group section workspace 4px 6px 8px 12px 16px 24px	model-selector demonstration-control exploration-composer backgroundColor textColor rounded {colors.surface} {colors.text-control} {rounded.control} height 36px backgroundColor rounded {colors.surface} {rounded.composer}

ARTEMIS 设计与交互约定

Overview

ARTEMIS 面向使用自然语言执行、探索和复跑测试的人。当前产品包含 Flash、Pro、探索三种入口，按需调用安卓设备和电脑插件，提供批次、精选任务、历史、报告及证据。用户应能看懂当前在做什么、何时需要回答、哪些结果已有证据。

本文记录主程序的职责边界及 apps/showcase_ui 的视觉与交互规则，包括浅色和暗色外观。远程 SDK 的协议边界见局部设计；独立插件仓库维护适配器设计和构建规则。阶段性进度见开发快照，当前工作区版本与发布状态见2.2.0 说明。

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 负责启动、镜像、独立升级和源码打包

插件运行辅助接口见 SDK 与市场材料：已批准文件用不可变快照绑定实际消费字节，受管外部工具在返回前回收后代。宿主负责 MCP 总预算，插件负责内部超时和取消。开发检查保持轻量；市场材料使用独立内容指纹与验收记录校验，不代替源码、权利来源或真实业务审查。

请求重试、业务执行与最终验收分别处理。提交使用稳定标识；创建批次或探索草稿不自动执行，查询不产生设备动作。执行准入和恢复遵守现有资源锁，任务固定所用插件版本，不能通过另建队列绕开互斥。

设备保活是辅助服务。保活所属锁或旧保活清理目录不可访问时记录警告，不使设备连接、恢复或监控退出；未取得保活所属锁时不发送保活动作，也不创建替代锁绕过所属权。执行资源锁、主服务注册锁和队列写锁仍须成功取得。

运行时准备阶段失败记录 initialization_failed，批次保留详细原因并暂停未开始项，修复环境后由用户继续，已失败项不自动重跑。模型请求导致的批次暂停单独标记；模型暂停结束后恢复既定调度及失败即停止策略。用户暂停、停止全部任务和服务重启后的恢复暂停均需用户继续，不被模型恢复覆盖。Flash 与 Pro/探索 Operator 的生成失败复用统一备用模型与重试预算；不完整输出不会成为动作，已有动作不因模型切换而重放。

最终验收有独立总预算，按请求超时、重试和剩余任务时间协调，保留取证结果；完整有效的结构化结论才更新正式裁定。completed、工具成功、探索通过、用例提炼和复跑通过各自表达自己的状态。

Responses 消息交给工具、下游解析器或正式裁定前，必须具有服务端 completed 状态；工具参数的原始字符串必须是完整 JSON 对象，不能使用库自动补全的半截参数。流结束或库补出的 last 标记不能替代完成状态。缺少终止事件、明确未完成或失败的流丢弃预览，进入现有无效输出恢复策略，最多重新请求一次，配置为零次重试时不重试；恢复保留已有工具证据，不重新提交业务任务。非流式、结构化输出和串接解析器遵守同一检查。

普通应用启动及重试只负责启动或恢复前台，不隐式停止或重启应用；停止是独立的显式动作。焦点窗口为空时，使用已恢复活动所在任务的归属补充判断；只有可见候选任务、没有已恢复活动时继续等待。超时返回焦点与任务诊断，不升级为强制停止。

测试执行遵循用户任务指令和中途指导；明确的次数及禁止要求交给执行模型结合观察和历史遵守。执行层不额外编译自然语言约束、维护动作配额、比对提交内容指纹或请求 AI 二次审批。Flash、Pro 和插件动作经既有参数、目标及插件授权校验后调用工具；资源锁、取消与暂停、真实执行回执、输入状态观察和结果不明时不自动重发的行为继续保留。历史任务中的旧约束日志仅作为原始诊断记录，不再参与执行判定。

取消来源由拥有中断动作的运行时明确赋值，并穿过任务控制及模型等待包装层传递。用户停止、指导替换、暂停、任务或检查替换、已知外层时限，与单次请求超时、传输超时及最终验收总预算分开记录。没有来源的取消保留未知，HTTP 499 不能单独证明用户取消或代理故障；取消不进入模型重试，也不保存取消消息中的指导正文。

模型诊断复用现有 trace：自动重试保留本地请求编号，用尝试编号和上次尝试编号关联，重试及终止事件带对应尝试编号。可用的出站、服务端请求、Responses 响应及服务端链路编号随记录导出，仅采集白名单字段；历史缺失的来源及编号不补推。

短时安卓控件复用 Flash/Pro 统一动作层。action_sequence 是通用安卓短动作组合器，在单次工具调用内顺序执行 ensure_visible、click、wait、drag，成员之间不插入模型请求或安全网；默认不增加观测，显式可见性守卫读取本机最新层级，安卓不等待整屏截图稳定。ensure_visible 使用显式声明的面板内 target 与入口 opener 资源 ID：目标已显示时跳过打开，否则只点击入口一次，并有界等目标出现（默认 1500ms，上限 3000ms）；找不到、不唯一、层级不可用或超时就停止，不自动猜入口或重试业务输入。它只用于界面准备；每次短时面板操作都应将准备和操作放在同一次调用中。普通原生元素索引点击也确认资源 ID 仍覆盖记录位置，拒绝过期坐标。序列 click 可按真实资源 ID 定位并连续点击 1–10 次，每次重新校验目标，部分完成保留 completed_taps。整组参数在首个输入前校验，沿用 pro.execution.max_burst_actions 的短序列上限；两种模式的运行时工具声明都暴露实际上限，等待和准备均占一项。旧 click 的 unless_visible 在指定面板元素可见时跳过打开按钮，不能加到实际操作按钮上；drag 的 require_visible 在元素消失或层级不可用时拒绝输入。所有守卫只接受真实观察到的 resource_id，精简元素列表保留这些标识，不硬编码业务应用。暂停或新指导在成员边界生效，失败后停止，保留每项开始/结束时间及 completed/skipped/unknown/not_started 回执；不自动重发已完成或结果不明的输入。后续目标须来自同布局的真实观察，每次反向调整也须连续准备并操作；短序列不能代替业务流程的观察与端点、刻度验收。

drag 支持明确的归一化或原图像素端点，默认 300ms，不自动过冲。可根据当前缩放下的两个真实数值刻度校准 thumb 位置，或将 pan 刻度移至固定指针；返回真实派发端点、比例及端点取整误差。校准假定本次局部刻度线性，换缩放须重新读取锚点；计算回执保留 pending_observation，实际选中值及业务目标仍须通过动作后的观察验证。像素分辨率不足时先放大，不宣称任意时间精度。

状态动作使用显式 control_action.ensure_state：仅以真实原生 checked/selected、文本/描述或数值判断，已满足则跳过，否则写入一次并有界只读核验。缺失状态不当作 false；核验失败保留完成的输入，不自动再切换。drag/pinch/touch_gesture 的可选 region 在首个输入前约束所有触点路径。drag 或整个 action_sequence 的可选 feedback 绑定唯一持久数值读数，在输入前确认可读，整组结束后有界等待稳定并报告实际值、目标、残差和允许误差；连续两次同策略未减小误差则拒绝第三次输入，要求重新观察、缩放或改变有效移动距离。记录仅存于当前设备执行实例，缺失读数不记作零，不共享到新任务。计算精度、实际数值条件和最终业务验收分开；无原生读数的自绘控件仍依靠视觉证据，不能宣称任意精度。详见原生动作说明。

任务耗时复用现有队列、工作进程控制文件与验收 trace，网页、MCP 和报告使用同一只读投影。分别列出后台排队、等待设备/资源、暂停与示范、执行与整理、最终验收及报告导出；总历时包含这些等待，不代表模型速度。缺少时间记录显示未知，不将旧任务缺失的分项补成零。运行结束后不继续累计执行耗时，报告导出单独计时。

指导接收不保证赶在终态前消费。保留接收时点、执行器消费回执及后续动作记录的区别；consumed 仅证明执行器已读取，不能宣称模型已应用或验收已通过。终态仍未领取的指导投影为 unapplied，领取后未留下消费回执的为 unconfirmed，不改写原始文件。网页详细查询复用原指导入口，旧数组响应保持兼容。

执行平台与证据来源分别记录。报告和证据索引从执行记录汇总来源及实际 step_id/call_id/source_id；界面、接口、文件和终端各自只能支持其观察范围，业务后台名称或网址不能推断平台。最终复核明确事实、矛盾和未验证边界；来源清单不生成新结论，不覆盖 AI 原判、有效结论或人工复验。

原生安卓动作在派发时记录所选设备来源。安卓截图来源也可从已保存的成功截图回执读取设备、采集时间、文件路径和校验值，并引用实际 trace_id；兼容 Flash 与 Pro 的回执封装，不从模型参数补造来源。空步骤、笔记和结束声明不计入缺失动作来源；窗口枚举等无单一目标的操作保留未关联状态，该计数不等于截图丢失。未生成独立输出正文时，报告展示当前有效判定及依据，保留人工复验优先级，不把正文缺失写成验收结论缺失。

规划器的笔记工具与执行器的设备、插件工具分别绑定。规划器依据任务的实际授权插件清单制定计划，由执行器加载并验证能力；规划阶段没有绑定动作工具，不表示任务缺少这些能力，也不构成重新申请授权的依据。

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，来自全局样式
首页操作 / 悬停	#1a73e8 / #1557b0，来自首页样式
探索操作 / 浅色状态面	#4f46e5 / #eef2ff，来自探索面板
正文层级 / 边框	强调 #0f172a、次级 #475569、辅助 #64748b；常规边框 #e2e8f0
成功、等待、错误	浅色外观用深色状态文字配对应浅色面，暗色采用下方语义映射；同时给出文字、图标或说明，结论不只依靠颜色

全局导航使用单个太阳/月亮按钮，点击一次直接切换浅色与暗色，不使用下拉菜单。首次使用跟随系统，点击后记住当前浏览器的明确选择；首次绘制前应用，页面切换和刷新保持一致。按钮图标和可访问名称提示点击后将切换的外观。

颜色通过 --app-* 语义变量引用，浅色保留组件原有回退值，暗色集中定义在主题样式。主要映射如下：

语义变量	暗色值
--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 使用随源码分发的本地字体，构建和显示不依赖 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 以下收紧外边距并允许操作换行；模型选择控件宽度跟随容器。窄屏仍可辨认状态、选择来源和发送指导。
• 列表后台刷新保留滚动、选择和折叠状态；首次加载与静默更新分开，避免周期性加载提示挤动内容。实时连接复用现有页面可见性管理。
• 结束任务的错误与阻塞说明默认只占一行，点击展开安全 Markdown 正文与已有依据，长正文限高滚动。摘要优先采用已保存的有效结论原因，否则取执行错误首行；不新增 AI 复盘请求，不改写原始记录。展开说明不触发任务切换，刷新保留展开状态。

Elevation

卡片使用细边框和克制的阴影区分区域。首页现有玻璃效果、渐变和按钮悬停保留在原有区域，正文、报告、表单和选项保持清晰背景及文字对比。

探索输入区沿用 0 6px 24px #0f172a08 的阴影；焦点反馈沿用所在控件的轮廓和浅色描边。全局 CDK overlay 层级为 1200，新增弹层先使用既有 overlay 机制，不任意叠加更大的层级。

Shapes

模型输入与选择框圆角 10px；紧凑控件常用 8px，内容卡片按组件使用 12–16px，探索输入区为 22px。保留现有徽标、标签与胶囊形控件的局部形状；这些值不要求把全部历史控件改成同一圆角。

Components

组件或状态	必须维持的交互与尺寸	实现依据
模型选择	预设选择加自定义输入；主模型、兜底和精选任务复用同一组件。最小高度 40px、内边距 10px 12px、圆角 10px，保留焦点与禁用态	model-selector
人工示范控件	来源标签与控件水平对齐，选择框及开始按钮均为 36px 高、垂直居中；窄屏可换行。准备、录制、分析分别显示	exploration-panel
探索建议	推荐内容为用户口吻的可编辑回复；点击只填草稿，用户发送后才继续任务	探索组件
历史标题与星标	星标只占标题，第二行状态与编号正常左对齐；状态徽标沿用 20px 高及统一内边距	task-history
验收状态	展示准备证据、核对、生成与校验等阶段及可用的耗时、预算、重试诊断；未完成的流式文字不变为正式通过标签	agent-stream
插件工具回执	先显示窗口、控件、截图等已有关键字段与短预览；长文本、控件树及完整原始 payload 可展开查看。只调整网页呈现，保留原始证据和模型上下文	plugin-tool-result
截图、录像与文件	显示真实来源和缺口；按时间定位并保留跳转前的播放/暂停状态，文件成功以真实保存回执为准	工作区说明
保存和错误反馈	配置加载、保存、空值、失败与密钥已配置状态有明确提示；空密钥保留已有值，连接测试与保存分开	模型配置
Flash 判定开关	切换即保存，保存中禁用，失败恢复已保存值；不顺带提交其他配置草稿。说明尚未开始的任务生效、无需重启，运行中任务保持原配置	功能配置
仅 PC 勾选项	位于首页输入区，与扩展插件控件共用配色和尺寸；默认关闭。开启后切换电脑文案与插件目标，就绪条件保留运行时和模型，排除 Android 设备、锁屏、ADB 及手机录屏工具；单任务提交使用 execution_target=computer	首页
外观选择	所有页面共用，键盘可操作；窄屏可收起导航文字，但保留链接的可访问名称	导航

这些规则对应已接受的现有行为。改动后结合实际层叠样式、渲染尺寸和相关状态检查，不能只核对一处声明。

Do's and Don'ts

• 复用现有组件、API 类型、中文文案和状态语义。新增状态先说明它与执行、验收或人工操作的关系。
• 保持实际来源与证据一致，缺失时说明原因；不使用手机画面替代电脑操作，也不把工具成功当作业务通过。
• 保留可见焦点、禁用反馈和减少动画偏好；录制红点表示实际录制，等待或执行中使用各自文案。
• 源码已更新而页面仍旧时，先核对服务目录、构建与缓存；不通过反复增加样式覆盖掩盖旧构建问题。
• 视觉变化验证代表性宽度、长标题、加载、等待回答、错误与展开状态；文档格式检查不等于渲染验证。开发检查按前端指南执行。

Workspace plugin extensions

工作区扩展使用声明式清单版本 3，宿主提供回放面板、人工表单、任务存储和报告接口；不运行插件页面脚本，不另建队列或结果库。纯工作区插件不加入模型执行选择。接口定义见 工作区插件。

回放两侧面板默认收起、独立展开，普通浮窗和影院模式共用；插件声明期望/最小/最大宽度，宿主按视口收缩，窄屏一次展开一侧，始终保持面板位于回放的左侧或右侧。任务需求只展示本次运行最初的提示词，复用安全 Markdown 渲染。人工表单字段均可留空，不调用模型、不覆盖已有执行结论或人工复验。

评审按单次任务和插件 ID 保存版本历史；运行中只读，终态可编辑或清空。停用/卸载隐藏面板与新导出字段但保留记录，任务删除时同步清理。报告只采用已安装且启用的贡献，空值保持空白；修改记录或插件状态使后续报告缓存失效。

执行详情中的 Payload 默认折叠；其他超长字段也默认折叠，展开后保留完整可复制内容并限制显示高度。原始用例面板仅由启用的工作区插件声明，额外导入列不影响未启用插件的用户。评审支持所有执行模式和目标，用户修改评审后自动保存：结果选择立即保存，备注短暂防抖；切换任务前保存，失败时保留输入和当前任务。仅用户编辑触发写入，AI 不推断人工结论。

模型网络代理策略仅由环境项 OPENAI_USE_SYSTEM_PROXY 控制，默认 false。同步、异步模型客户端和模型凭据检查统一遵循；不出现在前端配置中，不改变 TLS 验证与自定义 CA 设置。