@lark-base-open/base-database-cli 1.1.0 → 1.3.7

package/CHANGELOG.md

@@ -1,5 +1,91 @@
 # Changelog
 
+## [1.3.7] - 2026-09-28
+
+### Added
+
+- 支持通过 Mutation 创建、更新、删除记录及追加附件。
+- AI Function 支持图片、视频、音频和 PDF 等多模态输入。
+- 新增 Skill 前端设计指引。
+
+### Changed
+
+- Database Function 参数对齐 TEXT、INT、DOUBLE、BOOL、TIMESTAMP、INTERVAL，支持一维数组和空值；不再接受 DURATION、USER_ID、GROUP_ID、RECORD_ID 声明。
+- 完善 Skill 的 SQL 使用说明。
+- 新建站点和 README 支持中英日语言。
+- CLI 通用提示改为英文。
+- 新建站点使用 Channel SDK 0.1.3。
+- 更新新建站点的编辑入口。
+
+### Removed
+
+- 移除应用能力 Skill 及相关 CLI 入口。
+
+### Fixed
+
+- 部署时跳过未变化的 Base 表绑定。
+- SQL 请求失败时展示结构化错误及诊断信息。
+- 修复附件封面和下载请求缺少站点身份的问题。
+- 修复 AI Function 调试的能力类型判断。
+- 保留 AI Function 批量请求失败时的诊断信息。
+- 修复 Prod 发布结果中的制品信息误用本地 Preview 回执。
+
+## [1.3.0] - 2026-09-22
+
+### Added
+
+- 站点工程提供面向展示的 README 模板，记录用户诉求、已提供的业务能力和验证边界；README 随源码制品上传，并可从远端恢复。
+
+### Changed
+
+- Skill 引导 Agent 在每次部署前核对 README 与用户需求及当前实现，业务能力变化时先更新说明。
+- `check` 和 `deploy` 要求 README 已填写且包含必要业务章节；旧 Preview 制品需重新生成后才能发布 Prod。
+
+## [1.2.0] - 2026-09-21
+
+### Added
+
+- 支持配置、同步和调用 AI Function，覆盖文本、流式及图片、视频等媒体任务。
+- 支持声明、设置、清除和查看第三方 Agent 使用的 FaaS 环境变量，并避免在错误信息中回显变量值。
+- 新增项目级 `check` 命令，在发布前检查并构建 Page、Database Function 与 FaaS。
+- 初始化过程新增本地回执、字段级有限重试和 `--resume` 恢复能力，避免重复创建已确认资源。
+- 为 Database Function 生成输入类型，并在 starter 中提供日期时区和附件图片处理能力。
+- 新增 `context` 命令，汇总当前项目的资源、命令入口和开发上下文。
+- `check` 支持结构化结果和增量检查，便于定位具体失败项。
+
+### Changed
+
+- 将 SQL Function 统一更名为 Database Function，并同步命令、文档与生成工程中的术语。
+- 更新 Page starter 的 Channel runtime 接入与宿主组件集成，固定使用可发布的组合制品。
+- 精简公开 npm 包内容，加入许可证并排除维护者内部文件。
+- 生成工程将 Database Function 目录统一为 `database-functions/`，并兼容现有 `sql/` 目录。
+
+### Removed
+
+- 移除 starter 中的旧 Chatbot 集成；AI 场景统一使用 AI Function。
+- 移除 starter 对 `base-site-js` 和页面 CSRF 注入插件的依赖。
+
+### Fixed
+
+- 修复附件图片加载时的宿主 Blob 处理和错误透传。
+- 修复初始化前 Schema 校验、部分结果保留及限流字段重试行为。
+- 修复空 AI Function 配置的部署同步和 starter 兼容性检查。
+- 修复应用身份授权缺少权限时的申请与诊断提示。
+- 修复 AI Function 参数与用量契约、Database Function Schema 与交付结果不一致的问题。
+- 修复生成工程依赖安装和部分预览重复构建问题。
+
+## [1.1.1] - 2026-09-10
+
+### Changed
+
+- 应用搭建优先使用本地已安装的 CLI，未安装时仍可直接运行。
+
+### Fixed
+
+- 修复含自关联或相互关联数据表的应用初始化失败。
+- 修复部分宿主环境下的账号识别与身份检查失败。
+- 修复部分宿主环境下的应用部署和文件上传失败。
+
 ## [1.1.0] - 2026-09-10
 
 ### Added

package/LICENSE

@@ -0,0 +1,6 @@
+©Lark Technologies Pte. Ltd. All rights reserved. Use is subject to the Legal Agreements outlined here:
+[Feishu User Terms of Service](https://www.feishu.cn/terms)
+[Feishu Privacy Policy](https://www.feishu.cn/privacy)
+[Feishu Open Platform App Service Provider Security Management Specifications](https://open.feishu.cn/document/uAjLw4CM/uMzNwEjLzcDMx4yM3ATM/management-practice/app-service-provider-security-management-specifications)
+[Lark User Terms of Service](https://www.larksuite.com/user-terms-of-service)
+[Lark Privacy Policy](https://www.larksuite.com/privacy-policy)

package/README.md

@@ -10,12 +10,13 @@ Skill 和配套 CLI，用于基于飞书多维表格创建、开发并发布数
 需要 Node.js 20.19 或更新版本，以及可用的 npm。首次安装到 Codex：
 
 ```bash
-npx --yes @lark-base-open/base-database-cli@latest install --target codex
+npm install -g @lark-base-open/base-database-cli@latest
+base-database-cli install --target codex
 ```
 
-安装器将自身版本安装到 npm 全局目录，再从全局包安装 Skill；已有同版本 CLI 时只安装 Skill。支持 `--target codex|claude|agents|all` 或 `--dir <skills 根目录>`。安装器也会同步上述受支持用户目录中可确认来源的公开版 Lark Base Database Skill，避免 Agent 读取另一份旧副本；自动发现跳过内部版和来源不明的副本，不会为未安装的 Agent 新建副本。任一目标已有内容时需显式添加 `--force`，否则在更改 CLI 前停止。单独的 `skill install` 仍只处理所选目标。Codex 使用 `CODEX_HOME/skills`，未设置时使用 `~/.codex/skills`。
+安装器将自身版本安装到 npm 全局目录，再从全局包安装 Skill；已有同版本 CLI 时只安装 Skill。支持 `--target codex|claude|agents|all` 或 `--dir <skills 根目录>`。安装器也会同步上述受支持用户目录中可确认来源的公开版 Lark Base Database Skill，避免 Agent 读取另一份旧副本；自动发现跳过与当前 CLI 来源不匹配或来源不明的副本，不会为未安装的 Agent 新建副本。任一目标已有内容时需显式添加 `--force`，否则在更改 CLI 前停止。单独的 `skill install` 仍只处理所选目标。Codex 使用 `CODEX_HOME/skills`，未设置时使用 `~/.codex/skills`。
 
-若已安装的 CLI 文件损坏，`npx` 可能复用损坏的全局命令，无法启动安装器。先用 `npm install -g @lark-base-open/base-database-cli@<精确版本>` 重装，再执行 `base-database-cli update --version <同一精确版本> --yes` 同步已安装的 Skills。测试或私有 registry 环境需在重装时保留对应 npm registry 配置。
+若已安装的 CLI 文件损坏，先用 `npm install -g @lark-base-open/base-database-cli@<精确版本>` 重装，再执行 `base-database-cli update --version <同一精确版本> --yes` 同步已安装的 Skills。测试或私有 registry 环境需在重装时保留对应 npm registry 配置。
 
 成功结果包含 CLI 版本、实际入口和 Skill 目录。PATH 不通时输出需加入的目录及可直接运行的 Node/CLI 参数；命令入口缺失时提示检查 npm 的 bin-links 配置。不修改 shell 配置、npm prefix 或 Node 安装。npm 失败时保留错误并停止后续步骤。重新加载 Skill 后，日常直接运行 `base-database-cli …`。
 
@@ -47,6 +48,14 @@ CLI 版本来自包内 `package.json`；每份 Skill 的 `base-database-version.
 
 ## 创建、恢复并发布数据库应用
 
+已有或待初始化的本地目录可以先读取一份紧凑、确定性的项目快照：
+
+```bash
+base-database-cli context . --summary --json
+```
+
+`context` 只读取本地配置、Catalog、Function metadata 和 init/Preview 回执。摘要保留环境、资源数量、readiness 与建议的下一步，不输出本地路径、fingerprint 值或逐项资源；排障时去掉 `--summary` 可读取完整快照。Preview freshness 只跟踪 `base-database.jsonc`、Page、Database Function、FaaS 和 AI Function 等部署输入，README、workflow 定义及验收材料不会触发无效重发。缺少 `base-database.jsonc` 时返回 `project.status=uninitialized`，不会报 project-not-found。该命令不读取认证凭证或环境变量值，不调用远端 API，也不执行 `doctor`、`check`、构建或发布；默认输出已经是 JSON，`--json` 用于显式声明机器读取。
+
 ### 复用 lark-cli profile
 
 CLI 复用本机已有的 lark-cli profile，不另存应用密钥或用户 token。通过全局
@@ -81,6 +90,8 @@ base-database-cli init ./todo-database \
   --env online
 ```
 
+CLI 会先创建每张表的主字段，再在所有表都取得真实 ID 后按原顺序创建其余字段，因此 Schema 可以包含自关联和跨表关联字段。
+
 已有 Base 时，不创建或修改 Base。CLI 会读取其中的全部 table，直接创建绑定该 Base 的新应用，获取 Catalog，并生成同样的工程：
 
 ```bash
@@ -100,13 +111,27 @@ base-database-cli init ./todo-database \
   --description '供个人集中创建、跟踪和完成日常任务'
 ```
 
-成功结果通过 `baseSource`、`databaseSource` 分别列出 Base 与应用来源，通过 `baseToken`、`appToken` 返回对应 token；新建或复用的应用信息位于 `created.database` 或 `reused.database`。结果同时列出数据表、binding、生成的工程目录、配置文件和 `catalog.json`，并在 `nextSteps` 中给出开发目录与 Preview 发布命令。
+成功结果通过 `baseSource`、`databaseSource` 分别列出 Base 与应用来源，通过 `baseToken`、`appToken` 返回对应 token；新建或复用的应用信息位于 `created.database` 或 `reused.database`。结果同时列出数据表、binding、生成的工程目录、配置文件和 `catalog.json`。`developmentReadiness` 明确标记初始化尚未准备 Page/FaaS 依赖或执行本地检查，`nextSteps` 按开发、`base-database-cli check --json`、Preview 发布给出后续命令。
+
+初始化失败或在步骤之间中断时，CLI 保留 `.base-database-cli/state/init.json`。字段批次返回完整逐项结果且失败项明确为 `retryable=true` 时，CLI 只重试该字段，单字段最多执行 3 次，按 1 秒、2 秒退避且单次初始化的自动重试等待总计不超过 3 秒；成功后再继续从未尝试的字段。已创建字段不会重发；`retryable=false`、不完整响应、transport 错误和结果未知都不会自动重试，初始化以 `partial` 或 `unknown` 退出并保留回执。
+
+确认回执没有结果未知或正在写入的步骤后，使用原命令和原参数追加 `--resume`；CLI 会先核对环境、profile、计划摘要及回执中的真实资源 ID，再跳过已确认步骤并执行尚未开始的步骤。字段批次只有在逐项结果完整且已创建字段 ID 与远端一致时才补剩余字段。参数变化、资源漂移、`unknown` 或写入中的 `running` 都会在恢复写入前停止；恢复不会按名称认领资源、自动删除资源或整体回滚。
 
-生成项目的 `page/`、`server-functions/`、`sql/` 直接位于项目根目录；`base-database.jsonc` 和 `catalog.json` 也保留在根目录。`server-functions/` 是服务端 FaaS Functions 的源码与构建工作区。CLI 的 Preview 状态和发布临时制品统一写入被 Git 忽略的 `.base-database-cli/state/`。
+```bash
+base-database-cli init ./todo-database \
+  --resume \
+  --schema ./base-schema.json \
+  --name 'Todo 管理' \
+  --env online
+```
+
+生成项目的 `page/`、`server-functions/`、`database-functions/` 直接位于项目根目录；`base-database.jsonc` 和 `catalog.json` 也保留在根目录。`server-functions/` 是服务端 FaaS Functions 的源码与构建工作区。CLI 的 Preview 状态和发布临时制品统一写入被 Git 忽略的 `.base-database-cli/state/`。
 
 ### 恢复并修改已有数据库应用
 
-已有数据库应用存在源码制品时，使用 `pull` 恢复可编辑工程，不要重新执行 `init`。目标目录必须为空；CLI 会下载当前 `page/`、`server-functions/` 和 `sql/` 源码，读取应用 Catalog，并重建 `base-database.jsonc` 与 `catalog.json`，不会创建或修改 Base、应用元信息和 binding：
+已有数据库应用存在源码制品时，使用 `pull` 恢复可编辑工程，不要重新执行 `init`。目标目录必须为空；CLI 会下载当前 `page/`、`server-functions/` 和 `database-functions/` 源码，读取应用 Catalog，并重建 `base-database.jsonc` 与 `catalog.json`，不会创建或修改 Base、应用元信息和 binding：
+
+旧制品中的 `sql/` 会在恢复时迁移为 `database-functions/`。本地旧工程仍可直接检查和发布，但不能同时保留两个目录。
 
 ```bash
 base-database-cli pull ./todo-database \
@@ -118,10 +143,11 @@ base-database-cli pull ./todo-database \
 
 ### 发布 Preview 和正式版本
 
-新建流程是 `init → deploy`；修改已有数据库应用时是 `pull → 修改 → deploy`。Agent 在每个阶段一次性获取所需上下文，根据 Catalog 完整实现 Page、SQL 和 FaaS 后发布 Preview：
+新建流程是 `init → 开发 → check → deploy`；修改已有数据库应用时是 `pull → 修改 → check → deploy`。Agent 在每个阶段一次性获取所需上下文，根据 Catalog 完整实现 Page、Database Function 和 FaaS，通过项目级本地检查后发布 Preview：
 
 ```bash
 cd todo-database
+base-database-cli check --json
 base-database-cli deploy
 ```
 
@@ -137,25 +163,6 @@ Preview 回执会记录生成该制品时的工作区输入指纹。Preview 之
 Preview 回执同时绑定有效的 lark-cli profile；切换 profile 或旧回执没有 profile
 而当前使用本地 profile 时，需要重新发布 Preview，不能直接推广为正式版。
 
-### 部署后的应用能力 Skill
-
-每次部署成功后，CLI 自动将该应用的专属 Skill 安装或更新到当前用户的 `$CODEX_HOME/skills`，未配置时使用 `~/.codex/skills`。部署结果的 `agentGuide.skill` 包含安装状态、名称和路径；后续可直接让 Agent 查询或操作这个应用的数据，或输入 `$<skill.name>`。客户端若未刷新技能列表，开启新会话即可。
-
-Skill 按需读取正式版的 Function 和参数 Schema，不依赖应用工程目录。Preview 发布也会更新 Skill，但不会把 Preview 当成正式版。安装不授予额外权限，也不会自动执行业务动作。
-
-需要单独修复安装或指定其他 Agent 的用户技能目录时：
-
-```bash
-base-database-cli --profile <profile-name> database-skill install --app-token <app-token> --title '<应用名称>' --dir <skills-root>
-```
-
-只更新本工具管理的该应用 `SKILL.md`，不删除其他文件；安装失败会单独返回，不影响已经成功的应用发布。
-
-能力 Skill 使用 `base-database-<hash>` 名称，通过 `database-skill` 命令安装和使用。
-同一应用、环境和 profile 使用固定目录，每次部署更新本工具管理的 `SKILL.md`，保留附加文件。
-生成的发现和调用命令显式携带 profile，不跟随 lark-cli 默认账号变化；托管凭证模式不写入 profile。
-目标目录不受本工具管理或存在符号链接冲突时报告错误，不自动覆盖。
-
 ## 环境
 
 CLI 只支持 `online`，`--env` 默认且仅接受 `online`。保留该参数是为了兼容现有自动化命令；传入其他值会直接失败。所有 lark-cli、OpenAPI、Accounts、应用管理后台和 Page 运行时请求都直接使用线上域名，不启动代理、不改写域名，也不向项目配置写入环境路由。
@@ -167,11 +174,18 @@ base-database-cli auth login --env online
 base-database-cli doctor --env online
 ```
 
-`auth login` 使用上述规则选中的 lark-cli profile，并申请 Base 用户权限。仅未指定
+`auth login` 使用上述规则选中的 lark-cli profile，并申请多维表格相关的用户身份权限（`--domain base`），显式补充
+`base:appmode:read`、`base:appmode:create`、`base:appmode:update`。仅未指定
 profile 且 lark-cli 尚未配置时，才自动启动首次 `config init --new`；指定的 profile
 不存在时直接报错，不创建或覆盖配置。
 
-Base Database CLI 会按 `PATH` 顺序探测全部 `lark-cli`，读取各自的 `--version`，并跳过版本号中带构建 hash 的定制版本，默认使用第一个不带构建 hash 的 release 版本。如果没有可用的 release 版本，命令会明确失败而不会回退到定制版本。需要显式覆盖自动选择时，可将 `BASE_DATABASE_LARK_CLI_PATH` 设置为目标可执行文件的绝对路径；显式设置不会应用版本过滤。
+CLI 明确报告 scope 权限不足时，使用同一 profile 重新执行 `auth login`；若错误另有应用权限开通或额外 scope 的处理要求，按错误提示处理。正常业务调用不增加权限探测。
+`doctor` 复用登录状态中的 scope 列表检查上述三个用户权限，缺少时列出 `missing_scopes` 并提示重新登录；未返回 scope 列表时报告 `unavailable`，托管授权报告 `host_managed`。此项不代替应用侧权限开通检查。
+
+Base Database CLI 按 `PATH` 顺序选择第一个可识别的 `lark-cli`。可通过 `BASE_DATABASE_LARK_CLI_PATH` 指定已确认的可执行文件绝对路径；显式路径优先于 PATH。
+
+宿主入口缺少 `config` 且未选择 profile 时，CLI 保留宿主认证上下文，不生成虚构的本地 profile；指定 profile 却无法核验时仍报错。缺少 `auth` 时，`doctor` 和 `auth whoami` 使用当前用户只读接口核验身份，`doctor` 还检查应用列表接口；认证失败和权限错误不会按命令缺失跳过。宿主登录、退出仍由宿主提供，不模拟成功。Skill 文档命令 `skills read` 缺失时可直接读取已安装文件，不影响业务执行。
+
 
 ## 项目配置
 
@@ -205,16 +219,26 @@ base-database-cli auth login|logout|whoami
 base-database-cli doctor
 base-database-cli init
 base-database-cli pull
+base-database-cli environment-variables list|declare|set|clear
+base-database-cli check [directory] [--no-install | --force-install] [--force-build] [--json]
 base-database-cli deploy
 base-database-cli deployments status
 base-database-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`，因为平台镜像打包器直接调用它。
+`check` 用于开发期本地检查：验证工程配置、页面标题、Function metadata 和输入 Schema，先从 Database Function/FaaS metadata 生成 Page Function 输入类型，再使用 CLI 内置 npm 按依赖指纹准备 Page/FaaS 依赖并运行两者的 build（starter 的 build 包含类型检查）。默认目录为当前目录；`--no-install` 要求依赖已存在，`--force-install` 强制重装，两者不能同时使用。
+
+成功的 Page 和 FaaS build 会分别按源码、lock、Node/npm、平台和构建环境指纹缓存在 `.base-database-cli/state/check-build/`。输入未变化时后续 `check` 直接复用对应结果；只有一侧失败时，修复重试会保留并复用另一侧的成功结果。`--force-build` 忽略这份构建缓存，`--force-install` 会同时重新安装并重新构建；`deploy` 仍执行完整 build，不复用本地 `check` 的构建结果。
+
+使用 `--json` 时，成功或失败的 stdout 都是单个 JSON 文档，报告 `schemaVersion` 为 `2`；成功结果的 `functions["database-functions"]` 和 `functions["server-functions"]` 分别计数两类本地 Function。构建日志在失败时收敛到 `error.diagnostics`；失败结果还提供稳定的 `error.code`、`error.stage`、阶段状态和 `nextActions`，`cache.pageBuild` / `cache.faasBuild` 使用 `hit`、`miss`、`not_run` 单独表达缓存状态，不改变 `checks.*=passed` 的成功语义。不加该参数时保留面向终端的实时 npm/build 输出和文本错误。命令会更新 `page/src/lib/database-function-inputs.generated.ts`、生成本地缓存和构建输出，不调用应用 API、不修改 binding、不上传或发布，也不改写初始化和 Preview 回执。结果中的 `sqlValidation.status=not_run` 表示服务端查询语法、Catalog 与绑定校验未执行；本地通过不代表查询语句或业务运行态已通过。
+
+`deploy` 在一次调用内先生成 Function metadata 并完成全部查询校验，通过后再检查依赖指纹、执行必要的依赖安装、Page/FaaS build、archive、Functions sync、Artifact upload、Preview publish 和状态轮询。CLI 会汇总全部未通过的 Database Function 后一次性报错；存在任一查询校验失败时不会安装依赖或执行 build。依赖指纹未变化且对应 `node_modules` 仍存在时，默认跳过该子项目的 `npm ci`；`--force-install` 强制重装，`--no-install` 无条件跳过安装。build 仍会在每次 Preview deploy 中执行；`check` 不替代发布门禁。FaaS 子项目必须保留可通过 `npm run build` 执行的构建脚本。
+
+FaaS 中静态引用的 `process.env` 变量通过 `environment-variables` 命令管理。定义由 Preview 和 Prod 共享，两套值独立保存；Config 查询时明文返回，Secret 只返回脱敏值。`declare` 创建共享定义并默认拒绝覆盖同名但元数据不同的定义；确认影响后可用 `--force` 修改。声明必须显式传入 `--target`、`--type`，并用 `--required` 或 `--optional` 表明是否必填；`set` 和 `clear` 也必须显式指定目标环境。`set` 只接受 `--value-stdin`，CLI 不提供把值放入进程参数的 `--value`。保存后需重新发布才生效，保存动作不会自动发布。
 
-初始化结果保留所绑定多维表格的 `baseUrl`。发布完成后，CLI 只读取成功态 `publish_status` 返回的 `result.baseAppUrl`，不再使用 `catalog.json` 或 OpenAPI GetProject 兜底；成功态缺少该字段时会明确报错。Preview 发布返回的顶层 `baseAppUrl` 会保留原有查询参数并设置 `mode=edit`，Production 发布返回的顶层 `baseAppUrl` 会移除 `mode`。命令结果不再包含应用管理后台 URL、旧 Preview URL、`preview`/`production` URL 对象或静态资源 `appUrl`/`staticUrl`；静态资源地址只保存在内部 Preview 回执。
+初始化结果保留所绑定多维表格的 `baseUrl`。发布完成后，使用 CLI 返回的顶层 `baseAppUrl` 访问应用；发布成功但未返回访问入口时，CLI 会明确报错。CLI 校验并原样返回 DevCenter 在发布结果中给出的完整访问入口：Preview 入口由服务端提供 `mode=edit`，Production 入口由服务端提供正式访问地址。不要根据应用 token 猜测访问地址，也不要使用构建产物的静态资源地址作为应用入口。
 
-`lark-cli` 子命令仅用于调试。先进入包含 `base-database.jsonc` 的项目根目录；命令只读取当前目录，不接受额外项目路径，并在线上环境直接透传参数。正常初始化和发布无需调用：
+`lark-cli` 子命令仅用于调试。先进入包含 `base-database.jsonc` 的项目根目录；命令只读取当前目录，不接受额外项目路径。普通 JSON API 响应会统一输出到 stdout，兼容宿主将 JSON 正文落盘的行为；显式 `--output`、`--jq`、`--page-all`、非 JSON 格式及其他原生命令保留透传行为。正常初始化和发布无需调用：
 
 ```bash
 base-database-cli lark-cli -- \

package/dist/ai-functions.d.ts

@@ -0,0 +1,42 @@
+import { type RuntimeProfile } from './environment.js';
+export interface AIFunctionInput {
+    functionKey: string;
+    name: string;
+    description: string;
+    configJson: string;
+}
+export declare function collectLocalAIFunctions(workspace: string): AIFunctionInput[];
+export declare function syncAIFunctionsFullCover(appToken: string, items: AIFunctionInput[], env: NodeJS.ProcessEnv, cwd?: string): Record<string, unknown>;
+export declare function syncAIFunctionsForDeploy(appToken: string, items: AIFunctionInput[], env: NodeJS.ProcessEnv, cwd?: string): Record<string, unknown>;
+export interface AIFunctionCommandOptions {
+    directory: string;
+    runtimeProfile?: RuntimeProfile;
+}
+export declare function listAIFunctions(options: AIFunctionCommandOptions): Promise<Record<string, unknown>>;
+export declare function getAIFunction(functionKey: string, options: AIFunctionCommandOptions): Promise<Record<string, unknown>>;
+export declare function syncAIFunctions(options: AIFunctionCommandOptions): Promise<Record<string, unknown>>;
+export declare function validateAIFunction(functionKey: string, options: AIFunctionCommandOptions): Promise<Record<string, unknown>>;
+export interface AIFunctionDebugOptions extends AIFunctionCommandOptions {
+    env: 'preview' | 'prod';
+    variables?: Record<string, unknown>;
+    messages?: Array<{
+        content: Array<Record<string, unknown>>;
+        role: string;
+    }>;
+    input?: Record<string, unknown>;
+}
+export declare function debugAIFunction(functionKey: string, options: AIFunctionDebugOptions): Promise<Record<string, unknown>>;
+export interface AIFunctionTaskOptions extends AIFunctionCommandOptions {
+    env: 'preview' | 'prod';
+}
+export declare function getAIFunctionTask(functionKey: string, taskId: string, options: AIFunctionTaskOptions): Promise<Record<string, unknown>>;
+export interface AIFunctionUsageOptions extends AIFunctionCommandOptions {
+    env?: string;
+    from?: string;
+    to?: string;
+    functionKey?: string;
+    model?: string;
+    capabilityType?: string;
+}
+export declare function getAIFunctionUsage(options: AIFunctionUsageOptions): Promise<Record<string, unknown>>;
+//# sourceMappingURL=ai-functions.d.ts.map

package/dist/ai-functions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-functions.d.ts","sourceRoot":"","sources":["../src/ai-functions.ts"],"names":[],"mappings":"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"}

package/dist/ai-functions.js

@@ -0,0 +1,327 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { readConfig } from './config.js';
+import { assertProjectRuntimeProfile, ONLINE_RUNTIME_PROFILE, } from './environment.js';
+import { LarkCliError } from './lark-cli-error.js';
+import { responseData, runLarkCli } from './lark-cli.js';
+// AI Function 是「功能清单」里的一类声明式资源（function_type=4）：model/System Prompt/能力配置都在
+// ai/<functionKey>/meta.json 里维护，随 deploy 走 OpenAPI 全量覆盖同步。不进 site.zip（不是部署代码，是配置）。
+const FUNCTION_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+const MAX_AI_FUNCTIONS = 200;
+const AI_FUNCTIONS_DIR = 'ai';
+const CAPABILITY_TYPES = new Set(['text', 'vision', 'image', 'video']);
+function stripPlatformManagedFields(config) {
+    const normalized = { ...config };
+    delete normalized.limits;
+    const text = config.text;
+    if (text && typeof text === 'object' && !Array.isArray(text)) {
+        const rest = { ...text };
+        delete rest.max_tokens;
+        normalized.text = rest;
+    }
+    return normalized;
+}
+function aiFunctionsRoot(workspace) {
+    return join(resolve(workspace), AI_FUNCTIONS_DIR);
+}
+function readAIFunctionMeta(path) {
+    const functionKey = basename(dirname(path));
+    if (functionKey.length < 1 ||
+        functionKey.length > 64 ||
+        !FUNCTION_ID_PATTERN.test(functionKey)) {
+        throw new Error(`Invalid AI Function key: ${functionKey}`);
+    }
+    const manifest = JSON.parse(readFileSync(path, 'utf8'));
+    if (typeof manifest.name !== 'string' || manifest.name === '') {
+        throw new Error(`AI Function name must be a non-empty string: ${path}`);
+    }
+    if (manifest.description !== undefined &&
+        typeof manifest.description !== 'string') {
+        throw new Error(`AI Function description must be a string: ${path}`);
+    }
+    if (!manifest.config || typeof manifest.config !== 'object') {
+        throw new Error(`AI Function config must be an object: ${path}`);
+    }
+    const config = stripPlatformManagedFields(manifest.config);
+    if (typeof config.capability_type !== 'string' ||
+        !CAPABILITY_TYPES.has(config.capability_type)) {
+        throw new Error(`AI Function capability_type must be one of text|vision|image|video: ${path}`);
+    }
+    return {
+        configJson: JSON.stringify(config),
+        description: manifest.description ?? '',
+        functionKey,
+        name: manifest.name,
+    };
+}
+// collectLocalAIFunctions 读取 ai/<key>/meta.json 全集（本地声明），供 deploy 全量覆盖同步与 sync 命令共用。
+export function collectLocalAIFunctions(workspace) {
+    const root = aiFunctionsRoot(workspace);
+    if (!existsSync(root)) {
+        return [];
+    }
+    const items = [];
+    const seen = new Set();
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const path = join(root, entry.name, 'meta.json');
+        if (!existsSync(path) || !statSync(path).isFile())
+            continue;
+        const item = readAIFunctionMeta(path);
+        if (seen.has(item.functionKey)) {
+            throw new Error(`Duplicate AI Function key: ${item.functionKey}`);
+        }
+        seen.add(item.functionKey);
+        items.push(item);
+    }
+    if (items.length > MAX_AI_FUNCTIONS) {
+        throw new Error(`AI Functions cannot exceed ${MAX_AI_FUNCTIONS}`);
+    }
+    return items;
+}
+// buildUpdatePayload 把本地全集转成 OpenAPIUpsertAIFunctions 的全量覆盖请求体。
+function buildUpdatePayload(items) {
+    return JSON.stringify({
+        ai_functions: items.map((item) => ({
+            config_json: item.configJson,
+            description: item.description,
+            function_key: item.functionKey,
+            name: item.name,
+        })),
+    });
+}
+// assertAIFunctionResultsOk 严格校验逐条结果：任一条 code != 0 立即抛错。
+// 后端整批拒绝时会同时返回顶层失败和 data.results；调用方必须保留逐条诊断，
+// 并阻止 deploy 继续上传产物或发布失败快照。
+function assertAIFunctionResultsOk(data) {
+    const results = data.results ?? data.Results;
+    if (results === undefined || results === null) {
+        return;
+    }
+    if (!Array.isArray(results)) {
+        throw new Error('AI Function sync returned an invalid results payload');
+    }
+    const failures = [];
+    for (const entry of results) {
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const record = entry;
+        const code = record.code ?? record.Code;
+        if (typeof code === 'number' && code !== 0) {
+            const key = record.function_key ?? record.functionKey ?? record.FunctionKey;
+            const message = record.msg ?? record.Msg ?? record.message ?? '';
+            failures.push(`${String(key ?? '(unknown)')}: code=${code}${message ? ` ${String(message)}` : ''}`);
+        }
+    }
+    if (failures.length > 0) {
+        throw new Error(`AI Function sync failed for ${failures.length} function(s): ${failures.join('; ')}`);
+    }
+}
+// syncAIFunctionsFullCover 走 OpenAPI 全量覆盖同步（对齐 update_functions 心智）：传本地全集，服务端 diff 出
+// add/update/delete + 逐条校验码。deploy 与 `ai sync` 命令共用。空集合仍会清空远端 AI Function（全量覆盖语义）。
+// 任一条 results[].code != 0 立即抛错，避免 deploy 在 AI 同步失败后继续 artifact/publish。
+export function syncAIFunctionsFullCover(appToken, items, env, cwd) {
+    const token = encodeURIComponent(appToken);
+    let response;
+    try {
+        response = runLarkCli([
+            'api',
+            'POST',
+            `/open-apis/base/v3/sites/${token}/ai_functions/update`,
+            '--data',
+            buildUpdatePayload(items),
+        ], env, cwd);
+    }
+    catch (error) {
+        // 顶层失败不能覆盖服务端保留的逐条诊断。
+        if (error instanceof LarkCliError && error.details.results) {
+            assertAIFunctionResultsOk({ results: error.details.results });
+        }
+        throw error;
+    }
+    const data = responseData(response);
+    assertAIFunctionResultsOk(data);
+    return data;
+}
+// deploy 只在本地声明了 AI Function 时同步。空集合不代表用户显式要求清空远端资源，
+// 因而不能为普通 Page/Database Function/FaaS 发布额外请求尚未开放的 AI Function 接口。
+// 显式 `ai sync` 仍直接调用 syncAIFunctionsFullCover，保留空集合全量清空语义。
+export function syncAIFunctionsForDeploy(appToken, items, env, cwd) {
+    if (items.length === 0) {
+        return { skipped: true, reason: 'no_local_ai_functions' };
+    }
+    return syncAIFunctionsFullCover(appToken, items, env, cwd);
+}
+async function resolveEnv(workspace, runtimeProfile) {
+    const config = readConfig(workspace);
+    assertProjectRuntimeProfile(config.runtimeProfile, runtimeProfile);
+    const env = await runtimeProfile.commandEnvironment();
+    return { config, env };
+}
+// listAIFunctions 列出 Site 下 AI Function。
+export async function listAIFunctions(options) {
+    const workspace = resolve(options.directory);
+    const runtimeProfile = options.runtimeProfile ?? ONLINE_RUNTIME_PROFILE;
+    const { config, env } = await resolveEnv(workspace, runtimeProfile);
+    const response = runLarkCli([
+        'api',
+        'GET',
+        `/open-apis/base/v3/sites/${encodeURIComponent(config.appToken)}/ai_functions`,
+    ], env, workspace);
+    return responseData(response);
+}
+// getAIFunction 读取单个 AI Function 配置（用于本地编辑 / diff）。
+export async function getAIFunction(functionKey, options) {
+    const workspace = resolve(options.directory);
+    const runtimeProfile = options.runtimeProfile ?? ONLINE_RUNTIME_PROFILE;
+    const { config, env } = await resolveEnv(workspace, runtimeProfile);
+    const response = runLarkCli([
+        'api',
+        'GET',
+        `/open-apis/base/v3/sites/${encodeURIComponent(config.appToken)}/ai_functions/${encodeURIComponent(functionKey)}`,
+    ], env, workspace);
+    return responseData(response);
+}
+// syncAIFunctions 把本地 ai/ 全集全量覆盖同步到 Site。
+export async function syncAIFunctions(options) {
+    const workspace = resolve(options.directory);
+    const runtimeProfile = options.runtimeProfile ?? ONLINE_RUNTIME_PROFILE;
+    const { config, env } = await resolveEnv(workspace, runtimeProfile);
+    const items = collectLocalAIFunctions(workspace);
+    const data = syncAIFunctionsFullCover(config.appToken, items, env, workspace);
+    return {
+        ok: true,
+        appToken: config.appToken,
+        count: items.length,
+        results: data,
+    };
+}
+// validateAIFunction 静态校验单个本地 AI Function（保存/发布前，按能力分支），不落库。
+export async function validateAIFunction(functionKey, options) {
+    const workspace = resolve(options.directory);
+    const runtimeProfile = options.runtimeProfile ?? ONLINE_RUNTIME_PROFILE;
+    const { config, env } = await resolveEnv(workspace, runtimeProfile);
+    const items = collectLocalAIFunctions(workspace);
+    const target = items.find((item) => item.functionKey === functionKey);
+    if (!target) {
+        throw new Error(`AI Function not found in ${AI_FUNCTIONS_DIR}/: ${functionKey}`);
+    }
+    const response = runLarkCli([
+        'api',
+        'POST',
+        `/open-apis/base/v3/sites/${encodeURIComponent(config.appToken)}/ai_functions/validate`,
+        '--data',
+        JSON.stringify({
+            function: {
+                config_json: target.configJson,
+                description: target.description,
+                function_key: target.functionKey,
+                name: target.name,
+            },
+        }),
+    ], env, workspace);
+    const data = responseData(response);
+    if (data.is_success !== true) {
+        const message = String(data.err_msg ?? 'unknown validation error');
+        throw new Error(`AI Function validation failed: ${message}`);
+    }
+    return data;
+}
+function readCapabilityType(data) {
+    const value = data.function;
+    if (!value || typeof value !== 'object') {
+        throw new Error('AI Function detail does not contain function');
+    }
+    const view = value;
+    const raw = view.config_json;
+    if (typeof raw !== 'string' || raw === '') {
+        throw new Error('AI Function detail is missing config_json');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('AI Function detail config_json is not valid JSON');
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        throw new Error('AI Function detail config_json is not an object');
+    }
+    const capability = parsed.capability_type;
+    if (typeof capability !== 'string' || !CAPABILITY_TYPES.has(capability)) {
+        throw new Error('AI Function detail contains invalid capability_type');
+    }
+    return capability;
+}
+// debugAIFunction 调试 text/vision 时走 unary 聚合；image/video 走统一 tasks 提交接口。
+export async function debugAIFunction(functionKey, options) {
+    const workspace = resolve(options.directory);
+    const runtimeProfile = options.runtimeProfile ?? ONLINE_RUNTIME_PROFILE;
+    const { config, env } = await resolveEnv(workspace, runtimeProfile);
+    const token = encodeURIComponent(config.appToken);
+    const key = encodeURIComponent(functionKey);
+    const detail = runLarkCli(['api', 'GET', `/open-apis/base/v3/sites/${token}/ai_functions/${key}`], env, workspace);
+    const capabilityType = readCapabilityType(responseData(detail));
+    const body = JSON.stringify({
+        input: options.input ?? {},
+        messages: options.messages ?? [],
+        variables: options.variables ?? {},
+    });
+    const response = runLarkCli([
+        'api',
+        'POST',
+        `/open-apis/base/v3/sites/${token}/ai_functions/${key}/${capabilityType === 'image' || capabilityType === 'video' ? 'tasks' : 'invoke'}`,
+        '--params',
+        JSON.stringify({ env: options.env }),
+        '--data',
+        body,
+    ], env, workspace);
+    return responseData(response);
+}
+// getAIFunctionTask 查询 OpenAPI image/video 媒体任务状态。
+export async function getAIFunctionTask(functionKey, taskId, options) {
+    const workspace = resolve(options.directory);
+    const runtimeProfile = options.runtimeProfile ?? ONLINE_RUNTIME_PROFILE;
+    const { config, env } = await resolveEnv(workspace, runtimeProfile);
+    const token = encodeURIComponent(config.appToken);
+    const key = encodeURIComponent(functionKey);
+    const task = encodeURIComponent(taskId);
+    const response = runLarkCli([
+        'api',
+        'GET',
+        `/open-apis/base/v3/sites/${token}/ai_functions/${key}/tasks/${task}`,
+        '--params',
+        JSON.stringify({ env: options.env }),
+    ], env, workspace);
+    return responseData(response);
+}
+// getAIFunctionUsage 读天表聚合的 Owner 可见用量（总量 + 按日期/function/能力分布），走 OpenAPI usage/summary。
+export async function getAIFunctionUsage(options) {
+    const workspace = resolve(options.directory);
+    const runtimeProfile = options.runtimeProfile ?? ONLINE_RUNTIME_PROFILE;
+    const { config, env } = await resolveEnv(workspace, runtimeProfile);
+    const token = encodeURIComponent(config.appToken);
+    const params = {};
+    if (options.from !== undefined)
+        params.from = options.from;
+    if (options.to !== undefined)
+        params.to = options.to;
+    if (options.env)
+        params.env = options.env;
+    if (options.functionKey)
+        params.function_key = options.functionKey;
+    if (options.model)
+        params.model = options.model;
+    if (options.capabilityType)
+        params.capability_type = options.capabilityType;
+    const response = runLarkCli([
+        'api',
+        'GET',
+        `/open-apis/base/v3/sites/${token}/ai_functions/usage/summary`,
+        '--params',
+        JSON.stringify(params),
+    ], env, workspace);
+    return responseData(response);
+}
+//# sourceMappingURL=ai-functions.js.map