agentxx AGENTS.md

Agentxx

• C++ 23 实现的 AI Agent；编译器启用标准 c++26/c17

兼容性

• 跨系统支持:
  • 可编译为独立可执行程序/动态库/静态库，摆脱额外的动态库依赖，仅依赖基本的系统库
  • Linux x86_64 + WSL扩展功能
  • Windows 10+ x86_64
  • Android 5.0+

设计 & 建议

• 详细主程序架构设计见design.md，插件设计文档见plugins.md，当大幅修改代码时，请参考并更新
• Agent 的设计支持:
  • 并发多会话，单线程/多协程交错执行会话，不需要线程锁
  • client (tui/cli) 主要负责UI渲染展示、用户交互；agent (BaseAgent/CodeAgent) 负责运行会话、调用 llm api、运行 toolcall 等
  • client 应当仅做UI渲染，各种数据来源、消息插入应当尽量由 agent 实现并提供
  • 支持 client+agent 在同一个进程内启动，此时两者使用线程间数据交互
  • 支持 client 通过网络连接 agent server，此时两者在不同进程，通过网络传输交互（已支持 websocket）
  • 应当尽量统一抽象接口，分层屏蔽细节，降低复杂度，让架构设计更清晰
  • 会话 Agent_IO、CancelToken、上下文统计、模型选择 应当独立记录，按 thread_id 取值
• 编写代码时在需要注意的地方、设计描述应当有清晰的注释，请勿随意移除原代码中的注释; 编写注释时，统一使用 markdown 风格，多行注释使用 /// 开头
• 合适的情况下，尽量使用std::string_view替代const std::string&
• 应当使用 XX_LOG 输出日志，而不是 std::cout/cerr，避免影响 TUI 显示
• 最终的代码实现目标要能稳定运行在生产环境，广泛服务于各种设备和用户，需要仔细思考实现方案、编写足量的常规使用方式测试+各种边界情况测试
• 非必要不应修改 agent/third_party/ 内的代码，尽量修改本项目的代码实现功能。如果修改了的话应当删除 build 内对应的目录，让 cmake 重新编译，否则可能不生效
• 使用 grep、glob 等工具前参考以下代码结构缩小范围，非必要不应去搜索 agent/** 整个代码库，里面包含了 build、third_party 等文件夹太大
• 需要捕获异常时，建议优先考虑 agentxx::util::catchError 系列，尤其是协程异常，不应 try {} catch(...) 捕获全部异常，应当使用 agentxx::util::catchErrorAsync 放行 取消和中断
• 如果需要编译或运行测试，一般跑 debug 即可

代码结构

• agent:
  • C++ 实现 Agent
• agent/lib: libagentxx
  • 核心库，包含了内置实现的 BaseAgent/CodeAgent、toolcall、node、middleware 等，分离编译以便嵌入其他 app 开发使用
  • util 一些工具类和函数，包括 http server/client、websocket server/client、log、lru cache、aho_corasick/regex、字符串工具 (大小写转换、str转数值、自动检测字符编码并转utf8、计算utf8长度、移除空白符、base64、unix/windows/自动路径标准化、忽略大小写的判断包含/相等、split按char切割字符串)、异常处理
  • BaseAgent agent 运行核心基类 (ReAct 循环 + 会话执行)
  • CodeAgent 继承 BaseAgent, 添加编程工具/中间件
• agent/client: 编译结果 {build}/exec/agentxx_cli
  • 命令行可执行程序，用于启动 agent 服务、实现命令行 cli/TUI 交互
  • agent/client/main.cpp 通过 --agent 启动时
  • IO交互继承于 AgentIOBase (端点基类)
    • agent/client/include/agentxx-client/io/stdio 采用 stdin、stdout、stderr 作为输入输出 agentxx_cli cli
    • agent/client/include/agentxx-client/io/tui 采用 TUI 作为终端渲染界面交互
    • client/server 为两个 AgentIOBase 端点, 经 transport 双向通信 (进程内 Channel / 远程 WS); 发送经 sendToPeer(), 接收经 onPeerMessage() 分发到 protected 被动回调 (onDelta 等)
    • 服务端点为 SessionServerAgentIO (被 BaseAgent 驱动, delta 缓冲/重连重放)
• agent/test: 编译结果 {build}/exec/agentxx_test
  • 测试
  • 运行测试示例:

# 运行所有测试模块，遇到错误也不终止继续运行
path/to/agentxx_test 

# 当任意模块测试存在错误时立即终止测试，未指定时默认无论模块是否存在错误，都完成运行所有测试模块
path/to/agentxx_test --fail-fast
path/to/agentxx_test -f

# - 指定仅运行测试模块 `string_util` `regex`, 其他不运行，默认未指定时运行所有模块
# - 测试模块名称定义见 `agent/test/test.cpp`
path/to/agentxx_test string_util regex

• agent/benchmark: 编译结果 {build}/exec/agentxx_benchmark
  • 性能测试（一般仅 release 启用编译该模块）
• agent/third_party: 第三方库依赖
  • boost
    • asio
    • beast
    • process
    • exception
  • codegraph-cpp
  • cmark-gfm
  • curl
  • fmt
  • FTXUI
  • glob
  • html2md
  • hyperscan
  • [iconv] | libiconv-native
  • liburing
  • NeoGraph
  • Markdown-ui
  • OpenSSL
  • simdjson
  • [sqlite3] | sqlite3-cmake
  • uchardet
  • yaml-cpp
  • [zlib] | zlib-ng