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
spreadsheet_tokenis the id in the share URL after/sheets/(e.g.https://…/sheets/shtcnXXXX→ tokenshtcnXXXX). Read it from the URL the user pasted; never invent it.- Range =
{sheet_id}!A1:D10and every read/write wraps values in avalueRangeobject. A range without thesheet_id!prefix, or values not wrapped invalueRange, is the usual 400.
How to run it
Resolve the sheet ids (and scope probe).
GET /open-apis/sheets/v3/spreadsheets/{spreadsheet_token}/sheets/querylists every sheet with itssheet_idandtitle. On 403/scope error, report it verbatim, say the tenant app needs sheets scopes (e.g.sheets:spreadsheet), and stop. Pick thesheet_idfor the tab the user means (default the first tab if there is only one).Read a range.
GET /open-apis/sheets/v2/spreadsheets/{spreadsheet_token}/values/{sheet_id}!A1:D50→data.valueRange.valuesis a row-major 2D array. Render it as a compact table and say which range you read.Append rows to the bottom.
POST /open-apis/sheets/v2/spreadsheets/{spreadsheet_token}/values_append?insertDataOption=INSERT_ROWSbody{"valueRange":{"range":"{sheet_id}!A1:C1","values":[["a","b","c"],["d","e","f"]]}}. Therangeonly anchors the columns/sheet; appended rows go after the existing data. Echo the rows and confirm before writing.Overwrite a specific range.
PUT /open-apis/sheets/v2/spreadsheets/{spreadsheet_token}/valuesbody{"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(missingsheet_id!prefix) or values not wrapped invalueRange; 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_tokenorsheet_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.