109 lines
12 KiB
Markdown
109 lines
12 KiB
Markdown
# ARTEMIS 2.0.0：插件步骤、录像与开发规范
|
|
|
|
状态：2026-10-15 用户已确认设计，待实现。本文补充 [2.0.0 总体方案](2.0.0-plugins.md)，不代表运行代码已具备这些能力。本轮只更新设计文档。
|
|
|
|
本次确认覆盖统一步骤、跨端录像、证据导出和插件开发规则。用户对审阅稿补充了三条约束：录像以高效留档为主；第三方插件和 Skill 必须按 ARTEMIS 规则适配；不自动恢复业务环境，恢复需求由任务提示词表达。
|
|
|
|
## 1. 统一步骤与结果
|
|
|
|
- 沿用一条任务时间线。步骤卡标明安卓、电脑、终端等来源，展示实际动作、结果、耗时和证据。观察、读取文件等辅助调用默认折叠，可展开。
|
|
- 以用户能理解的业务操作作为主步骤，其下保留实际工具调用、连点子动作和所有重试。分组只影响展示，不能隐藏失败或修改原始执行记录。
|
|
- 平台生成任务、步骤、调用和证据关联标识及时间；插件返回真实操作结果。一个业务步骤可以关联多次调用和多项附件。
|
|
- 区分“操作已执行”和“效果已验证”。工具成功不能直接变成用例通过；验收结合提示词和实际证据，保留不通过、未验证、阻塞等结果及人工复验优先级。
|
|
- 视觉步骤关联同一目标的操作前后截图，默认展示操作后图。缺图时明确说明，不用另一来源的画面补位。
|
|
- 每份视觉证据绑定插件及版本、资源实例、屏幕或窗口目标、采集时间、尺寸和坐标范围。窗口、屏幕、DPI 或目标切换后重新观察，不能仅按插件 ID 复用旧画面。
|
|
- 手机截图不能证明电脑操作成功，电脑截图不能进入手机观察状态。允许文字观察，但没有有效图像时不能猜测像素坐标。
|
|
|
|
## 2. 录像范围与生命周期
|
|
|
|
- 本次开发同时覆盖安卓和电脑录像；首批仍只有一个电脑控制插件，浏览器作为电脑应用操作，不增加独立浏览器插件。
|
|
- 通用协议预留其他视觉来源；终端、文件和 API 能力使用日志、退出码、请求结果、文件校验等原生证据，不强制提供录像。
|
|
- 录屏总开关继续默认关闭。用户开启后，自动覆盖任务实际使用且支持录制的来源，不要求选择执行目标或组合模式。
|
|
- 在来源首次被实际使用前启动录制，持续至任务暂停或结束。切换去操作另一来源时继续录，保留后台变化与等待过程；未使用来源不录。
|
|
- 暂停结束当前片段；恢复重新获取资源和观察，为后续使用建立新片段。任务结束或取消时收尾已录内容。
|
|
- 当前资源互斥是任务级，不随工具切换释放。“预留资源”和“开始录制”分别管理，不能因为插件可用就录完整个任务。
|
|
- 电脑默认录当前控制的目标屏幕，覆盖菜单、弹窗和窗口切换；提供仅录目标窗口的选项。多屏不默认全录，跨屏操作建立对应来源片段。
|
|
- 界面显示录制状态与当前屏幕/窗口范围，明确屏幕模式包含该屏幕其他可见内容。范围变化记录为事件，不悄悄扩大捕获范围。
|
|
|
|
## 3. 高效留档策略
|
|
|
|
目标是便于留档、体积可控、不会明显拖慢测试；录像仍需辨认操作和主要状态，细节文字可结合步骤截图查看。
|
|
|
|
- 优先评估 H.265/HEVC，优先利用可用的硬件编码能力；限制分辨率、帧率和目标码率，不默认保存原生高分辨率、高帧率视频。
|
|
- 编码能力、实际录制和网页播放兼容性必须验证；保留 H.264 回退，记录最终采用的编码及回退原因，不因强制 H.265 阻断任务。
|
|
- 实现时以长边不超过 1280、最高 15 fps、H.265 约 1 Mbps / H.264 约 1.5 Mbps 作为初始试验档位。这些是待测候选值，不是已验证或已生效的默认值；根据中文界面可读性、快速动作、CPU/GPU 占用和文件大小确定最终留档默认值。
|
|
- 优先录制时直接采用留档参数，避免任务结束或打包下载时再全量转码。已有合适片段尽量不重复编码。
|
|
- 默认只保留一套留档视频，不同时持久保存高清原片和压缩副本。临时转码文件按生命周期清理；用户证据不因清理被删除。
|
|
- 模型观察截图、步骤证据截图与录像参数独立，不能为了降低录像体积而降低模型定位所需画面质量。
|
|
- 编码、尺寸、帧率和码率进入统一配置层，提供合理默认；普通用户不必填写编码参数。网页、任务覆盖、MCP 和配置文档保持一致。
|
|
- 限帧或可变帧率不能破坏时间映射。实际时间戳、片段起止和关键帧定位必须用于回看，不能仅按帧数推算时间。
|
|
|
|
技术依据：[scrcpy 视频参数](https://github.com/Genymobile/scrcpy/blob/master/doc/video.md)提供尺寸、帧率、码率及编码器选项；[MDN 视频编码说明](https://developer.mozilla.org/en-US/docs/Web/Media/Guides/Formats/Video_codecs)用于核对播放兼容性。以项目实际安装版本和运行环境的能力探测及实测为准，不将文档列出的选项等同于所有设备均可用。
|
|
|
|
## 4. 回看与异常呈现
|
|
|
|
- 一个播放器区域切换安卓、电脑等来源，共享真实任务时间轴。首版不做多画面同时播放，不默认合并成一个大视频。
|
|
- 点击步骤或关键节点，自动切换对应来源并定位。跳转前正在播放则继续播放，暂停则保持暂停；按钮状态与实际播放器状态一致。
|
|
- 暂停、尚未录制、中断和无覆盖区间明确展示，不能抹掉缺口或用旧帧冒充连续画面。无视频步骤展示其截图或日志及缺失原因，不跳到无关片段。
|
|
- 普通录制故障告警后可以继续任务；要求以录像验收但缺少证据的项目标记未验证，不自动推断通过。
|
|
- 无法观察当前目标会影响视觉动作，应停止依赖该画面的操作，不能把它当成普通录屏故障继续盲点。
|
|
- 磁盘不足、编码失败等同类故障只产生一次主要告警，并持续显示录制状态；故障恢复有明确预算，不无界重试或阻塞批次。
|
|
|
|
## 5. 证据与导出
|
|
|
|
- 单任务和批次资料包含步骤记录、各来源截图与录像、插件日志、生成文件及统一索引。索引关联步骤、调用、来源、片段和视频时间，也说明缺失证据的原因。
|
|
- 截图和导出文件默认先留存到任务 trace；用户要求保存桌面等位置时额外复制，并记录真实写入结果及校验信息，不能仅凭工具文字声称保存成功。
|
|
- 批次按用例编号、轮次组织，关联任务 ID 以消除同名歧义；来源文件不相互覆盖。
|
|
- 网页、Word、Excel、单任务包和批次包的结论及证据引用一致。非视觉输出保留原生文件和可读摘要。
|
|
- 下载沿用现有打包进度。媒体压缩不挪到下载请求中执行，避免用户长时间等待；合适的已编码视频直接纳入资料包。
|
|
- 插件升级或卸载不影响历史证据读取。附件保留与删除遵循现有任务记录生命周期和共享文件引用规则。
|
|
|
|
## 6. 平台与插件的职责
|
|
|
|
- 平台负责配置、调度、版本固定、资源锁、权限范围检查、步骤和证据保存、时间映射、任务预算及报告。
|
|
- 插件负责自身能力的实际执行、观察、结果及附件输出，明确说明完成、失败、部分执行或无法确认，不自行判定整个测试用例通过，也不另建业务任务队列。
|
|
- 标准采用公共协议与能力附录：视觉、终端、API、文件各有证据要求，不把全部插件强制做成截图点击模式。
|
|
- 结果和附件协议明确类型、来源、时间、元数据与落库方式。接口版本、兼容范围和迁移规则必须与现有严格清单校验一起设计，不直接向旧清单塞入未知字段。
|
|
- 工具声明包含类型化参数、读写影响、资源范围、观察类型、截图/录像支持、超时、取消保证、重试与幂等语义。自动重复调用的观察工具必须明确只读，并接受校验。
|
|
- 未来终端插件可以明确提供命令能力，但应声明主机、工作目录与权限边界；普通业务插件不能用一个无限制 shell 接口代替全部规范。
|
|
|
|
## 7. 外部插件与 Skill 适配
|
|
|
|
- 既有开源插件和 Skill 必须按 ARTEMIS 规则适配并验证，再进入市场；不能直接复制即视为兼容。
|
|
- 可以保留适用的原工具实现，但工具名称与参数、资源身份、观察与坐标、权限、步骤和证据、错误和取消语义都要符合宿主契约；不兼容部分需要改造。
|
|
- Skill 描述实际存在的能力、使用方法、判断规则和限制。安装检查其所依赖的工具、平台及版本；缺少依赖应报清楚原因，不能靠提示词虚构能力。
|
|
- Skill 不能绕开授权、调度或证据规则，不能把工具返回成功直接写成业务通过。
|
|
- 保留原有来源和必要许可证信息；适配包按自己的版本和实测范围发布。
|
|
|
|
## 8. 失败处理与恢复边界
|
|
|
|
- 错误说明动作是否已执行、是否产生副作用、失败原因、受影响资源及已取得的部分证据。需要稳定错误码、可否重试及是否重新观察的语义，不能只有一条笼统失败消息。
|
|
- 明确未执行的请求可在预算内按策略重试；结果不明的保存、发送、删除等动作先核对，不盲目重复提交。模型重试不能变成业务用例重提。
|
|
- 沿用插件启动 30 秒、工具 60 秒、关闭 15 秒的配置默认，同时受任务总预算限制；现有参数可以配置，不新增无限等待。
|
|
- 远端动作无法确认停止时保护受影响资源，保留现有核对解除机制；不能因本地取消就假定远端已经停止。
|
|
- **不自动恢复业务环境，不建设默认原值快照、恢复计划或统一回滚模块。只有任务提示词提出恢复要求时，才作为普通任务步骤执行和验证。**
|
|
- 正常的连接关闭、录像收尾、进程回收和资源锁释放仍然必需。这些属于运行时清理，不是恢复用户业务配置。
|
|
|
|
## 9. 市场准入、开发资料与验收
|
|
|
|
- 市场仅发布按规则适配且完成相应验证的版本。覆盖多少平台和场景就声明多少，未覆盖项明确标为未验证或预览。
|
|
- 公共验收覆盖安装和兼容性、输入输出契约、错误/部分结果、超时取消、资源互斥、版本固定、证据导出和生命周期清理。
|
|
- 视觉插件额外验证窗口遮挡、DPI、多屏、窗口/目标切换、截图来源、坐标映射，以及声明支持的录像生命周期和回看。
|
|
- 录像验收覆盖长程体积、编码开销、中文可读性、快速动作、暂停恢复、丢失区间、多端时间映射、关键节点跳转、兼容回退和磁盘不足。
|
|
- 文件插件覆盖中文路径、覆盖保护和传输校验；终端/API 插件按其能力验证原生结果和副作用，不要求跑视觉专属项目。
|
|
- 提供最小可运行模板、公共规范、能力示例和自动合规检查命令；示例包含执行、网页展示和资料导出的完整路径。
|
|
- 延续 HTTPS、文件校验、平台兼容、安全解压与同版本不可覆盖规则。升级由用户发起，排队、暂停和运行任务固定版本；同一资源整条任务串行。
|
|
- 沿用用户启用时授权的范围，不新增逐动作确认；密钥不能进入普通查询、日志和报告。参数范围检查不宣称是操作系统沙箱。
|
|
|
|
## 10. 待实施顺序与检查点
|
|
|
|
- [ ] 定义公共结果/附件/时间契约及各能力声明，补齐错误与副作用语义和兼容迁移。
|
|
- [ ] 完成 Flash/Pro 的来源隔离与步骤分组，验证默认安卓任务调用插件、同插件跨窗口及多图证据。
|
|
- [ ] 实现电脑录像、统一录制生命周期和高效留档参数，实测后确定默认值及兼容回退。
|
|
- [ ] 实现多来源回看、缺口展示、关键节点与播放状态同步。
|
|
- [ ] 完成单任务/批次导出索引、原生附件和各报告一致性。
|
|
- [ ] 按 ARTEMIS 规则适配首发插件与 Skill，交付模板、能力附录及合规检查。
|
|
- [ ] 完成确定性检查、真实环境和长期运行验收，记录实测范围再发布。
|
|
|
|
已有静态检查发现两项需要复现验证的风险：Pro 对默认安卓任务调用插件时的图片隔离可能不完整；插件前图缓存按插件标识而非具体目标区分，跨窗口可能引用旧图。它们是待验证项，不应在复现前写成已确认故障或已修复。
|