mirror of
https://github.com/larksuite/cli.git
synced 2026-08-03 08:32:46 +08:00
feat(im): add raw API affordance guidance for the im domain
This commit is contained in:
luozhixiong
343
affordance/im.md
Normal file
343
affordance/im.md
Normal file
@@ -0,0 +1,343 @@
|
||||
# im
|
||||
> skill: lark-im
|
||||
|
||||
## chat.members create
|
||||
Add users or bots to an existing chat by id.
|
||||
|
||||
### Avoid when
|
||||
- Creating a new chat with initial members → use [[+chat-create]] with --users/--bots
|
||||
- Only need to see who is already in the chat → use [[+chat-members-list]]
|
||||
|
||||
### Prerequisites
|
||||
- chat_id (oc_xxx) from [[+chat-search]], [[+chat-list]], or [[+chat-create]] output
|
||||
- member open_ids (ou_xxx) from contact +search-user
|
||||
|
||||
### Examples
|
||||
|
||||
**Add two users to a chat**
|
||||
```bash
|
||||
lark-cli im chat.members create --chat-id <chat_id> --data '{"id_list":["<open_id1>","<open_id2>"]}'
|
||||
```
|
||||
|
||||
## chat.members delete
|
||||
Remove users or bots from a chat.
|
||||
|
||||
### Avoid when
|
||||
- Only reviewing membership before removal → use [[+chat-members-list]] first
|
||||
|
||||
### Prerequisites
|
||||
- chat_id (oc_xxx) and the member open_ids, both visible in [[+chat-members-list]] output
|
||||
|
||||
### Examples
|
||||
|
||||
**Remove one user from a chat**
|
||||
```bash
|
||||
lark-cli im chat.members delete --chat-id <chat_id> --data '{"id_list":["<open_id>"]}'
|
||||
```
|
||||
|
||||
## chat.members get
|
||||
Page through the raw member list of a chat.
|
||||
|
||||
### Avoid when
|
||||
- Normal member listing → use [[+chat-members-list]]; it buckets users[]/bots[], paginates, and surfaces truncations[]
|
||||
|
||||
### Prerequisites
|
||||
- chat_id (oc_xxx) from [[+chat-search]] or [[+chat-list]]
|
||||
|
||||
### Examples
|
||||
|
||||
**Fetch one raw member page**
|
||||
```bash
|
||||
lark-cli im chat.members get --chat-id <chat_id>
|
||||
```
|
||||
|
||||
## chat.members bots
|
||||
Check whether the calling bot itself is in the chat.
|
||||
|
||||
### Avoid when
|
||||
- Listing which bots are members → use [[+chat-members-list]] --member-types bot
|
||||
|
||||
### Prerequisites
|
||||
- chat_id (oc_xxx); call with bot identity (--as bot)
|
||||
|
||||
### Examples
|
||||
|
||||
**Check the calling bot's membership**
|
||||
```bash
|
||||
lark-cli im chat.members bots --chat-id <chat_id> --as bot
|
||||
```
|
||||
|
||||
## messages forward
|
||||
Forward an existing message unchanged to another chat, user, or thread.
|
||||
|
||||
### Avoid when
|
||||
- Need to send new text, markdown, image, or file content → use [[+messages-send]]
|
||||
- Need to reply under an existing message → use [[+messages-reply]]
|
||||
- Need to read messages before forwarding → use [[+chat-messages-list]] or [[+messages-search]]
|
||||
|
||||
### Prerequisites
|
||||
- message_id from [[+chat-messages-list]], [[+messages-search]], or [[+messages-mget]]
|
||||
- receive_id_type must match the target id, usually chat_id for group chats
|
||||
|
||||
### Examples
|
||||
|
||||
**Forward one message to a chat**
|
||||
```bash
|
||||
lark-cli im messages forward --message-id <message_id> --receive-id-type chat_id --data '{"receive_id":"<chat_id>"}'
|
||||
```
|
||||
|
||||
## messages delete
|
||||
Recall (delete) a sent message.
|
||||
|
||||
### Avoid when
|
||||
- Fixing content → there is no edit-by-recall; send a corrected message with [[+messages-send]] or reply with [[+messages-reply]]
|
||||
|
||||
### Prerequisites
|
||||
- message_id from [[+chat-messages-list]] or [[+messages-mget]]
|
||||
- bot identity can only recall messages the bot itself sent; recall also fails after the tenant's recall window expires
|
||||
|
||||
### Examples
|
||||
|
||||
**Recall a message**
|
||||
```bash
|
||||
lark-cli im messages delete --message-id <message_id>
|
||||
```
|
||||
|
||||
## messages merge_forward
|
||||
Merge-forward multiple messages from one chat as a single combined message.
|
||||
|
||||
### Avoid when
|
||||
- Forwarding a single message → use [[messages forward]]
|
||||
- Forwarding a whole thread → use [[threads forward]]
|
||||
|
||||
### Prerequisites
|
||||
- message_ids all from the same source chat, via [[+chat-messages-list]]
|
||||
- receive_id_type matching the target id
|
||||
|
||||
### Examples
|
||||
|
||||
**Merge-forward two messages to a chat**
|
||||
```bash
|
||||
lark-cli im messages merge_forward --receive-id-type chat_id --data '{"receive_id":"<chat_id>","message_id_list":["<message_id1>","<message_id2>"]}'
|
||||
```
|
||||
|
||||
## messages read_users
|
||||
List who has read a message you sent.
|
||||
|
||||
### Avoid when
|
||||
- Checking a message's content or reactions → use [[+messages-mget]]
|
||||
|
||||
### Prerequisites
|
||||
- message_id of a message sent by the current identity; user_id_type decides the id form in the response
|
||||
|
||||
### Examples
|
||||
|
||||
**List readers of a message**
|
||||
```bash
|
||||
lark-cli im messages read_users --message-id <message_id> --user-id-type open_id
|
||||
```
|
||||
|
||||
## reactions create
|
||||
Add an emoji reaction to a message.
|
||||
|
||||
### Avoid when
|
||||
- Replying with content → use [[+messages-reply]]; reactions carry no text
|
||||
|
||||
### Prerequisites
|
||||
- message_id from [[+chat-messages-list]], [[+messages-search]], or [[+messages-mget]]
|
||||
- emoji_type is a fixed enum key (e.g. THUMBSUP, OK); it is not free-form text
|
||||
|
||||
### Examples
|
||||
|
||||
**Add a thumbs-up reaction**
|
||||
```bash
|
||||
lark-cli im reactions create --message-id <message_id> --data '{"reaction_type":{"emoji_type":"THUMBSUP"}}'
|
||||
```
|
||||
|
||||
## reactions delete
|
||||
Remove a reaction you previously added.
|
||||
|
||||
### Avoid when
|
||||
- Removing someone else's reaction → not possible; only the reaction creator can delete it
|
||||
|
||||
### Prerequisites
|
||||
- reaction_id from [[reactions list]] or the [[reactions create]] response
|
||||
|
||||
### Examples
|
||||
|
||||
**Delete a reaction**
|
||||
```bash
|
||||
lark-cli im reactions delete --message-id <message_id> --reaction-id <reaction_id>
|
||||
```
|
||||
|
||||
## reactions list
|
||||
List reactions on a single message, optionally filtered by emoji type.
|
||||
|
||||
### Avoid when
|
||||
- Fetching reactions for many messages at once → use [[reactions batch_query]]
|
||||
- Reading messages with reactions attached → [[+messages-mget]] already enriches reactions
|
||||
|
||||
### Prerequisites
|
||||
- message_id from [[+chat-messages-list]] or [[+messages-mget]]
|
||||
|
||||
### Examples
|
||||
|
||||
**List reactions on a message**
|
||||
```bash
|
||||
lark-cli im reactions list --message-id <message_id>
|
||||
```
|
||||
|
||||
## reactions batch_query
|
||||
Fetch reactions for several messages in one call.
|
||||
|
||||
### Avoid when
|
||||
- Only one message → use [[reactions list]]
|
||||
- Reading messages together with reactions → [[+messages-mget]] enriches automatically
|
||||
|
||||
### Prerequisites
|
||||
- one or more message_ids from [[+chat-messages-list]], each wrapped as a query entry
|
||||
|
||||
### Examples
|
||||
|
||||
**Query reactions for two messages**
|
||||
```bash
|
||||
lark-cli im reactions batch_query --data '{"queries":[{"message_id":"<message_id1>"},{"message_id":"<message_id2>"}]}'
|
||||
```
|
||||
|
||||
## pins create
|
||||
Pin a message in its chat.
|
||||
|
||||
### Avoid when
|
||||
- Personal bookmark rather than chat-visible pin → use [[+flag-create]]
|
||||
|
||||
### Prerequisites
|
||||
- message_id from [[+chat-messages-list]] or [[+messages-search]]
|
||||
- the calling identity must be in the chat that contains the message
|
||||
|
||||
### Examples
|
||||
|
||||
**Pin a message**
|
||||
```bash
|
||||
lark-cli im pins create --data '{"message_id":"<message_id>"}'
|
||||
```
|
||||
|
||||
## pins delete
|
||||
Unpin a previously pinned message.
|
||||
|
||||
### Avoid when
|
||||
- Removing a personal bookmark → use [[+flag-cancel]]
|
||||
|
||||
### Prerequisites
|
||||
- message_id of the pinned message, from [[pins list]]
|
||||
|
||||
### Examples
|
||||
|
||||
**Unpin a message**
|
||||
```bash
|
||||
lark-cli im pins delete --message-id <message_id>
|
||||
```
|
||||
|
||||
## pins list
|
||||
List pinned messages in a chat.
|
||||
|
||||
### Avoid when
|
||||
- Listing normal (non-pinned) history → use [[+chat-messages-list]]
|
||||
|
||||
### Prerequisites
|
||||
- chat_id (oc_xxx) from [[+chat-search]] or [[+chat-list]]
|
||||
|
||||
### Examples
|
||||
|
||||
**List pins in a chat**
|
||||
```bash
|
||||
lark-cli im pins list --chat-id <chat_id>
|
||||
```
|
||||
|
||||
## images create
|
||||
Upload a local image and get an image_key for later use.
|
||||
|
||||
### Avoid when
|
||||
- Sending an image message directly → use [[+messages-send]] --image <path>; it uploads and sends in one step
|
||||
|
||||
### Prerequisites
|
||||
- a local image file; the returned image_key is what other APIs accept
|
||||
|
||||
### Examples
|
||||
|
||||
**Upload an image for reuse**
|
||||
```bash
|
||||
lark-cli im images create --data '{"image_type":"message"}' --file ./picture.png
|
||||
```
|
||||
|
||||
## threads forward
|
||||
Forward an entire thread (topic) to another chat, user, or thread.
|
||||
|
||||
### Avoid when
|
||||
- Forwarding a single message → use [[messages forward]]
|
||||
- Reading the thread before forwarding → use [[+threads-messages-list]]
|
||||
|
||||
### Prerequisites
|
||||
- thread_id (omt_xxx) from [[+threads-messages-list]] or thread fields in [[+chat-messages-list]] output
|
||||
- receive_id_type matching the target id
|
||||
|
||||
### Examples
|
||||
|
||||
**Forward a thread to a chat**
|
||||
```bash
|
||||
lark-cli im threads forward --thread-id <thread_id> --receive-id-type chat_id --data '{"receive_id":"<chat_id>"}'
|
||||
```
|
||||
|
||||
## chats get
|
||||
Fetch raw chat metadata by id.
|
||||
|
||||
### Avoid when
|
||||
- Finding a chat or its id → use [[+chat-search]] (by keyword) or [[+chat-list]] (my chats); reach for this raw call only for fields the shortcuts don't surface
|
||||
|
||||
### Examples
|
||||
|
||||
**Fetch chat metadata**
|
||||
```bash
|
||||
lark-cli im chats get --chat-id <chat_id>
|
||||
```
|
||||
|
||||
## chats update
|
||||
Update raw chat settings.
|
||||
|
||||
### Avoid when
|
||||
- Renaming or changing the description → use [[+chat-update]]; this raw call is for settings the shortcut doesn't cover (permissions, membership approval, etc.)
|
||||
|
||||
### Examples
|
||||
|
||||
**Update chat join permission**
|
||||
```bash
|
||||
lark-cli im chats update --chat-id <chat_id> --data '{"join_message_visibility":"only_owner"}'
|
||||
```
|
||||
|
||||
## chats create
|
||||
Create a chat via the raw API.
|
||||
|
||||
### Avoid when
|
||||
- Normal chat creation → use [[+chat-create]]; it handles member invites, chat mode, and owner in one step
|
||||
|
||||
### Examples
|
||||
|
||||
**Create a bare chat**
|
||||
```bash
|
||||
lark-cli im chats create --data '{"name":"project chat"}'
|
||||
```
|
||||
|
||||
## chats link
|
||||
Generate a share link for a chat.
|
||||
|
||||
### Avoid when
|
||||
- Only need the chat id or basic info → use [[+chat-search]] or [[chats get]]
|
||||
|
||||
### Prerequisites
|
||||
- chat_id (oc_xxx); link validity is controlled by validity_period in --data
|
||||
|
||||
### Examples
|
||||
|
||||
**Get a chat share link**
|
||||
```bash
|
||||
lark-cli im chats link --chat-id <chat_id> --data '{"validity_period":"week"}'
|
||||
```
|
||||
78
internal/affordance/affordance_im_test.go
Normal file
78
internal/affordance/affordance_im_test.go
Normal file
@@ -0,0 +1,78 @@
|
||||
// Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
||||
// SPDX-License-Identifier: MIT
|
||||
|
||||
package affordance
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"os"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// The 21 im raw-API methods that affordance/im.md must cover: 17 first-batch
|
||||
// methods plus 4 "prefer the shortcut" entries. Keys follow the parsed heading
|
||||
// form (spaces become dots), same as TestFor's fixture keys.
|
||||
var imAffordanceMethods = []string{
|
||||
"chat.members.create", "chat.members.delete", "chat.members.get", "chat.members.bots",
|
||||
"messages.forward", "messages.delete", "messages.merge_forward", "messages.read_users",
|
||||
"reactions.create", "reactions.delete", "reactions.list", "reactions.batch_query",
|
||||
"pins.create", "pins.delete", "pins.list",
|
||||
"images.create",
|
||||
"threads.forward",
|
||||
"chats.get", "chats.update", "chats.create", "chats.link",
|
||||
}
|
||||
|
||||
type parsedAffordance struct {
|
||||
UseWhen []string `json:"use_when"`
|
||||
AvoidWhen []string `json:"avoid_when"`
|
||||
Prerequisites []string `json:"prerequisites"`
|
||||
Examples []struct {
|
||||
Command string `json:"command"`
|
||||
} `json:"examples"`
|
||||
}
|
||||
|
||||
// TestForIMRealFile parses the real affordance/im.md through the production
|
||||
// parser and asserts coverage plus depth on the showcase method.
|
||||
func TestForIMRealFile(t *testing.T) {
|
||||
prev := mdSource
|
||||
t.Cleanup(func() { SetSource(prev) })
|
||||
SetSource(os.DirFS("../../affordance"))
|
||||
|
||||
for _, m := range imAffordanceMethods {
|
||||
raw, ok := For("im", m)
|
||||
if !ok {
|
||||
t.Errorf("For(\"im\", %q) ok=false, want an overlay section in affordance/im.md", m)
|
||||
continue
|
||||
}
|
||||
var a parsedAffordance
|
||||
if err := json.Unmarshal(raw, &a); err != nil {
|
||||
t.Errorf("%s: overlay is not valid affordance JSON: %v", m, err)
|
||||
continue
|
||||
}
|
||||
if len(a.UseWhen) == 0 {
|
||||
t.Errorf("%s: missing lead paragraph (use_when)", m)
|
||||
}
|
||||
if len(a.AvoidWhen) == 0 {
|
||||
t.Errorf("%s: missing Avoid when section", m)
|
||||
}
|
||||
}
|
||||
|
||||
// Showcase depth: messages forward (spec §3.3, mirrors the tech-plan diff).
|
||||
raw, ok := For("im", "messages.forward")
|
||||
if !ok {
|
||||
t.Fatal("messages.forward overlay missing")
|
||||
}
|
||||
var fwd parsedAffordance
|
||||
if err := json.Unmarshal(raw, &fwd); err != nil {
|
||||
t.Fatalf("messages.forward overlay invalid: %v", err)
|
||||
}
|
||||
if len(fwd.AvoidWhen) < 3 {
|
||||
t.Errorf("messages.forward: want >=3 avoid_when entries, got %d", len(fwd.AvoidWhen))
|
||||
}
|
||||
if len(fwd.Prerequisites) < 2 {
|
||||
t.Errorf("messages.forward: want >=2 prerequisites, got %d", len(fwd.Prerequisites))
|
||||
}
|
||||
if len(fwd.Examples) < 1 || fwd.Examples[0].Command == "" {
|
||||
t.Errorf("messages.forward: want >=1 fenced example command")
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user