{"id":49527356,"url":"https://github.com/yauntyour/agent.cpp","last_synced_at":"2026-05-02T04:00:59.756Z","repository":{"id":344221559,"uuid":"1181005288","full_name":"yauntyour/agent.cpp","owner":"yauntyour","description":"agent.cpp：微型体积，无限可能，告别臃肿的依赖，迎接极致轻量的智能体时代。","archived":false,"fork":false,"pushed_at":"2026-04-29T13:31:28.000Z","size":1525,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-29T13:39:11.504Z","etag":null,"topics":["agent","cpp"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yauntyour.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-13T16:40:16.000Z","updated_at":"2026-04-29T13:29:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yauntyour/agent.cpp","commit_stats":null,"previous_names":["yauntyour/agent.cpp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/yauntyour/agent.cpp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yauntyour%2Fagent.cpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yauntyour%2Fagent.cpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yauntyour%2Fagent.cpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yauntyour%2Fagent.cpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yauntyour","download_url":"https://codeload.github.com/yauntyour/agent.cpp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yauntyour%2Fagent.cpp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32522252,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T01:12:54.858Z","status":"online","status_checked_at":"2026-05-02T02:00:05.923Z","response_time":132,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","cpp"],"created_at":"2026-05-02T04:00:57.823Z","updated_at":"2026-05-02T04:00:59.742Z","avatar_url":"https://github.com/yauntyour.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agent.cpp：极致轻量、完全可控的 C++ Agent 系统（WebUI）\n\n## 简介\n\n**agent.cpp** 是一个完全透明、高度可控的 C++ 原生 Agent 系统，具备完整的工具链支持。与庞大的 Openclaw 等框架相比，agent.cpp 仅依赖少数几个核心文件实现通信调度与工具管理，内存占用极低（系统额外开销趋近于零，实际占用完全取决于上下文长度），尤其适合资源受限或边缘计算环境。\n\n**设计理念**：语言是经验的载体。LLM 作为系统的语言中枢服务于 Agent，Agent 再将语言转化为行动与记忆。二者的协同，是通向通用人工智能（AGI）的一条可行路径。\n\n## WebUI\n\n![WebUI 截图](./assets/WebUI_1.png)\n\n文件使用状态预览系统（禁止操作\u00260注入风险）\n\n![文件系统](./assets/WebUI_2.png)\n\n依赖需求：\n\n```bash\n#Linux：\nsudo apt-get install -y libcurl4-openssl-dev libboost-dev\n\n#Windows （msys2）：\npacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake mingw-w64-x86_64-ninja mingw-w64-x86_64-curl mingw-w64-x86_64-boost\n\n#MacOS：\nbrew install cmake ninja curl boost\n```\n\n懒狗安装指令：\n\n```bash\nrm -rf ./* \u0026\u0026 git clone --recurse-submodules https://github.com/yauntyour/agent.cpp.git \u0026\u0026 cd agent.cpp \u0026\u0026 mkdir build \u0026\u0026 cd build \u0026\u0026 cmake .. \u0026\u0026 cmake --build . \u0026\u0026 cmake --install . --prefix install\n```\n\n## 核心特性\n\n- **极致轻量**：核心由 `agent.hpp` 单头文件 + `app.cpp` 入口构成，充分利用 C++20 零拷贝与栈上分配特性，运行开销极低。\n- **工作区隔离**：所有用户资源（工具、系统脚本、会话、记忆、提示词）统一存放于 `workspace/` 目录下，结构与部署清晰。\n- **文件使用追踪**：系统自动追踪工具调用中访问过的文件，WebUI 实时展示文件使用状态，防止误操作。\n- **图片资产管理**：Base64 图片数据自动从会话记录中剥离并存储至 `assets/messages/`，大幅缩减会话文件体积。\n- **流式响应**：支持 SSE 流式生成，逐 Token 回调输出，并可分离推理内容（thinking）与回复内容。\n- **完整工具链**：通过 Python CLI 桥接方式，支持任意 Python 工具的原生链式调用。\n- **100% 可控**：系统提示词（System Prompt）完全开放自定义，无隐藏魔法指令。\n- **轻量化扩展设计**：工具直接调用 Python CLI 脚本，避免加载臃肿的技能包描述，最大限度节省上下文 Token。\n- **会话记忆系统**：支持自动/手动将对话历史摘要为记忆，并实时更新会话上下文。\n- **会话记录热加载**：切换会话或频道时，记忆与聊天记录无缝动态加载，图片数据自动恢复。\n- **记忆自动演进**：当会话已存在记忆时，系统会基于既有记忆与最新交互自动优化并更新记忆内容，实现经验积累的闭环。\n\n## 核心文件结构\n\n为了便于理解与二次开发，以下列出系统核心文件及其职责：\n\n```\n.\n├── agent.hpp                  # Agent 主循环、会话管理、工具调度、LLM 通信核心\n├── app.cpp                    # 程序入口，初始化 HTTP 服务与 API 路由\n├── servic.cpp                 # WebUI 后端服务与 API 处理\n├── webui.html                 # WebUI 前端页面\n├── CMakeLists.txt             # CMake 构建配置（含 FetchContent + CPack）\n├── settings.json              # 系统配置文件\n│\n└── workspace/                 # 工作区根目录（所有用户资源集中管理）\n    ├── agent.txt              # 系统提示词文件（100% 自定义）\n    ├── sessions/              # 会话记录持久化（JSON，图片已剥离）\n    ├── memorys/               # 会话记忆持久化\n    ├── assets/                # 静态资源\n    │   ├── WebUI_1.png        # WebUI 截图\n    │   ├── WebUI_2.png        # 文件系统预览截图\n    │   └── messages/          # 图片资产存储（Base64 自动剥离存放）\n    ├── sys/                   # 系统指令、工具调度与通信核心\n    │   ├── cs.txt             # CS 指令系统帮助\n    │   ├── sys_state.py       # 系统状态查询脚本\n    │   ├── sys_tools.py       # 工具调度脚本\n    │   ├── tg_bot.py          # Telegram 频道驱动\n    │   ├── data.json          # 用量统计数据\n    │   └── todos.json         # 待办事项\n    └── tools/                 # 自定义 Python 工具目录\n        ├── tools.json         # 工具注册清单\n        ├── image-drawer/      # 图像生成工具\n        └── playwright-tools/  # 浏览器自动化工具\n```\n\n\u003e 注：实际文件数量可能随版本迭代微调，以上为核心逻辑分布。\n\n## 系统指令集\n\n系统采用简洁的 XML 标签格式进行内部通信，确保行为可审计、可干预。\n\n### 1. 工具调用指令（Tools Call System）\n\n调用预定义工具，格式：\n\n```\n\u003ctool\u003ename:args\u003c/tool\u003e\n```\n\n**内置基础工具**：\n\n| 工具调用格式 | 功能描述 |\n| :--- | :--- |\n| `exec:\u003ccommand\u003e` | 以当前服务权限执行系统命令 |\n| `read:\u003cfilepath\u003e` | 读取指定文件内容 |\n| `write:\u003cfilepath\u003e\\|\u003cdata\u003e` | 向指定文件写入数据（覆盖） |\n| `wget:\u003cURL\u003e` | 发起 HTTP GET 请求并返回响应 |\n\n**示例**：\n\n```xml\n\u003ctool\u003eexec:pip list\u003c/tool\u003e\n\u003ctool\u003eImage:test.jpg\u003c/tool\u003e\n\u003ctool\u003ewrite:exp/data.txt|Hello, agent!\u003c/tool\u003e\n\u003ctool\u003eread:data.txt\u003c/tool\u003e\n\u003ctool\u003ewget:https://cn.bing.com/\u003c/tool\u003e\n```\n\n### 2. 通信系统指令（Communication System, CS）\n\n用于获取系统状态或执行控制命令，格式：\n\n```\n\u003ccs\u003ename:args\u003c/cs\u003e\n```\n\n**支持的命令**：\n\n| 命令 | 功能描述 |\n| :--- | :--- |\n| `system_status` | 返回当前系统运行状态摘要 |\n| `tools_status` | 返回所有已注册工具的状态 |\n| `restart` | 请求重启系统（需 master 显式确认） |\n| `time` | 返回当前系统日期与时间 |\n| `random:\u003cseed\u003e` | 基于种子生成 [-1e9, 1e9] 范围内的伪随机数 |\n\n**示例**：\n\n```xml\n\u003ccs\u003etime\u003c/cs\u003e\n\u003ccs\u003erandom:123\u003c/cs\u003e\n```\n\n## 自定义 Tool 开发\n\n自定义工具采用约定优于配置的方式，仅需提供两个文件即可被系统识别和调度。以 `playwright-tools` 为例，目录结构如下：\n\n```\nworkspace/tools/\n└── playwright-tools\n    ├── run.py       # 被 CS 指令系统调度的入口脚本\n    ├── tool.md      # 工具的参数文档、使用说明（仅此文件被系统读取用于生成帮助）\n    └── ...          # 其他依赖文件（系统仅调用 run.py）\n```\n\n**建议在 `run.py` 中实现帮助信息回退**：当参数错误或调用失败时，将 `tool.md` 的内容打印到标准输出，以便 Agent 获取正确的调用方式。\n\n```python\nimport os\n\ndef print_tool_help():\n    \"\"\"打印 tool.md 中的帮助信息\"\"\"\n    script_dir = os.path.dirname(os.path.abspath(__file__))\n    tool_md_path = os.path.join(script_dir, \"tool.md\")\n    try:\n        with open(tool_md_path, \"r\", encoding=\"utf-8\") as f:\n            print(f.read())\n    except FileNotFoundError:\n        print(f\"警告: 未找到帮助文件 {tool_md_path}\")\n```\n\n## 安全与控制机制\n\n- **高风险操作需显式授权**：当 Agent 处于自主调用模式时，执行重启、关键文件写入等操作必须获得用户显式确认。通过主动指令触发的操作则无需二次确认（仍建议通过提示词约束 `shutdown` 等敏感行为）。\n- **工具状态实时反馈**：每次工具调用后，系统会以独立消息形式返回执行结果（成功或错误详情）。\n- **开箱即用**：会话启动后即可使用全部工具，亦可随时通过 `\u003ccs\u003etools_status\u003c/cs\u003e` 查询可用工具列表。\n\n## 会话管理\n\n- **WebUI 会话**：以创建时的 UNIX 时间戳（秒）作为唯一 `Session ID`，同时用作会话目录命名。\n- **频道（Channel）**：每个频道对应一个以频道名命名的 JSON 文件，存储该频道的聊天记录。频道与 WebUI 会话一样具备独立的记忆摘要。\n\n### 自动会话记忆\n\n当会话上下文长度超过配置的阈值时，系统会自动触发记忆摘要生成（或更新），并将记忆注入当前上下文。阈值可通过配置文件调整：\n\n```json\n\"max_context\": 1048576\n```\n\n\u003e 注：阈值为字符数估算值，实际触发逻辑由系统内部维护。\n\n## 系统提示词自定义（System Prompt）\n\n系统支持 **100% 自定义** 系统提示词。您可以在 `workspace/agent.txt`（或配置中 `prompt` 指定的路径）中以纯文本形式定义 Agent 的行为准则与身份认知。提示词结构建议包含以下模块：\n\n- **外部宣言（External Manifesto）**：优先级排序的行为总则。\n- **身份认知初始化**：定义“你是谁”的起点。\n- **行为许可与禁止**：\n    - 允许的行为（Permitted Conduct）\n    - 禁止的行为（Prohibited Acts）\n- **服务对象定义**：明确 Agent 为谁服务及其关系。\n- **自我愿景**：Agent 期望达成的长期目标或角色定位。\n- **边界定义**：能力与权限的硬性边界。\n- **工具调用说明**：必须保留的章节，用于告知 Agent 可用的 CS 指令及其格式。\n\n\u003e 除“工具调用说明”部分需保留必要技术信息外，其余内容均可自由增删修改。\n\n## 配置文件详解\n\n```json\n{\n    \"user_name\": \"Yauntyours\",                   // 用户名称\n    \"agent_name\": \"assistant\",                   // Agent 角色名\n    \"workspace\": \"./workspace/\",                 // 工作区根目录（含 sessions/ memorys/ sys/ tools/ 等子目录）\n    \"server_address\": \"http://localhost:11434\",  // LLM 服务地址（兼容 OpenAI API 格式）\n    \"model\": \"uGemma4\",                          // 模型名称\n    \"prompt\": \"agent.txt\",                       // 系统提示词文件路径（相对于 workspace）\n    \"stream\": true,                              // 是否启用流式响应（SSE 逐 Token 输出）\n    \"max_mpc_rounds\": 5,                         // 最大多轮工具调用轮次\n    \"max_context\": 1048576,                      // 触发自动记忆摘要的上下文长度阈值（字节）\n    \"channels\": [\n        {\n            \"name\": \"Telegram\",\n            \"status\": \"active\",\n            \"user_count\": 1,\n            \"path\": \"sys/tg_bot.py\"              // 频道对应的驱动脚本（相对于 workspace）\n        }\n    ]\n}\n```\n\n## 授权与致谢\n\n本项目遵循 [Apache-2.0](LICENSE) 协议。在使用或分发时，请保留原始版权与许可声明。若您认可本项目的价值，欢迎点亮 Star ⭐，这对我是极大的鼓励。\n\n---","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyauntyour%2Fagent.cpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyauntyour%2Fagent.cpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyauntyour%2Fagent.cpp/lists"}