raphaelmansuy/edgecrab

# EdgeCrab 🦀 [](LICENSE) [](https://www.rust-lang.org/) [](https://crates.io/crates/edgecrab-cli) [](https://pypi.org/project/edgecrab-cli/) [](https://www.npmjs.com/package/edgecrab-cli) [](https://github.com/raphaelmansuy/edgecrab/actions/workflows/ci.yml) [](https://www.edgecrab.com) [](CHANGELOG.md) EdgeCrab 是一个 **SuperAgent** —— 一个用 Rust 锻造的个人助理和编码代理。它承载了 **Nous Hermes Agent** 的灵魂（自主推理、持久记忆、用户优先对齐）以及 **OpenClaw** 的常驻存在（17 条消息网关、智能家居集成），被打包为一个约 **49 MB** 的原生发行二进制文件，适用于当前 macOS arm64 构建，零 Python 或 Node.js 运行时依赖。适用于 Linux、macOS 和 Android（Termux）。 ## 架构  ``` hermes-agent soul + OpenClaw vision = EdgeCrab (reasoning) (presence) (Rust) ``` | 指标 | EdgeCrab 🦀 | hermes-agent ☤ | | --- | --- | --- | | 二进制文件 | ~49 MB 剥离后的发行构建 | Python venv + uv | | 运行时引导 | 无 | Python + uv | | 内存 | 工作负载相关的原生进程 | ~80–150 MB | | LLM 提供商 | 15 个内置 | 可变 | | 消息平台 | 17 个网关 | 7 个平台 | | 测试 | 1629 个通过的测试（Rust） | — | | 从 hermes 迁移 | `edgecrab migrate` | 不适用 |  ## 目录 - [EdgeCrab 🦀](#edgecrab-) - [架构](#architecture) - [目录](#table-of-contents) - [为何选择 EdgeCrab？](#why-edgecrab) - [快速启动（90 秒）](#quick-start-90-seconds) - [选项 A — npm（无需 Rust）](#option-a--npm-no-rust-required) - [选项 B — pip（无需 Rust）](#option-b--pip-no-rust-required) - [选项 C — cargo](#option-c--cargo) - [选项 D — 从源码构建](#option-d--build-from-source) - [引导设置输出](#guided-setup-output) - [首次提示](#first-prompts) - [EdgeCrab 能做什么](#what-edgecrab-can-do) - [ReAct 工具循环](#react-tool-loop) - [内置工具](#built-in-tools) - [语义代码智能（LSP）](#semantic-code-intelligence-lsp) - [文件工具（`file` 工具集）](#file-tools-file-toolset) - [终端工具（`terminal` 工具集）](#terminal-tools-terminal-toolset) - [Web 工具（`web` 工具集）](#web-tools-web-toolset) - [浏览器工具（`browser` 工具集）](#browser-tools-browser-toolset) - [内存与 Honcho 工具（`memory` + `honcho` 工具集）](#memory--honcho-tools-memory--honcho-toolsets) - [技能工具（`skills` 工具集）](#skills-tools-skills-toolset) - [会话与搜索（`session` 工具集）](#session--search-session-toolset) - [委托与 MoA（`delegation` + `moa` 工具集）](#delegation--moa-delegation--moa-toolsets) - [代码执行（`code_execution` 工具集）](#code-execution-code_execution-toolset) - [MCP 工具（`mcp` 工具集）](#mcp-tools-mcp-toolset) - [媒体工具（`vision` / `tts` / `transcribe` 工具集）](#media-tools-vision--tts--transcribe-toolsets) - [自动化工具](#automation-tools) - [子代理委托](#sub-agent-delegation) - [沙箱代码执行](#sandboxed-code-execution) - [浏览器自动化](#browser-automation) - [17 条消息网关](#17-messaging-gateways) - [持久化内存与学习](#persistent-memory--learning) - [技能库](#skills-library) - [技能与插件](#skills-vs-plugins) - [插件系统](#plugin-system) - [Cron 调度](#cron-scheduling) - [检查点与回滚](#checkpoints--rollback) - [配置文件与工作树](#profiles--worktrees) - [视觉、TTS 与转录](#vision-tts--transcription) - [15 个 LLM 提供商](#15-llm-providers) - [6 个终端后端](#6-terminal-backends) - [MCP 服务器集成](#mcp-server-integration) - [ACP / VS Code Copilot 集成](#acp--vs-code-copilot-integration) - [ratatui TUI](#ratatui-tui) - [所有 CLI 命令](#all-cli-commands) - [所有斜杠命令](#all-slash-commands) - [安全模型](#security-model) - [架构](#architecture-1) - [配置](#configuration) - [SDK](#sdks-one-edgecrab-experience) - [Python SDK（`edgecrab`）](#python-sdk-edgecrab) - [Node.js SDK（`edgecrab`）](#nodejs-sdk-edgecrab) - [Docker](#docker) - [从 hermes-agent 迁移](#migrating-from-hermes-agent) - [测试](#testing) - [项目结构](#project-structure) - [需求与构建](#requirements--build) - [贡献](#contributing) - [发布渠道](#release-channels) - [许可证](#license) ## 为何选择 EdgeCrab？ 大多数 AI 代理要么过于受限（会话结束后就忘记你的存在），要么过于臃肿（Python 运行时、Node 守护进程、GB 级内存）。EdgeCrab 与它们不同。 **它会学习。** 像 Nous Hermes Agent 一样，EdgeCrab 在会话之间保持持久记忆，自动生成可复用的技能，并构建一个跨会话的 Honcho 用户模型，随时间推移变得更智能。 **它无处不在。** 像 OpenClaw 一样，EdgeCrab 存在于你的频道中 —— Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost、DingTalk、SMS、Email、Home Assistant 等更多平台。给它在 WhatsApp 上发送一条语音备忘录，它会返回一个 PR。 **它快速且精简。** 与 Python 代理不同，EdgeCrab 以原生 Rust 二进制文件的形式分发，而不是 Python 或 Node.js 运行时堆栈。当前剥离后的 macOS arm64 发行构建约为 49 MB，安全功能内置于编译时 —— 路径沙箱、SSRF 防护、命令扫描 —— 而不是运行时补丁。 **它可扩展。** 提供 MCP 服务器、自定义 Rust 工具、Python/JS 沙箱、子代理、混合智能体共识 —— 完整的重型自动化工具包。 **它现在是插件原生。** 技能插件注入提示专业知识，工具服务器插件暴露外部 JSON-RPC 工具，脚本插件运行安全的 Rhai 逻辑，全部来自 `~/.edgecrab/plugins/`，并带有持久化的启用/禁用策略。 ## 快速启动（90 秒） ### 选项 A — npm（无需 Rust ``` npm install -g edgecrab-cli edgecrab update # channel-aware updater edgecrab setup # interactive wizard — detects API keys, writes config edgecrab doctor # verify health edgecrab # launch TUI ``` ### 选项 B — pip（无需 Rust） ``` pip install edgecrab-cli # OR: pipx install edgecrab-cli (isolated install) edgecrab update edgecrab setup && edgecrab doctor && edgecrab ``` ### 选项 C — cargo ``` cargo install edgecrab-cli edgecrab update --check edgecrab setup && edgecrab doctor && edgecrab ``` ### 选项 D — 从源码构建 ``` git clone https://github.com/raphaelmansuy/edgecrab cd edgecrab cargo build --workspace --release # ~30 s first build ./target/release/edgecrab setup ``` ### 引导设置输出 ``` EdgeCrab Setup Wizard ────────────────────────────────────────────────────────────── ✓ Detected GitHub Copilot (GITHUB_TOKEN) ✓ Detected OpenAI (OPENAI_API_KEY) Choose LLM provider: [1] copilot (GitHub Copilot — GPT-5 / Claude / Gemini catalog) ← auto-detected [2] openai (OpenAI — GPT-4.1, GPT-5, o3/o4) [3] anthropic (Anthropic — Claude Opus 4.6) [4] ollama (local — llama3.3) ... Provider [1]: 1 ✓ Config written to ~/.edgecrab/config.yaml ✓ Created ~/.edgecrab/memories/ ✓ Created ~/.edgecrab/skills/ Run `edgecrab` to start chatting! ``` ### 首次提示 ``` edgecrab "summarise the git log for today and open PRs" edgecrab --model openai/gpt-5 "review this codebase for security issues" edgecrab --model ollama/llama3.3 "explain this code offline" edgecrab --quiet "count lines in src/**/*.rs" # pipe-safe, no banner edgecrab -C "continue-my-refactor" # resume named session edgecrab -w "explore that perf idea" # isolated git worktree ``` ## EdgeCrab 能做什么 EdgeCrab 是一个自主代理。给它一个自然语言目标；它会推理、调用工具、观察结果并循环，直到任务完成。以下是它实际能够触及的范围。 ### ReAct 工具循环 EdgeCrab 使用 **推理 → 行动 → 观察** 循环（ReAct 模式），实现于 `crates/edgecrab-core/src/conversation.rs`。每一轮： 1. **系统提示在会话中仅构建一次**（SOUL.md、AGENTS.md、记忆、技能、日期/时间、当前工作目录）——缓存以供 Anthropic 提示缓存命中 2. **LLM 决定下一步要做什么**（包括并行工具调用） 3. **安全检查在每次工具执行前运行**（路径沙箱、SSRF 防护、命令扫描） 4. **工具执行** —— 文件 I/O、Shell、网络、代码、子代理、浏览器等 5. **结果注入回上下文** 6. **循环** 直到没有更多工具调用（任务完成）、`Ctrl-C` 或 90 次迭代预算耗尽 7. **上下文压缩** 在达到上下文窗口的 50% 时触发 —— 修剪旧的工具输出，然后由 LLM 总结 8. **学习反思** 在 ≥5 次工具调用后自动触发 —— 代理可以保存新技能并更新记忆 预算默认值为 **90 次迭代**（配置中的 `max_iterations`）。对于长时间自主任务，可以增加该值。 ### 内置工具 工具在编译时通过 `inventory` crate 注册 —— 启动开销为零。`ToolRegistry` 通过精确名称分发，并带有模糊（Levenshtein ≤3）回退建议。 ### 语义代码智能（LSP） EdgeCrab 现在通过 `lsp` 工具集公开专用的 LSP 子系统。当配置了语言服务器时，代理可以优先执行语义操作而非基于 grep 的猜测： - Claude 兼容导航：`lsp_goto_definition`、`lsp_find_references`、`lsp_hover`、`lsp_document_symbols`、`lsp_workspace_symbols`、`lsp_goto_implementation`、`lsp_call_hierarchy_prepare`、`lsp_incoming_calls`、`lsp_outgoing_calls` - EdgeCrab 专属语义编辑：`lsp_code_actions`、`lsp_apply_code_action`、`lsp_rename`、`lsp_format_document`、`lsp_format_range` - 深度分析：`lsp_inlay_hints`、`lsp_semantic_tokens`、`lsp_signature_help`、`lsp_type_hierarchy_prepare`、`lsp_supertypes`、`lsp_subtypes` - 诊断：`lsp_diagnostics_pull`、`lsp_linked_editing_range`、`lsp_enrich_diagnostics`、`lsp_select_and_apply_action`、`lsp_workspace_type_errors` 内置默认服务器定义现已覆盖 Rust、TypeScript、JavaScript、Python、Go、C、C++、Java、C#、PHP、Ruby、Bash、HTML、CSS 和 JSON。 #### 文件工具（`file` 工具集） | 工具 | 功能 | | --- | --- | | `read_file` | 读取文件（支持 `start_line`/`end_line`）——路径沙箱、规范化 | | `write_file` | 写入或创建文件（自动创建父目录） | | `patch_file` | 精确字符串匹配的搜索替换补丁，原子写入 | | `search_files` | 在目录树中进行正则表达式 + Glob 搜索 | #### 终端工具（`terminal` 工具集） | 工具 | 功能 | | --- | --- | | `terminal` | 执行 Shell 命令 —— 每个任务独立的持久 Shell，环境变量黑名单 | | `manage_process` | 启动/停止/列出/杀死/读取后台进程 | #### Web 工具（`web` 工具集） | 工具 | 功能 | | --- | --- | | `web_search` | 通过 Firecrawl → Tavily → Brave → DuckDuckGo 备用链进行网络搜索 | | `web_extract` | 全页提取 —— HTML 剥离 + PDF 解析（EdgeParse）—— SSRF 防护 | #### 浏览器工具（`browser` 工具集） | 工具 | 功能 | | --- | --- | | `browser_navigate` | 通过 CDP 导航 Chrome | | `browser_snapshot` | 可访问性树快照（非像素）——LLM 可推理页面结构 | | `browser_click` | 根据快照中的 `@eN` 引用 ID 点击元素 | | `browser_type` | 向聚焦输入框键入文本 | | `browser_screenshot` | 带编号元素覆盖层的注释截图 | | `browser_console` | 捕获/清除浏览器控制台日志 | #### 内存与 Honcho 工具（`memory` + `honcho` 工具集） | 工具 | 功能 | | --- | --- | | `memory_read` | 读取 `MEMORY.md` 和 `USER.md`（来自 `~/.edgecrab/memories/`） | | `memory_write` | 写入/追加到内存文件（提示注入扫描） | | `honcho_profile` | 通过 Honcho 跨会话模型获取/设置用户画像事实 | | `honcho_context` | 为当前任务检索相关的 Honcho 记忆 | #### 技能工具（`skills` 工具集） | 工具 | 功能 | | --- | --- | | `skill_manage` | 创建、查看、打补丁、删除、列出技能 | #### 会话与搜索（`session` 工具集） | 工具 | 功能 | | --- | --- | | `session_search` | 使用 SQLite FTS5 对所有过往会话进行全文搜索 | #### 委托与 MoA（`delegation` + `moa` 工具集） | 工具 | 功能 | | --- | --- | | `delegate_task` | 分叉子代理 —— 单任务或最多 3 个并行任务 | | `mixture_of_agents` | 通过 Claude Opus 4.6、Gemini 2.5 Pro、GPT-4.1、DeepSeek R1 运行并行任务；综合共识 | #### 代码执行（`code_execution` 工具集） | 工具 | 功能 | | --- | --- | | `execute_code` | 沙箱化的 Python / JS / Bash / Ruby / Perl / Rust 执行，带工具 RPC | #### MCP 工具（`mcp` 工具集） | 工具 | 功能 | | --- | --- | | `mcp_list_tools` | 列出所有连接的 MCP 服务器提供的工具 | | `mcp_call_tool` | 调用任意连接的 MCP 服务器上的命名工具 | #### 媒体工具（`vision` / `tts` / `transcribe` 工具集） | 工具 | 功能 | | --- | --- | | `vision_analyze` | 通过多模态模型（Claude、GPT-4o、Gemini）分析图像（URL 或本地路径） | | `text_to_speech` | 文本转语音（OpenAI TTS 或配置提供者） | | `transcribe_audio` | 转录音频文件（Whisper、Groq Whisper、OpenAI Whisper） | #### 自动化工具 | 工具 | 功能 | | --- | --- | | `manage_todo_list` | 结构化待办事项 —— 创建、更新、完成、删除条目 | | `manage_cron_jobs` | 安排周期性或一次性定时任务 | | `checkpoint` | 文件系统快照用于回滚（创建、列出、恢复、差异） | | `clarify` | 向用户提问（可带选项）——不阻塞循环 | | `send_message` | 通过网关向任意连接平台发送消息 | | `ha_get_states` | 获取 Home Assistant 实体状态 | | `ha_call_service` | 调用 HA 服务（例如 `light.turn_on`） | | `ha_trigger_automation | 触发 HA 自动化 | | `ha_get_history` | 获取 HA 实体历史记录 | **控制哪些工具集处于活动状态：** ``` edgecrab --toolset file,terminal "add tests" # minimal dev edgecrab --toolset all "go wild" # full capability edgecrab --toolset coding "refactor this module" # file+terminal+search+exec+lsp edgecrab --toolset research "investigate this bug" # web+browser+vision ``` ### 子代理委托 EdgeCrab 可以生成运行完整 ReAct 循环的子代理，拥有独立会话状态。这实现了并行处理复杂任务。 ``` # Example: agent delegates 3 subtasks in parallel delegate_task([ { task: "Review auth module for security issues" }, { task: "Write unit tests for the payment service" }, { task: "Update API documentation" } ]) # → 3 sub-agents run concurrently, results aggregated ``` **工作原理**（`crates/edgecrab-tools/src/tools/delegate_task.rs`）： - 子代理共享 LLM 提供者 Arc + 工具注册表 Arc - 每个子代理拥有独立的 `SessionState`、`ProcessTable`、`TodoStore`、`IterationBudget` - 最大并发：**3 个子代理**（可通过 `delegation.max_subagents` 配置） - 最大深度：**2 层**（父代理 → 子代理 → 孙子代理被阻止） - 子代理无法使用 `delegation`、`clarify`、`memory`、`code_execution` 或 `messaging` 工具集 配置委托： ``` delegation: enabled: true model: "openai/gpt-4o" # use a capable shared model for sub-agents max_subagents: 3 max_iterations: 50 ``` ### 沙箱代码执行 `execute_code` 工具在具有严格资源限制的隔离子进程中运行代码： - **语言**：Python、JavaScript、Bash、Ruby、Perl、Rust - **工具 RPC**：脚本可通过 Unix 域套接字调用 7 个工具 —— `web_search`、`web_extract`、`read_file`、`write_file`、`search_files`、`terminal`、`session_search` - **限制**：50 次工具调用上限，5 分钟超时，50 KB 标准输出上限，10 KB 标准错误上限 - **安全**：执行前从子环境剥离 API 密钥/令牌 ``` # Example: agent writes and executes this in a sandbox import subprocess result = subprocess.run(['cargo', 'test', '-p', 'edgecrab-core'], capture_output=True) print(result.stdout.decode()) ``` ### 浏览器自动化 基于 Chrome DevTools Protocol 的浏览器自动化 —— 无需 Selenium 或 Playwright 依赖。EdgeCrab 直接连接到 CDP 端点。 ``` Requirements: Chrome/Chromium binary, or set CDP_URL to an existing instance Check: edgecrab doctor (reports browser availability) ``` `browser_snapshot` 工具返回可访问性树（非像素），因此 LLM 可在不产生视觉成本的情况下推理页面结构。`browser_screenshot` 添加带编号元素覆盖层的截图以便精确点击。 ### 17 条消息网关 启动网关服务器后，EdgeCrab 可同时在 17 个消息平台中作为常驻助理： ``` edgecrab gateway start # runs in background edgecrab gateway start --foreground # keep in foreground edgecrab gateway status # check which platforms are live edgecrab gateway stop ``` | 平台 | 传输方式 | 认证 | | --- | --- | --- | | **Telegram** | 长轮询 REST | `TELEGRAM_BOT_TOKEN` | | **Discord** | WebSocket 网关 | `DISCORD_BOT_TOKEN` | | **Slack** | Socket Mode WebSocket | `SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` | | **WhatsApp** | Baileys 桥接（本地 Node 子进程） | `edgecrab whatsapp` QR 配对 | | **Signal** | signal-cli HTTP + SSE | `SIGNAL_HTTP_URL` + `SIGNAL_ACCOUNT` | | **Matrix** | 客户端-服务器 REST + 长轮询同步 | `MATRIX_HOMESERVER` + `MATRIX_ACCESS_TOKEN` | | **Mattermost** | REST v4 + WebSocket | `MATTERMOST_URL` + `MATTERMOST_TOKEN` | | **DingTalk** | Stream SDK（无公开 Webhook） | `DINGTALK_APP_KEY` + `DINGTALK_APP_SECRET` | | **SMS** | Twilio REST v2010 | `TWILIO_ACCOUNT_SID` + `TWILIO_AUTH_TOKEN` | | **Email** | SMTP（lettre、rustls）+ 入站 Webhook | `EMAIL_PROVIDER` + `EMAIL_FROM` + `EMAIL_API_KEY` | | **Home Assistant** | WebSocket + REST | `HASS_URL` + `HASS_TOKEN` | | **Webhook** | axum HTTP POST | 任意 HTTP 调用方 | | **API 服务器** | axum OpenAI 兼容 HTTP | `API_SERVER_PORT`（可选） | | **Feishu/Lark** | REST | `FEISHU_APP_ID` + `FEISHU_APP_SECRET` | | **WeCom** | WebSocket + REST + 心跳 | `WECOM_BOT_ID` + `WECOM_SECRET` | | **iMessage** | BlueBubbles REST + Webhook + 附件 | `BLUEBUBBLES_SERVER_URL` + `BLUEBUBBLES_PASSWORD` | | **WeChat** | iLink Bot API POST 轮询 + AES CDN 媒体 | `WEIXIN_TOKEN` + `WEIXIN_ACCOUNT_ID` | **流式交付**：编辑模式平台（Telegram、Discord、Slack）接收带 300ms 编辑间隔的实时令牌流。批处理平台（WhatsApp、Signal、SMS、Email）累积完整响应后一次性发送。 **内置网关斜杠命令**（通过聊天发送）： ``` /help /new /reset /stop /retry /status /usage /background /approve /deny ``` **设置 WhatsApp**（一次性 QR 配对）： ``` edgecrab whatsapp # launches QR code scanner wizard # Scan with your phone — session persists across restarts edgecrab gateway start ``` **定时触发消息**：安排代理主动向你发送消息： ``` # ~/.edgecrab/cron/daily-standup.json schedule: "0 9 * * 1-5" # every weekday at 9am task: "Summarize open PRs and blockers for today's standup" target: telegram # deliver to your Telegram ``` ## 持久化内存与学习 EdgeCrab 拥有一个三层内存系统： **第一层 — MEMORY.md**（`~/.edgecrab/memories/MEMORY.md`）：自由格式笔记。代理在会话开始时读取此文件，并可更新它。你也可以直接编辑它。 **第二层 — SQLite 会话历史**（`~/.edgecrab/state.db`）：所有会话以 WAL 模式 SQLite 存储，并带有 FTS5 全文搜索。浏览、搜索并导出会话： ``` edgecrab sessions list # list recent sessions edgecrab sessions search "auth bug from last week" # FTS5 search edgecrab sessions export --format jsonl # export session edgecrab sessions browse # interactive browser ``` **第三层 — Honcho 跨会话用户模型**：EdgeCrab 通过 Honcho API 构建你的语义化用户画像 —— 你的偏好、项目、工作风格。此上下文在新建会话时注入，以提供连续性。 **自动学习**：在会话中 ≥5 次工具调用后，学习反思会自动触发。代理可以保存新技能、更新 MEMORY.md，并记录有用模式，而无需人工请求。 ## 技能库 技能是可重用的代理流程 —— 定义了提示、步骤和最佳实践的 Markdown 文件。可以把它们想象成给代理的“食谱卡片”。 ``` # Create a skill edgecrab skills list # browse installed skills edgecrab skills view git-workflow # read a skill edgecrab skills install my-skill.md # install from file edgecrab skills search "diagram" # search remote skill sources edgecrab skills install edgecrab:diagramming/ascii-diagram-master edgecrab skills install hermes-agent:research/ml-paper-writing edgecrab skills install raphaelmansuy/edgecrab/skills/research/ml-paper-writing edgecrab skills update # refresh all remote-installed skills edgecrab skills update ml-paper-writing # Use a skill in a session edgecrab -S git-workflow "review this branch for prod readiness" edgecrab -S security,refactor # load multiple skills ``` 在 TUI 中：`/skills` 打开已安装技能的浏览器，`/skills search [query]` 打开远程技能浏览器，支持实时搜索、来源注释以及安装/更新操作。 技能保存在 `~/.edgecrab/skills/` 中，并在需要时加载。代理还可以在学习反思期间动态创建新技能。 支持 Claude 风格的技能包，其中包含辅助文件： - `references/`、`templates/`、`scripts/` 和 `assets/` 下的辅助文件 - `${CLAUDE_SKILL_DIR}` 替换为实际技能目录 - `${CLAUDE_SESSION_ID}` 替换为当前 EdgeCrab 会话 ID - 对 `skill_view` 和预加载的 `--skill` / `skills.preloaded` 流程使用相同的包渲染 - 解析并显示 `when_to_use`、`arguments`、`argument-hint`、`allowed-tools`、`user-invocable`、`disable-model-invocation`、`context` 和 `shell` 当前边界：EdgeCrab 不会自动执行 Claude 内联提示 Shell 块，也不会自动派生专用的技能子代理，仅根据这些元数据字段。 ### 技能与插件 首先原则： - **技能** 是对模型的重复性指导。 - **插件** 是可安装运行时单元，EdgeCrab 会发现、启用、禁用、更新并审核它们。 由此产生清晰的运行分离： - 当扩展是 **指令优先** 时使用 `skills` —— 流程、示例、检查清单，或捆绑辅助文件/脚本，代理通过正常工具使用它们。 - 当扩展需要 **可执行代码**、工具注册、钩子、就绪性检查、信任元数据或安装生命周期管理时使用 `plugins`。 - 单纯的技能会改变提示行为。它可以捆绑辅助文件（如 `scripts/`、`references/`、`templates/` 和 `assets/`），但本身不会注册新的运行时服务或插件生命周期。 - 插件可以捆绑 `SKILL.md`，但该捆绑技能仍是插件管理的运行时包的一部分。 具体示例： - `~/.edgecrab/skills/security-review/SKILL.md` 是一个独立技能。 - `~/.edgecrab/skills/security-review/scripts/check.py` 可以与该技能，并通过 `SKILL.md` 引用。 - `~/.edgecrab/plugins/github-tools/plugin.toml` 是一个插件。 - `~/.edgecrab/plugins/calculator/plugin.yaml` 加 `__init__.py` 是 Hermes 插件。 - 种类为 `skill` 的插件仍通过 `edgecrab plugins ...` 管理，而非 `edgecrab skills ...`。 ## 插件系统 插件在不 fork 仓库的情况下扩展 EdgeCrab 超出内置工具库存。 ``` edgecrab plugins list edgecrab plugins info github-tools edgecrab plugins status edgecrab plugins install github:edgecrab/plugins/github-tools edgecrab plugins install hub:community/github-tools edgecrab plugins install https://example.com/github-tools.zip edgecrab plugins install ./plugins/github-tools edgecrab plugins enable github-tools edgecrab plugins disable github-tools edgecrab plugins toggle [github-tools] edgecrab plugins audit --lines 20 edgecrab plugins search github edgecrab plugins search --source hermes weather edgecrab plugins search --source hermes-evey telemetry edgecrab plugins browse edgecrab plugins update edgecrab plugins remove github-tools ``` 在 TUI 中，`/plugins search ...` 和 `/plugins browse` 现在打开相同的 异步远程浏览器，EdgeCrab 已用于技能和 MCP： 模糊过滤、后台搜索、分屏详细视图，以及一键安装或 从官方注册表替换。 EdgeCrab 现在支持四种插件类型： - `skill` 插件将 `SKILL.md` 内容从 `~/.edgecrab/plugins//` 加载到会话提示中，并带有 Hermes 兼容的前置元数据、就绪性检查以及平台过滤。 - `tool-server` 插件派生子进程，并通过 stdio 代理与 MCP 兼容的换行符分隔的 JSON-RPC，包括反向 `host:*` 调用以获取平台信息、内存/会话访问、密钥读取、安全会话消息注入、日志记录和委托工具执行。 - `script` 插件加载用于轻量级本地扩展的 Rhai 代码，而无需单独运行守护进程。 - `hermes` 插件加载 Hermes 风格的 Python 目录插件，包含 `plugin.yaml` + `__init__.py register(ctx)` 兼容性，包括 `requires_env` 设置门控、捆绑的 `SKILL.md` 加载、`post_tool_call`、`on_session_start`、`pre_llm_call` 和 `on_session_end`。 EdgeCrab 还会发现 `~/.hermes/plugins/` 下的遗留 Hermes 插件根目录，以及在 `HERMES_ENABLE_PROJECT_PLUGINS=true` 时的 `./.hermes/plugins/`。插件安装现在会进行隔离暂存、运行静态安全扫描、解析来源信任，并在 `plugin.toml` 中盖章目录校验和后再激活。插件状态持久化在 `config.yaml` 的 `plugins:` 下。禁用或设置需要的插件会从工具暴露或提示注入中排除，而无需卸载它们。 运行时暴露是实时的： - 已启用的插件工具会注册到 `plugins` 工具集中，并出现在 `/tools` - 禁用插件会将其工具从活动注册表中移除，无需重启 EdgeCrab - 重新启用插件会立即在同一 TUI 会话中重新暴露这些工具 在 TUI 中可以直接验证： ``` /plugins # open the installed-plugin browser overlay /tools # shows active built-in + plugin tools /plugins disable demo /tools # demo plugin tools are gone /plugins enable demo /tools # demo plugin tools are back under the plugins toolset ``` 远程插件搜索会基于第一原则进行缓存： - hub 索引和仓库支持的源树缓存在 `~/.edgecrab/plugins/.hub/cache/` - 仓库支持的插件描述单独缓存，这样重复搜索不会重新获取 `plugin.yaml` 或 `SKILL.md` - 过期缓存会刷新，但刷新失败时仍会使用陈旧缓存，这样插件搜索在失败时会优雅降级而非返回空 示例：安装一个 Hermes 风格指南式本地插件并捆绑技能： ``` calculator/ ├── plugin.yaml ├── __init__.py ├── schemas.py ├── tools.py ├── SKILL.md └── data/ └── units.json ``` ``` edgecrab plugins install ./calculator edgecrab plugins info calculator edgecrab plugins status ``` 本仓库还提供了官方 Hermes 格式示例，并由 `edgecrab-official` 搜索源索引： ``` edgecrab plugins search --source edgecrab calculator edgecrab plugins search --source edgecrab json edgecrab plugins install ./plugins/productivity/calculator edgecrab plugins install ./plugins/developer/json-toolbox edgecrab plugins info calculator edgecrab plugins info json-toolbox ``` 这些示例证明了两种不同的 Hermes 运行时接口： - `plugins/productivity/calculator` 注册工具以及 `post_tool_call` 钩子 - `plugins/developer/json-toolbox` 注册工具以及顶级 CLI 命令 示例：从本地克隆的 `NousResearch/hermes-agent` 直接安装真实的 Hermes 资源： ``` edgecrab plugins install ~/src/hermes-agent/plugins/memory/holographic edgecrab plugins info holographic # pip entry-point plugins are discovered through the selected Python runtime EDGECRAB_PLUGIN_PYTHON=~/.venvs/hermes/bin/python \ edgecrab plugins list EDGECRAB_PLUGIN_PYTHON=~/.venvs/hermes/bin/python \ edgecrab entry-demo status ``` 独立 Hermes 技能从技能界面浏览，而不是插件浏览器： ``` edgecrab skills search 1password edgecrab skills install hermes-agent:security/1password ``` 示例：从 `42-evey/hermes-plugins` 搜索并安装经过整理的社区 Hermes 插件： ``` edgecrab plugins search --source hermes-evey telemetry edgecrab plugins install hub:hermes-evey/evey-telemetry edgecrab plugins install hub:hermes-evey/evey-status edgecrab plugins info evey-telemetry ``` 有关分步编写指南，请参阅 `docs/007_memory_skills/005_building_hermes_style_plugins.md` 和站点指南 `site/src/content/docs/guides/build-hermes-plugin.md`。 兼容性证明目前涵盖： - 官方仓库 Hermes 示例 `calculator` 和 `json-toolbox`，包括搜索可见性和端到端本地安装/运行时验证 - 指南式 Hermes 插件安装和端到端工具执行 - 真实的 Hermes 插件安装和运行时执行（`holographic`） - 真实的 Hermes 可选技能兼容性（`1password` 通过本地捆绑安装） - 真实的 Python 导入/运行时 shim 以及 `cli.py register_cli(subparser)` CLI 桥接（`honcho`） - 真实的 `42-evey/hermes-plugins` 运行时执行（`evey-telemetry` 和 `evey-status`） - 通过 pip 的入口点发现以及顶级 Hermes CLI 命令执行（通过 `ctx.register_cli_command()`） - Hermes hub 索引用于上游 `plugins/...` 目录和 `42-evey` 仓库根目录下的 Hermes 目录 - Hermes 的完整 `VALID_HOOKS` 表面在 CLI 运行时：`pre_tool_call`、`post_tool_call`、`pre_llm_call`、`post_llm_call`、`pre_api_request`、`post_api_request`、`on_session_start`、`on_session_end`、`on_session_finalize`、`on_session_reset` - 网关每聊天会话隔离以及会话边界对 `on_session_start`、`on_session_end`、`on_session_finalize` 和 `on_session_reset` 的等价性证明 ## Cron 调度 安排周期性或一次性任务： ``` edgecrab cron list edgecrab cron add "0 9 * * 1-5" "Summarize open PRs for standup" edgecrab cron add "@daily" "Update MEMORY.md with project progress" edgecrab cron pause edgecrab cron resume edgecrab cron remove edgecrab cron run # manual trigger edgecrab cron tick # process due jobs (called by system cron) ``` 或在 TUI 会话内： ``` /cron list /cron add "0 18 * * 5" "Generate weekly summary" ``` `manage_cron_jobs` 工具还允许代理自主安排后续任务。 ## 检查点与回滚 在执行破坏性操作之前，EdgeCrab 会创建文件系统快照： ``` # Manual checkpoint edgecrab sessions # → checkpoint auto-created before every file write # Inside TUI /rollback # restore last checkpoint /rollback checkpoint-abc123 # restore specific checkpoint ``` 配置： ``` checkpoints: enabled: true max_snapshots: 50 # keep last 50 checkpoints per session ``` `checkpoint` 工具也提供给代理本身 —— 它可以在执行风险操作前创建快照，并在出错时回滚。 ## 配置文件与工作树 **配置文件** 为 EdgeCrab 提供隔离的运行环境，包含独立的 `config.yaml`、`.env`、`SOUL.md`、内存、技能、插件、钩子、MCP 令牌等。EdgeCrab 现在默认提供三个启动配置文件： `work`、`research` 和 `homelab`。 ``` edgecrab profile list # default + bundled starters edgecrab profile show work edgecrab profile use work # sticky default profile edgecrab -p research "compare SDKs" # one-shot override edgecrab profile alias work --name w edgecrab profile list ``` 启动配置文件示例： ``` # ~/.edgecrab/profiles/work/config.yaml model: default: "openai/gpt-5" max_iterations: 90 display: personality: "technical" tool_progress: "verbose" show_cost: true reasoning_effort: "high" ``` ``` # ~/.edgecrab/profiles/research/config.yaml model: default: "openai/gpt-5" max_iterations: 120 display: personality: "teacher" reasoning_effort: "high" ``` 在 TUI 中，`/profile` 现在镜像 Hermes 并显示当前配置文件名及其有效主目录。`/profiles` 打开交互式浏览器，`/profile show ` 将浏览器定位到特定配置文件。内部操作：`Enter` 切换，`C` 配置，`S` SOUL，`M` 内存，`T` 工具，`A` 别名，`E` 导出，`D` 删除，`N` 创建，`I` 导入，`O` 重命名，`Tab` 或 `←`/`→` 循环详情视图，`Home`/`End` 在结果中跳转。运行时切换是实时的，而不是推迟到下次启动。 **工作树** 为每个代理会话隔离独立的 Git 工作树： ``` edgecrab -w "explore that refactor idea safely" # Creates .worktrees/edgecrab-/ inside the current git repo # Changes stay isolated on an ephemeral branch until you merge or discard them ``` 你也可以在配置中启用始终开启的工作树模式： ``` # ~/.edgecrab/config.yaml worktree: true ``` 在 TUI 中，`/worktree` 打开当前检出状态的报告叠加层以及保存的启动策略，`/worktree on|off|toggle` 更新该默认设置。 `/log` 打开分屏浏览器，用于查看 `~/.edgecrab/logs/`，`Enter` 会深入检查每个条目的尾部。叠加层默认实时跟随，`F` 切换跟随模式，`1-5` 或 `/log level ` 持久化保存默认日志详细级别到 `config.yaml`；当前进程会立即重新加载其过滤器（如果运行时支持日志重载）。 清理是保守设计：EdgeCrab 在退出时移除干净的可丢弃工作树，但会保留包含未推送提交的工作树，以防止代理意外销毁分支本地工作。 ## 视觉、TTS 与转录 ``` # Vision: analyze an image edgecrab "What's in this screenshot?" --attach screenshot.png # TTS: speak the response edgecrab --quiet "Write a haiku about Rust" | say # pipe to macOS say # Or the agent can generate audio directly via text_to_speech tool # Transcription: send a voice note via WhatsApp gateway # → EdgeCrab transcribes it with Whisper and responds ``` 视觉提供者：多模态模型（Claude、GPT-4o、Gemini）。 TTS 提供者：OpenAI TTS、edge-tts（离线）。 转录：Whisper（本地）、Groq Whisper、OpenAI Whisper。 ## 15 个 LLM 提供商 EdgeCrab 开箱即用 15 个 LLM 提供商（13 个云端，2 个本地）。超过 200 个模型已编译在内，用户可通过 `~/.edgecrab/models.yaml` 覆盖。 | 提供商 | 环境变量 | notable 模型 | | --- | --- | --- | | `copilot` | `GITHUB_TOKEN` 或 VS Code 身份验证缓存 | `copilot/auto`、GPT-5 mini、GPT-4.1 —— 由 GitHub Copilot 路由 | | `openai` | `OPENAI_API_KEY` | GPT-4.1、GPT-5、o3、o4-mini | | `anthropic` | `ANTHROPIC_API_KEY` | Claude Opus 4.6、Sonnet 4.6、Haiku 4.5 | | `google` | `GOOGLE_API_KEY` | Gemini 2.5 Pro、Gemini 2.5 Flash | | `vertexai` | `GOOGLE_APPLICATION_CREDENTIALS` | 通过 Google Cloud 的 Gemini | | `xai` | `XAI_API_KEY` | Grok 3、Grok 4 | | `deepseek` | `DEEPSEEK_API_KEY` | DeepSeek V3、DeepSeek R1 | | `mistral` | `MISTRAL_API_KEY` | Mistral Large、Mistral Small | | `groq` | `GROQ_API_KEY` | Llama 3.3 70B、Gemma2 9B（极速推理） | | `huggingface` | `HUGGING_FACE_HUB_TOKEN` | 任何 HF 推理 API 模型 | | `zai` | `ZAI_API_KEY` | Z.AI / GLM 系列 | | `openrouter` | `OPENROUTER_API_KEY` | 通过单一端点访问 600+ 模型 | | `ollama` | （无） | 任意模型 —— `ollama serve` 在 11434 端口 | | `lmstudio` | （无） | 任意模型 —— LM Studio 在 1234 端口 | **随时切换提供商：** ``` edgecrab --model openai/gpt-5 "deep code review" edgecrab --model ollama/llama3.3 "work offline" edgecrab --model groq/llama-3.3-70b-versatile "quick task" ``` **在 TUI 中热切换：** ``` /model groq/llama-3.3-70b-versatile /reasoning high # enable extended thinking (Anthropic/OpenAI) ``` **为何 `copilot/auto` 现在是最佳默认值**：GitHub Copilot 会决定当前会话中可用的聊天能力模型和计费路径，遵循该服务器选择可避免不必要的模型限流，并保持与真实 VS Code 体验一致。 **智能路由**（实验性）：自动根据回合复杂度选择廉价与完整模型： ``` model: smart_routing: enabled: true cheap_model: "groq/llama-3.3-70b-versatile" ``` **混合智能体**：并行运行单个提示到 4 个前沿模型，并综合共识： ``` /model moa # Claude Opus 4.6 + Gemini 2.5 Pro + GPT-4.1 + DeepSeek R1 → aggregated ``` ## 6 个终端后端 `terminal` 工具是可插拔的。选择你的执行环境： | 后端 | 激活方式 | 用途 | | --- | --- | --- | | **本地**（默认） | `EDGECRAB_TERMINAL_BACKEND=local` | 本机上的持久 Shell | | **Docker** | `backend: docker` | 每个任务隔离的容器 | | **SSH** | `backend: ssh` | 通过 ControlMaster 访问远程服务器 | | **Modal** | `backend: modal` | 云沙箱（Modal.com） | | **Daytona** | `backend: daytona` | 持久化云开发沙箱 | | **Singularity** | `backend: singularity` | HPC/Apptainer 带持久化覆盖层 | ``` terminal: backend: docker docker: image: "python:3.12-slim" container_name: "edgecrab-sandbox" ``` ## MCP 服务器集成 EdgeCrab 是一个完整的 MCP（模型上下文协议）客户端。连接任意 MCP 服务器，其工具会自动对代理可用。 ``` # ~/.edgecrab/config.yaml mcp_servers: filesystem: command: "npx" args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp/workspace"] my-api-server: url: "https://my-server.example.com/mcp" bearer_token: "${MY_API_TOKEN}" # env-backed bearer token works enabled: true ``` ``` edgecrab mcp list # show configured MCP servers edgecrab mcp install filesystem --path "/tmp/ws" # install a curated preset edgecrab mcp doctor # static checks + live probe edgecrab mcp doctor filesystem # diagnose one configured server edgecrab mcp remove server-name /mcp # open the TUI MCP browser /reload-mcp # hot-reload in TUI without restart ``` 代理使用 `mcp_list_tools` 和 `mcp_call_tool` 来发现并调用 MCP 服务器功能。 TUI 的 MCP 浏览器支持安装、查看、测试、诊断和移除流程，并且会安全解析 `--path` / `name=` 参数（支持 Unix 和 Windows 风格路径）。 依赖 OAuth 风格承载令牌的 HTTP MCP 服务器可通过以下方式支持： - `bearer_token`、`/mcp-token set ` 或环境变量配置值（如 `bearer_token: "${MY_API_TOKEN}"`） ## ACP / VS Code Copilot 集成 EdgeCrab 实现了 [Agent Communication Protocol](https://github.com/i-am-bee/acp) —— 通过 stdio 的 JSON-RPC 2.0，允许其作为 VS Code Copilot 代理，在 Zed、JetBrains 以及任何 ACP 兼容运行器中运行。 ``` edgecrab acp # starts ACP server on stdin/stdout edgecrab acp init # scaffold agent.json manifest for a workspace ``` `acp_registry/agent.json` 清单声明了扩展发现功能。ACP 适配器使用受限的 `ACP_TOOLS` 子集，排除了交互式专用工具（`clarify`、`send_message`、`text_to_speech`）。 ## ratatui TUI 60 fps 能力、GPU 合成全屏 TUI，基于 [ratatui](https://ratatui.rs/) 构建。 **布局：** ``` ┌────────────────────────────────────────────────────────────┐ │ output area (markdown-rendered, mouse-scrollable) │ │ ⚙ file_read src/main.rs │ │ → 342 lines read │ │ │ │ The `main` function initializes the agent loop and... │ ├────────────────────────────────────────────────────────────┤ │ ● openai/gpt-5 1,234t $0.023 [/commands] │ ├────────────────────────────────────────────────────────────┤ │ ❯ Type your message… │ └────────────────────────────────────────────────────────────┘ ``` **特性：** - 流式输出（逐令牌渲染） - Fish 风格鬼文（类型补全） - Tab 补全斜杠命令（模糊匹配覆盖层） - 多行输入（Shift+Enter 换行） - 鼠标滚动输出区域 - 危险操作确认对话框（内联、非阻塞） - 澄清对话框 —— 代理提问但不阻塞循环 - 密钥请求覆盖层 —— 运行时提示缺失的 API 密钥 - 状态栏显示会话 Spinner、模型名称、Token 数、成本 **主题定制**（`~/.edgecrab/skin.yaml`）： ``` user_fg: "#89b4fa" # Catppuccin blue assistant_fg: "#a6e3a1" # Catppuccin green system_fg: "#f9e2af" # Catppuccin yellow error_fg: "#f38ba8" # Catppuccin red tool_fg: "#cba6f7" # Catppuccin mauve status_bg: "#313244" status_fg: "#cdd6f4" border_fg: "#6c7086" prompt_symbol: "❯" tool_prefix: "⚙" ``` ## 所有 CLI 命令 ``` # Launch edgecrab # interactive TUI edgecrab "prompt here" # TUI + auto-submit edgecrab --quiet "prompt" # no banner, pipe-safe output edgecrab --model p/m "prompt" # specify LLM edgecrab --toolset web,file "p" # restrict toolsets edgecrab --session id "p" # use specific session edgecrab --resume title "p" # resume by title edgecrab -C "p" # continue last session edgecrab -w "p" # isolated git worktree edgecrab -S skill1,skill2 "p" # preload skills # Setup & diagnostics edgecrab setup [--section s] [--force] # interactive wizard edgecrab doctor # full health check edgecrab version # version + providers edgecrab migrate [--dry-run] # import hermes-agent state # Sessions edgecrab sessions list edgecrab sessions browse edgecrab sessions export [--format jsonl] edgecrab sessions delete edgecrab sessions rename