android-midscene-automation 0.2.3 → 1.1.0

package/CHANGELOG.md

@@ -1,4 +1,15 @@
 # 更新记录
+## v1.1.0
+- [Artemis]修复自定义模型返回 `<think>` 思考标签导致 Hopper 等节点 JSON 解析失败的问题：非 Google 模型的 Pydantic 结构化输出接入统一清理、提取和校验流程，显式提供 JSON Schema，格式错误时限次要求模型纠正。
+- [Artemis]修复 Flash 步骤摘要和历史压缩仍直接创建 Gemini 客户端的问题：非 Google 模型统一使用配置中的 summarizer 节点及其备用模型；模型初始化错误不再静默切换到 Gemini。
+- [Artemis]修复 Artemis 使用 MiniMax、GLM 等非 Google 默认模型时，辅助检查节点仍强制调用 Gemini 并因缺少密钥导致任务启动失败的问题；支持这些节点继承默认模型或使用显式配置。
+- [Artemis]集成 Google Artemis。
+- [Midscene]Midscene 集成已停止日常维护，现有功能仍保留。
+
+## v0.2.4
+- Midscene Android、Android Playground、Core、Playground、Shared 和 Web 模块统一升级至 1.14.0。
+- 修复 Midscene 测试脚本生成过程中切换“AI 生成 / 自定义步骤编排”会清空生成状态和结果的问题；生成任务继续在后台执行，模式切换后保留已生成步骤与代码。
+
 ## v0.2.3
 - 修复长时间执行 ADB 操作、延时或 AI 识别后，Appium 因默认 60 秒命令空闲超时销毁会话，导致后续 Home 键、点击等节点报“invalid session id”的问题；托管服务关闭会话空闲计时，外部服务通过心跳保活并保留 60 秒空闲回收，避免创建请求取消或清理失败后遗留永久会话。
 - 为启动 App、清理数据、坐标点击与滑动补齐 ADB 超时和取消控制；终止前台检查后不再继续启动 App，异常结束仍清理会话。
@@ -6,7 +17,6 @@
 - 修复远程设备无法手动终止回放的问题，通过独立心跳传递取消信号，兼容任务派发前取消，并阻止同一设备重复提交回放。
 
 ## v0.2.2
-- 更新浅色后台界面：蓝色主色、白色卡片、浅灰背景、可折叠侧边栏与顶部页签。
 - 新增“概览 → 分析页”，根据已保存脚本和真实执行记录分别汇总 Midscene、Appium 测试数据。
 - 修复配置加载失败后出现空白可保存表单的问题，增加独立错误提示和重试；后端断线后自动尝试重连并支持手动重连，保留页面编辑内容。
 - Appium 配置自动保存失败后保留最新待保存内容并提供“重试保存”；修复切换或关闭 Appium 页签后，离开页面时未保存草稿保护失效的问题。

package/README.md

@@ -2,6 +2,30 @@
 
 一个面向 Android App 的自动化测试工具，同时支持 Midscene AI 测试和 Appium 组件树录制回放。
 
+## 界面预览
+
+![](./screen/c1.jpg)
+
+### Midscene
+
+![](./screen/m1.jpg)
+
+![](./screen/m2.jpg)
+
+![](./screen/m3.jpg)
+
+### Appium
+
+![](./screen/a1.jpg)
+
+![](./screen/a2.jpg)
+
+![](./screen/a3.jpg)
+
+![](./screen/a4.jpg)
+
+![](./screen/a5.jpg)
+
 ## 支持的测试方式
 
 | 测试方式 | 页面入口 | 工作方式 | 模型要求 | 适用场景 |
@@ -15,6 +39,34 @@ Appium 方案完全不依赖大模型，不需要填写 Base URL、API Key、Mod
 
 ## 环境要求
 
+### Artemis 控制台集成（可选）
+
+菜单中的 **Artemis** 在主内容区嵌入独立的 Artemis 控制台，支持切换菜单后保留页面状态。首次连接和“重新连接”都会检查服务；未启动或未允许嵌入时显示操作提示。
+
+1. Artemis 源码独立放在项目根目录的 `artemis-main/`，或通过 `ARTEMIS_PROJECT_DIR` 指定源码绝对路径。`artemis-main/` 源码随主项目的 Git / npm 包分发。本地 `config/artemis.jsonc`、`.env`、依赖环境和运行数据不提交、不打包；首次启动会从公开的 `config/artemis.example.jsonc` 生成本地配置，已有配置不会被覆盖。
+2. 安装 `uv`，准备 Python 3.12+、Node.js 22.22.3+（22 LTS）、ADB 和设备；Artemis 前端首次启动时会自动安装依赖并构建。
+3. 在项目根目录运行 `npm run dev`，或使用 `npx android-midscene-automation`，会同时启动主项目与 Artemis；首次会同步 Python 依赖并按需构建 Artemis 前端。启动完成后点击 **Artemis**。API Key、模型和设备在 Artemis 自身的配置中设置，不会自动复用 Midscene 的模型配置。
+
+检测到 Artemis 已运行时会复用该服务；按 Ctrl+C 会停止本次启动的服务，不会停止之前已运行的 Artemis。缺少源码或 Artemis 启动失败时会输出提示，主项目仍可使用。仍可通过 `npm run artemis` 单独启动 Artemis。主项目端口被占用时会明确报错，可通过 `npm run dev -- --port 5174` 指定其他端口，并自动为新启动的 Artemis 配置对应的嵌入来源。
+
+在 Artemis 的“系统设置 → 自定义配置”中点击“编辑 JSONC”，可直接修改并保存当前使用的 `artemis.jsonc`；支持注释和原有排版，保存前校验 JSONC、模型与智能体配置。文件已被其他操作修改时会阻止覆盖，保存失败时保留草稿。“取消编辑”放弃本次修改并重新加载文件。模型配置用于新任务，运行中的任务保持当前设置；API Key 和接口地址仍在 Artemis 的 `.env` 中配置。
+
+修改配置文件或 `.env` 后，点击自定义配置中的“刷新配置”，会重新校验 JSONC 并加载模型密钥和 Base URL，更新“已配置 / 未设置”状态，无需重启服务。刷新只检查本地配置，不调用模型 API 验证密钥；正在编辑草稿时按钮禁用，校验失败时保留当前已加载设置。
+
+专用启动入口仅绑定 `127.0.0.1:8000`，通过 CSP 允许 `localhost` / `127.0.0.1` 的 `5173`、`4173` 端口嵌入，并保留 Artemis 原有的 Host / Origin 校验。原来的 `artemis ui` 默认禁止 iframe；若已启动，需要先停止原服务再执行 `npm run artemis`。终端按 Ctrl+C 停止服务。
+
+可选环境变量：
+
+| 变量 | 用途 |
+| --- | --- |
+| `ARTEMIS_PROJECT_DIR` | Artemis 源码目录，传给 `npm run dev` 或 `npm run artemis` |
+| `ARTEMIS_PORT` | Artemis 服务端口，默认 `8000` |
+| `ARTEMIS_EMBED_ORIGINS` | 允许嵌入的完整来源地址，逗号分隔；主项目使用其他端口时需设置，不接受通配符 |
+| `ARTEMIS_URL` | 主项目后端连接的 Artemis 地址，默认 `http://127.0.0.1:8000`，传给 `npm run dev` 或 `npm run preview` |
+| `ARTEMIS_AUTO_START` | 设置为 `0` 时，`npm run dev` 仅启动主项目；默认自动启动 Artemis |
+
+当前集成面向本机使用。Artemis 与 Midscene/Appium 的任务队列、设备锁和结果各自独立，请不要同时控制同一台设备。
+
 - Node.js 18+
 - npm
 - Android SDK / ADB，移动端自动化测试需要
@@ -1358,6 +1410,17 @@ Linux: ~/.local/share/android-midscene-automation
 
 # 项目更新记录
 
+## v1.1.0
+- [Artemis]修复自定义模型返回 `<think>` 思考标签导致 Hopper 等节点 JSON 解析失败的问题：非 Google 模型的 Pydantic 结构化输出接入统一清理、提取和校验流程，显式提供 JSON Schema，格式错误时限次要求模型纠正。
+- [Artemis]修复 Flash 步骤摘要和历史压缩仍直接创建 Gemini 客户端的问题：非 Google 模型统一使用配置中的 summarizer 节点及其备用模型；模型初始化错误不再静默切换到 Gemini。
+- [Artemis]修复 Artemis 使用 MiniMax、GLM 等非 Google 默认模型时，辅助检查节点仍强制调用 Gemini 并因缺少密钥导致任务启动失败的问题；支持这些节点继承默认模型或使用显式配置。
+- [Artemis]集成 Google Artemis。
+- [Midscene]Midscene 集成已停止日常维护，现有功能仍保留。
+
+## v0.2.4
+- Midscene Android、Android Playground、Core、Playground、Shared 和 Web 模块统一升级至 1.14.0。
+- 修复 Midscene 测试脚本生成过程中切换“AI 生成 / 自定义步骤编排”会清空生成状态和结果的问题；生成任务继续在后台执行，模式切换后保留已生成步骤与代码。
+
 ## v0.2.3
 - 修复长时间执行 ADB 操作、延时或 AI 识别后，Appium 因默认 60 秒命令空闲超时销毁会话，导致后续 Home 键、点击等节点报“invalid session id”的问题；托管服务关闭会话空闲计时，外部服务通过心跳保活并保留 60 秒空闲回收，避免创建请求取消或清理失败后遗留永久会话。
 - 为启动 App、清理数据、坐标点击与滑动补齐 ADB 超时和取消控制；终止前台检查后不再继续启动 App，异常结束仍清理会话。
@@ -1365,7 +1428,6 @@ Linux: ~/.local/share/android-midscene-automation
 - 修复远程设备无法手动终止回放的问题，通过独立心跳传递取消信号，兼容任务派发前取消，并阻止同一设备重复提交回放。
 
 ## v0.2.2
-- 更新浅色后台界面：蓝色主色、白色卡片、浅灰背景、可折叠侧边栏与顶部页签。
 - 新增“概览 → 分析页”，根据已保存脚本和真实执行记录分别汇总 Midscene、Appium 测试数据。
 - 修复配置加载失败后出现空白可保存表单的问题，增加独立错误提示和重试；后端断线后自动尝试重连并支持手动重连，保留页面编辑内容。
 - Appium 配置自动保存失败后保留最新待保存内容并提供“重试保存”；修复切换或关闭 Appium 页签后，离开页面时未保存草稿保护失效的问题。

package/artemis-main/.dockerignore

@@ -0,0 +1,15 @@
+.git
+.github
+.venv
+.pytest_cache
+.ruff_cache
+**/__pycache__
+**/*.pyc
+apps/showcase_ui/.angular
+apps/showcase_ui/dist
+apps/showcase_ui/node_modules
+build
+dist
+traces
+.env
+*.log

package/artemis-main/.env.example

@@ -0,0 +1,34 @@
+# ==============================================================================
+# Artemis Environment Configuration Template
+# ==============================================================================
+# Copy this file to .env and fill in your API credentials:
+# cp .env.example .env
+
+# LLM Providers (Configure at least one)
+GEMINI_API_KEY=
+GOOGLE_API_KEY=
+OPENAI_API_KEY=
+# OpenAI-compatible endpoint for GLM, DeepSeek, or other providers
+OPENAI_BASE_URL=
+ANTHROPIC_API_KEY=
+OPEN_ROUTER_API_KEY=
+XAI_API_KEY=
+
+# Google Cloud Vision OCR (Optional - for advanced OCR processing)
+OCR_API_KEY=
+
+# Android ADB Connectivity (Optional - defaults to 127.0.0.1:5037)
+ADB_HOST=127.0.0.1
+ADB_PORT=5037
+# ADB_DEVICE_SERIAL=
+# Keep the display awake, falling back to a wake lock or safe heartbeat when needed.
+# Set to false if Artemis is used with a personal device whose screen should time out.
+ARTEMIS_KEEP_DEVICE_AWAKE=true
+# UI hierarchy backend: auto (Accessibility Helper, UIAutomator2 fallback) | helper | uiautomator
+ARTEMIS_HIERARCHY_BACKEND=auto
+# Let tasks install / upgrade the Accessibility Helper APK on a device they hold.
+# Set to false on shared or personal phones: then only `artemis helper install` installs it.
+ARTEMIS_HELPER_AUTO_INSTALL=true
+
+# Artemis Execution Defaults (flash or pro)
+ARTEMIS_DEFAULT_PROFILE=flash

package/artemis-main/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing to ARTEMIS
+
+Thank you for your interest in contributing to **ARTEMIS**! We welcome and appreciate all forms of contributions—whether it's reporting bugs, proposing new features, improving documentation, or submitting code.
+
+---
+
+## 🤝 Ways to Contribute
+
+- **🐛 Report Bugs & Suggest Features**: If you find an issue or have an idea to improve ARTEMIS, please open an [Issue](https://github.com/google/artemis/issues).
+- **💡 Submit Pull Requests**:
+  1. Fork the repository and create your feature/fix branch (`git checkout -b feat/my-feature`).
+  2. Make your changes and verify with `make test`, `make lint`, and `make typecheck`.
+  3. Open a Pull Request with a brief summary of your work.
+- **💬 Community & Discussion**: Join our [Discord Community](https://discord.gg/wF2FN4WHGY) to chat with maintainers, ask questions, or share feedback.
+
+---
+
+Every contribution—big or small—helps make ARTEMIS better. Thank you for building with us!
+
+## Test layers
+
+`make test` is the required, deterministic suite. It does not need an Android
+device, model credentials, or the optional private cloud service. This is the
+same suite used by pull-request CI.
+
+- `make test-integration` runs cross-component tests that may need configured
+  model credentials.
+- `make test-device` runs Android and end-to-end tests and therefore requires
+  an attached, authorized device or emulator.
+- `make test-all` collects every test tree and is intended for a fully
+  provisioned maintainer environment.
+
+Tests that require external state must carry the appropriate `android`,
+`cloud`, `manual`, or `e2e` marker. They must remain safely collectable when
+that dependency is unavailable.

package/artemis-main/Dockerfile

@@ -0,0 +1,68 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+FROM node:22-bookworm-slim AS frontend-builder
+
+WORKDIR /build/apps/showcase_ui
+COPY apps/showcase_ui/package.json apps/showcase_ui/package-lock.json ./
+RUN npm ci
+COPY apps/showcase_ui/angular.json apps/showcase_ui/tsconfig*.json ./
+COPY apps/showcase_ui/public/ ./public/
+COPY apps/showcase_ui/src/ ./src/
+RUN npm run build
+
+
+FROM python:3.12-slim AS wheel-builder
+
+WORKDIR /build
+COPY artemis/ ./artemis/
+COPY apps/ ./apps/
+COPY mcp_server/ ./mcp_server/
+COPY third_party/ ./third_party/
+COPY packages/artemis-client/ ./packages/artemis-client/
+COPY config/ ./config/
+COPY pyproject.toml setup.py README.md LICENSE ./
+COPY --from=frontend-builder /build/apps/showcase_ui/dist/ ./apps/showcase_ui/dist/
+
+# Build wheels for the runtime image.
+RUN python -m pip wheel --no-cache-dir --no-deps --wheel-dir /wheels ./packages/artemis-client \
+    && python -m pip wheel --no-cache-dir --no-deps --wheel-dir /wheels .
+
+
+FROM python:3.12-slim
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    adb \
+    curl \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=wheel-builder /wheels/ /wheels/
+RUN pip install --no-cache-dir /wheels/artemis_client-*.whl \
+    && pip install --no-cache-dir /wheels/artemis-*.whl \
+    && rm -rf /wheels
+
+ENV PYTHONUNBUFFERED=1
+ENV ARTEMIS_APP_DIR=/app
+ENV PORT=8080
+
+EXPOSE 8080
+
+# The console has no user authentication: publish the port to loopback only,
+# e.g. `docker run -p 127.0.0.1:8080:8080 ...`, and reach it remotely through
+# a Tailscale/SSH tunnel. (0.0.0.0 here is container-internal and required
+# for the port mapping to work.)
+CMD ["uvicorn", "apps.admin_console.server:app", "--host", "0.0.0.0", "--port", "8080"]

package/artemis-main/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        https://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Google LLC.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/artemis-main/Makefile

@@ -0,0 +1,115 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+.PHONY: help test test-integration test-device test-all install install-deps setup start ui restart stop status build-ui doctor clean precommit-install precommit lint format typecheck quality-ratchet
+
+help: ## Show this help message
+	@echo 'Usage: make [target]'
+	@echo ''
+	@echo 'Available targets:'
+	@awk 'BEGIN {FS = ":.*?## "} /^[a-zA-Z_-]+:.*?## / {printf "  %-20s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+start: ## One-click start Artemis Showcase UI and auto-open browser
+	@bash start.sh
+
+ui: ## Launch the unified Showcase UI & Admin Console in browser
+	@uv run artemis ui --open
+
+restart: ## Restart running Artemis Web UI & server
+	@uv run artemis restart
+
+stop: ## Stop running Artemis Web UI & server
+	@uv run artemis stop
+
+status: ## Display Artemis Web UI & server status
+	@uv run artemis status
+
+build-ui: ## Build the Showcase UI Angular frontend
+	@echo "🎨 Building Showcase UI..."
+	@cd apps/showcase_ui && npm install && npm run build
+
+doctor: ## Run system, device, and toolchain diagnostics
+	@uv run artemis doctor
+
+test: ## Run deterministic tests that need no device, credentials, or private services
+	@echo "🧪 Running deterministic tests..."
+	@uv run pytest
+
+test-integration: ## Run non-device integration tests (may require configured model credentials)
+	@echo "🧪 Running integration tests..."
+	@uv run pytest tests/integration tests/tools -m "integration and not android and not cloud and not manual"
+
+test-device: ## Run Android and end-to-end tests explicitly
+	@echo "📱 Running device and end-to-end tests..."
+	@uv run pytest tests/integration tests/e2e -m "android or e2e"
+
+test-all: ## Run every test tree; external prerequisites must be available
+	@echo "🧪 Running the complete test tree..."
+	@uv run pytest tests packages/artemis-client/tests -m "integration or not integration"
+
+install: ## Install python dependencies via uv
+	@echo "📦 Installing python dependencies..."
+	@uv sync --dev
+
+install-deps: ## One-click install all system dependencies (ADB, FFmpeg, scrcpy, Python, uv)
+	@echo "⚡ Running one-click dependency installer..."
+	@bash scripts/install_deps.sh
+
+setup: ## Setup project (install dependencies + pre-commit hooks + build UI)
+	@echo "🚀 Setting up project..."
+	@$(MAKE) install
+	@$(MAKE) build-ui
+	@$(MAKE) precommit-install
+	@echo ""
+	@echo "✅ Setup complete! You're ready to start developing."
+
+lint: ## Run linting checks
+	@echo "🔍 Running linting checks..."
+	@uv run ruff format --check
+	@uv run ruff check
+	@uv run python scripts/quality_ratchet.py
+
+format: ## Format code
+	@echo "✨ Formatting code..."
+	@uv run ruff format
+	@uv run ruff check --fix
+
+typecheck: ## Run type checking
+	@echo "🔍 Running type checks..."
+	@uv run pyright --project pyright-core.json
+
+quality-ratchet: ## Prevent broad exception and type-ignore debt from increasing
+	@uv run python scripts/quality_ratchet.py
+
+precommit-install: ## Install pre-commit hooks
+	@echo "🔧 Installing pre-commit hooks..."
+	@uv run pre-commit install
+	@echo "✅ Pre-commit hooks installed successfully!"
+	@echo ""
+	@echo "Pre-commit will now run automatically on every commit."
+	@echo "To run manually: make precommit"
+
+precommit: ## Run pre-commit hooks manually on all files
+	@echo "🔍 Running pre-commit checks..."
+	@uv run pre-commit run --all-files
+
+clean: ## Clean up generated files, caches, and traces
+	@echo "🧹 Cleaning up caches and temporary files..."
+	@rm -rf .pytest_cache .ruff_cache .artemis_paused traces scratch .venv apps/showcase_ui/.angular build dist
+	@find . -type d -name "outputs" -exec rm -rf {} + 2>/dev/null || true
+	@find . -type f -name ".artemis_paused" -delete 2>/dev/null || true
+	@find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	@find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true
+	@find . -type f -name "*.py[cod]" -delete 2>/dev/null || true
+	@echo "✅ Cleanup complete"