feat: add Android task file evidence and finalize plugin design

docs/ai-automation.md

@@ -14,6 +14,14 @@
 
 > 搜索昨天包含“登录”的失败任务，根据截图与步骤说明失败原因，不重跑。
 
+> 把当前安卓屏幕保存成 PNG 到本次任务的 trace 目录，并再保存一份到电脑桌面，返回实际文件路径。
+
+Flash 和 Pro 都支持任务内的安卓文件工具 `android_file`：保存原生截图、列目录、读写 UTF-8 文本、在手机与任务目录/桌面之间传输文件。默认保存位置为 `traces/<trace_id>/artifacts/android/`，指定桌面时保留 trace 副本；Windows 会识别重定向的真实桌面。文本上限 64 KiB，单文件传输上限 64 MiB，每次 ADB 操作最多 60 秒，取消或超时会回收子进程。默认不覆盖已有文件，也不绕过 Android 文件访问权限。保存和传输会校验实际内容，返回文件路径、大小与 SHA-256；用例是否通过仍需结合画面和预期判断。
+
+新保存的截图及下载文件会进入单任务“全部资料”和批次 ZIP 的 `任务文件/安卓/`。原有自动步骤截图仍位于 `traces/images/`，按步骤截图下载；二者用途不同，历史截图不能作为当前画面的新截图。
+
+文件操作结果会进入任务执行记录，Flash 中也逐项记录操作步骤及校验结果，供终检和报告引用；不会只留下模型自行撰写的“已完成”说明。
+
 ## MCP 能力
 
 | 工具 | 功能 |
@@ -38,7 +46,7 @@ Python 按 `uv.lock` 同步缺失/变化的依赖；前端依据源码、资源
 
 scrcpy 固定版本的国内下载采用多个来源，失败或 SHA256 不符时自动尝试下一来源，全部失败会显示 HTTP 状态、超时或校验原因。`config/downloads.json` 的 `overrides.scrcpy_url` 指定首选 HTTPS 地址，`overrides.scrcpy_fallback_urls` 指定备用地址数组；`null` 使用默认备用源，`[]` 禁用备用源。国内模式不自动回退到 GitHub 直连。
 
-MCP 同步仅检查 `$CODEX_HOME/config.toml`；未设置或为空时使用当前用户的 `~/.codex/config.toml`。日志会显示实际路径，以及新装、更新、已是最新、未检测到或自定义跳过的结果。检测到目录但缺少 ARTEMIS 条目时安装当前源码的标准配置；已有标准配置即使指向旧解压目录，也会更新解释器、项目目录、环境路径和工具清单。保留用户额外环境变量、禁用状态及其他服务；自定义启动包装器保持原样并提示。其他客户端的配置和规则文件不读取、不修改，其格式错误不会阻止启动。Codex 配置无法安全解析时停止启动，原文件不被覆盖；可使用 `-SkipMcpSync` 仅启动网页。首次修改保留备份。同步后需在 Codex 中重新加载 MCP 或重启 Codex，脚本无法替宿主重启已加载的 MCP 进程。
+MCP 同步仅检查 `$CODEX_HOME/config.toml`；未设置或为空时使用当前用户的 `~/.codex/config.toml`。日志会显示实际路径，以及新装、更新、已是最新、未检测到或自定义跳过的结果。检测到目录但缺少 ARTEMIS 条目时安装当前源码的标准配置；已有标准配置即使指向旧解压目录，也会更新解释器、项目目录、环境路径和工具清单。保留用户额外环境变量、禁用状态、`tools` 下的工具审批策略及其他服务；不会重建权限表、添加 `eager` 或删除旧工具策略。自定义启动包装器保持原样并提示。其他客户端的配置和规则文件不读取、不修改，其格式错误不会阻止启动。Codex 原配置无法解析，或同步程序生成的更新未通过校验时，均停止启动且不覆盖原文件；日志会区分这两种原因，不把同步生成错误归因于用户配置。遇到后者请更新 ARTEMIS，不要删除有效的 `config.toml`；可使用 `-SkipMcpSync` 临时仅启动网页。首次修改保留备份。同步后需在 Codex 中重新加载 MCP 或重启 Codex，脚本无法替宿主重启已加载的 MCP 进程。
 
 创建批次时必须提供唯一 `request_id`；请求超时后可以按编号查询或用相同内容重发，避免重复用例。创建只保存草稿，`start` 才执行。AI 无需先制造 Excel，也可直接提交 JSON；字段与示例见 [Skill 批量任务参考](../skills/artemis-automation/references/batches.md)。
 

docs/plans/2.0.0-plugin-evidence.md

@@ -0,0 +1,108 @@
+# 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 对默认安卓任务调用插件时的图片隔离可能不完整；插件前图缓存按插件标识而非具体目标区分，跨窗口可能引用旧图。它们是待验证项，不应在复现前写成已确认故障或已修复。

docs/plans/2.0.0-plugins.md

@@ -2,6 +2,8 @@
 
 状态：核心插件链路、首发 Windows 插件适配已实现；Flash/Pro 纯电脑任务和基础浏览器表单实测通过，跨端与长期稳定性验收仍在进行，不是正式发行。
 
+2026-10-15 已确认下一阶段的[插件步骤、录像与开发规范](2.0.0-plugin-evidence.md)。该文档是待实现的设计，包含电脑录像、统一回看、节省空间的留档策略及插件适配要求，不代表这些功能已经上线。
+
 开发分支：`codex/v2.0.0-plugins`，从 1.5.2 主线建立。版本号为 2.0.0，发布前不创建正式版本标签。1.5.x 的 BUG 修复继续在主线进行，后续正常合并进开发分支。
 
 插件市场仓库：<https://git.playones.com/chenmingxuan/Artemis-Plugins>
@@ -31,7 +33,7 @@
 - 用户启用插件时授权其控制范围，范围内自动执行；超出范围等待用户指导。
 - 执行层校验可调用工具及可识别的目标参数。第三方进程的系统权限必须如实说明，工具参数检查不能宣称等同于操作系统沙箱。
 - AI 从已启用且配置就绪的插件中按需选择，按需加载工具、Skill 及其引用资源。
-- 复用第三方 Skill 时适配工具名称和运行环境。依赖宿主专用 API 的 Skill 需要对应适配，不能仅复制文件就宣称可用。
+- 复用第三方插件或 Skill 时，必须按 ARTEMIS 的工具、资源、权限、步骤、证据及错误契约适配并验证。可保留适用的原工具实现；依赖宿主专用 API 的 Skill 需要对应适配，不能仅复制文件就宣称可用。
 
 ## 任务执行和共享资源
 
@@ -48,10 +50,10 @@
 
 ## 环境恢复和报告
 
-- 环境恢复由任务提示词或配置决定，不统一强制回滚。
-- 具备读取能力时记录配置修改前后的值；要求恢复时将恢复纳入结束阶段并验证，失败单独展示并标记受影响资源。
+- 不自动恢复业务环境，不建设默认的原值快照或回滚流程。只有用户任务提示词要求恢复时，才按任务执行并验证恢复；配置不会另行触发恢复。
+- 按提示词执行的恢复失败时，在对应步骤和报告中如实记录。插件连接、录像进程及资源锁仍按正常生命周期清理。
 - 手机、电脑和浏览器操作进入同一时间线，记录资源、插件版本、耗时、动作结果及证据来源。
-- 首版电脑证据以步骤截图和工具结果为主。保留 Android 录屏，插件接口允许返回视频附件，电脑持续录屏后续扩展。
+- 当前电脑证据以步骤截图和工具结果为主，已有 Android 录屏。已确认将电脑持续录屏、多来源同步回看和统一证据附件纳入本次 2.0.0 后续开发，按上述专项设计实施；目前尚未实现。
 - 执行完成与测试通过继续分开。缺少验收证据时记录未验证或阻塞，保留已有明确结论，人工复验沿用现有优先级。
 - 网页、Word、Excel、单任务资料包和批次资料包提供一致的跨端结果与证据。
 - 对外 MCP、参数文档和随源码分发的自动化 Skill 同步新任务配置及能力查询。

docs/plugins.md

@@ -48,7 +48,7 @@ SDK：先 `await agent.init(execution_target="computer")`，然后 `agent.new_ta
 
 暂停会先取消调用并关闭插件连接，再释放任务资源；恢复排队后重新观察。插件取消/超时的写操作可能已经生效，不能盲目重放。如果远程服务未确认动作停止，页面会显示资源保护及原因，用户核对后点击「已核对，解除保护」。这只解除 ARTEMIS 的保护，不会替用户终止远程操作。
 
-工具返回成功表示调用完成，业务是否通过仍需实际证据。图片、工具文本、插件版本和动作结果进入任务记录；已有报告、截图下载和人工复验入口继续使用。Word 的「扩展插件操作」与 Excel 的「插件操作」保留来源及实际结果，资料包截图名称含插件 ID。同一截图被多个任务引用时，删除最后一个任务后才清理。插件画面与手机截图属于不同来源，不能相互替代。电脑持续录屏不属于首版能力。
+工具返回成功表示调用完成，业务是否通过仍需实际证据。图片、工具文本、插件版本和动作结果进入任务记录；已有报告、截图下载和人工复验入口继续使用。Word 的「扩展插件操作」与 Excel 的「插件操作」保留来源及实际结果，资料包截图名称含插件 ID。同一截图被多个任务引用时，删除最后一个任务后才清理。插件画面与手机截图属于不同来源，不能相互替代。电脑持续录屏目前尚未实现，已纳入[步骤、录像与插件开发规范设计](plans/2.0.0-plugin-evidence.md)；该设计不是当前版本的能力声明。
 
 ## 插件清单