Artemis-Eapil/docs/development-handoff.md

开发交接：2026-10-19

2026-10-24 开发主线已迁入新会话，迁入基线为 2.1.0；2026-10-26 工作区已升至 2.2.0，尚未发布，完整增量见2.2.0 说明。新增工作与待办优先级见本轮主线计划；以下保留原始迁入快照，不将其提交号、分叉计数或测试数量视为当前状态。

本文件保留 2026-10-19 从《Artemis开发主线-1017-2》迁入时的开发快照。历史结论已结合代码、发行说明和当时的本地 Git 引用核对；后续开发以仓库指南、设计约定和实时 Git 状态为准，以下提交号与分叉计数不随后续提交自动更新。

迁入时插件仓库有本地改动及分叉，不能用该工作目录代表已发布版本。 后续发布应明确本次范围，保留尚未归并的开发现场。

当前仓库与版本

两个项目是工作区中的独立 Git 仓库：主程序目录 artemis，相邻插件目录 Artemis-Plugins。后续分别检查各自的分支、改动和验证结果。

项目	本次核实的基线	工作区现场
主程序	main、本地 eapil/main、v2.0.0 标签解引用均为 973ccae	已跟踪文件无修改；根目录存在未跟踪的 .angular/ 缓存，不纳入提交
插件	本地 main 为 1eb77e6，本地 origin/main 为 cf110b7；本地分支领先 3 个、落后 6 个提交	有 OCU 修改、未跟踪的 Cua 适配源码及构建、滚动、基准测试文件，全部保留

以上远端分支名称指本地已有的跟踪引用，本次没有联网刷新。后续修改前需重新读取 Git 状态。

主程序 2.0.0 曾重新发布：首次合并提交为 f4cb55c，当前应以包含后续修复的 973ccae 为准。完整说明见 2.0.0 发行说明。

插件存在三种不同状态，后续必须明确区分：

• 本地 catalog.json 仍列出 OCU 1.0.0，本地 Cua 文档仍描述 0.1.2 候选。
• 本地 origin/main 的市场索引已改为 Cua 0.36.0+artemis.4；OCU 已从市场入口下架，旧安装和历史保留。
• 用户机器实际安装的插件版本需另行查询，不能由仓库版本推定。

已完成的开发主线

范围	当前能力与约定	主要说明
中文与模型调用	简体中文网页；模型传输统一 OpenAI Responses，移除 Gemini 原生分支；支持视觉、工具调用、流式及结构化结果	用户入口
可保存配置	网页保存接口、模型、思考强度、超时重试和功能开关；保留已有配置，密钥查询只返回配置状态	配置示例
批量、历史与报告	Excel 模板、校验与预览、按用例配置、循环与选中执行、暂停恢复；历史搜索分页、人工复验；Word、Excel、ZIP 与证据导出	工作区说明
探索	持续交流、补充指导、人工示范、预算暂停继续；成功后提炼一个可编辑版本的用例，供 Flash/Pro 复跑或加入批次	探索说明
插件与跨端证据	安装、授权、启用插件；统一资源调度、步骤来源、截图、录像、文件附件与证据索引	插件说明、开发规范
精选任务	收藏任务、探索用例和批次；独立保存模板与执行配置，首页复跑；旧收藏按实际记录补全配置	2.0.0 发行说明
MCP 与 Skill	轻量连接用户已启动的主程序；覆盖执行、探索、收藏、批次、诊断与导出；启动时同步官方 Skill，并保留客户端工具策略	AI 接入、随仓库分发的 Skill
性能与诊断	稳定多轮上下文与缓存前缀，减少重复摘要和无关手机截图；请求阶段与实际用量可追踪；复用未变化的终态资料包	2.0.0 发行说明
安装与升级	官方源/国内镜像启动，独立快进升级，保护配置与历史，使用源码打包脚本	仓库指南

设备动作回放曾在早期实现，随后已按用户要求移除。历史步骤、截图、只读回看与上下文回忆仍保留；不能因文件中出现 replay 就把这些能力当作待删代码，也不恢复旧动作回放方案。

最近修复及其原因

• 最终验收与请求预算冲突：原先整段验收在 180 秒时取消，比单次请求 300 秒还短，使请求重试没有机会发生。现在最终验收有独立总预算，协调模型超时与重试，保留已有工具证据；只重试失败的模型请求，不重复设备业务动作。任务本身的执行时限仍有效。
• 完整结论后才显示通过：有效结构化结果直接校验，减少重复模型格式转换；取消或截断的流式内容会丢弃。页面与下载诊断区分验收阶段、请求重试耗尽、总预算耗尽和用户中断。
• 电脑示范错误转到安卓执行：实际示范来源贯穿分析、澄清、规划、执行、验收和用例提炼；规划同时获得可用插件信息。补充网址不等于更换平台，手机成功不能代替电脑验收。
• 窗口示范错误录制双屏：人工示范遵循窗口/屏幕配置；窗口模式跟随当前前台窗口，只保留一路录像。无有效窗口时保留缺口，不扩大到整个桌面。
• 探索建议与布局：建议使用用户口吻，点击先填入草稿，发送后才继续；星标只占标题位置，示范来源与按钮等高对齐。

历史上多次出现服务仍从旧工作树加载构建的问题。遇到“源码已改但页面没变”，先核对服务的实际源码目录和构建来源。本次确认当前虚拟环境中的 artemis 解析到主仓库；未检查或重启正在运行的服务。

默认设置与持续约束

设置	新安装默认值或上限
普通任务模型 / 思考强度	gpt-6-luna / high
探索模型 / 思考强度	gpt-6.1-sol / high，单独保存
单次模型请求	300 秒；失败后最多重试 5 次，间隔 10 秒
视频分析 / 普通任务录屏	默认关闭；人工示范录制独立管理
探索主动执行预算	每段 1800 秒；等待回答和人工示范不计入，耗尽后暂停，可继续
人工示范时长	默认上限 900 秒，可延长；超时保存并暂停
上下文参照上限 / 默认历史压缩预算	300k / 80k token；不是整条任务累计用量限制
高效录像留档	默认长边 1280、15 fps；编码与回退遵循现有配置

已保存配置优先，不能把这些默认值强制写回用户环境。旧模型已从预设移除，仍可自定义输入；接口不支持指定思考强度时明确报错。

后续实现持续遵守：

• 网页、MCP、SDK 复用后台配置、队列、历史与报告服务；不另建业务调度器或第二套状态存储。MCP 连接用户启动的主程序。
• 创建批次与执行分开，提交保持 request_id 幂等；同设备和共享桌面资源按现有锁串行，任务固定插件版本。
• 模型请求重试不变成业务用例重提；结果未知的写操作先核对，不盲目重发。
• 执行结束、工具成功、独立业务验证、AI 最终裁定分别记录。缺少电脑证据、报告或关键检查项时不能直接判通过，也不改写旧任务结论来代替复测。
• 示范和截图保留实际来源；控件、截图编号、窗口几何或 DPI 变化后重新观察。录屏质量设置不降低模型定位截图质量。
• 只读最终验收前停止普通录屏；无录像时段明确保留缺口，历史丢失的画面不能补造。
• 业务环境恢复由任务提示词提出；不新增默认业务回滚系统。连接关闭、录制收尾、进程回收和资源锁释放仍由运行时负责。
• 密钥不进入 MCP 参数、查询结果、日志或报告。保护用户配置、历史与运行现场；新代码不包含个人设备号、绝对目录或凭据。
• 变更配置默认值时同步开发和打包配置；变更 MCP 工具时同步注册、安装白名单、测试、Skill 和能力文档。

缓存命中率按 API 实际用量加权统计，不能承诺固定命中率或把缓存输入当作消失的 token。历史公告中的“约 81%”是条件计算：假设输入命中率 90%、缓存输入单价为普通输入的 10%，输入费用可下降约 81%；不是总 token 或总账单的固定降幅。Cua 小样本中的约 26.1% token 差异也不能外推为普遍收益。

协同开发入口

修改目标	主仓库入口
模型传输、超时、重试与请求诊断	artemis/llm/、artemis/services/llm.py、apps/admin_console/services/request_diagnostics.py
默认值与配置保存	artemis/config/、config/artemis.jsonc、artemis/resources/config/artemis.jsonc、apps/admin_console/services/model_settings_service.py
探索、示范与用例提炼	artemis/exploration/、apps/admin_console/services/exploration_service.py
插件运行、截图、录像与附件	artemis/plugins/、apps/admin_console/routers/plugins.py
队列、批次、收藏、报告	apps/admin_console/services/，优先复用现有服务
网页	apps/showcase_ui/，先读局部指南
MCP、远程 SDK、AI 使用规则	mcp_server/、packages/artemis-client/、skills/artemis-use/
插件适配包与市场	插件仓库的 plugins/、scripts/、tests/、catalog.json；先明确比较的是本地现场还是发布引用

下一次修改插件前，先比较分叉提交及全部本地改动，再按具体任务选择保留、迁移和合并范围。可在插件目录只读查看：

rtk proxy git status --short --branch
rtk proxy git log --left-right --oneline main...origin/main
rtk proxy git diff --stat
rtk proxy git show origin/main:plugins/cua-driver/RELEASE.md

验证基线与仍需实测的范围

以下是原开发记录及重新发行说明保存的结果，本次没有重跑：后端默认测试 2943 项通过、2 项跳过、8 项按标记排除；前端 290 项通过，生产构建、Ruff 两项、质量基线与核心类型检查通过。最近的示范来源和录制范围修复未调用付费模型完整复跑业务任务。

后续不能据此宣称以下范围已全部验证：

• 用户原先失败的完整手机/电脑业务流程，以及最近修复后的真实示范、恢复、执行与验收闭环。
• 多 DPI、多显示器、复杂控制台、跨端长任务、长时间资源开销及并发压力。
• 安卓与电脑同时示范的完整组合、真实 15 分钟示范上限，以及外部 Agent 经安装后的 MCP 完整操作链。
• 网关缓存路由、辅助摘要调用的缓存收益和稳定费用降幅，需同任务实测及请求级记录支持。

Cua 仍为 Windows x64 预览。前台操作会占用用户桌面；PNG 保存成功不等于有效观察，少量通过任务也不证明所有浏览器、窗口或业务均可靠。

旧开发工作树和 artifacts/worktree-archive 已按用户要求删除，本次确认目录不存在。继续使用当前主目录及相邻插件目录，不重建旧归档作为开发前提。

涉及 Python 行为修改时，在主仓库执行规定检查：

rtk proxy uv run pytest
rtk proxy uv run ruff format --check .
rtk proxy uv run ruff check .
rtk proxy uv run python scripts/quality_ratchet.py
rtk proxy uv run pyright --project pyright-core.json
rtk proxy git diff --check

前端修改在 apps/showcase_ui 执行，并验证实际布局与关键交互：

rtk proxy npm test -- --watch=false --browsers=ChromeHeadless
rtk proxy npm run build

本机外部命令沿用 RTK 包装；PowerShell cmdlet 和控制流不套 RTK。默认测试不调用设备、私有服务或付费模型。实际应用交互先通过 ARTEMIS 探索，设备沿用用户指定对象。

本次交接的核对依据

证据	结论	后续使用方式
用户迁入记录、发行说明、主仓库 Git 日志及标签解引用	重发后的 2.0.0 基线为 973ccae，早期“未提交/未发布”状态已被后续记录覆盖	从当前主目录继续开发，按新需求修改
插件仓库 git status、分叉日志及 git show origin/main:catalog.json	本地 OCU/Cua 候选现场与发布的 Cua .4 不一致	保留现场，先比较再处理分叉，不把旧候选文档当作最新市场状态
当前源码定位、配置默认值、仓库指南与前端指南	架构边界、入口与验证命令可继续沿用	新任务先读对应局部规则，按变更范围验证

docs/plans/ 是阶段性设计记录，其中“未发布”“待验证”等文字保留各自时点含义；当前发布状态以发行说明、对应版本源码及实际验证记录为准。