内容
<p align="center">
<img src="assets/brand/picklab-lockup-horizontal.svg" alt="PickLab" width="560">
</p>
# PickLab
用于原生应用和安卓模拟器的 Playwright。PickLab 为 AI 编程代理提供眼睛、手和可复制的实验室：Xvfb 上的桌面会话、专用 AVD 上的安卓模拟器、截图、输入、日志和运行工件 — 通过 CLI 和 MCP 服务器。
PickForge 构建应用。PickLab 让代理看到、运行和测试它。PickArena 衡量结果。
本地优先。开源。 为那些交付的人而建。
## 安装
```sh
curl -fsSL https://pickforge.dev/picklab/install.sh | sh
```
或无需安装：
```sh
npx -y @pickforge/picklab doctor
bunx @pickforge/picklab doctor
```
或全局安装：
```sh
npm install -g @pickforge/picklab
bun add -g @pickforge/picklab
```
这会安装两个二进制文件：`picklab`（CLI）和 `picklab-mcp`（MCP 标准输入/输出服务器）。安装程序从不使用 sudo。
## 快速入门
```sh
cd your-app
picklab init --profile desktop+android # 配置实验室用户 + AVD，写入项目配置
picklab doctor # 验证依赖项；--fix 修复可以修复的问题
picklab session create --type desktop+android
picklab desktop launch ./build/your-app
picklab desktop screenshot
picklab android install-apk build/app-release.apk
picklab android launch-app com.example.app
picklab android screenshot
picklab artifacts report # 渲染最新的运行结果
picklab session destroy
```
每个截图、日志和操作都会保存在 `.picklab/runs/<runId>/` 中，并带有清单，因此运行结果可以复现和检查。
### 并发会话
每个会话都有自己的独立显示或模拟器，因此多个代理和项目可以并行运行实验室。当在没有显式会话 ID 的情况下调用命令或工具时，默认解析每个项目：只考虑为同一项目目录创建的正在运行的会话。传递 `session` ID（CLI：`--session <id>`）以定位特定的实验室，包括属于另一个项目的实验室。
<p align="center">
<img src="assets/brand/picklab-run-lab-mock.svg" alt="PICKLAB · RUN LAB — 桌面会话，安卓模拟器，实时截图，日志和代理终端" width="900">
</p>
## MCP 设置代理
将 MCP 服务器注册到您的编程代理：
```sh
picklab agents install claude-code # 另见：codex，cursor
picklab agents list
picklab agents doctor
```
对于其他代理，请自行添加标准输入/输出服务器：
```json
{
"mcpServers": {
"picklab": {
"command": "picklab",
"args": ["mcp", "serve"]
}
}
}
```
自定义代理可以存储在 `~/.picklab/agents` 下：
```sh
picklab agents add --name my-agent --mcp-command "picklab mcp serve"
```
## CLI 参考
| 组 | 命令 |
| --- | --- |
| 设置 | `doctor`，`init`，`setup lab-user`，`setup android` |
| 会话 | `session create`，`session status [id]`，`session destroy [id]` |
| 桌面 | `desktop launch <cmd>`，`desktop screenshot`，`desktop click <x> <y>`，`desktop type <text>`，`desktop key <keys>` |
| 安卓 | `android start`，`android install-apk <apk>`，`android launch-app <pkg>`，`android screenshot`，`android tap <x> <y>`，`android type <text>`，`android back`，`android home`，`android ui-tree`，`android logcat`，`android adb [args...]` |
| 工件 | `artifacts list`，`artifacts open <runId>`，`artifacts report [runId]` |
| 代理 | `agents list`，`agents install <agent>`，`agents link <agent>`，`agents unlink <agent>`，`agents doctor`，`agents add` |
| MCP | `mcp serve` |
会话类型：`desktop`（Xvfb，可选 VNC），`android`（专用 AVD 上的模拟器），`desktop+android`。大多数命令接受 `--json` 以获取机器可读的输出，并接受 `--project-dir` 以定位其他项目。
## MCP 接口
`picklab mcp serve` 通过标准输入/输出暴露了 22 种工具：
- 会话：`session_create`，`session_status`，`session_destroy`
- 桌面：`desktop_launch`，`desktop_screenshot`，`desktop_click`，`desktop_type`，`desktop_key`
- 安卓：`android_start`，`android_install_apk`，`android_launch_app`，`android_screenshot`，`android_tap`，`android_type`，`android_back`，`android_home`，`android_get_ui_tree`，`android_logcat`，`android_run_adb`
- 工件：`artifact_list`，`artifact_report`
- 用户：`request_user_input` — 向人类提问（通过 MCP 诱导，当客户端支持时）并等待答案；从不用于机密
资源，可寻址为 `picklab://` URI：
- `picklab://runs` — 记录的运行
- `picklab://runs/{runId}/manifest` — 运行清单
- `picklab://runs/{runId}/screenshots/{name}` — 截图
- `picklab://runs/{runId}/logs/{name}` — 日志
- `picklab://sessions/{sessionId}/status` — 会话活跃度
提示：`test-flutter-desktop-visually`，`debug-android-apk`，`run-visual-regression-check`。
## 架构
TypeScript 单体仓库。`@pickforge/picklab` 是已发布的包；其余为内部包，并被捆绑到其中。
| 包 | 角色 |
| --- | --- |
| `packages/core` | 配置、会话、工件、清单、进程监督 |
| `packages/desktop-linux` | Xvfb、VNC、窗口、输入和截图自动化 |
| `packages/android` | AVD、模拟器、ADB、UIAutomator 和 logcat 协调 |
| `packages/mcp-server` | MCP 工具、资源和提示 |
| `packages/agent-installers` | Codex、Claude Code、Cursor 和自定义代理注册 |
| `packages/cli` | `picklab` 和 `picklab-mcp` 二进制文件 |
## 安全模型
- MCP 工具从不调用 sudo。特权配置仅通过 CLI（`picklab setup lab-user`）进行，具有明确的同意（`--yes` 或提示）。
- 所有用户输入都作为参数数组生成 — 从不插入 shell 字符串。
- VNC 默认仅绑定到环回地址：`x11vnc` 使用 `-localhost` 启动，因此服务器监听 `127.0.0.1` 且无法从网络访问。通过 SSH 隧道进行远程访问。
- 工件默认被删除：logcat 输出在存储或返回之前会剥离令牌和机密。只有 `android adb` 是原始的，它说明了这一点。
- PickLab 配置了一个专用的锁定实验室用户（`picklab-lab`）和一个专用的 AVD（`picklab-avd`），因此实验室工作负载不会借用您的个人资源。计划在 MVP 之后在实验室用户下运行会话进程。
- 代理配置编辑是原子的，带有以前配置的备份。
## 开发
```sh
bun install
npm run build # 捆绑所有包
npm run typecheck
npx vitest run
```
## 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
---
<p align="center">
<a href="https://pickforge.dev">
<img src="assets/brand/pickforge-studio-footer.svg" alt="Pickforge Studio — 本地优先，开源，为那些交付的人而建" width="560">
</a>
</p>
