内容
# 无感 — 手机摄像头、传感器和文件用于PC端AI代理
<!-- mcp-name: io.github.hufirst/onsense -->
**让AI自己看吧。** `onsense` 是 [onSense](https://play.google.com/store/apps/details?id=com.shdev.onsense) 安卓应用的PC端MCP代理： 在PC上运行 `uvx onsense pair`，然后 **任何支持MCP的AI** — Claude Code、Claude Desktop、Codex 或您自己的代理 — 都可以通过手机摄像头查看、读取传感器数据，并双向移动文件和剪贴板。 **无需云中继。无需ADB。**
> *Claude Code在PC上运行，通过onSense读取手机传感器和摄像头，实时回答 — 通过本地Wi-Fi。*
> *……而Codex也是如此。onSense是一个标准的MCP服务器，因此任何MCP客户端都可以使用。*
---
## 架构
```text
安卓手机（onSense应用） PC（此软件包） AI客户端
HTTP提供者 :8080 ←→ 标准输入输出MCP代理 Claude / Codex / …
摄像头帧、照片、 onsense服务 自然语言或
传感器、二维码配对 onsense剪贴板 :8770 /onsense工具调用
```
- **手机** 运行一个HTTP提供者，端口为8080。它公开摄像头帧、最近的照片和传感器读数，所有这些都通过配对令牌进行控制。
- **PC软件包** (`onsense`) 是一个标准输入输出MCP代理。它将AI客户端的MCP工具调用翻译成对手机的HTTP请求。
- 发现使用mDNS (`_onsense._tcp.local.`). 如果手机的IP地址更改，代理会自动重新发现它 — 无需手动重新配置。
- 一个可选的 **剪贴板桥接** 守护进程，端口为8770，允许手机将摄像头帧、文件和剪贴板内容推送到PC（并可选地允许手机从PC剪贴板拉取）。
---
## 要求
- [uv](https://docs.astral.sh/uv/) （提供`uvx`；自动下载托管的Python — 无需单独安装Python）
- 在与PC处于 **同一本地Wi-Fi网络** 的手机上安装onSense安卓应用
- 支持MCP的AI客户端，如 [Claude Code](https://claude.ai/code)、Codex 或任何标准输入输出MCP客户端
---
## 快速入门
### 0. 没有uv的新PC？使用应用的设置助手（推荐）
在干净的PC上，`uvx`尚不存在，以下命令将失败，提示 *"'uvx' 未识别"*。最简单的解决方法：首先安装onSense应用，点击 **"启动PC设置助手"**，然后在PC上打开显示的地址。它为您提供一行命令，安装uv、配对并注册MCP服务器 — 由于PC连接到手机，因此它也完全绕过了Windows防火墙。
如果您更喜欢自己安装uv？一行命令：
```powershell
# Windows（PowerShell）
irm https://astral.sh/uv/install.ps1 | iex
$env:Path = "$env:USERPROFILE\.local\bin;$env:Path" # 使uvx在此同一shell中可见
```
```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
```
### 1. 配对您的手机
运行此命令一次。PC打印一个二维码；从onSense应用中扫描它（"扫描PC二维码"）。手机将其地址和令牌推送到PC，PC自动注册MCP服务器。
```bash
uvx onsense pair
```
配对后，重新启动您的AI客户端，以便它拾取新的`onsense` MCP服务器。
### 2. 使用它
自然地询问您的AI客户端：
> "拍摄一张我手机前面的照片。"
> "当前的传感器读数是什么？"
> "显示我手机上的最后5张照片。"
MCP工具将自动调用。在Claude Code中，您还可以使用捆绑的 **`/onsense`** 斜杠命令（在配对期间安装）。
### 3. 诊断问题
```bash
uvx onsense doctor # 检查Python、uv、MCP、Claude注册、mDNS、手机可达性
uvx onsense doctor --base http://192.168.1.5:8080 --token YOUR_PAIRING_TOKEN
```
### Windows：二维码扫描超时？
#1个原因是Windows防火墙阻止了手机的入站连接：
- 如果您的Wi-Fi网络配置文件是 **公共**，则入站流量被严格阻止。将其切换到 **私人** （设置 → 网络 → 您的Wi-Fi → 网络配置文件），或仅使用应用的 **PC设置助手**，它根本不需要入站端口。
- 在私人网络上，一次添加一个持久的允许规则：
```powershell
uvx onsense pair --fix-firewall
```
首次运行的防火墙弹出窗口是 *程序路径作用域* 的，而uvx的临时路径会悄悄地使其失效 — 上面的端口作用域规则（TCP 8765–8774，私人）实际上是有效的。
---
## 子命令
| 命令 | 执行的操作 |
| --- | --- |
| `uvx onsense pair` | 在PC上显示二维码；手机扫描它并推送 `{base, token}`；自动注册MCP |
| `uvx onsense pair "onsense://pair?base=...&token=..."` | 直接解析配对URI（手机显示的二维码 → 手动复制） |
| `uvx onsense pair --img screenshot.png` | 从截图文件解码配对二维码（需要opencv） |
| `uvx onsense serve` | 运行MCP服务器（标准输入输出）。还自动启动剪贴板守护进程，除非传递 `--no-clip` |
| `uvx onsense serve --no-clip` | 仅运行MCP服务器，不启动剪贴板守护进程 |
| `uvx onsense clip` | 独立运行剪贴板桥接守护进程（端口8770） |
| `uvx onsense clip --allow-pull` | 启用手机→拉取：手机可以GET /clip以检索PC剪贴板 |
| `uvx onsense clip --set-clipboard` | 自动将接收的内容注入PC操作系统剪贴板（默认关闭） |
| `uvx onsense pair --fix-firewall` | （Windows，管理员）添加持久的端口作用域防火墙规则，然后像往常一样配对 |
| `uvx onsense doctor` | 诊断安装、连接性和手机可达性 |
| `uvx onsense stats` | 显示仅限本地的激活统计信息 (`--json`, `--reset`)。不会自动上传任何内容 |
---
## 其他MCP客户端（Claude Desktop，Codex，…）
`uvx onsense pair` 自动将服务器注册到 **Claude Code** （通过 `claude mcp add`） — 此一行自动设置是Claude Code特有的。 MCP服务器本身是标准的标准输入输出MCP，因此 **任何MCP兼容的客户端都可以使用**，只需手动添加即可。 运行 `uvx onsense pair` 一次：它将手机的地址和令牌保存到 `~/.onsense/pair.json`，服务器在请求时读取它 — 因此您不必在每个客户端的配置中输入令牌，并且手机的IP地址通过mDNS自动跟踪。
**Claude Desktop** — 添加到 `claude_desktop_config.json`:
```json
{ "mcpServers": { "onsense": { "command": "uvx", "args": ["onsense", "serve"] } } }
```
**Codex** — 通过CLI注册（验证Codex CLI 0.142.5）：
```bash
codex mcp add onsense -- uvx onsense serve
```
> **Codex沙盒注意：** Codex的默认沙盒阻止网络访问，因此MCP服务器无法到达您的手机，工具调用会静默失败。运行Codex并启用网络访问（例如 `--sandbox danger-full-access`，或允许网络的沙盒策略），以便onsense可以与LAN上的手机通信。
或添加到 `~/.codex/config.toml`:
```toml
[mcp_servers.onsense]
command = "uvx"
args = ["onsense", "serve"]
```
在添加服务器后重启客户端。 任何其他标准输入输出MCP客户端都可以使用相同的方式 — 将其指向 `uvx onsense serve`。
---
## MCP工具
这些工具在配对后可供AI客户端使用：
| 工具 | 描述 |
| --- | --- |
| `get_live_frame()` | 从手机捕获当前的摄像头帧（返回JPEG图像） |
| `read_sensors()` | 以JSON返回手机传感器读数：电池级别/充电状态、环境光（勒克斯）、加速度计（x/y/z） |
| `recent_photos(limit=10)` | 列出手机上的最近照片：id、名称、添加日期、大小、宽度、高度 |
| `get_photo(id, max_width=1024)` | 通过id获取特定的照片（缩放到最大宽度）；使用 `recent_photos` 中的id |
| `get_reference()` | 获取手机指定的 **参考源** — 实时摄像头帧、捕获的照片或任意文件（包括非图像） — 保存到磁盘并带有路径和元数据。 文件/捕获桥的核心 |
| `get_cam_fps()` | 读取手机当前的摄像头FPS设置（15 = 高性能，2 = 平衡，0 = 按需） |
| `set_cam_fps(fps)` | 设置手机的摄像头FPS： `15` （高性能）， `2` （平衡，推荐）或 `0` （省电/按需） |
如果手机的IP地址更改，代理在显示错误之前会使用mDNS自动发现重试。
---
## 剪贴板桥接（手机 ↔ PC文件和剪贴板）
`onsense serve` 自动启动一个 **端口8770** 上的剪贴板守护进程。您也可以单独使用 `onsense clip` 运行它。
### 手机 → PC推送（POST /clip）
onSense安卓应用可以将内容推送到PC：
- **图像** 保存在磁盘上为 `latest.jpg` （在 `ONSENSE_CLIP_DIR` 中，默认为 `<tempdir>/onsense/`）。
- **文本文件** 保存在磁盘上。
- **其他文件** （视频、PDF等） 按文件名保存在磁盘上。
- 如果启用了 `--set-clipboard`，图像和文本也会注入PC操作系统剪贴板，以便您可以使用Ctrl+V立即粘贴。
默认情况下， `--set-clipboard` 是 **关闭的** — 文件保存在磁盘上，但剪贴板不被触及。
### PC → 手机拉取（GET /clip）
默认情况下关闭。启用方式：
```bash
uvx onsense clip --allow-pull
```
启用后，手机可以GET /clip以检索当前的PC剪贴板内容（复制的文件优先，然后是图像，然后是文本）。如果剪贴板为空，则返回204。
### 端口和环境变量
| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `PHONE_BASE` | （来自配对） | 手机HTTP基准URL，例如 `http://192.168.1.5:8080` |
| `PHONE_TOKEN` | （来自配对） | 配对身份验证令牌 |
| `ONSENSE_CLIP_DIR` | `<tempdir>/onsense` | 推送的文件保存目录 |
| `ONSENSE_CLIP_MAX_MB` | `200` | 最大传入文件大小（MB）（0 = 无限制） |
| `ONSENSE_CLIP_ALLOW_PULL` | `0` | 设置为 `1` 以启用PC→手机拉取，无需CLI标志 |
| `ONSENSE_CLIP_SET_CLIPBOARD` | `0` | 设置为 `1` 以自动注入操作系统剪贴板，无需CLI标志 |
| `ONSENSE_TEST_FRAME` | （未设置） | 当手机无法访问时， `get_live_frame` 返回的本地JPEG路径 |
---
## 安全
**仅限本地网络。** PC端服务绑定到所有接口，但拒绝来自非私有IP地址的连接，位于应用层。它们不打算暴露给互联网。
**HMAC请求签名。** 配对令牌永远不会明文发送。每个身份验证请求都使用HMAC-SHA256签名，密钥由配对令牌通过HKDF-SHA256派生（与加密密钥分开），并携带 `X-Ts` / `X-Nonce` / `X-Sig` / `X-Enc` 头。服务器在恒定时间内验证，拒绝时间戳超出 ±300秒窗口的请求，并拒绝重用的随机数 — 因此，捕获的请求无法重放，令牌无法从线路上窃取。新安卓安装程序生成一个128位随机令牌，存储在手机和 `~/.onsense/pair.json` （chmod 600）中。 （ `/health` 端点是未经身份验证的。） 有关确切的线路格式，请参见 [PROTOCOL.md](PROTOCOL.md)。
**拉取和剪贴板注入默认关闭。** `GET /clip` （手机拉取PC剪贴板）和操作系统剪贴板自动注入（手机推送 → Ctrl+V）除非您明确传递 `--allow-pull` 或 `--set-clipboard`，否则禁用。
**加密正文（AES-256-GCM）。** 敏感的有效载体 — 摄像头帧、照片、传感器数据、文件和剪贴板内容 — 在手机和PC之间使用AES-256-GCM加密（中间没有云，因此没有第三方解密它们）。密钥通过HKDF-SHA256从配对令牌派生（与签名密钥分开）；每个消息使用新的96位随机数，GCM标签验证正文并将其绑定到其请求（因此拒绝篡改或响应替换）。同一Wi-Fi上的被动窃听者只看到密文。低敏感性元数据保持明文：开放的 `/version` 和 `/health` 端点、HTTP错误响应和推送后返回的保存文件路径。 （注意：目前，大传输在加密/解密时会在内存中缓冲 — 针对非常大的文件的分段流式传输是未来的一步。传输级TLS也是可能的未来强化。）
**文件大小上限。** 如果传入的推送超过 `ONSENSE_CLIP_MAX_MB` （默认为200 MB），则拒绝。设置为 `0` 以删除上限。
**报告漏洞。** 请私下报告安全问题 — 参见 [SECURITY.md](SECURITY.md)。不要为安全报告开启公共问题。
---
## 许可证
MIT。参见 [LICENSE](LICENSE)。
