# AScript Codex 离线安装

这份离线包把本地 AScript MCP、自动化开发 Skill 和本地 Marketplace 一次性打包到 Codex 可直接使用的结构里。安装后，Codex 可以查询 AScript API、连接本地 Android/iOS 设备、读取截图和控件树、上传运行工程并分析日志。

这是本地直连版，不包含 AI Studio 服务器的 Relay 地址、context token 或配对链路，也不依赖官方插件目录。

## 1. 下载

下载 `ascript-codex-plugin.zip` 并解压。插件结构：

```text
ascript-codex-plugin/
├── .agents/plugins/marketplace.json
└── plugins/ascript/
    ├── .codex-plugin/plugin.json
    ├── .mcp.json
    ├── assets/logo.png
    └── skills/ascript/SKILL.md
```

## 2. 准备 uvx

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"
```

## 3. 安装插件

macOS / Linux：进入解压目录执行：

```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`。

## 4. 连接手机

插件安装成功不代表手机已经连接。

局域网方式：在手机 AScript App 的 **开发者** 中开启设备服务，让手机和电脑连接同一局域网，然后输入：

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

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

Android USB 方式：开启 USB 调试并确认 ADB 授权，确保 `adb devices` 显示设备状态为 `device`，然后输入：

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

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

## 5. 连接边界

AI Studio 配对码只用于 AI Studio 服务器 Relay 链路。本地插件不读取配对码，必须通过同一局域网或 Android USB/ADB 连接手机。不要把手机的 `9096` 端口暴露到公网。

## 6. 为什么是离线包

这个版本的目标是让本地 Codex 直接拥有 AScript 同款能力，所以默认只讲离线安装。

它走本地 Marketplace + 本地 MCP + 局域网/ADB 真机连接，不依赖官方插件目录，也不要求先准备付款方式、企业验证或公网 MCP。

## 7. 备用直连

只有 Codex 暂不支持插件时，才把 `codex-config.toml` 中的 `[mcp_servers.ascript-local]` 合并到 `~/.codex/config.toml`，并把 `ascript-skill.md` 保存为 `~/.codex/skills/ascript/SKILL.md`。