@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.
Files changed (207) hide show
  1. package/miaoda/ai-data-processing/SKILL.md +4 -1
  2. package/miaoda/animation-skill/SKILL.md +348 -0
  3. package/miaoda/authz-cli/SKILL.md +1 -0
  4. package/miaoda/charts-skill/SKILL.md +264 -0
  5. package/miaoda/creative-to-fullstack/SKILL.md +64 -0
  6. package/miaoda/data-analysis/SKILL.md +151 -0
  7. package/miaoda/data-analysis/references/json-output-specification.md +277 -0
  8. package/miaoda/data-analysis/references/post-analysis-guide.md +77 -0
  9. package/miaoda/data-analysis/references/python-analysis-reference.md +272 -0
  10. package/miaoda/data-analysis/references/tmp-file-management-guide.md +100 -0
  11. package/miaoda/debug-investigation/SKILL.md +35 -23
  12. package/miaoda/extract-json-schema/SKILL.md +147 -0
  13. package/miaoda/feishu/SKILL.md +4 -4
  14. package/miaoda/forms-skill/SKILL.md +46 -4
  15. package/miaoda/lark-apps/SKILL.md +37 -0
  16. package/miaoda/lark-apps/references/openapi-key.md +80 -0
  17. package/miaoda/lark-apps-authz/SKILL.md +292 -0
  18. package/miaoda/lark-apps-authz/references/permission-points.md +39 -0
  19. package/miaoda/lark-apps-authz/references/role.md +122 -0
  20. package/miaoda/lark-apps-db/SKILL.md +227 -0
  21. package/miaoda/lark-apps-db/references/full-reference.md +424 -0
  22. package/miaoda/lark-apps-file/SKILL.md +216 -0
  23. package/miaoda/lark-apps-ops/SKILL.md +67 -0
  24. package/miaoda/lark-apps-ops/references/lark-apps-access-scope-get.md +30 -0
  25. package/miaoda/lark-apps-ops/references/lark-apps-access-scope-set.md +40 -0
  26. package/miaoda/lark-apps-ops/references/lark-apps-cache.md +62 -0
  27. package/miaoda/lark-apps-ops/references/lark-apps-env.md +46 -0
  28. package/miaoda/lark-apps-ops/references/lark-apps-export.md +46 -0
  29. package/miaoda/lark-apps-ops/references/lark-apps-local-dev.md +26 -0
  30. package/miaoda/lark-apps-ops/references/lark-apps-mcp.md +25 -0
  31. package/miaoda/lark-apps-ops/references/lark-apps-member.md +93 -0
  32. package/miaoda/lark-apps-ops/references/lark-apps-observability.md +46 -0
  33. package/miaoda/lark-apps-ops/references/lark-apps-plugin-install.md +36 -0
  34. package/miaoda/lark-apps-ops/references/lark-apps-plugin-list.md +23 -0
  35. package/miaoda/lark-apps-ops/references/lark-apps-plugin-uninstall.md +25 -0
  36. package/miaoda/lark-apps-ops/references/lark-apps-release-create.md +37 -0
  37. package/miaoda/lark-apps-ops/references/lark-apps-release-get.md +59 -0
  38. package/miaoda/lark-apps-ops/references/lark-apps-release-list.md +31 -0
  39. package/miaoda/lark-apps-ops/references/lark-apps-update.md +30 -0
  40. package/miaoda/lark-apps-ops/references/lark-apps-user-id-convert.md +63 -0
  41. package/miaoda/lark-apps-ops/references/openapi-key.md +80 -0
  42. package/miaoda/lark-design-prototype/DESIGN.md +603 -0
  43. package/miaoda/lark-design-prototype/SKILL.md +85 -0
  44. package/miaoda/lark-design-prototype/references/assets/card-illustration-library.md +113 -0
  45. package/miaoda/lark-design-prototype/references/case-matching.md +53 -0
  46. package/miaoda/lark-design-prototype/references/cases/conversational-ai-home.md +27 -0
  47. package/miaoda/lark-design-prototype/references/cases/data-table.md +30 -0
  48. package/miaoda/lark-design-prototype/references/cases/official-home.md +26 -0
  49. package/miaoda/lark-design-prototype/references/cases/workspace-home.md +34 -0
  50. package/miaoda/lark-design-prototype/references/color-roles.md +163 -0
  51. package/miaoda/lark-design-prototype/references/component-selection.md +134 -0
  52. package/miaoda/lark-design-prototype/references/design-quality-checklist.md +156 -0
  53. package/miaoda/lark-design-prototype/references/form-shell-patterns.md +77 -0
  54. package/miaoda/lark-design-prototype/references/icon-semantics.md +237 -0
  55. package/miaoda/lark-design-prototype/references/layout-interaction.md +164 -0
  56. package/miaoda/lark-design-prototype/references/page-contract.md +281 -0
  57. package/miaoda/lark-design-prototype/references/product-patterns.md +93 -0
  58. package/miaoda/lark-design-prototype/references/prompt-expansion.md +107 -0
  59. package/miaoda/lark-design-prototype/references/restoration-traps.md +113 -0
  60. package/miaoda/lark-design-prototype/references/token-semantics.md +112 -0
  61. package/miaoda/lark-design-prototype/references/visual-brief.md +125 -0
  62. package/miaoda/lark-design-prototype/references/visual-style-prompts.md +61 -0
  63. package/miaoda/lark-design-prototype/scripts/icon-query.mjs +272 -0
  64. package/miaoda/lark-design-prototype/scripts/token-query.mjs +76 -0
  65. package/miaoda/lark-design-prototype/scripts/verify-static-html.mjs +117 -0
  66. package/miaoda/miaoda-file/SKILL.md +1 -0
  67. package/miaoda/miaoda-sql/SKILL.md +21 -2
  68. package/miaoda/performance-review/SKILL.md +144 -0
  69. package/miaoda/performance-review/references/business-analyzer.md +139 -0
  70. package/miaoda/performance-review/references/examples.md +107 -0
  71. package/miaoda/semantic-search/SKILL.md +6 -4
  72. package/miaoda/table-skill/SKILL.md +2 -0
  73. package/{shared → miaoda}/testing-guide/SKILL.md +119 -13
  74. package/miaoda-design/lark-apps-comment/SKILL.md +119 -0
  75. package/miaoda-design/lark-apps-ops/SKILL.md +47 -0
  76. package/miaoda-design/lark-apps-ops/references/lark-apps-release-create.md +52 -0
  77. package/miaoda-design/lark-apps-ops/references/lark-apps-release-get.md +59 -0
  78. package/miaoda-design/lark-apps-ops/references/lark-apps-release-list.md +31 -0
  79. package/miaoda-design/lark-apps-ops/references/lark-apps-update.md +33 -0
  80. package/{shared → miaoda-modern}/charts-skill/SKILL.md +1 -1
  81. package/miaoda-modern/debug-investigation/SKILL.md +1 -1
  82. package/miaoda-modern/forms-skill/SKILL.md +70 -7
  83. package/{shared → miaoda-modern}/lark-apps/SKILL.md +5 -5
  84. package/miaoda-modern/lark-apps/references/openapi-key.md +80 -0
  85. package/miaoda-modern/lark-apps-ops/SKILL.md +67 -0
  86. package/miaoda-modern/lark-apps-ops/references/lark-apps-access-scope-get.md +30 -0
  87. package/miaoda-modern/lark-apps-ops/references/lark-apps-access-scope-set.md +40 -0
  88. package/miaoda-modern/lark-apps-ops/references/lark-apps-cache.md +62 -0
  89. package/miaoda-modern/lark-apps-ops/references/lark-apps-env.md +46 -0
  90. package/miaoda-modern/lark-apps-ops/references/lark-apps-export.md +46 -0
  91. package/miaoda-modern/lark-apps-ops/references/lark-apps-local-dev.md +26 -0
  92. package/miaoda-modern/lark-apps-ops/references/lark-apps-mcp.md +25 -0
  93. package/miaoda-modern/lark-apps-ops/references/lark-apps-member.md +93 -0
  94. package/miaoda-modern/lark-apps-ops/references/lark-apps-observability.md +46 -0
  95. package/miaoda-modern/lark-apps-ops/references/lark-apps-plugin-install.md +36 -0
  96. package/miaoda-modern/lark-apps-ops/references/lark-apps-plugin-list.md +23 -0
  97. package/miaoda-modern/lark-apps-ops/references/lark-apps-plugin-uninstall.md +25 -0
  98. package/miaoda-modern/lark-apps-ops/references/lark-apps-release-create.md +37 -0
  99. package/miaoda-modern/lark-apps-ops/references/lark-apps-release-get.md +59 -0
  100. package/miaoda-modern/lark-apps-ops/references/lark-apps-release-list.md +31 -0
  101. package/miaoda-modern/lark-apps-ops/references/lark-apps-update.md +30 -0
  102. package/miaoda-modern/lark-apps-ops/references/lark-apps-user-id-convert.md +63 -0
  103. package/{shared/lark-apps → miaoda-modern/lark-apps-ops}/references/openapi-key.md +3 -3
  104. package/miaoda-modern/lark-design-prototype/DESIGN.md +603 -0
  105. package/miaoda-modern/lark-design-prototype/SKILL.md +85 -0
  106. package/miaoda-modern/lark-design-prototype/references/assets/card-illustration-library.md +113 -0
  107. package/miaoda-modern/lark-design-prototype/references/case-matching.md +53 -0
  108. package/miaoda-modern/lark-design-prototype/references/cases/conversational-ai-home.md +27 -0
  109. package/miaoda-modern/lark-design-prototype/references/cases/data-table.md +30 -0
  110. package/miaoda-modern/lark-design-prototype/references/cases/official-home.md +26 -0
  111. package/miaoda-modern/lark-design-prototype/references/cases/workspace-home.md +34 -0
  112. package/miaoda-modern/lark-design-prototype/references/color-roles.md +163 -0
  113. package/miaoda-modern/lark-design-prototype/references/component-selection.md +134 -0
  114. package/miaoda-modern/lark-design-prototype/references/design-quality-checklist.md +156 -0
  115. package/miaoda-modern/lark-design-prototype/references/form-shell-patterns.md +77 -0
  116. package/miaoda-modern/lark-design-prototype/references/icon-semantics.md +237 -0
  117. package/miaoda-modern/lark-design-prototype/references/layout-interaction.md +164 -0
  118. package/miaoda-modern/lark-design-prototype/references/page-contract.md +281 -0
  119. package/miaoda-modern/lark-design-prototype/references/product-patterns.md +93 -0
  120. package/miaoda-modern/lark-design-prototype/references/prompt-expansion.md +107 -0
  121. package/miaoda-modern/lark-design-prototype/references/restoration-traps.md +113 -0
  122. package/miaoda-modern/lark-design-prototype/references/token-semantics.md +112 -0
  123. package/miaoda-modern/lark-design-prototype/references/visual-brief.md +125 -0
  124. package/miaoda-modern/lark-design-prototype/references/visual-style-prompts.md +61 -0
  125. package/miaoda-modern/lark-design-prototype/scripts/icon-query.mjs +272 -0
  126. package/miaoda-modern/lark-design-prototype/scripts/token-query.mjs +76 -0
  127. package/miaoda-modern/lark-design-prototype/scripts/verify-static-html.mjs +117 -0
  128. package/miaoda-modern/memory/SKILL.md +86 -0
  129. package/{shared → miaoda-modern}/performance-review/SKILL.md +3 -3
  130. package/miaoda-modern/reviewer-usage/SKILL.md +113 -0
  131. package/package.json +1 -1
  132. package/shared/attachment/SKILL.md +5 -1
  133. package/shared/lark-cli/SKILL.md +221 -0
  134. package/shared/lark-cli/lark-base/README.md +61 -0
  135. package/shared/lark-cli/lark-base/references/lark-base-commands.md +123 -0
  136. package/shared/lark-cli/lark-calendar/README.md +158 -0
  137. package/shared/lark-cli/lark-calendar/references/lark-calendar-meeting.md +30 -0
  138. package/shared/lark-cli/lark-calendar/references/lark-calendar-room-find.md +108 -0
  139. package/shared/lark-cli/lark-calendar/references/lark-calendar-suggestion.md +120 -0
  140. package/shared/lark-cli/lark-contact/README.md +35 -0
  141. package/shared/lark-cli/lark-contact/references/lark-contact-get-user.md +13 -0
  142. package/shared/lark-cli/lark-contact/references/lark-contact-search-user.md +121 -0
  143. package/shared/lark-cli/lark-doc/README.md +68 -0
  144. package/shared/lark-cli/lark-doc/references/lark-doc-fetch.md +138 -0
  145. package/shared/lark-cli/lark-doc/references/lark-doc-history.md +61 -0
  146. package/shared/lark-cli/lark-drive/README.md +158 -0
  147. package/shared/lark-cli/lark-drive/references/lark-drive-batch-query-comments.md +44 -0
  148. package/shared/lark-cli/lark-drive/references/lark-drive-files-list.md +183 -0
  149. package/shared/lark-cli/lark-drive/references/lark-drive-list-replies.md +49 -0
  150. package/shared/lark-cli/lark-im/README.md +70 -0
  151. package/shared/lark-cli/lark-im/references/lark-im-chat-list.md +140 -0
  152. package/shared/lark-cli/lark-im/references/lark-im-chat-members-list.md +84 -0
  153. package/shared/lark-cli/lark-im/references/lark-im-chat-search.md +135 -0
  154. package/shared/lark-cli/lark-im/references/lark-im-reactions.md +232 -0
  155. package/shared/lark-cli/lark-minutes/README.md +51 -0
  156. package/shared/lark-cli/lark-minutes/references/lark-minutes-download.md +130 -0
  157. package/shared/lark-cli/lark-sheets/README.md +174 -0
  158. package/shared/lark-cli/lark-sheets/references/lark-sheets-changeset.md +105 -0
  159. package/shared/lark-cli/lark-sheets/references/lark-sheets-chart.md +46 -0
  160. package/shared/lark-cli/lark-sheets/references/lark-sheets-conditional-format.md +42 -0
  161. package/shared/lark-cli/lark-sheets/references/lark-sheets-filter-view.md +51 -0
  162. package/shared/lark-cli/lark-sheets/references/lark-sheets-filter.md +42 -0
  163. package/shared/lark-cli/lark-sheets/references/lark-sheets-float-image.md +43 -0
  164. package/shared/lark-cli/lark-sheets/references/lark-sheets-formula-verify.md +64 -0
  165. package/shared/lark-cli/lark-sheets/references/lark-sheets-history.md +70 -0
  166. package/shared/lark-cli/lark-sheets/references/lark-sheets-pivot-table.md +44 -0
  167. package/shared/lark-cli/lark-sheets/references/lark-sheets-read-data.md +287 -0
  168. package/shared/lark-cli/lark-sheets/references/lark-sheets-search-replace.md +67 -0
  169. package/shared/lark-cli/lark-sheets/references/lark-sheets-sheet-structure.md +52 -0
  170. package/shared/lark-cli/lark-sheets/references/lark-sheets-sparkline.md +47 -0
  171. package/shared/lark-cli/lark-sheets/references/lark-sheets-workbook.md +69 -0
  172. package/shared/lark-cli/lark-sheets/scripts/lark_detect_subtables.py +596 -0
  173. package/shared/lark-cli/lark-sheets/scripts/lark_inspect_workbook.py +193 -0
  174. package/shared/lark-cli/lark-sheets/scripts/lark_profile_table.py +616 -0
  175. package/shared/lark-cli/lark-sheets/scripts/lark_sheet_range.py +176 -0
  176. package/shared/lark-cli/lark-sheets/scripts/lark_sheet_read_cli.py +221 -0
  177. package/shared/lark-cli/lark-sheets/scripts/sheets_df.py +50 -0
  178. package/shared/lark-cli/lark-slides/README.md +87 -0
  179. package/shared/lark-cli/lark-slides/references/lark-slides-history.md +117 -0
  180. package/shared/lark-cli/lark-slides/references/lark-slides-xml-presentation-slide-get.md +108 -0
  181. package/shared/lark-cli/lark-slides/references/lark-slides-xml-presentations-get.md +77 -0
  182. package/shared/lark-cli/lark-task/README.md +93 -0
  183. package/shared/lark-cli/lark-task/references/lark-task-get-my-tasks.md +57 -0
  184. package/shared/lark-cli/lark-task/references/lark-task-get-related-tasks.md +49 -0
  185. package/shared/lark-cli/lark-task/references/lark-task-search.md +36 -0
  186. package/shared/lark-cli/lark-task/references/lark-task-tasklist-search.md +35 -0
  187. package/shared/lark-cli/lark-vc/README.md +40 -0
  188. package/shared/lark-cli/lark-vc/references/lark-vc-recording.md +31 -0
  189. package/shared/lark-cli/lark-whiteboard/README.md +34 -0
  190. package/shared/lark-cli/lark-whiteboard/references/lark-whiteboard-export.md +59 -0
  191. package/shared/lark-cli/lark-wiki/README.md +50 -0
  192. package/shared/lark-cli/lark-wiki/references/lark-wiki-node-get.md +70 -0
  193. package/shared/lark-cli/lark-wiki/references/lark-wiki-node-list.md +95 -0
  194. package/shared/lark-cli/lark-wiki/references/lark-wiki-space-list.md +68 -0
  195. package/miaoda-design/attachment/SKILL.md +0 -58
  196. package/shared/dev-channel-probe/SKILL.md +0 -40
  197. /package/{shared → miaoda}/memory/SKILL.md +0 -0
  198. /package/{shared → miaoda}/reviewer-usage/SKILL.md +0 -0
  199. /package/{shared → miaoda-modern}/animation-skill/SKILL.md +0 -0
  200. /package/{shared → miaoda-modern}/data-analysis/SKILL.md +0 -0
  201. /package/{shared → miaoda-modern}/data-analysis/references/json-output-specification.md +0 -0
  202. /package/{shared → miaoda-modern}/data-analysis/references/post-analysis-guide.md +0 -0
  203. /package/{shared → miaoda-modern}/data-analysis/references/python-analysis-reference.md +0 -0
  204. /package/{shared → miaoda-modern}/data-analysis/references/tmp-file-management-guide.md +0 -0
  205. /package/{shared → miaoda-modern}/extract-json-schema/SKILL.md +0 -0
  206. /package/{shared → miaoda-modern}/performance-review/references/business-analyzer.md +0 -0
  207. /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