6.0 KiB
6.0 KiB
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。启动只提示源码更新；升级使用 update.bat / update-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 快进，保护已有配置和本地修改。
update*.bat保持精简的 ASCII 入口；升级程序及其辅助脚本先复制到项目外执行。更新后通过新版start.ps1 -PrepareOnly -SkipUpdate同步环境，保留此内部调用约定，避免继续运行旧版安装函数。- 前端遵循现有简体中文文案与视觉样式；不直接编辑构建产物。
Definition of Done
- Python 行为改动运行默认测试、Ruff 两项检查、质量基线和核心类型检查；前端改动遵循局部指南的测试与构建要求。
- 文档改动核对命令、相对链接和功能说明；仅文档变更无需启动设备或调用付费模型。
- 默认测试不依赖设备、密钥或私有服务；外部测试按现有 android、integration、e2e、cloud、manual 标记分层，不默认执行全量外部测试。
- 设备验证沿用用户指定设备；多设备且未指定时先确认。编写应用交互测试前，先通过 ARTEMIS 探索实际页面和操作路径。
- 提交前检查
git diff --check和暂存范围；报告实际执行的验证及未完成项，不将未运行的检查写成通过。
Boundaries
- 始终保护用户任务、历史库、环境配置和凭据。不要把个人设备序列号、绝对目录或 API Key 写入源码。
- 删除历史、清空设备数据、停止用户正在运行的任务或覆盖已有配置，需要明确授权；已有授权不重复询问。
- 不提交
.env、虚拟环境、依赖目录、执行记录和编译产物；发布源码使用仓库打包脚本。 - 不通过强推、禁用 TLS、绕过钩子或降低测试要求来完成交付。推送成功须核验远端提交。