@yandy0725/pi-lark 0.1.0

package/skills/lark-base/references/lark-base-form-detail.md

@@ -0,0 +1,71 @@
+# base +form-detail
+
+通过表单分享 token 读取表单详情。只读操作，适合在提交表单前解析题目结构、必填项、显示条件和附件提交所需的 Base token。
+
+## 何时使用
+
+- 用户给出 `/share/base/form/{shareToken}` 表单分享链接，先提取最后一段作为 `--share-token`。
+- 准备调用 `+form-submit` 前，必须先用 `+form-detail` 读取 `questions[]`。
+- 只知道分享链接、还不知道 `base-token` / `table-id` / `form-id` 时，用 `+form-detail`；已在 Base 内部管理表单时，才用 `+form-get`。
+
+```bash
+lark-cli base +form-detail --share-token <share_token> --format pretty
+```
+
+## 读取重点
+
+`+form-detail` 返回的关键字段：
+
+| 字段 | 用途 |
+|---|---|
+| `base_token` | 表单所属 Base；提交附件时必须传给 `+form-submit --base-token` |
+| `questions[].id` | 题目标识，通常对应字段 ID |
+| `questions[].title` | 提交时使用的字段名/题目名，以真实返回为准 |
+| `questions[].type` | 决定值格式；与字段类型和 `lark-base-cell-value.md` 对齐 |
+| `questions[].required` | 判断必填项 |
+| `questions[].filter` | 判断题目是否对当前提交可见；被隐藏的问题不要填写 |
+
+题目除固定字段外，会按类型携带动态配置，例如 `select.options` / `select.multiple`、`number.style`、`datetime.style.format`、`user.multiple`、`link.link_table`、`formula.expression`、`lookup.from/select/where/aggregate`。提交前按返回结构构造值，不要猜题目类型或选项。
+
+## filter 显示条件
+
+`questions[].filter` 控制题目显示/隐藏：
+
+```json
+{
+  "conjunction": "and",
+  "conditions": [
+    {"field_name": "是否携带家属", "operator": "is", "value": ["是"]},
+    {"field_name": "参与人数", "operator": "isGreater", "value": [1]}
+  ]
+}
+```
+
+- `conjunction` 为 `and` / `or`，表示条件全部满足或任一满足。
+- `conditions[].field_name` 引用其他题目的 `title`。
+- `conditions[].operator` 常见为 `is`、`isNot`、`contains`、`doesNotContain`、`isEmpty`、`isNotEmpty`、`isGreater`、`isGreaterEqual`、`isLess`、`isLessEqual`。
+- `isEmpty` / `isNotEmpty` 不需要 `value`。
+- 附件题目的 filter 只适合 `isEmpty` / `isNotEmpty`。
+
+如果当前已填写值不满足某题目的 `filter`，该题目视为隐藏，不应放入 `+form-submit --json.fields` 或 `--json.attachments`。
+
+## 与 form-submit 的关系
+
+提交普通字段：
+
+```bash
+lark-cli base +form-submit \
+  --share-token <share_token> \
+  --json '{"fields":{"姓名":"张三","评分":5}}'
+```
+
+提交附件字段：
+
+```bash
+lark-cli base +form-submit \
+  --share-token <share_token> \
+  --base-token <base_token_from_form_detail> \
+  --json '{"fields":{"姓名":"张三"},"attachments":{"附件":["./report.pdf"]}}'
+```
+
+附件字段不要写进 `fields`；放在顶层 `attachments`，值为本地文件路径数组。

package/skills/lark-base/references/lark-base-form-questions-create.md

@@ -0,0 +1,118 @@
+# base +form-questions-create
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+向多维表格表单/问卷中批量添加问题。
+
+## 命令
+
+```bash
+# 添加一个文本必填问题
+lark-cli base +form-questions-create \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[{"type":"text","title":"您的姓名是？","required":true}]'
+
+# 添加多个问题（按顺序排列）
+lark-cli base +form-questions-create \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[
+    {"type":"text","title":"您的姓名是？","required":true},
+    {"type":"text","title":"您的联系方式是？","required":false}
+  ]'
+
+# 添加单选题（带选项）
+lark-cli base +form-questions-create \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[{"type":"select","title":"满意度评价","required":true,"multiple":false,"options":[{"name":"非常满意","hue":"Green"},{"name":"满意","hue":"Blue"},{"name":"一般","hue":"Yellow"}]}]'
+
+# 添加评分题
+lark-cli base +form-questions-create \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[{"type":"number","title":"服务评分","style":{"type":"rating","icon":"star","min":1,"max":5}}]'
+  
+# 添加带描述的问题（纯文本）
+lark-cli base +form-questions-create \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[{"type":"text","title":"您的姓名","description":"请填写真实姓名"}]'
+# 添加带描述的问题（含链接）
+lark-cli base +form-questions-create \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[{"type":"text","title":"反馈建议","description":"更多详情请查看[帮助文档](https://example.com/help)"}]'  
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token（base_token） |
+| `--table-id <id>` | 是 | 数据表 ID |
+| `--form-id <id>` | 是 | 表单 ID |
+| `--questions <json>` | 是 | 问题 JSON 数组，最多 10 个（见下方格式） |
+| `--format` | 否 | 输出格式：json（默认）\| pretty \| table \| ndjson \| csv |
+| `--as` | 否 | 身份：user（默认）\| bot |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## `--questions` 格式
+
+每个问题对象支持以下字段：
+
+| 字段                    | 必填 | 说明 |
+|-----------------------|------|------|
+| `title`               | **是** | 问题标题（字段名） |
+| `type`                | **是** | 题目类型：`text`、`number`、`select`、`datetime`、`user`、`attachment`、`location` |
+| `description`         | 否 | 问题描述（纯文本或 Markdown 链接，如 `[文本](https://example.com)`） |
+| `required`            | 否 | 是否必填（true/false） |
+| `option_display_mode` | 否 | 选项展示方式（仅 `select` 有效）：`0`=下拉，`1`=纵向（默认），`2`=横向 |
+| `multiple`            | 否 | 是否多选（`select`/`user` 类型有效，bool） |
+| `options`             | 否 | 选项列表（仅 `select` 有效）：`[{"name":"选项1","hue":"Blue"}]`，hue 可选：`Red`/`Orange`/`Yellow`/`Green`/`Blue`/`Purple`/`Gray` |
+| `style`               | 否 | 字段样式配置（见下方说明） |
+
+### `style` 字段说明
+
+| 类型 | style 结构 | 说明 |
+|------|------|------|
+| `text` | `{"type":"plain"}` | 当前仅支持 `plain` |
+| `number` | `{"type":"plain","precision":2}` | precision 为小数位数 |
+| `number`（评分） | `{"type":"rating","icon":"star","min":1,"max":5}` | icon 可选：`star`/`heart`/`thumbsup`/`fire`/`smile`/`lightning`/`flower`/`number` |
+| `datetime` | `{"format":"yyyy/MM/dd"}` | format 可选：`yyyy/MM/dd`、`yyyy/MM/dd HH:mm`、`MM-dd`、`MM/dd/yyyy`、`dd/MM/yyyy` |
+
+## 输出格式
+
+返回创建成功的问题列表：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "items": [
+      {"id": "q_001", "title": "您的姓名是？", "required": true}
+    ]
+  }
+}
+```
+
+## 工作流
+
+> [!CAUTION]
+> 这是**写入操作** — 执行前必须向用户确认。
+
+1. 先用 `+form-questions-list` 查看现有问题
+2. 确认要添加的问题内容
+3. 执行命令并报告新建的问题 ID
+
+## 参考
+
+- [lark-base](../SKILL.md) — 多维表格全部命令
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/skills/lark-base/references/lark-base-form-questions-update.md

@@ -0,0 +1,92 @@
+# base +form-questions-update
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+批量更新多维表格表单/问卷中的问题（标题、描述、是否必填）。
+
+## 命令
+
+```bash
+# 更新一个问题的标题
+lark-cli base +form-questions-update \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[{"id":"q_001","title":"您的真实姓名是？"}]'
+
+# 同时更新多个问题
+lark-cli base +form-questions-update \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[
+    {"id":"q_001","title":"姓名（必填）","required":true},
+    {"id":"q_002","title":"联系方式","required":false}
+  ]'
+  
+# 更新问题描述（纯文本）
+lark-cli base +form-questions-update \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[{"id":"q_001","description":"请填写您的真实姓名"}]'
+# 更新问题描述（含链接）
+lark-cli base +form-questions-update \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --form-id <form_id> \
+  --questions '[{"id":"q_001","description":"更多说明请参考[帮助文档](https://example.com/help)"}]'  
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token（base_token） |
+| `--table-id <id>` | 是 | 数据表 ID |
+| `--form-id <id>` | 是 | 表单 ID |
+| `--questions <json>` | 是 | 问题更新 JSON 数组，最多 10 个（见下方格式） |
+| `--format` | 否 | 输出格式：json（默认）\| pretty \| table \| ndjson \| csv |
+| `--as` | 否 | 身份：user（默认）\| bot |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## `--questions` 格式
+
+每个问题对象必须包含 `id`，其余字段按需传入：
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `id` | **是** | 问题 ID（field_id），不可修改 |
+| `title` | 否 | 新的问题标题 |
+| `description` | 否 | 新的问题描述（纯文本或 Markdown 链接，如 `[文本](https://example.com)`） |
+| `required` | 否 | 是否必填 |
+| `option_display_mode` | 否 | 选项展示方式（仅 `select` 有效）：`0`=下拉，`1`=纵向（默认），`2`=横向 |
+
+## 输出格式
+
+返回更新后的问题列表：
+
+```json
+{
+  "ok": true,
+  "data": {
+    "items": [
+      {"id": "q_001", "title": "姓名（必填）", "required": true}
+    ]
+  }
+}
+```
+
+## 工作流
+
+> [!CAUTION]
+> 这是**写入操作** — 执行前必须向用户确认。
+
+1. 先用 `+form-questions-list` 获取现有问题及其 `id`
+2. 构造包含 `id` 的更新数组
+3. 执行命令并报告更新结果
+
+## 参考
+
+- [lark-base](../SKILL.md) — 多维表格全部命令
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/skills/lark-base/references/lark-base-form-submit.md

@@ -0,0 +1,170 @@
+# base +form-submit
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+通过表单分享链接填写并提交多维表格表单。仅支持分享模式（share_token），支持填写普通字段值和上传本地文件作为附件。
+
+## 填写前必读：先获取表单详情
+
+**在调用 `+form-submit` 之前，必须先使用 `+form-detail` 获取表单详情。** 原因如下：
+
+1. **字段类型匹配**：每个题目的 `type` 决定了值的格式（文本、数字、选项、人员、日期等），需根据类型正确构造 `fields` 中的值
+2. **必填校验**：通过 `questions[].required` 判断哪些题目为必填项，避免遗漏
+3. **显示条件过滤**：部分题目带有 `filter`（显示/隐藏逻辑），需根据用户已填的其他题目值判断该题目是否应该出现——**不应填写被 filter 隐藏的题目**
+4. **获取 base_token（附件场景必用）**：`+form-detail` 返回的 `data.base_token` 是该表单所属的多维表格标识。当表单包含附件字段时，提交时必须通过 `--base-token` 传入此值，因为附件需要上传到该 Base 的 Drive Media 中
+
+典型流程：
+
+```bash
+# 1️⃣ 先获取表单详情，了解所有题目
+lark-cli base +form-detail --share-token <share_token>
+
+# 2️⃣ 根据返回的 questions 列表，按 type 格式化值、检查 required、判断 filter 条件
+
+# 3️⃣ 再提交
+lark-cli base +form-submit \
+  --share-token <share_token> \
+  --json '{"fields":{...}}'
+```
+
+`+form-detail` 的返回中要重点读取 `questions[].type`、`questions[].required`、题目 `filter` 和附件场景所需的 `data.base_token`。
+
+## 命令
+
+```bash
+# 基本提交（填写普通字段）
+lark-cli base +form-submit \
+  --share-token <share_token> \
+  --json '{"fields":{"服务评分":5,"评价内容":"服务态度好"}}'
+
+# 带附件提交（需要额外提供 --base-token）
+lark-cli base +form-submit \
+  --share-token <share_token> \
+  --base-token <base_token> \
+  --json '{
+    "fields": {"服务评分": 5, "评价内容": "好"},
+    "attachments": {
+      "附件字段名": ["./report.pdf", "./photo.png"],
+      "另一个附件字段": ["./doc.docx"]
+    }
+  }'
+
+# 使用应用身份（bot）
+lark-cli base +form-submit \
+  --share-token <share_token> \
+  --json '{"fields":{...}}' \
+  --as bot
+
+# 预览 API 调用（不实际执行）
+lark-cli base +form-submit \
+  --share-token <share_token> \
+  --json '{"fields":{...}}' \
+  --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--share-token <token>` | 是 | 表单分享 Token（必填），从表单分享链接中提取 |
+| `--base-token <token>` | 条件必填 | Base token；**当 `--json` 包含 `attachments` 时必须提供**，用于将附件上传到 Base Drive Media |
+| `--json <json>` | 是 | JSON 对象，包含 `"fields"`（普通字段值）和 `"attachments"`（附件上传），详见下方说明 |
+| `--format` | 否 | 输出格式：json（默认）\| pretty \| table \| ndjson \| csv |
+| `--as` | 否 | 身份：user（默认）\| bot |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+### --json 结构说明
+
+`--json` 是一个 JSON 对象，包含两个部分：
+
+#### fields（普通字段）
+
+`fields` 中的单元格值写法与 [`lark-base-cell-value.md`](lark-base-cell-value.md) 完全对齐，填写前应先阅读该文档了解各类型的构造规则：
+
+```json
+{
+  "文本字段": "Hello World",
+  "电话字段": "13800000000",
+  "超链接字段": "https://example.com",
+  "数字字段": 12.5,
+  "单选字段": "选项A",
+  "多选字段": ["选项A", "选项B"],
+  "时间字段": "2026-04-27 14:30:00",
+  "复选框字段": true,
+  "人员字段": [{ "id": "ou_7094d131420c8749632145f08fbf114a" }],
+  "关联字段": [{ "id": "recXXXXXXXXXXXX" }],
+  "地理位置字段": { "lng": 116.397428, "lat": 39.90923 }
+}
+```
+
+> **注意：附件类型字段不要写在 `fields` 里。** `fields` 中不包含附件，附件有独立的填写方式，见下方「attachments（附件上传）」章节。
+
+> 自动编号、公式、创建/修改人、创建/修改时间等系统字段会自动填入，无需手动传入。
+
+#### attachments（附件上传）
+
+**附件字段的填写方式与 `fields` 中的普通单元格完全不同**，不能在 `fields` 里传 `file_token` 或其他附件格式。必须将附件字段单独放在 `--json` 的顶层 `attachments` 对象中，值为**本地文件路径数组**（不是 token）：
+
+```json
+{
+  "attachments": {
+    "附件字段名": ["./report.pdf", "./photo.png"],
+    "另一个附件字段": ["./doc.docx"]
+  }
+}
+```
+
+CLI 收到路径后会自动完成以下流程：
+1. 校验所有文件（存在性、大小 ≤2GB、常规文件）
+2. 并行上传到 Base Drive Media（并发上限 5，跨字段重复路径自动去重）
+3. 获取 `file_token` 后合并到最终表单提交内容中
+
+> 与 [`lark-base-cell-value.md`](lark-base-cell-value.md) 中 Record 场景的附件写法不同：Record 写入时附件走独立的 `+record-upload-attachment` 命令；而 `+form-submit` 只需在 `attachments` 中传本地路径，上传由 CLI 内部自动完成。
+
+### 从分享链接提取 share-token
+
+用户提供形如以下格式的表单分享链接时：
+
+```
+https://www.example.com/share/base/form/shrbcvST8eZy0vk8zjVZ1CAXNye
+```
+
+**提取方式：** 取 URL 路径最后一段作为 `--share-token`。
+
+以上述链接为例：
+
+- `share-token` = `shrbcvST8eZy0vk8zjVZ1CAXNye`
+
+```bash
+lark-cli base +form-submit \
+  --share-token shrbcvST8eZy0vk8zjVZ1CAXNye \
+  --json '{"fields":{...}}'
+```
+
+## 输出格式
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `can_submit_again` | bool | 是否可以再次填写 |
+
+```json
+{
+  "ok": true,
+  "data": {
+    "can_submit_again": true
+  }
+}
+```
+
+## 提示
+
+- 本命令仅支持通过表单分享链接（share_token）提交，不支持通过 base_token + table_id + view_id 方式提交
+- **当 `--json` 包含 `attachments` 时，必须额外提供 `--base-token`**，因为附件上传到 Base Drive Media 需要指定目标 Base
+- 附件字段只需在 `--json.attachments` 中提供本地路径即可，CLI 自动完成校验、并行上传、Token 获取和合并写入
+- 限流：单应用 20 QPS，单用户 5 QPS
+- 权限要求：`base:form:update`；使用 attachments 时还需 `docs:document.media:upload`
+
+## 参考
+
+- [lark-base](../SKILL.md) — 多维表格全部命令
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/skills/lark-base/references/lark-base-record-batch-create.md

@@ -0,0 +1,57 @@
+# base +record-batch-create
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+批量创建记录。
+
+## 适用场景（重点）
+
+- 适合导入 CSV / Excel、外部系统一次性写入新数据。
+- 先把输入数据映射到合适的字段类型，再组装 `fields + rows`。
+
+## 推荐命令
+
+```bash
+lark-cli base +record-batch-create --base-token <base_token> --table-id <table_id> \
+  --json '{"fields":["标题","状态"],"rows":[["任务 A","Open"],["任务 B","Done"]]}'
+
+lark-cli base +record-batch-create --base-token <base_token> --table-id <table_id> --json @batch-create.json
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token |
+| `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
+| `--json <body>` | 是 | 批量创建请求体，必须是 JSON 对象。支持直接传 JSON 字符串，或 `@<file_path>` 从文件读取 |
+
+## API
+
+`POST /open-apis/base/v3/bases/:base_token/tables/:table_id/records/batch_create`
+
+## `--json` 结构
+
+本节只说明 `+record-batch-create` 的外层 JSON 形状；CellValue 统一看 [lark-base-cell-value.md](lark-base-cell-value.md)。
+
+对象形态：`{"fields":[...],"rows":[...]}`。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `fields` | `string[]` | 是 | 字段 ID 或字段名数组 |
+| `rows` | `CellValue[][]` | 是 | 二维数组，每一行按 `fields` 同序给 cell；单次最多 200 行 |
+
+## 返回重点
+
+返回 `fields`、`field_id_list`、`record_id_list`、`data`，其中 `data` 与 `fields` 列顺序对齐。
+
+## 坑点
+
+- `fields` 与每行 `rows` 的列顺序必须一一对应。
+- 空单元格必须显式用 `null` 填充。
+- 单次最多 200 行，超出需分批写入。
+- select 写入未知选项时平台可能自动新增选项；如果不是要新增选项，先确认真实选项名。
+
+## 参考
+
+- [lark-base-cell-value.md](lark-base-cell-value.md) — CellValue 格式规范

package/skills/lark-base/references/lark-base-record-batch-update.md

@@ -0,0 +1,52 @@
+# base +record-batch-update (batch update)
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+批量更新记录（将同一份 `patch` 批量应用到一批 `record_id_list`）。
+
+## 推荐命令
+
+```bash
+lark-cli base +record-batch-update --base-token <base_token> --table-id <table_id> \
+  --json '{"record_id_list":["<record_id>"],"patch":{"状态":"完成"}}'
+
+lark-cli base +record-batch-update --base-token <base_token> --table-id <table_id> --json @batch-update.json
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token |
+| `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
+| `--json <body>` | 是 | 批量更新请求体，必须是 JSON 对象。支持直接传 JSON 字符串，或 `@<file_path>` 从文件读取 |
+
+## API
+
+`POST /open-apis/base/v3/bases/:base_token/tables/:table_id/records/batch_update`
+
+## `--json` 结构
+
+本节只说明 `+record-batch-update` 的外层 JSON 形状；CellValue 统一看 [lark-base-cell-value.md](lark-base-cell-value.md)。
+
+对象形态：`{"record_id_list":[...],"patch":{...}}`。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `record_id_list` | `string[]` | 是 | 要更新的记录 ID 列表（单次最多 200 条） |
+| `patch` | `Map<FieldNameOrID, CellValue>` | 是 | 字段更新对象；key 是字段名或字段 ID，value 是 `CellValue`；同一份 `patch` 会应用到 `record_id_list` 内所有记录 |
+
+## 返回重点
+
+返回 `record_id_list`、`update`，可选返回 `ignored_fields`；`update` 可能为空对象。
+
+## 坑点
+
+- 这是“同值批量更新”：所有 `record_id_list` 都应用同一份 `patch`。
+- `record_id_list` 最大 200 条，超过会被接口校验拒绝。
+- 命令不会自动做字段/行映射转换，传什么就发什么。
+- 如果 `patch` 包含只读字段，返回里可能出现 `ignored_fields`；这些字段不会被更新。
+
+## 参考
+
+- [lark-base-cell-value.md](lark-base-cell-value.md) — CellValue 格式规范

package/skills/lark-base/references/lark-base-record-history-list.md

@@ -0,0 +1,43 @@
+# base +record-history-list
+
+查询单条记录的变更历史。它返回历史事件，不返回记录当前值，也不支持整表审计扫描。
+
+## 推荐命令
+
+```bash
+lark-cli base +record-history-list \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --record-id <record_id>
+
+lark-cli base +record-history-list \
+  --base-token <base_token> \
+  --table-id <table_id> \
+  --record-id <record_id> \
+  --page-size 30 \
+  --max-version <next_max_version>
+```
+
+## 返回解释
+
+- 历史条目通常按版本号降序返回，最新在前。
+- 每条历史包含版本号、操作人、操作时间、操作类型和字段变更。
+- `create_time` 是秒级 Unix 时间戳。
+- `field_changes` 描述字段变更，重点看字段名/字段类型、`before` 和 `after`。
+- `activity_type` 常见值：`create`（创建记录）、`update`（编辑记录）、`delete`（删除记录）。
+
+以下字段类型的变化可能不会出现在 `field_changes` 中：
+
+- 计算字段：`formula`、`lookup`
+- 系统字段：自动编号、创建时间、创建人、修改时间、修改人
+
+## 翻页
+
+- 首次请求不传 `--max-version`。
+- 如果返回 `has_more=true`，取返回中的 `next_max_version` 作为下一次请求的 `--max-version`。
+- `--page-size` 默认 30，最大 50。
+
+## 注意
+
+- `table-id` 和 `record-id` 必须来自同一张表。
+- 这是单条记录历史，不是表级审计；需要查多条记录时串行调用。

package/skills/lark-base/references/lark-base-record-upsert.md

@@ -0,0 +1,63 @@
+# base +record-upsert
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+创建记录，或在带 `--record-id` 时更新记录。
+
+## 推荐命令
+
+```bash
+# 创建记录
+lark-cli base +record-upsert --base-token <base_token> --table-id <table_id> \
+  --json '{"项目名称":"Apollo","状态":"进行中"}'
+
+# 更新记录
+lark-cli base +record-upsert --base-token <base_token> --table-id <table_id> --record-id <record_id> \
+  --json '{"项目名称":"Apollo","状态":"完成","完成时间":"2026-03-24 10:00:00"}'
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--base-token <token>` | 是 | Base Token |
+| `--table-id <id_or_name>` | 是 | 表 ID 或表名 |
+| `--record-id <id>` | 否 | 传入时走更新，不传时走创建 |
+| `--json <body>` | 是 | 字段写入对象，类型 `Map<FieldNameOrID, CellValue>` |
+
+## API
+
+- 创建：`POST /open-apis/base/v3/bases/:base_token/tables/:table_id/records`
+- 更新：带 `--record-id` 时改走 `PATCH /records/:record_id`
+
+## `--json` 结构
+
+- `--json` 必须是 **JSON object map**，形状是 `Map<FieldNameOrID, CellValue>`。
+- key 是字段名或字段 ID；value 是该字段的 `CellValue`。
+- 一次请求里同一字段只用一种标识，避免重复写入冲突。
+- 写入前先 `+field-list` 确认字段类型和字段名/ID。
+- CellValue 统一看 [lark-base-cell-value.md](lark-base-cell-value.md)。
+
+```json
+{
+  "项目名称": "Apollo",
+  "状态": "进行中",
+  "完成时间": "2026-03-24 10:00:00"
+}
+```
+
+## 返回重点
+
+- 创建时返回 `record` 和 `created: true`。
+- 更新时返回 `record` 和 `updated: true`。
+- 如果写入了 `formula / lookup / created_at / updated_at / created_by / updated_by` 等只读字段，返回里可能出现 `ignored_fields`，这些字段不会被更新。
+
+## 坑点
+
+- 有 `--record-id` 就一定更新；不传就一定创建，不会自动查重或按业务键 upsert。
+- select 写入未知选项时平台可能自动新增选项；如果不是要新增选项，先用 `+field-list` / `+field-search-options` 确认真实选项名。
+- 这是写入操作，执行前必须确认目标表和字段。
+
+## 参考
+
+- [lark-base-cell-value.md](lark-base-cell-value.md) — CellValue 格式规范