# Arena Local Agent

让支持 MCP 的 AI 客户端连接你的 Windows 电脑：读取和编辑项目文件、执行 PowerShell、检查 Git、管理任务、记忆和技能。配套本地 Web 控制台，用于配置工作区、查看命令、处理审批和管理 Cloudflare Tunnel。

> **安全提示：这是远程执行工具，不是隔离虚拟机。** 持有网关 Token 的客户端可能以启动网关的 Windows 用户权限操作电脑。不要以管理员身份运行网关，不要把 Token、隧道凭证或运行数据库上传 GitHub。建议先在不含敏感信息的测试项目中试用。
>
> 本项目为独立工具，不表示获得 Arena.ai 官方授权或背书。此次发布包是源码版本，不含依赖、个人数据或预构建二进制。

## 目录

- [环境要求](#环境要求)
- [安装与首次启动](#安装与首次启动)
- [日常使用](#日常使用)
- [连接 AI 客户端](#连接-ai-客户端)
- [建立 Cloudflare 隧道](#建立-cloudflare-隧道)
- [配置与安全边界](#配置与安全边界)
- [开发与测试](#开发与测试)
- [故障排查](#故障排查)
- [发布到 GitHub](#发布到-github)

## 架构与功能

```text
AI 客户端 / 云端 Agent
        │ HTTPS + Authorization: Bearer <GATEWAY_TOKEN>
        ▼
Cloudflare Tunnel（推荐仅允许 /mcp）
        │
        ▼
Windows: 127.0.0.1:8789
        ├── /mcp      Streamable HTTP MCP
        ├── /api/*   控制台 API
        ├── /        Web 控制台
        └── data/    SQLite、任务、日志、记忆、技能等本地状态
```

主要能力：文件浏览/编辑/搜索/补丁；前台和后台命令、交互终端、输出分页；TypeScript 诊断与语言服务；Git 状态/差异/历史；人工审批；任务简报、待办、进度；全局/项目记忆；技能导入与注入；隧道状态管理。工具清单以 MCP `tools/list` 的实际返回为准，不依赖固定数量。

## 环境要求

- Windows 10/11 x64，Windows PowerShell 5.1。
- **建议 Node.js 24 LTS**，自带 npm。本项目使用内置 `node:sqlite`；旧 Node 版本不能直接运行。发布验证结果见 `RELEASE-NOTES.md`。
- Git：克隆、提交和 Git 工具需要。
- cloudflared：仅公网连接需要，本机使用不需要。
- 首次安装需要 npm 网络访问。`better-sqlite3` 等依赖若没有匹配的预编译包，可能需要 Python 及 Visual Studio C++ Build Tools；优先选择推荐的 Node LTS x64。

检查（PowerShell，每行分别执行）：

```powershell
node --version
npm.cmd --version
git --version
$PSVersionTable.PSVersion
```

## 安装与首次启动

### 1. 下载或克隆

在 GitHub 下载 ZIP 并解压，或从本项目公开仓库执行以下命令：

```powershell
git clone https://github.com/Aries430323/arena-to-local.git
Set-Location .\arena-to-local
npm.cmd ci
npm.cmd run build
```

使用 `npm ci` 按锁文件安装依赖；不要提交 `node_modules`。当前锁文件的下载地址使用公共镜像 `registry.npmmirror.com`，不是私有仓库。如果你的网络无法访问该镜像，需要有意识地切换 npm 源并重新生成、复核锁文件，再跑构建；仅设置 registry 不一定会替换锁文件已有 URL。在你的电脑创建一个专用工作区，例如 `D:\Projects\demo`。

### 2. 一键启动

双击 `start-arena-local-agent.bat`，或在项目根目录运行：

```powershell
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\start-arena-local-agent.ps1 -WorkspaceRoot "D:\Projects\demo"
```

该参数目录必须已经存在。脚本在缺少依赖时安装依赖，在缺少前端构建时构建控制台，启动一个独立 PowerShell 网关窗口，并打开 `http://127.0.0.1:8789/`。

**注意：一键启动当前使用 `tsx watch` 运行后端，修改后端源文件可能导致重启。** 关闭启动器不等于停止网关。长期使用可采用下面的编译运行方式。已有端口上的网关会被复用，此时命令行指定的工作区不会替换旧实例的配置；请在控制台确认工作区。

发布副本已去除固定占位 Token：首次无 Token 时网关随机生成并存储于本地数据库。请在本地控制台“连接与设置”中读取、复制或轮换实际 Token；不要截图公开这一页。

### 3. 编译运行（推荐长期使用）

在独立 PowerShell 窗口中、项目根目录下执行：

```powershell
npm.cmd ci
npm.cmd run build
$env:ARENA_GATEWAY_HOST = '127.0.0.1'
$env:ARENA_GATEWAY_PORT = '8789'
$env:ARENA_WORKSPACE_ROOTS = 'D:\Projects\demo'
$env:ARENA_REQUIRE_APPROVAL = 'true'
$env:ARENA_RESTRICT_TO_WORKSPACE = 'true'
node .\apps\gateway\dist\index.js
```

保持该窗口运行，手动打开 `http://127.0.0.1:8789/`。停止这个前台实例：在它自己的窗口按 Ctrl+C。不要结束所有 Node/PowerShell 进程。不同副本必须使用不同端口，且不要让多个进程同时使用同一份 `data/`。

辅助停止脚本现在必须指定 `-ProcessId <PID>` 并人工确认，仅接受命令行包含本发布目录绝对路径的 Node 进程；无法证明归属时会拒绝。对 watch 模式优先在对应网关窗口按 Ctrl+C，以免仅停止子进程后被 watcher 重新拉起。

## 日常使用

1. **工作区**：在控制台导入具体项目文件夹；顶栏切换默认工作区。相对文件路径、默认命令目录和项目简报以默认工作区为基准。移除工作区登记不代表删除磁盘文件。
2. **连接**：先确认总览中的网关状态，再按下文配置本机或公网 MCP。云端 Agent 不能用它自己的 `127.0.0.1` 访问你的电脑。
3. **开始任务**：让 Agent 首先调用 `get_task_briefing`，确认工作区后操作。换工作区或恢复上下文后再次调用，避免接续其他项目的旧待办。
4. **文件**：文件工作区可浏览、预览和编辑，保存前检查路径。Git 页查看差异，重要修改前自行提交或备份。
5. **命令**：Windows 命令使用 PowerShell 5.1。不要使用 Bash 语法或 `&&`；长任务采用 `run_command` 的 `background: true`，再用 `get_command_output` 查看结果。
6. **审批**：启用安全与审批开关。出现 `approval_required` 后，在本地“审批中心”检查完整命令再批准；让 Agent 携带返回的 `approval_id` 重试原命令。一次批准不可重复使用，也不是授权任意等价命令。
7. **输出分页**：工具输出被截断不代表数据丢失。按返回的 `next_offset` 使用输出读取工具继续；偏移单位为 UTF-8 字节。
8. **任务与记忆**：待办管理当前工作，记忆保存长期约定和关键陷阱，不要存账号密码。全局记忆影响所有项目，项目记忆仅用于对应工作区。
9. **技能**：按需导入本地或 GitHub 技能。技能可能包含可执行命令，必须先检查可信度；链接目录只是引用，不应认为发布包已经包含这些本机技能。
10. **断开**：先在控制台停止由它启动的隧道，再关闭对应网关窗口。外部服务形式的 cloudflared 需要在原服务管理方式中停止。

## 连接 AI 客户端

### 原生 MCP 配置

客户端需要支持 **Streamable HTTP** 和自定义 HTTP headers。不同客户端配置入口可能不同，参考其 MCP 文档。

```json
{
  "mcpServers": {
    "arena-local": {
      "url": "http://127.0.0.1:8789/mcp",
      "headers": {
        "authorization": "Bearer REPLACE_WITH_YOUR_GATEWAY_TOKEN"
      }
    }
  }
}
```

公网连接只替换 `url` 为 `https://mcp.example.com/mcp`，Token 仍是**网关 Token**，不是 Cloudflare Tunnel Token。不要将实际配置提交到仓库。

完成后调用 `get_task_briefing`：返回正确项目路径才算连通。仅在浏览器打开 `/mcp` 得到错误，不足以判断 MCP 故障；协议需要初始化、请求头和会话处理。

提示词弹窗每次打开都会重新获取配置；“复制完整提示词”“复制最新地址”“复制最新 Token”都会在复制前再次请求当前值，并绕过 HTTP 缓存。请求失败不会复制旧内容，复制失败会明确报错。已粘贴到其他客户端的内容不会自动变更，地址或令牌变更后需重新复制粘贴。外部启动的 Named Tunnel 仍需在设置页登记正确公网域名。

### 客户端无法自行添加 MCP 时

本地控制台提供“复制 Arena 初始化提示词”，内容包含实际地址、Token、工作守则及 Python 标准库 HTTP 桥接方法，可粘贴给你信任、具备终端工具的 Agent。**整段提示词含凭证，只能作为私密连接资料使用。** Agent 必须验证 `get_task_briefing` 成功，不能把它自己的云沙箱误称为你的本机。

MCP 的 `tools/list` 是 JSON-RPC 协议方法，不是名为 `tools/list` 的普通工具；自行编写桥接时要区分协议方法和 `tools/call`。

## 建立 Cloudflare 隧道

### 先理解两种 Token

| 项目 | 用途 | 获取位置 |
| --- | --- | --- |
| Gateway Token | AI 调用 `/mcp` 的 Bearer 鉴权 | 本地控制台连接设置 |
| Tunnel Token / 凭证 JSON | cloudflared 向 Cloudflare 建立连接 | Cloudflare 后台或 `tunnel create` |

两者不能互换。建立 Tunnel 不代表 MCP 已鉴权成功；必须分别验证网关、隧道和 MCP。

### 安装 cloudflared

```powershell
winget install --id Cloudflare.cloudflared --exact
```

安装后打开新的 PowerShell：

```powershell
cloudflared --version
```

若不在 PATH，检查 `C:\Program Files\cloudflared` 或 `C:\Program Files (x86)\cloudflared`，将实际安装目录加入 PATH 后重开终端。官方资料：<https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/>。

### 方案 A：Quick Tunnel，临时体验

无需自有域名。先启动本机网关，再到控制台的 Cloudflare Tunnel 设置中选 **quick** 并启动，等日志出现 `https://随机名称.trycloudflare.com`；客户端连接该地址加 `/mcp`。

也可以在独立终端启动：

```powershell
cloudflared tunnel --url http://127.0.0.1:8789
```

手动启动时，将日志中的公网主机名登记到控制台；若已有 cloudflared，控制台可能只检测到外部进程，不会自动知道它服务的域名。

**限制与风险：** Quick Tunnel 地址可能每次变化，无可用性保证；Cloudflare 官方注明 Quick Tunnel 不支持 SSE，而 MCP 使用 Streamable HTTP 并可能返回 SSE，所以它只适合临时排查，**不能作为稳定 MCP 长连接方案**。若初始化、通知或长请求异常，改用 Named Tunnel。Quick Tunnel 转发整个站点，静态控制台外壳也可能公网可见；API 仍需鉴权，但这不等同于“只公开 MCP”。

若 Quick Tunnel 因用户目录已有 cloudflared 配置而无法启动，使用命名隧道，或先妥善备份再按 Cloudflare 文档调整配置；不要直接删除现有配置。

### 方案 B：Named Tunnel + 自有域名（推荐）

前提：一个已加入你 Cloudflare 账号、DNS 托管生效的域名。以下 `example.com`、用户名及隧道 UUID 都是占位值。

**1. 登录授权**

```powershell
cloudflared tunnel login
```

在打开的浏览器中选择域名并授权。生成的 `cert.pem` 是敏感凭证，只存你自己的用户目录，不要放进项目。

**2. 创建隧道**

```powershell
cloudflared tunnel create arena-local
```

记录输出中的隧道 UUID，凭证通常存于 `%USERPROFILE%\.cloudflared\<UUID>.json`。

**3. 建立 DNS 路由**

```powershell
cloudflared tunnel route dns arena-local mcp.example.com
```

如同名 DNS 记录已存在，应先检查用途并处理冲突，不要覆盖不明记录。

**4. 写入 ingress 配置**

将项目的 `config/cloudflared.config.example.yml` 复制到 `%USERPROFILE%\.cloudflared\config.yml`，但若目标已存在，先备份并人工合并，勿直接覆盖。

```yaml
tunnel: REPLACE_WITH_TUNNEL_UUID
credentials-file: 'C:/Users/YOUR_USER/.cloudflared/REPLACE_WITH_TUNNEL_UUID.json'
ingress:
  - hostname: mcp.example.com
    path: ^/mcp$
    service: http://127.0.0.1:8789
  - service: http_status:404
```

使用空格缩进，Windows 路径推荐正斜线；替换全部占位值。该配置**只转发 `/mcp`**，公网 `/`、`/api/config`、`/healthz` 都返回 404，本机控制台不受影响。

**5. 校验并运行**

```powershell
cloudflared tunnel --config "$env:USERPROFILE\.cloudflared\config.yml" ingress validate
cloudflared tunnel --config "$env:USERPROFILE\.cloudflared\config.yml" run arena-local
```

保持窗口打开。在控制台选择 `named-name` 并填写名称 `arena-local`、公网主机名 `mcp.example.com`，也可以让控制台负责启动（不要两种方式重复启动）。项目辅助脚本用法：

```powershell
.\scripts\start-cloudflare.ps1 -TunnelName 'arena-local'
```

网关启动脚本也支持 `-WithCloudflare -TunnelName 'arena-local'`；它使用用户目录的现有配置，不会自动完成域名注册、登录授权或创建隧道。

**6. 验证**

- 本机 `Invoke-RestMethod http://127.0.0.1:8789/healthz` 应返回健康信息。
- cloudflared 日志应显示连接注册成功；仅出现进程 PID 不表示域名已正确路由。
- 从公网访问 `/api/config` 应为 **404**（推荐 ingress 下）；如果返回控制台数据，立即停止隧道检查路由。
- 客户端用正确 Gateway Token 连接 `https://mcp.example.com/mcp`，执行 `get_task_briefing`。
- 401 通常是网关 Token 问题，502 通常是隧道无法连接本地端口；具体见故障排查。

### 方案 C：Cloudflare 后台管理的 Tunnel Token

1. 登录 Cloudflare Zero Trust，在 Networks / Connectors / Tunnels 对应页面创建 Cloudflared Tunnel（后台名称可能调整）。
2. 选择 Windows，获取连接器安装命令中的 Tunnel Token。不要把包含 Token 的完整命令发到 Issue。
3. 在本地控制台选择 **named-token**，私密填入 Tunnel Token，填写公网主机名并启动。
4. 在 Cloudflare 中设置公开主机名 `mcp.example.com`，服务类型 HTTP，地址 `127.0.0.1:8789`；将路径规则限定为 `^/mcp$`，确保不存在同主机的无路径兜底转发规则。
5. 核对公网 `/api/config` 不可达，再用 Gateway Token 做 MCP 验证。

后台管理的隧道主要使用后台路由配置，不要以为本机 YAML 一定会覆盖后台配置。若无法确认后台路径限制生效，优先使用方案 B 的本地配置并校验 ingress。

### 长期运行与网络注意事项

- cloudflared 需要持续运行；笔记本休眠、断网或网关退出都会影响连接。
- Tunnel 建立出站连接，一般不需要路由器端口转发，也不需要把网关绑定到 `0.0.0.0`。
- 自动重连不等于 Windows 登录启动服务。确需服务方式，按 Cloudflare 官方 Windows 服务文档配置，并留意服务账号的用户目录、凭证权限及网关是否已启动。不要在未确认前覆盖已有 cloudflared 服务。
- 企业防火墙可能阻断连接器协议；按官方网络要求排查，不要关闭整台电脑防火墙。
- Cloudflare Access 的交互式登录页面可能使 MCP 客户端无法连接。需要 Access 时应配置客户端支持的服务身份，并区分 Access 凭证与网关 Bearer；不要为解决报错而关闭网关鉴权。
- 推荐规则下不对公网提供健康检查；请在本机检查健康，不能因为公网 `/healthz` 是 404 就断言网关离线。

## 配置与安全边界

`config/.env.example` 仅为变量参考，程序**不会自动加载该文件**。用 PowerShell `$env:变量名 = '值'` 后在同一窗口启动，或通过本地控制台设置。SQLite 中已持久化的设置通常优先于环境变量（监听地址和端口取环境变量）。

| 变量 | 含义 |
| --- | --- |
| `ARENA_GATEWAY_HOST` | 默认 `127.0.0.1`，保持本机监听 |
| `ARENA_GATEWAY_PORT` | 默认 `8789` |
| `ARENA_GATEWAY_TOKEN` | 留空自动生成；已持久化 Token 优先 |
| `ARENA_WORKSPACE_ROOTS` | 初始工作区，多项用分号分隔 |
| `ARENA_REQUIRE_APPROVAL` | 建议 `true`；发布启动脚本默认开启 |
| `ARENA_RESTRICT_TO_WORKSPACE` | 建议 `true`；只限制文件工具，不隔离 PowerShell |
| `ARENA_LOCAL_AUTH` | `true` 时本机 API 也需要 Token；开启前确保安全保存有效 Token |
| `ARENA_ALLOW_SELF_APPROVAL` | 建议保持 `false`，不允许 Agent 自行批准 |

**不能夸大的边界：**

- 网关 `/mcp` 始终需要 Token。本机控制台 API 默认可免鉴权；代理转发的请求不能享受本机免鉴权。
- 完整站点隧道会转发控制台外壳；只绑定 loopback 并不等于它不会被隧道公开。真正只公开 MCP 要靠 ingress 路径规则。
- 原始网关直接启动的审批和工作区限制默认关闭；发布的一键脚本为新实例设置了更安全的默认环境值。已有数据库覆盖值仍可能关闭它们，启动后必须检查控制台。
- 工作区约束不是 OS 安全沙箱；PowerShell 仍有当前用户的文件和网络权限。严格隔离请使用专门 Windows 用户或虚拟机。
- Token 轮换有约 10 分钟旧 Token 宽限期。泄露时先停公网入口，轮换 Token，必要时重启网关清除内存宽限期，再重新接入。
- 不建议放行所有浏览器扩展；只允许明确需要的扩展来源。
- `data/` 包含敏感持久化状态。备份需妥善保管，停止网关后完整备份以避免 SQLite/WAL 不一致。升级源码不应直接覆盖或删除现有数据。

## 开发与测试

```powershell
npm.cmd ci
npm.cmd run typecheck
npm.cmd run build
node .\scripts\test-connection-prompt.mjs
```

前后端开发分别开两个窗口：

```powershell
npm.cmd run dev:gateway
# 另一个窗口
npm.cmd run dev:web
```

前端开发默认使用 `5173`，代理配置见 `apps/web/vite.config.ts`。自定义网关端口时同时检查代理目标。

**冒烟测试会修改任务、工作区、技能和记忆等状态，不能对正在使用的网关运行。** 在单独解压的测试副本中，使用独立 `data/`、临时工作区和例如 `18789` 端口启动网关，然后在测试副本另一个终端运行：

```powershell
node .\scripts\smoke-test.mjs http://127.0.0.1:18789
```

测试脚本通过本地 API 获取 Token，因此本机强制鉴权模式下需要调整测试凭证获取方式；不能为让测试通过而关闭生产网关鉴权。测试完停止测试实例；不要把测试数据打进发布 ZIP。

```text
apps/gateway/      Node.js + TypeScript MCP 网关
apps/web/          React + Vite 控制台
config/            不含真实凭证的配置示例
scripts/           Cloudflare 启动辅助与冒烟测试
start-*.bat/ps1    Windows 启动入口
data/.gitkeep      运行数据目录占位，实际数据不入库
```

## 故障排查

| 现象 | 检查与处理 |
| --- | --- |
| npm.ps1 被执行策略阻止 | 交互命令使用 `npm.cmd`；启动器以 `powershell.exe -ExecutionPolicy Bypass -File ...` 运行，此参数仅作用于该进程 |
| 找不到 node:sqlite | 更新到 Node 24 LTS，检查 `where.exe node` 是否仍指向旧版 |
| 安装依赖失败 | 检查网络、Node 架构及 npm 日志；使用锁文件重新 `npm.cmd ci`，不要上传日志中的凭证 |
| 8789 被占用 | 不要停止未知进程；确认是旧网关还是其他程序，用 `-Port 18789` 启动独立实例 |
| 修改前端后页面没变化 | 重新 `npm.cmd run build:web`；启动器只在 dist 缺失时构建 |
| 工作区还是旧项目 | 已运行实例被复用或数据库已有配置；在顶栏切换并重新读取任务简报 |
| MCP 401 | 检查 Bearer 前缀、Gateway Token、轮换后的配置；不要使用 Tunnel Token |
| MCP 403 | 查看来源白名单/跨站拒绝信息；不要一律放开所有扩展 |
| Cloudflare 502 | 检查本地健康、端口及 ingress 服务地址；网关必须持续运行 |
| Cloudflare 1033 / Tunnel 离线 | 检查连接器是否在线、凭证/名称是否对应、DNS 与网络是否正确 |
| 公网 /mcp 404 | 检查 hostname、路径必须精确 `/mcp`、DNS 路由和最后的 404 兜底规则 |
| 控制台显示隧道运行但 MCP 不通 | 可能只是检测到其他 cloudflared 进程；实际验证域名路由和协议调用 |
| Quick Tunnel 断流 | 切换 Named Tunnel；Quick Tunnel 不适合作为 SSE 长连接保证 |
| 重连后 session 不存在 | 重新 initialize，发送 initialized 通知，再调用 get_task_briefing |

## 发布到 GitHub

此文件夹已按源码发布整理，不包含原仓库 `.git` 历史、个人配置、运行数据库、审计记录、缓存、依赖或第三方本机技能。不要直接把原工作目录整包上传。

1. **许可证**：本包没有替作者选择开源许可证。公开仓库不自动授予开源使用权；发布前由权利人选择许可证并添加 `LICENSE`，确认第三方素材和代码使用权。依赖许可证以各依赖声明为准。
2. 在 GitHub 创建空仓库（先不要自动添加 README / LICENSE / .gitignore）。
3. 建议把本文件夹复制到原项目外的独立位置，例如 `D:\Publish\arena-local-agent`，然后进入它；避免 Git 向上找到原仓库。
4. 初始化、检查并提交：

```powershell
Set-Location 'D:\Publish\arena-local-agent'
git init
git branch -M main
git add .
git status --short
git diff --cached --stat
# 人工确认暂存区没有 data、Token、用户路径或凭证后再提交
git commit -m "chore: prepare initial public source release"
git remote add origin https://github.com/Aries430323/arena-to-local.git
git push -u origin main
```

如用 GitHub Desktop，添加的是这个独立发布目录，不是原始项目。不要强制推送覆盖已有远端仓库。

本地构建出来的 `dist/`、运行数据和 `node_modules/` 已被 `.gitignore` 排除；但 `.gitignore` 不能自动清除已经被跟踪的敏感文件。提交前始终检查暂存区。若凭证曾被公开，应先吊销/轮换，删除文件或修改 Git 历史不能让旧凭证重新安全。

发布后的使用者可以从 GitHub 下载源码并按照本 README 安装。若要提供开箱即用 ZIP，需要另行设计 Windows 打包与签名流程，不应把本机依赖目录直接当作通用安装包。