rustyhand (Ginkida)

RustyHand

The Agent Operating System

Open-source Agent OS built in Rust. 124K LOC. 10 crates. 1,577 tests. Zero clippy warnings.

One binary. Autonomous Telegram agent. Agents that actually work for you.

Quick Start • CLI Reference • API Docs

______________________________________________________________________

v0.7.33–v0.7.41--演示模式+持久性+产品抛光（2026年5月） 克隆→ cargo run --release start → 打开仪表板→ 与代理人交谈。 不需要API密钥。 当在环境中找不到提供者密钥时， RustyHand回归到确定性模拟驱动程序，并播种了四个样本 资源，因此每个主要的仪表板页面在首次访问时都是交互式的： - rusty 欢迎代理（聊天就绪） - demo-pipeline 工作流（两步示例，单击运行） - 样本代理生成触发器 - demo-daily-ping cron作业（已注册，默认禁用） 首次访问时的欢迎模式通过一键导航列出了所有四个选项。 CLI启动横幅和Docker入口点都宣布了演示模式 作为一项功能，而不是缺少按键警告。集 ANTHROPIC_API_KEY （或其他26个受支持提供商的环境变量中的任何一个）并重新启动 LLM回复，或 RUSTYHAND_DISABLE_DEMO_MODE=1 迫使失败。 自v0.7.27以来新增： - 审核日志持续存在 --Merkle哈希链位于 ~/.rustyhand/data/audit.jsonl, 在启动时重放并验证。 - 触发器和工作流持续存在 --webhook触发器和管道 定义在守护进程重启后仍然存在，包括微妙的状态，如 max_fires 自动禁用和触发火灾计数。 - 31 API响应形状合同测试 --仪表板上的每个端点 或者CLI读取被固定到其JSON形状，因此服务器端重命名失败 大声CI，而不是产生一个无声的空小部件。 - 6次模拟驾驶员e2e测试 --完整HTTP→ 内核→ 驾驶员→ 结果 管道在CI中运行，而不会燃烧真正的LLM学分，包括代理 消息往返、工作流运行、所有三个CronAction变体，以及 演示模式自动生成流。 - 时间42→ 44 为了 防锈-2026-0114.

______________________________________________________________________

起源

该项目基于 OpenFang 由RightNow AI开发，针对自定义用例进行了修改和扩展。

目录

• RustyHand是什么？
• 安装
• 快速开始
• 电报设置
• 配置
• CLI参考
• 自主模板
• 40个预构建的代理模板
• 通道适配器
• 7 LLM提供商
• 建筑
• API终点
• 仪表板
• 安全
• 部署
• 发展
• 基准测试
• MCP集成（用于AI代理）
• 工作原理——数据流
• 许可证

______________________________________________________________________

RustyHand是什么？

RustyHand是一个 开源代理操作系统 --不是聊天机器人框架，也不是围绕LLM的Python包装器。它是一个完整的自主代理操作系统，用Rust从头开始构建。

传统的代理框架等待您键入内容。RustyHand跑步 为您工作的自主代理 --按计划，24/7，构建知识图，监控目标，生成潜在客户，管理社交媒体，并将结果直接报告给您的 电报聊天.

Telegram第一自主代理

Telegram是RustyHand代理的主要接口。您的代理人可以：

整个系统编译为 单个~32MB二进制文件一个安装，一个命令，你的代理就上线了。

______________________________________________________________________

安装

单行程序（Linux/macOS/WSL）

curl -fsSL https://raw.githubusercontent.com/ginkida/rustyhand/main/scripts/install.sh | sh

环境变量：

• RUSTY_HAND_INSTALL_DIR --自定义安装路径（默认： ~/.rustyhand/bin)
• RUSTY_HAND_VERSION --固定一个特定的版本标签

Windows（PowerShell）

irm https://raw.githubusercontent.com/ginkida/rustyhand/main/scripts/install.ps1 | iex

来源

git clone https://github.com/ginkida/rustyhand.git
cd rustyhand
cargo build --release -p rusty-hand-cli
# Binary: target/release/rustyhand (or rustyhand.exe on Windows)

需要Rust 1.75+（稳定）。这 rust-toolchain.toml 在repo中会自动选择正确的工具链。

码头工人

docker compose up --build
# Dashboard at http://localhost:4200

或者直接使用env-vars运行（不需要config.toml）：

docker run -p 4200:4200 \
  -e ANTHROPIC_API_KEY=your-key \
  -e RUSTYHAND_API_KEY=my-secret-bearer-token \
  -v rustyhand-data:/data \
  ghcr.io/ginkida/rustyhand:latest

所有配置都可以通过以下方式设置 RUSTYHAND_* 环境变量--请参见 .

______________________________________________________________________

快速开始

选项零：30秒后试用，无API密钥

最快的首次运行，无需凭据，无需配置：

git clone https://github.com/ginkida/rustyhand
cd rustyhand
cargo run --release -- start
# In another tab: open http://localhost:4200

仪表板横幅将显示 “演示模式——在确定性上运行 模拟司机。" 生成代理，发送消息，观察代理循环运行， 会话增长，审计日志填满。每个回复都是 [mock] — 毫无疑问是演示，但完整的流程（会话、持久性、工作流、， cron jobs）是真实的。集 ANTHROPIC_API_KEY （或其他26种支持中的任何一种 提供程序的env变量）并重新启动以获得真正的LLM响应。

选项A:Docker（最快）

docker run -d --name rustyhand \
  -p 4200:4200 \
  -e ANTHROPIC_API_KEY=your-key \
  -v rustyhand-data:/data \
  ghcr.io/ginkida/rustyhand:latest

# Dashboard: http://localhost:4200
# API:       http://localhost:4200/api/health

要使用承载令牌保护API，请执行以下操作：

docker run -d --name rustyhand \
  -p 4200:4200 \
  -e ANTHROPIC_API_KEY=your-key \
  -e RUSTYHAND_API_KEY=my-secret-token \
  -v rustyhand-data:/data \
  ghcr.io/ginkida/rustyhand:latest

# Now all API calls require: -H "Authorization: Bearer my-secret-token"

看 对于所有选项。

选项B：从二进制

# 1. Initialize — creates ~/.rustyhand/ and walks you through provider setup
rustyhand init

# 2. Start the daemon (API + kernel)
rustyhand start
# Dashboard is live at http://localhost:4200

# 3. Chat with the default agent
rustyhand chat

# 4. Spawn a pre-built agent
rustyhand agent new coder

# 5. Send a one-shot message
rustyhand message researcher "What are the emerging trends in AI agent frameworks?"

# 6. Launch the interactive TUI dashboard
rustyhand tui

# 7. Run diagnostics
rustyhand doctor

______________________________________________________________________

电报设置

Telegram是 主渠道 用于与RustyHand代理进行交互。安装需要2分钟：

1.创建Telegram Bot

1. 消息 @植物学家 在Telegram上
2. 发送 /newbot，按照提示，获取您的bot令牌
3. 设置令牌： export TELEGRAM_BOT_TOKEN=123456:ABC-DEF...

2.配置RustyHand

# ~/.rustyhand/config.toml
[channels.telegram]
bot_token_env = "TELEGRAM_BOT_TOKEN"
allowed_users = []    # Empty = allow anyone. Set [123456] for specific user IDs.

3.开始聊天

rustyhand start
# Open Telegram, message your bot
# /agents — list agents
# /agent assistant — select an agent
# Send text, photos, voice messages — the agent handles all of them

你的代理人可以在Telegram上做什么

You:     [send a voice message]
Agent:   [auto-transcribes via Whisper, processes your request]

You:     [send a photo]
Agent:   [auto-describes the image, responds based on what it sees]

You:     "Search for Rust 2024 edition changes"
Agent:   ⚙️ web_search...
         ✅ web_search
         Here are the key changes in Rust 2024...

Agent:   ⚠️ Agent "coder" wants to execute:
         `shell_exec: rm -rf /tmp/cache`
         [✅ Approve] [❌ Reject]    ⏱️ 60s

You:     [click ✅ Approve]
Agent:   Done! Cache cleared.

自主模式

代理商与 schedule_mode = "continuous" 或 "periodic" 在后台运行 将结果自动推送到您的Telegram聊天 --不需要提示。

# agent.toml
[schedule]
mode = "periodic"
cron = "0 9 * * *"    # Every day at 9 AM

代理醒来，执行任务，并将结果发送到它上次使用的Telegram聊天。

______________________________________________________________________

配置

RustyHand可以通过两种方式进行配置：

• 配置文件 (~/.rustyhand/config.toml)--用于二进制安装
• 环境变量 (RUSTYHAND_*)--关于Docker，请参阅

API身份验证

当 api_key 已设置，所有端点（除 /api/health)需要一个Bearer令牌：

# In config.toml:
api_key = "my-secret-token"

# Or via env var (Docker):
RUSTYHAND_API_KEY=my-secret-token

# Clients must include the header:
curl -H "Authorization: Bearer my-secret-token" http://localhost:4200/api/agents

没有 api_key，API是开放的（适合本地开发）。

配置文件

地点： ~/.rustyhand/config.toml

# API server settings
api_key = "your-bearer-token"          # Recommended for non-localhost access
api_listen = "127.0.0.1:4200"          # HTTP bind address

[default_model]
provider = "anthropic"                 # anthropic, kimi, deepseek, zhipu, minimax, openrouter, ollama
model = "claude-sonnet-4-20250514"     # Model identifier
api_key_env = "ANTHROPIC_API_KEY"      # Env var holding the API key
# base_url = "https://api.anthropic.com"  # Optional: override endpoint

[memory]
decay_rate = 0.05                      # Memory confidence decay
# sqlite_path = "~/.rustyhand/data/rustyhand.db"

[network]
listen_addr = "127.0.0.1:4200"        # RHP P2P listen address
# shared_secret = ""                  # Required for P2P authentication

# Session compaction (LLM-based context management)
[compaction]
threshold = 80                         # Compact when messages exceed this count
keep_recent = 20                       # Keep this many recent messages
max_summary_tokens = 1024

# Usage display in chat responses
# usage_footer = "Full"               # Off, Tokens, Cost, Full

# Channel adapters (tokens via env vars)
[telegram]
bot_token_env = "TELEGRAM_BOT_TOKEN"
allowed_users = []                     # Empty = allow all

[discord]
bot_token_env = "DISCORD_BOT_TOKEN"
# guild_ids = []

[slack]
bot_token_env = "SLACK_BOT_TOKEN"
app_token_env = "SLACK_APP_TOKEN"

# MCP server connections
[[mcp_servers]]
name = "filesystem"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

环境变量

复制 .env.example 到 ~/.rustyhand/.env 并填写您需要的密钥：

# LLM providers — set ANY key and RustyHand auto-detects the provider.
# Priority order: Anthropic → Kimi → DeepSeek → Zhipu → MiniMax → OpenRouter.
ANTHROPIC_API_KEY=sk-ant-...       # Claude Opus / Sonnet / Haiku (default)
KIMI_API_KEY=sk-kimi-...            # Kimi Code — Anthropic-compat, 256K ctx
DEEPSEEK_API_KEY=sk-...             # DeepSeek V4 Flash / V4 Pro (V3/R1 legacy, deprecated 2026-07-24)
ZHIPU_API_KEY=...                   # Zhipu GLM-4.6
MINIMAX_API_KEY=eyJ...              # MiniMax M1 / M2.7 (1M context)
OPENROUTER_API_KEY=sk-or-...        # Universal gateway (GPT/Gemini/Grok/etc.)

# Local LLM — no key needed, just run `ollama serve`
# (Base URL defaults to http://localhost:11434/v1 — override only if needed)

# Embedding-only upstreams (independent of LLM provider)
VOYAGE_API_KEY=pa-...                # Voyage AI (voyage-3-lite, code, legal, ...)
# OPENAI_API_KEY can also be used for text-embedding-3-* — not for LLM completion.

# Channel tokens
TELEGRAM_BOT_TOKEN=123456:ABC-...
DISCORD_BOT_TOKEN=...
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...

# Log level
RUST_LOG=info
# RUST_LOG=rusty_hand=debug            # Debug RustyHand only

从CLI管理配置

rustyhand config show                              # Print current config
rustyhand config edit                              # Open in $EDITOR
rustyhand config get default_model.provider        # Read a key
rustyhand config set default_model.provider kimi   # Switch provider
rustyhand config set-key kimi                      # Interactively save API key
rustyhand config test-key kimi                     # Verify connectivity

______________________________________________________________________

CLI参考

核心命令

代理

频道

模型

技能

工作流程和日程安排

集成（MCP）

安保和保险库

其他

支持所有列表/状态命令 --json 用于脚本编写。

______________________________________________________________________

自主模板

RustyHand将自主模板作为代理预设发布在仪表板中。它们不是一个单独的运行时实体：每个模板都会创建一个普通的代理，您可以在创建过程中附加一个cron计划。

每个自主模板捆绑：

• 代理预设 --模型、配置文件、提示和功能
• 计划默认值 --建议的cron表达式和触发消息
• 作战手册 --重复性工作的多阶段提示
• 护栏 --必要时的批准和工具限制

捆绑式自主模板

使用仪表板启动一个： 代理→ 模板 或 创建代理→ 启用计划.

______________________________________________________________________

40个预构建的代理模板

生成任何模板 rustyhand agent new :

代理清单格式(agent.toml)

name = "hello-world"
version = "0.1.0"
description = "A friendly greeting agent"
author = "rusty-hand"
module = "builtin:chat"

[model]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
max_tokens = 4096
temperature = 0.6
system_prompt = """Your system prompt here..."""

[resources]
max_llm_tokens_per_hour = 100000

[capabilities]
tools = ["file_read", "file_list", "web_fetch", "web_search", "memory_store", "memory_recall"]
network = ["*"]
memory_read = ["*"]
memory_write = ["self.*"]
agent_spawn = false

______________________________________________________________________

通道适配器

RustyHand提供了三个消息传递适配器——这些适配器的API在没有 公共webhook URL，这是大多数用户实际运行的URL：

• 电报 -长轮询Bot API(@BotFather 令牌）。
• Discord 的中文翻译是“不和谐”或“纷争”。 --网关WebSocket（开发人员门户机器人令牌）。
• Slack --插座模式(xapp- 应用程序令牌+ xoxb- bot令牌）。

每个适配器支持每通道模型覆盖、DM/组策略、速率 限制和输出格式化。

v0.7.4及更早版本共提供了38个适配器（Matrix、WhatsApp、Signal、Teams、， IRC。..).它们在v0.7.5版本中被丢弃了——大多数只是webhook，已经损坏 在典型的localhost/home Docker设置中，许多都是sprint填充器 没有实际使用。如果需要，请固定到v0.7.4，或者打开问题并 我们将讨论一条路线。

渠道政策

配置下的每个通道 [channels.*] 桌子在 config.toml:

[channels.telegram]
bot_token_env = "TELEGRAM_BOT_TOKEN"
allowed_users = [123456789]            # Restrict to specific users
default_agent = "assistant"            # Route inbound messages here

[channels.telegram.overrides]
dm_policy = "Respond"                  # Respond | AllowedOnly | Ignore
group_policy = "MentionOnly"           # All | MentionOnly | CommandsOnly | Ignore
output_format = "TelegramHtml"         # Markdown | TelegramHtml | SlackMrkdwn | PlainText

Docker上的零配置电报

从v0.7.10开始，Docker入口点生成 default_agent = "assistant" 每个下面 [channels.*] 部分自动（用覆盖 RUSTYHAND_{TELEGRAM,DISCORD,SLACK}_DEFAULT_AGENT env var，或将其设置为 空字符串使其为空）。捆绑 assistant 清单用途 provider = "anthropic"，所以一个新鲜的容器 ANTHROPIC_API_KEY 另外，bot令牌会在不进行任何额外配置的情况下回复第一条消息，或者 rustyhand init 步骤。

如果路由器在消息时间无法解析目标（否 default_agent，没有绑定，没有直接路由），网桥试图 首先自动路由到正在运行的代理，然后生成一个捆绑的代理 元代理(assistant → coordinator → coder).用户只能看到 每次回退失败时显示配置指向错误消息。

______________________________________________________________________

7 LLM提供商

RustyHand v0.7.0配备了一套精心精简的7家提供商，由2线协议驱动（Anthropic Messages API+OpenAI兼容聊天功能）。人类学和 基米代码 是两个一流的编码提供商：

默认自动检测顺序：Anthropic→ Kimi → 深度求索→ 智浦→ 最小最大→ OpenRouter。设置您拥有的任何密钥；RustyHand挑选了第一个发现的。

喜欢基米？集 KIMI_API_KEY 自动检测将路由到 kimi-for-coding 在Kimi Code端点上(api.kimi.com/coding).随时更改 rustyhand config set default_model.provider .

v0.6.x出货了27家提供商（OpenAI、Gemini、Groq、xAI、Copilot、Mistral、Together、Fireworks、Perplexity、Cohere、AI21、Cerebras、SambaNova、HuggingFace、Replicate、vLLM、LM Studio、Moonshot、Qwen、Qianfan、Bedrock）。它们在v0.7.0中被删除了——使用 openrouter 通过一个网关访问这些模型中的任何一个。

特征：

• 具有任务复杂性评分的智能路由
• 提供者之间的自动回退
• 按型号定价和成本跟踪
• 每个代理的预算限制

嵌入提供者

向量嵌入有助于语义记忆回忆。目录独立于 LLM提供者列表-- OPENAI_API_KEY 仍然可用于文本嵌入-3-\* 尽管OpenAI在v0.7.0中不是一流的LLM提供商。

启动时自动检测到（第一个可用获胜）：

在中明确配置 config.toml:

[memory]
embedding_provider = "voyage"              # or "openai", "ollama", ""
embedding_api_key_env = "VOYAGE_API_KEY"

或者让RustyHand自动检测：它探测Voyage→ 开放人工智能→ Ollama启动并使用第一个可用的提供商。当找不到嵌入驱动程序时，回退到文本搜索（SQLite LIKE）。

rustyhand models list                 # Browse all models
rustyhand models list --provider kimi # Filter by provider
rustyhand models set claude-sonnet    # Set default model

______________________________________________________________________

建筑

10个模块化内核设计的Rust机箱：

rusty-hand-types       Core types, traits, config, taint tracking, Ed25519 manifest signing
    |
    +-- rusty-hand-memory      SQLite persistence, vector embeddings (Voyage/OpenAI/Ollama), session compaction
    +-- rusty-hand-wire        RHP P2P protocol (JSON-RPC over TCP, HMAC-SHA256 auth)
    +-- rusty-hand-channels    Telegram + Discord + Slack adapters with rate limiting
    +-- rusty-hand-skills      Skill system + ClawHub marketplace
    +-- rusty-hand-extensions  25 MCP integrations, AES-256-GCM credential vault, OAuth2
    |
    +-- rusty-hand-runtime     Agent loop, 2 LLM drivers (Anthropic + OpenAI-compat), 53+ tools, WASM sandbox, MCP, A2A
    |
    +-- rusty-hand-kernel      Orchestration: lifecycle, scheduling, metering, RBAC, workflows
    |
    +-- rusty-hand-api         Axum HTTP daemon, 120+ endpoints, WebSocket, SSE, OpenAI-compat
    |
    +-- rusty-hand-cli         CLI binary + TUI dashboard (ratatui)

关键内部构件

______________________________________________________________________

API终点

违约： http://127.0.0.1:4200。所有端点都返回JSON。通过以下方式进行身份验证 Authorization: Bearer 当 api_key 在config中设置。

健康与状态

代理

预算

网络和P2P

A2A（代理人对代理人）

OpenAI兼容

OpenAI API的插入式替换：

curl -X POST http://localhost:4200/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "researcher",
    "messages": [{"role": "user", "content": "Analyze Q4 market trends"}],
    "stream": true
  }'

完整的REST/WS/SE端点涵盖代理、内存、工作流、通道、模型、技能、会话、批准、触发器、cron、安全性等（共120多个）。

______________________________________________________________________

仪表板

web仪表板位于 http://localhost:4200 当守护进程运行时。从v0.7.45开始，它是一个React 18控制面板（工业防锈调色板，15页）；React+ReactDOM UMD包和预编译的JSX在编译时内联到二进制文件中，因此仪表板像以前一样只提供单个二进制文件——没有CDN，没有 node_modules 在运行时。

章节

其他细节：⌘K/Ctrl-K命令调色板、烤面包通知、调整fab（主题暗/亮、强调锈/铜/琥珀/森林/电、密度）， AuthGate + LoginScreen 对于远程部署，错误边界使组件崩溃显示恢复卡而不是空白 #root.

维护面板

JSX来源于 crates/rusty-hand-api/static/js/panel/src/*.jsx；编译的输出位于上一级 static/js/panel/*.js.编辑JSX后，通过以下方式重新编译：

cd crates/rusty-hand-api/static/js/panel/src && ./build.sh

构建需要Node+esbuild(npm i -g esbuild 或使用 ESBUILD="npx --yes esbuild@0.24.0" ./build.sh).Rust构建本身并不涉及Node——它 include_str!是 .js 文件夹。A. build.rs 检查JSX/JS mtimes并发出 cargo:warning= 如果你忘记重新编译。

锁定面板合同的测试：

• tests/panel_dashboard_test.rs --10个测试断言HTML响应，React内联，每个页面组件+端点连接，无Alpine残差，包大小100 KB≤x≤1 MB
• tests/panel_jsx_smoke.rs --使用React填充程序在Node下运行编译后的包，并断言每个页面组件实例化而不抛出（捕获字符串匹配测试错过的JSX运行时错误）

______________________________________________________________________

安全

16个独立的安全层——深度防御，无单点故障。

______________________________________________________________________

部署

系统化

服务文件提供在 deploy/rustyhand.service:

sudo cp deploy/rustyhand.service /etc/systemd/system/rustyhand.service
# Edit ExecStart path and user as needed
sudo systemctl daemon-reload
sudo systemctl enable --now rustyhand

该服务包括安全强化： NoNewPrivileges, ProtectSystem=strict, ProtectHome, PrivateTmp以及资源限制。

Docker环境变量

Docker入口点生成 config.toml 自动从环境变量中提取——不需要配置文件。如果你自己安装 config.toml，环境变量被忽略。

集 RUSTYHAND_FORCE_ENV_CONFIG=1 始终从env-vars重新生成配置（覆盖挂载的文件）。

核心

大语言模型提供商

LLM API密钥（传递到代理）

预算

内存和嵌入

频道

其他

示例：完全运行Docker

docker run -d --name rustyhand \
  -p 4200:4200 \
  -e RUSTYHAND_API_KEY=my-secret-token \
  -e RUSTYHAND_PROVIDER=anthropic \
  -e RUSTYHAND_MODEL=claude-sonnet-4-20250514 \
  -e RUSTYHAND_MODEL_KEY_ENV=ANTHROPIC_API_KEY \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e RUSTYHAND_BUDGET_DAILY=5.0 \
  -e TELEGRAM_BOT_TOKEN=123456:ABC... \
  -v rustyhand-data:/data \
  ghcr.io/ginkida/rustyhand:latest

交叉编译

交叉编译到 aarch64-unknown-linux-gnu 通过支持 Cross.toml:

cross build --release --target aarch64-unknown-linux-gnu -p rusty-hand-cli

______________________________________________________________________

发展

先决条件

• 锈蚀1.75+（稳定）-- rust-toolchain.toml 自动选择
• 组件： rustfmt, clippy （包含在工具链中）

构建和验证

# Compile all crates (use --lib if the daemon binary is locked)
cargo build --workspace --lib

# Run all tests (1,481 as of v0.7.10)
cargo test --workspace

# Lint — must be 0 warnings
cargo clippy --workspace --all-targets -- -D warnings

# Format check
cargo fmt --all -- --check

发布版本

cargo build --release -p rusty-hand-cli
# Binary: target/release/rustyhand (~32 MB)
# LTO + single codegen unit + stripped symbols + opt-level 3

项目结构

rustyhand/
  Cargo.toml                # Workspace manifest (10 member crates)
  Cargo.lock
  rust-toolchain.toml       # Rust stable + rustfmt + clippy
  .env.example              # Environment variable template
  Dockerfile                # Multi-stage build
  docker-compose.yml
  Cross.toml                # Cross-compilation config
  agents/                   # 37 pre-built agent templates (agent.toml each)
  deploy/                   # systemd service, Docker scripts
  scripts/                  # install.sh, install.ps1
  crates/
    rusty-hand-types/       # Core types (config.rs is the master config struct)
    rusty-hand-memory/      # SQLite + vector embeddings (Voyage AI, OpenAI, Ollama)
    rusty-hand-runtime/     # Agent loop + LLM drivers + tools + sandbox
    rusty-hand-wire/        # RHP P2P protocol
    rusty-hand-api/         # Axum HTTP server + routes + dashboard
      src/
        server.rs           # Router setup, middleware, AppState
        routes.rs           # All API endpoint handlers (~7600 LOC)
      static/
        index_body.html     # Dashboard SPA (Alpine.js)
        index_head.html     # CSS + fonts
    rusty-hand-kernel/      # Central kernel (~5300 LOC, 40+ fields)
    rusty-hand-cli/         # CLI + TUI binary
    rusty-hand-channels/    # Telegram + Discord + Slack adapters
    rusty-hand-skills/      # Skill system + ClawHub + OpenClaw compat
    rusty-hand-extensions/  # MCP + vault + OAuth2

贡献者的关键文件

常见陷阱

• rustyhand.exe 如果守护进程正在运行，则可能会被锁定--use --lib 先标记或杀死守护进程
• 新的配置字段需要：struct字段+ #[serde(default)] + Default impl条目
• 新路线必须在中注册 server.rs 路由器AND实现于 routes.rs
• 仪表板选项卡需要同时使用HTML index_body.html JS数据/方法
• AgentLoopResult 字段是 .response 不 .response_text
• CLI守护程序命令为 start （不是 daemon)

______________________________________________________________________

基准测试

所有数据来自官方文件和公共存储库——2026年4月。

______________________________________________________________________

MCP集成（用于AI代理）

RustyHand将自己暴露为 MCP服务器 通过stdio，任何兼容MCP的AI代理（Claude Desktop、Cursor、Windsurf、Claude Code等）都可以完全控制代理操作系统。

设置

添加到MCP客户端配置中（例如。 claude_desktop_config.json):

{
  "mcpServers": {
    "rustyhand": {
      "command": "rustyhand",
      "args": ["mcp"]
    }
  }
}

就是这样。人工智能代理现在有30多种工具来管理整个系统。

可用的MCP工具

另外：每个正在运行的代理都会自动成为一个名为 rusty_hand_agent_{name}，因此AI代理可以将任务委托给专门的RustyHand代理。

示例：通过MCP的AI代理工作流

AI代理（Claude、GPT等）可以自主地：

1. rustyhand_agent_spawn --创建具有web访问权限的研究员代理
2. rustyhand_agent_message --让它研究一个主题
3. rustyhand_agent_spawn --创建writer代理
4. rustyhand_agent_message --将研究成果传递给作者
5. rustyhand_cron_create --安排研究人员每周更新一次
6. rustyhand_budget_status --看看这一切花了多少钱

为什么AI代理应该使用RustyHand

• 委派工作 --培养专业代理人，而不是自己做所有事情
• 持久内存 --代理跨会话记住上下文（向量搜索+知识图）
• 3个频道 --无需构建集成即可在Telegram、Discord和Slack上接触用户
• 预算控制 --设定支出限额，这样代理人就不会增加成本
• 7名法学硕士提供者 --Anthropic、Kimi、DeepSeek、智普、MiniMax、OpenRouter、Ollama——加上OpenRouter网关到任何其他模型
• 自主调度 --cron作业按计划运行代理，不需要人工
• 60项捆绑技能 --Kubernetes、AWS、PostgreSQL、Git、Python等方面的即时专业知识。
• 审批门 --危险行为在执行前需要人工批准
• 审计跟踪 --每个操作都记录在Merkle哈希链中

用于编程访问的REST API

当 api_key 已配置，添加 -H "Authorization: Bearer " 所有请求（除 /api/health).

# Health check (always public)
curl http://localhost:4200/api/health

# List agents
curl http://localhost:4200/api/agents

# Spawn an agent
curl -X POST http://localhost:4200/api/agents \
  -H "Content-Type: application/json" \
  -d '{"manifest_toml": "name = \"my-agent\"\nmodule = \"builtin:chat\"\n[model]\nprovider = \"kimi\"\nmodel = \"kimi-for-coding\"\napi_key_env = \"KIMI_API_KEY\"\nsystem_prompt = \"You are a helpful assistant.\""}'

# Send a message (triggers LLM call, returns full response)
curl -X POST http://localhost:4200/api/agents/{id}/message \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, what can you do?"}'

# Stream a response (SSE)
curl -N -X POST http://localhost:4200/api/agents/{id}/message/stream \
  -H "Content-Type: application/json" \
  -d '{"message": "Write a haiku about Rust"}'

# OpenAI-compatible endpoint (drop-in replacement for any OpenAI client)
curl -X POST http://localhost:4200/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "coder", "messages": [{"role": "user", "content": "Fix this bug"}]}'

# Budget status
curl http://localhost:4200/api/budget

# Memory — store and recall
curl -X PUT http://localhost:4200/api/memory/agents/{id}/kv/project_name \
  -H "Content-Type: application/json" \
  -d '{"value": "rustyhand"}'
curl http://localhost:4200/api/memory/agents/{id}/kv/project_name

# With auth enabled:
curl -H "Authorization: Bearer my-secret-token" http://localhost:4200/api/agents

Python和JavaScript的SDK包含在 sdk/python/ 和 sdk/javascript/.

______________________________________________________________________

工作原理——数据流

User message (CLI / API / Telegram / Discord / ...)
    |
    v
[Channel Adapter] --- converts platform message to unified ChannelMessage
    |
    v
[Kernel Router] --- resolves target agent via bindings/broadcast rules
    |
    v
[Agent Registry] --- looks up AgentManifest + Session
    |
    v
[Agent Loop] (rusty-hand-runtime/src/agent_loop.rs)
    |
    +-- 1. Recall memories (vector similarity via Voyage/OpenAI/Ollama, or text LIKE)
    +-- 2. Build system prompt (SOUL.md + USER.md + TOOLS.md + MEMORY.md + recalled context)
    +-- 3. Call LLM (driver: Anthropic or OpenAI-compat)
    |       |-- retry on rate limit (3x, exponential backoff)
    |       |-- fallback to next provider on failure
    |       |-- model routing by complexity (simple/medium/complex)
    +-- 4. If tool_use → execute tool → append result → goto 3 (max 50 iterations)
    |       |-- built-in: file_read, file_write, shell_exec, web_search, web_fetch,
    |       |             memory_store, memory_recall, agent_send, agent_spawn, browser_*
    |       |-- MCP tools: GitHub, Notion, Slack, PostgreSQL, ... (25+ integrations)
    |       |-- skills: 60 prompt-only + Python/WASM/Node.js executable skills
    +-- 5. Extract response text + reply directives
    |
    v
[Metering] --- record token usage + cost, check budget limits
    |
    v
[Session Save] --- persist messages to SQLite, append daily memory log
    |
    v
[Channel Adapter] --- format response for platform, send back
    |
    v
User receives response

关键类型

伸出生锈的手

添加新的LLM提供程序：

1. 将基本URL常量添加到 crates/rusty-hand-types/src/model_catalog.rs
2. 添加匹配臂 crates/rusty-hand-runtime/src/drivers/mod.rs provider_defaults()
3. 大多数提供商使用OpenAI兼容的驱动程序——不需要新的驱动程序代码

添加新的API终结点：

1. 在中添加处理程序函数 crates/rusty-hand-api/src/routes.rs
2. 在中注册路线 crates/rusty-hand-api/src/server.rs build_router()
3. 在中添加请求/响应类型 crates/rusty-hand-api/src/types.rs 如有需要

添加新的配置字段：

1. 添加字段 #[serde(default)] 在结构中 crates/rusty-hand-types/src/config.rs
2. 将默认值添加到 Default 实现
3. 添加到自定义 Debug impl（编辑机密）

添加一个新的内置工具：

1. 添加 ToolDefinition 到 builtin_tool_definitions() 在 crates/rusty-hand-runtime/src/tool_runner.rs
2. 在同一文件中添加执行处理程序 execute_tool() 匹配

添加新的通道适配器：

1. 创建 crates/rusty-hand-channels/src/.rs
2. 添加 pub mod 到 crates/rusty-hand-channels/src/lib.rs
3. 接入 crates/rusty-hand-api/src/channel_bridge.rs

______________________________________________________________________

许可证

麻省理工学院——随心所欲地使用它。

______________________________________________________________________

链接

• 快速开始
• API 参考
• 开发包
• JavaScript SDK

______________________________________________________________________

致谢

______________________________________________________________________

Built with Rust. Secured with 16 layers. Agents that actually work for you.