@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,176 @@
|
|
|
1
|
+
# Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
|
2
|
+
# SPDX-License-Identifier: MIT
|
|
3
|
+
"""Range and coordinate helpers for Lark Sheet scripts."""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
import re
|
|
8
|
+
from dataclasses import dataclass
|
|
9
|
+
|
|
10
|
+
CELL_RE = re.compile(r"^\$?([A-Za-z]+)\$?([1-9][0-9]*)$")
|
|
11
|
+
ROW_RE = re.compile(r"^\$?([1-9][0-9]*)$")
|
|
12
|
+
COLUMN_RE = re.compile(r"^\$?([A-Za-z]+)$")
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@dataclass(frozen=True)
|
|
16
|
+
class RangeBounds:
|
|
17
|
+
start_row: int
|
|
18
|
+
start_col: int
|
|
19
|
+
end_row: int
|
|
20
|
+
end_col: int
|
|
21
|
+
|
|
22
|
+
@property
|
|
23
|
+
def row_count(self) -> int:
|
|
24
|
+
return self.end_row - self.start_row + 1
|
|
25
|
+
|
|
26
|
+
@property
|
|
27
|
+
def col_count(self) -> int:
|
|
28
|
+
return self.end_col - self.start_col + 1
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def col_to_index(col: str) -> int:
|
|
32
|
+
value = 0
|
|
33
|
+
for char in col.strip().upper():
|
|
34
|
+
if not ("A" <= char <= "Z"):
|
|
35
|
+
raise ValueError(f"Invalid column: {col}")
|
|
36
|
+
value = value * 26 + (ord(char) - ord("A") + 1)
|
|
37
|
+
if value <= 0:
|
|
38
|
+
raise ValueError(f"Invalid column: {col}")
|
|
39
|
+
return value
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def index_to_col(index: int) -> str:
|
|
43
|
+
if index < 1:
|
|
44
|
+
raise ValueError(f"Column index must be >= 1: {index}")
|
|
45
|
+
chars = []
|
|
46
|
+
n = index
|
|
47
|
+
while n:
|
|
48
|
+
n, rem = divmod(n - 1, 26)
|
|
49
|
+
chars.append(chr(ord("A") + rem))
|
|
50
|
+
return "".join(reversed(chars))
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def parse_cell(cell_ref: str) -> tuple[int, int]:
|
|
54
|
+
match = CELL_RE.match(cell_ref.strip())
|
|
55
|
+
if not match:
|
|
56
|
+
raise ValueError(f"Invalid cell reference: {cell_ref}")
|
|
57
|
+
col, row = match.groups()
|
|
58
|
+
return int(row), col_to_index(col)
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def _parse_endpoint(endpoint: str) -> tuple[str, int, int] | tuple[str, int]:
|
|
62
|
+
cell = CELL_RE.match(endpoint)
|
|
63
|
+
if cell:
|
|
64
|
+
col, row = cell.groups()
|
|
65
|
+
return "cell", int(row), col_to_index(col)
|
|
66
|
+
row = ROW_RE.match(endpoint)
|
|
67
|
+
if row:
|
|
68
|
+
return "row", int(row.group(1))
|
|
69
|
+
column = COLUMN_RE.match(endpoint)
|
|
70
|
+
if column:
|
|
71
|
+
return "column", col_to_index(column.group(1))
|
|
72
|
+
raise ValueError(f"Invalid A1 range endpoint: {endpoint}")
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def parse_range(
|
|
76
|
+
range_ref: str,
|
|
77
|
+
*,
|
|
78
|
+
max_row: int | None = None,
|
|
79
|
+
max_col: int | None = None,
|
|
80
|
+
) -> RangeBounds:
|
|
81
|
+
"""Parse the A1 range forms accepted by ``+csv-get``.
|
|
82
|
+
|
|
83
|
+
Open-ended forms need the caller's actual returned grid dimensions. This
|
|
84
|
+
keeps generated ranges finite without guessing a spreadsheet-wide limit.
|
|
85
|
+
"""
|
|
86
|
+
ref = range_ref.strip()
|
|
87
|
+
if "!" in ref:
|
|
88
|
+
_, ref = ref.rsplit("!", 1)
|
|
89
|
+
if not ref:
|
|
90
|
+
raise ValueError(f"Invalid A1 range: {range_ref}")
|
|
91
|
+
parts = ref.split(":")
|
|
92
|
+
if len(parts) > 2:
|
|
93
|
+
raise ValueError(f"Invalid A1 range: {range_ref}")
|
|
94
|
+
start = _parse_endpoint(parts[0])
|
|
95
|
+
end = _parse_endpoint(parts[-1])
|
|
96
|
+
|
|
97
|
+
if len(parts) == 1:
|
|
98
|
+
if start[0] != "cell":
|
|
99
|
+
raise ValueError(f"A1 range must include a cell or ':' separator: {range_ref}")
|
|
100
|
+
_, row, col = start
|
|
101
|
+
return RangeBounds(row, col, row, col)
|
|
102
|
+
|
|
103
|
+
if start[0] == end[0] == "cell":
|
|
104
|
+
_, start_row, start_col = start
|
|
105
|
+
_, end_row, end_col = end
|
|
106
|
+
elif start[0] == end[0] == "row":
|
|
107
|
+
_, start_row = start
|
|
108
|
+
_, end_row = end
|
|
109
|
+
start_col = 1
|
|
110
|
+
if max_col is None:
|
|
111
|
+
raise ValueError(f"Range needs a maximum column: {range_ref}")
|
|
112
|
+
end_col = max_col
|
|
113
|
+
elif start[0] == end[0] == "column":
|
|
114
|
+
_, start_col = start
|
|
115
|
+
_, end_col = end
|
|
116
|
+
start_row = 1
|
|
117
|
+
if max_row is None:
|
|
118
|
+
raise ValueError(f"Range needs a maximum row: {range_ref}")
|
|
119
|
+
end_row = max_row
|
|
120
|
+
elif start[0] == "cell" and end[0] == "column":
|
|
121
|
+
_, start_row, start_col = start
|
|
122
|
+
_, end_col = end
|
|
123
|
+
if max_row is None:
|
|
124
|
+
raise ValueError(f"Range needs a maximum row: {range_ref}")
|
|
125
|
+
end_row = max(start_row, max_row)
|
|
126
|
+
elif start[0] == "cell" and end[0] == "row":
|
|
127
|
+
_, start_row, start_col = start
|
|
128
|
+
_, end_row = end
|
|
129
|
+
if max_col is None:
|
|
130
|
+
raise ValueError(f"Range needs a maximum column: {range_ref}")
|
|
131
|
+
end_col = max(start_col, max_col)
|
|
132
|
+
else:
|
|
133
|
+
raise ValueError(f"Invalid A1 range: {range_ref}")
|
|
134
|
+
return RangeBounds(min(start_row, end_row), min(start_col, end_col), max(start_row, end_row), max(start_col, end_col))
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def format_cell(row: int, col: int) -> str:
|
|
138
|
+
if row < 1:
|
|
139
|
+
raise ValueError(f"Row must be >= 1: {row}")
|
|
140
|
+
return f"{index_to_col(col)}{row}"
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
def format_range(start_row: int, start_col: int, end_row: int, end_col: int) -> str:
|
|
144
|
+
bounds = RangeBounds(
|
|
145
|
+
min(start_row, end_row),
|
|
146
|
+
min(start_col, end_col),
|
|
147
|
+
max(start_row, end_row),
|
|
148
|
+
max(start_col, end_col),
|
|
149
|
+
)
|
|
150
|
+
start = format_cell(bounds.start_row, bounds.start_col)
|
|
151
|
+
end = format_cell(bounds.end_row, bounds.end_col)
|
|
152
|
+
return start if start == end else f"{start}:{end}"
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def iter_cells(bounds: RangeBounds):
|
|
156
|
+
for row in range(bounds.start_row, bounds.end_row + 1):
|
|
157
|
+
for col in range(bounds.start_col, bounds.end_col + 1):
|
|
158
|
+
yield row, col
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
def ranges_intersect(a: RangeBounds, b: RangeBounds) -> bool:
|
|
162
|
+
return not (
|
|
163
|
+
a.end_row < b.start_row
|
|
164
|
+
or b.end_row < a.start_row
|
|
165
|
+
or a.end_col < b.start_col
|
|
166
|
+
or b.end_col < a.start_col
|
|
167
|
+
)
|
|
168
|
+
|
|
169
|
+
|
|
170
|
+
def range_union(a: RangeBounds, b: RangeBounds) -> RangeBounds:
|
|
171
|
+
return RangeBounds(
|
|
172
|
+
min(a.start_row, b.start_row),
|
|
173
|
+
min(a.start_col, b.start_col),
|
|
174
|
+
max(a.end_row, b.end_row),
|
|
175
|
+
max(a.end_col, b.end_col),
|
|
176
|
+
)
|
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
# Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
|
2
|
+
# SPDX-License-Identifier: MIT
|
|
3
|
+
"""Read-only Lark Sheet subset wrapper for the helper scripts."""
|
|
4
|
+
|
|
5
|
+
from __future__ import annotations
|
|
6
|
+
|
|
7
|
+
import json
|
|
8
|
+
import subprocess
|
|
9
|
+
import sys
|
|
10
|
+
from typing import Any
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
class LarkCliError(RuntimeError):
|
|
14
|
+
def __init__(self, message: str, *, cmd: list[str] | None = None):
|
|
15
|
+
super().__init__(message)
|
|
16
|
+
self.cmd = cmd or []
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
def add_spreadsheet_args(
|
|
20
|
+
parser,
|
|
21
|
+
*,
|
|
22
|
+
require_sheet: bool = False,
|
|
23
|
+
allow_sheet: bool = True,
|
|
24
|
+
) -> None:
|
|
25
|
+
spreadsheet = parser.add_mutually_exclusive_group(required=True)
|
|
26
|
+
spreadsheet.add_argument("--url")
|
|
27
|
+
spreadsheet.add_argument("--spreadsheet-token")
|
|
28
|
+
if allow_sheet:
|
|
29
|
+
sheet = parser.add_mutually_exclusive_group(required=require_sheet)
|
|
30
|
+
sheet.add_argument("--sheet-id")
|
|
31
|
+
sheet.add_argument("--sheet-name")
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def _append_flag(cmd: list[str], name: str, value: Any) -> None:
|
|
35
|
+
flag = f"--{name.replace('_', '-')}"
|
|
36
|
+
if value is None:
|
|
37
|
+
return
|
|
38
|
+
if isinstance(value, bool):
|
|
39
|
+
cmd.append(flag if value else f"{flag}=false")
|
|
40
|
+
return
|
|
41
|
+
cmd.extend([flag, str(value)])
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def run_sheets(
|
|
45
|
+
shortcut: str,
|
|
46
|
+
*,
|
|
47
|
+
url: str | None = None,
|
|
48
|
+
spreadsheet_token: str | None = None,
|
|
49
|
+
sheet_id: str | None = None,
|
|
50
|
+
sheet_name: str | None = None,
|
|
51
|
+
flags: dict[str, Any] | None = None,
|
|
52
|
+
timeout: int = 60,
|
|
53
|
+
) -> dict[str, Any]:
|
|
54
|
+
if bool(url) == bool(spreadsheet_token):
|
|
55
|
+
raise LarkCliError("Pass exactly one of --url or --spreadsheet-token")
|
|
56
|
+
if sheet_id and sheet_name:
|
|
57
|
+
raise LarkCliError("Pass only one of --sheet-id or --sheet-name")
|
|
58
|
+
|
|
59
|
+
cmd = ["lark-cli", "sheets", shortcut]
|
|
60
|
+
_append_flag(cmd, "url", url)
|
|
61
|
+
_append_flag(cmd, "spreadsheet_token", spreadsheet_token)
|
|
62
|
+
_append_flag(cmd, "sheet_id", sheet_id)
|
|
63
|
+
_append_flag(cmd, "sheet_name", sheet_name)
|
|
64
|
+
for key, value in (flags or {}).items():
|
|
65
|
+
_append_flag(cmd, key, value)
|
|
66
|
+
|
|
67
|
+
try:
|
|
68
|
+
completed = subprocess.run(
|
|
69
|
+
cmd,
|
|
70
|
+
capture_output=True,
|
|
71
|
+
text=True,
|
|
72
|
+
timeout=timeout,
|
|
73
|
+
check=False,
|
|
74
|
+
)
|
|
75
|
+
except FileNotFoundError as exc:
|
|
76
|
+
raise LarkCliError("lark-cli not found", cmd=cmd) from exc
|
|
77
|
+
except subprocess.TimeoutExpired as exc:
|
|
78
|
+
raise LarkCliError(f"lark-cli timed out after {timeout}s", cmd=cmd) from exc
|
|
79
|
+
|
|
80
|
+
if completed.returncode != 0:
|
|
81
|
+
detail = (completed.stderr or completed.stdout or "").strip()
|
|
82
|
+
raise LarkCliError(detail or f"lark-cli exited with {completed.returncode}", cmd=cmd)
|
|
83
|
+
|
|
84
|
+
try:
|
|
85
|
+
envelope = json.loads(completed.stdout)
|
|
86
|
+
except json.JSONDecodeError as exc:
|
|
87
|
+
snippet = completed.stdout[:500].replace("\n", "\\n")
|
|
88
|
+
raise LarkCliError(f"lark-cli stdout was not JSON: {snippet}", cmd=cmd) from exc
|
|
89
|
+
|
|
90
|
+
if isinstance(envelope, dict) and envelope.get("ok") is False:
|
|
91
|
+
raise LarkCliError(json.dumps(envelope, ensure_ascii=False), cmd=cmd)
|
|
92
|
+
if not isinstance(envelope, dict):
|
|
93
|
+
raise LarkCliError("lark-cli returned a non-object JSON payload", cmd=cmd)
|
|
94
|
+
return _resolve_offload(envelope, cmd)
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def _resolve_offload(envelope: dict[str, Any], cmd: list[str]) -> dict[str, Any]:
|
|
98
|
+
"""Load the payload back when the CLI wrote it to a file instead of stdout.
|
|
99
|
+
|
|
100
|
+
Reads over an internal size threshold come back as a receipt
|
|
101
|
+
(``output_path`` + ``complete``) rather than the data, so a caller that
|
|
102
|
+
reads ``data`` directly would silently get a receipt where it expected
|
|
103
|
+
cells. Resolving it here keeps every caller working on one shape; doing it
|
|
104
|
+
per call site means each new one starts out broken.
|
|
105
|
+
"""
|
|
106
|
+
data = envelope.get("data")
|
|
107
|
+
if not isinstance(data, dict):
|
|
108
|
+
return envelope
|
|
109
|
+
path = data.get("output_path")
|
|
110
|
+
if not isinstance(path, str) or not path:
|
|
111
|
+
return envelope
|
|
112
|
+
|
|
113
|
+
try:
|
|
114
|
+
with open(path, encoding="utf-8") as handle:
|
|
115
|
+
payload = json.load(handle)
|
|
116
|
+
except (OSError, json.JSONDecodeError) as exc:
|
|
117
|
+
raise LarkCliError(
|
|
118
|
+
f"lark-cli wrote the result to {path}, which could not be read back: {exc}",
|
|
119
|
+
cmd=cmd,
|
|
120
|
+
) from exc
|
|
121
|
+
if not isinstance(payload, dict):
|
|
122
|
+
raise LarkCliError(f"{path} does not hold a JSON object", cmd=cmd)
|
|
123
|
+
|
|
124
|
+
# Keep the receipt's own fields (complete / rows_total / batches) beside the
|
|
125
|
+
# data: `complete` is the read-everything verdict and callers check it.
|
|
126
|
+
merged = dict(payload)
|
|
127
|
+
for key in ("complete", "rows_total", "batches", "bytes_written", "note"):
|
|
128
|
+
if key in data and key not in merged:
|
|
129
|
+
merged[key] = data[key]
|
|
130
|
+
merged["output_path"] = path
|
|
131
|
+
return {**envelope, "data": merged}
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
def envelope_data(envelope: dict[str, Any]) -> dict[str, Any]:
|
|
135
|
+
data = envelope.get("data")
|
|
136
|
+
return data if isinstance(data, dict) else envelope
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
def emit_success(action: str, data: dict[str, Any], warnings: list[str] | None = None) -> None:
|
|
140
|
+
print(
|
|
141
|
+
json.dumps(
|
|
142
|
+
{
|
|
143
|
+
"ok": True,
|
|
144
|
+
"engine": "lark",
|
|
145
|
+
"action": action,
|
|
146
|
+
"data": data,
|
|
147
|
+
"warnings": warnings or [],
|
|
148
|
+
},
|
|
149
|
+
ensure_ascii=False,
|
|
150
|
+
indent=2,
|
|
151
|
+
)
|
|
152
|
+
)
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def emit_error(action: str, message: str, warnings: list[str] | None = None) -> None:
|
|
156
|
+
print(
|
|
157
|
+
json.dumps(
|
|
158
|
+
{
|
|
159
|
+
"ok": False,
|
|
160
|
+
"engine": "lark",
|
|
161
|
+
"action": action,
|
|
162
|
+
"error": message,
|
|
163
|
+
"warnings": warnings or [],
|
|
164
|
+
},
|
|
165
|
+
ensure_ascii=False,
|
|
166
|
+
indent=2,
|
|
167
|
+
)
|
|
168
|
+
)
|
|
169
|
+
sys.exit(1)
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
def sheet_title(sheet: dict[str, Any]) -> str:
|
|
173
|
+
return str(sheet.get("title") or sheet.get("sheet_name") or sheet.get("name") or "")
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
def sheet_identifier(sheet: dict[str, Any]) -> str:
|
|
177
|
+
return str(sheet.get("sheet_id") or sheet.get("id") or "")
|
|
178
|
+
|
|
179
|
+
|
|
180
|
+
def sheet_locator(sheet: dict[str, Any]) -> dict[str, str]:
|
|
181
|
+
sid = sheet_identifier(sheet)
|
|
182
|
+
if sid:
|
|
183
|
+
return {"sheet_id": sid}
|
|
184
|
+
title = sheet_title(sheet)
|
|
185
|
+
if title:
|
|
186
|
+
return {"sheet_name": title}
|
|
187
|
+
return {}
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
def extract_sheets(workbook_data: dict[str, Any]) -> list[dict[str, Any]]:
|
|
191
|
+
sheets = workbook_data.get("sheets")
|
|
192
|
+
if isinstance(sheets, list):
|
|
193
|
+
return [sheet for sheet in sheets if isinstance(sheet, dict)]
|
|
194
|
+
workbook = workbook_data.get("workbook")
|
|
195
|
+
if isinstance(workbook, dict) and isinstance(workbook.get("sheets"), list):
|
|
196
|
+
return [sheet for sheet in workbook["sheets"] if isinstance(sheet, dict)]
|
|
197
|
+
return []
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
def resolve_target_sheets(
|
|
201
|
+
workbook_data: dict[str, Any],
|
|
202
|
+
*,
|
|
203
|
+
sheet_id: str | None = None,
|
|
204
|
+
sheet_name: str | None = None,
|
|
205
|
+
require_one: bool = False,
|
|
206
|
+
) -> list[dict[str, Any]]:
|
|
207
|
+
sheets = extract_sheets(workbook_data)
|
|
208
|
+
if sheet_id:
|
|
209
|
+
matches = [sheet for sheet in sheets if sheet_identifier(sheet) == sheet_id]
|
|
210
|
+
elif sheet_name:
|
|
211
|
+
matches = [sheet for sheet in sheets if sheet_title(sheet) == sheet_name]
|
|
212
|
+
else:
|
|
213
|
+
matches = sheets
|
|
214
|
+
|
|
215
|
+
if require_one:
|
|
216
|
+
if len(matches) == 1:
|
|
217
|
+
return matches
|
|
218
|
+
if not matches:
|
|
219
|
+
raise LarkCliError("No matching sheet found")
|
|
220
|
+
raise LarkCliError("Multiple sheets matched; pass --sheet-id or --sheet-name")
|
|
221
|
+
return matches
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
# Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
|
3
|
+
# SPDX-License-Identifier: MIT
|
|
4
|
+
"""DataFrame ↔ Feishu Sheet typed-JSON helpers.
|
|
5
|
+
|
|
6
|
+
Shared helper pulled out so callers can `import` it instead of copy-pasting.
|
|
7
|
+
`sheet_to_df` supports the read command `+table-get`(见 `lark-sheets-read-data`
|
|
8
|
+
"输出 → DataFrame");`df_to_sheet` 是打包 payload 的通用工具(沙箱只读子集里
|
|
9
|
+
不作为推荐入口,保留仅为 helper 完整性):
|
|
10
|
+
|
|
11
|
+
from sheets_df import df_to_sheet, sheet_to_df
|
|
12
|
+
|
|
13
|
+
Callers run lark-cli themselves; this file is a library, not a CLI.
|
|
14
|
+
"""
|
|
15
|
+
import json
|
|
16
|
+
|
|
17
|
+
import pandas as pd
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def df_to_sheet(df, name, formats=None):
|
|
21
|
+
"""Pack one DataFrame into one entry of a `+table-put --sheets` payload."""
|
|
22
|
+
packed = json.loads(df.to_json(orient="split", date_format="iso"))
|
|
23
|
+
# The protocol requires string column names. pandas keeps integer labels
|
|
24
|
+
# (e.g. the default RangeIndex columns 0/1/2) as JSON numbers, while the
|
|
25
|
+
# dtypes dict keys get stringified during JSON serialization — the CLI
|
|
26
|
+
# then rejects `columns` ("cannot unmarshal number into … type string")
|
|
27
|
+
# and the dtype lookup would miss anyway. Stringify every key once, and
|
|
28
|
+
# refuse to continue when that conversion silently merges two columns.
|
|
29
|
+
normalized_labels = [str(c) for c in df.columns]
|
|
30
|
+
columns = [str(c) for c in packed["columns"]]
|
|
31
|
+
if normalized_labels != columns:
|
|
32
|
+
columns = normalized_labels
|
|
33
|
+
if len(set(columns)) != len(columns):
|
|
34
|
+
raise ValueError(
|
|
35
|
+
"column labels collide after str() conversion; "
|
|
36
|
+
"rename the DataFrame columns before packing"
|
|
37
|
+
)
|
|
38
|
+
packed["columns"] = columns
|
|
39
|
+
dtype_values = list(df.dtypes)
|
|
40
|
+
return {
|
|
41
|
+
"name": name,
|
|
42
|
+
**packed,
|
|
43
|
+
"dtypes": {key: str(dtype) for key, dtype in zip(columns, dtype_values)},
|
|
44
|
+
**({"formats": {str(k): v for k, v in formats.items()}} if formats else {}),
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def sheet_to_df(sheet):
|
|
49
|
+
"""Restore one `+table-get` sheet dict into a typed DataFrame."""
|
|
50
|
+
return pd.DataFrame(sheet["data"], columns=sheet["columns"]).astype(sheet["dtypes"])
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
# slides
|
|
2
|
+
|
|
3
|
+
## 身份
|
|
4
|
+
|
|
5
|
+
- slides 相关的读取操作默认以 `--as user`(用户身份)执行,下文示例统一显式带 `--as user`。
|
|
6
|
+
|
|
7
|
+
## 能力边界
|
|
8
|
+
|
|
9
|
+
本 skill 在沙箱内是**只读**的:用于读取和检查已有演示文稿,不生成、不修改幻灯片内容。
|
|
10
|
+
|
|
11
|
+
- 读取整份演示文稿的完整 XML(`slides xml_presentations get`)。
|
|
12
|
+
- 按 `slide_id` 读取单页 XML,可指定历史版本(`slides xml_presentation.slide get`)。
|
|
13
|
+
- 列出历史版本、查询回滚任务状态(`slides +history-list` / `+history-revert-status`)。
|
|
14
|
+
|
|
15
|
+
## 核心概念
|
|
16
|
+
|
|
17
|
+
### URL 格式与 Token
|
|
18
|
+
|
|
19
|
+
| URL 格式 | 示例 | Token 类型 | 处理方式 |
|
|
20
|
+
|----------|------|-----------|----------|
|
|
21
|
+
| `/slides/` | `https://example.larkoffice.com/slides/xxxxxxxxxxxxx` | `xml_presentation_id` | URL 路径中的 token 直接作为 `xml_presentation_id` 使用 |
|
|
22
|
+
| `/wiki/` | `https://example.larkoffice.com/wiki/wikcnxxxxxxxxx` | `wiki_token` | ⚠️ **不能直接使用**,需要先查询获取真实的 `obj_token` |
|
|
23
|
+
|
|
24
|
+
### Wiki 链接特殊处理(关键!)
|
|
25
|
+
|
|
26
|
+
知识库链接(`/wiki/TOKEN`)不能直接当 `xml_presentation_id`。调用 slides 原生 API 前,先查询
|
|
27
|
+
wiki 节点,确认 `node.obj_type == "slides"`,再用 `node.obj_token` 作为真实 presentation ID。
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
lark-cli wiki spaces get_node --as user --params '{"token":"wiki_token"}'
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
例外:`slides +history-list` / `+history-revert-status` 的 `--presentation` 可以直接接收
|
|
34
|
+
wiki URL(自动解析,要求该节点是幻灯片),不需要先手动查询节点。
|
|
35
|
+
|
|
36
|
+
### 资源关系
|
|
37
|
+
|
|
38
|
+
```text
|
|
39
|
+
Wiki Space (知识空间)
|
|
40
|
+
└── Wiki Node (知识库节点, obj_type: slides)
|
|
41
|
+
└── obj_token → xml_presentation_id
|
|
42
|
+
|
|
43
|
+
Slides (演示文稿)
|
|
44
|
+
├── xml_presentation_id (演示文稿唯一标识)
|
|
45
|
+
├── revision_id (版本号)
|
|
46
|
+
└── Slide (幻灯片页面)
|
|
47
|
+
└── slide_id (页面唯一标识)
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## References
|
|
51
|
+
|
|
52
|
+
- 读取整份 XML:[`lark-slides-xml-presentations-get.md`](references/lark-slides-xml-presentations-get.md)
|
|
53
|
+
- 读取单页 XML:[`lark-slides-xml-presentation-slide-get.md`](references/lark-slides-xml-presentation-slide-get.md)
|
|
54
|
+
- 历史版本与回滚状态:[`lark-slides-history.md`](references/lark-slides-history.md)
|
|
55
|
+
|
|
56
|
+
## 快捷命令(沙箱内仅以下两个可用,均只读)
|
|
57
|
+
|
|
58
|
+
- `+history-list` — 分页列出历史版本,返回 `entries[]`(含 `history_version_id`、`revision_id`、`edit_time`)
|
|
59
|
+
- `+history-revert-status` — 按 `task_id` 查询回滚任务状态(`status`、`failed_block_tokens`)
|
|
60
|
+
|
|
61
|
+
`--presentation` 接收 `xml_presentation_id`、`/slides/` URL 或可解析为幻灯片的 `/wiki/` URL。
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
lark-cli slides +history-list --as user --presentation "<slides_url_or_token>" --page-size 20
|
|
65
|
+
lark-cli slides +history-revert-status --as user --presentation "<slides_url_or_token>" --task-id "<task_id>"
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## API(沙箱内仅以下原生 API 调用可用)
|
|
69
|
+
|
|
70
|
+
本沙箱内**仅**以下原生 `<service> <resource> <method>` 组合可用(全部只读),不要再自行拼其它
|
|
71
|
+
service/api 组合去试。调用前先用 `lark-cli schema slides.<resource>.<method>` 查看最新参数结构。
|
|
72
|
+
|
|
73
|
+
### xml_presentations
|
|
74
|
+
|
|
75
|
+
- `get` — 读取演示文稿的完整 XML 内容(返回 `data.xml_presentation.content`)
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
lark-cli slides xml_presentations get --as user --params '{"xml_presentation_id":"<id>","revision_id":-1}'
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### xml_presentation.slide
|
|
82
|
+
|
|
83
|
+
- `get` — 按 `slide_id` 读取单页 XML,可指定历史版本
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
lark-cli slides xml_presentation.slide get --as user --params '{"xml_presentation_id":"<id>","slide_id":"<slide_id>","revision_id":-1}'
|
|
87
|
+
```
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# slides history(历史版本与回滚任务状态)
|
|
2
|
+
|
|
3
|
+
用于查看 Slides XML presentation 的历史版本列表,以及查询回滚任务的执行状态。这两个都是
|
|
4
|
+
**只读**快捷命令:
|
|
5
|
+
|
|
6
|
+
- `slides +history-list` — 分页列出历史版本。
|
|
7
|
+
- `slides +history-revert-status` — 按 `task_id` 查询回滚任务状态。
|
|
8
|
+
|
|
9
|
+
> 发起回滚本身(`+history-revert`)是高风险写操作,不在本沙箱的只读推荐入口
|
|
10
|
+
> 内。用户临时要求回滚而撞到 exit 10 时,按上层 lark-cli SKILL.md 的高风险写审批协议处理。
|
|
11
|
+
> `+history-revert-status` 只负责查询一个已存在的回滚任务的执行进度。
|
|
12
|
+
|
|
13
|
+
`entries[].edit_time` 是 UTC RFC3339 时间字符串(例如 `2026-06-22T12:24:45Z`)。按时间匹配时先将
|
|
14
|
+
其解析为时间值,再比较先后关系或时间差。
|
|
15
|
+
|
|
16
|
+
## 命令形态
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
# 列出历史版本
|
|
20
|
+
lark-cli slides +history-list --as user --presentation "<slides_url_or_token>" --page-size 20
|
|
21
|
+
|
|
22
|
+
# 翻页
|
|
23
|
+
lark-cli slides +history-list --as user --presentation "<slides_url_or_token>" --page-size 20 --page-token "<page_token>"
|
|
24
|
+
|
|
25
|
+
# 查询回滚任务状态
|
|
26
|
+
lark-cli slides +history-revert-status --as user --presentation "<slides_url_or_token>" --task-id "<task_id>"
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## 参数
|
|
30
|
+
|
|
31
|
+
| 命令 | 参数 | 必填 | 说明 |
|
|
32
|
+
|-|-|-|-|
|
|
33
|
+
| `+history-list` | `--presentation` | 是 | `xml_presentation_id`、Slides URL,或可解析为 Slides 的 wiki URL |
|
|
34
|
+
| `+history-list` | `--page-size` | 否 | 返回条数,范围 `1-20`,默认 `20` |
|
|
35
|
+
| `+history-list` | `--page-token` | 否 | 上一页返回的 `page_token` |
|
|
36
|
+
| `+history-revert-status` | `--presentation` | 是 | 同一个演示文稿 |
|
|
37
|
+
| `+history-revert-status` | `--task-id` | 是 | 发起回滚时返回的 `task_id` |
|
|
38
|
+
|
|
39
|
+
> `+history-list` 支持分页:无 `--page-token` 取第一页,`has_more=true` 时用上一页返回的
|
|
40
|
+
> `page_token` 继续翻页。`--presentation` 收到 wiki URL 时自动解析出真实演示文稿 ID,
|
|
41
|
+
> 无需先手动查询 wiki 节点。
|
|
42
|
+
|
|
43
|
+
## 按 revision_id 或时间点定位版本
|
|
44
|
+
|
|
45
|
+
当用户说"看看昨天下午 3 点的版本""revision_id=42 是哪一条"这类需求时,用 `+history-list` 定位:
|
|
46
|
+
|
|
47
|
+
1. 执行 `slides +history-list --presentation <presentation>` 获取第一页历史记录;只有
|
|
48
|
+
`has_more=true` 且还需要更多候选时才继续传 `--page-token` 翻页。
|
|
49
|
+
2. 如果用户给出 `revision_id`:先筛选当前页中 `entries[].revision_id == 用户给出的 revision_id`。
|
|
50
|
+
如果未命中且 `has_more=true`,继续拉下一页;如果已经命中候选,最多额外再拉一页,补齐同一个
|
|
51
|
+
`revision_id` 可能跨页出现的相邻 `history_version_id`。若用户同时给出目标时间,在候选里选择
|
|
52
|
+
`edit_time` 与目标时间最接近的一条;若未给目标时间但候选只有一条,可直接使用;若多个候选无法
|
|
53
|
+
可靠区分,不要自行取第一条,向用户展示候选并确认。
|
|
54
|
+
3. 如果用户只给出时间:用 `entries[].edit_time` 匹配,选择目标时刻之前最近的一条;如果用户表达
|
|
55
|
+
的是"最接近某时刻",则选择绝对时间差最小的一条。
|
|
56
|
+
4. 从最终匹配条目读取 `history_version_id`。`history_version_id` 对应服务端 `minor_history.version`。
|
|
57
|
+
|
|
58
|
+
候选确认时使用类似格式:
|
|
59
|
+
|
|
60
|
+
```text
|
|
61
|
+
同一个 revision_id 命中多个历史版本,请确认是哪一条:
|
|
62
|
+
- history_version_id=11 revision_id=42 edit_time=2026-06-22T12:24:45Z name=...
|
|
63
|
+
- history_version_id=12 revision_id=42 edit_time=2026-06-22T12:25:14Z name=...
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## 回滚任务状态轮询
|
|
67
|
+
|
|
68
|
+
已发起的回滚任务返回 `task_id` 与 `status` 后:
|
|
69
|
+
|
|
70
|
+
1. 如果 `status` 不是 `running`,不再调用状态接口。
|
|
71
|
+
2. 如果 `status` 是 `running`,等待响应中的 `poll_after_ms` 后调用 `+history-revert-status`;
|
|
72
|
+
`poll_after_ms` 缺失、为 `0` 或非法时,默认等待 10 秒。
|
|
73
|
+
3. 状态查询返回 `running` 时继续轮询;返回 `done`、`partial_failed` 或 `failed` 时停止。
|
|
74
|
+
4. 默认最多轮询 5 分钟。达到上限后停止轮询,向用户说明任务仍在运行并返回 `task_id`,不得将其
|
|
75
|
+
描述为回滚失败。
|
|
76
|
+
5. 状态查询出现临时错误时,按相同间隔最多连续重试 3 次;只重试 `+history-revert-status`。
|
|
77
|
+
6. `partial_failed` 或 `failed` 时展示 `failed_block_tokens`。
|
|
78
|
+
|
|
79
|
+
## 返回值要点
|
|
80
|
+
|
|
81
|
+
`+history-list` 返回:
|
|
82
|
+
|
|
83
|
+
```json
|
|
84
|
+
{
|
|
85
|
+
"entries": [
|
|
86
|
+
{
|
|
87
|
+
"revision_id": 42,
|
|
88
|
+
"history_version_id": "11",
|
|
89
|
+
"edit_time": "2026-06-22T12:24:45Z",
|
|
90
|
+
"type": 1,
|
|
91
|
+
"name": "版本名",
|
|
92
|
+
"description": "版本说明",
|
|
93
|
+
"editor_ids": ["ou_xxx"]
|
|
94
|
+
}
|
|
95
|
+
],
|
|
96
|
+
"has_more": true,
|
|
97
|
+
"page_token": "page_token"
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
`+history-revert-status` 返回:
|
|
102
|
+
|
|
103
|
+
```json
|
|
104
|
+
{
|
|
105
|
+
"status": "partial_failed",
|
|
106
|
+
"history_version_id": "11",
|
|
107
|
+
"failed_block_tokens": ["blk_xxx"]
|
|
108
|
+
}
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
`status` 可能是 `running`、`done`、`partial_failed`、`failed`。当状态是 `partial_failed` 或
|
|
112
|
+
`failed` 时,优先检查 `failed_block_tokens`。
|
|
113
|
+
|
|
114
|
+
## 相关命令
|
|
115
|
+
|
|
116
|
+
- [xml_presentations get](lark-slides-xml-presentations-get.md) — 读取整份演示文稿 XML
|
|
117
|
+
- [xml_presentation.slide get](lark-slides-xml-presentation-slide-get.md) — 按 `slide_id` 读取单页 XML
|