91 lines
8.4 KiB
Markdown
91 lines
8.4 KiB
Markdown
# 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)，保持标准库薄客户端边界 |
|
||
| 继续历史开发、确认版本或发布 | [迁入时的开发快照](docs/development-handoff.md)、[2.1.0 发行说明](docs/releases/2.1.0.md)，再核对实时 Git 状态；`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 入口和必要文档；默认值同步 `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` 和暂存范围，只暂存本次具体路径；报告实际执行的验证及未完成项，不将未运行的检查写成通过。
|
||
|
||
## Boundaries
|
||
|
||
- 始终保护用户任务、历史库、环境配置和凭据。不要把个人设备序列号、绝对目录或 API Key 写入源码。
|
||
- 删除历史、清空设备数据、停止用户正在运行的任务或覆盖已有配置，需要明确授权；已有授权不重复询问。
|
||
- 不提交 `.env`、虚拟环境、依赖目录、执行记录和编译产物；发布源码使用仓库打包脚本。
|
||
- 不通过强推、禁用 TLS、绕过钩子或降低测试要求来完成交付。推送成功须核验远端提交。
|
||
|
||
## References
|
||
|
||
- [用户入口](README.md)：安装、配置与日常使用。
|
||
- [设计约定](DESIGN.md)：当前架构、行为与网页视觉规则。
|
||
- [AI 自动化](docs/ai-automation.md)：MCP、Skill 及升级行为。
|
||
- [工作区说明](docs/automation-workspace.md)：报告、批量导入和历史检索。
|