跳转到主要内容
Chinese, Simplified

category

正文

披露:我是 PRAXO-CORE 维护者。本文基于 2.10.0 公开范围;不是生产、安全或平台兼容性认证。

在游戏引擎、网络设备、IoT 控制面、OpenResty 风格的网关和带插件系统的应用里,Lua 经常是“宿主里的扩展语言”。

这些扩展不拥有整个运行时,却握着宿主状态、配置、连接和业务钩子。让 Agent 参与这些流程,默认方案是加一个 Python sidecar;但在嵌入式宿主里,sidecar 可能不存在、不被允许,或者太重。

PRAXO-CORE 的 Lua SDK 提供第三条路:保留宿主,把受治理的 Agent 循环放进 Lua 扩展所在的地方。

但最重要的边界必须先说:这是 Lua 5.4,不是“Lua 通用”。

一、核心结论

Lua SDK 是原生 Lua 5.4 Core 实现,不是桥接,也不是 Python 包装。

当前公开验证:

  • 11 组共享向量全部通过;
  • core tests;
  • 公共 API 快照;
  • 远程 lua-conformance CI;
  • 源码 tag lua/v0.8.0,目标 SPEC_VERSION 0.2.0;
  • 只依赖 Lua 标准库;
  • MIT 许可。

三个明确的 partial 面:

  1. event sink:覆盖向量行为和常见路径,但不是每个可选 Go hook;
  2. stream part:有 stream kind 表示,但不是异步运行时;
  3. JSON Schema:覆盖向量定义行为,但不是完整 JSON Schema。

不要把它说成“完整 Go parity”。

二、最重要的兼容性边界

  • 仅 Lua 5.4。
  • 不宣称 LuaJIT 兼容。
  • 不宣称 Lua 5.1 / 5.3 兼容。
  • 不宣称 OpenResty 兼容。
  • 不宣称 Redis 兼容。

这一点非常关键。很多流行的 Lua 宿主使用 LuaJIT 或更老的 Lua 版本。公开材料如果只写“Lua”,会误导读者。更诚实的说法是:这是 Lua 5.4 的原生 Core 循环;如果你的宿主是别的 Lua 运行时,需要单独做移植评估。

三、原生 Lua 5.4 是什么

SDK 由一组原生 Lua module 组成:

  • agent:Agent 循环、options、tool registry、function tool;
  • models:message、request、response、usage、session、event、decision、memory record、context budget、stream kinds;
  • runtime:event sink、path checker、memory store、checkpoint allowlist、context budget、token estimate;
  • toolcall:tool-call 解析、markup 移除;
  • jsonschema:schema 校验;
  • plugin:manifest 解析;
  • middleware:call limit、fallback、PII 脱敏、structured output、tool selection。

核心调用:

package.path = "language/lua/?.lua;lua/?/init.lua;" .. package.path
local agent = require("praxo.agent")
local models = require("praxo.models")

local model = agent.static_model("hello")
local options = agent.agent_options(model)
local result = agent.run_agent(options, models.session({ id = "demo" }), "hello")
print(result.output)

注册工具:

local registry = agent.tool_registry()
agent.register_tool(registry, agent.func_tool("echo", "Echo arguments", function(arguments)
  return arguments
end))
options.tools = registry
options.max_steps = 8

四、依赖故事:标准库 only

Lua 宿主动辄关心 footprint。这个 SDK 刻意做小:

  • 只依赖 Lua 标准库;
  • 没有 Python host;
  • 没有 provider SDK;
  • 核心循环不需要编译扩展。

这不等于“绝对零依赖”,但它把依赖面做小、做可审计。在嵌入式宿主里,这经常是“能不能评估”和“能不能部署”的区别。

五、三个 partial 面

必须明确:

  1. event sink:覆盖向量行为和常见路径,但不是每个可选 Go hook;
  2. stream part:有 stream kind 表示,但不是异步运行时;
  3. JSON Schema:覆盖向量定义行为,但不是完整 JSON Schema。

其余声明范围内通过。provider adapter 需调用方提供传输、异步运行时、plugin host 或持久 session store。

六、治理与宿主状态

嵌入式宿主不需要一个会聊 Lua 的 Agent。它需要的是:Agent 能参与宿主工作流,同时不绕过工作流周围的控件。

这意味着:

  • 策略检查能看到最终工具参数;
  • 工具授权是显式的;
  • 检查点支持恢复;
  • 事件是结构化的,能用于审计和遥测;
  • 人类审批发生在正确边界;
  • 框架清楚说明自己不负责什么。

如果循环就在 Lua 宿主里,宿主状态、凭证和策略决策可以靠得更近。这减少了一种边界穿越,但不自动等于安全或合规。

七、我们不宣称什么

  • 不宣称 LuaJIT、Lua 5.1/5.3、OpenResty 或 Redis 兼容;
  • 不是完整 Go parity;event sink、stream part、JSON Schema 是 partial;
  • 不是包注册表发布;
  • provider adapter 需调用方提供传输;
  • 不宣称异步运行时;
  • 不是 plugin host;只解析 manifest;
  • 不宣称持久 session store;
  • 不是通用 PII 合规;
  • 不宣称生产可用或安全认证。

八、如何验证

lua language/lua/conformance/run.lua
python language/lua/api-snapshot.py --check
lua language/lua/tests/run.lua

然后:

  1. 读 spec/languages.md 的 Lua 行;
  2. 读 language/lua/README.md;
  3. 读 spec/parity/lua.md 的三个 partial 面;
  4. 确认宿主是 Lua 5.4;如果是 LuaJIT/5.1/5.3/OpenResty/Redis,按移植评估处理;
  5. 测试策略顺序、路径处理、取消、回调失败;
  6. 再决定原生循环、桥接还是 sidecar。

仓库:https://github.com/axisvela/praxo-core
Lua 文档:https://axisvela.github.io/praxo-core/languages/lua/
Lua 源码:https://github.com/axisvela/praxo-core/tree/main/language/lua
语言矩阵:https://github.com/axisvela/praxo-core/blob/main/spec/languages.md

九、结语

Lua 不需要变成 Python,才能用 Agent。

它需要的是一个能在宿主进程里受治理地运行、依赖面小、边界清楚的 Agent 循环。

11 组向量、core tests、三个 partial 面、标准库 only、Lua 5.4 边界——这些限制不是缺点清单,而是可信度的一部分。

对无法增加 sidecar、但又需要 Agent 能力的嵌入式宿主,这是一条值得评估的第三条路。

本文地址
最后修改
星期六, 十一月 21, 2026 - 17:56
Article
↑