02 · CodeAct 与 Agent 工程
CodeAct 沙箱、TypeScript 选型、Function Calling、SDK 与 Batch 概念。返回总览
8. CodeAct 与沙箱基础概念
8.1 CodeAct 架构
用户自然语言需求
→ LLM 生成 TypeScript 代码(调用 @bitable/agent-sdk)
→ 沙箱编译(tsc 类型检查)
→ 试运行(dry run)
→ 正式执行(apply,操作真实 Base)
→ 返回结果
8.2 SDK 是什么
SDK = Software Development Kit(软件开发工具包)。就是别人提前写好的一堆现成函数,直接调用即可。@bitable/agent-sdk 提供建表、加字段、配视图等 TypeScript API。
8.3 TypeScript 代码是什么
TypeScript 是 JavaScript 加了类型系统的超集。写代码时就做类型检查,写错类型直接标红。
8.4 tsc 类型检查是什么
tsc = TypeScript Compiler,做两件事:
- 类型检查:静态扫描代码,检查类型错误、函数是否存在、参数是否匹配。
- 转译:把 TS 转成 JS 给 Node.js 跑。
"编译通过/失败"就是指类型检查的结果。失败时返回精确到行号和类型的错误信息,LLM 可据此修复。
8.5 如何操作真实 Base
沙箱里的 TS 代码
→ 调用 SDK 函数(如 createTable)
→ SDK 封装成 HTTP 请求(带 JWT 鉴权令牌)
→ 调用飞书开放平台 API
→ 在真实 Base 文档上执行操作
→ 返回结果
- 沙箱创建时注入 BASE_ID、USER_ID、JWT,LLM 拿不到也改不了。
- dry run 只检查不执行;apply 才真正改数据。
- Journal 记录每步成功操作,防止重试时重复建表。
8.6 沙箱是什么
隔离的 Node.js 执行环境,支持本地和 VeFaaS 远程两种模式。用内存文件系统,用完即毁。目的:安全隔离 + 任务独立 + 性能。
9. TypeScript vs Python:为什么选 TS
| 考虑点 | TypeScript | Python |
|---|---|---|
| 类型检查 | tsc 编译前抓错 | 运行时才报错 |
| 沙箱启动速度 | Node.js 快,镜像小 | 环境重,启动慢 |
| Base 生态 | 原生 TS SDK,功能最全 | Python SDK 更新慢 |
| LLM 训练数据 | GitHub 上 JS/TS 代码量大 | 也多但类型工具不如 TS |
核心理由:类型系统能在 LLM 生成代码后、执行前就拦掉错误。
10. Function Calling vs CodeAct
| 维度 | Function Calling | CodeAct(写代码) |
|---|---|---|
| 表达能力 | 受限于预定义工具 schema | 图灵完备,能写循环/条件/变量 |
| 组合性 | 多步操作要多轮对话 | 一段代码完成全部操作 |
| 纠错能力 | 靠模型理解自然语言返回 | 编译器给精确结构化错误 |
| 扩展性 | 新操作要新增工具定义 | SDK 加 API,模型自动会用 |
11. SDK 与编程语言的关系
- 一个 SDK 通常绑定一种语言(@bitable/agent-sdk 是 TS 的)。
- 平台会提供多语言 SDK(Python SDK、Java SDK 等),底层都是封装同一批 HTTP API。
- CodeAct 选 TS 不是"SDK 只能 TS",而是 TS + tsc 类型检查 + Base 生态三者综合最优。
12. Batch 概念
一个 batch 就是一次训练 step 里同时喂给模型的一批样本。
GRPO 中:batch 包含 N 个 prompt,每个 prompt 采样 G 条 rollout。
- 例:batch = 32 个 prompt,每个 prompt 采 8 条 → 实际 256 条序列算梯度。
- batch 越大,梯度估计越稳,但显存和算力成本越高。