# remote-behavior-agent

跨平台(Windows/Linux/macOS)**远程软件调试 (dbg)** 代理。
控制端用 MCP/AI 远程驱动目标机(含虚拟机):启动软件 / 截图 / 下断点(命中抓现场)/ 读写内存 / 枚举模块符号。

## 架构(三层)

```
用户层  server/(MCP:stdio 或 HTTP+Bearer令牌)  +  adapters/(Frida/截图/启动 外部适配器)
业务层  service/orchestrator.py(会话编排 · 注册表 · 选后端 · 唯一持业务状态)
逻辑层  logic/(纯函数:事件格式化 / 解码 / 截图非空白判定)
```

- **调试内核**:Frida(三系统通吃)。x64dbg/GDB/LLDB 为可选原生后端(能力探测式接入)。
- **断点模型**:Frida 插桩式 —— 在函数/地址命中时抓参数+调用栈+(可选)缓冲并继续(非暂停)。
- **两种传输**:`stdio`(本机,Claude Code 直接 spawn)/ `http`(局域网,Bearer 令牌)。

## MCP 工具(14)

| 类别 | 工具 |
|---|---|
| 进程 | `launch` `screenshot` `list_processes` |
| 会话 | `attach(pid)` `spawn(path)` `resume` `teardown` |
| 断点 | `hook_api(符号[,buf_arg,len_arg])` `hook_addr(地址)` `stream_events` |
| 内存/符号 | `read_mem` `write_mem` `modules` `resolve` |

---

## A. 本机使用(stdio)

控制端 `.mcp.json`(本仓库已带):
```json
{ "mcpServers": { "remote-behavior-agent": {
  "command": "python", "args": ["-m","agent.main","--transport","stdio"],
  "env": { "PYTHONUTF8":"1", "PYTHONPATH":"<项目绝对路径>" } } } }
```
```bash
pip install -r requirements.txt
```
重启 Claude Code → 工具可用(调试本机)。

---

## B. 局域网远程使用(http + 令牌)—— 多台/虚拟机

**思路**:每台目标机(含 VM)各跑一个 HTTP agent;控制端按 IP 把它们都列进 `.mcp.json`。
**哪台装 agent → 哪台就能被远程断点。**

### 1) 目标机(VM/PC)起服务

Windows(管理员 PowerShell,项目根目录):
```powershell
./scripts/run_agent.ps1 -Token "你的强令牌>=16位" -Port 8765
```
Linux:
```bash
sudo sysctl -w kernel.yama.ptrace_scope=0     # 允许 attach
RBA_TOKEN=你的强令牌 ./scripts/run_agent.sh 0.0.0.0 8765
```
> 脚本会 `pip install -r requirements.txt` 并以 `--host 0.0.0.0 --allow-remote` 启动。

### 2) 虚拟机网络要点
- VM 网卡用**桥接**(拿到局域网 IP)或 host-only + 端口转发;
- VM 内**防火墙放行该端口**(如 8765);
- frida 在 VM 内建议**管理员/root** 运行。

### 3) 控制端 `.mcp.json`(列多台,都可用)
```json
{ "mcpServers": {
  "vm1": { "type":"http", "url":"http://192.168.1.51:8765/mcp",
           "headers": { "Authorization": "Bearer ${RBA_TOKEN}" } },
  "pc2": { "type":"http", "url":"http://192.168.1.52:8765/mcp",
           "headers": { "Authorization": "Bearer ${RBA_TOKEN}" } }
}}
```
设环境变量 `RBA_TOKEN=你的强令牌` 后启动 Claude Code,即可远程驱动各台。
加一台目标 = 加一行。

> ⚠️ 安全:令牌走**明文 HTTP**,仅适合**可信局域网/隔离网**。不可信网络请叠加 TLS
> (agent 前置反代,或后续 `--tls`;控制端用 `https://` + `NODE_EXTRA_CA_CERTS` 信任自签 CA)。

## 测试
```bash
pytest        # 逻辑层 + 令牌中间件单测
```

详见 `.pp/wiki/当前任务/远程跨平台行为分析代理/`。