nyx-lark

name	nyx-lark
description	Lark/Feishu integration via NyxID proxy. Replaces lark-cli — call Lark OpenAPI directly through nyxid proxy request with automatic credential injection.
version	1.0.0
metadata	{"category":"plain","tag":["nyxid","lark","feishu","messaging","calendar","drive"],"requires":{"bins":["nyxid"]}}

nyx-lark

This skill replaces all 20 lark-cli skills. Instead of lark-cli <service> +<shortcut>, use nyxid proxy request <slug> <path>. NyxID handles tenant token exchange (bot) and OAuth token injection (user) automatically.

1. Dual Service Architecture

Two NyxID services for Lark, matching lark-cli's --as bot / --as user:

Service	Identity	Auth Method	Base URL	Path Convention
api-lark-bot	Bot (tenant_access_token)	Token exchange	https://open.larksuite.com	Paths start with /open-apis/
api-lark	User (user_access_token)	OAuth	https://open.larksuite.com/open-apis	Paths start with / (no /open-apis/ prefix)

Same API, different service — the base URL already contains the prefix for user.

The key difference: api-lark-bot base URL ends at the domain, so you must include /open-apis/ in every path. api-lark base URL already includes /open-apis, so paths start directly with the API version segment.

# Bot: list chats — note the /open-apis/ prefix
nyxid proxy request api-lark-bot /open-apis/im/v1/chats

# User: list chats — no /open-apis/ prefix needed
nyxid proxy request api-lark /im/v1/chats

# Bot: send message — POST with JSON body
nyxid proxy request api-lark-bot "/open-apis/im/v1/messages?receive_id_type=chat_id" \
  -m POST -d '{"receive_id":"oc_xxx","msg_type":"text","content":"{\"text\":\"hello\"}"}'

# User: get primary calendar
nyxid proxy request api-lark /calendar/v4/calendars/primary

If you accidentally double the prefix (e.g., api-lark /open-apis/im/v1/chats), the downstream URL becomes /open-apis/open-apis/... and returns 404.

2. Identity Routing Table

Which service to use for each Lark API domain:

Domain	Service	Reason
IM — bot messages, list chats	api-lark-bot	Org-level, bot identity
IM — send as user	api-lark	Needs user_access_token
Calendar — agenda, events, free/busy	api-lark	Personal calendar data
Contact — user lookup, search	api-lark-bot	User OAuth scope hard to obtain
Drive — upload, download, list files	api-lark-bot	drive scope only on bot
Doc — create, read, write documents	api-lark	docx scope available on user
Wiki — spaces, nodes	api-lark-bot	wiki scope only on bot
Task — CRUD, subtasks, tasklists	api-lark-bot	task scope only on bot
Sheets — read, write, append	api-lark-bot	sheets scope on bot
Base (Bitable) — tables, records	api-lark-bot	bitable scope on bot
Mail — send, reply, drafts	api-lark	Personal mailbox
Approval — instances, tasks	api-lark-bot	Org-level
VC / Minutes — meetings, transcripts	api-lark-bot	Org-level

See references/identity.md for complete scope mapping.

3. First-Time Setup

Bot setup (token exchange — NyxID handles transparently)

nyxid service add api-lark-bot
# Prompted for JSON credential:
#   app_id: your Lark app ID (e.g., cli_a940e30bf3b89eea)
#   app_secret: your Lark app secret
# Get these from: https://open.larksuite.com/app → your app → Credentials

User OAuth setup (opens browser for consent)

nyxid service add api-lark --oauth --scope "\
contact:user.base:readonly,\
calendar:calendar.event:read,calendar:calendar.event:create,\
calendar:calendar.event:update,calendar:calendar.free_busy:read,\
calendar:calendar:read,\
docx:document,docx:document:readonly,docx:document:create,\
im:chat:read,im:message,im:message.send_as_user,\
im:message:readonly,im:message.group_msg:get_as_user,\
sheets:spreadsheet:readonly,\
approval:task:read,approval:instance:read,\
drive:drive:readonly,wiki:wiki:readonly,\
task:task:read,task:task:write,\
mail:mailbox:readonly,bitable:bitable:readonly"

Verify both services work

# Bot: should return a JSON object with data.items[] containing chat_id, name, etc.
nyxid proxy request api-lark-bot /open-apis/im/v1/chats

# User: should return a JSON object with data.calendar_list[] containing calendar_id, summary, etc.
nyxid proxy request api-lark /calendar/v4/calendars

If either returns a scope error, see Section 6 (Scope Troubleshooting).

4. Quick Recipes (end-to-end)

These are the most common multi-step tasks. Follow in order.

Recipe A: Send a DM to someone by name

# Step 1: Find their open_id (list all org users from root department)
nyxid proxy request api-lark-bot "/open-apis/contact/v3/users?user_id_type=open_id&department_id=0&page_size=50"
# → scan data.items[] for the target name, extract open_id (ou_xxx)

# Step 2: Send DM using open_id
nyxid proxy request api-lark-bot "/open-apis/im/v1/messages?receive_id_type=open_id" \
  -m POST -d '{"receive_id":"ou_xxx","msg_type":"text","content":"{\"text\":\"hello\"}"}'

Do NOT use /contact/v3/users/me for "send to myself" — it fails on scope. Use the department list above and match by name.

Recipe B: Check my schedule today

# Step 1: Get primary calendar ID
nyxid proxy request api-lark /calendar/v4/calendars
# → find the primary calendar in data.calendar_list[], extract calendar_id

# Step 2: List today's events (replace timestamps — Unix seconds)
# Example: 2026-04-13 00:00 SGT = 1776182400, 23:59 = 1776268799
nyxid proxy request api-lark "/calendar/v4/calendars/CALENDAR_ID/events?start_time=1776182400&end_time=1776268799"

Recipe C: Send a message to a group chat

# Step 1: Find the chat_id
nyxid proxy request api-lark-bot /open-apis/im/v1/chats
# → scan data.items[] for the target group name, extract chat_id (oc_xxx)

# Step 2: Send message
nyxid proxy request api-lark-bot "/open-apis/im/v1/messages?receive_id_type=chat_id" \
  -m POST -d '{"receive_id":"oc_xxx","msg_type":"text","content":"{\"text\":\"hello\"}"}'

Recipe D: Send a rich-text (post) message

The content field is double-encoded JSON — a JSON string containing JSON.

nyxid proxy request api-lark-bot "/open-apis/im/v1/messages?receive_id_type=open_id" \
  -m POST -d '{"receive_id":"ou_xxx","msg_type":"post","content":"{\"zh_cn\":{\"title\":\"Title\",\"content\":[[{\"tag\":\"text\",\"text\":\"Body text\"}]]}}"}'

Critical pitfall: content double-encoding

The content field in message send is always a JSON string, not a JSON object:

• Wrong: "content": {"text": "hello"}
• Right: "content": "{\"text\":\"hello\"}"

This applies to all msg_types (text, post, image, file, interactive card).

---

5. lark-cli Migration Cheat Sheet

Top 10 most common operations, showing lark-cli vs NyxID equivalent.

4a. Send a message (bot)

# lark-cli
lark-cli im +messages-send --as bot --chat-id oc_xxx --msg-type text --data '{"text":"hello"}'

# nyx
nyxid proxy request api-lark-bot "/open-apis/im/v1/messages?receive_id_type=chat_id" \
  -m POST -d '{"receive_id":"oc_xxx","msg_type":"text","content":"{\"text\":\"hello\"}"}'

4b. List chats (bot)

# lark-cli
lark-cli im +chat-search --as bot

# nyx
nyxid proxy request api-lark-bot /open-apis/im/v1/chats

4c. View today's agenda (user)

# lark-cli
lark-cli calendar +agenda --as user

# nyx (replace CALENDAR_ID and timestamps)
nyxid proxy request api-lark "/calendar/v4/calendars/CALENDAR_ID/events?\
start_time=START_UNIX&end_time=END_UNIX"

4d. Create a calendar event (user)

nyxid proxy request api-lark "/calendar/v4/calendars/CALENDAR_ID/events" \
  -m POST -d '{"summary":"Meeting","start_time":{"timestamp":"1718280000"},"end_time":{"timestamp":"1718283600"}}'

4e. Get user info (bot)

# lark-cli
lark-cli contact +get-user --as bot --user-id ou_xxx

# nyx
nyxid proxy request api-lark-bot /open-apis/contact/v3/users/ou_xxx

4f. List files in drive (bot)

nyxid proxy request api-lark-bot /open-apis/drive/v1/files

4g. Create a document (user)

nyxid proxy request api-lark /docx/v1/documents \
  -m POST -d '{"title":"New Doc","folder_token":"fldcniHf40Vcv1"}'

4h. Create a task (bot)

nyxid proxy request api-lark-bot /open-apis/task/v2/tasks \
  -m POST -d '{"summary":"My task"}'

4i. Search messages (user)

nyxid proxy request api-lark "/im/v1/messages/search?query=keyword" \
  -m POST -d '{"query":"search term"}'

4j. Query free/busy (user)

nyxid proxy request api-lark "/calendar/v4/freebusy/list" \
  -m POST -d '{"time_min":"1718280000","time_max":"1718366400","user_id":{"user_id":"ou_xxx","id_type":"open_id"}}'

6. Scope Troubleshooting

Bot scope missing

# Lark error includes helps[].url — open it to add the scope
open "https://open.larksuite.com/app/cli_a940e30bf3b89eea/auth?q=im:chat:readonly&op_from=openapi"
# Bot scopes take effect immediately after adding

User scope missing

# 1. Delete all old OAuth credentials (they share a refresh token)
nyxid external-key list               # find Lark OAuth entries
nyxid external-key delete <id>        # delete each one

# 2. Re-add with correct scopes
nyxid service add api-lark --oauth --scope "new,scopes,here"

Key gotchas

• Bot scope names differ from user scope names (e.g., contact:contact.base:readonly vs contact:user.base:readonly). Always check the Lark API docs for the correct scope variant.
• "Non-review permissions" (免审权限) still need explicit addition in the app console before they take effect. Not having them in the console means the scope string alone is insufficient.
• Max 32 scopes per OAuth request. If you need more, split across multiple service registrations with different slugs.
• After adding bot scopes, they take effect immediately. After adding user scopes, you must delete old OAuth tokens and re-authorize (the old refresh token remembers the original scope set).
• A 404 on a seemingly valid path usually means the path prefix is wrong. Double-check Section 1 for the correct prefix convention per service.

7. Pagination

Most Lark list endpoints return paginated results. The pattern is consistent across all APIs:

# First page
nyxid proxy request api-lark-bot /open-apis/im/v1/chats

# Response includes: "page_token": "xxx", "has_more": true
# Next page
nyxid proxy request api-lark-bot "/open-apis/im/v1/chats?page_token=xxx&page_size=50"

Default page size is 20. Maximum is typically 50 or 100 depending on the endpoint. Check the specific API reference for limits.

8. Reference Docs

File	Description
references/identity.md	Complete bot vs user routing + scope mapping
references/im.md	Messages, chats, threads, reactions
references/calendar.md	Events, free/busy, RSVP, suggestions
references/contact.md	User lookup, org structure
references/drive.md	Files, folders, comments, permissions
references/doc.md	Document CRUD, media upload
references/wiki.md	Knowledge base spaces, nodes
references/task.md	Tasks, subtasks, tasklists
references/sheets.md	Spreadsheet cells, rows, filters
references/base.md	Bitable tables, fields, records, views
references/mail.md	Email send, reply, drafts, folders
references/approval.md	Approval instances, tasks
references/vc.md	Meetings, minutes, transcripts