From 33a41bee5e98f5956b78c817a5f9de45911c57f8 Mon Sep 17 00:00:00 2001 From: zgz2048 Date: Wed, 6 May 2026 16:18:34 +0800 Subject: [PATCH] docs(base): update location full_address guidance --- skill-template/domains/base.md | 1 + skills/lark-base/SKILL.md | 4 +++- skills/lark-base/references/lark-base-cell-value.md | 4 +++- skills/lark-base/references/lark-base-data-query.md | 1 + .../lark-base/references/lark-base-field-update.md | 2 +- .../lark-base-shortcut-field-properties.md | 2 ++ .../references/lark-base-view-set-filter.md | 12 +++++++++++- 7 files changed, 22 insertions(+), 4 deletions(-) diff --git a/skill-template/domains/base.md b/skill-template/domains/base.md index 1c6e4a813..1f9ea31b4 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 0a8218087..8da45197e 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: @@ -211,6 +211,7 @@ metadata: |----------|------|-----------------------------------------------------------|------| | 存储字段 | 真实存用户输入的数据 | 可以 | 常见如文本、数字、日期、单选、多选、人员、关联 | | 附件字段 | 存储文件附件 | 不应直接按普通字段写 | 上传附件走 `+record-upload-attachment`；下载附件走 `lark-cli docs +media-download` | +| 地理位置字段 | 存储坐标并由平台解析地址 | 可以 | 写入只传 `{lng,lat}`；读回包含 `full_address`；筛选和转文本都按 `full_address` 文本处理 | | 系统字段 | 平台自动维护 | 不可以 | 常见如创建时间、更新时间、创建人、修改人、自动编号 | | `formula` 字段 | 通过表达式计算 | 不可以 | 只读字段 | | `lookup` 字段 | 通过跨表规则查找引用 | 不可以 | 只读字段 | @@ -225,6 +226,7 @@ metadata: | 读取原始记录明细 / 关键词检索 / 导出 | `+record-search / +record-list / +record-get` | 不要拿 `+data-query` 当取数命令 | | 上传附件到记录 | `+record-upload-attachment` | 不要用 `+record-upsert` / `+record-batch-*` 伪造附件值 | | 下载记录里的附件文件 | `lark-cli docs +media-download --token --output ` | `file_token` 从 `+record-get` 返回的附件字段里取；用法见 [`../lark-doc/references/lark-doc-media-download.md`](../lark-doc/references/lark-doc-media-download.md) | +| 写入地理位置 | `+record-upsert` / `+record-batch-*` 传 `{lng,lat}` | 不要传 `full_address`；平台会按坐标换算最近可用地址 | | 基于视图做筛选读取 | `+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 7acbaf923..d539a1e7d 100644 --- a/skills/lark-base/references/lark-base-cell-value.md +++ b/skills/lark-base/references/lark-base-cell-value.md @@ -102,7 +102,7 @@ ### 2.8 location -用对象 `{lng, lat}`，两者都是数字；`lng` 是经度，`lat` 是纬度。 +写入用对象 `{lng, lat}`，两者都是数字；`lng` 是经度，`lat` 是纬度。不要传 `full_address`：平台会根据坐标解析最近可用地理位置，读回时单元格值会包含 `full_address`。 ```json { @@ -113,6 +113,8 @@ } ``` +读取、筛选、转文本时优先使用 `full_address`。如果用户只给地址文本，先获取或确认坐标后再写入，不能把地址文本当作 location CellValue。 + ### 2.9 attachment（不作为普通 CellValue 写入） 用户要把本地文件加到记录里时，必须使用 `lark-cli base +record-upload-attachment --file ` 上传到已有记录。不能用普通记录操作接口来上传附件。 diff --git a/skills/lark-base/references/lark-base-data-query.md b/skills/lark-base/references/lark-base-data-query.md index 9eae81c95..df234f3dd 100644 --- a/skills/lark-base/references/lark-base-data-query.md +++ b/skills/lark-base/references/lark-base-data-query.md @@ -258,6 +258,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 c81370609..d96972937 100644 --- a/skills/lark-base/references/lark-base-field-update.md +++ b/skills/lark-base/references/lark-base-field-update.md @@ -95,7 +95,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 a794e8853..3080bab37 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": "位置" } ``` +location 单元格写入只接受 `{lng,lat}` 坐标；读回会包含 `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 ec18a4c4f..02f2949df 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` 用数字：