Arena Local Agent

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

安全提示：这是远程执行工具，不是隔离虚拟机。 持有网关 Token 的客户端可能以启动网关的 Windows 用户权限操作电脑。不要以管理员身份运行网关，不要把 Token、隧道凭证或运行数据库上传 GitHub。建议先在不含敏感信息的测试项目中试用。

本项目为独立工具，不表示获得 Arena.ai 官方授权或背书。此次发布包是源码版本，不含依赖、个人数据或预构建二进制。

目录

• 环境要求

• 安装与首次启动

• 日常使用

• 连接 AI 客户端

• 建立 Cloudflare 隧道

• 配置与安全边界

• 开发与测试

• 故障排查

• 发布到 GitHub

Related MCP server: COP Plug

架构与功能

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，每行分别执行）：

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

安装与首次启动

1. 下载或克隆

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

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.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 窗口中、项目根目录下执行：

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 文档。

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

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

安装 cloudflared

winget install --id Cloudflare.cloudflared --exact

安装后打开新的 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。

也可以在独立终端启动：

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. 登录授权

cloudflared tunnel login

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

2. 创建隧道

cloudflared tunnel create arena-local

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

3. 建立 DNS 路由

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

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

4. 写入 ingress 配置

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

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. 校验并运行

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，也可以让控制台负责启动（不要两种方式重复启动）。项目辅助脚本用法：

.\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 中已持久化的设置通常优先于环境变量（监听地址和端口取环境变量）。

不能夸大的边界：

• 网关 /mcp 始终需要 Token。本机控制台 API 默认可免鉴权；代理转发的请求不能享受本机免鉴权。

• 完整站点隧道会转发控制台外壳；只绑定 loopback 并不等于它不会被隧道公开。真正只公开 MCP 要靠 ingress 路径规则。

• 原始网关直接启动的审批和工作区限制默认关闭；发布的一键脚本为新实例设置了更安全的默认环境值。已有数据库覆盖值仍可能关闭它们，启动后必须检查控制台。

• 工作区约束不是 OS 安全沙箱；PowerShell 仍有当前用户的文件和网络权限。严格隔离请使用专门 Windows 用户或虚拟机。

• Token 轮换有约 10 分钟旧 Token 宽限期。泄露时先停公网入口，轮换 Token，必要时重启网关清除内存宽限期，再重新接入。

• 不建议放行所有浏览器扩展；只允许明确需要的扩展来源。

• data/ 包含敏感持久化状态。备份需妥善保管，停止网关后完整备份以避免 SQLite/WAL 不一致。升级源码不应直接覆盖或删除现有数据。

开发与测试

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

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

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

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

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

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

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

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

故障排查

发布到 GitHub

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

1. 许可证：本包没有替作者选择开源许可证。公开仓库不自动授予开源使用权；发布前由权利人选择许可证并添加 LICENSE，确认第三方素材和代码使用权。依赖许可证以各依赖声明为准。

2. 在 GitHub 创建空仓库（先不要自动添加 README / LICENSE / .gitignore）。

3. 建议把本文件夹复制到原项目外的独立位置，例如 D:\Publish\arena-local-agent，然后进入它；避免 Git 向上找到原仓库。

4. 初始化、检查并提交：

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 打包与签名流程，不应把本机依赖目录直接当作通用安装包。