docs: refresh Artemis development and design guides
This commit is contained in:
chenmingxuan committed
1 parent
973ccae679
commit
bf6247703d
5 files changed
+362
-30
No files matched your search
@@ -2,15 +2,27 @@
|
||||
|
||||
## Project Overview
|
||||
|
||||
本仓库是基于 ARTEMIS 扩展的 Android AI 自动化测试平台，提供简体中文网页、OpenAI Responses 模型调用、批量任务、历史检索及 Word/Excel 报告。后端使用 Python 3.12+、FastAPI、LangGraph，前端使用 Angular，AI 客户端通过 MCP 接入。
|
||||
本仓库是基于 ARTEMIS 扩展的自动化测试平台，提供简体中文网页、Flash/Pro 执行、交互探索、插件跨端操作、精选任务、批量任务及 Word/Excel 报告。后端使用 Python 3.12+、FastAPI、LangGraph，前端使用 Angular；模型统一使用 OpenAI Responses，AI 客户端通过轻量 MCP 桥接用户启动的主程序。
|
||||
|
||||
## Scope
|
||||
|
||||
- 本文件适用于整个仓库；子目录的 AGENTS.md 在对应目录内优先。
|
||||
- 当前任务的用户指令优先于仓库指南。保留用户已有修改，只处理本次任务范围。
|
||||
- 本文件指导开发；使用软件执行 Android 测试时，阅读 [自动化 Skill](skills/artemis-use/SKILL.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.0.0 发行说明](docs/releases/2.0.0.md)，再核对实时 Git 状态；`docs/plans/` 保留各自阶段的状态 |
|
||||
|
||||
## Quick Commands
|
||||
|
||||
在仓库根目录执行，前端命令见局部指南：
|
||||
@@ -29,45 +41,39 @@
|
||||
|
||||
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 网页；遵循 [前端指南](apps/showcase_ui/AGENTS.md)。
|
||||
- `mcp_server/`：MCP 工具与客户端使用规则。
|
||||
- `packages/artemis-client/`：远程 Python SDK；`skills/artemis-use/`：随源码分发的 AI 使用技能。
|
||||
- `scripts/`：安装、镜像、升级、检查及打包脚本。
|
||||
- `tests/unit/`、`tests/tools/`、`packages/artemis-client/tests/`：默认测试范围。
|
||||
|
||||
## Architecture Boundaries
|
||||
|
||||
- 模型传输只使用 OpenAI Responses，不恢复 Gemini 专用调用或 Chat Completions 分支。API 模型名与 Flash/Pro 执行模式分开处理。
|
||||
- 网页和工作区 MCP 工具复用后台配置、队列、历史和报告服务；不要另建调度器或第二套状态存储。
|
||||
- 批次创建与执行分开；保持 request_id 幂等性。同设备串行，失败项不自动重跑；模型重试不能变成业务用例重提。
|
||||
- 区分“执行完成”与“验证通过”。报告结论必须有实际证据，保留未验证、失败、跳过和中断状态。
|
||||
- 网页、MCP 与 SDK 复用后台配置、队列、历史和报告服务；不另建调度器或第二套状态存储。MCP 不自行启动完整后台，主程序离线时仍可握手并明确提示连接状态。
|
||||
- 批次创建与执行分开；保持 `request_id` 幂等性。同设备及共享桌面资源按现有锁串行，任务固定插件版本；失败项不自动重跑，模型重试不能变成业务用例重提，结果不明的写操作不盲目重发。
|
||||
- 最终验收使用独立总预算，协调单次模型超时与重试；不能套用中间检查点的 180 秒时限。重试保留已取得的工具证据，用户停止或探索新指导仍可中断。
|
||||
- 区分执行完成、工具成功和验证通过。正式结论必须经过完整解析与校验，取消或截断的流式内容不能显示为通过；报告、网页、MCP 与人工复验后的有效结论保持一致。
|
||||
- 示范的实际来源贯穿分析、澄清、规划、执行、验收与用例提炼。补充网址不等于更换平台；用户明确要求改端或跨端时再按要求执行，手机证据不能替代电脑证据。
|
||||
- 人工示范遵循窗口/屏幕录制配置。窗口模式跟随前台窗口，无有效窗口时保留缺口，不扩大到多屏桌面；普通录屏在只读最终验收前停止，恢复操作时再追加片段。
|
||||
- 探索主动执行预算耗尽后保留进度并暂停，不直接判失败；探索成功、用例提炼成功和固定版本复跑通过分别记录。收藏保存独立模板与配置，不依赖原任务一直存在。
|
||||
- 历史压缩、视觉摘要与工具上下文调整须保留关键文件回执和来源，维护稳定的多轮前缀；缓存率使用实际用量加权统计，不把缓存输入当作消失的 token，也不承诺固定收益。
|
||||
- 设备动作回放已移除；只读历史步骤、截图和上下文回忆仍保留，不因 replay 命名误删这些能力。
|
||||
- 密钥仅通过网页或环境配置写入，读取配置不得回显；MCP 不接受密钥。全局配置修改影响后续任务。
|
||||
- 默认 high、请求超时 300 秒、失败后重试 5 次、间隔 10 秒，视频分析与录屏关闭。接口不支持思考强度时明确报错，不静默降级。
|
||||
- 密钥仅通过网页或环境配置写入，读取配置不得回显；MCP 不接受密钥。全局配置修改影响后续任务，已保存配置优先于新安装默认值。
|
||||
- 新安装普通任务默认 `gpt-6-luna / high`，探索默认 `gpt-6.1-sol / high`；请求超时 300 秒、失败后重试 5 次、间隔 10 秒，视频分析与普通录屏关闭。接口不支持思考强度时明确报错，不静默降级。
|
||||
- 业务环境恢复由任务提示词提出，不新增默认业务回滚流程；连接、录像、子进程和资源锁的运行时收尾仍然必需。
|
||||
|
||||
## Conventions
|
||||
|
||||
- Python 使用绝对导入、4 空格缩进和双引号，由 Ruff 检查；不要放宽质量基线来掩盖新增问题。
|
||||
- 新增可调参数集中进入配置层，并更新环境示例、网页/MCP 入口和必要文档，避免散落硬编码。
|
||||
- 新增可调参数集中进入配置层，并更新环境示例、网页/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` 和暂存范围；报告实际执行的验证及未完成项，不将未运行的检查写成通过。
|
||||
- 提交前检查 `git diff --check` 和暂存范围，只暂存本次具体路径；报告实际执行的验证及未完成项，不将未运行的检查写成通过。
|
||||
|
||||
## Boundaries
|
||||
|
||||
@@ -79,5 +85,6 @@ Windows 首次安装使用 `start.bat`，国内镜像使用 `start-cn.bat`。启
|
||||
## References
|
||||
|
||||
- [用户入口](README.md)：安装、配置与日常使用。
|
||||
- [设计约定](DESIGN.md)：当前架构、行为与网页视觉规则。
|
||||
- [AI 自动化](docs/ai-automation.md)：MCP、Skill 及升级行为。
|
||||
- [工作区说明](docs/automation-workspace.md)：报告、批量导入和历史检索。
|
||||
Reference in new issue
Block a user