83 lines
5.6 KiB
Markdown
83 lines
5.6 KiB
Markdown
# ARTEMIS 仓库协作指南
|
||
|
||
## Project Overview
|
||
|
||
本仓库是基于 ARTEMIS 扩展的 Android AI 自动化测试平台，提供简体中文网页、OpenAI Responses 模型调用、批量任务、历史检索及 Word/Excel 报告。后端使用 Python 3.12+、FastAPI、LangGraph，前端使用 Angular，AI 客户端通过 MCP 接入。
|
||
|
||
## Scope
|
||
|
||
- 本文件适用于整个仓库；子目录的 AGENTS.md 在对应目录内优先。
|
||
- 当前任务的用户指令优先于仓库指南。保留用户已有修改，只处理本次任务范围。
|
||
- 本文件指导开发；使用软件执行 Android 测试时，阅读 [自动化 Skill](skills/artemis-automation/SKILL.md)。
|
||
- 以下是项目原生命令；宿主要求 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 网页；遵循 [前端指南](apps/showcase_ui/AGENTS.md)。
|
||
- `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
|
||
|
||
- [用户入口](README.md)：安装、配置与日常使用。
|
||
- [AI 自动化](docs/ai-automation.md)：MCP、Skill 及升级行为。
|
||
- [工作区说明](docs/automation-workspace.md)：报告、批量导入和历史检索。
|