Capyra

让对话中的想法，在你自己的电脑上发生。

轻量、可组合的本机 AI 能力平台，为 ChatGPT 和其他 MCP 客户端提供工作区、文件、终端、Git、桌面控制、编码代理与插件能力。

快速开始 · 连接 ChatGPT · 插件开发 · 安全模型 · 开发文档

Capyra 是什么

Capyra 在本机运行一个 MCP 服务和一个浏览器工作台。AI 客户端提出请求，Capyra 在你选择的工作区内执行，并按照本机设置进行逐次确认或自动批准。文件、命令、Git 状态和任务结果保留在你的电脑上；只有获准返回的内容会发送给客户端。

它适合这些场景：

• 让 ChatGPT 浏览、搜索和修改本机项目。

• 运行命令、交互终端和持续时间较长的任务。

• 查看 Git 差异、历史和隔离 worktree。

• 通过截图与鼠标键盘工具，让 ChatGPT 直接观察和操作 macOS 桌面。

• 从同一个对话派发并继续 Codex、Claude、OpenCode、Pi、Cursor、Copilot 或 Grok 编码代理。

• 用自然语言创建、检查、安装和组合 Capyra 插件。

• 通过 stdio、本机 HTTP、Cloudflare Tunnel 或自托管固定 Relay 接入 MCP 客户端。

Related MCP server: Kastor

主要能力

快速开始

环境要求

• Node.js 22.16 或更新版本。

• npm 10 或更新版本。

• Git；只使用文件和终端功能时可选。

从源码运行

git clone https://github.com/dxeledx/capyra.git
cd capyra
npm ci
npm run build
node dist/cli.js init
node dist/cli.js start --open

init 会在当前目录创建 capyra.json。start --open 启动 MCP 服务并打开带一次性本机认证的管理工作台：

• 本机工作台：http://127.0.0.1:4318

• MCP：http://127.0.0.1:4317/mcp

重新打开正在运行的工作台：

node dist/cli.js open

安装为全局命令：

npm install -g .
capyra init
capyra start --open

Capyra 尚未发布到 npm registry。请从本仓库源码安装；registry 中的同名包不代表本项目。

第一次使用

1. 在顶部工作区菜单打开“管理工作区”。

2. 点击“选择文件夹”，在系统目录面板中选择项目，然后注册。

3. 在“插件组合”中启用需要的能力并检查权限。

4. 打开“连接 ChatGPT”，复制固定 MCP 地址并完成一次 OAuth 授权。

5. 默认个人模式会自动执行正常请求；多人共用 ChatGPT 账号时，再开启“共享账号保护”。

每个 ChatGPT 对话第一次调用 Capyra 时绑定当时的工作区。本机切换默认工作区只影响以后建立的对话；已有对话继续使用原项目。要改变当前对话，直接让 Capyra 列出并选择工作区，无需 reconnect 或新开对话。

连接 ChatGPT

ChatGPT 需要能够访问一个 HTTPS MCP 地址。Capyra 提供以下方式：

Quick Tunnel

在工作台的“连接 ChatGPT”中选择“快速直连”，让 Capyra 下载并校验官方 cloudflared，然后启动连接。页面会给出连接名称、HTTPS MCP 地址和认证方式。

在 ChatGPT 中启用开发者模式并添加自定义应用：

1. 名称填写 Capyra。

2. MCP 地址粘贴工作台生成的 HTTPS 地址。

3. 认证方式选择 OAuth。

4. 回到本机工作台批准首次连接。

5. 在对话中选择 Capyra 并发送：“请使用 Capyra 浏览当前工作区，并告诉我有哪些文件。”

Quick Tunnel 的地址可能变化。地址不变时继续使用原连接；地址变化时更新 ChatGPT 中的应用连接。

固定 Relay

sites-relay/ 提供自托管固定入口的参考实现。它使用 D1 保存设备公钥、短时请求和防重放随机数；设备私钥、OAuth 令牌、工作区数据和批准操作留在本机。部署后，在工作台填写 Relay 首页地址和管理员生成的设备接入码。

Relay 地址、接入码和托管项目 ID 不包含在仓库中。详见固定连接说明和 Relay 部署说明。

本机 MCP 客户端

node /absolute/path/to/capyra/dist/cli.js start \
  --stdio \
  --workspace /path/to/project

stdio 模式只在 stdout 输出 MCP 协议；状态写入 stderr。stdin 关闭后实例会释放资源。

工作原理

flowchart LR
  Client[ChatGPT / MCP 客户端] -->|OAuth + MCP| MCP[MCP 服务 :4317]
  Browser[本机浏览器] -->|一次性入口 + HttpOnly 会话| Console[管理工作台 :4318]
  Console --> Runtime[Capyra Runtime]
  MCP --> Policy[授权与批准]
  Policy --> Runtime
  Runtime --> Plugins[插件与服务]
  Plugins --> Workspace[本机工作区]
  Plugins --> Terminal[终端 / Git / 编码代理]

MCP 入口与本机管理入口分别监听。公网连接只转发 MCP 与 OAuth 所需路由，不能调用批准设置或替用户批准请求。

批准与结果

• 个人模式（默认）：完成一次 OAuth 连接授权后自动执行正常请求；仍受工作区、插件权限、暂停和撤销约束。

• 共享账号保护：一键开启后，读取、搜索、目录、命令和历史结果逐项在本机批准。

• 仅留本机：任务可以执行，但完整结果不返回客户端。

• 暂停与撤销：暂停拒绝新请求并中断远程后台任务；撤销使对应 OAuth 令牌和请求失效。

本机“更多功能 → 安全与授权”会列出每条 OAuth 连接，可以添加本机备注、查看创建时间/最后访问/请求数，并单独暂停、恢复或撤销。ChatGPT 不会把登录邮箱或 OpenAI 账号 ID 提供给 MCP 服务，因此备注用于区分个人、工作等连接，不能视为经过 OpenAI 验证的账号身份。

个人模式无法区分共享同一个 ChatGPT 账号的不同操作者。共享账号场景应开启“共享账号保护”，并在不使用时暂停或撤销连接。账号与设备认证继续作为可选高级插件，默认不启用。

插件开发

内置功能和外部插件使用同一套 API v1。插件可以注册工具、服务、指令和资源，并声明权限、依赖、配置 schema 与释放逻辑。

capyra plugin create paper-organizer \
  --prompt "按年份和主题整理论文，并生成索引"

capyra plugin spec --json
capyra plugin validate ./capyra-plugins/paper-organizer --json
capyra plugin install ./capyra-plugins/paper-organizer
capyra plugin enable paper-organizer

新插件安装后默认禁用。启用前由本机用户检查 manifest、权限和配置。可运行示例：

• 单词统计工具

• SQLite 存储替换

• 严格执行策略

• 替换式本机界面

完整契约见插件开发指南。

用户明确要求安装和启用后，ChatGPT 可以在同一对话里完成预检、安装、授权与启用，不需要用户执行终端命令。若改动的是 Capyra 宿主自身，plugin-dev__host_update 会在本机逐次确认后安装精确 SHA-256 的本地包，短暂重启同一实例，并在失败时恢复旧包；原对话通过固定 MCP 地址继续。

编码代理

capyra agents targets
capyra agents run codex --prompt "Read the project and explain its structure"
capyra agents ls
capyra agents show AGENT_ID
capyra agents continue AGENT_ID --prompt "Continue the previous task"
capyra agents daemon status

代理提供者需要相应客户端、SDK 或合法登录。模型调用可能消耗提供者额度；Capyra 不附带第三方账号或 API Key。详见代理运维。

桌面控制（Computer Use）

在本机工作台打开“桌面控制”，添加 computer 内置插件，配置所需的 computer:read / computer:execute 权限，再在插件组合中启用。已有配置不会自动开放桌面权限。

ChatGPT 通过四个 MCP 工具形成视觉操作闭环：computer__prepare 明确准备本机组件，computer__status 检查环境，computer__screenshot 返回原生图片与坐标元数据，computer__act 根据最新截图执行一组鼠标键盘操作并返回新的截图。桌面控制本身不需要额外模型 API Key。用户要求安装和使用后，ChatGPT 可以通过 plugin-dev__install_builtin 完成受控安装、授权和启用，不需要用户执行终端命令。

当前实现面向 macOS 14 或更新版本的主显示器，需要本机编译工具与系统屏幕录制、辅助功能权限。首次准备原生组件、截图和键鼠操作分别受 computer:prepare、computer:read 与 computer:execute 控制；截图和动作默认跟随工作台的逐次确认或自动批准设置，也可由本机单独改为每次确认。桌面操作不受项目目录限制；截图可能包含其他应用的信息。安装、权限、工具示例与验收步骤见桌面控制指南。

安全模型

Capyra 运行在你的操作系统账号权限下，因此应把它当作本机开发工具：

• 本机工作台使用一次性启动链接、HttpOnly cookie、Host 与同源检查。

• OAuth、Capyra 账号、设备绑定和具体任务批准属于不同安全层。

• 文件工具拒绝目录穿越、受保护配置、符号链接和硬链接别名。

• 写入支持 SHA 前置条件，避免覆盖读取后已经变化的文件。

• 远程请求在批准前不读取文件敏感预览；断连、超时和撤销会使批准失效。

• 原生插件、命令和编码代理拥有当前系统用户可用的权限，批准前应检查目录、命令和内容。

• 桌面控制可触及当前桌面的其他应用；会话与工作区隔离用于工具状态归属，不构成桌面沙箱。

• 密钥、配置、任务状态与设备私钥存放在私有 .capyra/，不得提交到 Git。

漏洞报告方式见 SECURITY.md，实现边界见安全设计。

配置

默认配置文件是当前目录的 capyra.json。常用命令：

capyra init
capyra doctor
capyra start --open
capyra start --compact
capyra start --tunnel cloudflare
capyra local

CLI 完整列表：

capyra --help

项目结构

src/            核心运行时、插件、连接、身份和 MCP 传输
public/         本机浏览器工作台
tests/          Node 测试与协议/安全回归
examples/       外部插件与替换式服务示例
schemas/        插件 manifest JSON Schema
cloud/          可选账号与设备服务
sites-relay/    可选固定设备 Relay
docs/           使用、扩展和安全文档

开发

npm ci
npm run build
npm test
npm run check

提交补丁前请阅读 CONTRIBUTING.md。TypeScript 构建输出位于 dist/，不提交到仓库。

开发文档

• 架构概览

• 插件开发

• 连接与运维

• 固定 Relay

• 编码代理

• 桌面控制（Computer Use）

• Skills 与项目规则

• MCP Apps 界面

• 安全设计

项目状态

Capyra 仍处于 0.x 阶段，插件 API 为 v1。macOS 是当前主要开发环境；通用功能具有 Windows 和 Linux 代码路径，桌面控制目前仅实现 macOS 后端。跨平台发布前仍需要更多真实设备反馈。

项目的产品能力参考 DevSpace，插件化方向参考 DeepSeek Harness。Capyra 的实现、接口与用户体验均为独立设计。

贡献与许可证

欢迎提交 Issue 和 Pull Request。请勿在 Issue、日志或示例中附带真实令牌、私钥、设备地址或工作区内容。

Capyra 使用 MIT License。