内容
# 卡普里戈
**本地优先的 AI 代理运行时** — 工具、MCP、任务、Board/会话、市场连接的技能。
| | |
|-|-|
| 产品 | [caprigoai.com](https://caprigoai.com) |
| 仓库 | https://github.com/doteyeso-ops/caprigo |
| 致谢 | **b_Radford** · Vibes-Coded |
| 许可证 | MIT |
| 市场 | [vibes-coded.com](https://vibes-coded.com) |
| AMD 实例证明 | [rx580-vulkan-agents](https://github.com/doteyeso-ops/rx580-vulkan-agents) · [docs/AMD.md](docs/AMD.md) |
| 演示视频 | [docs/demo/Caprigo_AMD_Demo.mp4](docs/demo/Caprigo_AMD_Demo.mp4) (~72s, 配音) |
**8GB / 废弃 GPU:** 设置 `CAPRIGO_LEAN_TOOLS=1`，这样无限制代理将发送约 17 个核心工具，而不是完整的约 170 个工具目录（vibes / Agent Skills / MCP 模式）。在需要额外功能时分配技能。
- **卡普里戈核心** — 运行时（LLM 适配器、技能、会话、网关）
- **卡普里戈 CLI** — `caprigo` 命令行客户端
- **卡普里戈网格** — 代理网络（计划中）
## 演示（AMD）
[约 72 秒的演练](docs/demo/Caprigo_AMD_Demo.mp4) — 卡普里戈概述 / 会话 / 板块，RX 580 Vulkan 实验室基准，配音。
https://github.com/doteyeso-ops/caprigo/raw/main/docs/demo/Caprigo_AMD_Demo.mp4
更多 AMD 背景信息：[docs/AMD.md](docs/AMD.md) · 废弃包：[rx580-vulkan-agents](https://github.com/doteyeso-ops/rx580-vulkan-agents)
## 快速开始
```bash
git clone https://github.com/doteyeso-ops/caprigo.git
cd caprigo
cp .env.example .env # 编辑 OLLAMA_URL / DEFAULT_MODEL（如果需要）
npm install
npm run build
npm run build:web
npm run start # 网关 + 仪表盘，端口：18789
```
有关推荐的测试设置路径，请参见 `INSTALL_AND_FIRST_RUN.md`。
Windows 快速开始：
```powershell
.\setup.ps1
```
或：
```bat
setup.bat
```
如果卡普里戈已经配置好，您只需启动它：
```powershell
.\launch.ps1
```
CLI 首次运行助手：
```bash
caprigo onboard
caprigo setup --interactive
caprigo doctor
```
交互式设置流程可以为您编写 `.env`，启动网关，并为您打开本地概览页面。`setup.ps1` 将安装、构建和引导设置封装为一个 Windows 优先的入口点，而 `launch.ps1` 是轻量级的设置后启动器。
使用 `caprigo doctor` 检查本地配置、权限和运行时状态，以排查测试安装问题。
或者，对于开发：在另一个终端运行 `npm run web`（Vite，端口：3000，热重载）。
然后：
```bash
# 创建会话
curl -X POST http://localhost:18789/api/sessions
# 发送消息（使用上述会话 ID）
curl -X POST http://localhost:18789/api/sessions/SESSION_ID/messages \
-H "Content-Type: application/json" \
-d '{"message": "列出当前目录中的文件"}'
```
Web UI 中的内置工作流团队现在包括：
- `仓库团队` - 仓库侦察和实施
- `自动化团队` - 本地脚本执行和结果报告
- `启动审计团队` - 跨设置、UX 和发布风险的启动就绪性审查
- `PR 审查团队` - 用于本地差异、补丁、分支或拉取请求的构造审查工作流
板块级工作流工具现在还包括：
- `工作流库` - 来自概览和板块的内置团队的共享启动器
- `工作流配方` - 保存的本地预设，用于编排启动，包括触发器元数据（`手动`、`文件更改`、`每日扫描`）和可选的引导指令 Markdown，注入到启动的引导中
- 所选团队条带 - 显示当前引导、成员芯片和直接操作，当在板块上选择团队成员时
- 重量级跟踪徽章 - 当会话的近期跟踪量或成本启发式看起来很高时发出警告
## 添加您自己的技能
将 `.js` 文件放入 `./skills/` 或 `~/.caprigo/skills/`。对于 **Agent Skills**（`SKILL.md`，[agentskills.io](https://agentskills.io) 兼容布局），使用 `./skills/agentskills/`（参见 `skills/agentskills/README.md`）。
```javascript
// skills/my-skill/index.js
module.exports = {
name: 'my_skill',
description: 'What it does',
execute: async (params) => {
return { success: true, result: 'done' };
},
};
```
重启网关。您的技能已加载。
内置的文件系统/上下文工具现在包括：
- `read_file`
- `list_directory`
- `search_files`
- `search_replace`
- `repo_map` — 用于符号级上下文的紧凑结构化代码库映射，无需将整个文件转储到提示中
- `codebase_context` — 一次性存储库感知检索，结合结构化映射和文本命中，然后在 `read_file` 之前对候选文件进行排名
对于 TypeScript/JavaScript 家族文件，存储库映射现在使用真正的 TypeScript AST 遍历，用于类、接口、类型、枚举、函数、方法和函数值属性。其他语言仍使用现有的轻量级启发式路径。
## 跟踪可见性
卡普里戈现在公开了一个轻量级的跟踪/重放层，用于工具活动，无需添加单独的可观察性服务。
- 会话跟踪条目现在包括紧凑的 `rationale`、`resultSummary` 和 `outputChars` 字段。
- Web UI 从最近的跟踪活动中推导出粗略的压力和成本启发式，包括 `light` / `watch` / `heavy` 压力和 `low` / `watch` / `high` 成本信号。
- 板块卡片可以在会话的最近跟踪看起来昂贵或嘈杂时显示 `Heavy` 徽章。
- 会话详细信息可以导出跟踪包为 Markdown 或 JSON，以便重放和审查。
相关端点：
- `GET /api/execution-log`
- `GET /api/sessions/:id/execution-log`
- `GET /api/sessions/:id/execution-log/export?format=markdown`
- `GET /api/sessions/:id/execution-log/export?format=json`
## 权限强化
卡普里戈现在应用了一个基准权限层，其灵感来自我们审查的上游 agent-runtime 项目：
- 文件系统工具的作用域限定在批准的路径
- shell 执行拒绝阻止命令列表
- 默认情况下，shell 工作目录必须保持在批准的作用域内
卡普里戈将权限文件写入：
```text
~/.caprigo/permissions.json
```
默认批准的作用域包括：
- 卡普里戈工作区根目录
- 卡普里戈数据根目录
如果文件或 shell 操作被拒绝，请有意扩展 `permissions.json` 中的批准作用域，而不是禁用整个安全层。
## 全局 LLM 指南
卡普里戈现在支持工作区级指南文件，该文件在模型开始运行之前会自动注入到每个 **LLM** 会话中。
- 默认文件：工作区根目录中的 `CAPRIGO_LLM_GUIDE.md`
- 工作区根目录：`CAPRIGO_WORKSPACE`（如果设置），否则网关工作目录
- 可选覆盖：`CAPRIGO_LLM_GUIDE_PATH` 或 `CAPRIGO_PROGRAM_GUIDE_PATH`
使用此文件为连接的模型描述卡普里戈本身：产品是什么，UI 如何映射到行为，何时使用 Board 与 Session，运行时模式，编排以及您希望每个模型首先读取的任何产品特定操作规则。
本文件的推荐内容包括卡普里戈与 **vibes-coded.com**、市场导入技能以及您希望外部 LLM 在开始操作产品之前了解的任何连接器特定规则。
## 卡普里戈 CLI
命令名称是 **`caprigo`**（参见 `packages/cli` → `"bin": { "caprigo": ... }`）。您 **不** 必须输入 `npm run cli --`，除非您更喜欢存储库快捷方式。
**从存储库根目录**（在 `npm install` 和 `npm run build` 之后，以便 `packages/cli/dist` 存在）：
- **`npx caprigo`** — 从工作区运行 `caprigo` 二进制文件（与链接的全局 `caprigo` 相同）。
- **`npm run caprigo -- <args>`** — 相同的 CLI； `--` 将标志转发（例如 `npm run caprigo -- agents list`）。
**在您的 PATH 上**（选择一个）：
- **`cd packages/cli && npm link`** — 然后在任意目录键入 **`caprigo`**。
- 或 **`npm install -g ./packages/cli`** 从存储库根目录 — 在全局安装 `caprigo` 命令。
如果 API 不在 `http://localhost:18789`，请设置 **`CAPRIGO_GATEWAY_URL`**。如果网关使用 **`CAPRIGO_API_TOKEN`**，请在 shell 中导出相同的令牌用于变更 CLI 调用。
```bash
caprigo # 概览首页面板
caprigo open # 在浏览器中打开仪表盘
caprigo agents list
caprigo agents create -n "Coder"
caprigo chat <sessionId> -m "Hello"
caprigo skills
caprigo models
caprigo health
caprigo onboard
```
## 可选：MiroFish 集成
[MiroFish](https://github.com/666ghj/MiroFish) 是一个 API 驱动的群体智能引擎。要启用：
```bash
cp -r integrations/mirofish skills/mirofish
```
需要运行在端口 5001 上的 MiroFish 后端。设置 `MIROFISH_URL` 以覆盖。
## 可选：MCP 服务器（例如 Windows-MCP）
卡普里戈核心包括一个 **MCP 客户端**：网关可以启动 stdio MCP 服务器，并将每个工具公开为 `mcp_<id>_<tool>`，与普通技能并列。在 Web UI 中在 **设置 → MCP 服务器** 下配置（在您的卡普里戈数据目录下写入 `gateway/mcp-servers.json`），或使用 `GET`/`PATCH /api/mcp-servers`。
对于 [Windows-MCP](https://github.com/CursorTouch/Windows-MCP)，具体参见 [integrations/windows-mcp/README.md](integrations/windows-mcp/README.md)。您也可以仅使用 [mcp-config.example.json](integrations/windows-mcp/mcp-config.example.json) 将 Windows-MCP 附加到 **Cursor** 或另一个 IDE。
环境变量：`CAPRIGO_DISABLE_MCP=1` 禁用 MCP；`CAPRIGO_MCP_TOOL_TIMEOUT_MS` 设置每工具超时（默认 180000 毫秒）。
## 要求
- Node.js 18+
- [Ollama](https://ollama.ai) 已安装并运行
- 本地 Ollama 模型，例如：`ollama pull qwen3.5:latest`
### Ollama GPU（CPU 重推理，空闲 GPU）
卡普里戈仅通过 HTTP 调用 **Ollama**；**GPU 与否由 Ollama 主机决定**（驱动程序、构建、模型大小、VRAM）。
1. **验证服务器实际使用 GPU:** 在请求期间，查看 **NVIDIA:** `nvidia-smi`；**AMD (Linux):** 如果可用，`rocm-smi` / `radeontop`。平坦的 VRAM + 繁忙的 CPU 通常意味着 CPU 推断。
2. **常见原因：** Ollama 安装为 **仅限 CPU**；**Docker** 无 GPU 直通；**模型 + KV 缓存** 大于 VRAM，因此大多数权重在 CPU 上运行；非常大的 **`num_ctx`** 在设置中占用 VRAM。
3. **在 Ollama 端修复：** 安装 **GPU 启用** 的 Ollama 构建和正确的 **NVIDIA** 或 **AMD ROCm** 堆栈用于您的操作系统。使用适合 VRAM 的量化模型或较小的标签。降低上下文（**设置 →** 引擎 / 每代理）。参见 [Ollama GPU](https://docs.ollama.com/gpu) 和您操作系统的上游存储库。
#### AMD RX 580（8 GB）和类似的 Polaris 卡
**现代 ROCm 放弃了 Polaris。** 在 **Windows** 上，工作路径是 **Ollama → Vulkan**（ggml）。我们在生产 RX 580 盒子上以这种方式运行卡普里戈代理 - 参见 [docs/AMD.md](docs/AMD.md) 和 [rx580-vulkan-agents](https://github.com/doteyeso-ops/rx580-vulkan-agents)。
**现实选择：
- **Windows + Vulkan:** 目前适用于 Polaris。确认 `ollama ps` 层位于 GPU。
- **Linux + ROCm:** 通常是 gfx803 的死胡同；实验性覆盖是脆弱的。
- **优化拟合：** 较小的 / Q4 模型，较低的 `num_ctx`，较高的 `num_gpu` / 层卸载，一个模型加载。
- **支持路径：** 柠檬水 / Ryzen AI Halo / Radeon+ROCm，用于相同的卡普里戈循环，具有更多余量。
4. **从卡普里戈网关（可选）：** 设置 **`CAPRIGO_OLLAMA_NUM_GPU`**，以便请求包含 Ollama 的 **`num_gpu`**（卸载的层数 - 不是“GPU 索引”）。示例：尝试 **`99`** 或 **`-1`**，如果您的 Ollama 版本接受“最大层”（检查服务器日志 / `ollama ps`）。 **`CAPRIGO_OLLAMA_NUM_THREAD`** 设置 CPU 线程数，用于保持在 CPU 上的层。这仅在 **Ollama 主机** 已经具有有效的 GPU 后端时有所帮助；它不会为不支持的卡添加 ROCm 支持。
## 环境
使用 **`CAPRIGO_*`** 变量。运行时还通过 `@caprigo/shared` 中的 `caprigoEnv()` 读取较旧的单一产品环境名称，因此现有安装保持正常工作。
- `PORT` — 网关端口（默认：18789）
- `OLLAMA_URL` 或 `CAPRIGO_OLLAMA_URL` — Ollama API URL（默认：http://localhost:11434）。对于另一台机器上的 Ollama，例如 `http://172.29.176.1:11434`（该主机必须在 `0.0.0.0:11434` 或您的 LAN IP 上提供 Ollama，而不仅仅是 `127.0.0.1`）。参见 `.env.example`。
- `CAPRIGO_OLLAMA_TIMEOUT_MS` — 网关每次 **`/api/chat`** 调用（默认 **600000** 毫秒）。每个工具轮次都是一个单独的调用；如果聊天在运行缓慢的 CPU/GPU 上中止，请提高此值。
- `CAPRIGO_OPENAI_CHAT_TIMEOUT_MS` — OpenAI 兼容聊天的类似想法（默认 **600000** 毫秒）。
- `CAPRIGO_OLLAMA_NUM_GPU` / `CAPRIGO_OLLAMA_NUM_THREAD` — 可选；转发到 Ollama 聊天 **`options`**（GPU 层卸载 + CPU 线程）。参见上面的 *Ollama GPU*。
- `CAPRIGO_LLM_PROVIDER` — `ollama`（默认）或 OpenAI 兼容
- `CAPRIGO_PROGRAM_GUIDE_MAX_CHARS` — 从 `CAPRIGO_LLM_GUIDE.md` 或配置的全局指南路径注入的最大字符数（默认 **16000**）。
- `CAPRIGO_AGENT_INSTRUCTIONS_MAX_CHARS` — 从每会话 Markdown 指令文件中注入的最大字符数（默认 **24000**）。
- `CAPRIGO_INLINE_INSTRUCTIONS_MAX_CHARS` — 从内联会话 Markdown 指令中注入的最大字符数（默认 **12000**）。
- `CAPRIGO_HISTORY_RECENT_MESSAGES` — 在提示历史记录中保留的最新用户/助手回合数，在较旧的回合被压缩成摘要之前（默认 **12**）。
- `CAPRIGO_HISTORY_SUMMARY_MAX_CHARS` — 压缩的“较早对话摘要”块使用的最大字符数（默认 **6000**）。
- `CAPRIGO_TOOL_RESULT_MAX_CHARS` — 馈送到下一个模型步骤的任何工具结果的最大字符数（默认 **4000**）。
- `CAPRIGO_SKILLS_DIR` — 覆盖技能目录
- `CAPRIGO_HOME` — 数据目录根（默认：`~/.caprigo`，如果存在较旧的点目录，则进行迁移）
- `DEFAULT_MODEL` — 模型名称
- `MIROFISH_URL` — MiroFish 后端 URL（默认：http://localhost:5001）
