ARTEMIS 仓库协作指南

Project Overview

本仓库是基于 ARTEMIS 扩展的 Android AI 自动化测试平台，提供简体中文网页、OpenAI Responses 模型调用、批量任务、历史检索及 Word/Excel 报告。后端使用 Python 3.12+、FastAPI、LangGraph，前端使用 Angular，AI 客户端通过 MCP 接入。

Scope

本文件适用于整个仓库；子目录的 AGENTS.md 在对应目录内优先。
当前任务的用户指令优先于仓库指南。保留用户已有修改，只处理本次任务范围。
本文件指导开发；使用软件执行 Android 测试时，阅读自动化 Skill。
以下是项目原生命令；宿主要求 RTK 等包装器时按宿主规则调用，不把本机路径或工具写成项目安装前提。

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。开发中需要保留当前源码时传入 -SkipUpdate，避免启动脚本拉取远端更新。

Key Paths

artemis/agents/、artemis/runtime/：Flash/Pro 执行、设备与任务运行时。
artemis/llm/、artemis/services/llm.py：模型请求、超时、重试与恢复。
artemis/config/、.env.example：运行配置、环境变量及默认值。
config/artemis.jsonc、artemis/resources/config/artemis.jsonc：开发与打包使用的配置，默认值变更须同步。
apps/admin_console/：HTTP API、统一队列、批次、历史及报告服务。
apps/showcase_ui/：Angular 网页；遵循前端指南。
mcp_server/：MCP 工具与客户端使用规则。
packages/artemis-client/：远程 Python SDK；skills/artemis-automation/：随源码分发的 AI 使用技能。
scripts/：安装、镜像、升级、检查及打包脚本。
tests/unit/、tests/tools/、packages/artemis-client/tests/：默认测试范围。

Architecture Boundaries

模型传输只使用 OpenAI Responses，不恢复 Gemini 专用调用或 Chat Completions 分支。API 模型名与 Flash/Pro 执行模式分开处理。
网页和工作区 MCP 工具复用后台配置、队列、历史和报告服务；不要另建调度器或第二套状态存储。
批次创建与执行分开；保持 request_id 幂等性。同设备串行，失败项不自动重跑；模型重试不能变成业务用例重提。
区分“执行完成”与“验证通过”。报告结论必须有实际证据，保留未验证、失败、跳过和中断状态。
设备动作回放已移除；只读历史步骤、截图和上下文回忆仍保留，不因 replay 命名误删这些能力。
密钥仅通过网页或环境配置写入，读取配置不得回显；MCP 不接受密钥。全局配置修改影响后续任务。
默认 high、请求超时 300 秒、失败后重试 5 次、间隔 10 秒，视频分析与录屏关闭。接口不支持思考强度时明确报错，不静默降级。

Conventions

Python 使用绝对导入、4 空格缩进和双引号，由 Ruff 检查；不要放宽质量基线来掩盖新增问题。
新增可调参数集中进入配置层，并更新环境示例、网页/MCP 入口和必要文档，避免散落硬编码。
MCP 工具增删时同步工具注册、CLI 安装白名单、测试、Skill 和能力文档。
Windows PowerShell 启动脚本保持兼容 Windows PowerShell 5.1，避免编码导致解析失败。升级只做 Git 快进，保护已有配置和本地修改。
前端遵循现有简体中文文案与视觉样式；不直接编辑构建产物。

Definition of Done

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

Boundaries

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

References

用户入口：安装、配置与日常使用。
AI 自动化：MCP、Skill 及升级行为。
工作区说明：报告、批量导入和历史检索。

5.6 KiB Raw Blame History Unescape Escape