章节总览
Agent 工程与轨迹数据 / 14 · 正文
原目录

用代码作为动作的 Agent 执行链路,以及沙箱、SDK、TypeScript 和工具调用的基本概念。

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,做两件事:

  1. 类型检查:静态扫描代码,检查类型错误、函数是否存在、参数是否匹配。
  2. 转译:把 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 越大,梯度估计越稳,但显存和算力成本越高。