Base Site CLI

@lark-base-open/base-site-cli 为 Coding Agent 提供 base-site-building Skill 和配套 CLI，用于基于飞书多维表格创建、开发并发布 Base Site。CLI 负责初始化 Base 与 Site、生成项目、校验和构建 Functions，以及发布 Preview 和正式版本。

安装 Agent Skill

首次安装到 Codex：

npx --yes @lark-base-open/base-site-cli@latest skill install --target codex

升级已安装的 Skill：

npx --yes @lark-base-open/base-site-cli@latest skill install --target codex --force

安装后，在 Codex 中描述要搭建的业务系统；Agent 会读取 Skill，并通过 CLI 完成数据模型、页面和 Functions 的开发与发布。

创建并发布 Site

新建 Site 有两种标准入口。需要从零建数据模型时，Agent 根据 Skill 写出完整 base-schema.json，再用一条命令创建 Base、全部 table、Site 与 binding，并生成 hello-world 工程和 Catalog：

npx @lark-base-open/base-site-cli init ./todo-site \
  --schema ./base-schema.json \
  --name 'Todo 管理' \
  --env online

已有 Base 时，不创建或修改 Base。CLI 会读取其中的全部 table，直接创建绑定该 Base 的新 Site，获取 Catalog，并生成同样的工程：

npx @lark-base-open/base-site-cli init ./todo-site \
  --base-token basxxxxxxxx \
  --name 'Todo 管理' \
  --env online

--schema 与 --base-token 必须且只能选择一个。成功结果会列出 Base 来源、数据表、创建的 Site 与 binding、生成的工程目录、配置文件和 catalog.json，并在 nextSteps 中给出开发目录与 Preview 发布命令。

生成项目的 page/、server-functions/、sql/ 直接位于项目根目录；base-site.jsonc 和 catalog.json 也保留在根目录。server-functions/ 是服务端 FaaS Functions 的源码与构建工作区。CLI 的 Preview 状态和发布临时制品统一写入被 Git 忽略的 .base-site-cli/state/。

正常建站只需要 init 和 deploy 两条 CLI 命令。Agent 在每个阶段一次性获取所需上下文，根据 Catalog 完整实现 Page、SQL 和 FaaS 后直接发布 Preview：

cd todo-site
npx @lark-base-open/base-site-cli deploy

部署结果同时返回管理后台 URL 和 Preview URL。Agent 把链接交给用户后停止；用户体验并明确回复“部署正式版”后，把同一制品发布到 Prod：

npx @lark-base-open/base-site-cli deploy --production --yes

环境

CLI 只支持 online，--env 默认且仅接受 online。保留该参数是为了兼容现有自动化命令；传入其他值会直接失败。所有 lark-cli、OpenAPI、Accounts、Site 管理后台和 Page 运行时请求都直接使用线上域名，不启动代理、不改写域名，也不向项目配置写入环境路由。

需要登录或诊断时：

npx @lark-base-open/base-site-cli auth login --env online
npx @lark-base-open/base-site-cli doctor --env online

auth login 使用默认 lark-cli 配置；首次使用时自动启动 config init --new，配置完成后继续申请 Base 用户权限。

项目配置

线上项目的最小配置：

{
  "configVersion": 1,
  "name": "todo-site",
  "siteToken": "Prjxxxxxxxx",
  "bindings": {
    "MAIN_BASE": {
      "type": "base",
      "baseToken": "basxxxxxxxx",
      "tableIds": ["tbl_tasks"],
    },
  },
}

deploy 会在发布前应用合法的 Base binding。目前只支持一个 Base；多个不同 baseToken 会停止发布并提示删除多余 binding。无法解析或暂不支持类型的单个 binding 会输出警告并建议修正 base-site.jsonc。

CLI 命令

npx @lark-base-open/base-site-cli skill install
npx @lark-base-open/base-site-cli auth login|logout|whoami
npx @lark-base-open/base-site-cli doctor
npx @lark-base-open/base-site-cli init
npx @lark-base-open/base-site-cli deploy
npx @lark-base-open/base-site-cli deployments status
npx @lark-base-open/base-site-cli lark-cli -- <arguments...>

deploy 在一次调用内先生成 Function metadata 并完成全部 SQL validate，通过后再检查依赖指纹、执行必要的依赖安装、Page/FaaS build、archive、Functions sync、Artifact upload、Preview publish 和状态轮询。CLI 会汇总全部未通过的 SQL Function 后一次性报错；存在任一 SQL 校验失败时不会安装依赖或执行 build。依赖指纹未变化且对应 node_modules 仍存在时，默认跳过该子项目的 npm ci；--force-install 强制重装，--no-install 无条件跳过安装。build 仍会在每次 Preview deploy 中执行。正常建站不单独运行这些步骤；FaaS 子项目仍保留 npm run build，因为平台镜像打包器直接调用它。

lark-cli 子命令仅用于调试。先进入包含 base-site.jsonc 的项目根目录；命令只读取当前目录，不接受额外项目路径，并在线上环境直接透传参数。正常初始化和发布无需调用。CLI 短期兼容旧的 base-site-cli.jsonc；两个文件同时存在时使用 base-site.jsonc：

npx @lark-base-open/base-site-cli lark-cli -- \
  api GET /open-apis/base/v3/sites/list \
  --params '{"pageSize":1}' --json