From cccf025599d97571c0b887e07963328806344dba Mon Sep 17 00:00:00 2001 From: liujinkun2025 <77097548+liujinkun2025@users.noreply.github.com> Date: Fri, 3 Jul 2026 11:39:07 +0800 Subject: [PATCH] docs(drive): document 30-char query limit for +search (#1560) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Search v2 API rejects queries longer than 30 characters (counted by Unicode code point, CJK 1 each) with 99992402 field validation failed — it is a hard error, not truncation. Surface this in the --query -h help text and the lark-drive search skill so callers compress long queries before searching instead of hitting the error. Change-Id: Ieb30a66edae7a573690c49719627ec8fb2500a1a --- shortcuts/drive/drive_search.go | 2 +- skills/lark-drive/references/lark-drive-search.md | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/shortcuts/drive/drive_search.go b/shortcuts/drive/drive_search.go index ca4ece03..dd513f6d 100644 --- a/shortcuts/drive/drive_search.go +++ b/shortcuts/drive/drive_search.go @@ -75,7 +75,7 @@ var DriveSearch = common.Shortcut{ AuthTypes: []string{"user", "bot"}, HasFormat: true, Flags: []common.Flag{ - {Name: "query", Desc: "search keyword (may be empty to browse by filter only)"}, + {Name: "query", Desc: "search keyword (may be empty to browse by filter only); max 30 characters by Unicode code point (CJK counts 1 each), over 30 the server rejects with 99992402 field validation failed"}, {Name: "mine", Type: "bool", Desc: "restrict to docs I own (server-side owner semantic, NOT original creator; uses current user's open_id)"}, {Name: "creator-ids", Desc: "comma-separated owner open_ids (API field is creator_ids but matched by owner); mutually exclusive with --mine"}, diff --git a/skills/lark-drive/references/lark-drive-search.md b/skills/lark-drive/references/lark-drive-search.md index 0021d14f..64e5e857 100644 --- a/skills/lark-drive/references/lark-drive-search.md +++ b/skills/lark-drive/references/lark-drive-search.md @@ -23,6 +23,8 @@ > 错误：`lark-cli drive +search 方案` > `+search` 不接受位置参数；空 `--query` 或省略 `--query` 表示纯靠 filter 浏览（合法）。 > +> **`--query` 最长 30 个字符**：按字符数（Unicode 码点）算，中文每字算 1 个，与 ASCII 同口径；超过 30 会被服务端拒绝（`99992402 field validation failed`，**是报错不是截断**）。长关键词必须先压缩成核心实体 + 主题词（如把整句问题压成「项目名 + 主题」再搜），不要把整句原问塞进 `--query`。 +> > **列表型请求不要硬塞关键词**：如果用户只是要求"我这月创建的所有文档"、"最近半年我编辑过的文档"、"按类型分类统计"这类范围浏览 / 汇总请求，且没有给出标题片段或业务关键词，应使用 `--query ""` 搭配 `--created-by-me`、`--mine`、`--created-*`、`--edited-*`、`--doc-types` 等过滤条件。不要把"查找"、"所有文档"、"最近更新过"、"按类型分类统计"这类动作词或统计意图放进 `--query`，否则会把本来应靠 filter 命中的结果过度收窄。 ### 自然语言 → 命令映射速查 @@ -101,7 +103,7 @@ lark-cli drive +search --query 方案 --page-token '' | 参数 | 必填 | 说明 | |---|---|---| -| `--query ` | 否 | 搜索关键词；支持服务端高级语法（`intitle:`、`""`、`OR`、`-`）。空字符串或省略表示纯 filter 浏览 | +| `--query ` | 否 | 搜索关键词；支持服务端高级语法（`intitle:`、`""`、`OR`、`-`）。空字符串或省略表示纯 filter 浏览。**长度上限 30 个字符（按 Unicode 码点算，中文每字算 1 个，与 ASCII 同口径）；超过 30 服务端直接报 `99992402 field validation failed`，不会截断** | | `--page-size ` | 否 | 每页数量，默认 15，最大 20。超过 20 自动 clamp；非正数（≤0）回落 15；**非数字值直接返回 validation 错误** | | `--page-token ` | 否 | 上一次响应里的 `page_token`，用于翻页 | | `--format` | 否 | `json`（默认）/ `pretty` |