@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.ec88bb5 → 0.1.0-dev.f3f0e48
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/miaoda/ai-data-processing/SKILL.md +4 -1
- package/miaoda/animation-skill/SKILL.md +348 -0
- package/miaoda/authz-cli/SKILL.md +1 -0
- package/miaoda/charts-skill/SKILL.md +264 -0
- package/miaoda/creative-to-fullstack/SKILL.md +64 -0
- package/miaoda/data-analysis/SKILL.md +151 -0
- package/miaoda/data-analysis/references/json-output-specification.md +277 -0
- package/miaoda/data-analysis/references/post-analysis-guide.md +77 -0
- package/miaoda/data-analysis/references/python-analysis-reference.md +272 -0
- package/miaoda/data-analysis/references/tmp-file-management-guide.md +100 -0
- package/miaoda/debug-investigation/SKILL.md +35 -23
- package/miaoda/extract-json-schema/SKILL.md +147 -0
- package/miaoda/feishu/SKILL.md +4 -4
- package/miaoda/forms-skill/SKILL.md +46 -4
- package/miaoda/lark-apps/SKILL.md +37 -0
- package/miaoda/lark-apps/references/openapi-key.md +80 -0
- package/miaoda/lark-apps-authz/SKILL.md +292 -0
- package/miaoda/lark-apps-authz/references/permission-points.md +39 -0
- package/miaoda/lark-apps-authz/references/role.md +122 -0
- package/miaoda/lark-apps-db/SKILL.md +227 -0
- package/miaoda/lark-apps-db/references/full-reference.md +424 -0
- package/miaoda/lark-apps-file/SKILL.md +216 -0
- package/miaoda/lark-apps-ops/SKILL.md +67 -0
- package/miaoda/lark-apps-ops/references/lark-apps-access-scope-get.md +30 -0
- package/miaoda/lark-apps-ops/references/lark-apps-access-scope-set.md +40 -0
- package/miaoda/lark-apps-ops/references/lark-apps-cache.md +62 -0
- package/miaoda/lark-apps-ops/references/lark-apps-env.md +46 -0
- package/miaoda/lark-apps-ops/references/lark-apps-export.md +46 -0
- package/miaoda/lark-apps-ops/references/lark-apps-local-dev.md +26 -0
- package/miaoda/lark-apps-ops/references/lark-apps-mcp.md +25 -0
- package/miaoda/lark-apps-ops/references/lark-apps-member.md +93 -0
- package/miaoda/lark-apps-ops/references/lark-apps-observability.md +46 -0
- package/miaoda/lark-apps-ops/references/lark-apps-plugin-install.md +36 -0
- package/miaoda/lark-apps-ops/references/lark-apps-plugin-list.md +23 -0
- package/miaoda/lark-apps-ops/references/lark-apps-plugin-uninstall.md +25 -0
- package/miaoda/lark-apps-ops/references/lark-apps-release-create.md +37 -0
- package/miaoda/lark-apps-ops/references/lark-apps-release-get.md +59 -0
- package/miaoda/lark-apps-ops/references/lark-apps-release-list.md +31 -0
- package/miaoda/lark-apps-ops/references/lark-apps-update.md +30 -0
- package/miaoda/lark-apps-ops/references/lark-apps-user-id-convert.md +63 -0
- package/miaoda/lark-apps-ops/references/openapi-key.md +80 -0
- package/miaoda/lark-design-prototype/DESIGN.md +603 -0
- package/miaoda/lark-design-prototype/SKILL.md +85 -0
- package/miaoda/lark-design-prototype/references/assets/card-illustration-library.md +113 -0
- package/miaoda/lark-design-prototype/references/case-matching.md +53 -0
- package/miaoda/lark-design-prototype/references/cases/conversational-ai-home.md +27 -0
- package/miaoda/lark-design-prototype/references/cases/data-table.md +30 -0
- package/miaoda/lark-design-prototype/references/cases/official-home.md +26 -0
- package/miaoda/lark-design-prototype/references/cases/workspace-home.md +34 -0
- package/miaoda/lark-design-prototype/references/color-roles.md +163 -0
- package/miaoda/lark-design-prototype/references/component-selection.md +134 -0
- package/miaoda/lark-design-prototype/references/design-quality-checklist.md +156 -0
- package/miaoda/lark-design-prototype/references/form-shell-patterns.md +77 -0
- package/miaoda/lark-design-prototype/references/icon-semantics.md +237 -0
- package/miaoda/lark-design-prototype/references/layout-interaction.md +164 -0
- package/miaoda/lark-design-prototype/references/page-contract.md +281 -0
- package/miaoda/lark-design-prototype/references/product-patterns.md +93 -0
- package/miaoda/lark-design-prototype/references/prompt-expansion.md +107 -0
- package/miaoda/lark-design-prototype/references/restoration-traps.md +113 -0
- package/miaoda/lark-design-prototype/references/token-semantics.md +112 -0
- package/miaoda/lark-design-prototype/references/visual-brief.md +125 -0
- package/miaoda/lark-design-prototype/references/visual-style-prompts.md +61 -0
- package/miaoda/lark-design-prototype/scripts/icon-query.mjs +272 -0
- package/miaoda/lark-design-prototype/scripts/token-query.mjs +76 -0
- package/miaoda/lark-design-prototype/scripts/verify-static-html.mjs +117 -0
- package/miaoda/miaoda-file/SKILL.md +1 -0
- package/miaoda/miaoda-sql/SKILL.md +21 -2
- package/miaoda/performance-review/SKILL.md +144 -0
- package/miaoda/performance-review/references/business-analyzer.md +139 -0
- package/miaoda/performance-review/references/examples.md +107 -0
- package/miaoda/semantic-search/SKILL.md +6 -4
- package/miaoda/table-skill/SKILL.md +2 -0
- package/{shared → miaoda}/testing-guide/SKILL.md +119 -13
- package/miaoda-design/lark-apps-comment/SKILL.md +119 -0
- package/miaoda-design/lark-apps-ops/SKILL.md +47 -0
- package/miaoda-design/lark-apps-ops/references/lark-apps-release-create.md +52 -0
- package/miaoda-design/lark-apps-ops/references/lark-apps-release-get.md +59 -0
- package/miaoda-design/lark-apps-ops/references/lark-apps-release-list.md +31 -0
- package/miaoda-design/lark-apps-ops/references/lark-apps-update.md +33 -0
- package/{shared → miaoda-modern}/charts-skill/SKILL.md +1 -1
- package/miaoda-modern/debug-investigation/SKILL.md +1 -1
- package/miaoda-modern/forms-skill/SKILL.md +70 -7
- package/{shared → miaoda-modern}/lark-apps/SKILL.md +5 -5
- package/miaoda-modern/lark-apps/references/openapi-key.md +80 -0
- package/miaoda-modern/lark-apps-ops/SKILL.md +67 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-access-scope-get.md +30 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-access-scope-set.md +40 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-cache.md +62 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-env.md +46 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-export.md +46 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-local-dev.md +26 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-mcp.md +25 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-member.md +93 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-observability.md +46 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-plugin-install.md +36 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-plugin-list.md +23 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-plugin-uninstall.md +25 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-release-create.md +37 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-release-get.md +59 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-release-list.md +31 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-update.md +30 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-user-id-convert.md +63 -0
- package/{shared/lark-apps → miaoda-modern/lark-apps-ops}/references/openapi-key.md +3 -3
- package/miaoda-modern/lark-design-prototype/DESIGN.md +603 -0
- package/miaoda-modern/lark-design-prototype/SKILL.md +85 -0
- package/miaoda-modern/lark-design-prototype/references/assets/card-illustration-library.md +113 -0
- package/miaoda-modern/lark-design-prototype/references/case-matching.md +53 -0
- package/miaoda-modern/lark-design-prototype/references/cases/conversational-ai-home.md +27 -0
- package/miaoda-modern/lark-design-prototype/references/cases/data-table.md +30 -0
- package/miaoda-modern/lark-design-prototype/references/cases/official-home.md +26 -0
- package/miaoda-modern/lark-design-prototype/references/cases/workspace-home.md +34 -0
- package/miaoda-modern/lark-design-prototype/references/color-roles.md +163 -0
- package/miaoda-modern/lark-design-prototype/references/component-selection.md +134 -0
- package/miaoda-modern/lark-design-prototype/references/design-quality-checklist.md +156 -0
- package/miaoda-modern/lark-design-prototype/references/form-shell-patterns.md +77 -0
- package/miaoda-modern/lark-design-prototype/references/icon-semantics.md +237 -0
- package/miaoda-modern/lark-design-prototype/references/layout-interaction.md +164 -0
- package/miaoda-modern/lark-design-prototype/references/page-contract.md +281 -0
- package/miaoda-modern/lark-design-prototype/references/product-patterns.md +93 -0
- package/miaoda-modern/lark-design-prototype/references/prompt-expansion.md +107 -0
- package/miaoda-modern/lark-design-prototype/references/restoration-traps.md +113 -0
- package/miaoda-modern/lark-design-prototype/references/token-semantics.md +112 -0
- package/miaoda-modern/lark-design-prototype/references/visual-brief.md +125 -0
- package/miaoda-modern/lark-design-prototype/references/visual-style-prompts.md +61 -0
- package/miaoda-modern/lark-design-prototype/scripts/icon-query.mjs +272 -0
- package/miaoda-modern/lark-design-prototype/scripts/token-query.mjs +76 -0
- package/miaoda-modern/lark-design-prototype/scripts/verify-static-html.mjs +117 -0
- package/miaoda-modern/memory/SKILL.md +86 -0
- package/{shared → miaoda-modern}/performance-review/SKILL.md +3 -3
- package/miaoda-modern/reviewer-usage/SKILL.md +113 -0
- package/package.json +1 -1
- package/shared/attachment/SKILL.md +5 -1
- package/shared/lark-cli/SKILL.md +221 -0
- package/shared/lark-cli/lark-base/README.md +61 -0
- package/shared/lark-cli/lark-base/references/lark-base-commands.md +123 -0
- package/shared/lark-cli/lark-calendar/README.md +158 -0
- package/shared/lark-cli/lark-calendar/references/lark-calendar-meeting.md +30 -0
- package/shared/lark-cli/lark-calendar/references/lark-calendar-room-find.md +108 -0
- package/shared/lark-cli/lark-calendar/references/lark-calendar-suggestion.md +120 -0
- package/shared/lark-cli/lark-contact/README.md +35 -0
- package/shared/lark-cli/lark-contact/references/lark-contact-get-user.md +13 -0
- package/shared/lark-cli/lark-contact/references/lark-contact-search-user.md +121 -0
- package/shared/lark-cli/lark-doc/README.md +68 -0
- package/shared/lark-cli/lark-doc/references/lark-doc-fetch.md +138 -0
- package/shared/lark-cli/lark-doc/references/lark-doc-history.md +61 -0
- package/shared/lark-cli/lark-drive/README.md +158 -0
- package/shared/lark-cli/lark-drive/references/lark-drive-batch-query-comments.md +44 -0
- package/shared/lark-cli/lark-drive/references/lark-drive-files-list.md +183 -0
- package/shared/lark-cli/lark-drive/references/lark-drive-list-replies.md +49 -0
- package/shared/lark-cli/lark-im/README.md +70 -0
- package/shared/lark-cli/lark-im/references/lark-im-chat-list.md +140 -0
- package/shared/lark-cli/lark-im/references/lark-im-chat-members-list.md +84 -0
- package/shared/lark-cli/lark-im/references/lark-im-chat-search.md +135 -0
- package/shared/lark-cli/lark-im/references/lark-im-reactions.md +232 -0
- package/shared/lark-cli/lark-minutes/README.md +51 -0
- package/shared/lark-cli/lark-minutes/references/lark-minutes-download.md +130 -0
- package/shared/lark-cli/lark-sheets/README.md +174 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-changeset.md +105 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-chart.md +46 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-conditional-format.md +42 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-filter-view.md +51 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-filter.md +42 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-float-image.md +43 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-formula-verify.md +64 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-history.md +70 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-pivot-table.md +44 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-read-data.md +287 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-search-replace.md +67 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-sheet-structure.md +52 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-sparkline.md +47 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-workbook.md +69 -0
- package/shared/lark-cli/lark-sheets/scripts/lark_detect_subtables.py +596 -0
- package/shared/lark-cli/lark-sheets/scripts/lark_inspect_workbook.py +193 -0
- package/shared/lark-cli/lark-sheets/scripts/lark_profile_table.py +616 -0
- package/shared/lark-cli/lark-sheets/scripts/lark_sheet_range.py +176 -0
- package/shared/lark-cli/lark-sheets/scripts/lark_sheet_read_cli.py +221 -0
- package/shared/lark-cli/lark-sheets/scripts/sheets_df.py +50 -0
- package/shared/lark-cli/lark-slides/README.md +87 -0
- package/shared/lark-cli/lark-slides/references/lark-slides-history.md +117 -0
- package/shared/lark-cli/lark-slides/references/lark-slides-xml-presentation-slide-get.md +108 -0
- package/shared/lark-cli/lark-slides/references/lark-slides-xml-presentations-get.md +77 -0
- package/shared/lark-cli/lark-task/README.md +93 -0
- package/shared/lark-cli/lark-task/references/lark-task-get-my-tasks.md +57 -0
- package/shared/lark-cli/lark-task/references/lark-task-get-related-tasks.md +49 -0
- package/shared/lark-cli/lark-task/references/lark-task-search.md +36 -0
- package/shared/lark-cli/lark-task/references/lark-task-tasklist-search.md +35 -0
- package/shared/lark-cli/lark-vc/README.md +40 -0
- package/shared/lark-cli/lark-vc/references/lark-vc-recording.md +31 -0
- package/shared/lark-cli/lark-whiteboard/README.md +34 -0
- package/shared/lark-cli/lark-whiteboard/references/lark-whiteboard-export.md +59 -0
- package/shared/lark-cli/lark-wiki/README.md +50 -0
- package/shared/lark-cli/lark-wiki/references/lark-wiki-node-get.md +70 -0
- package/shared/lark-cli/lark-wiki/references/lark-wiki-node-list.md +95 -0
- package/shared/lark-cli/lark-wiki/references/lark-wiki-space-list.md +68 -0
- package/miaoda-design/attachment/SKILL.md +0 -58
- package/shared/dev-channel-probe/SKILL.md +0 -40
- /package/{shared → miaoda}/memory/SKILL.md +0 -0
- /package/{shared → miaoda}/reviewer-usage/SKILL.md +0 -0
- /package/{shared → miaoda-modern}/animation-skill/SKILL.md +0 -0
- /package/{shared → miaoda-modern}/data-analysis/SKILL.md +0 -0
- /package/{shared → miaoda-modern}/data-analysis/references/json-output-specification.md +0 -0
- /package/{shared → miaoda-modern}/data-analysis/references/post-analysis-guide.md +0 -0
- /package/{shared → miaoda-modern}/data-analysis/references/python-analysis-reference.md +0 -0
- /package/{shared → miaoda-modern}/data-analysis/references/tmp-file-management-guide.md +0 -0
- /package/{shared → miaoda-modern}/extract-json-schema/SKILL.md +0 -0
- /package/{shared → miaoda-modern}/performance-review/references/business-analyzer.md +0 -0
- /package/{shared → miaoda-modern}/performance-review/references/examples.md +0 -0
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# Lark Sheet Float Image
|
|
2
|
+
|
|
3
|
+
## 使用场景
|
|
4
|
+
|
|
5
|
+
查看飞书表格中已有**浮动图片**对象的配置(悬浮在单元格上方的图片,不属于单元格内容;与随行走的单元格内嵌图片不同)。本 reference 覆盖 1 个只读 shortcut:
|
|
6
|
+
|
|
7
|
+
| 操作需求 | 使用工具 | 说明 |
|
|
8
|
+
|---------|---------|------|
|
|
9
|
+
| 查看已有浮动图片 | `+float-image-list` | 获取浮动图片的位置、大小和层级配置 |
|
|
10
|
+
|
|
11
|
+
## Shortcuts
|
|
12
|
+
|
|
13
|
+
| Shortcut | Risk | 分组 |
|
|
14
|
+
| --- | --- | --- |
|
|
15
|
+
| `+float-image-list` | read | 对象 |
|
|
16
|
+
|
|
17
|
+
## Flags
|
|
18
|
+
|
|
19
|
+
### `+float-image-list`
|
|
20
|
+
|
|
21
|
+
_公共四件套 · 系统:`--dry-run`_
|
|
22
|
+
|
|
23
|
+
| Flag | Type | 必填 | 说明 |
|
|
24
|
+
| --- | --- | --- | --- |
|
|
25
|
+
| `--float-image-id` | string | optional | 按 id 过滤;省略时列工作表全部 |
|
|
26
|
+
|
|
27
|
+
## Examples
|
|
28
|
+
|
|
29
|
+
公共四件套:所有 shortcut 顶部排列 `--url` / `--spreadsheet-token` / `--sheet-id` / `--sheet-name`(XOR)。浮动图片是 sheet 级对象。
|
|
30
|
+
|
|
31
|
+
### `+float-image-list`
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
lark-cli sheets +float-image-list --url "..." --sheet-id "$SID"
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
返回每张浮动图片的 `image_token` / `position` / `size` / `z-index` 等。
|
|
38
|
+
|
|
39
|
+
### Validate / DryRun / Execute 约束
|
|
40
|
+
|
|
41
|
+
- `Validate`:XOR 公共四件套。
|
|
42
|
+
- `DryRun`:输出请求模板,零网络副作用。
|
|
43
|
+
- `Execute`:发起浮动图片列表查询。
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Lark Sheet Formula Verify(+formula-verify)
|
|
2
|
+
|
|
3
|
+
> **本文定位**:飞书表格"公式是否真的零错误"的**只读**自检入口。`+formula-verify` 对指定子表(或整本工作簿)扫描公式与单元格值,一次调用聚合全表错误清单 + 编译失败清单 + 每类错误的定位与样本,让你快速核对一张表的公式健康度。它**不改动表格**。
|
|
4
|
+
|
|
5
|
+
## 为什么需要自检
|
|
6
|
+
|
|
7
|
+
飞书在线表格已经实时算好结果,但"算出来"和"算对了"是两件事。常见缺口:
|
|
8
|
+
|
|
9
|
+
- 公式编译失败 → 单元格落成文本(写入类操作留下的 `formula_errors[]` 是**编译失败**信号)。
|
|
10
|
+
- 公式编译成功但**运行时错误**:`#REF!` / `#DIV/0!` / `#VALUE!` / `#NAME?` / `#NULL!` / `#NUM!` / `#N/A`——这一类只看 `formula_errors[]` 看不到,必须扫单元格值。
|
|
11
|
+
|
|
12
|
+
`+formula-verify` 把两路信号合并成一份统一 JSON:一次调用聚合全表错误清单 + 编译失败清单 + 每类错误的定位与样本,AI 一眼就能定位问题。
|
|
13
|
+
|
|
14
|
+
## 调用契约
|
|
15
|
+
|
|
16
|
+
最小调用形态:
|
|
17
|
+
|
|
18
|
+
| 入参 | 含义 |
|
|
19
|
+
|---|---|
|
|
20
|
+
| `--url` / `--spreadsheet-token` | 表格定位(XOR 二选一,必填) |
|
|
21
|
+
| `--sheet-id` / `--sheet-name` | 限定子表(mutually exclusive;省略则扫全部可见子表) |
|
|
22
|
+
| `--range` | 限定 A1 范围;省略则用各 sheet 的 `current_region` |
|
|
23
|
+
| `--max-locations` | 每类错误样本上限,默认 20 |
|
|
24
|
+
| `--ai-only` | 只校验 AI 公式(`=AI(prompt, [range])`),跳过普通公式的 7 类 Excel 错误扫描。AI 公式是异步计算的:把这个 flag 配 `--range` 当写后的**第一次抽样检查**,不要用 `+cells-get` 轮询;抽样里没有明确的 failed / unsupported 状态时,可以在告知用户「计算仍在后台进行」的前提下继续交付,不必卡着等 pending 公式算完 |
|
|
25
|
+
| `--exit-on-error` | `status='errors_found'` 时返回非 0 退出码(CI 网关用) |
|
|
26
|
+
|
|
27
|
+
返回核心字段:
|
|
28
|
+
|
|
29
|
+
- `status` ∈ `success` / `errors_found` / `partial`——**唯一可机读的健康度判据**。
|
|
30
|
+
- `total_errors` / `total_formulas` / `scanned_cells`——本次扫描规模指标。
|
|
31
|
+
- `has_more`——为 true 表示扫描被内部上限截断(详见后文「截断与续读」),未覆盖完整范围。
|
|
32
|
+
- `error_summary[<错误类型>]`——每类错误的 `count` / `locations[]` / `samples[].{address,formula,depends_on}`。
|
|
33
|
+
- `compile_errors[]`——合并最近一次写入留下的编译失败清单,与运行时错误并存时同时出现。
|
|
34
|
+
- `warning_message`——仅在 `has_more=true` 时出现,告知调用方需要缩小 `--range` / 拆 `--sheet-id` 续读。
|
|
35
|
+
|
|
36
|
+
## 结果判读规则
|
|
37
|
+
|
|
38
|
+
- `status='success'` → 该扫描范围内公式零错误。
|
|
39
|
+
- `status='partial'` → 扫描被内部上限截断,只覆盖了一部分。先缩小 `--range` 或拆 `--sheet-id` 续扫,**不允许**把 `partial` 当作 `success`。
|
|
40
|
+
- `status='errors_found'` 且 `compile_errors[]` 非空 → 存在编译失败(这些单元格此刻是文本、不是公式);按 `compile_errors[].reason` 定位是哪类语法问题(飞书函数名 / 范围语法 / 引用样式)。
|
|
41
|
+
- `status='errors_found'` 且只剩运行时错误 → 按 `error_summary` 的 `samples[].formula` + `depends_on` 排查根因(零除?空值参与运算?引用越界?日期差写法?数组语义?)。
|
|
42
|
+
|
|
43
|
+
注意:
|
|
44
|
+
|
|
45
|
+
- "编译失败但运行时无报错"不算 zero-error(编译失败的单元格此刻是文本不是公式,源数据一变就再也算不出值)。
|
|
46
|
+
- 靠肉眼读首末 5 行确认是不可靠的——表中段、隐藏行、合并区里的错误这样根本看不到。
|
|
47
|
+
- 修复公式属于写操作,不在本只读命令的范围内;把 `+formula-verify` 报出的错误定位转述给用户即可。
|
|
48
|
+
|
|
49
|
+
## 截断与续读
|
|
50
|
+
|
|
51
|
+
后端有一个内部硬上限对总扫描单元格数做截断(不暴露给调用方),超过后立即返回 `has_more=true` + `warning_message`,`error_summary` / `compile_errors` 仅覆盖已扫描部分。处理路径:
|
|
52
|
+
|
|
53
|
+
- 把工作簿按 `--sheet-id` / `--sheet-name` 拆成多次调用。
|
|
54
|
+
- 同 sheet 内按 `--range` 切片(如先 `A1:Z200` 再 `AA1:AZ200`),逐块自检。
|
|
55
|
+
- 每块都跑到 `has_more=false` 且 `status='success'` 才算这块通过。
|
|
56
|
+
|
|
57
|
+
## 常见陷阱
|
|
58
|
+
|
|
59
|
+
| 坑 | 应对 |
|
|
60
|
+
|---|---|
|
|
61
|
+
| 错误字符串本地化 | 后端按内部 `error_kind` / `compute_status` 字段识别错误类别,不走字符串匹配;调用方拿到的 7 类英文错误代码由后端统一规范输出,与 locale 无关。 |
|
|
62
|
+
| `formatted_value` 可能隐藏错误 | 某些条件格式 / 自定义数字格式会把 `#DIV/0!` 显示成空白。后端直接读 cell `error_kind`,不依赖 `formatted_value`,绕开此类被遮蔽。 |
|
|
63
|
+
| 把 `partial` 当 `success` | `partial` 仅表示**已扫描部分**无错误,剩余区域未知。必须续扫直到 `has_more=false` 且 `status='success'` 才能算通过。 |
|
|
64
|
+
| 编译失败 vs 运行时错误 | 同一份报告里 `compile_errors[]` 与 `error_summary` 并存。先看 `compile_errors[]`(编译失败)、再看运行时错误。 |
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# Lark Sheet History
|
|
2
|
+
|
|
3
|
+
## 概念回顾
|
|
4
|
+
|
|
5
|
+
每张飞书电子表格保留一串历史版本(`minor_histories`)。每个版本由 `history_version_id` 标识,并附带创建时间(`create_time`)、动作(`action`)与块修订信息(`all_block_revision`)。历史是**工作簿级**的(针对整张电子表格,不针对单个子表)。
|
|
6
|
+
|
|
7
|
+
`+history-list` 读取版本列表;`+history-revert-status` 轮询某次回滚任务的状态(进行中 / 成功 / 失败)。若只是想拿**当前文档版本号(revision)**当作 `+changeset-get` 的起点锚点,直接用 `+revision-get`(见 `lark-sheets-workbook`)更轻量。
|
|
8
|
+
|
|
9
|
+
## 使用场景
|
|
10
|
+
|
|
11
|
+
读取历史版本列表、查询回滚状态。本 reference 覆盖 2 个只读 shortcut:
|
|
12
|
+
|
|
13
|
+
| 操作需求 | 使用工具 | 说明 |
|
|
14
|
+
|---------|---------|------|
|
|
15
|
+
| 查看历史版本列表 | `+history-list` | 返回 `minor_histories`,每条含 `history_version_id` / `create_time` / `action` / `all_block_revision` 四个字段;支持向前分页(可选 `--end-version`) |
|
|
16
|
+
| 查询回滚状态 | `+history-revert-status` | 传入 `--transaction-id`(回滚任务的异步受理标识);轮询某次回滚的进行中 / 成功 / 失败状态 |
|
|
17
|
+
|
|
18
|
+
**注意事项(必须了解)**:
|
|
19
|
+
- **历史是工作簿级**:定位只需 `--url` / `--spreadsheet-token`(XOR),不需要子表选择器。
|
|
20
|
+
- **`+history-list` 倒序分页**:首次查省略 `--end-version`,返回最新一页;若响应里附带 `next_end_version` 与 `has_more=true`,把 `next_end_version` 作为下一次的 `--end-version` 即可继续向更早翻页;当响应**不包含**这两个字段时表示已到最早一页,不必再翻。
|
|
21
|
+
- **`+history-revert-status` 是只读轮询**:`--transaction-id` 是某次回滚任务的受理标识;回滚本身是高风险写操作,不在本只读集合内。
|
|
22
|
+
|
|
23
|
+
## Shortcuts
|
|
24
|
+
|
|
25
|
+
| Shortcut | Risk | 分组 |
|
|
26
|
+
| --- | --- | --- |
|
|
27
|
+
| `+history-list` | read | 历史版本 |
|
|
28
|
+
| `+history-revert-status` | read | 历史版本 |
|
|
29
|
+
|
|
30
|
+
## Flags
|
|
31
|
+
|
|
32
|
+
### `+history-list`
|
|
33
|
+
|
|
34
|
+
_公共:URL/token(无 sheet 定位) · 系统:`--dry-run`_
|
|
35
|
+
|
|
36
|
+
| Flag | Type | 必填 | 说明 |
|
|
37
|
+
| --- | --- | --- | --- |
|
|
38
|
+
| `--end-version` | int | optional | 分页查询的最大版本(倒序);首次查询省略,下一页传上一页返回的 next_end_version。 |
|
|
39
|
+
|
|
40
|
+
### `+history-revert-status`
|
|
41
|
+
|
|
42
|
+
_公共:URL/token(无 sheet 定位) · 系统:`--dry-run`_
|
|
43
|
+
|
|
44
|
+
| Flag | Type | 必填 | 说明 |
|
|
45
|
+
| --- | --- | --- | --- |
|
|
46
|
+
| `--transaction-id` | string | required | 异步回滚的受理标识 |
|
|
47
|
+
|
|
48
|
+
## Examples
|
|
49
|
+
|
|
50
|
+
公共定位:所有 shortcut 顶部排列 `--url` / `--spreadsheet-token`(XOR,二选一)。
|
|
51
|
+
|
|
52
|
+
### `+history-list`
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
# 列出某张电子表格的最新一页历史版本
|
|
56
|
+
lark-cli sheets +history-list --url "https://sample.feishu.cn/sheets/SHTxxxxxx"
|
|
57
|
+
|
|
58
|
+
# 用原始 spreadsheet token 定位
|
|
59
|
+
lark-cli sheets +history-list --spreadsheet-token "SHTxxxxxx"
|
|
60
|
+
|
|
61
|
+
# 翻到下一页:把上次响应里的 next_end_version 作为 --end-version 传入
|
|
62
|
+
lark-cli sheets +history-list --url "https://sample.feishu.cn/sheets/SHTxxxxxx" --end-version 12345
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### `+history-revert-status`
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
# 查询某次回滚的当前状态(进行中 / 成功 / 失败)
|
|
69
|
+
lark-cli sheets +history-revert-status --url "https://sample.feishu.cn/sheets/SHTxxxxxx" --transaction-id "<transaction-id>"
|
|
70
|
+
```
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Lark Sheet Pivot Table
|
|
2
|
+
|
|
3
|
+
## 使用场景
|
|
4
|
+
|
|
5
|
+
查看飞书表格中已有数据透视表对象的配置。本 reference 覆盖 1 个只读 shortcut:
|
|
6
|
+
|
|
7
|
+
| 操作需求 | 使用工具 | 说明 |
|
|
8
|
+
|---------|---------|------|
|
|
9
|
+
| 查看已有透视表 | `+pivot-list` | 获取透视表的结构、数据源、配置与展开后的占用区域 |
|
|
10
|
+
|
|
11
|
+
## Shortcuts
|
|
12
|
+
|
|
13
|
+
| Shortcut | Risk | 分组 |
|
|
14
|
+
| --- | --- | --- |
|
|
15
|
+
| `+pivot-list` | read | 对象 |
|
|
16
|
+
|
|
17
|
+
## Flags
|
|
18
|
+
|
|
19
|
+
### `+pivot-list`
|
|
20
|
+
|
|
21
|
+
_公共四件套 · 系统:`--dry-run`_
|
|
22
|
+
|
|
23
|
+
| Flag | Type | 必填 | 说明 |
|
|
24
|
+
| --- | --- | --- | --- |
|
|
25
|
+
| `--pivot-table-id` | string | optional | 按 id 过滤 |
|
|
26
|
+
|
|
27
|
+
## Examples
|
|
28
|
+
|
|
29
|
+
公共四件套:所有 shortcut 顶部排列 `--url` / `--spreadsheet-token` / `--sheet-id` / `--sheet-name`(XOR)。
|
|
30
|
+
|
|
31
|
+
### `+pivot-list`
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
lark-cli sheets +pivot-list --url "..." --sheet-id "$SID"
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
> **返回值含 `info`(展开后的占用区域与状态)**:每个透视表对象除 `position` / `snapshot` 外,还返回 `info`,标明它在 sheet 上的平铺区域与状态——`info.page_range`(筛选/分页区 A1)、`info.content_range`(主体数据区 A1)、`info.span_range`(空表合并区 A1)、`info.error_state`(错误状态,如 `None`/`Cover`/`Shrink`/`Loading`)、`info.is_empty` / `info.is_hidden`、`info.row`/`info.col`(锚点)等。
|
|
38
|
+
> **用途(判断某单元格是否属于透视表)**:读到某单元格要判断它是普通单元格还是透视产物时,先 `+pivot-list` 拿 `info`,看该单元格是否落在 `page_range` / `content_range` 内——落在区域内即属于某个透视表(透视表单元格不能当普通单元格解读),落在区域外则是普通单元格。
|
|
39
|
+
|
|
40
|
+
### Validate / DryRun / Execute 约束
|
|
41
|
+
|
|
42
|
+
- `Validate`:`--url` / `--spreadsheet-token` XOR 必填;`--sheet-id` / `--sheet-name` XOR 必填一个。
|
|
43
|
+
- `DryRun`:输出请求模板,零网络副作用。
|
|
44
|
+
- `Execute`:发起透视表列表查询。
|
|
@@ -0,0 +1,287 @@
|
|
|
1
|
+
# Lark Sheet Read Data
|
|
2
|
+
|
|
3
|
+
## 列格式多样性预探(写公式 / 排序 / 筛选前必做)
|
|
4
|
+
|
|
5
|
+
> 本节给出"写公式 / 排序 / 筛选前先探清列格式多样性"的正确流程,是「读全再写」原则在 read_data 工具层的落地。
|
|
6
|
+
|
|
7
|
+
对参与后续**计算 / 排序 / 筛选 / 公式提取**的列,**必须**先 sample **至少 50 行**(小表则全量),识别该列所有值类型变体后再设计公式 / 条件。只看前 10 行不够,因为下列差异通常潜伏在表尾或中段:
|
|
8
|
+
|
|
9
|
+
- **日期列同时出现多种格式**:`YYYYMM`、`YYYY-MM-DD`、`YYYY/M/D`、带时间戳、文本"未知"
|
|
10
|
+
- **数值列混入公式文本 / 单位 / 注释**:`1000+200=1200`、`100元`、`/(合同未明确)`、`#N/A`
|
|
11
|
+
- **空值与 0 / "0" 混杂**
|
|
12
|
+
- **大小写 / 全角半角差异**("办公费" vs "办公费 "、"Sales" vs "sales")
|
|
13
|
+
|
|
14
|
+
预探后必须在公式 / 筛选条件里用 `IFERROR` / `IFS` / 提取数值的辅助列处理所有变体;不能为了通过 head(10) 的样本就直接落地。一旦设计的逻辑只覆盖 sample 中出现的格式,就属于违规。
|
|
15
|
+
|
|
16
|
+
⚠️ **大数字(15 位以上的身份证 / 参考号 / 流水号)做去重 / 比较时禁止用 `+csv-get` 的显示值**:`+csv-get` 返回的是**格式化显示值**,15 位以上数字会被显示成 `1.04E+14` 这类科学计数法——多个本不相同的号在显示层全变成同一个 `1.04E+14`,拿去判重会**整列误判为重复**。比较 / 去重 / 匹配大数字时必须改用 `+cells-get`(取原始精确值)或把该列读为文本,禁止用 csv-get 的科学计数显示值(反例:大批长参考号被显示成科学计数后,互不相同的号全变成同一个值,被当成整列重复并错误高亮)。
|
|
17
|
+
|
|
18
|
+
## 使用场景
|
|
19
|
+
|
|
20
|
+
读取。从飞书表格中读取单元格数据。本 reference 覆盖 4 个 shortcut,按读取目的选择:
|
|
21
|
+
|
|
22
|
+
| 读取目的 | 用这个 shortcut | 数据去向 | 说明 |
|
|
23
|
+
|---------|----------------|---------|------|
|
|
24
|
+
| 快速查看纯值数据、批量处理 | `+csv-get` | 对话上下文 | 返回标准 CSV(`csv` 字段,可直接喂 csv.reader);**不传 `--max-chars` 即读全量**,大表由 CLI 内部分批取回拼接。要按字面行号逐行定位时加 `--include-row-prefix` 拿回 `[row=N]` 版本 |
|
|
25
|
+
| 按列类型结构化读出(喂 DataFrame) | `+table-get` | 对话上下文 | 返回 typed 协议(`columns:[列名]` + `data` + `dtypes`/`formats` + `range`),输出形状对齐 pandas split;可一行 `pd.DataFrame(sheet["data"], columns=sheet["columns"]).astype(sheet["dtypes"])` 还原 DataFrame。不带 `--range` 时读**完整 used range**(跨过表中部空行 / 空列),每个子表回传实际读取范围 `range` 供完整性校验;used range 超 20 万格时会被拒绝并给出替代命令——每格是一个对象,体积约为 `+csv-get` 的 17 倍,整表读走 `+csv-get`;不传 `--max-chars` 时读全量;显式给了才会截断,此时该子表带 `truncated: true` 与 `truncation_warning`。回执的 `complete` 是读全判据,`complete:false` 必定伴随非零退出码。注意这与下文 `current_region` "遇表中部空行截断"不矛盾:`+table-get` 读的是子表物理 used range(飞书记录的已用矩形,含中间空行),`current_region` 是从锚点连通扩展、遇整行空行就断 |
|
|
26
|
+
| 查看公式、样式、批注、数据验证 | `+cells-get` | 对话上下文 | 返回单元格完整信息,token 开销较大 |
|
|
27
|
+
| 查看某区域的下拉框(数据验证)选项 | `+dropdown-get` | 对话上下文 | 返回该 A1 范围已配置的下拉列表选项 |
|
|
28
|
+
|
|
29
|
+
**选择原则**:
|
|
30
|
+
- 只看值或做数据处理 → `+csv-get`;默认读全量,结果超出 stdout 阈值时自动落盘、路径写在回执里
|
|
31
|
+
- 要按列类型结构化读出(喂 DataFrame)→ `+table-get`
|
|
32
|
+
- 需要公式/样式/批注 → `+cells-get`
|
|
33
|
+
- 只想知道某区域下拉框有哪些选项 → `+dropdown-get`
|
|
34
|
+
|
|
35
|
+
## 读表理解脚本(Agent 优先入口)
|
|
36
|
+
|
|
37
|
+
当目标是"先理解表格内容 / 结构 / 子表边界"时,优先用本 skill 随包分发的只读理解脚本 `scripts/lark_*.py`(与本文件同级的 `scripts/` 目录),再决定是否直接调用上述 shortcut。脚本是可选捷径,不是必经入口——脚本不可用时直接按下表右列的 CLI 等价路径执行:如果任务很小,或需要公式 / 样式 / 批注 / 精确原始值等脚本未覆盖的信息,可以直接用 CLI 做等价或更精细读取。
|
|
38
|
+
|
|
39
|
+
| 脚本 | 底层 shortcut | 适用场景 |
|
|
40
|
+
| --- | --- | --- |
|
|
41
|
+
| `scripts/lark_inspect_workbook.py` | `+workbook-info` / `+sheet-info` / `+csv-get` | 在线表格第一步预检:拿 sheet 清单、布局、预览、`current_region` |
|
|
42
|
+
| `scripts/lark_detect_subtables.py` | `+workbook-info` / `+sheet-info --include merges,hidden_rows,hidden_cols` / 小窗口 `+csv-get` | 同一 sheet 可能有多个表格区域、汇总块、备注块时,在**已知且未截断的窗口**内识别候选子表 range |
|
|
43
|
+
| `scripts/lark_profile_table.py` | `+csv-get` / `+sheet-info --include hidden_rows,hidden_cols`(默认包含隐藏行列时;必要时再手工 `+cells-get` / `+table-get`) | 对**已确认且未截断的候选 range**做表头、数据范围、列类型、特殊行画像,并输出 `summary` / `field_map` / `risk_warnings` / `write_hints` |
|
|
44
|
+
|
|
45
|
+
(`scripts/lark_sheet_range.py` 与 `scripts/lark_sheet_read_cli.py` 是上面三个脚本 import 的公共库,不单独调用。)
|
|
46
|
+
|
|
47
|
+
`lark_profile_table.py` 是**启发式画像**,不是最终判定器:它能降低手工数行列和漏看特殊行的风险,但表头、多行标题、数据末行、列类型、特殊行和追加列都可能需要二次确认。汇总、去重、lookup / 匹配、透视 / 图表范围推导等操作前,不能只凭 profile 结果下结论;必须把 profile 输出与任务语义、样本值、必要的 CLI 补读一起核对。
|
|
48
|
+
|
|
49
|
+
`lark_profile_table.py` 的使用口径:
|
|
50
|
+
|
|
51
|
+
| 任务类型 | 建议 |
|
|
52
|
+
| --- | --- |
|
|
53
|
+
| 只读取用户明确指定的单个单元格 / 很小范围,且不需要理解整表 | 可直接用 CLI |
|
|
54
|
+
| 统计 / 汇总、排序筛选核对、去重、lookup / 匹配、条件与范围推导 | 优先对目标区域运行 `lark_profile_table.py`;若已用等价 CLI 明确确认表头、数据范围、字段列、列类型和特殊行,可跳过脚本。去重 / lookup 若目标列含 `long_numeric_like_id`、前导 0 或格式化数字,profile 只能定位列,比较值必须改用 `+cells-get` 或 `+table-get` |
|
|
55
|
+
| 多块表、表头不确定、存在合并 / 汇总 / 空行 / 备注块、选区是单格但任务语义是整表 | 先 `lark_detect_subtables.py` 或补充 CLI 确认候选范围,再对目标 range 跑 `lark_profile_table.py` |
|
|
56
|
+
| 需要公式、样式、批注、数据验证、精确原始值、长数字 ID 精确比较 | 先用脚本形成结构化理解,再按需补 `+cells-get` / `+table-get` / 分批 `+csv-get` |
|
|
57
|
+
|
|
58
|
+
推荐链路(大表先定窗口,脚本不接受截断结果):
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
python scripts/lark_inspect_workbook.py --url "<表格URL>"
|
|
62
|
+
# 先用 +workbook-info 和小窗口 +csv-get 确认真实 sheet、列边界和起始区域;大表按行窗口推进。
|
|
63
|
+
python scripts/lark_detect_subtables.py --url "<表格URL>" --sheet-name "<子表名>" --range "A1:H200"
|
|
64
|
+
python scripts/lark_profile_table.py --url "<表格URL>" --sheet-name "<子表名>" --range "A1:H200"
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
`lark_detect_subtables.py` / `lark_profile_table.py` 显式传小 `--max-chars` 控制体量,因此仍可能命中 `has_more`;命中时它们以错误退出并报告已读取的 `actual_range`,绝不基于半截数据给出候选范围或画像。遇到此错误,以 `actual_range` 为已完成窗口,缩小列数或从其末行之后继续读;跨窗口的候选范围、汇总行必须再用 CLI 核对,不能把单个窗口结果当整表结论。
|
|
68
|
+
|
|
69
|
+
脚本只读,不做任何写入。它们的输出用于降低 token 和定位错误;后续需要公式、样式、批注、精确原始值时,仍按本文件规则直接调用 `+cells-get` / `+table-get` / `+csv-get`。使用了 `lark_profile_table.py` 后下结论前,至少读取并使用这些字段:`summary.header_row`、`summary.data_range`、`summary.data_row_segments`、`field_map`、`risk_warnings`、`visibility` 和 `special_rows`。仅当 `risk_warnings` 不含 `data_range_has_gaps` 时,才可把 `data_range` 当连续数据范围;有缺口时按 `data_row_segments` 分段读取。
|
|
70
|
+
|
|
71
|
+
脚本关键 flag:
|
|
72
|
+
|
|
73
|
+
| Flag | 脚本 / 默认 | 何时调整 |
|
|
74
|
+
| --- | --- | --- |
|
|
75
|
+
| `--skip-hidden` | profile / detect,关闭(默认包含隐藏行列) | 只分析可见数据时开启;此时必须使用 profile 的 `data_row_segments`,不要把连续 `data_range` 直接当真实连续区间。 |
|
|
76
|
+
| `--max-chars` | inspect `8000`;profile / detect `25000` | 输出过大时缩小范围或降低值;profile / detect 若截断会报错并给 `actual_range`,按窗口继续。 |
|
|
77
|
+
| `--header-scan-rows` | profile `20` | 表头前有多行标题、说明或空行时提高;过大时结合 `possible_multi_row_header` 补读确认,不要仅凭评分结果下结论。 |
|
|
78
|
+
| `--max-sheets` | inspect `3` | 未指定 sheet 时仅前 N 个 sheet 带 layout / preview,其余仍返回摘要并在 warnings 说明。 |
|
|
79
|
+
| `--max-merge-components` | detect `2000` | 超限会跳过 gap 合并并告警;需缩小窗口或人工复核子表边界。 |
|
|
80
|
+
| `--gap-rows` / `--gap-cols` | detect `1` / `0` | 子表被切碎或粘连时调整;每次调整后复核候选范围。 |
|
|
81
|
+
|
|
82
|
+
detect 最多确认 10 个跨窗口合并锚点;超限会在 `warnings` 中说明跳过的数量。遇到该 warning,缩小扫描窗口后再复核受影响的子表边界。
|
|
83
|
+
|
|
84
|
+
`lark_profile_table.py` 输出触发补读的规则:
|
|
85
|
+
|
|
86
|
+
- `risk_warnings` 非空时,不要把画像当最终事实;按下表补读或调整,不在表内的 warning 也先保守复核。
|
|
87
|
+
|
|
88
|
+
| Warning | 必做动作 |
|
|
89
|
+
| --- | --- |
|
|
90
|
+
| `mixed_value_types` / `long_numeric_like_id` / `formula_or_value_errors` | 补 `+cells-get` 或 `+table-get`,确认原始值、类型和公式。 |
|
|
91
|
+
| `duplicate_headers` / `unnamed_columns` / `header_not_detected` / `header_row_not_first` / `many_empty_cells` | 补 `+csv-get` 读取表头附近和空值样本,确认真正表头与字段列。 |
|
|
92
|
+
| `data_range_not_detected` / `special_rows_present` / `empty_rows_present` | 补 `+csv-get` 读取尾部和特殊行样本,确认有效数据末行。 |
|
|
93
|
+
| `possible_multi_row_header` | 补读表头上下各 1-2 行;必要时 `+sheet-info --include merges` 核对跨列合并。 |
|
|
94
|
+
| `hidden_rows_in_range` / `hidden_columns_in_range` | 用 `+sheet-info --include hidden_rows,hidden_cols` 确认隐藏区间,决定是过滤还是照常解读。 |
|
|
95
|
+
| `data_range_has_gaps` | 不把连续 `data_range` 当真实连续区间;用 `summary.data_row_segments` 对每个实际读取行段单独处理。 |
|
|
96
|
+
| `data_range_has_col_gaps` | 返回的列不连续(`--skip-hidden` 跳过了隐藏列);不要把 `data_range` 当连续列区解读,按 `summary.data_col_segments` 分列段处理,否则缺口右侧的值会整体错位。 |
|
|
97
|
+
|
|
98
|
+
- `write_hints.safe_append_col` 只是候选追加列(脚本为通用画像输出保留该字段),不代表绝对安全;引用它之前必须用 `+csv-get` / `+cells-get` / `+sheet-info` 核对该列为空、没有隐藏列 / 公式 / 样式 / 对象依赖。该字段已自动跳过隐藏列(跳过的列名列在 `write_hints.skipped_hidden_cols`)——注意 `--skip-hidden` 下隐藏列根本不出现在返回网格里,若它们正好都贴在数据右边缘,`data_range_has_col_gaps` 也不会告警,所以这层跳过是唯一的保护,别绕过它自己按「最后一列 +1」推落点。
|
|
99
|
+
|
|
100
|
+
⚠️ **大数据不要灌进上下文**:`+csv-get` / `+cells-get` 都受调用方 Bash / 终端的单命令 stdout 输出上限约束(常见默认约 30000 字符)。默认读全量时,结果超出 stdout 阈值会自动落盘,回执给出 `output_path`,后续用本地脚本处理该文件。只要结果直接进上下文,就显式给 `--max-chars 25000` 主动截断取样本。
|
|
101
|
+
|
|
102
|
+
> **`complete` 是唯一读全判据**——内联结果与落盘回执都带这个字段(没有单独的 `truncated` 标志,那是同一事实的第二个名字;要做什么看 `note`)。别拿 `warning_message` 的文字当判据:它是上游文案、随语言变化。`--output-path` 只决定落点,不影响读多少。内部分批有任一批重试耗尽时命令以非零码退出,回执 `complete:false` 并给出已完成边界;多子表读取还会用 `unread_sheets` 列出没读到的子表。**不要用文件行数或 `wc -l` 判断读全**——多行文本单元格会让物理行数虚高于逻辑行数。
|
|
103
|
+
|
|
104
|
+
**`+csv-get` 返回值核心设计**:
|
|
105
|
+
- `csv` — **CSV 数据入口**,标准 RFC4180,可直接喂 csv.reader / pandas。
|
|
106
|
+
- `annotated_csv` — 每一逻辑行前加 `[row=N] ` 前缀(N = 真实表格行号)的同一份数据,**仅在 `--include-row-prefix` 时返回**。需要把行号填进下游工具参数时加这个 flag,读前缀比按序推算可靠。
|
|
107
|
+
- `col_indices` — **定位列字母唯一入口**。在表头中找到目标字段是第 j 个(0-based),用 `col_indices[j]` 取列字母。**禁止手数逗号**——列数超过 10 时极易 off-by-one(例如把 W 误判为 X)。
|
|
108
|
+
- `row_indices` — 与 `csv` 数据行一一对应的真实行号数组。不开 `--include-row-prefix` 时行号从这里取;按下标取值即可,不要自己从 `actual_range` 心算累加。
|
|
109
|
+
- `current_region` — 从请求范围扩展到被空行空列包围的连续数据区域(等价于 Excel Ctrl+Shift+*),适合先读少量行探表头。⚠️ 它**遇表中部整行空行 / 整列空列就截断**,可能小于真实数据范围(漏掉空行之后的行);**不能**直接当整表末行用,判断整表是否读全要拿 `+workbook-info` 的物理 `row_count` / `column_count` 当上界交叉核对(见下方「按 row_count 盲读空行」与「确定数据范围的正确流程」)。
|
|
110
|
+
|
|
111
|
+
注意:
|
|
112
|
+
|
|
113
|
+
- `+csv-get` 和 `+cells-get` 默认返回全量;只有显式给了 `--max-chars` 才会截断并带 `has_more`。两者在处理返回数据之前都必须先读 `warning_message`(上游 schema 要求先读它再用其它字段,内含定位与截断续读提示),`+cells-get` 还要用每个 range 的 `actual_range` / `row_indices` / `col_indices` 判断真实位置
|
|
114
|
+
- 隐藏行列默认包含在返回结果中(`--skip-hidden=false`),如需只看可见数据设为 `true`。读取原语本身不标注哪些行列被隐藏:若要识别隐藏区间(以决定是否过滤、或如何解读混入的隐藏数据),用 `+sheet-info --include hidden_rows,hidden_cols` 取隐藏行列集合,再结合 `+csv-get` / `+cells-get` 返回的 `row_indices` / `col_indices` 判断每行 / 每列是否隐藏
|
|
115
|
+
- 要判断单元格内容是否被行高列宽挤到显示不全(排版检查),给 `+cells-get` 加 `--include truncation`:会按字号 / 自动换行 / 行高列宽估算并返回被截断单元格的 `isRowTruncated` / `isColTruncated`(未返回视为未截断)。有额外计算开销,仅需要时才开
|
|
116
|
+
|
|
117
|
+
**常见配置错误(必须注意)**:
|
|
118
|
+
- **别把大表读进上下文**:大表(数百行以上)默认读全量会自动落盘,用回执里的 `output_path` 交给本地脚本处理,不要试图让整表进上下文;只需要样本时显式给 `--max-chars`。`scripts/lark_sheet_read_cli.py` 的 `run_sheets()` 已透明处理这个回执(自动读回文件),基于它的脚本无需各自适配
|
|
119
|
+
- **了解结构 ≠ 读取全量数据**:探表不用读全表,但必须同时探两个方向的表头:
|
|
120
|
+
- **横向(列头)**:先读前几行,且**列范围必须覆盖所有列**——用 `+workbook-info` 拿总列数,`range` 末列填到最后一列(例如总列数是 N,则 `range: "A1:[列N]10"`)。列范围截短会遗漏右侧字段、后续写入列定位错误。
|
|
121
|
+
- **纵向(行标)**:若左侧 1-2 列是行标签(日期/类别/编号枚举每行含义,典型交叉表/透视布局),**必须再读 `A:A` 或 `A:B` 把行标列读到底**,拿全部行标。只读前几行会看不全表尾的行,导致批量写入漏改——这是"只改前 N 行、其余未更新"的主要成因。扁平列表(每行独立记录、列是字段)可跳过这一步,但仍要按下方「确定数据范围的正确流程」用 `+workbook-info` 的物理 `row_count` 交叉核对末行(`current_region` 遇空行会截断,不能单独兜底)。
|
|
122
|
+
- 数据量大时按回执的 `output_path` 走本地处理,不要一口气拉全表到上下文。
|
|
123
|
+
- **`+cells-get` 滥用**:当只需要数据值时,使用 `+csv-get`(token 开销约为 `+cells-get` 的 1/5)。只有确实需要公式、样式或批注时才用 `+cells-get`
|
|
124
|
+
- **拿部分数据当全量**:`has_more=true` 只在显式给了 `--max-chars` 时出现,说明这是你主动要的样本;任务需要完整数据就去掉 `--max-chars` 重读,不要拿样本直接写入
|
|
125
|
+
- **直接按 `+cells-get` 返回二维数组下标推导真实位置**:`ranges[n].cells[i][j]` 里的 `i/j` 只是返回数组下标,不等于真实表格行列。定位真实行号必须用 `ranges[n].row_indices[i]`,定位真实列字母必须用 `ranges[n].col_indices[j]`;若 `--skip-hidden=true`、请求范围越界被裁剪,或最后一行是部分返回,错误地自己数下标会立刻错位
|
|
126
|
+
- **CSV 行号计数错误**:`+csv-get` 返回的 CSV 遵循 RFC 4180 标准,被双引号 `"..."` 包裹的字段中的换行符属于**字段内容的一部分**(即单元格内换行),不代表新的一行。计算行号时必须按**逻辑记录**计数,而非按物理换行符 `\n` 计数
|
|
127
|
+
- **手动数列确定列号**:禁止通过在 CSV 表头中手动数逗号/字段来确定目标列的列字母。当列数超过 10 时,手动计数极易产生 off-by-one 偏移(例如把 W 列误判为 X 列)。**必须使用 `col_indices`**:先在 CSV 表头中找到目标字段名是第 j 个字段(0-based),再用 `col_indices[j]` 获取该列的实际列字母
|
|
128
|
+
- **用数据列的值推导行号(常被巧合掩盖)**:CSV 中常见"序号 / ID / 编号 / No."等形似行号的列,其值与实际表格行号**没有任何绑定关系**——序号可能跳号(1,2,3,5,6...)、可能从非 1 开始、可能有重复或被中途重置。此规则适用于**所有需要行号的下游操作**:合并单元格、区间写入/清空/格式化、插入/删除行、条件格式范围、筛选器范围、图表数据源、透视表范围、搜索替换范围等等——**凡是要把行号填进任何工具参数的场景,行号一律取自 `row_indices`(或加 `--include-row-prefix` 后读行首 `[row=N]` 前缀)**,禁止用"序号=行号"、"表头占 1 行所以数据从第 2 行开始"、"第 N 个序号就在第 N+1 行"等心算,也禁止先心算再"事后核对"。**危险特征**:前几十行中序号恰好等于表格行号(典型成因:表头 +1 与一次跳号 -1 的偏移互相抵消形成巧合),模型一旦把这个巧合当作规律,会在后续所有行沿用;而中间再出现跳号时,从该行起整块区域全部错位,且错位不自查很难发现。**正确工作流**:①在 `csv` 里定位目标逻辑行(按字段内容匹配);②取同下标的 `row_indices[i]` 得到真实表格行号(开了 `--include-row-prefix` 就直接读该行的 `[row=N]`);③把这个行号填进下游工具参数。区间操作时,起止行各取各自的行号。**自检**:动手前在靠后位置再抽 1~2 行,核对取到的行号是否与首列"序号"一致——不一致(典型:`[row=57] 58,...`)即说明有跳号/隐藏行,更要严格从 `[row=N]` 取值,不要被序号列迷惑
|
|
129
|
+
- **`row_count` 与 `current_region` 都不能单独定末行**:`+workbook-info` 的 `row_count` 是 sheet 的**网格物理行数**(常是 200 / 1000 等默认值),通常**大于**真实数据末行——直接按它把 `--range` 拉到 `S200` 会读回大片空行,浪费上下文。反过来,`+csv-get` 返回的 `current_region` 是从锚点扩展、被空行空列围住的连续块,**遇表中部整行空行就截断**,可能**小于**真实数据范围(漏掉空行之后的行,典型反例:1–80 行有数据、81 行空、82 行起还有数据,`current_region` 只到 80,82 行起整段被漏读)。正确做法:把 `row_count` 当**上界**、`current_region` 当**起点参考**,在二者之间按下方「确定数据范围的正确流程」确认真实末行(含跨过中间空行的核对),不要只信其一。
|
|
130
|
+
- **current_region 当作纯数据范围**:`current_region` 返回的是从请求范围向四周扩展到被空行空列包围的**连续非空区域**,等价于 Excel 的 Ctrl+Shift+\*。它包含该区域内**所有非空行**——不仅包含数据行,还可能包含标题行、汇总行(如"总计")、签名行(如"编制人/审批人")、脚注等非数据内容。**严禁直接将 `current_region` 的末尾行作为数据范围的结束行**。正确做法见下方「确定数据范围的正确流程」
|
|
131
|
+
|
|
132
|
+
### 确定数据范围的正确流程(排序、筛选、批量写入等操作前必做)
|
|
133
|
+
|
|
134
|
+
当后续操作需要精确的数据范围(如排序、筛选、删除、批量写入)时,仅靠 `current_region` 探测到的范围是不够的——它**两头都可能不准**:表中部有整行空行时会被截断(末行偏小、漏数据),表尾有汇总 / 签名行时又会偏大。必须同时确认数据的**起始行**和**结束行**。具体步骤:
|
|
135
|
+
|
|
136
|
+
1. **确认起始行**:读取前 5~10 行,识别表头行位置,数据起始行 = 表头行 + 1
|
|
137
|
+
2. **确认结束行**(关键步骤,不可跳过):
|
|
138
|
+
- **先防截断(漏数据)**:拿 `+workbook-info` 的物理 `row_count` 当上界,与 `current_region` 末行对比。若 `current_region` 末行 **远小于** `row_count`(差出很多空间),不要直接采信——在 `current_region` 末行之后再探一段(如往下读到 `row_count`,或分段扫到首个连续空白区),确认空行之后确实没有数据;典型反例:`row_count=327`、`current_region` 只到第 80 行,第 81 行空、82 行起还有数据,只读到 80 就漏了一大段。
|
|
139
|
+
- **再排尾部非数据行**:读取确认到的末行附近若干行(建议末尾 5~10 行),逐行排除:
|
|
140
|
+
- **汇总行**:内容为"合计"、"总计"、"小计"、"总计:"等
|
|
141
|
+
- **签名/审批行**:内容为"编制人"、"审核人"、"部门负责人"等
|
|
142
|
+
- **空行或分隔行**:整行为空或仅有边框
|
|
143
|
+
- **备注/脚注行**:注释性文字、说明文字等
|
|
144
|
+
3. **最终数据范围** = 起始行 ~ 最后一条有效数据行(跨过中间空行、排除尾部非数据行)
|
|
145
|
+
|
|
146
|
+
**示例**:`current_region` 返回 `A1:N51`,读取 Row 48~51 发现:
|
|
147
|
+
|
|
148
|
+
- Row 49: 序号=47, 姓名=xxx, 有正常数据 → ✅ 数据行
|
|
149
|
+
- Row 50: "总计", 有合并单元格 → ❌ 汇总行
|
|
150
|
+
- Row 51: "总经理:...", "编制人:..." → ❌ 签名行
|
|
151
|
+
- **正确数据范围 = A3:N49**(而非 A3:N51)
|
|
152
|
+
|
|
153
|
+
## Shortcuts
|
|
154
|
+
|
|
155
|
+
| Shortcut | Risk | 分组 |
|
|
156
|
+
| --- | --- | --- |
|
|
157
|
+
| `+cells-get` | read | 单元格 |
|
|
158
|
+
| `+dropdown-get` | read | 对象 |
|
|
159
|
+
| `+csv-get` | read | 单元格 |
|
|
160
|
+
| `+table-get` | read | 单元格 |
|
|
161
|
+
|
|
162
|
+
## Flags
|
|
163
|
+
|
|
164
|
+
### `+cells-get`
|
|
165
|
+
|
|
166
|
+
_公共四件套 · 系统:`--dry-run`_
|
|
167
|
+
|
|
168
|
+
| Flag | Type | 必填 | 说明 |
|
|
169
|
+
| --- | --- | --- | --- |
|
|
170
|
+
| `--range` | string | required | A1 范围,如 `A1:F10`(不带 sheet 前缀;用 `--sheet-id` / `--sheet-name` 指定 sheet) |
|
|
171
|
+
| `--include` | string_slice | optional | 要返回的信息类别,逗号分隔多个。`truncation` 会额外按行高列宽 / 字号 / 自动换行估算每个单元格是否被截断显示,返回 `isRowTruncated` / `isColTruncated`(有额外计算开销,仅排版检查时才开)(可选值:`value` / `formula` / `style` / `comment` / `data_validation` / `truncation`) |
|
|
172
|
+
| `--max-chars` | int | optional | 单次返回字符上限。**不传即读全量**——CLI 内部按 1000000 字符分批取回并拼接,返回始终完整。**显式传值则视为要求截断**:只返回该上限内的内容并给出 `has_more`,用于取样本或控制进入上下文的体量(如 25000)。传 0 等价于不传。 |
|
|
173
|
+
| `--output-path` | string | optional | 把完整读取结果写入本地路径(如 `./out.json`),文件内容为 data 载荷的 JSON;stdout 只回含 `output_path` / 字节数 / `complete` 的确认信息。读取本身默认就是全量(CLI 内部自动分页拼接),本 flag 只决定落点,不再影响字符上限。结果超出 stdout 阈值时即使不传本 flag 也会自动落盘,路径见回执。 |
|
|
174
|
+
| `--skip-hidden` | bool | optional | 跳过隐藏行列,默认 `false` |
|
|
175
|
+
|
|
176
|
+
### `+dropdown-get`
|
|
177
|
+
|
|
178
|
+
_公共四件套 · 系统:`--dry-run`_
|
|
179
|
+
|
|
180
|
+
| Flag | Type | 必填 | 说明 |
|
|
181
|
+
| --- | --- | --- | --- |
|
|
182
|
+
| `--range` | string | required | A1 范围,如 `A2:A100`(不带 sheet 前缀;用 `--sheet-id` / `--sheet-name` 指定 sheet) |
|
|
183
|
+
|
|
184
|
+
### `+csv-get`
|
|
185
|
+
|
|
186
|
+
_公共四件套 · 系统:`--dry-run`_
|
|
187
|
+
|
|
188
|
+
| Flag | Type | 必填 | 说明 |
|
|
189
|
+
| --- | --- | --- | --- |
|
|
190
|
+
| `--range` | string | optional | A1 范围,如 `A1:F30`(不带 sheet 前缀;用 `--sheet-id` / `--sheet-name` 指定 sheet)。**可省略:缺省读取整个子表**(按表格实际边界裁剪,返回的 `actual_range` 标注实际读取范围);大表配合 `--max-chars` / `--output-path` 控制体量 |
|
|
191
|
+
| `--max-chars` | int | optional | 单次返回字符上限。**不传即读全量**——CLI 内部按 1000000 字符分批取回并拼接,返回始终完整。**显式传值则视为要求截断**:只返回该上限内的内容并给出 `has_more`,用于取样本或控制进入上下文的体量(如 25000)。传 0 等价于不传。 |
|
|
192
|
+
| `--output-path` | string | optional | 把完整读取结果写入本地路径(如 `./out.json`),文件内容为 data 载荷的 JSON;stdout 只回含 `output_path` / 字节数 / `complete` 的确认信息。读取本身默认就是全量(CLI 内部自动分页拼接),本 flag 只决定落点,不再影响字符上限。结果超出 stdout 阈值时即使不传本 flag 也会自动落盘,路径见回执。落盘的是 data 载荷的 JSON(CSV 文本是其中一个字段),不是直接可用的 .csv 文件。 |
|
|
193
|
+
| `--include-row-prefix` | bool | optional | 额外输出带 `[row=N]` 行号前缀的 `annotated_csv`,默认 `false`。主载荷 `csv` 恒为标准 CSV(可直接喂 csv.reader);行号按 `actual_range` 起始行 + 行序推算,行号不连续时(如 `--skip-hidden`)读 `row_indices`。只有要按字面行号逐行定位、又不想自己算时才开——它会让返回体大约翻倍。 |
|
|
194
|
+
| `--skip-hidden` | bool | optional | 跳过隐藏行列,默认 `false` |
|
|
195
|
+
|
|
196
|
+
### `+table-get`
|
|
197
|
+
|
|
198
|
+
_公共:URL/token(无 sheet 定位) · 系统:`--dry-run`_
|
|
199
|
+
|
|
200
|
+
| Flag | Type | 必填 | 说明 |
|
|
201
|
+
| --- | --- | --- | --- |
|
|
202
|
+
| `--sheet-id` | string | optional | 只读该子表(按 id);省略则读所有子表 |
|
|
203
|
+
| `--sheet-name` | string | optional | 只读该子表(按名);省略则读所有子表 |
|
|
204
|
+
| `--range` | string | optional | 读取的 A1 范围;省略则读每个子表的完整 used range(会跨过表中部的整行空行 / 整列空列,不会被截断) |
|
|
205
|
+
| `--max-chars` | int | optional | 单次返回字符上限。**不传即读全量**——CLI 内部按 1000000 字符分批取回并拼接,返回始终完整。**显式传值则视为要求截断**:只返回该上限内的内容并给出 `has_more`,用于取样本或控制进入上下文的体量(如 25000)。传 0 等价于不传。 |
|
|
206
|
+
| `--output-path` | string | optional | 把完整读取结果写入本地路径(如 `./out.json`),文件内容为 data 载荷的 JSON;stdout 只回含 `output_path` / 字节数 / `complete` 的确认信息。读取本身默认就是全量(CLI 内部自动分页拼接),本 flag 只决定落点,不再影响字符上限。结果超出 stdout 阈值时即使不传本 flag 也会自动落盘,路径见回执。 |
|
|
207
|
+
| `--no-header` | bool | optional | 把第一行当数据而非表头(列名取 col1/col2 …) |
|
|
208
|
+
|
|
209
|
+
## Examples
|
|
210
|
+
|
|
211
|
+
### `+csv-get`
|
|
212
|
+
|
|
213
|
+
公共四件套:`--url` / `--spreadsheet-token` / `--sheet-id` / `--sheet-name`(前两者 XOR,后两者 XOR)。
|
|
214
|
+
|
|
215
|
+
示例:
|
|
216
|
+
|
|
217
|
+
```bash
|
|
218
|
+
# 简单读(sheet 定位必填:--sheet-name 或 --sheet-id 必给一个;range 的 Sheet1! 前缀不能替代它)
|
|
219
|
+
lark-cli sheets +csv-get --url "https://example.feishu.cn/sheets/shtXXX" --sheet-name "Sheet1" --range "A1:F30"
|
|
220
|
+
|
|
221
|
+
# 用 sheet-name 模糊定位(运行时框架会先解析到 sheet-id)
|
|
222
|
+
lark-cli sheets +csv-get --spreadsheet-token shtXXX --sheet-name "销售明细" --range "A1:F30"
|
|
223
|
+
|
|
224
|
+
# 全量读:省略 --range 即读整个子表(按实际边界裁剪,返回 actual_range 标注实读范围),
|
|
225
|
+
# 无需先 +workbook-info 探行列再拼 range;默认读全量,大表自动落盘
|
|
226
|
+
lark-cli sheets +csv-get --spreadsheet-token shtXXX --sheet-name "销售明细"
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
输出契约(envelope.data):
|
|
230
|
+
|
|
231
|
+
- `csv` — 标准 CSV 主入口;`annotated_csv` — 含 `[row=N]` 前缀的同一份数据,仅 `--include-row-prefix` 时返回
|
|
232
|
+
- `col_indices` / `row_indices` — 列字母 / 行号映射数组
|
|
233
|
+
- `current_region` — 从锚点扩展到被空行空列包围的连续区域的 A1 范围。⚠️ **它不是整表真实边界**:遇表中部整行空行 / 整列空列会截断、可能小于真实数据范围;表尾的汇总 / 签名 / 脚注又可能让它大于纯数据范围。判断整表是否读全须拿 `+workbook-info` 的物理 `row_count` 当上界交叉核对(见上方「`row_count` 与 `current_region` 都不能单独定末行」)
|
|
234
|
+
- `row_count` / `col_count` — **本次返回的行 / 列数**(= `actual_range` 的尺寸,随 `--range` 变),**不是整表物理总行列数**;整表物理尺寸取 `+workbook-info`
|
|
235
|
+
- `has_more` — 仅在显式给了 `--max-chars` 时才可能为 true,表示本次按你要求截断了;不传 `--max-chars` 时恒为 `false`(已读全量)。它不反映整表边界——覆盖到哪里一律看 `actual_range`
|
|
236
|
+
|
|
237
|
+
> 要按列类型结构化读出(喂 DataFrame)用 `+table-get`(见下);`+csv-get` 给的是带 `[row=N]` 前缀的纯值快照,下游需要行号/列坐标时直接从前缀与 `col_indices` 取。
|
|
238
|
+
|
|
239
|
+
### `+cells-get`
|
|
240
|
+
|
|
241
|
+
示例:
|
|
242
|
+
|
|
243
|
+
```bash
|
|
244
|
+
# 读 A1:F10 的公式 + 样式(sheet 定位必填)
|
|
245
|
+
lark-cli sheets +cells-get --url "https://example.feishu.cn/sheets/shtXXX" --sheet-name "Sheet1" \
|
|
246
|
+
--range "A1:F10" --include formula,style
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
> ⚠️ 调用方在 `cells[i][j]` 中**不能**用下标推真实行列:必须读 `ranges[n].row_indices[i]` / `ranges[n].col_indices[j]`。
|
|
250
|
+
|
|
251
|
+
### `+table-get`(飞书 → DataFrame,类型保真读出)
|
|
252
|
+
|
|
253
|
+
把表格读回一份 typed 协议(`sheets[]` + `columns:[列名]` + `data:[[行]]` + `dtypes:{列名:pandas_dtype}` + `formats?:{列名:number_format}` + `range`),可一行还原 DataFrame。
|
|
254
|
+
|
|
255
|
+
**默认(不带 `--range`)读取整张子表的完整 used range**:会跨过表中部的整行空行 / 整列空列,覆盖到真实数据边界。每个子表都回传实际读取的 `range`(如 `A1:F10`):拿它和源 xlsx 行列数、关键末行 / 末日期交叉核对,确认读取完整。不传 `--max-chars` 时读全量;显式给了才截断,此时 `truncated=true` / `complete=false` 表示只有部分数据,去掉 `--max-chars` 重读即可。仍要精确控制范围时显式传 `--range`。
|
|
256
|
+
|
|
257
|
+
列类型从每列 `number_format` 推断(日期格式→`date`/`datetime64[ns]`、数值→`number`/`float64`、bool→`bool`),`date` 列的序列号转回 ISO `yyyy-mm-dd`——日期、数字往返不丢类型。**列类型只在该列所有非空值一致时才定(`number` / `date` / `bool`);一列混了类型(如数字列混入「暂无」、日期列混入裸数字)会降为 `string`(dtypes 输出 `object`),让 `dtypes` 与 `data` 里每个值自洽——不让 pandas `astype` 崩。降级是无损的(脏值原样保留为文本);若要把零星脏值转成数值列,交给调用方在 pandas 侧做(`to_numeric(errors='coerce')`),那里原始值仍在、可追溯。** 默认读所有子表、第一行当表头(`--no-header` 把首行当数据、列名取 `col1` / `col2` …)。
|
|
258
|
+
|
|
259
|
+
```bash
|
|
260
|
+
# 默认读所有子表 → sheets[](typed 协议,可直接转 DataFrame)
|
|
261
|
+
lark-cli sheets +table-get --url "<表URL>"
|
|
262
|
+
# 可选:--sheet-name / --sheet-id 限定只读某一个子表(不给则读全部)
|
|
263
|
+
lark-cli sheets +table-get --url "<表URL>" --sheet-name "销售"
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
#### 输出 → DataFrame(用 `sheet_to_df` helper)
|
|
267
|
+
|
|
268
|
+
输出形状对齐 pandas split:`columns` 是列名数组、`data` 是二维数据、`dtypes` 是 `{列名: pandas_dtype_str}` 映射。直接喂给 `pd.DataFrame(...).astype(...)` 就能一次性还原所有列类型(不必逐列 `to_datetime` / `to_numeric`)。本 skill 把这段还原 helper 打包成可 import 的 [`scripts/sheets_df.py`](../scripts/sheets_df.py)(用 `sheet_to_df` 把读回的子表还原成 DataFrame):
|
|
269
|
+
|
|
270
|
+
```python
|
|
271
|
+
from sheets_df import sheet_to_df
|
|
272
|
+
|
|
273
|
+
# 单 sheet
|
|
274
|
+
df = sheet_to_df(out["data"]["sheets"][0])
|
|
275
|
+
|
|
276
|
+
# 多 sheet——按名字取
|
|
277
|
+
sheets = {s["name"]: sheet_to_df(s) for s in out["data"]["sheets"]}
|
|
278
|
+
df_sales = sheets["销售"]
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
> 显示格式(千分位、百分比、自定义日期)在 `sheet["formats"]`,pandas 不消费;`sheet_to_df(sheet)` 消费 `(columns, data, dtypes)` 还原 DataFrame,读出后即可在本地分析。
|
|
282
|
+
|
|
283
|
+
### Validate / DryRun / Execute 约束
|
|
284
|
+
|
|
285
|
+
- `Validate` 阶段只做 XOR 检查、Enum 合法性、防爆参数上限校验;**禁止**联网(如不能用 `--sheet-name` 提前去查 `sheet-id`)。
|
|
286
|
+
- `DryRun` 输出请求模板:`--sheet-name` 在 dry-run 输出里生成为 `<resolve:销售明细>` 占位符,不实际解析。
|
|
287
|
+
- `Execute` 阶段才进行 sheet-name → sheet-id 解析与 API 调用。
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# Lark Sheet Search
|
|
2
|
+
|
|
3
|
+
## 使用场景
|
|
4
|
+
|
|
5
|
+
在飞书表格中搜索 / 定位文本。本 reference 覆盖 1 个只读 shortcut:
|
|
6
|
+
|
|
7
|
+
| 操作需求 | 使用工具 | 说明 |
|
|
8
|
+
|---------|---------|------|
|
|
9
|
+
| 搜索/定位文本 | `+cells-search` | 返回匹配的单元格位置,支持正则、精确匹配、范围限定等 |
|
|
10
|
+
|
|
11
|
+
**常见配置错误(必须注意)**:
|
|
12
|
+
- **不要把操作动词当搜索词**:用户说"汇总金额"是一个操作动作(求和),不是要搜索"汇总金额"这个文本。只有当确实需要定位某个文本值的位置时才用 `+cells-search`
|
|
13
|
+
- **不要用搜索来了解表格结构**:要了解表头和数据结构时,应使用 `+csv-get` 读取前几行,而不是用 `+cells-search` 逐个猜测字段名
|
|
14
|
+
- **注意正则特殊字符**:使用正则匹配时,`.`、`*`、`(`、`)` 等特殊字符需要转义
|
|
15
|
+
|
|
16
|
+
## Shortcuts
|
|
17
|
+
|
|
18
|
+
| Shortcut | Risk | 分组 |
|
|
19
|
+
| --- | --- | --- |
|
|
20
|
+
| `+cells-search` | read | 单元格 |
|
|
21
|
+
|
|
22
|
+
## Flags
|
|
23
|
+
|
|
24
|
+
### `+cells-search`
|
|
25
|
+
|
|
26
|
+
_公共四件套 · 系统:`--dry-run`_
|
|
27
|
+
|
|
28
|
+
| Flag | Type | 必填 | 说明 |
|
|
29
|
+
| --- | --- | --- | --- |
|
|
30
|
+
| `--find` | string | required | 待查找文本(与 `--regex` 配合时按正则解释) |
|
|
31
|
+
| `--range` | string | optional | 查找范围(A1 格式);省略时整表 |
|
|
32
|
+
| `--match-case` | bool | optional | 大小写敏感 |
|
|
33
|
+
| `--match-entire-cell` | bool | optional | 完全匹配整个单元格 |
|
|
34
|
+
| `--regex` | bool | optional | 把 `--find` 按正则解释 |
|
|
35
|
+
| `--include-formulas` | bool | optional | 也在公式文本中搜索 |
|
|
36
|
+
| `--max-matches` | int | optional | 防爆,默认 5000(隐藏 flag:不在 `--help` 列出,但可正常传入) |
|
|
37
|
+
| `--offset` | int | optional | 跳过前 N 个匹配(分页用),默认 0 |
|
|
38
|
+
|
|
39
|
+
## Examples
|
|
40
|
+
|
|
41
|
+
公共四件套:所有 shortcut 顶部排列 `--url` / `--spreadsheet-token` / `--sheet-id` / `--sheet-name`(XOR 规则)。
|
|
42
|
+
|
|
43
|
+
### `+cells-search`
|
|
44
|
+
|
|
45
|
+
示例:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
# 普通查找
|
|
49
|
+
lark-cli sheets +cells-search --url "https://example.feishu.cn/sheets/shtXXX" \
|
|
50
|
+
--sheet-name "Sheet1" --find "张三"
|
|
51
|
+
|
|
52
|
+
# 正则 + 范围限定
|
|
53
|
+
lark-cli sheets +cells-search --spreadsheet-token shtXXX --sheet-id "$SID" \
|
|
54
|
+
--find "^[A-Z]{2}-\\d{4}$" --regex --range "A2:A1000"
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
输出契约(envelope.data):
|
|
58
|
+
|
|
59
|
+
- `matches` — 命中 cell 列表,每条含 `address`(A1)+ `value` + `sheet_id`
|
|
60
|
+
- `total_matches` — 匹配总数
|
|
61
|
+
- `has_more` / `next_offset` — 分页游标(命中数超过单页上限时用于继续读取)
|
|
62
|
+
|
|
63
|
+
### Validate / DryRun / Execute 约束
|
|
64
|
+
|
|
65
|
+
- `Validate`:XOR 公共四件套;`--find` 非空;正则模式下 `--find` 必须是合法正则。
|
|
66
|
+
- `DryRun`:`+cells-search` 输出请求模板。
|
|
67
|
+
- `Execute`:发起搜索查询。
|