diff --git a/skill-template/domains/base.md b/skill-template/domains/base.md index 1c6e4a813..b914a74a2 100644 --- a/skill-template/domains/base.md +++ b/skill-template/domains/base.md @@ -34,6 +34,7 @@ - **Base token 口径统一**:无论 Shortcut 还是原生 API,都统一使用 `base_token` - **附件字段**:上传本地文件时只能走 `lark-cli base +record-upload-attachment` +- **地理位置字段**:写入必须使用 `{lng,lat}`;读取、筛选和转文本等场景使用 `full_address` 字符串,筛选优先用包含匹配;只有公式能访问坐标 - **能力边界**:当前 `base/v3` 原生 spec 以单表 / 单记录 / 视图筛选配置为主,批量写入和旧 `search` 场景优先走 unified Shortcut 组合能力 - **视图重命名确认规则**:用户已经明确“把哪个视图改成什么名字”时,执行 `table.views patch` / 对应 shortcut 直接改名即可,不需要再补一句确认 - **删除确认规则(记录 / 字段 / 表)**:执行 `table.records delete / table.fields delete / tables delete` 或对应 shortcut 时,如果用户已经明确要求删除且目标明确,可以直接执行;只有目标不明确时才先追问 diff --git a/skills/lark-base/SKILL.md b/skills/lark-base/SKILL.md index 371191767..87549b19e 100644 --- a/skills/lark-base/SKILL.md +++ b/skills/lark-base/SKILL.md @@ -1,6 +1,6 @@ --- name: lark-base -version: 1.2.0 +version: 1.2.1 description: "当需要用 lark-cli 操作飞书多维表格(Base)时调用:搜索 Base、建表、字段管理、记录读写、记录分享链接、视图配置、历史查询,以及角色/表单/仪表盘管理/工作流;也适用于把旧的 +table / +field / +record 写法改成当前命令写法。涉及字段设计、公式字段、查找引用、跨表计算、行级派生指标、数据分析需求时也必须使用本 skill。" metadata: requires: @@ -216,6 +216,7 @@ metadata: |----------|------|-----------------------------------------------------------|------| | 存储字段 | 真实存用户输入的数据 | 可以 | 常见如文本、数字、日期、单选、多选、人员、关联 | | 附件字段 | 存储文件附件 | 不应直接按普通字段写 | 上传附件走 `+record-upload-attachment`;下载附件走 `+record-download-attachment`;删除附件走 `+record-remove-attachment` | +| 地理位置字段 | 存储坐标并由平台解析地址 | 可以 | 写入必须使用 `{lng,lat}`;读取、筛选和转文本等场景使用 `full_address` 字符串;只有公式能访问坐标 | | 系统字段 | 平台自动维护 | 不可以 | 常见如创建时间、更新时间、创建人、修改人、自动编号 | | `formula` 字段 | 通过表达式计算 | 不可以 | 只读字段 | | `lookup` 字段 | 通过跨表规则查找引用 | 不可以 | 只读字段 | @@ -230,6 +231,7 @@ metadata: | 读取原始记录明细 / 关键词检索 / 导出 | `+record-search / +record-list / +record-get` | 不要拿 `+data-query` 当取数命令 | | 上传附件到记录 | `+record-upload-attachment` | 不要用 `+record-upsert` / `+record-batch-*` 伪造附件值 | | 下载记录里的附件文件 | `+record-download-attachment --record-id --output `,可加 `--file-token ` 只下指定附件 | Base 附件必须用这个命令下载;用其他下载入口可能失败 | +| 写入地理位置 | `+record-upsert` / `+record-batch-*` 传 `{lng,lat}` | 不要把纯地址文本当成 CellValue | | 基于视图做筛选读取 | `+view-set-filter` + `+record-list` | 不要跳过视图筛选直接猜条件 | | 本地 Excel / CSV / `.base` 导入为 Base | `lark-cli drive +import --type bitable` | 不要误走 `+base-create`、`+table-create` 或 `+record-upsert` | diff --git a/skills/lark-base/references/lark-base-cell-value.md b/skills/lark-base/references/lark-base-cell-value.md index d308b029b..bb9cd6631 100644 --- a/skills/lark-base/references/lark-base-cell-value.md +++ b/skills/lark-base/references/lark-base-cell-value.md @@ -106,7 +106,7 @@ ### 2.8 location -用对象 `{lng, lat}`,两者都是数字;`lng` 是经度,`lat` 是纬度。 +写入对象必须使用 `{lng, lat}`,两者都是数字;`lng` 是经度,`lat` 是纬度。不需要手动传 `full_address`,平台会根据坐标解析地址。 ```json { @@ -117,6 +117,8 @@ } ``` +读取、筛选、转文本等场景使用 `full_address` 字符串;只有公式能访问坐标。如果用户只给地址文本,先获取或确认坐标后再写入;不要把仅有地址文本直接当作 location CellValue。 + ### 2.9 attachment(不作为普通 CellValue 写入) - 追加附件:使用 `lark-cli base +record-upload-attachment --record-id --field-id --file `;可重复 `--file` 一次追加多个附件,不能用普通记录操作接口写附件值。 diff --git a/skills/lark-base/references/lark-base-data-query.md b/skills/lark-base/references/lark-base-data-query.md index b63ee2e7f..2428252b8 100644 --- a/skills/lark-base/references/lark-base-data-query.md +++ b/skills/lark-base/references/lark-base-data-query.md @@ -277,6 +277,7 @@ POST /open-apis/base/v3/bases/:base_token/data/query | `isEmpty` / `isNotEmpty` | `[]` | 0 个 | `[]` | > **不支持** `isGreater` / `isGreaterEqual` / `isLess` / `isLessEqual`:地理位置无自然顺序。 +> location 按 `full_address` 字符串筛选,不支持经纬度空间筛选;查城市/片区时优先用 `contains`,避免用 `is` 匹配短地址词。 *`checkbox`* diff --git a/skills/lark-base/references/lark-base-field-update.md b/skills/lark-base/references/lark-base-field-update.md index 76511a4d2..a0f1de4ff 100644 --- a/skills/lark-base/references/lark-base-field-update.md +++ b/skills/lark-base/references/lark-base-field-update.md @@ -101,7 +101,7 @@ PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id | 目标类型 | 允许的源类型 | 说明 | |------|------|------| -| `text` | `number`、`select`、`datetime`、`created_at`、`updated_at`、`location`、`auto_number`、`checkbox` | 保留字符串表示;丢失原类型语义和结构化能力 | +| `text` | `number`、`select`、`datetime`、`created_at`、`updated_at`、`location`(只保留 `full_address`)、`auto_number`、`checkbox` | 保留字符串表示;丢失原类型语义和结构化能力 | | `number` | `text`、`number`、`datetime`、`created_at`、`updated_at`、`checkbox` | 保留可解析的数字值;无法解析的值会变空,原文本格式会丢失 | | `datetime` | `text`、`number`、`datetime`、`created_at`、`updated_at` | 保留可解析的时间字符串和时间戳;无法解析的值会变空,原文本格式会丢失 | | `select` | `text -> select`、`number -> select`、`single select -> multi select` | 只有完全匹配目标选项名的值会转成对应选项;没匹配上的值会被丢弃 | diff --git a/skills/lark-base/references/lark-base-shortcut-field-properties.md b/skills/lark-base/references/lark-base-shortcut-field-properties.md index ea6ebb1a3..e28e7f67f 100644 --- a/skills/lark-base/references/lark-base-shortcut-field-properties.md +++ b/skills/lark-base/references/lark-base-shortcut-field-properties.md @@ -464,6 +464,8 @@ { "type": "location", "name": "位置" } ``` +写入必须使用 `{lng,lat}`。location 读回会包含 `full_address`;筛选和 `location -> text` 类型转换按 `full_address` 字符串处理,只有公式能访问坐标。 + ```json { "type": "checkbox", "name": "完成" } ``` diff --git a/skills/lark-base/references/lark-base-view-set-filter.md b/skills/lark-base/references/lark-base-view-set-filter.md index 1bd0efada..568242233 100644 --- a/skills/lark-base/references/lark-base-view-set-filter.md +++ b/skills/lark-base/references/lark-base-view-set-filter.md @@ -30,7 +30,7 @@ ## 3. value 写法 -### `text` / `location` +### `text` 用字符串: @@ -38,6 +38,16 @@ ["标题", "intersects", "发布"] ``` +### `location` + +location 筛选只按 `full_address` 字符串匹配,不能直接按经纬度筛选;优先使用 `intersects` 做包含匹配,例如查深圳: + +```json +["位置", "intersects", "深圳"] +``` + +不推荐写 `["位置", "==", "深圳"]` 这类精确匹配,除非确保筛选值与完整 `full_address` 完全一致。 + ### `number` / `auto_number` 用数字: