humanus.cpp/README.zh.md

English | 中文

   

humanus.cpp

Humanus（拉丁语意为"人类"）是一个基于 OpenManus 和 mem0 启发的轻量级 C++ 框架，集成了模型上下文协议（MCP, Model Context Protocol）。本项目旨在为构建本地 LLM 智能体提供快速、模块化的基础。

主要特点：

• C++ 实现：核心逻辑为 C++，优化速度并最小化开销
• 轻量级设计：最少的依赖和简单的架构，非常适合嵌入式或资源受限的环境
• 跨平台兼容：支持 Linux、macOS 和 Windows
• MCP 协议集成：通过 MCP 原生支持标准化工具交互
• 向量化记忆：使用基于 HNSW 的相似度搜索进行上下文检索
• 模块化架构：易于插入新的模型、工具或存储后端

Humanus 仍处于早期阶段 — 这是一个正在进行中的工作，正在快速发展。我们在开放地迭代，不断改进，并始终欢迎反馈、想法和贡献。

让我们一起探索使用 humanus.cpp 构建本地 LLM 智能体的潜力！

项目演示

如何构建

git submodule update --init

cmake -B build
cmake --build build --config Release

如何运行

配置

要设置自定义配置，请按照以下步骤操作：

1. 将 config/example 中的所有文件复制到 config。
2. 根据需要，在 config/config_llm.toml 中替换 base_url、api_key 等，以及 config/config*.toml 中的其他配置。

   Note：llama.cpp 中的 llama-server 也支持用于向量化记忆的嵌入模型。

3. 在 "@modelcontextprotocol/server-filesystem" 后填写 args 以控制对文件的访问。例如：

[filesystem]
type = "stdio"
command = "npx"
args = ["-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/{Username}/Desktop",
        "other/path/to/your/files] # Allowed paths

mcp_server

（目前工具仅以 python_execute 为例）

在端口 8895 上启动带有 python_execute 工具的 MCP 服务器（或将端口作为参数传递）：

./build/bin/mcp_server <port> # Unix/MacOS

.\build\bin\Release\mcp_server.exe <port> # Windows

humanus_cli

运行带有 python_execute、filesystem 和 playwright（用于浏览器）工具的默认智能体：

./build/bin/humanus_cli # Unix/MacOS

.\build\bin\Release\humanus_cli.exe # Windows

humanus_cli_plan（开发中）

运行规划流程（仅使用 humanus 智能体作为执行器）：

./build/bin/humanus_cli_plan # Unix/MacOS

.\build\bin\Release\humanus_cli_plan.exe # Windows

humanus_server（开发中）

在 MCP 服务器中运行智能体（默认运行在端口 8896）：

• humanus_initialze：传递 JSON 配置（如 config/config.toml 中）以初始化会话的智能体。（每个会话/客户端只维护一个智能体）
• humanus_run：传递 prompt 告诉智能体要做什么。（一次只能执行一个任务）
• humanus_terminate：停止当前任务。
• humanus_status：获取智能体和任务的当前状态及其他信息。返回：
  • state：智能体状态。
  • current_step：智能体的当前步骤索引。
  • max_steps：无需与用户交互的最大执行步骤数。
  • prompt_tokens：提示（输入）token 消耗。
  • completion_tokens：完成（输出）token 消耗。
  • log_buffer：缓冲区中的日志，类似 humanus_cli。获取后将被清除。
  • result：解释智能体的工作过程，任务未完成时为空。

./build/bin/humanus_server <port> # Unix/MacOS

.\build\bin\Release\humanus_cli_plan.exe <port> # Windows

在 Cursor 中配置：

{
  "mcpServers": {
    "humanus": {
      "url": "http://localhost:8896/sse"
    }
  }
}

实验性功能：MCP 中的 MCP！可以运行 humanus_server 并从另一个 MCP 服务器或 humanus_cli 与它互动。

致谢

本工作得到了中国国家自然科学基金（编号：62306216）与湖北省自然科学基金（编号：2023AFB816）。

引用

@misc{humanus_cpp,
  author = {Zihong Zhang and Zuchao Li},
  title = {humanus.cpp: A Lightweight C++ Framework for Local LLM Agents},
  year = {2025}
}