# Lark Sheets Ops

> Read and write Lark Sheets (电子表格) through the bot's NyxID-brokered sheets APIs — find a spreadsheet and its sheet ids, read a cell range, append rows to the bottom, and overwrite a range. Handles the range format (sheetId!A1:D10) and the valueRange wrapper, extracts the spreadsheet_token from a share URL, and doubles as the sheets-scope probe — on a scope 403 it reports the exact missing permission. Lark Sheets here is the spreadsheet product, distinct from Lark Base / Bitable — use the Base skill for Bitable tables.

- Skill: `chronoaiproject/lark-sheets-ops` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx get-skill add chronoaiproject/lark-sheets-ops`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chronoaiproject/lark-sheets-ops/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: ChronoAIProject (https://skillmd.com/u/chronoaiproject)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/chronoaiproject/lark-sheets-ops

---


# Lark Sheets Ops

Use for "把这些数据追加到那张表 / 读一下这个表格 / 把第二列改成 X" against a **Lark Sheets**
spreadsheet. (For a **Base / Bitable** table — records, fields, views — use the Base skill instead;
they are different products with different APIs.)

**You (the agent) run the flow yourself** via NyxID-brokered access `nyxid_proxy`
`{slug:"api-lark-bot", path:"/open-apis/sheets/...", method:...}`. NyxID injects the bot's
`tenant_access_token` server-side — never ask for a token. Paths start at `/open-apis/...`.

## Two footguns

1. **`spreadsheet_token`** is the id in the share URL after `/sheets/` (e.g.
   `https://…/sheets/shtcnXXXX` → token `shtcnXXXX`). Read it from the URL the user pasted; never invent it.
2. **Range = `{sheet_id}!A1:D10`** and every read/write wraps values in a `valueRange` object. A range
   without the `sheet_id!` prefix, or values not wrapped in `valueRange`, is the usual 400.

## How to run it

1. **Resolve the sheet ids (and scope probe).** `GET /open-apis/sheets/v3/spreadsheets/{spreadsheet_token}/sheets/query`
   lists every sheet with its `sheet_id` and `title`. On 403/scope error, report it verbatim, say the
   tenant app needs sheets scopes (e.g. `sheets:spreadsheet`), and stop. Pick the `sheet_id` for the
   tab the user means (default the first tab if there is only one).

2. **Read a range.** `GET /open-apis/sheets/v2/spreadsheets/{spreadsheet_token}/values/{sheet_id}!A1:D50`
   → `data.valueRange.values` is a row-major 2D array. Render it as a compact table and say which range
   you read.

3. **Append rows to the bottom.**
   `POST /open-apis/sheets/v2/spreadsheets/{spreadsheet_token}/values_append?insertDataOption=INSERT_ROWS`
   body `{"valueRange":{"range":"{sheet_id}!A1:C1","values":[["a","b","c"],["d","e","f"]]}}`. The
   `range` only anchors the columns/sheet; appended rows go after the existing data. Echo the rows and
   confirm before writing.

4. **Overwrite a specific range.**
   `PUT /open-apis/sheets/v2/spreadsheets/{spreadsheet_token}/values`
   body `{"valueRange":{"range":"{sheet_id}!A2:C3","values":[[...],[...]]}}`. This **replaces** the
   cells in that exact range — echo the range and the new values and get an explicit confirm first,
   because it overwrites existing content.

## Failure semantics

- Scope 403 / `99991xxx` → verbatim error + the missing sheets scope; never retry blindly.
- 400 on read/write → almost always a bad `range` (missing `sheet_id!` prefix) or values not wrapped
  in `valueRange`; fix the shape and retry once.

## Guardrails

- Append is additive and low-risk; **overwrite (PUT) replaces cells** — always echo the target range
  and values and get an explicit confirm before a PUT.
- Never invent a `spreadsheet_token` or `sheet_id` — read the token from the URL and the sheet_id from
  step 1.
- Only use real returned data; never ask the user for tokens — NyxID handles all credentials.

