@lark-base-open/base-database-cli 1.0.0

package/skills/lark-base-database/references/development.md

@@ -0,0 +1,642 @@
+# 数据库应用代码开发手册
+
+本文负责 Page、SQL Function 和 FaaS 的代码边界与 ABI。搭建和发布命令见 [Skill 主流程](../SKILL.md)，SQL 方言与类型见 [SQL Function 专项](sql-function.md)，工程取舍见 [风格手册](style-guide.md)。
+
+## 阅读路径
+
+- [数据库应用代码开发手册](#数据库应用代码开发手册)
+  - [阅读路径](#阅读路径)
+  - [工程结构](#工程结构)
+  - [Function 调用契约](#function-调用契约)
+  - [Page 调用](#page-调用)
+  - [自动化实现边界](#自动化实现边界)
+  - [FaaS 开发](#faas-开发)
+    - [远程调用与写入链路设计](#远程调用与写入链路设计)
+    - [下游错误归一化](#下游错误归一化)
+    - [写入行（记录）](#写入行记录)
+      - [应用记录 写入协议](#应用记录写入协议)
+      - [创建实现示例](#创建实现示例)
+  - [Base 读写协议](#base-读写协议)
+
+## 工程结构
+
+```text
+project/
+├── page/
+├── sql/<functionId>/{main.sql,meta.json}
+└── server-functions/functions/<functionId>/{index.ts,meta.json}
+```
+
+SQL 与 FaaS 的 `functionId` 在应用内全局唯一，匹配 `/^[A-Za-z0-9_-]+$/`；SQL ID 长度为 1～64。`functionId` 会作为 URL 路径段参与运行态调用，除该字符集外不接受其它字符。不同 FaaS Function 目录独立构建，不跨目录 import。Page 和 `server-functions/` 分别维护自己的 npm 工程与 `package-lock.json`。
+
+## Function 调用契约
+
+ABI 是 Page、应用加载器 与 Function 之间固定的数据边界。Page 侧两类 Function 都通过 `invokeDatabaseFunction(functionId, params)` 调用，但 `params` 类型不同：
+
+`functionId` 使用源码目录名，是工程常量。应用 token 由 `page/src/lib/database-runtime.ts` 从产物托管路径解析，不由业务代码传入；FaaS 内部的 `context.invokeFunction` 仍使用 `{projectId,functionId,params}`，两者不要混用。
+
+| Function | `params` | 实现 | 结果 |
+|---|---|---|---|
+| SQL | 按 `$1`、`$2` 排列的数组 | `main.sql` + `meta.json` | 一层 `{data:{rows},code,msg}` |
+| FaaS | 业务对象 | `index.ts` + `meta.json` | 一层 `{data,code,msg}`，`data` 是 handler 业务数据 |
+
+SQL 示例：
+
+```ts
+await invokeDatabaseFunction<{ rows: unknown[] }>('listTasks', ['待处理'])
+```
+
+FaaS 创建操作示例：
+
+```ts
+await invokeDatabaseFunction<{ created: boolean }>('createTask', {
+  title: '准备评审',
+  status: '待处理',
+})
+```
+
+`invokeDatabaseFunction` 打统一网关的 `POST /space/api/bitable/site/v1/:token/invoke_function/:function_id`，由 BaseApp 父页面以同源身份代发；应用 token 与环境由 `src/lib/database-runtime.ts` 统一解析，`env` 走 query，请求体固定为 `{"params": <上述 params>}`。返回统一包裹结构 `{code,msg,data}`，页面使用当前登录用户身份，不保存也不传递任何凭证。
+
+## Page 调用
+
+默认 Page 的 `page/index.html` 需要把 `<title>` 设置为本次生成的应用名称，不留空。
+
+默认 Page 必须引用并渲染 `page/src/components/floating-button/index.tsx` 中的 `FloatingButton` 组件，并显式传入 `language`。该组件自行解析应用 token，不接受 `projectId`。悬浮控件现在只有「编辑应用」和 Chatbot 两个入口，没有「三个点」菜单。
+
+当前账号信息（头像、姓名、组织、退出登录）由**应用自己的导航**承载，用 `page/src/components/database-user-menu/index.tsx` 的 `DatabaseUserMenu`。位置由你按页面布局决定，放在用户会去找账号的地方——顶栏右上角、侧边栏左下角都行，不要再塞进浮层：
+
+```tsx
+// 顶栏右上角
+<header className="flex items-center justify-between ...">
+  <h1>设备台账</h1>
+  {/* 判据：员工 / 部门 / 领用归还属于组织内多角色协作 */}
+  <DatabaseUserMenu language="zh" audience="enterprise" />
+</header>
+
+// 侧边栏左下角
+<aside className="flex flex-col ...">
+  <nav className="flex-1">…</nav>
+  <DatabaseUserMenu language="zh" audience="enterprise" align="left" side="up" />
+</aside>
+```
+
+`align` 控制弹层贴左还是贴右，`side` 控制向上还是向下展开，`showName={false}` 用于窄侧栏只留头像。
+
+`audience` 决定这块身份信息出不出现。它交代的是「你是谁、属于哪个组织、怎么退出」，只有会被本人以外的人打开的系统才需要；个人系统里是噪音，`personal` 时组件整块不渲染。判定在应用开发时做一次并写死在调用处，运行时不推断——产物里没有可靠信号（应用数据模型普遍不建模「用户」这一维），而忽隐忽现比判错更糟。
+
+判定规则，命中任一即 `enterprise`：
+
+1. 需求里出现组织角色词：员工、客户、供应商、部门、审批、工单、门店、团队成员；
+2. 数据模型里存在**第三方实体表**：供应商、客户、合作方、申请人；
+3. 存在跨人流程：提交→审批、分配 / 指派、对账、交接；
+4. 用户明确说要分享给同事或团队使用。
+
+全不命中且主体是「我」（我的账本、习惯打卡、收藏夹、健身记录、背单词——数据只描述自己的行为）时用 `personal`。
+
+**拿不准一律用 `enterprise`。** 代价不对称：多显示一个头像只是碍眼，少显示会让用户在应用内找不到退出登录入口。
+
+判定结果要在建模确认环节一并向用户说明，并写清判据，便于用户当场纠正。判错时用户改这一行重新部署即可，不需要重建应用。
+
+`page/src/main.tsx` 已在首屏挂载后通过 `DatabaseRuntimeReady` 上报 `siteRuntime.ready()`，并在启动失败时上报 `reportLoadFailed`。宿主从握手完成起 10 秒内等不到 ready 会展示加载失败态，因此不要把 ready 上报移到数据加载完成之后，也不要删除该组件。
+
+涉及人员搜索或人员选择的页面，优先引用 `page/src/components/UserSelectorEditor` 和 `page/src/components/UserSelectorPanel` 等 `page/src/components/` 下的人员组件；只有现有组件无法满足交互契约时才做局部扩展。
+选人组件返回的 `User.user_id` 是 Base 人员单元格使用的内部用户 ID；写入人员字段时固定传 `[{"id": user.user_id}]`。`User.open_id` 只是可选的开放平台标识，不得填入应用记录 写入 payload。
+
+业务请求集中在 operation/runtime client，不散落在组件中：
+
+```ts
+import { invokeDatabaseFunction } from '../lib/database-runtime'
+
+interface SqlRows<TRow> {
+  rows: TRow[]
+  columns?: unknown[]
+  row_count?: number
+  log_id?: string
+}
+```
+
+浏览器 SDK 对 SQL 和 FaaS 都只返回一层 `{data,code,msg}`。`invokeDatabaseFunction<TData>` 的 `TData` 只描述当前 operation 约定的顶层 `data`：SQL 通常是 ResultJSON，FaaS 则以各 handler 的业务结果为准，不能统一假设存在 `recordId`。页面只检查一次顶层 `code`，再按 operation 契约校验 `data`；不得写成 `invokeDatabaseFunction<FaasHandlerResult<TData>>`，也不得对 `result.data` 二次解包。否则后端已经写入成功时，页面仍可能误报失败。
+
+运行时业务数据在边界处校验，不能只依赖 TypeScript 泛型。`functionId` 和所有路由是工程常量；用户输入只进入已声明的业务参数。
+
+Page 的所有业务 HTTP 都经父页面代理，使用 `page/src/lib/database-runtime.ts` 导出的 `fetch` 或 `invokeHttp`，URL 必须是以单个 `/` 开头的同源相对路径；绝对 URL、跨域 URL、路径穿越以及 Cookie、Authorization、Host、Origin 等受限 Header 都会被父页面拒绝。请求体只支持字符串，4xx/5xx 会正常返回 `Response`，业务必须自行判断 `response.ok`。禁止直连业务域名，也不得把直连作为代理失败时的兜底。Page 发起的 Base 业务读取和写入仍分别走 SQL Function 与 FaaS。
+
+#### 从零搭建应用的示例数据
+
+从零创建 Base 时，交付前必须写入一组可识别的真实示例记录。Preview 发布后，从 `catalog.json` 取得真实 Base token、table ID、字段类型和选项，通过项目级 Base Database CLI 路由先执行 `lark-cli base +field-list` 核对可写字段，再执行 `lark-cli base +record-batch-create` 写入；当前环境提供等价 CLI 前缀时可以替换前缀，没有项目级路由时直接使用 `lark-cli ... --as user`。示例初始化不要求创建 seed 专用 Function；页面的真实业务写入使用 FaaS。
+
+示例数据保持小而自洽，覆盖默认展示需要的核心对象、典型状态和必要关联；使用非敏感值，并在可见业务主字段中带稳定“示例”标记，不增加只为播种服务的字段。不要在页面加载 Effect 中自动播种。修复后再次写入前先用 SQL Function 查询稳定标记或上一轮返回的 record ID，只补齐缺失记录；非幂等结果未知时不能盲目重试。
+
+列表、详情、看板、统计等展示必须通过 Page 实际使用的 SQL Function 读取 Base。写入成功后通过 `/open-apis/base/v3/sites/:site_token/invoke_function/:function_id?env=preview` 调用该 SQL Function，请求体使用 `{"params":[...]}`，确认返回真实示例记录及预期关系/聚合；页面不得用写入返回值、硬编码数组、`localStorage` 或 fallback mock 冒充查询成功。`lark-cli` 写入失败、写入数量不符或 SQL 回读缺失都属于闭环失败；实现问题必须修复、重新发布 Preview 并重跑写入—查询闭环，认证或平台阻塞与实现失败分开记录。
+
+## 自动化实现边界
+
+代码实现前复核需求拆解结果：Page 主动提交且需要服务端校验的即时业务写入可以实现为 FaaS；定时、记录变化触发、提醒、通知等自动化优先使用原生多维表格能力，不创建 FaaS Function，也不从 Page 调用 FaaS 模拟自动化。
+
+无法确认一项需求是否由原生 Base 支持时，必须先执行[原生 Base 能力发现与路由](base-capability-routing.md)：查询当前 `lark-cli base` shortcut、对应命令帮助和目标 Base 的真实资源，再决定由原生 Base、数据库应用开发链路或两者组合实现。未完成该查询前不得记录能力缺口；查询后仍受限时，必须区分原生能力缺口、当前 CLI 覆盖缺口和权限或环境阻塞。
+
+## FaaS 开发
+
+每个由 Page 主动发起的写入 operation 的目录：
+
+```text
+server-functions/functions/<functionId>/
+├── index.ts
+└── meta.json
+```
+
+```json
+{
+  "name": "创建任务",
+  "description": "校验输入并创建一条任务记录",
+  "inputSchema": {
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "properties": {
+      "title": { "type": "string", "minLength": 1 },
+      "priority": { "type": "string", "enum": ["高", "中", "低"] }
+    },
+    "required": ["title"],
+    "additionalProperties": false
+  }
+}
+```
+
+`inputSchema` 是 Agent 调用该 Function 时 `params` 业务值的结构，不包含外层 `{"params": ...}`；FaaS Function 必须显式声明。CLI 会校验并上传该 Schema，发布后的能力发现接口据此返回可调用参数。只使用 JSON Schema 2020-12 的受限子集：`type`、`description`、`properties`、`required`、`additionalProperties`、`items`、`prefixItems`、`minItems`、`maxItems`、`enum`、`minimum`、`maximum`、`minLength`、`maxLength`；不使用 `$ref`、组合关键字、`pattern`、`format` 或未知关键字。Schema 最大 32 KiB、嵌套不超过 16 层、节点不超过 256 个。
+
+SQL Function 的 `inputSchema` 不手写，由 CLI 根据 `meta.params` 的顺序和 `kind` 确定性生成固定长度数组 Schema；`TIMESTAMP` 与 `DURATION` 均明确为毫秒整数。
+
+上传时 CLI 把 Schema 对象放入 `sourceCode` JSON 字符串：SQL 为 `{sql,meta,inputSchema}`，FaaS 为 `{inputSchema}`，不发送独立的 Function `inputSchema` 字段。FaaS 的可执行代码仍在源码包，`meta.json` 的写法不变；发现接口仍独立返回 `inputSchema` JSON 字符串。
+
+loader 读取 HTTP `req.body.params`，把这个业务对象作为 handler 第一个参数 `rawParams`；第二个参数是 runtime context：
+
+```ts
+interface FunctionContext {
+  fetch: typeof fetch
+  invokeFunction(request: {
+    projectId: string
+    functionId: string
+    params: unknown[]
+  }): Promise<unknown>
+}
+
+interface FaasHandlerResult<T> {
+  data: T | null
+  code: number
+  msg: string
+}
+
+export default async function handler(
+  rawParams: unknown,
+  context: FunctionContext,
+): Promise<FaasHandlerResult<unknown>> {
+  const input = parseCreateTask(rawParams)
+  // 执行业务写入。
+  return { data: { title: input.title }, code: 0, msg: 'success' }
+}
+```
+
+`rawParams` 已经是业务对象。输入校验失败返回稳定业务码、`data:null` 和可读 `msg`。`FaasHandlerResult` 只描述 handler 的返回约定，不得作为页面 `invokeFunction` 的泛型参数。
+
+### 远程调用与写入链路设计
+
+实现前先按设计结果确认一致性、部分成功、重试语义和远程调用依赖。以一次 Page/FaaS operation 为边界列出 SQL Function、`context.fetch` 和写入 OpenAPI；标记哪些输入在 operation 开始时已经确定、哪些必须等待前一步响应。默认使用满足业务语义的最少远程等待阶段：
+
+- 同表多条创建、更新或删除合并到一个 batch 请求，单批不超过 200 条。
+- 同一 operation 调用多个 SQL Function 或 FaaS Function 时，输入已确定、互不依赖，且并发不改变一致性或部分成功语义的调用尽量并发；只有真实响应依赖才串行。
+- 多个无副作用读取或请求的参数已经确定且互不依赖时，先启动全部 Promise，再在共同消费结果处等待；存在真实响应依赖时才串行。
+- 原始 Promise 仍可能 reject 且需要知道每一路结果时使用 `Promise.allSettled`；helper 已把异常归一化为结构化结果时可以使用 `Promise.all`。
+- 写前 SQL 只用于服务端必须确认的权限、关键状态或其他可信数据；写后 SQL 回读用于验收或明确要求的业务校验，不作为每次生产写入的默认步骤。
+- 页面状态仅可用于允许弱一致性的非安全敏感计算。用户身份、权限、租户隔离、支付、库存、额度等约束不得信任页面传值。
+- 多路写入返回值区分全部成功、部分成功和全部失败，并携带已取得的 record ID 与安全错误信息。非幂等创建结果未知时不自动整体重试。
+- 需要事务、唯一约束、条件更新或原子 compare-and-set 才能保证正确性的 operation，在当前 Base 能力下标记为不支持，不使用多次远程请求模拟。
+
+无依赖的多路写入可以采用：
+
+```ts
+const writes = await Promise.allSettled([
+  updatePrimaryRecord(context, input),
+  createAuditRecord(context, input),
+])
+
+return summarizeWrites(writes)
+```
+
+性能敏感的 operation 记录总耗时和各远程调用耗时；只使用成功业务请求评价写入性能，鉴权失败、参数失败和平台凭证缺失只用于诊断。日志和返回值不得包含 token、cookie 或请求凭证。
+
+### 下游错误归一化
+
+FaaS 调用 Base OpenAPI 或其他应用 Function 时，把当前 operation 的业务结果与下游诊断分开：
+
+- 顶层 `code` 和 `msg` 表达稳定、面向调用方的业务语义，不直接使用上游错误码，也不把技术细节拼进 `msg`。
+- 成功或部分成功的业务结果保留在 `data`；仅在失败或部分成功时，把失败步骤放入 `data.errors`。
+- 上游只返回错误摘要时原样保留经清理的摘要和 LogID，不猜测或拼造不存在的校验详情。
+
+```ts
+type DownstreamErrorKind =
+  | 'openapi'
+  | 'function'
+  | 'transport'
+  | 'invalid_response'
+
+interface DownstreamError {
+  source: 'base_openapi' | 'site_function'
+  step: string
+  kind: DownstreamErrorKind
+  operation: string
+  httpStatus?: number
+  code?: number
+  msg: string
+  logId?: string
+  retryable: boolean
+}
+
+type DownstreamOutcome<T> =
+  | { ok: true; value: T }
+  | { ok: false; error: DownstreamError }
+```
+
+下游 helper 捕获预期失败并返回 `DownstreamOutcome<T>`，业务 handler 再汇总各步骤；代码自身的非预期异常仍由 handler 最外层捕获并返回通用错误，不向页面泄漏原始异常或堆栈。分类规则固定为：
+
+- Base OpenAPI 返回合法 JSON 且含非零数值 `code`：`openapi`；
+- 应用 Function 返回合法 envelope 且含非零数值 `code`：`function`；
+- `fetch` reject、超时、连接中断等未取得合法响应：`transport`；
+- 非 JSON、缺少约定字段，或成功响应缺少预期结果：`invalid_response`。
+
+错误对象只允许返回诊断所需的白名单字段。`msg` 取上游安全摘要，去除首尾空白并限制在 300 字符内；`logId` 优先取响应 `x-tt-logid`，可回退 `x-request-id`，限制在 128 字符内。不得返回 URL、请求 body、完整响应、完整 headers、stack、token、cookie 或其他凭证。对于 `context.invokeFunction`，只从其合法返回 envelope 中提取同等字段。
+
+`retryable` 同时取决于错误和写入语义，不能只看 HTTP 状态。明确幂等的固定字段更新或删除遇到 transport、408、429 或 5xx 时可以标记为可重试；非幂等创建出现 transport 或结果未知时必须为 `false`，除非业务已有稳定幂等键和去重机制。页面不得仅因为 `retryable: true` 自动重提，仍按 operation 契约决定交互。
+
+多路写入的顶层业务码至少区分输入无效、部分成功、下游全部失败和内部异常，并在同一 operation 内保持稳定。全部成功时省略 `errors`；部分成功时返回已完成结果、失败步骤和明确的后续动作，避免用户重复提交已经成功的非幂等写入。
+
+应用调用网关在 handler 返回前产生的 504、运行时崩溃或加载失败无法被上述结构捕获。排查这类错误时保留 invoke HTTP 响应自身的 `x-tt-logid`，不要伪装成某次 OpenAPI 调用错误。
+
+### 写入行（记录）
+
+FaaS 使用 `context.fetch` 调用固定的批量写入路由；只使用线上 origin：
+
+| 目标 | Origin |
+|---|---|
+| Online | `https://open.feishu.cn` |
+
+#### 应用记录 写入协议
+
+FaaS 只使用以下五个固定路由，均为 `POST`，请求头为
+`Content-Type: application/json; charset=utf-8`：
+
+```http
+POST /open-apis/bitable/v1/apps/:base_token/tables/:table_id/records/batch_create
+POST /open-apis/bitable/v1/apps/:base_token/tables/:table_id/records/batch_update
+POST /open-apis/bitable/v1/apps/:base_token/tables/:table_id/records/batch_delete
+POST /open-apis/bitable/v1/apps/:base_token/tables/:table_id/append_attachments
+POST /open-apis/bitable/v1/apps/:base_token/tables/:table_id/remove_attachments
+```
+
+后两条是附件字段专用的增量路由（注意不在 `records/` 段下）：请求只提交本次增删的
+`file_token`，服务端读取、合并后整格提交，保留读到的其它附件及宽高；不保证原子性或去重。目标环境必须已部署对应 FaaS runtime 和服务端能力，不能仅凭 Skill 存在就判定可用。什么时候必须用它们、什么时候仍可整格写，
+见[文件传输](file-transfer.md)的「写单元格」。
+
+路径首个参数是 **Base token，不是应用 token**：取 `catalog.json` 中该表的
+`tables[].baseToken`，与 table ID 一起作为 Function 内的工程常量。应用 token 只用于
+`context.invokeFunction` 的 `projectId`，两者不要混用。
+
+请求体必须严格使用对应结构，不混用普通 Base OpenAPI、MCP 或其他 batch 接口的字段：
+
+| operation | 请求体 | 成功时 `data.record_id_list` 的语义 |
+|---|---|---|
+| `batch_create` | `{"create_records":[{字段名: CellValue}, ...]}` | 与 `create_records` 按位置一一对应的新记录 ID |
+| `batch_update` | `{"update_records":{"rec_xxx":{字段名: CellValue}, ...}}` | 实际存在并处理的记录 ID；不存在的 ID 放入 `record_not_found` |
+| `batch_delete` | `{"record_id_list":["rec_xxx", ...]}` | 原样回显请求 ID；不存在、因此未删除的 ID 另放入 `record_not_found` |
+| `append_attachments` | `{"attachments":{"rec_xxx":{"字段名或字段ID":[{"file_token":"...","image_width":640,"image_height":480}]}}}` | 无 `record_id_list`，见下方附件增量响应 |
+| `remove_attachments` | 同 `append_attachments`，数组项只需 `file_token` | 同上 |
+
+五个请求体都是 strict JSON Schema：不接受表格中未列出的额外顶层字段。「每批 1～200 条
+记录」只适用于前三条 batch 路由；附件增量路由的限制是**一次操作的 `file_token` 总数不超过
+50**；附件映射及每个 record-field 数组没有非空 Schema 约束。record ID 必须匹配
+`^rec[A-Za-z0-9]{1,11}$`；删除列表不允许重复，
+更新映射的 key 自然唯一。`batch_update` 使用 `update_records` 为不同记录分别提交
+patch；不要混用 MCP 工具层 `patch_records_batch` 的 `record_id_list + patch` 请求结构。
+
+**附件非空检查由调用方负责**：Page/FaaS 先过滤空字段数组、再移除空记录映射，全部为空时
+本地短路，不发送请求。不要依赖平台拒绝空输入：合法目标上的 `append []` 仍会读取并写回
+已有列表，`remove []` 不产生实际变更并可返回成功。图片宽高须由 Page 从本地 `File` 解码
+取得，不能依赖上传返回值中的可选宽高；非图片与解码失败的处理见[文件传输](file-transfer.md)。
+
+所有写入的成功 HTTP body 都只有一层 OpenAPI envelope（batch 路由示例如下）：
+
+```json
+{
+  "code": 0,
+  "msg": "",
+  "data": {
+    "record_id_list": ["rec_xxx"],
+    "record_not_found": ["rec_missing"]
+  }
+}
+```
+
+Node MCP 直接响应中的 `meta` 不会经过当前 FaaS Entry 的合成响应返回，FaaS 不得依赖该字段。
+
+`batch_create` 和 `batch_update` 的 `data` 还可能包含被忽略的只读或不支持字段；未忽略任何字段时
+`ignored_fields` 不存在：
+
+```json
+{
+  "record_id_list": ["rec_xxx"],
+  "ignored_fields": [
+    {
+      "id": "fld_xxx",
+      "name": "创建时间",
+      "reason": "READONLY: created_at field is auto-created by the system."
+    }
+  ]
+}
+```
+
+附件增量路由的成功响应没有 `record_id_list`：`data.attachments` 按记录、字段回显
+**本次操作合并出的附件列表**（`file_token` / `name` / `size`），页面用它更新本地状态；
+它不是包含全部并发写入的最终快照，不要立即用 SQL 回读替换它（从库可能尚未同步）。超时或结果未知时保留已上传 token，按[文件传输](file-transfer.md#超时与结果未知)有界核对；append 不幂等，不能自动重提或重新上传。字段设置了「仅限手机拍摄」时，
+`append_attachments` 对该字段的追加被忽略并进入 `ignored_fields`；`remove_attachments`
+不受该限制，仍可移除。校验纪律同 batch：只认约定字段，不递归找。
+
+runtime 识别后返回的是合成响应，因此这条链路上：
+
+- HTTP 状态恒为 `200`，业务成败只看 body 的 `code`，不能只判 `response.ok`；
+- 响应头没有 `x-tt-logid`，`DownstreamError.logId` 必然为空。排查改用 invoke 响应
+  自身的 LogID，见[下游错误归一化](#下游错误归一化)。
+
+**三条 batch 路由**的成功响应固定读取 `body.data.record_id_list`，未找到的记录固定读取
+`body.data.record_not_found`；**附件增量路由**的成功响应固定读取 `body.data.attachments`，
+两类不得混用同一解析器。不得递归遍历整个响应寻找字符串，不得猜测或兼容 `record_id`、
+`recordId`、`records[].id` 等未约定结构，也不得把 `data.record_id_list` 当作 handler 自定义返回的
+`recordId`。三种 batch operation 分别校验：
+
+- `batch_create`：`record_id_list.length` 必须与 `create_records.length` 一致，且不得返回 `record_not_found`。
+- `batch_update`：`record_id_list` 是实际存在的记录，允许为空；它与 `record_not_found` 必须是请求 key 的不重叠、无遗漏分组。
+- `batch_delete`：`record_id_list` 必须与请求列表一致，`record_not_found` 必须是其子集；实际删除的 ID 是两者的差集。
+
+`code === 0` 且 `record_not_found` 非空是 Node MCP batch 的合法部分成功，不是 `invalid_response`。FaaS handler 必须在
+业务结果中保留已完成和未找到的 ID；需要向 Page 表达部分成功时，使用当前 operation 的稳定业务码，
+但不得伪装成下游失败或整体重试。只有响应缺失、类型不符或不满足上述 operation 约束时才按
+`invalid_response` 处理；非幂等创建不得自动重试。
+
+可复用的严格解析器：
+
+```ts
+interface IgnoredRecordField {
+  id: string
+  name: string
+  reason: string
+}
+
+interface SiteRecordsWriteData {
+  record_id_list: string[]
+  record_not_found?: string[]
+  ignored_fields?: IgnoredRecordField[]
+}
+
+interface SiteRecordsWriteEnvelope {
+  code: number
+  msg: string
+  data: SiteRecordsWriteData
+}
+
+function parseDatabaseRecordsWriteData(
+  value: unknown,
+): SiteRecordsWriteData | undefined {
+  if (typeof value !== 'object' || value === null) return undefined
+  const envelope = value as Record<string, unknown>
+  if (envelope.code !== 0) return undefined
+  if (typeof envelope.data !== 'object' || envelope.data === null) {
+    return undefined
+  }
+  const data = envelope.data as Record<string, unknown>
+  const recordIdPattern = /^rec[A-Za-z0-9]{1,11}$/
+  const parseRecordIDs = (input: unknown): string[] | undefined => {
+    if (
+      !Array.isArray(input) ||
+      input.length > 200 ||
+      input.some(
+        (recordId) =>
+          typeof recordId !== 'string' || !recordIdPattern.test(recordId),
+      ) ||
+      new Set(input).size !== input.length
+    ) {
+      return undefined
+    }
+    return input as string[]
+  }
+  const recordIDs = parseRecordIDs(data.record_id_list)
+  const recordNotFound =
+    data.record_not_found === undefined
+      ? undefined
+      : parseRecordIDs(data.record_not_found)
+  if (
+    !recordIDs ||
+    (data.record_not_found !== undefined && !recordNotFound) ||
+    (recordIDs.length === 0 && (recordNotFound?.length ?? 0) === 0)
+  ) {
+    return undefined
+  }
+  return {
+    record_id_list: recordIDs,
+    ...(recordNotFound ? { record_not_found: recordNotFound } : {}),
+    ...(Array.isArray(data.ignored_fields)
+      ? { ignored_fields: data.ignored_fields as IgnoredRecordField[] }
+      : {}),
+  }
+}
+```
+
+该 helper 只负责成功 payload 的固定结构；HTTP 失败、非零业务码和错误摘要仍按
+[下游错误归一化](#下游错误归一化)处理。
+
+#### 创建实现示例
+
+```ts
+const OPENAPI_ORIGIN = 'https://open.feishu.cn'
+const response = await context.fetch(
+  `${OPENAPI_ORIGIN}/open-apis/bitable/v1/apps/${encodeURIComponent(BASE_TOKEN)}` +
+    `/tables/${encodeURIComponent(TABLE_ID)}/records/batch_create`,
+  {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json; charset=utf-8' },
+    body: JSON.stringify({
+      create_records: [
+        {
+          任务名称: input.title,
+          状态: input.status,
+          截止时间: input.dueAt,
+        },
+      ],
+    }),
+  },
+)
+
+const body: unknown = await response.json().catch(() => null)
+
+if (
+  !response.ok ||
+  typeof body !== 'object' ||
+  body === null ||
+  !('code' in body) ||
+  body.code !== 0
+) {
+  const logId =
+    response.headers.get('x-tt-logid') ??
+    response.headers.get('x-request-id') ??
+    undefined
+  const upstreamCode =
+    typeof body === 'object' &&
+    body !== null &&
+    'code' in body &&
+    typeof body.code === 'number'
+      ? body.code
+      : undefined
+  const rawUpstreamMsg =
+    typeof body === 'object' &&
+    body !== null &&
+    'msg' in body &&
+    typeof body.msg === 'string'
+      ? body.msg.trim().slice(0, 300)
+      : ''
+  const upstreamMsg =
+    rawUpstreamMsg || response.statusText || `OpenAPI HTTP ${response.status}`
+  const isOpenApiError =
+    typeof upstreamCode === 'number' && upstreamCode !== 0
+
+  return {
+    data: {
+      created: false,
+      errors: [
+        {
+          source: 'base_openapi',
+          step: 'createTask',
+          kind: isOpenApiError ? 'openapi' : 'invalid_response',
+          operation: 'batch_create',
+          httpStatus: response.status,
+          ...(typeof upstreamCode === 'number'
+            ? { code: upstreamCode }
+            : {}),
+          msg: upstreamMsg,
+          ...(logId ? { logId: logId.trim().slice(0, 128) } : {}),
+          retryable: false,
+        },
+      ],
+    },
+    code: 50201,
+    msg: '创建任务失败',
+  }
+}
+
+const created = parseDatabaseRecordsWriteData(body)
+if (
+  !created ||
+  created.record_id_list.length !== 1 ||
+  (created.record_not_found?.length ?? 0) > 0
+) {
+  return {
+    data: {
+      created: true,
+      errors: [
+        {
+          source: 'base_openapi',
+          step: 'createTask',
+          kind: 'invalid_response',
+          operation: 'batch_create',
+          msg: '创建成功但响应中的记录 ID 数量不符合请求',
+          retryable: false,
+        },
+      ],
+    },
+    code: 50202,
+    msg: '任务已创建，但无法确认记录 ID',
+  }
+}
+
+const [recordId] = created.record_id_list
+return { data: { created: true, recordId }, code: 0, msg: 'success' }
+```
+
+FaaS 写入 Base 时，必须调用目标环境的
+`/open-apis/bitable/v1/apps/:base_token/tables/:table_id/records/batch_*`（记录批量写）或
+`.../append_attachments`、`.../remove_attachments`（附件增量）路由；
+`:base_token` 取 `catalog.json` 的 `tables[].baseToken`，并检查 HTTP 状态和业务码。
+
+需要读 Base 时调用固定 SQL Function：
+
+```ts
+const result: unknown = await context.invokeFunction({
+  projectId: PROJECT_ID,
+  functionId: 'findTaskById',
+  params: [input.recordId],
+})
+```
+
+确需写前查重、权限范围、状态检查或写后查询时复用固定 SQL Function；可以在一次查询中完成的检查不拆成多个串行调用。前一个 SQL 返回的关联 ID 仅用于定位后一个 SQL 的记录时，优先把关联查询下推为一个 SQL Function。
+
+## Base 读写协议
+
+同一个字段在创建 schema、SQL 读取和 OpenAPI 写入时使用三套不同但相关的数据结构：
+
+| Field JSON | SQL 读取 | OpenAPI CellValue |
+|---|---|---|
+| `text` | `TEXT` string | string |
+| `number` | `DOUBLE` number | finite number |
+| 单选 `select` | `OPTION` string | 合法选项名 string |
+| 多选 `select` | `COLLECTION<OPTION>` | 合法选项名 string[] |
+| `datetime` | `TIMESTAMP` 毫秒 number | `YYYY-MM-DD HH:mm:ss` |
+| `checkbox` | `BOOL` boolean | boolean |
+| 单/多 `user` | `USER` / `COLLECTION<USER>` | `[{"id":"6882577547121393684"}]`；`id` 是内部 `user_id` |
+| 单/多 `group_chat` | `GROUP` / `COLLECTION<GROUP>` | `[{"id":"oc_xxx"}]` |
+| `link` | `COLLECTION<RECORD_ID>` | `[{"id":"rec_xxx"}]` |
+| `attachment` | `COLLECTION<FILE>` | `[{"file_token":"...","image_width":number,"image_height":number}]`；追加/移除走附件增量路由，`batch_update` 写该字段是整格覆盖、会丢已有图片宽高，仅用于置空或明确重设。见[文件传输](file-transfer.md) |
+| `location` | `UNSUPPORTED` | `{"lng":number,"lat":number}` |
+| 公式、lookup、系统字段 | 推导类型或 `UNSUPPORTED` | 只读 |
+
+写入时 `null` 清空字段，`[]` 表示空集合，省略字段表示不修改。选项名、用户/群 ID 和关联 record ID 必须来自真实数据。
+
+应用行写入只使用 [应用记录 写入协议](#应用记录写入协议)中的固定路由。
+
+创建一行或多行时，`create_records` 中每一项是字段到 cell value 的映射，不同记录可以填写不同字段：
+
+```json
+{
+  "create_records": [
+    {
+      "任务名称": "客户回访",
+      "状态": "待处理",
+      "负责人": [{ "id": "6882577547121393684" }]
+    }
+  ]
+}
+```
+
+更新时把以 record ID 为 key 的字段 patch 放入 `update_records`：
+
+```json
+{
+  "update_records": {
+    "rec_xxx": { "状态": "已完成" },
+    "rec_yyy": { "状态": "进行中", "备注": "处理中" }
+  }
+}
+```
+
+删除时传入 record ID 列表：
+
+```json
+{
+  "record_id_list": ["rec_xxx", "rec_yyy"]
+}
+```
+
+检查 HTTP 状态和外层业务码后，还必须按固定成功响应协议校验：batch 路由校验
+`data.record_id_list`，附件增量路由校验 `data.attachments`；需要后续写入、关联或回读时，
+只使用约定字段中的记录 ID。
+
+batch 路由单批最多 200 条。多选、多人员、关联这些集合字段是**整格覆盖**：追加或移除必须先读现有值、合并出完整列表再整格写回，直接写会丢掉单元格里已有的项。**附件字段是唯一的例外**：追加/移除走上面的附件增量路由，禁止用读-合并-整格写回实现——服务端不会补齐省略的宽高，而 SQL 读不回旧图宽高，基于 SQL 列表的重写无法重建宽高；并发时整格写回还会互相覆盖。见[文件传输](file-transfer.md)的「写单元格」。
+
+**整格覆盖的合并基准必须是可信的完整列表。** SQL 回读走从库，刚写完就回读可能拿到写入前的旧值；拿缺项的列表做基准整格写回，会静默删掉其它项，而写入仍返回成功。读取失败、从未读到过、或回读缺少本次刚写入的项时，禁掉入口让用户稍后重试，不要写。
+
+文件字节的上传与展示是另外的路，见[文件传输](file-transfer.md)。