# ARTEMIS 仓库协作指南

## Project Overview

本仓库是基于 ARTEMIS 扩展的自动化测试平台，提供简体中文网页、Flash/Pro 执行、交互探索、插件跨端操作、精选任务、批量任务及 Word/Excel 报告。后端使用 Python 3.12+、FastAPI、LangGraph，前端使用 Angular；模型统一使用 OpenAI Responses，AI 客户端通过轻量 MCP 桥接用户启动的主程序。

## Scope

- 本文件适用于整个仓库；子目录的 AGENTS.md 在对应目录内优先。
- 当前任务的用户指令优先于仓库指南。保留用户已有修改，只处理本次任务范围。
- 主程序与 `Artemis-Plugins` 是独立仓库。跨仓库任务分别检查分支、未提交改动和远端状态；发布文档或修复时，不夹带已有未发布提交。必要时使用隔离工作树，只移植本次提交。
- 本文件指导开发；使用软件执行设备或跨端任务、排查任务时，阅读 [自动化 Skill](skills/artemis-use/SKILL.md)。
- 以下是项目原生命令；宿主要求 RTK 等包装器时按宿主规则调用，不把本机路径或工具写成项目安装前提。

## Read When Needed

| 修改范围 | 先读 |
| --- | --- |
| 执行、验收、探索、插件或证据的职责边界 | [DESIGN.md 的架构与行为约定](DESIGN.md#system-architecture) |
| 网页布局、样式或交互 | [视觉与交互设计](DESIGN.md#colors)及[前端指南](apps/showcase_ui/AGENTS.md) |
| 探索、示范、用例提炼与复跑 | [探索说明](docs/exploration-mode.md) |
| 插件协议、适配或市场协同 | [插件开发规范](docs/plugin-development.md)及插件仓库自身的 AGENTS.md、DESIGN.md |
| 远程 Python SDK | [SDK 设计](packages/artemis-client/DESIGN.md)，保持标准库薄客户端边界 |
| 继续历史开发、确认版本或发布 | [README 当前发行入口](README.md)、对应发行说明及实时 Git 状态；[开发快照](docs/development-handoff.md)与 `docs/plans/` 仅作为历史线索，不替代当前源码与发布包核验 |

## Quick Commands

在仓库根目录执行，前端命令见局部指南：

| 用途 | 命令 |
| --- | --- |
| 安装锁定的开发依赖 | `uv sync --dev --locked` |
| 启动已准备好的网页服务 | `uv run artemis ui --no-open` |
| 环境诊断 | `uv run artemis doctor` |
| 默认确定性测试 | `uv run pytest` |
| 格式检查 | `uv run ruff format --check .` |
| 静态检查 | `uv run ruff check .` |
| 质量基线检查 | `uv run python scripts/quality_ratchet.py` |
| 核心类型检查 | `uv run pyright --project pyright-core.json` |
| 源码打包 | `uv run --no-sync python scripts/package_source.py` |

Windows 首次安装使用 `start.bat`，国内镜像使用 `start-cn.bat`。启动只提示源码更新；升级使用 `update.bat` / `update-cn.bat`，会终止本项目运行进程。开发中可传入 `-SkipUpdate` 跳过更新提示。

## Architecture Boundaries

- 模型传输只使用 OpenAI Responses，不恢复 Gemini 专用调用或 Chat Completions 分支。API 模型名与 Flash/Pro 执行模式分开处理。
- 网页、MCP 与 SDK 复用后台配置、队列、历史和报告服务；不另建调度器或第二套状态存储。MCP 不自行启动完整后台，主程序离线时仍可握手并明确提示连接状态。
- 批次创建与执行分开；保持 `request_id` 幂等性。同设备及共享桌面资源按现有锁串行，任务固定插件版本；失败项不自动重跑，模型重试不能变成业务用例重提，结果不明的写操作不盲目重发。
- 最终验收使用独立总预算，协调单次模型超时与重试；不能套用中间检查点的 180 秒时限。重试保留已取得的工具证据，用户停止或探索新指导仍可中断。
- 区分执行完成、工具成功和验证通过。正式结论必须经过完整解析与校验，取消或截断的流式内容不能显示为通过；报告、网页、MCP 与人工复验后的有效结论保持一致。
- 示范的实际来源贯穿分析、澄清、规划、执行、验收与用例提炼。补充网址不等于更换平台；用户明确要求改端或跨端时再按要求执行，手机证据不能替代电脑证据。
- 人工示范遵循窗口/屏幕录制配置。窗口模式跟随前台窗口，无有效窗口时保留缺口，不扩大到多屏桌面；普通录屏在只读最终验收前停止，恢复操作时再追加片段。
- 探索主动执行预算耗尽后保留进度并暂停，不直接判失败；探索成功、用例提炼成功和固定版本复跑通过分别记录。收藏保存独立模板与配置，不依赖原任务一直存在。
- 历史压缩、视觉摘要与工具上下文调整须保留关键文件回执和来源，维护稳定的多轮前缀；缓存率使用实际用量加权统计，不把缓存输入当作消失的 token，也不承诺固定收益。
- 设备动作回放已移除；只读历史步骤、截图和上下文回忆仍保留，不因 replay 命名误删这些能力。
- 密钥仅通过网页或环境配置写入，读取配置不得回显；MCP 不接受密钥。全局配置修改影响后续任务，已保存配置优先于新安装默认值。
- 新安装普通任务默认 `gpt-6-luna / high`，探索默认 `gpt-6.1-terra / high`；请求超时 300 秒、失败后重试 5 次、间隔 10 秒，视频分析与普通录屏关闭。接口不支持思考强度时明确报错，不静默降级。
- 业务环境恢复由任务提示词提出，不新增默认业务回滚流程；连接、录像、子进程和资源锁的运行时收尾仍然必需。

## Conventions

- Python 使用绝对导入、4 空格缩进和双引号，由 Ruff 检查；不要放宽质量基线来掩盖新增问题。
- 新增可调参数集中进入配置层，按作用域更新环境示例、网页/MCP 入口和文档；明确仅供环境配置的参数不增加前端入口。JSON 默认值同步 `config/artemis.jsonc` 与 `artemis/resources/config/artemis.jsonc`。
- MCP 工具增删时同步工具注册、CLI 安装白名单、测试、Skill 和能力文档。
- 同步 Codex MCP/Skill 时保留已有工具白名单、禁用状态和审批策略；异常时保留原配置并告警，不生成非法 TOML 或阻断网页启动。
- Windows PowerShell 启动脚本保持兼容 Windows PowerShell 5.1，避免编码导致解析失败。升级只做 Git 快进，保护已有配置和本地修改。
- `update*.bat` 保持精简的 ASCII 入口；升级程序及其辅助脚本先复制到项目外执行。更新后通过新版 `start.ps1 -PrepareOnly -SkipUpdate` 同步环境，保留此内部调用约定，避免继续运行旧版安装函数。
- 前端遵循 DESIGN.md 与局部指南，复用现有组件和简体中文文案；不直接编辑构建产物。页面仍显示旧效果时，先核对实际服务的源码目录及构建来源。

## Definition of Done

- Python 行为改动运行默认测试、Ruff 两项检查、质量基线和核心类型检查；前端改动遵循局部指南的测试与构建要求。
- 文档改动核对命令、相对链接和功能说明；历史测试数量与未测范围见对应版本记录，不能冒充本次验证。仅文档变更无需启动设备或调用付费模型。
- 默认测试不依赖设备、密钥或私有服务；外部测试按现有 android、integration、e2e、cloud、manual 标记分层，不默认执行全量外部测试。
- 设备验证沿用用户指定设备；多设备且未指定时先确认。编写应用交互测试前，先通过 ARTEMIS 探索实际页面和操作路径。
- 提交前检查 `git diff --check` 和暂存范围，只暂存本次具体路径；报告实际执行的验证及未完成项，不将未运行的检查写成通过。

## Release Gates

- 主程序、SDK、插件和第三方依赖独立版本化。主程序升版只修改 `pyproject.toml` 的项目版本、`uv.lock` 的 artemis 条目及前端应用的根版本字段，发行文档另行更新。禁止对仓库或整个锁文件全局替换版本字符串。
- 单独审查锁文件差异。第三方条目的版本、下载地址、完整性校验和依赖声明必须相互匹配；主程序升版不应改变这些条目。真正升级依赖时由包管理器生成并核对上游声明；发生 EINTEGRITY 先核验来源，禁止关闭校验或只照错误提示改哈希。
- 发布前必须在隔离目录解压最终 ZIP，使用独立空 npm 缓存完成 `npm ci` 和生产构建，覆盖本次发布的官方/国内安装路径。包内安装或构建输入变化后必须重跑；不得清空用户全局缓存或改动用户运行目录来制造干净环境。
- 记录实际 Node/npm 版本、镜像、源码提交、ZIP SHA256 和验证范围。已有 node_modules、构建指纹、缓存命中或大量单元测试通过，均不能证明全新安装成功；某个 Node 版本通过也不能冒充其他版本实测。测试和构建命令见前端局部指南。
- 发布顺序：固定提交并打包 → 验证最终包 → 推送标签 → 创建草稿并上传包及校验文件 → 回读校验 → 正式发布 → 无认证下载核验。标签必须指向打包提交；推送标签后检查 Release 状态，本仓库曾出现 Gitea 将已有草稿自动发布的情况。失败时修复并重新验证，不提前宣布完成。
- 候选包与正式包目录明确区分。候选包失效后移出可分发路径并标明替代版本，不能留下同名旧 ZIP 供用户误取；对外只给已核验的正式发布链接或准确文件路径。正式版本不覆盖原标签或附件，后续修复发补丁版。
- 安装或市场版本不符时，先核对用户实际 ZIP 的 SHA256、运行源码提交及生效市场地址；不凭界面版本号判断，也不把未经验证的缓存假设当成原因。主程序与插件版本、索引兼容性分别验证。

## Boundaries

- 始终保护用户任务、历史库、环境配置和凭据。不要把个人设备序列号、绝对目录或 API Key 写入源码。
- 删除历史、清空设备数据、停止用户正在运行的任务或覆盖已有配置，需要明确授权；已有授权不重复询问。
- 不提交 `.env`、虚拟环境、依赖目录、执行记录和编译产物；发布源码使用仓库打包脚本。
- 不通过强推、禁用 TLS、绕过钩子或降低测试要求来完成交付。推送成功须核验远端提交。

## References

- [用户入口](README.md)：安装、配置与日常使用。
- [设计约定](DESIGN.md)：当前架构、行为与网页视觉规则。
- [AI 自动化](docs/ai-automation.md)：MCP、Skill 及升级行为。
- [工作区说明](docs/automation-workspace.md)：报告、批量导入和历史检索。