beagent

一个用 C + Lua 写成的 AI Agent 框架：LLM 调用、工具调度、会话与上下文管理， 配一门自研跨平台 shell bes 作为驱动与编排界面。

零解释器外部依赖：除 Lua 之外不引入 Python / Node / 任何脚本运行时。

文档索引

项目管理三件套（本仓库的”实时状态”以这三份为准）：

文件	作用	更新时机
todo.md	实时开发进度与任务板，唯一任务真源	每完成/开始/阻塞一个任务
design.md	开发设计书：目标、分层、接口、分期、构建与测试方案	方向性变化时
mem.md	开发方法与踩坑记录	每踩一个值得记的坑

格式规则见 docs/CONVENTIONS.md（进度板标记法、MEM 编号规则、提交约定）。

设计与记录之间的分工：

• design.md 写”这一版要做成什么样”（含未到期的接口与分期表）；
• 每一次”为什么选 A 不选 B”进 docs/decisions/（ADR 0001–0009），由 design.md 以编号引用；
• “开发中发生了什么意外”进 mem.md；
• “在哪套工具链上验证过”进 docs/BASELINE.md。

依赖原则

系统的唯一系统级依赖是 xmake。此外：

• 第三方库全部 vendor 进 libs/（Lua 5.4.8 源码一行不改），来源与 sha256 记在 ADR；
• 禁止传递构建依赖：任何需要 cmake / meson / autotools / perl / luarocks 才能构建的组件一律否决 （libuv、libcurl 包、readline、busted 因此被拒，见 ADR-0005）；
• 平台自带能力优先：HTTP/TLS 走 WinHTTP / OpenSSL / 系统 libcurl（ADR-0006）， 并发走 worker 线程 + 阻塞 IO（ADR-0007）。

clone 下来即可构建，无需联网拉包。

第三方代码来源与许可

libs/lua/ 是入库的第三方源码，不属于本项目的 MIT 授权范围：

项	值
组件	Lua 5.4.8 参考实现
上游	https://www.lua.org/ftp/lua-5.4.8.tar.gz
sha256	4f18ddae154e793e46eeab727c59ef1c0c0c2b744e7b94219710d76f530629ae
许可	Lua 5.4 license（MIT 风格，与 MIT 兼容），全文见 libs/lua/LICENSE
版权	Copyright © 1994–2025 Lua.org, PUC-Rio
改动	零改动，与上游逐字节一致；libs/lua/src/ 63 个文件入库（34 .c + 27 .h + lua.hpp + 上游 Makefile），其中 32 个 .c 参与构建（lua.c / luac.c 各带 main()，排除在外）

除 Lua 之外当前仓库没有其他第三方代码。计划引入的组件（yyjson、sqlite3 amalgamation、zlib） 及其许可与体积核查见 design.md §5.3 与 ADR-0005； 引入时按 ADR 规则登记来源与哈希。

目录结构

xmake.lua            唯一构建与测试入口（src/**/ 内不放分散构建文件）
design.md  todo.md  mem.md  README.md  LICENSE
docs/                CONVENTIONS / SHELL_SPEC / BASELINE / decisions(ADR 0001-0009)
src/pal/             平台抽象：进程、管道、PTY、路径、env、limits、http+TLS（唯一允许调平台 API 的层）
src/core/            纯 C 运行时：命令表、worker 池、json、log、error（不含 Lua、不含 shell 语义）
src/lua/             C→Lua 绑定层，注册 beagent 模块
src/shell/           bes 装配与 REPL/CLI；bes/ 子目录放 lexer/parser/exec/builtin
src/agent/           llm 适配、tool、memory 的 C 侧
libs/lua/            vendored Lua 5.4.8 源码，一行不改
scripts/             .bes 脚本与 .lua agent 定义
tests/               C 单测 + 自研 Lua harness + bes 回归

构建

需要 xmake（本项目唯一构建与测试管理工具，见 ADR-0003）。

git clone https://gitlink.org.cn/ltree/beagent.git && cd beagent
xmake f -p windows --toolchain=clang -y   # -p 必须显式给，见 mem.md MEM-003
xmake                                     # 构建
xmake test                                # 跑测试
build/windows/x64/release/bes.exe --version
build/windows/x64/release/bes.exe run scripts/hello.bes

Linux 下为 xmake f -p linux && xmake，产物在 build/linux/x64/release/bes。 M3 的联网能力（LLM 调用）在 Linux 上需要发行版的 libssl-dev，当前阶段还不需要； 各平台实测版本基线见 docs/BASELINE.md。

状态

M0（脚手架与可编译骨架）已完成，M1 在做 PAL 地基与外部命令执行，详见 todo.md。 当前 bes 能跑：REPL、bes run <file>.bes、bes -c "..."、引号/变量展开、内嵌 Lua 求值。 bes 的 Lua 表达式需用单引号包住（docs/SHELL_SPEC.md §5），这是目前最容易踩的写法坑。 管道、重定向、&& 已排期（M2）。规范要求未实现的语法必须报错， 但当前分词器仍把 | 当普通参数传给命令，这一违规登记为 todo M1-19 （docs/SHELL_SPEC.md §1 分期纪律）。 License: MIT，见 LICENSE。