# AScript Codex 插件

这个插件把 AScript 本地 MCP 和自动化开发 Skill 一次性安装到 Codex。安装后，Codex 可以查询 AScript API、连接本地 Android/iOS 设备、读取截图和控件树、执行 Python 片段、上传运行工程并分析日志。

这是面向开发者电脑的本地直连版，不包含 AI Studio 服务器的 Relay 地址、context token 或配对链路。

## 前置要求

- 已安装支持插件的 Codex CLI 或 Codex App
- 终端可以执行 `uvx`
- 手机已安装 AScript App

没有 `uvx` 时先安装 `uv`。

macOS / Linux：

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Windows PowerShell：

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

## 从离线包安装

进入本目录后执行：

```bash
codex plugin marketplace add "$(pwd)"
codex plugin add ascript@ascript
```

Windows PowerShell：

```powershell
codex plugin marketplace add (Get-Location).Path
codex plugin add ascript@ascript
```

安装后新开一个 Codex 任务，输入 `/mcp`，确认存在 `ascript-local`。

## 连接手机

插件安装成功只代表 MCP 已经加载，不代表手机已经连接。

### 局域网：Android / iOS

1. 打开手机上的 AScript App。
2. 进入 **开发者**，开启设备服务。
3. 手机与电脑连接同一个局域网。
4. 对 Codex 说：

```text
扫描局域网 AScript 设备，先把设备名称、平台和 IP 告诉我，等我确认后再连接。
```

确认后，Codex 会调用 `connect_device`。默认端口为 `9096`。

### USB：Android

1. 开启 Android 开发者选项和 USB 调试。
2. USB 连接电脑，并在手机上确认 ADB 授权。
3. 确认 `adb devices` 中设备状态为 `device`。
4. 对 Codex 说：

```text
扫描 USB/ADB 设备，连接我确认的 Android 设备，然后读取设备状态和当前屏幕。
```

连接后让 Codex 调用 `get_device_status`、`screen_capture` 或 `observe_device` 验证真实设备。

## 与 AI Studio 的区别

AI Studio 配对码只用于 AI Studio 服务器 Relay 链路。本地 Codex 插件不读取配对码，也不能因为手机已经与 AI Studio 配对就直接控制该手机。本地插件必须通过同一局域网或 Android USB/ADB 连接设备，请勿把手机的 `9096` 端口暴露到公网。

## 当前依赖

插件固定使用：

```text
uvx --with "mcp<2" "ascript-mcp==1.7.0"
```

`mcp<2` 是当前 1.7.0 发布包所需的兼容限制。