diff --git a/.codecov.yml b/.codecov.yml
new file mode 100644
index 00000000..2f0a040f
--- /dev/null
+++ b/.codecov.yml
@@ -0,0 +1,8 @@
+coverage:
+ status:
+ project:
+ default:
+ informational: true
+ patch:
+ default:
+ target: 60%
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 00000000..2ba1ecad
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,16 @@
+## Summary
+
+
+## Changes
+
+- Change 1
+- Change 2
+
+## Test Plan
+
+- [ ] Unit tests pass
+- [ ] Manual local verification confirms the `lark xxx` command works as expected
+
+## Related Issues
+
+- None
diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml
index 5aba7b0d..351cf3d9 100644
--- a/.github/workflows/coverage.yml
+++ b/.github/workflows/coverage.yml
@@ -2,22 +2,32 @@ name: Coverage
on:
push:
- branches: [ main ]
+ branches: [main]
+ paths:
+ - "**.go"
+ - go.mod
+ - go.sum
+ - .github/workflows/coverage.yml
pull_request:
- branches: [ main ]
+ branches: [main]
+ paths:
+ - "**.go"
+ - go.mod
+ - go.sum
+ - .github/workflows/coverage.yml
permissions:
contents: read
jobs:
- codecov:
- runs-on: ubuntu-22.04
+ coverage:
+ runs-on: ubuntu-latest
steps:
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
- uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
with:
- go-version: '1.23'
+ go-version-file: go.mod
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
with:
@@ -27,10 +37,18 @@ jobs:
run: python3 scripts/fetch_meta.py
- name: Run tests with coverage
- run: go test -coverprofile=coverage.txt -covermode=atomic ./...
-
- - name: Upload coverage to Codecov
- uses: codecov/codecov-action@75cd11691c0faa626561e295848008c8a7dddffe # v5
- with:
- files: coverage.txt
- token: ${{ secrets.CODECOV_TOKEN }}
+ run: go test -race -coverprofile=coverage.txt -covermode=atomic ./...
+
+ - name: Generate coverage report
+ run: |
+ total=$(go tool cover -func=coverage.txt | grep total | awk '{print $3}')
+ echo "## Coverage Report" >> $GITHUB_STEP_SUMMARY
+ echo "" >> $GITHUB_STEP_SUMMARY
+ echo "**Total coverage: ${total}**" >> $GITHUB_STEP_SUMMARY
+ echo "" >> $GITHUB_STEP_SUMMARY
+ echo "Details
" >> $GITHUB_STEP_SUMMARY
+ echo "" >> $GITHUB_STEP_SUMMARY
+ echo '```' >> $GITHUB_STEP_SUMMARY
+ go tool cover -func=coverage.txt >> $GITHUB_STEP_SUMMARY
+ echo '```' >> $GITHUB_STEP_SUMMARY
+ echo "
`) {
+ t.Fatalf("resolveMarkdownAsPost() = %q, want no literal
", got)
+ }
}
func TestValidateContentFlags(t *testing.T) {
diff --git a/shortcuts/im/helpers.go b/shortcuts/im/helpers.go
index 15d12773..32a0a33f 100644
--- a/shortcuts/im/helpers.go
+++ b/shortcuts/im/helpers.go
@@ -619,31 +619,22 @@ func readMp4Duration(f *os.File, fileSize int64) int64 {
// Steps:
// 1. Extract code blocks with placeholders to protect them
// 2. Downgrade headings: H1 → H4, H2~H6 → H5 (only when H1~H3 present)
-// 3. Add
between consecutive headings
-// 4. Add spacing around tables with
-// 5. Restore code blocks with
wrappers
-// 6. Compress excess blank lines
-// 7. Strip invalid image references (keep only img_xxx keys)
+// 3. Normalize spacing between consecutive headings and tables with blank lines
+// 4. Restore code blocks
+// 5. Compress excess blank lines
+// 6. Strip invalid image references (keep only img_xxx keys)
var (
- reH2toH6 = regexp.MustCompile(`(?m)^#{2,6} (.+)$`)
- reH1 = regexp.MustCompile(`(?m)^# (.+)$`)
- reHasH1toH3 = regexp.MustCompile(`(?m)^#{1,3} `)
- reConsecH = regexp.MustCompile(`(?m)^(#{4,5} .+)\n{1,2}(#{4,5} )`)
- reTableNoGap = regexp.MustCompile(`(?m)^([^|\n].*)\n(\|.+\|)`)
- reTableBefore = regexp.MustCompile(`\n\n((?:\|.+\|[^\S\n]*\n?)+)`)
- reTableAfter = regexp.MustCompile(`(?m)((?:^\|.+\|[^\S\n]*\n?)+)`)
- reTableTxtPre = regexp.MustCompile(`(?m)^([^\n]+)\n\n(
)\n\n(\|)`)
- reTableBoldPre = regexp.MustCompile(`(?m)^(\*\*.+)\n\n(
)\n\n(\|)`)
- reTableTxtPost = regexp.MustCompile(`(?m)(\|[^\n]*\n)\n(
\n)([^\n]+)`)
- reExcessNL = regexp.MustCompile(`\n{3,}`)
- reInvalidImg = regexp.MustCompile(`!\[[^\]]*\]\(([^)\s]+)\)`)
- reCodeBlock = regexp.MustCompile("```[\\s\\S]*?```")
+ reH2toH6 = regexp.MustCompile(`(?m)^#{2,6} (.+)$`)
+ reH1 = regexp.MustCompile(`(?m)^# (.+)$`)
+ reHasH1toH3 = regexp.MustCompile(`(?m)^#{1,3} `)
+ reConsecH = regexp.MustCompile(`(?m)^(#{4,5} .+)\n{1,2}(#{4,5} )`)
+ reTableNoGap = regexp.MustCompile(`(?m)^([^|\n].*)\n(\|.+\|)`)
+ reTableAfter = regexp.MustCompile(`(?m)((?:^\|.+\|[^\S\n]*\n?)+)`)
+ reExcessNL = regexp.MustCompile(`\n{3,}`)
+ reInvalidImg = regexp.MustCompile(`!\[[^\]]*\]\(([^)\s]+)\)`)
+ reCodeBlock = regexp.MustCompile("```[\\s\\S]*?```")
)
-func isTableSpacingProtectedLine(line string) bool {
- return strings.HasPrefix(line, "#### ") || strings.HasPrefix(line, "##### ") || strings.HasPrefix(line, "**")
-}
-
func optimizeMarkdownStyle(text string) string {
const mark = "___CB_"
var codeBlocks []string
@@ -659,29 +650,13 @@ func optimizeMarkdownStyle(text string) string {
r = reH1.ReplaceAllString(r, "#### $1")
}
- r = reConsecH.ReplaceAllString(r, "$1\n
\n$2")
+ r = reConsecH.ReplaceAllString(r, "$1\n\n$2")
r = reTableNoGap.ReplaceAllString(r, "$1\n\n$2")
- r = reTableBefore.ReplaceAllString(r, "\n\n
\n\n$1")
- r = reTableAfter.ReplaceAllString(r, "$1\n
\n")
- r = reTableTxtPre.ReplaceAllStringFunc(r, func(m string) string {
- sub := reTableTxtPre.FindStringSubmatch(m)
- if len(sub) != 4 || isTableSpacingProtectedLine(sub[1]) {
- return m
- }
- return sub[1] + "\n" + sub[2] + "\n" + sub[3]
- })
- r = reTableBoldPre.ReplaceAllString(r, "$1\n$2\n\n$3")
- r = reTableTxtPost.ReplaceAllStringFunc(r, func(m string) string {
- sub := reTableTxtPost.FindStringSubmatch(m)
- if len(sub) != 4 || isTableSpacingProtectedLine(sub[3]) {
- return m
- }
- return sub[1] + sub[2] + sub[3]
- })
+ r = reTableAfter.ReplaceAllString(r, "$1\n")
for i, block := range codeBlocks {
- r = strings.Replace(r, fmt.Sprintf("%s%d___", mark, i), "\n
\n"+block+"\n
\n", 1)
+ r = strings.Replace(r, fmt.Sprintf("%s%d___", mark, i), block, 1)
}
r = reExcessNL.ReplaceAllString(r, "\n\n")
@@ -901,7 +876,7 @@ func uploadImageToIM(ctx context.Context, runtime *common.RuntimeContext, filePa
fd.AddField("image_type", imageType)
fd.AddFile("image", f)
- apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
+ apiResp, err := runtime.DoAPIAsBot(&larkcore.ApiReq{
HttpMethod: http.MethodPost,
ApiPath: "/open-apis/im/v1/images",
Body: fd,
@@ -947,7 +922,7 @@ func uploadFileToIM(ctx context.Context, runtime *common.RuntimeContext, filePat
}
fd.AddFile("file", f)
- apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
+ apiResp, err := runtime.DoAPIAsBot(&larkcore.ApiReq{
HttpMethod: http.MethodPost,
ApiPath: "/open-apis/im/v1/files",
Body: fd,
diff --git a/shortcuts/im/helpers_network_test.go b/shortcuts/im/helpers_network_test.go
index 3321b683..b09b45e0 100644
--- a/shortcuts/im/helpers_network_test.go
+++ b/shortcuts/im/helpers_network_test.go
@@ -263,7 +263,7 @@ func TestDownloadIMResourceToPathSuccess(t *testing.T) {
}))
target := filepath.Join(t.TempDir(), "nested", "resource.bin")
- size, err := downloadIMResourceToPath(context.Background(), runtime, "om_123", "file_123", "file", target)
+ _, size, err := downloadIMResourceToPath(context.Background(), runtime, "om_123", "file_123", "file", target)
if err != nil {
t.Fatalf("downloadIMResourceToPath() error = %v", err)
}
@@ -307,7 +307,7 @@ func TestDownloadIMResourceToPathHTTPErrorBody(t *testing.T) {
}
}))
- _, err := downloadIMResourceToPath(context.Background(), runtime, "om_403", "file_403", "file", filepath.Join(t.TempDir(), "out.bin"))
+ _, _, err := downloadIMResourceToPath(context.Background(), runtime, "om_403", "file_403", "file", filepath.Join(t.TempDir(), "out.bin"))
if err == nil || !strings.Contains(err.Error(), "HTTP 403: denied") {
t.Fatalf("downloadIMResourceToPath() error = %v", err)
}
diff --git a/shortcuts/im/helpers_test.go b/shortcuts/im/helpers_test.go
index e5cbf7e0..bf9bf870 100644
--- a/shortcuts/im/helpers_test.go
+++ b/shortcuts/im/helpers_test.go
@@ -282,7 +282,7 @@ func TestOptimizeMarkdownStyle(t *testing.T) {
{
name: "heading downgrade H1 and H2",
input: "# Title\n## Section\ntext",
- want: "#### Title\n
\n##### Section\ntext",
+ want: "#### Title\n\n##### Section\ntext",
},
{
name: "no downgrade when no H1-H3",
@@ -292,17 +292,17 @@ func TestOptimizeMarkdownStyle(t *testing.T) {
{
name: "code block protected",
input: "# Title\n```\n# not a heading\n```\ntext",
- want: "#### Title\n\n
\n```\n# not a heading\n```\n
\n\ntext",
+ want: "#### Title\n```\n# not a heading\n```\ntext",
},
{
name: "table spacing",
input: "text\n| A | B |\n| - | - |\n| 1 | 2 |\nafter",
- want: "text\n
\n| A | B |\n| - | - |\n| 1 | 2 |\n
\nafter",
+ want: "text\n\n| A | B |\n| - | - |\n| 1 | 2 |\n\nafter",
},
{
name: "table spacing keeps heading separation",
input: "# Title\n| A | B |\n| - | - |\n| 1 | 2 |\n## Next",
- want: "#### Title\n\n
\n\n| A | B |\n| - | - |\n| 1 | 2 |\n\n
\n##### Next",
+ want: "#### Title\n\n| A | B |\n| - | - |\n| 1 | 2 |\n\n##### Next",
},
{
name: "excess blank lines compressed",
@@ -483,7 +483,7 @@ func TestDownloadIMResourceToPathHTTPClientError(t *testing.T) {
},
}
- _, err := downloadIMResourceToPath(context.Background(), runtime, "om_123", "img_123", "image", "out.bin")
+ _, _, err := downloadIMResourceToPath(context.Background(), runtime, "om_123", "img_123", "image", "out.bin")
if err == nil || !strings.Contains(err.Error(), "http client unavailable") {
t.Fatalf("downloadIMResourceToPath() error = %v", err)
}
diff --git a/shortcuts/im/im_messages_reply.go b/shortcuts/im/im_messages_reply.go
index d7aab26b..30087d58 100644
--- a/shortcuts/im/im_messages_reply.go
+++ b/shortcuts/im/im_messages_reply.go
@@ -17,10 +17,12 @@ import (
var ImMessagesReply = common.Shortcut{
Service: "im",
Command: "+messages-reply",
- Description: "Reply to a message (supports thread replies) with bot identity; bot-only; supports text/markdown/post/media replies, reply-in-thread, idempotency key",
+ Description: "Reply to a message (supports thread replies); user/bot; supports text/markdown/post/media replies, reply-in-thread, idempotency key",
Risk: "write",
Scopes: []string{"im:message:send_as_bot"},
- AuthTypes: []string{"bot"},
+ UserScopes: []string{"im:message.send_as_user"},
+ BotScopes: []string{"im:message:send_as_bot"},
+ AuthTypes: []string{"bot", "user"},
Flags: []common.Flag{
{Name: "message-id", Desc: "message ID (om_xxx)", Required: true},
{Name: "msg-type", Default: "text", Desc: "message type for --content JSON; when using --text/--markdown/--image/--file/--video/--audio, the effective type is inferred automatically", Enum: []string{"text", "post", "image", "file", "audio", "media", "interactive", "share_chat", "share_user"}},
diff --git a/shortcuts/im/im_messages_resources_download.go b/shortcuts/im/im_messages_resources_download.go
index 259c1391..beeaacd8 100644
--- a/shortcuts/im/im_messages_resources_download.go
+++ b/shortcuts/im/im_messages_resources_download.go
@@ -72,12 +72,12 @@ var ImMessagesResourcesDownload = common.Shortcut{
return output.ErrValidation("unsafe output path: %s", err)
}
- sizeBytes, err := downloadIMResourceToPath(ctx, runtime, messageId, fileKey, fileType, safePath)
+ finalPath, sizeBytes, err := downloadIMResourceToPath(ctx, runtime, messageId, fileKey, fileType, safePath)
if err != nil {
return err
}
- runtime.Out(map[string]interface{}{"saved_path": safePath, "size_bytes": sizeBytes}, nil)
+ runtime.Out(map[string]interface{}{"saved_path": finalPath, "size_bytes": sizeBytes}, nil)
return nil
},
}
@@ -108,7 +108,38 @@ func normalizeDownloadOutputPath(fileKey, outputPath string) (string, error) {
const defaultIMResourceDownloadTimeout = 120 * time.Second
-func downloadIMResourceToPath(ctx context.Context, runtime *common.RuntimeContext, messageID, fileKey, fileType, safePath string) (int64, error) {
+var imMimeToExt = map[string]string{
+ "image/png": ".png",
+ "image/jpeg": ".jpg",
+ "image/gif": ".gif",
+ "image/webp": ".webp",
+ "image/svg+xml": ".svg",
+ "application/pdf": ".pdf",
+ "video/mp4": ".mp4",
+ "video/3gpp": ".3gp",
+ "video/x-msvideo": ".avi",
+ "audio/mpeg": ".mp3",
+ "audio/ogg": ".ogg",
+ "audio/wav": ".wav",
+ "text/plain": ".txt",
+ "text/html": ".html",
+ "text/css": ".css",
+ "text/csv": ".csv",
+ "application/zip": ".zip",
+ "application/x-zip-compressed": ".zip",
+ "application/x-rar-compressed": ".rar",
+ "application/json": ".json",
+ "application/xml": ".xml",
+ "application/octet-stream": ".bin",
+ "application/msword": ".doc",
+ "application/vnd.openxmlformats-officedocument.wordprocessingml.document": ".docx",
+ "application/vnd.ms-excel": ".xls",
+ "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": ".xlsx",
+ "application/vnd.ms-powerpoint": ".ppt",
+ "application/vnd.openxmlformats-officedocument.presentationml.presentation": ".pptx",
+}
+
+func downloadIMResourceToPath(ctx context.Context, runtime *common.RuntimeContext, messageID, fileKey, fileType, safePath string) (string, int64, error) {
query := larkcore.QueryParams{}
query.Set("type", fileType)
downloadResp, err := runtime.DoAPIStream(ctx, &larkcore.ApiReq{
@@ -121,24 +152,36 @@ func downloadIMResourceToPath(ctx context.Context, runtime *common.RuntimeContex
QueryParams: query,
}, defaultIMResourceDownloadTimeout)
if err != nil {
- return 0, err
+ return "", 0, err
}
defer downloadResp.Body.Close()
if downloadResp.StatusCode >= 400 {
body, _ := io.ReadAll(io.LimitReader(downloadResp.Body, 4096))
if len(body) > 0 {
- return 0, output.ErrNetwork("download failed: HTTP %d: %s", downloadResp.StatusCode, strings.TrimSpace(string(body)))
+ return "", 0, output.ErrNetwork("download failed: HTTP %d: %s", downloadResp.StatusCode, strings.TrimSpace(string(body)))
}
- return 0, output.ErrNetwork("download failed: HTTP %d", downloadResp.StatusCode)
+ return "", 0, output.ErrNetwork("download failed: HTTP %d", downloadResp.StatusCode)
}
if err := os.MkdirAll(filepath.Dir(safePath), 0700); err != nil {
- return 0, output.Errorf(output.ExitInternal, "api_error", "cannot create parent directory: %s", err)
+ return "", 0, output.Errorf(output.ExitInternal, "api_error", "cannot create parent directory: %s", err)
+ }
+
+ // Auto-detect extension from Content-Type if missing
+ finalPath := safePath
+ if filepath.Ext(safePath) == "" {
+ contentType := downloadResp.Header.Get("Content-Type")
+ mimeType := strings.Split(contentType, ";")[0]
+ mimeType = strings.TrimSpace(mimeType)
+ if ext, ok := imMimeToExt[mimeType]; ok {
+ finalPath = safePath + ext
+ }
}
- sizeBytes, err := validate.AtomicWriteFromReader(safePath, downloadResp.Body, 0600)
+
+ sizeBytes, err := validate.AtomicWriteFromReader(finalPath, downloadResp.Body, 0600)
if err != nil {
- return 0, output.Errorf(output.ExitInternal, "api_error", "cannot create file: %s", err)
+ return "", 0, output.Errorf(output.ExitInternal, "api_error", "cannot create file: %s", err)
}
- return sizeBytes, nil
+ return finalPath, sizeBytes, nil
}
diff --git a/shortcuts/im/im_messages_search.go b/shortcuts/im/im_messages_search.go
index 3b0f7dfc..d122cc23 100644
--- a/shortcuts/im/im_messages_search.go
+++ b/shortcuts/im/im_messages_search.go
@@ -9,6 +9,7 @@ import (
"io"
"net/http"
"strconv"
+ "strings"
"github.com/larksuite/cli/internal/output"
"github.com/larksuite/cli/shortcuts/common"
@@ -16,6 +17,15 @@ import (
larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
)
+const (
+ messagesSearchDefaultPageSize = 20
+ messagesSearchMaxPageSize = 50
+ messagesSearchDefaultPageLimit = 20
+ messagesSearchMaxPageLimit = 40
+ messagesSearchMGetBatchSize = 50
+ messagesSearchChatBatchSize = 50
+)
+
var ImMessagesSearch = common.Shortcut{
Service: "im",
Command: "+messages-search",
@@ -37,6 +47,8 @@ var ImMessagesSearch = common.Shortcut{
{Name: "end", Desc: "end time(ISO 8601) with local timezone offset (e.g. 2026-03-25T23:59:59+08:00)"},
{Name: "page-size", Default: "20", Desc: "page size (1-50)"},
{Name: "page-token", Desc: "page token"},
+ {Name: "page-all", Type: "bool", Desc: "automatically paginate search results"},
+ {Name: "page-limit", Type: "int", Default: "20", Desc: "max search pages when auto-pagination is enabled (default 20, max 40)"},
},
DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
req, err := buildMessagesSearchRequest(runtime)
@@ -49,8 +61,14 @@ var ImMessagesSearch = common.Shortcut{
dryParams[k] = vs[0]
}
}
- return common.NewDryRunAPI().
- Desc("Step 1: search messages").
+ autoPaginate, pageLimit := messagesSearchPaginationConfig(runtime)
+ d := common.NewDryRunAPI()
+ if autoPaginate {
+ d = d.Desc(fmt.Sprintf("Step 1: search messages (auto-paginates up to %d page(s))", pageLimit))
+ } else {
+ d = d.Desc("Step 1: search messages")
+ }
+ return d.
POST("/open-apis/im/v1/messages/search").
Params(dryParams).
Body(req.body).
@@ -67,12 +85,10 @@ var ImMessagesSearch = common.Shortcut{
return err
}
- searchData, err := runtime.DoAPIJSON(http.MethodPost, "/open-apis/im/v1/messages/search", req.params, req.body)
+ rawItems, hasMore, nextPageToken, truncatedByLimit, pageLimit, err := searchMessages(runtime, req)
if err != nil {
return err
}
- rawItems, _ := searchData["items"].([]interface{})
- hasMore, nextPageToken := common.PaginationMeta(searchData)
if len(rawItems) == 0 {
outData := map[string]interface{}{
@@ -99,8 +115,7 @@ var ImMessagesSearch = common.Shortcut{
}
// ── Step 2: Batch fetch message details (mget) ──
- mgetURL := buildMGetURL(messageIds)
- mgetData, err := runtime.DoAPIJSON(http.MethodGet, mgetURL, nil, nil)
+ msgItems, err := batchMGetMessages(runtime, messageIds)
if err != nil {
// Fallback when mget fails: return ID list only
outData := map[string]interface{}{
@@ -118,37 +133,22 @@ var ImMessagesSearch = common.Shortcut{
})
return nil
}
- msgItems, _ := mgetData["items"].([]interface{})
// ── Step 3: Batch fetch chat info ──
- chatIdSet := map[string]bool{}
+ chatIds := make([]string, 0, len(msgItems))
+ chatSeen := make(map[string]bool)
for _, item := range msgItems {
m, _ := item.(map[string]interface{})
if chatId, _ := m["chat_id"].(string); chatId != "" {
- chatIdSet[chatId] = true
+ if !chatSeen[chatId] {
+ chatSeen[chatId] = true
+ chatIds = append(chatIds, chatId)
+ }
}
}
chatContexts := map[string]map[string]interface{}{}
- if len(chatIdSet) > 0 {
- chatIds := make([]string, 0, len(chatIdSet))
- for id := range chatIdSet {
- chatIds = append(chatIds, id)
- }
- chatRes, chatErr := runtime.DoAPIJSON(
- http.MethodPost, "/open-apis/im/v1/chats/batch_query",
- larkcore.QueryParams{"user_id_type": []string{"open_id"}},
- map[string]interface{}{"chat_ids": chatIds},
- )
- if chatErr == nil {
- if chatItems, ok := chatRes["items"].([]interface{}); ok {
- for _, ci := range chatItems {
- cm, _ := ci.(map[string]interface{})
- if cid, _ := cm["chat_id"].(string); cid != "" {
- chatContexts[cid] = cm
- }
- }
- }
- }
+ if len(chatIds) > 0 {
+ chatContexts = batchQueryChatContexts(runtime, chatIds)
}
// ── Step 4: Format message content + attach chat context ──
@@ -225,6 +225,9 @@ var ImMessagesSearch = common.Shortcut{
moreHint = " (more available, use --page-token to fetch next page)"
}
fmt.Fprintf(w, "\n%d search result(s)%s\n", len(enriched), moreHint)
+ if truncatedByLimit {
+ fmt.Fprintf(w, "warning: stopped after fetching %d page(s); use --page-limit, --page-all, or --page-token to continue\n", pageLimit)
+ }
})
return nil
},
@@ -247,6 +250,14 @@ func buildMessagesSearchRequest(runtime *common.RuntimeContext) (*messagesSearch
endFlag := runtime.Str("end")
pageSizeStr := runtime.Str("page-size")
pageToken := runtime.Str("page-token")
+ pageLimitStr := strings.TrimSpace(runtime.Str("page-limit"))
+
+ if runtime.Cmd != nil && runtime.Cmd.Flags().Changed("page-limit") {
+ pageLimit, err := strconv.Atoi(pageLimitStr)
+ if err != nil || pageLimit < 1 || pageLimit > messagesSearchMaxPageLimit {
+ return nil, output.ErrValidation("--page-limit must be an integer between 1 and 40")
+ }
+ }
filter := map[string]interface{}{}
timeRange := map[string]interface{}{}
@@ -322,14 +333,14 @@ func buildMessagesSearchRequest(runtime *common.RuntimeContext) (*messagesSearch
body["filter"] = filter
}
- pageSize := 20
+ pageSize := messagesSearchDefaultPageSize
if pageSizeStr != "" {
n, err := strconv.Atoi(pageSizeStr)
if err != nil || n < 1 {
return nil, output.ErrValidation("--page-size must be an integer between 1 and 50")
}
- if n > 50 {
- n = 50
+ if n > messagesSearchMaxPageSize {
+ n = messagesSearchMaxPageSize
}
pageSize = n
}
@@ -346,3 +357,124 @@ func buildMessagesSearchRequest(runtime *common.RuntimeContext) (*messagesSearch
body: body,
}, nil
}
+
+func messagesSearchPaginationConfig(runtime *common.RuntimeContext) (autoPaginate bool, pageLimit int) {
+ autoPaginate = runtime.Bool("page-all")
+ if runtime.Cmd != nil && runtime.Cmd.Flags().Changed("page-limit") {
+ autoPaginate = true
+ }
+
+ pageLimit = messagesSearchDefaultPageLimit
+ if runtime.Cmd != nil && runtime.Cmd.Flags().Changed("page-limit") {
+ if n, err := strconv.Atoi(strings.TrimSpace(runtime.Str("page-limit"))); err == nil && n > 0 {
+ pageLimit = min(n, messagesSearchMaxPageLimit)
+ }
+ } else if runtime.Bool("page-all") {
+ pageLimit = messagesSearchMaxPageLimit
+ }
+ return autoPaginate, pageLimit
+}
+
+func searchMessages(runtime *common.RuntimeContext, req *messagesSearchRequest) ([]interface{}, bool, string, bool, int, error) {
+ autoPaginate, pageLimit := messagesSearchPaginationConfig(runtime)
+ pageToken := ""
+ if tokens := req.params["page_token"]; len(tokens) > 0 {
+ pageToken = tokens[0]
+ }
+
+ pageSize := strconv.Itoa(messagesSearchDefaultPageSize)
+ if sizes := req.params["page_size"]; len(sizes) > 0 {
+ pageSize = sizes[0]
+ }
+
+ var (
+ allItems []interface{}
+ lastHasMore bool
+ lastPageToken string
+ truncatedByLimit bool
+ pageCount int
+ )
+
+ for {
+ pageCount++
+ params := larkcore.QueryParams{
+ "page_size": []string{pageSize},
+ }
+ if pageToken != "" {
+ params["page_token"] = []string{pageToken}
+ }
+
+ searchData, err := runtime.DoAPIJSON(http.MethodPost, "/open-apis/im/v1/messages/search", params, req.body)
+ if err != nil {
+ return nil, false, "", false, pageLimit, err
+ }
+
+ items, _ := searchData["items"].([]interface{})
+ allItems = append(allItems, items...)
+ lastHasMore, lastPageToken = common.PaginationMeta(searchData)
+
+ if !autoPaginate || !lastHasMore || lastPageToken == "" {
+ break
+ }
+ if pageCount >= pageLimit {
+ truncatedByLimit = true
+ break
+ }
+
+ pageToken = lastPageToken
+ }
+
+ return allItems, lastHasMore, lastPageToken, truncatedByLimit, pageLimit, nil
+}
+
+func batchMGetMessages(runtime *common.RuntimeContext, messageIds []string) ([]interface{}, error) {
+ var items []interface{}
+ for _, batch := range chunkStrings(messageIds, messagesSearchMGetBatchSize) {
+ mgetData, err := runtime.DoAPIJSON(http.MethodGet, buildMGetURL(batch), nil, nil)
+ if err != nil {
+ return nil, err
+ }
+ batchItems, _ := mgetData["items"].([]interface{})
+ items = append(items, batchItems...)
+ }
+ return items, nil
+}
+
+func batchQueryChatContexts(runtime *common.RuntimeContext, chatIds []string) map[string]map[string]interface{} {
+ chatContexts := map[string]map[string]interface{}{}
+ for _, batch := range chunkStrings(chatIds, messagesSearchChatBatchSize) {
+ chatRes, chatErr := runtime.DoAPIJSON(
+ http.MethodPost, "/open-apis/im/v1/chats/batch_query",
+ larkcore.QueryParams{"user_id_type": []string{"open_id"}},
+ map[string]interface{}{"chat_ids": batch},
+ )
+ if chatErr != nil {
+ continue
+ }
+ if chatItems, ok := chatRes["items"].([]interface{}); ok {
+ for _, ci := range chatItems {
+ cm, _ := ci.(map[string]interface{})
+ if cid, _ := cm["chat_id"].(string); cid != "" {
+ chatContexts[cid] = cm
+ }
+ }
+ }
+ }
+ return chatContexts
+}
+
+func chunkStrings(items []string, chunkSize int) [][]string {
+ if len(items) == 0 || chunkSize <= 0 {
+ return nil
+ }
+
+ chunks := make([][]string, 0, (len(items)+chunkSize-1)/chunkSize)
+ for start := 0; start < len(items); start += chunkSize {
+ end := start + chunkSize
+ if end > len(items) {
+ end = len(items)
+ }
+ chunks = append(chunks, items[start:end])
+ }
+ return chunks
+}
diff --git a/shortcuts/im/im_messages_search_execute_test.go b/shortcuts/im/im_messages_search_execute_test.go
new file mode 100644
index 00000000..6cccd184
--- /dev/null
+++ b/shortcuts/im/im_messages_search_execute_test.go
@@ -0,0 +1,285 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package im
+
+import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "fmt"
+ "io"
+ "net/http"
+ "reflect"
+ "strings"
+ "testing"
+
+ "github.com/larksuite/cli/shortcuts/common"
+ "github.com/spf13/cobra"
+)
+
+func newMessagesSearchRuntime(t *testing.T, stringFlags map[string]string, boolFlags map[string]bool, rt http.RoundTripper) *common.RuntimeContext {
+ t.Helper()
+
+ runtime := newBotShortcutRuntime(t, rt)
+ cmd := &cobra.Command{Use: "test"}
+
+ stringFlagNames := []string{
+ "query",
+ "page-size",
+ "page-token",
+ "page-limit",
+ }
+ for _, name := range stringFlagNames {
+ cmd.Flags().String(name, "", "")
+ }
+ boolFlagNames := []string{"page-all"}
+ for _, name := range boolFlagNames {
+ cmd.Flags().Bool(name, false, "")
+ }
+ if err := cmd.ParseFlags(nil); err != nil {
+ t.Fatalf("ParseFlags() error = %v", err)
+ }
+ for name, value := range stringFlags {
+ if err := cmd.Flags().Set(name, value); err != nil {
+ t.Fatalf("Flags().Set(%q) error = %v", name, err)
+ }
+ }
+ for name, value := range boolFlags {
+ if err := cmd.Flags().Set(name, map[bool]string{true: "true", false: "false"}[value]); err != nil {
+ t.Fatalf("Flags().Set(%q) error = %v", name, err)
+ }
+ }
+ runtime.Cmd = cmd
+ runtime.Format = "pretty"
+ return runtime
+}
+
+func TestImMessagesSearchExecuteAutoPaginationBatches(t *testing.T) {
+ var (
+ searchPageTokens []string
+ mgetBatchSizes []int
+ chatBatchSizes []int
+ )
+
+ runtime := newMessagesSearchRuntime(t, map[string]string{
+ "query": "incident",
+ "page-limit": "2",
+ }, map[string]bool{
+ "page-all": true,
+ }, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+ switch {
+ case strings.Contains(req.URL.Path, "tenant_access_token"):
+ return shortcutJSONResponse(200, map[string]interface{}{
+ "code": 0,
+ "tenant_access_token": "tenant-token",
+ "expire": 7200,
+ }), nil
+ case strings.Contains(req.URL.Path, "/open-apis/im/v1/messages/search"):
+ pageToken := req.URL.Query().Get("page_token")
+ searchPageTokens = append(searchPageTokens, pageToken)
+ switch pageToken {
+ case "":
+ return shortcutJSONResponse(200, map[string]interface{}{
+ "code": 0,
+ "data": map[string]interface{}{
+ "items": buildSearchResultItems(1, 50),
+ "has_more": true,
+ "page_token": "tok_p2",
+ },
+ }), nil
+ case "tok_p2":
+ return shortcutJSONResponse(200, map[string]interface{}{
+ "code": 0,
+ "data": map[string]interface{}{
+ "items": buildSearchResultItems(51, 55),
+ "has_more": true,
+ "page_token": "tok_p3",
+ },
+ }), nil
+ default:
+ return nil, fmt.Errorf("unexpected search page_token: %q", pageToken)
+ }
+ case strings.Contains(req.URL.Path, "/open-apis/im/v1/messages/mget"):
+ ids := req.URL.Query()["message_ids"]
+ mgetBatchSizes = append(mgetBatchSizes, len(ids))
+ return shortcutJSONResponse(200, map[string]interface{}{
+ "code": 0,
+ "data": map[string]interface{}{
+ "items": buildMessageDetails(ids),
+ },
+ }), nil
+ case strings.Contains(req.URL.Path, "/open-apis/im/v1/chats/batch_query"):
+ var body struct {
+ ChatIDs []string `json:"chat_ids"`
+ }
+ rawBody, err := io.ReadAll(req.Body)
+ if err != nil {
+ t.Fatalf("ReadAll() error = %v", err)
+ }
+ if err := json.Unmarshal(rawBody, &body); err != nil {
+ t.Fatalf("json.Unmarshal() error = %v", err)
+ }
+ chatBatchSizes = append(chatBatchSizes, len(body.ChatIDs))
+ return shortcutJSONResponse(200, map[string]interface{}{
+ "code": 0,
+ "data": map[string]interface{}{
+ "items": buildChatContexts(body.ChatIDs),
+ },
+ }), nil
+ default:
+ return nil, fmt.Errorf("unexpected request: %s", req.URL.String())
+ }
+ }))
+
+ if err := ImMessagesSearch.Execute(context.Background(), runtime); err != nil {
+ t.Fatalf("ImMessagesSearch.Execute() error = %v", err)
+ }
+
+ if !reflect.DeepEqual(searchPageTokens, []string{"", "tok_p2"}) {
+ t.Fatalf("search page tokens = %#v, want %#v", searchPageTokens, []string{"", "tok_p2"})
+ }
+ if !reflect.DeepEqual(mgetBatchSizes, []int{50, 5}) {
+ t.Fatalf("mget batch sizes = %#v, want %#v", mgetBatchSizes, []int{50, 5})
+ }
+ if !reflect.DeepEqual(chatBatchSizes, []int{50, 5}) {
+ t.Fatalf("chat batch sizes = %#v, want %#v", chatBatchSizes, []int{50, 5})
+ }
+
+ outBuf, _ := runtime.Factory.IOStreams.Out.(*bytes.Buffer)
+ if outBuf == nil {
+ t.Fatal("stdout buffer missing")
+ }
+ output := outBuf.String()
+ if !strings.Contains(output, "55 search result(s)") {
+ t.Fatalf("stdout = %q, want search results summary", output)
+ }
+ if !strings.Contains(output, "warning: stopped after fetching 2 page(s)") {
+ t.Fatalf("stdout = %q, want page limit warning", output)
+ }
+}
+
+func TestImMessagesSearchExecuteExplicitPageLimitWithoutPageAll(t *testing.T) {
+ var searchCalls int
+
+ runtime := newMessagesSearchRuntime(t, map[string]string{
+ "query": "incident",
+ "page-limit": "2",
+ }, nil, shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+ switch {
+ case strings.Contains(req.URL.Path, "tenant_access_token"):
+ return shortcutJSONResponse(200, map[string]interface{}{
+ "code": 0,
+ "tenant_access_token": "tenant-token",
+ "expire": 7200,
+ }), nil
+ case strings.Contains(req.URL.Path, "/open-apis/im/v1/messages/search"):
+ searchCalls++
+ pageToken := req.URL.Query().Get("page_token")
+ if searchCalls == 1 {
+ if pageToken != "" {
+ return nil, fmt.Errorf("unexpected first page token: %q", pageToken)
+ }
+ return shortcutJSONResponse(200, map[string]interface{}{
+ "code": 0,
+ "data": map[string]interface{}{
+ "items": buildSearchResultItems(1, 1),
+ "has_more": true,
+ "page_token": "tok_p2",
+ },
+ }), nil
+ }
+ if pageToken != "tok_p2" {
+ return nil, fmt.Errorf("unexpected second page token: %q", pageToken)
+ }
+ return shortcutJSONResponse(200, map[string]interface{}{
+ "code": 0,
+ "data": map[string]interface{}{
+ "items": buildSearchResultItems(2, 2),
+ "has_more": false,
+ "page_token": "",
+ },
+ }), nil
+ case strings.Contains(req.URL.Path, "/open-apis/im/v1/messages/mget"):
+ ids := req.URL.Query()["message_ids"]
+ return shortcutJSONResponse(200, map[string]interface{}{
+ "code": 0,
+ "data": map[string]interface{}{
+ "items": buildMessageDetails(ids),
+ },
+ }), nil
+ case strings.Contains(req.URL.Path, "/open-apis/im/v1/chats/batch_query"):
+ var body struct {
+ ChatIDs []string `json:"chat_ids"`
+ }
+ rawBody, err := io.ReadAll(req.Body)
+ if err != nil {
+ t.Fatalf("ReadAll() error = %v", err)
+ }
+ if err := json.Unmarshal(rawBody, &body); err != nil {
+ t.Fatalf("json.Unmarshal() error = %v", err)
+ }
+ return shortcutJSONResponse(200, map[string]interface{}{
+ "code": 0,
+ "data": map[string]interface{}{
+ "items": buildChatContexts(body.ChatIDs),
+ },
+ }), nil
+ default:
+ return nil, fmt.Errorf("unexpected request: %s", req.URL.String())
+ }
+ }))
+
+ if err := ImMessagesSearch.Execute(context.Background(), runtime); err != nil {
+ t.Fatalf("ImMessagesSearch.Execute() error = %v", err)
+ }
+ if searchCalls != 2 {
+ t.Fatalf("searchCalls = %d, want 2", searchCalls)
+ }
+}
+
+func buildSearchResultItems(start, end int) []interface{} {
+ items := make([]interface{}, 0, end-start+1)
+ for i := start; i <= end; i++ {
+ items = append(items, map[string]interface{}{
+ "meta_data": map[string]interface{}{
+ "message_id": fmt.Sprintf("om_%03d", i),
+ },
+ })
+ }
+ return items
+}
+
+func buildMessageDetails(ids []string) []interface{} {
+ items := make([]interface{}, 0, len(ids))
+ for _, id := range ids {
+ suffix := strings.TrimPrefix(id, "om_")
+ items = append(items, map[string]interface{}{
+ "message_id": id,
+ "msg_type": "text",
+ "create_time": "1710000000",
+ "chat_id": "oc_" + suffix,
+ "sender": map[string]interface{}{
+ "id": "cli_bot",
+ "name": "Bot",
+ "sender_type": "bot",
+ },
+ "body": map[string]interface{}{
+ "content": fmt.Sprintf(`{"text":"message %s"}`, suffix),
+ },
+ })
+ }
+ return items
+}
+
+func buildChatContexts(chatIDs []string) []interface{} {
+ items := make([]interface{}, 0, len(chatIDs))
+ for _, chatID := range chatIDs {
+ items = append(items, map[string]interface{}{
+ "chat_id": chatID,
+ "chat_mode": "group",
+ "name": "Chat " + strings.TrimPrefix(chatID, "oc_"),
+ })
+ }
+ return items
+}
diff --git a/shortcuts/im/im_messages_send.go b/shortcuts/im/im_messages_send.go
index 98609316..f3364c54 100644
--- a/shortcuts/im/im_messages_send.go
+++ b/shortcuts/im/im_messages_send.go
@@ -18,10 +18,12 @@ import (
var ImMessagesSend = common.Shortcut{
Service: "im",
Command: "+messages-send",
- Description: "Send a message to a chat or direct message with bot identity; bot-only; sends to chat-id or user-id with text/markdown/post/media, supports idempotency key",
+ Description: "Send a message to a chat or direct message; user/bot; sends to chat-id or user-id with text/markdown/post/media, supports idempotency key",
Risk: "write",
Scopes: []string{"im:message:send_as_bot"},
- AuthTypes: []string{"bot"},
+ UserScopes: []string{"im:message.send_as_user"},
+ BotScopes: []string{"im:message:send_as_bot"},
+ AuthTypes: []string{"bot", "user"},
Flags: []common.Flag{
{Name: "chat-id", Desc: "(required, mutually exclusive with --user-id) chat ID (oc_xxx)"},
{Name: "user-id", Desc: "(required, mutually exclusive with --chat-id) user open_id (ou_xxx)"},
@@ -188,7 +190,7 @@ var ImMessagesSend = common.Shortcut{
return output.ErrValidation("%v", err)
}
}
-
+ // Resolve content type
if markdown != "" {
msgType, content = "post", resolveMarkdownAsPost(ctx, runtime, markdown)
} else if mt, c, err := resolveMediaContent(ctx, runtime, text, imageVal, fileVal, videoVal, videoCoverVal, audioVal); err != nil {
diff --git a/shortcuts/mail/helpers.go b/shortcuts/mail/helpers.go
index 4c8c3fcf..193f4f46 100644
--- a/shortcuts/mail/helpers.go
+++ b/shortcuts/mail/helpers.go
@@ -18,6 +18,7 @@ import (
"strconv"
"strings"
+ "github.com/larksuite/cli/internal/auth"
"github.com/larksuite/cli/internal/output"
"github.com/larksuite/cli/internal/validate"
"github.com/larksuite/cli/shortcuts/common"
@@ -217,24 +218,24 @@ func mailboxPath(mailboxID string, segments ...string) string {
}
// fetchMailboxPrimaryEmail retrieves mailbox primary_email_address from
-// user_mailboxes.profile. Returns empty string on failure (non-fatal).
-func fetchMailboxPrimaryEmail(runtime *common.RuntimeContext, mailboxID string) string {
+// user_mailboxes.profile. Returns the email address or an error.
+func fetchMailboxPrimaryEmail(runtime *common.RuntimeContext, mailboxID string) (string, error) {
if mailboxID == "" {
mailboxID = "me"
}
data, err := runtime.CallAPI("GET", mailboxPath(mailboxID, "profile"), nil, nil)
if err != nil {
- return ""
+ return "", err
}
if email := extractPrimaryEmail(data); email != "" {
- return email
+ return email, nil
}
if nested, ok := data["data"].(map[string]interface{}); ok {
if email := extractPrimaryEmail(nested); email != "" {
- return email
+ return email, nil
}
}
- return ""
+ return "", fmt.Errorf("profile API returned no primary_email_address")
}
func extractPrimaryEmail(data map[string]interface{}) string {
@@ -251,7 +252,8 @@ func extractPrimaryEmail(data map[string]interface{}) string {
// fetchCurrentUserEmail retrieves the current mailbox primary email.
func fetchCurrentUserEmail(runtime *common.RuntimeContext) string {
- return fetchMailboxPrimaryEmail(runtime, "me")
+ email, _ := fetchMailboxPrimaryEmail(runtime, "me")
+ return email
}
// fetchSelfEmailSet returns a set containing the primary email of the given
@@ -263,7 +265,7 @@ func fetchSelfEmailSet(runtime *common.RuntimeContext, mailboxID string) map[str
mailboxID = "me"
}
set := make(map[string]bool)
- if email := fetchMailboxPrimaryEmail(runtime, mailboxID); email != "" {
+ if email, _ := fetchMailboxPrimaryEmail(runtime, mailboxID); email != "" {
set[strings.ToLower(email)] = true
}
return set
@@ -679,6 +681,9 @@ func addUniqueID(dst *[]string, seen map[string]bool, id string) {
}
func listMailboxFolders(runtime *common.RuntimeContext, mailboxID string) ([]folderInfo, error) {
+ if err := validateFolderReadScope(runtime); err != nil {
+ return nil, err
+ }
data, err := runtime.CallAPI("GET", mailboxPath(mailboxID, "folders"), nil, nil)
if err != nil {
return nil, output.ErrValidation("unable to resolve --folder: failed to list folders (%v). %s", err, resolveLookupHint("folder", mailboxID))
@@ -700,6 +705,9 @@ func listMailboxFolders(runtime *common.RuntimeContext, mailboxID string) ([]fol
}
func listMailboxLabels(runtime *common.RuntimeContext, mailboxID string) ([]labelInfo, error) {
+ if err := validateLabelReadScope(runtime); err != nil {
+ return nil, err
+ }
data, err := runtime.CallAPI("GET", mailboxPath(mailboxID, "labels"), nil, nil)
if err != nil {
return nil, output.ErrValidation("unable to resolve --label: failed to list labels (%v). %s", err, resolveLookupHint("label", mailboxID))
@@ -1854,6 +1862,79 @@ func checkAttachmentSizeLimit(filePaths []string, extraBytes int64, extraCount .
return nil
}
+// validateConfirmSendScope checks that the user's token includes the
+// mail:user_mailbox.message:send scope when --confirm-send is set.
+// This scope is not declared in the shortcut's static Scopes (to keep the
+// default draft-only path accessible without the sensitive send permission),
+// so we validate it dynamically here.
+func validateConfirmSendScope(runtime *common.RuntimeContext) error {
+ if !runtime.Bool("confirm-send") {
+ return nil
+ }
+ appID := runtime.Config.AppID
+ userOpenId := runtime.UserOpenId()
+ if appID == "" || userOpenId == "" {
+ return nil
+ }
+ stored := auth.GetStoredToken(appID, userOpenId)
+ if stored == nil {
+ return nil
+ }
+ required := []string{"mail:user_mailbox.message:send"}
+ if missing := auth.MissingScopes(stored.Scope, required); len(missing) > 0 {
+ return output.ErrWithHint(output.ExitAuth, "missing_scope",
+ fmt.Sprintf("--confirm-send requires scope: %s", strings.Join(missing, ", ")),
+ fmt.Sprintf("run `lark-cli auth login --scope \"%s\"` to grant the send permission", strings.Join(missing, " ")))
+ }
+ return nil
+}
+
+// validateFolderReadScope checks that the user's token includes the
+// mail:user_mailbox.folder:read scope. Called on-demand by listMailboxFolders
+// before hitting the folders API. System folders are resolved locally and
+// never reach this check.
+func validateFolderReadScope(runtime *common.RuntimeContext) error {
+ appID := runtime.Config.AppID
+ userOpenId := runtime.UserOpenId()
+ if appID == "" || userOpenId == "" {
+ return nil
+ }
+ stored := auth.GetStoredToken(appID, userOpenId)
+ if stored == nil {
+ return nil
+ }
+ required := []string{"mail:user_mailbox.folder:read"}
+ if missing := auth.MissingScopes(stored.Scope, required); len(missing) > 0 {
+ return output.ErrWithHint(output.ExitAuth, "missing_scope",
+ fmt.Sprintf("folder resolution requires scope: %s", strings.Join(missing, ", ")),
+ fmt.Sprintf("run `lark-cli auth login --scope \"%s\"` to grant folder read permission", strings.Join(missing, " ")))
+ }
+ return nil
+}
+
+// validateLabelReadScope checks that the user's token includes the
+// mail:user_mailbox.message:modify scope. Called on-demand by listMailboxLabels
+// before hitting the labels API. System labels are resolved locally and
+// never reach this check.
+func validateLabelReadScope(runtime *common.RuntimeContext) error {
+ appID := runtime.Config.AppID
+ userOpenId := runtime.UserOpenId()
+ if appID == "" || userOpenId == "" {
+ return nil
+ }
+ stored := auth.GetStoredToken(appID, userOpenId)
+ if stored == nil {
+ return nil
+ }
+ required := []string{"mail:user_mailbox.message:modify"}
+ if missing := auth.MissingScopes(stored.Scope, required); len(missing) > 0 {
+ return output.ErrWithHint(output.ExitAuth, "missing_scope",
+ fmt.Sprintf("label resolution requires scope: %s", strings.Join(missing, ", ")),
+ fmt.Sprintf("run `lark-cli auth login --scope \"%s\"` to grant label access permission", strings.Join(missing, " ")))
+ }
+ return nil
+}
+
func validateComposeHasAtLeastOneRecipient(to, cc, bcc string) error {
if strings.TrimSpace(to) == "" && strings.TrimSpace(cc) == "" && strings.TrimSpace(bcc) == "" {
return fmt.Errorf("at least one recipient (--to, --cc, or --bcc) is required")
diff --git a/shortcuts/mail/mail_confirm_send_scope_test.go b/shortcuts/mail/mail_confirm_send_scope_test.go
new file mode 100644
index 00000000..e93fb215
--- /dev/null
+++ b/shortcuts/mail/mail_confirm_send_scope_test.go
@@ -0,0 +1,52 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package mail
+
+import (
+ "errors"
+ "testing"
+
+ "github.com/larksuite/cli/internal/output"
+)
+
+func TestConfirmSendMissingScopeReply(t *testing.T) {
+ f, stdout, _, _ := mailShortcutTestFactory(t)
+ err := runMountedMailShortcut(t, MailReply, []string{
+ "+reply", "--message-id", "msg_001", "--body", "hello", "--confirm-send",
+ }, f, stdout)
+ assertMissingSendScope(t, err)
+}
+
+func TestConfirmSendMissingScopeReplyAll(t *testing.T) {
+ f, stdout, _, _ := mailShortcutTestFactory(t)
+ err := runMountedMailShortcut(t, MailReplyAll, []string{
+ "+reply-all", "--message-id", "msg_001", "--body", "hello", "--confirm-send",
+ }, f, stdout)
+ assertMissingSendScope(t, err)
+}
+
+func TestConfirmSendMissingScopeForward(t *testing.T) {
+ f, stdout, _, _ := mailShortcutTestFactory(t)
+ err := runMountedMailShortcut(t, MailForward, []string{
+ "+forward", "--message-id", "msg_001", "--to", "alice@example.com", "--confirm-send",
+ }, f, stdout)
+ assertMissingSendScope(t, err)
+}
+
+func assertMissingSendScope(t *testing.T, err error) {
+ t.Helper()
+ if err == nil {
+ t.Fatal("expected error when token lacks send scope with --confirm-send, got nil")
+ }
+ var exitErr *output.ExitError
+ if !errors.As(err, &exitErr) {
+ t.Fatalf("expected ExitError, got %T: %v", err, err)
+ }
+ if exitErr.Code != output.ExitAuth {
+ t.Errorf("expected exit code %d (ExitAuth), got %d", output.ExitAuth, exitErr.Code)
+ }
+ if exitErr.Detail == nil || exitErr.Detail.Type != "missing_scope" {
+ t.Errorf("expected detail type missing_scope, got %+v", exitErr.Detail)
+ }
+}
diff --git a/shortcuts/mail/mail_draft_create.go b/shortcuts/mail/mail_draft_create.go
index 8b932795..d6f70690 100644
--- a/shortcuts/mail/mail_draft_create.go
+++ b/shortcuts/mail/mail_draft_create.go
@@ -43,8 +43,8 @@ var MailDraftCreate = common.Shortcut{
{Name: "cc", Desc: "Optional. Full Cc recipient list. Separate multiple addresses with commas. Display-name format is supported."},
{Name: "bcc", Desc: "Optional. Full Bcc recipient list. Separate multiple addresses with commas. Display-name format is supported."},
{Name: "plain-text", Type: "bool", Desc: "Force plain-text mode, ignoring HTML auto-detection. Cannot be used with --inline."},
- {Name: "attach", Desc: "Optional. Regular attachment file paths. Separate multiple paths with commas. Each path must point to a readable local file."},
- {Name: "inline", Desc: "Optional. Inline images as a JSON array. Each entry: {\"cid\":\"\",\"file_path\":\"\"}. Cannot be used with --plain-text. CID images are embedded via ![](\"cid:...\")
in the HTML body. CID is a unique identifier, e.g. a random hex string like \"a1b2c3d4e5f6a7b8c9d0\"."},
+ {Name: "attach", Desc: "Optional. Regular attachment file paths (relative path only). Separate multiple paths with commas. Each path must point to a readable local file."},
+ {Name: "inline", Desc: "Optional. Inline images as a JSON array. Each entry: {\"cid\":\"\",\"file_path\":\"\"}. All file_path values must be relative paths. Cannot be used with --plain-text. CID images are embedded via in the HTML body. CID is a unique identifier, e.g. a random hex string like \"a1b2c3d4e5f6a7b8c9d0\"."},
},
DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
input, err := parseDraftCreateInput(runtime)
diff --git a/shortcuts/mail/mail_draft_edit.go b/shortcuts/mail/mail_draft_edit.go
index b28d69d1..99061b8b 100644
--- a/shortcuts/mail/mail_draft_edit.go
+++ b/shortcuts/mail/mail_draft_edit.go
@@ -32,7 +32,7 @@ var MailDraftEdit = common.Shortcut{
{Name: "set-to", Desc: "Replace the entire To recipient list with the addresses provided here. Separate multiple addresses with commas. Display-name format is supported."},
{Name: "set-cc", Desc: "Replace the entire Cc recipient list with the addresses provided here. Separate multiple addresses with commas. Display-name format is supported."},
{Name: "set-bcc", Desc: "Replace the entire Bcc recipient list with the addresses provided here. Separate multiple addresses with commas. Display-name format is supported."},
- {Name: "patch-file", Desc: "Edit entry point for body edits, incremental recipient changes, header edits, attachment changes, or inline-image changes. All body edits MUST go through --patch-file. Two body ops: set_body (full replacement including quote) and set_reply_body (replaces only user-authored content, auto-preserves quote block). Run --inspect first to check has_quoted_content, then --print-patch-template for the JSON structure."},
+ {Name: "patch-file", Desc: "Edit entry point for body edits, incremental recipient changes, header edits, attachment changes, or inline-image changes. All body edits MUST go through --patch-file. Two body ops: set_body (full replacement including quote) and set_reply_body (replaces only user-authored content, auto-preserves quote block). Run --inspect first to check has_quoted_content, then --print-patch-template for the JSON structure. Relative path only."},
{Name: "print-patch-template", Type: "bool", Desc: "Print the JSON template and supported operations for the --patch-file flag. Recommended first step before generating a patch file. No draft read or write is performed."},
{Name: "inspect", Type: "bool", Desc: "Inspect the draft without modifying it. Returns the draft projection including subject, recipients, body summary, has_quoted_content (whether the draft contains a reply/forward quote block), attachments_summary (with part_id and cid for each attachment), and inline_summary. Run this BEFORE editing body to check has_quoted_content: if true, use set_reply_body in --patch-file to preserve the quote; if false, use set_body."},
},
@@ -307,10 +307,10 @@ func buildDraftEditPatchTemplate() map[string]interface{} {
{"op": "set_reply_body", "shape": map[string]interface{}{"value": "string (user-authored content only, WITHOUT the quote block; the quote block is re-appended automatically)"}},
{"op": "set_header", "shape": map[string]interface{}{"name": "string", "value": "string"}},
{"op": "remove_header", "shape": map[string]interface{}{"name": "string"}},
- {"op": "add_attachment", "shape": map[string]interface{}{"path": "string"}},
+ {"op": "add_attachment", "shape": map[string]interface{}{"path": "string(relative path)"}},
{"op": "remove_attachment", "shape": map[string]interface{}{"target": map[string]interface{}{"part_id": "string(optional)", "cid": "string(optional)"}}},
- {"op": "add_inline", "shape": map[string]interface{}{"path": "string", "cid": "string", "filename": "string(optional)", "content_type": "string(optional)"}},
- {"op": "replace_inline", "shape": map[string]interface{}{"target": map[string]interface{}{"part_id": "string(optional)", "cid": "string(optional)"}, "path": "string", "cid": "string(optional)", "filename": "string(optional)", "content_type": "string(optional)"}},
+ {"op": "add_inline", "shape": map[string]interface{}{"path": "string(relative path)", "cid": "string", "filename": "string(optional)", "content_type": "string(optional)"}},
+ {"op": "replace_inline", "shape": map[string]interface{}{"target": map[string]interface{}{"part_id": "string(optional)", "cid": "string(optional)"}, "path": "string(relative path)", "cid": "string(optional)", "filename": "string(optional)", "content_type": "string(optional)"}},
{"op": "remove_inline", "shape": map[string]interface{}{"target": map[string]interface{}{"part_id": "string(optional)", "cid": "string(optional)"}}},
},
"supported_ops_by_group": []map[string]interface{}{
@@ -340,10 +340,10 @@ func buildDraftEditPatchTemplate() map[string]interface{} {
{
"group": "attachments_and_inline",
"ops": []map[string]interface{}{
- {"op": "add_attachment", "shape": map[string]interface{}{"path": "string"}},
+ {"op": "add_attachment", "shape": map[string]interface{}{"path": "string(relative path)"}},
{"op": "remove_attachment", "shape": map[string]interface{}{"target": map[string]interface{}{"part_id": "string(optional)", "cid": "string(optional)"}}},
- {"op": "add_inline", "shape": map[string]interface{}{"path": "string", "cid": "string", "filename": "string(optional)", "content_type": "string(optional)"}},
- {"op": "replace_inline", "shape": map[string]interface{}{"target": map[string]interface{}{"part_id": "string(optional)", "cid": "string(optional)"}, "path": "string", "cid": "string(optional)", "filename": "string(optional)", "content_type": "string(optional)"}},
+ {"op": "add_inline", "shape": map[string]interface{}{"path": "string(relative path)", "cid": "string", "filename": "string(optional)", "content_type": "string(optional)"}},
+ {"op": "replace_inline", "shape": map[string]interface{}{"target": map[string]interface{}{"part_id": "string(optional)", "cid": "string(optional)"}, "path": "string(relative path)", "cid": "string(optional)", "filename": "string(optional)", "content_type": "string(optional)"}},
{"op": "remove_inline", "shape": map[string]interface{}{"target": map[string]interface{}{"part_id": "string(optional)", "cid": "string(optional)"}}},
},
},
@@ -360,6 +360,7 @@ func buildDraftEditPatchTemplate() map[string]interface{} {
},
"notes": []string{
"`ops` is executed in order",
+ "all file paths (--patch-file and `path` fields in ops) must be relative — no absolute paths or .. traversal",
"all body edits MUST go through --patch-file; there is no --set-body flag",
"`set_body` replaces the ENTIRE body including any reply/forward quote block; when the draft has both text/plain and text/html, it updates the HTML body and regenerates the plain-text summary, so the input should be HTML",
"`set_reply_body` replaces only the user-authored portion of the body and automatically re-appends the trailing reply/forward quote block (generated by +reply or +forward); the value you pass should contain ONLY the new user-authored content WITHOUT the quote block — the quote block will be re-inserted automatically; if the user wants to modify content INSIDE the quote block, use `set_body` instead for full replacement; if the draft has no quote block, it behaves identically to `set_body`",
diff --git a/shortcuts/mail/mail_forward.go b/shortcuts/mail/mail_forward.go
index 7af87421..905bc8af 100644
--- a/shortcuts/mail/mail_forward.go
+++ b/shortcuts/mail/mail_forward.go
@@ -20,7 +20,7 @@ var MailForward = common.Shortcut{
Command: "+forward",
Description: "Forward a message and save as draft (default). Use --confirm-send to send immediately after user confirmation. Original message block included automatically.",
Risk: "write",
- Scopes: []string{"mail:user_mailbox.message:send", "mail:user_mailbox.message:modify", "mail:user_mailbox.message:readonly", "mail:user_mailbox:readonly", "mail:user_mailbox.message.address:read", "mail:user_mailbox.message.subject:read", "mail:user_mailbox.message.body:read"},
+ Scopes: []string{"mail:user_mailbox.message:modify", "mail:user_mailbox.message:readonly", "mail:user_mailbox:readonly", "mail:user_mailbox.message.address:read", "mail:user_mailbox.message.subject:read", "mail:user_mailbox.message.body:read"},
AuthTypes: []string{"user"},
Flags: []common.Flag{
{Name: "message-id", Desc: "Required. Message ID to forward", Required: true},
@@ -30,8 +30,8 @@ var MailForward = common.Shortcut{
{Name: "cc", Desc: "CC email address(es), comma-separated"},
{Name: "bcc", Desc: "BCC email address(es), comma-separated"},
{Name: "plain-text", Type: "bool", Desc: "Force plain-text mode, ignoring all HTML auto-detection. Cannot be used with --inline."},
- {Name: "attach", Desc: "Attachment file path(s), comma-separated (appended after original attachments)"},
- {Name: "inline", Desc: "Inline images as a JSON array. Each entry: {\"cid\":\"\",\"file_path\":\"\"}. Cannot be used with --plain-text. CID images are embedded via in the HTML body. CID is a unique identifier, e.g. a random hex string like \"a1b2c3d4e5f6a7b8c9d0\"."},
+ {Name: "attach", Desc: "Attachment file path(s), comma-separated, appended after original attachments (relative path only)"},
+ {Name: "inline", Desc: "Inline images as a JSON array. Each entry: {\"cid\":\"\",\"file_path\":\"\"}. All file_path values must be relative paths. Cannot be used with --plain-text. CID images are embedded via in the HTML body. CID is a unique identifier, e.g. a random hex string like \"a1b2c3d4e5f6a7b8c9d0\"."},
{Name: "confirm-send", Type: "bool", Desc: "Send the forward immediately instead of saving as draft. Only use after the user has explicitly confirmed recipients and content."},
},
DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
@@ -55,6 +55,9 @@ var MailForward = common.Shortcut{
return api
},
Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+ if err := validateConfirmSendScope(runtime); err != nil {
+ return err
+ }
if runtime.Bool("confirm-send") {
if err := validateComposeHasAtLeastOneRecipient(runtime.Str("to"), runtime.Str("cc"), runtime.Str("bcc")); err != nil {
return err
diff --git a/shortcuts/mail/mail_reply.go b/shortcuts/mail/mail_reply.go
index 465b6b60..b89bc5d6 100644
--- a/shortcuts/mail/mail_reply.go
+++ b/shortcuts/mail/mail_reply.go
@@ -18,7 +18,7 @@ var MailReply = common.Shortcut{
Command: "+reply",
Description: "Reply to a message and save as draft (default). Use --confirm-send to send immediately after user confirmation. Sets Re: subject, In-Reply-To, and References headers automatically.",
Risk: "write",
- Scopes: []string{"mail:user_mailbox.message:send", "mail:user_mailbox.message:modify", "mail:user_mailbox.message:readonly", "mail:user_mailbox:readonly", "mail:user_mailbox.message.address:read", "mail:user_mailbox.message.subject:read", "mail:user_mailbox.message.body:read"},
+ Scopes: []string{"mail:user_mailbox.message:modify", "mail:user_mailbox.message:readonly", "mail:user_mailbox:readonly", "mail:user_mailbox.message.address:read", "mail:user_mailbox.message.subject:read", "mail:user_mailbox.message.body:read"},
AuthTypes: []string{"user"},
Flags: []common.Flag{
{Name: "message-id", Desc: "Required. Message ID to reply to", Required: true},
@@ -28,8 +28,8 @@ var MailReply = common.Shortcut{
{Name: "cc", Desc: "Additional CC email address(es), comma-separated"},
{Name: "bcc", Desc: "BCC email address(es), comma-separated"},
{Name: "plain-text", Type: "bool", Desc: "Force plain-text mode, ignoring all HTML auto-detection. Cannot be used with --inline."},
- {Name: "attach", Desc: "Attachment file path(s), comma-separated"},
- {Name: "inline", Desc: "Inline images as a JSON array. Each entry: {\"cid\":\"\",\"file_path\":\"\"}. Cannot be used with --plain-text. CID images are embedded via in the HTML body. CID is a unique identifier, e.g. a random hex string like \"a1b2c3d4e5f6a7b8c9d0\"."},
+ {Name: "attach", Desc: "Attachment file path(s), comma-separated (relative path only)"},
+ {Name: "inline", Desc: "Inline images as a JSON array. Each entry: {\"cid\":\"\",\"file_path\":\"\"}. All file_path values must be relative paths. Cannot be used with --plain-text. CID images are embedded via in the HTML body. CID is a unique identifier, e.g. a random hex string like \"a1b2c3d4e5f6a7b8c9d0\"."},
{Name: "confirm-send", Type: "bool", Desc: "Send the reply immediately instead of saving as draft. Only use after the user has explicitly confirmed recipients and content."},
},
DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
@@ -52,6 +52,9 @@ var MailReply = common.Shortcut{
return api
},
Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+ if err := validateConfirmSendScope(runtime); err != nil {
+ return err
+ }
return validateComposeInlineAndAttachments(runtime.Str("attach"), runtime.Str("inline"), runtime.Bool("plain-text"), "")
},
Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
diff --git a/shortcuts/mail/mail_reply_all.go b/shortcuts/mail/mail_reply_all.go
index adfb81ae..6b82365e 100644
--- a/shortcuts/mail/mail_reply_all.go
+++ b/shortcuts/mail/mail_reply_all.go
@@ -18,7 +18,7 @@ var MailReplyAll = common.Shortcut{
Command: "+reply-all",
Description: "Reply to all recipients and save as draft (default). Use --confirm-send to send immediately after user confirmation. Includes all original To and CC automatically.",
Risk: "write",
- Scopes: []string{"mail:user_mailbox.message:send", "mail:user_mailbox.message:modify", "mail:user_mailbox.message:readonly", "mail:user_mailbox:readonly", "mail:user_mailbox.message.address:read", "mail:user_mailbox.message.subject:read", "mail:user_mailbox.message.body:read"},
+ Scopes: []string{"mail:user_mailbox.message:modify", "mail:user_mailbox.message:readonly", "mail:user_mailbox:readonly", "mail:user_mailbox.message.address:read", "mail:user_mailbox.message.subject:read", "mail:user_mailbox.message.body:read"},
AuthTypes: []string{"user"},
Flags: []common.Flag{
{Name: "message-id", Desc: "Required. Message ID to reply to all recipients", Required: true},
@@ -29,8 +29,8 @@ var MailReplyAll = common.Shortcut{
{Name: "bcc", Desc: "BCC email address(es), comma-separated"},
{Name: "remove", Desc: "Address(es) to exclude from the outgoing reply, comma-separated"},
{Name: "plain-text", Type: "bool", Desc: "Force plain-text mode, ignoring all HTML auto-detection. Cannot be used with --inline."},
- {Name: "attach", Desc: "Attachment file path(s), comma-separated"},
- {Name: "inline", Desc: "Inline images as a JSON array. Each entry: {\"cid\":\"\",\"file_path\":\"\"}. Cannot be used with --plain-text. CID images are embedded via in the HTML body. CID is a unique identifier, e.g. a random hex string like \"a1b2c3d4e5f6a7b8c9d0\"."},
+ {Name: "attach", Desc: "Attachment file path(s), comma-separated (relative path only)"},
+ {Name: "inline", Desc: "Inline images as a JSON array. Each entry: {\"cid\":\"\",\"file_path\":\"\"}. All file_path values must be relative paths. Cannot be used with --plain-text. CID images are embedded via in the HTML body. CID is a unique identifier, e.g. a random hex string like \"a1b2c3d4e5f6a7b8c9d0\"."},
{Name: "confirm-send", Type: "bool", Desc: "Send the reply immediately instead of saving as draft. Only use after the user has explicitly confirmed recipients and content."},
},
DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
@@ -53,6 +53,9 @@ var MailReplyAll = common.Shortcut{
return api
},
Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+ if err := validateConfirmSendScope(runtime); err != nil {
+ return err
+ }
return validateComposeInlineAndAttachments(runtime.Str("attach"), runtime.Str("inline"), runtime.Bool("plain-text"), "")
},
Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
diff --git a/shortcuts/mail/mail_send.go b/shortcuts/mail/mail_send.go
index 71c429df..43b63826 100644
--- a/shortcuts/mail/mail_send.go
+++ b/shortcuts/mail/mail_send.go
@@ -28,8 +28,8 @@ var MailSend = common.Shortcut{
{Name: "cc", Desc: "CC email address(es), comma-separated"},
{Name: "bcc", Desc: "BCC email address(es), comma-separated"},
{Name: "plain-text", Type: "bool", Desc: "Force plain-text mode, ignoring HTML auto-detection. Cannot be used with --inline."},
- {Name: "attach", Desc: "Attachment file path(s), comma-separated"},
- {Name: "inline", Desc: "Inline images as a JSON array. Each entry: {\"cid\":\"\",\"file_path\":\"\"}. Cannot be used with --plain-text. CID images are embedded via in the HTML body. CID is a unique identifier, e.g. a random hex string like \"a1b2c3d4e5f6a7b8c9d0\"."},
+ {Name: "attach", Desc: "Attachment file path(s), comma-separated (relative path only)"},
+ {Name: "inline", Desc: "Inline images as a JSON array. Each entry: {\"cid\":\"\",\"file_path\":\"\"}. All file_path values must be relative paths. Cannot be used with --plain-text. CID images are embedded via in the HTML body. CID is a unique identifier, e.g. a random hex string like \"a1b2c3d4e5f6a7b8c9d0\"."},
{Name: "confirm-send", Type: "bool", Desc: "Send the email immediately instead of saving as draft. Only use after the user has explicitly confirmed recipients and content."},
},
DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
diff --git a/shortcuts/mail/mail_shortcut_test.go b/shortcuts/mail/mail_shortcut_test.go
index 2c9d389a..88fa89e0 100644
--- a/shortcuts/mail/mail_shortcut_test.go
+++ b/shortcuts/mail/mail_shortcut_test.go
@@ -42,7 +42,7 @@ func mailShortcutTestFactory(t *testing.T) (*cmdutil.Factory, *bytes.Buffer, *by
RefreshToken: "test-refresh-token",
ExpiresAt: time.Now().Add(1 * time.Hour).UnixMilli(),
RefreshExpiresAt: time.Now().Add(24 * time.Hour).UnixMilli(),
- Scope: "mail:user_mailbox.messages:write mail:user_mailbox.messages:read mail:user_mailbox.message:send mail:user_mailbox.message:modify mail:user_mailbox.message:readonly mail:user_mailbox.message.address:read mail:user_mailbox.message.subject:read mail:user_mailbox.message.body:read mail:user_mailbox:readonly",
+ Scope: "mail:user_mailbox.messages:write mail:user_mailbox.messages:read mail:user_mailbox.message:modify mail:user_mailbox.message:readonly mail:user_mailbox.message.address:read mail:user_mailbox.message.subject:read mail:user_mailbox.message.body:read mail:user_mailbox:readonly",
GrantedAt: time.Now().Add(-1 * time.Hour).UnixMilli(),
}
if err := auth.SetStoredToken(token); err != nil {
diff --git a/shortcuts/mail/mail_watch.go b/shortcuts/mail/mail_watch.go
index 21386b7e..c5699427 100644
--- a/shortcuts/mail/mail_watch.go
+++ b/shortcuts/mail/mail_watch.go
@@ -7,6 +7,7 @@ import (
"bytes"
"context"
"encoding/json"
+ "errors"
"fmt"
"io"
"net/http"
@@ -16,6 +17,7 @@ import (
"regexp"
"sort"
"strings"
+ "sync"
"syscall"
larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
@@ -79,8 +81,8 @@ var MailWatch = common.Shortcut{
Command: "+watch",
Description: "Watch for incoming mail events via WebSocket (requires scope mail:event and bot event mail.user_mailbox.event.message_received_v1 added). Run with --print-output-schema to see per-format field reference before parsing output.",
Risk: "read",
- Scopes: []string{"mail:event", "mail:user_mailbox.message:readonly", "mail:user_mailbox.folder:read", "mail:user_mailbox.message.address:read", "mail:user_mailbox.message.subject:read", "mail:user_mailbox.message.body:read"},
- AuthTypes: []string{"user", "bot"},
+ Scopes: []string{"mail:event", "mail:user_mailbox.message:readonly", "mail:user_mailbox.message.address:read", "mail:user_mailbox.message.subject:read", "mail:user_mailbox.message.body:read"},
+ AuthTypes: []string{"user"},
Flags: []common.Flag{
{Name: "format", Default: "data", Desc: "json: NDJSON stream with ok/data envelope; data: bare NDJSON stream"},
{Name: "msg-format", Default: "metadata", Desc: "message payload mode: metadata(headers + meta, for triage/notification) | minimal(IDs and state only, no headers, for tracking read/folder changes) | plain_text_full(all metadata fields + full plain-text body) | event(raw WebSocket event, no API call, for debug) | full(full message including HTML body and attachments)"},
@@ -138,6 +140,11 @@ var MailWatch = common.Shortcut{
Desc(fmt.Sprintf("Subscribe mailbox events (effective_folder_ids=%s, effective_label_ids=%s)", effectiveFolderDisplay, effectiveLabelDisplay)).
Body(map[string]interface{}{"event_type": 1})
+ if mailbox == "me" {
+ d.GET(mailboxPath("me", "profile")).
+ Desc("Resolve mailbox address for event filtering (requires scope mail:user_mailbox:readonly)")
+ }
+
if len(resolvedLabelIDs) > 0 {
d.Set("filter_label_ids", strings.Join(resolvedLabelIDs, ","))
}
@@ -244,11 +251,24 @@ var MailWatch = common.Shortcut{
}
info("Mailbox subscribed.")
- // mailboxFilter: only apply event-level filtering when an explicit email address is given
- // "me" is a server-side alias and cannot be matched against event.mail_address
- mailboxFilter := ""
- if mailbox != "me" {
- mailboxFilter = mailbox
+ var unsubOnce sync.Once
+ var unsubErr error
+ unsubscribe := func() error {
+ unsubOnce.Do(func() {
+ _, unsubErr = runtime.CallAPI("POST", mailboxPath(mailbox, "event", "unsubscribe"), nil, map[string]interface{}{"event_type": 1})
+ })
+ return unsubErr
+ }
+
+ // Resolve "me" to the actual email address so we can filter events.
+ mailboxFilter := mailbox
+ if mailbox == "me" {
+ resolved, profileErr := fetchMailboxPrimaryEmail(runtime, "me")
+ if profileErr != nil {
+ unsubscribe() //nolint:errcheck // best-effort cleanup; primary error is profileErr
+ return enhanceProfileError(profileErr)
+ }
+ mailboxFilter = resolved
}
eventCount := 0
@@ -257,10 +277,10 @@ var MailWatch = common.Shortcut{
// Extract event body
eventBody := extractMailEventBody(data)
- // Filter by --mailbox (only when an explicit email address was provided)
+ // Filter by --mailbox
if mailboxFilter != "" {
mailAddr, _ := eventBody["mail_address"].(string)
- if mailAddr != mailboxFilter {
+ if !strings.EqualFold(mailAddr, mailboxFilter) {
return
}
}
@@ -414,12 +434,19 @@ var MailWatch = common.Shortcut{
}()
<-sigCh
info(fmt.Sprintf("\nShutting down... (received %d events)", eventCount))
+ info("Unsubscribing mailbox events...")
+ if unsubErr := unsubscribe(); unsubErr != nil {
+ fmt.Fprintf(errOut, "Warning: unsubscribe failed: %v\n", unsubErr)
+ } else {
+ info("Mailbox unsubscribed.")
+ }
signal.Stop(sigCh)
os.Exit(0)
}()
info("Connected. Waiting for mail events... (Ctrl+C to stop)")
if err := cli.Start(ctx); err != nil {
+ unsubscribe() //nolint:errcheck // best-effort cleanup
return output.ErrNetwork("WebSocket connection failed: %v", err)
}
return nil
@@ -692,6 +719,25 @@ func wrapWatchSubscribeError(err error) error {
return output.ErrWithHint(output.ExitAPI, "api_error", fmt.Sprintf("subscribe mailbox events failed: %v", err), hint)
}
+// enhanceProfileError wraps a profile API error with actionable hints.
+// Permission errors get a scope-specific hint; other errors (network, 5xx)
+// are reported as-is so diagnostics aren't misleading.
+func enhanceProfileError(err error) error {
+ var exitErr *output.ExitError
+ if errors.As(err, &exitErr) && exitErr.Detail != nil {
+ errType := exitErr.Detail.Type
+ lower := strings.ToLower(exitErr.Detail.Message)
+ if errType == "permission" || errType == "missing_scope" ||
+ strings.Contains(lower, "permission") || strings.Contains(lower, "scope") {
+ return output.ErrWithHint(output.ExitAuth, "missing_scope",
+ "unable to resolve mailbox address: "+exitErr.Detail.Message,
+ "run `lark-cli auth login --scope \"mail:user_mailbox:readonly\"` to grant mailbox profile access")
+ }
+ }
+ // Preserve original error (and its exit code) for non-permission failures.
+ return err
+}
+
// decodeBodyFieldsForFile returns a shallow copy of outputData with body_html and
// body_plain_text decoded from base64url, so that files saved via --output-dir contain
// human-readable content instead of raw base64 strings.
diff --git a/shortcuts/mail/mail_watch_test.go b/shortcuts/mail/mail_watch_test.go
index 9717de3b..02476fbd 100644
--- a/shortcuts/mail/mail_watch_test.go
+++ b/shortcuts/mail/mail_watch_test.go
@@ -87,8 +87,8 @@ func TestMailWatchDryRunDefaultMetadataFetchesMessage(t *testing.T) {
runtime := runtimeForMailWatchTest(t, map[string]string{})
apis := dryRunAPIsForMailWatchTest(t, MailWatch.DryRun(context.Background(), runtime))
- if len(apis) != 2 {
- t.Fatalf("expected 2 dry-run apis, got %d", len(apis))
+ if len(apis) != 3 {
+ t.Fatalf("expected 3 dry-run apis, got %d", len(apis))
}
if apis[0].Method != "POST" {
t.Fatalf("unexpected method: %s", apis[0].Method)
@@ -96,10 +96,13 @@ func TestMailWatchDryRunDefaultMetadataFetchesMessage(t *testing.T) {
if apis[0].URL != mailboxPath("me", "event", "subscribe") {
t.Fatalf("unexpected url: %s", apis[0].URL)
}
- if apis[1].URL != mailboxPath("me", "messages", "{message_id}") {
- t.Fatalf("unexpected fetch url: %s", apis[1].URL)
+ if apis[1].Method != "GET" || apis[1].URL != mailboxPath("me", "profile") {
+ t.Fatalf("unexpected profile api: %s %s", apis[1].Method, apis[1].URL)
}
- if got := apis[1].Params["format"]; got != "metadata" {
+ if apis[2].URL != mailboxPath("me", "messages", "{message_id}") {
+ t.Fatalf("unexpected fetch url: %s", apis[2].URL)
+ }
+ if got := apis[2].Params["format"]; got != "metadata" {
t.Fatalf("unexpected fetch format: %#v", got)
}
}
@@ -110,16 +113,16 @@ func TestMailWatchDryRunMetadataFormatFetchesMessage(t *testing.T) {
})
apis := dryRunAPIsForMailWatchTest(t, MailWatch.DryRun(context.Background(), runtime))
- if len(apis) != 2 {
- t.Fatalf("expected 2 dry-run apis, got %d", len(apis))
+ if len(apis) != 3 {
+ t.Fatalf("expected 3 dry-run apis, got %d", len(apis))
}
- if apis[1].Method != "GET" {
- t.Fatalf("unexpected fetch method: %s", apis[1].Method)
+ if apis[2].Method != "GET" {
+ t.Fatalf("unexpected fetch method: %s", apis[2].Method)
}
- if apis[1].URL != mailboxPath("me", "messages", "{message_id}") {
- t.Fatalf("unexpected fetch url: %s", apis[1].URL)
+ if apis[2].URL != mailboxPath("me", "messages", "{message_id}") {
+ t.Fatalf("unexpected fetch url: %s", apis[2].URL)
}
- if got := apis[1].Params["format"]; got != "metadata" {
+ if got := apis[2].Params["format"]; got != "metadata" {
t.Fatalf("unexpected fetch format: %#v", got)
}
}
@@ -130,10 +133,10 @@ func TestMailWatchDryRunMinimalFormatFetchesMessage(t *testing.T) {
})
apis := dryRunAPIsForMailWatchTest(t, MailWatch.DryRun(context.Background(), runtime))
- if len(apis) != 2 {
- t.Fatalf("expected 2 dry-run apis, got %d", len(apis))
+ if len(apis) != 3 {
+ t.Fatalf("expected 3 dry-run apis, got %d", len(apis))
}
- if got := apis[1].Params["format"]; got != "metadata" {
+ if got := apis[2].Params["format"]; got != "metadata" {
t.Fatalf("unexpected fetch format: %#v", got)
}
}
@@ -173,10 +176,10 @@ func TestMailWatchDryRunPlainTextFullFormatFetchesMessage(t *testing.T) {
})
apis := dryRunAPIsForMailWatchTest(t, MailWatch.DryRun(context.Background(), runtime))
- if len(apis) != 2 {
- t.Fatalf("expected 2 dry-run apis, got %d", len(apis))
+ if len(apis) != 3 {
+ t.Fatalf("expected 3 dry-run apis, got %d", len(apis))
}
- if got := apis[1].Params["format"]; got != "plain_text_full" {
+ if got := apis[2].Params["format"]; got != "plain_text_full" {
t.Fatalf("unexpected fetch format: %#v", got)
}
}
@@ -187,10 +190,10 @@ func TestMailWatchDryRunFullFormatUsesFull(t *testing.T) {
})
apis := dryRunAPIsForMailWatchTest(t, MailWatch.DryRun(context.Background(), runtime))
- if len(apis) != 2 {
- t.Fatalf("expected 2 dry-run apis, got %d", len(apis))
+ if len(apis) != 3 {
+ t.Fatalf("expected 3 dry-run apis, got %d", len(apis))
}
- if got := apis[1].Params["format"]; got != "full" {
+ if got := apis[2].Params["format"]; got != "full" {
t.Fatalf("unexpected fetch format: %#v", got)
}
}
@@ -202,13 +205,13 @@ func TestMailWatchDryRunEventFormatWithLabelFilterFetchesMessage(t *testing.T) {
})
apis := dryRunAPIsForMailWatchTest(t, MailWatch.DryRun(context.Background(), runtime))
- if len(apis) != 2 {
- t.Fatalf("expected 2 dry-run apis, got %d", len(apis))
+ if len(apis) != 3 {
+ t.Fatalf("expected 3 dry-run apis, got %d", len(apis))
}
- if apis[1].URL != mailboxPath("me", "messages", "{message_id}") {
- t.Fatalf("unexpected fetch url: %s", apis[1].URL)
+ if apis[2].URL != mailboxPath("me", "messages", "{message_id}") {
+ t.Fatalf("unexpected fetch url: %s", apis[2].URL)
}
- if got := apis[1].Params["format"]; got != "metadata" {
+ if got := apis[2].Params["format"]; got != "metadata" {
t.Fatalf("unexpected fetch format: %#v", got)
}
}
diff --git a/shortcuts/minutes/minutes_download.go b/shortcuts/minutes/minutes_download.go
new file mode 100644
index 00000000..9a8c5545
--- /dev/null
+++ b/shortcuts/minutes/minutes_download.go
@@ -0,0 +1,339 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package minutes
+
+import (
+ "context"
+ "fmt"
+ "io"
+ "mime"
+ "net/http"
+ "os"
+ "path/filepath"
+ "regexp"
+ "strings"
+ "time"
+
+ "github.com/larksuite/cli/internal/output"
+ "github.com/larksuite/cli/internal/validate"
+ "github.com/larksuite/cli/shortcuts/common"
+)
+
+const (
+ // disableClientTimeout removes the global 30s client timeout for large media downloads.
+ // The download is bounded by the caller's context (e.g. Ctrl+C). A fixed timeout
+ // would cut off legitimate large file transfers.
+ disableClientTimeout = 0
+
+ maxBatchSize = 50
+ maxDownloadRedirects = 5
+)
+
+// validMinuteToken matches minute tokens: lowercase alphanumeric characters only.
+var validMinuteToken = regexp.MustCompile(`^[a-z0-9]+$`)
+
+var MinutesDownload = common.Shortcut{
+ Service: "minutes",
+ Command: "+download",
+ Description: "Download audio/video media file of a minute",
+ Risk: "read",
+ Scopes: []string{"minutes:minutes.media:export"},
+ AuthTypes: []string{"user", "bot"},
+ HasFormat: true,
+ Flags: []common.Flag{
+ {Name: "minute-tokens", Desc: "minute tokens, comma-separated for batch download (max 50)", Required: true},
+ {Name: "output", Desc: "output path: file path for single token, directory for batch (default: current dir)"},
+ {Name: "overwrite", Type: "bool", Desc: "overwrite existing output file"},
+ {Name: "url-only", Type: "bool", Desc: "only print the download URL(s) without downloading"},
+ },
+ Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+ tokens := common.SplitCSV(runtime.Str("minute-tokens"))
+ if len(tokens) == 0 {
+ return output.ErrValidation("--minute-tokens is required")
+ }
+ if len(tokens) > maxBatchSize {
+ return output.ErrValidation("--minute-tokens: too many tokens (%d), maximum is %d", len(tokens), maxBatchSize)
+ }
+ for _, token := range tokens {
+ if !validMinuteToken.MatchString(token) {
+ return output.ErrValidation("invalid minute token %q: must contain only lowercase alphanumeric characters (e.g. obcnq3b9jl72l83w4f149w9c)", token)
+ }
+ }
+ return nil
+ },
+ DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+ tokens := common.SplitCSV(runtime.Str("minute-tokens"))
+ return common.NewDryRunAPI().
+ GET("/open-apis/minutes/v1/minutes/:minute_token/media").
+ Set("minute_tokens", tokens)
+ },
+ Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+ tokens := common.SplitCSV(runtime.Str("minute-tokens"))
+ outputPath := runtime.Str("output")
+ overwrite := runtime.Bool("overwrite")
+ urlOnly := runtime.Bool("url-only")
+ errOut := runtime.IO().ErrOut
+ single := len(tokens) == 1
+
+ // Batch mode: --output must be a directory, not an existing file.
+ if !single && outputPath != "" {
+ if fi, err := os.Stat(outputPath); err == nil && !fi.IsDir() {
+ return output.ErrValidation("--output %q is a file; batch mode expects a directory path", outputPath)
+ }
+ }
+
+ if !single {
+ fmt.Fprintf(errOut, "[minutes +download] batch: %d token(s)\n", len(tokens))
+ }
+
+ type result struct {
+ MinuteToken string `json:"minute_token"`
+ SavedPath string `json:"saved_path,omitempty"`
+ SizeBytes int64 `json:"size_bytes,omitempty"`
+ DownloadURL string `json:"download_url,omitempty"`
+ Error string `json:"error,omitempty"`
+ }
+
+ results := make([]result, len(tokens))
+ seen := make(map[string]int)
+ usedNames := make(map[string]bool)
+
+ // Clone the factory client for download use. We clone the struct (not the
+ // pointer) to avoid mutating the shared singleton's Timeout. The original
+ // transport chain is preserved so security headers and test mocks still work.
+ // SSRF protection: ValidateDownloadSourceURL (URL-level) + CheckRedirect
+ // (redirect-level). Transport-level IP check is intentionally omitted because
+ // download URLs originate from the trusted Lark API, not user input.
+ baseClient, err := runtime.Factory.HttpClient()
+ if err != nil {
+ return output.ErrNetwork("failed to get HTTP client: %s", err)
+ }
+ clonedClient := *baseClient
+ clonedClient.Timeout = disableClientTimeout
+ clonedClient.CheckRedirect = func(req *http.Request, via []*http.Request) error {
+ if len(via) >= maxDownloadRedirects {
+ return fmt.Errorf("too many redirects")
+ }
+ if len(via) > 0 {
+ prev := via[len(via)-1]
+ if strings.EqualFold(prev.URL.Scheme, "https") && strings.EqualFold(req.URL.Scheme, "http") {
+ return fmt.Errorf("redirect from https to http is not allowed")
+ }
+ }
+ return validate.ValidateDownloadSourceURL(req.Context(), req.URL.String())
+ }
+ dlClient := &clonedClient
+
+ ticker := time.NewTicker(time.Second / 5) // rate-limit to 5 req/s
+ defer ticker.Stop()
+
+ for i, token := range tokens {
+ if i > 0 {
+ select {
+ case <-ctx.Done():
+ return ctx.Err()
+ case <-ticker.C:
+ }
+ }
+
+ if err := validate.ResourceName(token, "--minute-tokens"); err != nil {
+ results[i] = result{MinuteToken: token, Error: err.Error()}
+ continue
+ }
+ if firstIdx, dup := seen[token]; dup {
+ results[i] = result{MinuteToken: token, Error: fmt.Sprintf("duplicate token, same as index %d", firstIdx)}
+ continue
+ }
+ seen[token] = i
+
+ downloadURL, err := fetchDownloadURL(ctx, runtime, token)
+ if err != nil {
+ results[i] = result{MinuteToken: token, Error: err.Error()}
+ continue
+ }
+
+ if urlOnly {
+ results[i] = result{MinuteToken: token, DownloadURL: downloadURL}
+ continue
+ }
+
+ fmt.Fprintf(errOut, "Downloading media: %s\n", common.MaskToken(token))
+
+ // single token: --output is a file path; batch: --output is a directory
+ opts := downloadOpts{overwrite: overwrite, usedNames: usedNames}
+ if single {
+ opts.outputPath = outputPath
+ } else {
+ opts.outputDir = outputPath
+ }
+
+ dl, err := downloadMediaFile(ctx, dlClient, downloadURL, token, opts)
+ if err != nil {
+ results[i] = result{MinuteToken: token, Error: err.Error()}
+ continue
+ }
+ results[i] = result{MinuteToken: token, SavedPath: dl.savedPath, SizeBytes: dl.sizeBytes}
+ }
+
+ // output
+ if single {
+ r := results[0]
+ if r.Error != "" {
+ return output.ErrAPI(0, r.Error, nil)
+ }
+ if urlOnly {
+ runtime.Out(map[string]interface{}{"download_url": r.DownloadURL}, nil)
+ } else {
+ runtime.Out(map[string]interface{}{"saved_path": r.SavedPath, "size_bytes": r.SizeBytes}, nil)
+ }
+ return nil
+ }
+
+ // batch output
+ successCount := 0
+ for _, r := range results {
+ if r.Error == "" {
+ successCount++
+ }
+ }
+ fmt.Fprintf(errOut, "[minutes +download] done: %d total, %d succeeded, %d failed\n", len(results), successCount, len(results)-successCount)
+
+ runtime.OutFormat(map[string]interface{}{"downloads": results}, &output.Meta{Count: len(results)}, nil)
+ if successCount == 0 && len(results) > 0 {
+ return output.ErrAPI(0, fmt.Sprintf("all %d downloads failed", len(results)), nil)
+ }
+ return nil
+ },
+}
+
+// fetchDownloadURL retrieves the pre-signed download URL for a minute token.
+func fetchDownloadURL(ctx context.Context, runtime *common.RuntimeContext, minuteToken string) (string, error) {
+ data, err := runtime.DoAPIJSON(http.MethodGet,
+ fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/media", validate.EncodePathSegment(minuteToken)),
+ nil, nil)
+ if err != nil {
+ return "", err
+ }
+ downloadURL := common.GetString(data, "download_url")
+ if downloadURL == "" {
+ return "", output.Errorf(output.ExitAPI, "api_error", "API returned empty download_url for %s", minuteToken)
+ }
+ return downloadURL, nil
+}
+
+type downloadResult struct {
+ savedPath string
+ sizeBytes int64
+}
+
+type downloadOpts struct {
+ outputPath string // explicit output file path (single mode only)
+ outputDir string // output directory (batch mode)
+ overwrite bool
+ usedNames map[string]bool // tracks used filenames to deduplicate in batch mode
+}
+
+// downloadMediaFile streams a media file from a pre-signed URL to disk.
+// Filename resolution: opts.outputPath > Content-Disposition filename > Content-Type ext > .media.
+func downloadMediaFile(ctx context.Context, client *http.Client, downloadURL, minuteToken string, opts downloadOpts) (*downloadResult, error) {
+ if err := validate.ValidateDownloadSourceURL(ctx, downloadURL); err != nil {
+ return nil, output.ErrValidation("blocked download URL: %s", err)
+ }
+
+ req, err := http.NewRequestWithContext(ctx, http.MethodGet, downloadURL, nil)
+ if err != nil {
+ return nil, output.ErrNetwork("invalid download URL: %s", err)
+ }
+
+ resp, err := client.Do(req)
+ if err != nil {
+ return nil, output.ErrNetwork("download failed: %s", err)
+ }
+ defer resp.Body.Close()
+
+ if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+ body, _ := io.ReadAll(io.LimitReader(resp.Body, 4096))
+ if len(body) > 0 {
+ return nil, output.ErrNetwork("download failed: HTTP %d: %s", resp.StatusCode, strings.TrimSpace(string(body)))
+ }
+ return nil, output.ErrNetwork("download failed: HTTP %d", resp.StatusCode)
+ }
+
+ // resolve output path
+ outputPath := opts.outputPath
+ if outputPath == "" {
+ filename := resolveFilenameFromResponse(resp, minuteToken)
+ // Deduplicate filenames in batch mode: prefix with token on collision.
+ if opts.usedNames != nil {
+ if opts.usedNames[filename] {
+ filename = minuteToken + "-" + filename
+ }
+ opts.usedNames[filename] = true
+ }
+ outputPath = filepath.Join(opts.outputDir, filename)
+ }
+
+ safePath, err := validate.SafeOutputPath(outputPath)
+ if err != nil {
+ return nil, output.ErrValidation("unsafe output path: %s", err)
+ }
+ if err := common.EnsureWritableFile(safePath, opts.overwrite); err != nil {
+ return nil, err
+ }
+ if err := os.MkdirAll(filepath.Dir(safePath), 0700); err != nil {
+ return nil, output.Errorf(output.ExitInternal, "api_error", "cannot create parent directory: %s", err)
+ }
+
+ sizeBytes, err := validate.AtomicWriteFromReader(safePath, resp.Body, 0600)
+ if err != nil {
+ return nil, output.Errorf(output.ExitInternal, "api_error", "cannot create file: %s", err)
+ }
+ return &downloadResult{savedPath: safePath, sizeBytes: sizeBytes}, nil
+}
+
+// resolveFilenameFromResponse derives the filename from HTTP response headers.
+// Priority: Content-Disposition filename > Content-Type extension > .media.
+func resolveFilenameFromResponse(resp *http.Response, minuteToken string) string {
+ if cd := resp.Header.Get("Content-Disposition"); cd != "" {
+ if _, params, err := mime.ParseMediaType(cd); err == nil {
+ if filename := params["filename"]; filename != "" {
+ return filename
+ }
+ }
+ }
+ if ext := extFromContentType(resp.Header.Get("Content-Type")); ext != "" {
+ return minuteToken + ext
+ }
+ return minuteToken + ".media"
+}
+
+// preferredExt overrides Go's mime.ExtensionsByType which returns alphabetically sorted
+// results (e.g. .m4v before .mp4 for video/mp4).
+var preferredExt = map[string]string{
+ "video/mp4": ".mp4",
+ "audio/mp4": ".m4a",
+ "audio/mpeg": ".mp3",
+}
+
+// newDownloadClient wraps the base HTTP client with SSRF protection
+// (redirect safety + transport-level IP validation). When the base transport
+// is not *http.Transport (e.g. test mocks), it falls back to cloning
+// http.DefaultTransport via NewDownloadHTTPClient.
+// extFromContentType returns a file extension for the given Content-Type, or "" if unknown.
+func extFromContentType(contentType string) string {
+ if contentType == "" {
+ return ""
+ }
+ mediaType, _, err := mime.ParseMediaType(contentType)
+ if err != nil {
+ return ""
+ }
+ if ext, ok := preferredExt[mediaType]; ok {
+ return ext
+ }
+ if exts, err := mime.ExtensionsByType(mediaType); err == nil && len(exts) > 0 {
+ return exts[0]
+ }
+ return ""
+}
diff --git a/shortcuts/minutes/minutes_download_test.go b/shortcuts/minutes/minutes_download_test.go
new file mode 100644
index 00000000..5e6a4738
--- /dev/null
+++ b/shortcuts/minutes/minutes_download_test.go
@@ -0,0 +1,439 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package minutes
+
+import (
+ "bytes"
+ "context"
+ "encoding/json"
+ "net/http"
+ "os"
+ "strings"
+ "sync"
+ "testing"
+
+ "github.com/spf13/cobra"
+
+ "github.com/larksuite/cli/internal/cmdutil"
+ "github.com/larksuite/cli/internal/core"
+ "github.com/larksuite/cli/internal/httpmock"
+ "github.com/larksuite/cli/shortcuts/common"
+)
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+var warmOnce sync.Once
+
+func warmTokenCache(t *testing.T) {
+ t.Helper()
+ warmOnce.Do(func() {
+ f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+ reg.Register(&httpmock.Stub{
+ URL: "/open-apis/auth/v3/tenant_access_token/internal",
+ Body: map[string]interface{}{
+ "code": 0, "msg": "ok",
+ "tenant_access_token": "t-test-token", "expire": 7200,
+ },
+ })
+ reg.Register(&httpmock.Stub{
+ URL: "/open-apis/test/v1/warm",
+ Body: map[string]interface{}{"code": 0, "msg": "ok", "data": map[string]interface{}{}},
+ })
+ s := common.Shortcut{
+ Service: "test",
+ Command: "+warm",
+ AuthTypes: []string{"bot"},
+ Execute: func(_ context.Context, rctx *common.RuntimeContext) error {
+ _, err := rctx.CallAPI("GET", "/open-apis/test/v1/warm", nil, nil)
+ return err
+ },
+ }
+ parent := &cobra.Command{Use: "test"}
+ s.Mount(parent, f)
+ parent.SetArgs([]string{"+warm"})
+ parent.SilenceErrors = true
+ parent.SilenceUsage = true
+ parent.Execute()
+ })
+}
+
+func mountAndRun(t *testing.T, s common.Shortcut, args []string, f *cmdutil.Factory, stdout *bytes.Buffer) error {
+ t.Helper()
+ warmTokenCache(t)
+ parent := &cobra.Command{Use: "minutes"}
+ s.Mount(parent, f)
+ parent.SetArgs(args)
+ parent.SilenceErrors = true
+ parent.SilenceUsage = true
+ if stdout != nil {
+ stdout.Reset()
+ }
+ return parent.Execute()
+}
+
+func defaultConfig() *core.CliConfig {
+ return &core.CliConfig{
+ AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
+ UserOpenId: "ou_testuser",
+ }
+}
+
+func mediaStub(token, downloadURL string) *httpmock.Stub {
+ return &httpmock.Stub{
+ Method: "GET",
+ URL: "/open-apis/minutes/v1/minutes/" + token + "/media",
+ Body: map[string]interface{}{
+ "code": 0, "msg": "ok",
+ "data": map[string]interface{}{"download_url": downloadURL},
+ },
+ }
+}
+
+func downloadStub(url string, body []byte, contentType string) *httpmock.Stub {
+ return &httpmock.Stub{
+ URL: url,
+ RawBody: body,
+ Headers: http.Header{"Content-Type": []string{contentType}},
+ }
+}
+
+// chdir changes the working directory and restores it when the test finishes.
+func chdir(t *testing.T, dir string) {
+ t.Helper()
+ orig, err := os.Getwd()
+ if err != nil {
+ t.Fatalf("failed to get cwd: %v", err)
+ }
+ if err := os.Chdir(dir); err != nil {
+ t.Fatalf("failed to chdir to %s: %v", dir, err)
+ }
+ t.Cleanup(func() { os.Chdir(orig) })
+}
+
+// ---------------------------------------------------------------------------
+// Unit tests: resolveOutputFromResponse
+// ---------------------------------------------------------------------------
+
+func TestResolveFilenameFromResponse_ContentDisposition(t *testing.T) {
+ resp := &http.Response{
+ Header: http.Header{
+ "Content-Disposition": []string{`attachment; filename="meeting_recording.mp4"`},
+ "Content-Type": []string{"video/mp4"},
+ },
+ }
+ got := resolveFilenameFromResponse(resp, "tok001")
+ if got != "meeting_recording.mp4" {
+ t.Errorf("expected Content-Disposition filename, got %q", got)
+ }
+}
+
+func TestResolveFilenameFromResponse_ContentType(t *testing.T) {
+ resp := &http.Response{
+ Header: http.Header{
+ "Content-Type": []string{"video/mp4"},
+ },
+ }
+ got := resolveFilenameFromResponse(resp, "tok001")
+ if !strings.HasPrefix(got, "tok001") {
+ t.Errorf("expected token prefix, got %q", got)
+ }
+ if ext := got[len("tok001"):]; ext == "" {
+ t.Errorf("expected extension after token, got %q", got)
+ }
+}
+
+func TestResolveFilenameFromResponse_Fallback(t *testing.T) {
+ resp := &http.Response{Header: http.Header{}}
+ got := resolveFilenameFromResponse(resp, "tok001")
+ if got != "tok001.media" {
+ t.Errorf("expected fallback %q, got %q", "tok001.media", got)
+ }
+}
+
+func TestResolveFilenameFromResponse_InvalidContentDisposition(t *testing.T) {
+ resp := &http.Response{
+ Header: http.Header{
+ "Content-Disposition": []string{"invalid;;;"},
+ "Content-Type": []string{"audio/mpeg"},
+ },
+ }
+ got := resolveFilenameFromResponse(resp, "tok001")
+ if !strings.HasPrefix(got, "tok001") {
+ t.Errorf("expected token prefix from Content-Type fallback, got %q", got)
+ }
+}
+
+func TestResolveFilenameFromResponse_EmptyDispositionFilename(t *testing.T) {
+ resp := &http.Response{
+ Header: http.Header{
+ "Content-Disposition": []string{"attachment"},
+ "Content-Type": []string{"video/mp4"},
+ },
+ }
+ got := resolveFilenameFromResponse(resp, "tok001")
+ if got == "" {
+ t.Error("expected non-empty filename")
+ }
+ if !strings.HasPrefix(got, "tok001") {
+ t.Errorf("expected token prefix, got %q", got)
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Validation tests
+// ---------------------------------------------------------------------------
+
+func TestDownload_Validation_NoFlags(t *testing.T) {
+ f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+ err := mountAndRun(t, MinutesDownload, []string{"+download", "--as", "user"}, f, nil)
+ if err == nil {
+ t.Fatal("expected validation error for no flags")
+ }
+}
+
+func TestDownload_Validation_InvalidToken(t *testing.T) {
+ f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+ err := mountAndRun(t, MinutesDownload, []string{
+ "+download", "--minute-tokens", "obcn***invalid", "--as", "user",
+ }, f, nil)
+ if err == nil {
+ t.Fatal("expected validation error for invalid token")
+ }
+ if !strings.Contains(err.Error(), "invalid minute token") {
+ t.Errorf("expected 'invalid minute token' error, got: %v", err)
+ }
+}
+
+func TestDownload_Validation_OutputWithBatch(t *testing.T) {
+ f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+ err := mountAndRun(t, MinutesDownload, []string{
+ "+download", "--minute-tokens", "t1,t2", "--output", "file.mp4", "--as", "user",
+ }, f, nil)
+ if err == nil {
+ t.Fatal("expected validation error for --output with --minute-tokens")
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Integration tests: single mode
+// ---------------------------------------------------------------------------
+
+func TestDownload_DryRun(t *testing.T) {
+ f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+ err := mountAndRun(t, MinutesDownload, []string{
+ "+download", "--minute-tokens", "tok001", "--dry-run", "--as", "user",
+ }, f, stdout)
+ if err != nil {
+ t.Fatalf("unexpected error: %v", err)
+ }
+ out := stdout.String()
+ if !strings.Contains(out, "media") {
+ t.Errorf("dry-run should show media API path, got: %s", out)
+ }
+ if !strings.Contains(out, "tok001") {
+ t.Errorf("dry-run should show minute_token, got: %s", out)
+ }
+}
+
+func TestDownload_UrlOnly(t *testing.T) {
+ f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+ reg.Register(mediaStub("tok001", "https://example.com/presigned/download"))
+
+ err := mountAndRun(t, MinutesDownload, []string{
+ "+download", "--minute-tokens", "tok001", "--url-only", "--as", "bot",
+ }, f, stdout)
+ if err != nil {
+ t.Fatalf("unexpected error: %v", err)
+ }
+ if !strings.Contains(stdout.String(), "https://example.com/presigned/download") {
+ t.Errorf("url-only should output download URL, got: %s", stdout.String())
+ }
+}
+
+func TestDownload_FullDownload(t *testing.T) {
+ chdir(t, t.TempDir())
+
+ f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+ reg.Register(mediaStub("tok001", "https://example.com/presigned/download"))
+ reg.Register(downloadStub("example.com/presigned/download", []byte("fake-video-content"), "video/mp4"))
+
+ err := mountAndRun(t, MinutesDownload, []string{
+ "+download", "--minute-tokens", "tok001", "--output", "output.mp4", "--as", "bot",
+ }, f, stdout)
+ if err != nil {
+ t.Fatalf("unexpected error: %v", err)
+ }
+
+ data, err := os.ReadFile("output.mp4")
+ if err != nil {
+ t.Fatalf("failed to read output file: %v", err)
+ }
+ if string(data) != "fake-video-content" {
+ t.Errorf("file content = %q, want %q", string(data), "fake-video-content")
+ }
+}
+
+func TestDownload_OverwriteProtection(t *testing.T) {
+ chdir(t, t.TempDir())
+ if err := os.WriteFile("existing.mp4", []byte("old"), 0644); err != nil {
+ t.Fatalf("setup failed: %v", err)
+ }
+
+ f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+ reg.Register(mediaStub("tok001", "https://example.com/presigned/download"))
+ reg.Register(downloadStub("example.com/presigned/download", []byte("new-content"), "video/mp4"))
+
+ err := mountAndRun(t, MinutesDownload, []string{
+ "+download", "--minute-tokens", "tok001", "--output", "existing.mp4", "--as", "bot",
+ }, f, nil)
+ if err == nil {
+ t.Fatal("expected error for existing file without --overwrite")
+ }
+ if !strings.Contains(err.Error(), "exists") {
+ t.Errorf("error should mention file exists, got: %v", err)
+ }
+
+ data, _ := os.ReadFile("existing.mp4")
+ if string(data) != "old" {
+ t.Errorf("original file should be preserved, got %q", string(data))
+ }
+}
+
+func TestDownload_HttpError(t *testing.T) {
+ chdir(t, t.TempDir())
+
+ f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+ reg.Register(mediaStub("tok001", "https://example.com/presigned/download"))
+ reg.Register(&httpmock.Stub{
+ URL: "example.com/presigned/download",
+ Status: 403,
+ RawBody: []byte("Forbidden"),
+ })
+
+ err := mountAndRun(t, MinutesDownload, []string{
+ "+download", "--minute-tokens", "tok001", "--output", "output.mp4", "--as", "bot",
+ }, f, nil)
+ if err == nil {
+ t.Fatal("expected error for HTTP 403")
+ }
+ if !strings.Contains(err.Error(), "403") {
+ t.Errorf("error should contain status code, got: %v", err)
+ }
+}
+
+// ---------------------------------------------------------------------------
+// Integration tests: batch mode
+// ---------------------------------------------------------------------------
+
+func TestDownload_Batch_UrlOnly(t *testing.T) {
+ f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+ reg.Register(mediaStub("tok001", "https://example.com/download/1"))
+ reg.Register(mediaStub("tok002", "https://example.com/download/2"))
+
+ err := mountAndRun(t, MinutesDownload, []string{
+ "+download", "--minute-tokens", "tok001,tok002", "--url-only", "--as", "bot",
+ }, f, stdout)
+ if err != nil {
+ t.Fatalf("unexpected error: %v", err)
+ }
+ out := stdout.String()
+ if !strings.Contains(out, "download/1") || !strings.Contains(out, "download/2") {
+ t.Errorf("batch url-only should show both URLs, got: %s", out)
+ }
+}
+
+func TestDownload_Batch_Download(t *testing.T) {
+ chdir(t, t.TempDir())
+
+ f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+ reg.Register(mediaStub("tok001", "https://example.com/download/1"))
+ reg.Register(mediaStub("tok002", "https://example.com/download/2"))
+ reg.Register(downloadStub("example.com/download/1", []byte("content-1"), "video/mp4"))
+ reg.Register(downloadStub("example.com/download/2", []byte("content-2"), "video/mp4"))
+
+ err := mountAndRun(t, MinutesDownload, []string{
+ "+download", "--minute-tokens", "tok001,tok002", "--as", "bot",
+ }, f, stdout)
+ if err != nil {
+ t.Fatalf("unexpected error: %v", err)
+ }
+
+ // verify output structure
+ var result struct {
+ Data struct {
+ Downloads []struct {
+ MinuteToken string `json:"minute_token"`
+ SavedPath string `json:"saved_path"`
+ } `json:"downloads"`
+ } `json:"data"`
+ }
+ if err := json.Unmarshal(stdout.Bytes(), &result); err != nil {
+ t.Fatalf("failed to parse output: %v\nraw: %s", err, stdout.String())
+ }
+ if len(result.Data.Downloads) != 2 {
+ t.Fatalf("expected 2 downloads, got %d", len(result.Data.Downloads))
+ }
+}
+
+func TestDownload_Batch_PartialFailure(t *testing.T) {
+ chdir(t, t.TempDir())
+
+ f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+ reg.Register(mediaStub("tok001", "https://example.com/download/1"))
+ reg.Register(downloadStub("example.com/download/1", []byte("content-1"), "video/mp4"))
+ reg.Register(&httpmock.Stub{
+ Method: "GET",
+ URL: "/open-apis/minutes/v1/minutes/tok002/media",
+ Status: 200,
+ Body: map[string]interface{}{
+ "code": 99999, "msg": "permission denied",
+ "data": map[string]interface{}{},
+ },
+ })
+
+ err := mountAndRun(t, MinutesDownload, []string{
+ "+download", "--minute-tokens", "tok001,tok002", "--as", "bot",
+ }, f, stdout)
+ // partial failure should not cause an overall error
+ if err != nil {
+ t.Fatalf("partial failure should not return error, got: %v", err)
+ }
+ out := stdout.String()
+ if !strings.Contains(out, "tok001") || !strings.Contains(out, "tok002") {
+ t.Errorf("output should contain both tokens, got: %s", out)
+ }
+}
+
+func TestDownload_Batch_DuplicateToken(t *testing.T) {
+ f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+ // register media stub only once — dedup means only one API call
+ reg.Register(mediaStub("tok001", "https://example.com/download/1"))
+
+ err := mountAndRun(t, MinutesDownload, []string{
+ "+download", "--minute-tokens", "tok001,tok001", "--url-only", "--as", "bot",
+ }, f, stdout)
+ if err != nil {
+ t.Fatalf("unexpected error: %v", err)
+ }
+ out := stdout.String()
+ if !strings.Contains(out, "duplicate") {
+ t.Errorf("second token should report duplicate, got: %s", out)
+ }
+}
+
+func TestDownload_Batch_DryRun(t *testing.T) {
+ f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+ err := mountAndRun(t, MinutesDownload, []string{
+ "+download", "--minute-tokens", "tok001,tok002", "--dry-run", "--as", "user",
+ }, f, stdout)
+ if err != nil {
+ t.Fatalf("unexpected error: %v", err)
+ }
+ out := stdout.String()
+ if !strings.Contains(out, "tok001") || !strings.Contains(out, "tok002") {
+ t.Errorf("dry-run should show tokens, got: %s", out)
+ }
+}
diff --git a/shortcuts/minutes/shortcuts.go b/shortcuts/minutes/shortcuts.go
new file mode 100644
index 00000000..9c1431f2
--- /dev/null
+++ b/shortcuts/minutes/shortcuts.go
@@ -0,0 +1,13 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package minutes
+
+import "github.com/larksuite/cli/shortcuts/common"
+
+// Shortcuts returns all minutes shortcuts.
+func Shortcuts() []common.Shortcut {
+ return []common.Shortcut{
+ MinutesDownload,
+ }
+}
diff --git a/shortcuts/register.go b/shortcuts/register.go
index 30fd506d..3f8048fb 100644
--- a/shortcuts/register.go
+++ b/shortcuts/register.go
@@ -17,6 +17,7 @@ import (
"github.com/larksuite/cli/shortcuts/event"
"github.com/larksuite/cli/shortcuts/im"
"github.com/larksuite/cli/shortcuts/mail"
+ "github.com/larksuite/cli/shortcuts/minutes"
"github.com/larksuite/cli/shortcuts/sheets"
"github.com/larksuite/cli/shortcuts/task"
"github.com/larksuite/cli/shortcuts/vc"
@@ -36,6 +37,7 @@ func init() {
allShortcuts = append(allShortcuts, base.Shortcuts()...)
allShortcuts = append(allShortcuts, event.Shortcuts()...)
allShortcuts = append(allShortcuts, mail.Shortcuts()...)
+ allShortcuts = append(allShortcuts, minutes.Shortcuts()...)
allShortcuts = append(allShortcuts, task.Shortcuts()...)
allShortcuts = append(allShortcuts, vc.Shortcuts()...)
allShortcuts = append(allShortcuts, whiteboard.Shortcuts()...)
diff --git a/shortcuts/register_test.go b/shortcuts/register_test.go
index 48b72c39..2d169617 100644
--- a/shortcuts/register_test.go
+++ b/shortcuts/register_test.go
@@ -4,6 +4,10 @@
package shortcuts
import (
+ "encoding/json"
+ "os"
+ "path/filepath"
+ "strings"
"testing"
"github.com/larksuite/cli/internal/cmdutil"
@@ -88,3 +92,39 @@ func TestRegisterShortcutsReusesExistingServiceCommand(t *testing.T) {
t.Fatal("base workspace shortcut not mounted on existing service command")
}
}
+
+func TestGenerateShortcutsJSON(t *testing.T) {
+ output := os.Getenv("SHORTCUTS_OUTPUT")
+ if output == "" {
+ t.Skip("set SHORTCUTS_OUTPUT env to generate shortcuts.json")
+ }
+
+ shortcuts := AllShortcuts()
+
+ type entry struct {
+ Verb string `json:"verb"`
+ Description string `json:"description"`
+ Scopes []string `json:"scopes"`
+ }
+ grouped := make(map[string][]entry)
+ for _, s := range shortcuts {
+ verb := strings.TrimPrefix(s.Command, "+")
+ grouped[s.Service] = append(grouped[s.Service], entry{
+ Verb: verb,
+ Description: s.Description,
+ Scopes: s.ScopesForIdentity("user"),
+ })
+ }
+
+ data, err := json.MarshalIndent(grouped, "", " ")
+ if err != nil {
+ t.Fatalf("marshal shortcuts: %v", err)
+ }
+ if err := os.MkdirAll(filepath.Dir(output), 0o755); err != nil {
+ t.Fatalf("mkdir: %v", err)
+ }
+ if err := os.WriteFile(output, data, 0o644); err != nil {
+ t.Fatalf("write file: %v", err)
+ }
+ t.Logf("wrote %d bytes to %s", len(data), output)
+}
diff --git a/shortcuts/sheets/helpers.go b/shortcuts/sheets/helpers.go
index 8604cbee..ba1ca642 100644
--- a/shortcuts/sheets/helpers.go
+++ b/shortcuts/sheets/helpers.go
@@ -23,6 +23,8 @@ var (
cellRefPattern = regexp.MustCompile(`^([A-Za-z]+)([1-9][0-9]*)$`)
)
+var sheetRangeSeparatorReplacer = strings.NewReplacer(`\！`, "!", `\!`, "!", "！", "!")
+
// getFirstSheetID queries the spreadsheet and returns the first sheet's ID.
func getFirstSheetID(runtime *common.RuntimeContext, spreadsheetToken string) (string, error) {
data, err := runtime.CallAPI("GET", fmt.Sprintf("/open-apis/sheets/v3/spreadsheets/%s/sheets/query", validate.EncodePathSegment(spreadsheetToken)), nil, nil)
@@ -56,7 +58,7 @@ func extractSpreadsheetToken(input string) string {
}
func normalizeSheetRange(sheetID, input string) string {
- input = strings.TrimSpace(input)
+ input = normalizeSheetRangeSeparators(input)
if input == "" || strings.Contains(input, "!") || sheetID == "" {
return input
}
@@ -80,7 +82,7 @@ func normalizePointRange(sheetID, input string) string {
func normalizeWriteRange(sheetID, input string, values interface{}) string {
rows, cols := matrixDimensions(values)
- input = strings.TrimSpace(input)
+ input = normalizeSheetRangeSeparators(input)
if input == "" {
return buildRectRange(sheetID, "A1", rows, cols)
}
@@ -97,7 +99,7 @@ func normalizeWriteRange(sheetID, input string, values interface{}) string {
}
func validateSheetRangeInput(sheetID, input string) error {
- input = strings.TrimSpace(input)
+ input = normalizeSheetRangeSeparators(input)
if input == "" || strings.Contains(input, "!") || sheetID != "" {
return nil
}
@@ -108,7 +110,7 @@ func validateSheetRangeInput(sheetID, input string) error {
}
func looksLikeRelativeRange(input string) bool {
- input = strings.TrimSpace(input)
+ input = normalizeSheetRangeSeparators(input)
if input == "" {
return false
}
@@ -120,13 +122,21 @@ func looksLikeRelativeRange(input string) bool {
}
func splitSheetRange(input string) (sheetID, subRange string, ok bool) {
- parts := strings.SplitN(strings.TrimSpace(input), "!", 2)
+ parts := strings.SplitN(normalizeSheetRangeSeparators(input), "!", 2)
if len(parts) != 2 || parts[0] == "" || parts[1] == "" {
return "", "", false
}
return parts[0], parts[1], true
}
+func normalizeSheetRangeSeparators(input string) string {
+ input = strings.TrimSpace(input)
+ if input == "" {
+ return input
+ }
+ return sheetRangeSeparatorReplacer.Replace(input)
+}
+
func buildRectRange(sheetID, anchor string, rows, cols int) string {
if sheetID == "" {
return ""
diff --git a/shortcuts/sheets/sheet_ranges_test.go b/shortcuts/sheets/sheet_ranges_test.go
new file mode 100644
index 00000000..b5eb2b6e
--- /dev/null
+++ b/shortcuts/sheets/sheet_ranges_test.go
@@ -0,0 +1,148 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package sheets
+
+import (
+ "context"
+ "encoding/json"
+ "strings"
+ "testing"
+
+ "github.com/larksuite/cli/shortcuts/common"
+ "github.com/spf13/cobra"
+)
+
+func mustMarshalSheetsDryRun(t *testing.T, v interface{}) string {
+ t.Helper()
+
+ b, err := json.Marshal(v)
+ if err != nil {
+ t.Fatalf("json.Marshal() error = %v", err)
+ }
+ return string(b)
+}
+
+func newSheetsTestRuntime(t *testing.T, stringFlags map[string]string, boolFlags map[string]bool) *common.RuntimeContext {
+ t.Helper()
+
+ cmd := &cobra.Command{Use: "test"}
+ for name := range stringFlags {
+ cmd.Flags().String(name, "", "")
+ }
+ for name := range boolFlags {
+ cmd.Flags().Bool(name, false, "")
+ }
+ if err := cmd.ParseFlags(nil); err != nil {
+ t.Fatalf("ParseFlags() error = %v", err)
+ }
+ for name, value := range stringFlags {
+ if err := cmd.Flags().Set(name, value); err != nil {
+ t.Fatalf("Flags().Set(%q) error = %v", name, err)
+ }
+ }
+ for name, value := range boolFlags {
+ if err := cmd.Flags().Set(name, map[bool]string{true: "true", false: "false"}[value]); err != nil {
+ t.Fatalf("Flags().Set(%q) error = %v", name, err)
+ }
+ }
+ return &common.RuntimeContext{Cmd: cmd}
+}
+
+func TestNormalizeSheetRangeSeparators(t *testing.T) {
+ t.Parallel()
+
+ tests := []struct {
+ name string
+ input string
+ want string
+ }{
+ {name: "standard", input: "sheet_123!A1:B2", want: "sheet_123!A1:B2"},
+ {name: "escaped ascii", input: `sheet_123\!A1:B2`, want: "sheet_123!A1:B2"},
+ {name: "fullwidth", input: "sheet_123！A1:B2", want: "sheet_123!A1:B2"},
+ {name: "escaped fullwidth", input: `sheet_123\！A1:B2`, want: "sheet_123!A1:B2"},
+ }
+
+ for _, tt := range tests {
+ t.Run(tt.name, func(t *testing.T) {
+ t.Parallel()
+ if got := normalizeSheetRangeSeparators(tt.input); got != tt.want {
+ t.Fatalf("normalizeSheetRangeSeparators(%q) = %q, want %q", tt.input, got, tt.want)
+ }
+ })
+ }
+}
+
+func TestValidateSheetRangeInputAcceptsEscapedSeparator(t *testing.T) {
+ t.Parallel()
+
+ if err := validateSheetRangeInput("", `sheet_123\！A1:B2`); err != nil {
+ t.Fatalf("validateSheetRangeInput() error = %v, want nil", err)
+ }
+}
+
+func TestSheetReadDryRunNormalizesEscapedSeparator(t *testing.T) {
+ t.Parallel()
+
+ runtime := newSheetsTestRuntime(t, map[string]string{
+ "spreadsheet-token": "sht_test",
+ "range": `sheet_123\！A1`,
+ "sheet-id": "",
+ }, nil)
+
+ got := mustMarshalSheetsDryRun(t, SheetRead.DryRun(context.Background(), runtime))
+ if !strings.Contains(got, `"range":"sheet_123!A1:A1"`) {
+ t.Fatalf("SheetRead.DryRun() = %s, want normalized escaped separator", got)
+ }
+}
+
+func TestSheetWriteDryRunNormalizesEscapedSeparator(t *testing.T) {
+ t.Parallel()
+
+ runtime := newSheetsTestRuntime(t, map[string]string{
+ "spreadsheet-token": "sht_test",
+ "range": `sheet_123\！A1:B2`,
+ "values": `[[1,2],[3,4]]`,
+ }, nil)
+
+ got := mustMarshalSheetsDryRun(t, SheetWrite.DryRun(context.Background(), runtime))
+ if !strings.Contains(got, `"range":"sheet_123!A1:B2"`) {
+ t.Fatalf("SheetWrite.DryRun() = %s, want normalized escaped separator", got)
+ }
+}
+
+func TestSheetAppendDryRunNormalizesEscapedSeparator(t *testing.T) {
+ t.Parallel()
+
+ runtime := newSheetsTestRuntime(t, map[string]string{
+ "spreadsheet-token": "sht_test",
+ "range": `sheet_123\！A1:B2`,
+ "values": `[["foo","bar"]]`,
+ }, nil)
+
+ got := mustMarshalSheetsDryRun(t, SheetAppend.DryRun(context.Background(), runtime))
+ if !strings.Contains(got, `"range":"sheet_123!A1:B2"`) {
+ t.Fatalf("SheetAppend.DryRun() = %s, want normalized escaped separator", got)
+ }
+}
+
+func TestSheetFindDryRunNormalizesEscapedSeparator(t *testing.T) {
+ t.Parallel()
+
+ runtime := newSheetsTestRuntime(t, map[string]string{
+ "spreadsheet-token": "sht_test",
+ "sheet-id": "sheet_123",
+ "find": "target",
+ "range": `sheet_123\！A1:B2`,
+ }, map[string]bool{
+ "ignore-case": false,
+ "match-entire-cell": false,
+ "search-by-regex": false,
+ "include-formulas": false,
+ })
+
+ got := mustMarshalSheetsDryRun(t, SheetFind.DryRun(context.Background(), runtime))
+ if !strings.Contains(got, `"range":"sheet_123!A1:B2"`) {
+ t.Fatalf("SheetFind.DryRun() = %s, want normalized escaped separator", got)
+ }
+}
diff --git a/shortcuts/vc/artifact-Empty Artifacts-tok003/transcript.txt b/shortcuts/vc/artifact-Empty Artifacts-tok003/transcript.txt
deleted file mode 100644
index 97dd8118..00000000
--- a/shortcuts/vc/artifact-Empty Artifacts-tok003/transcript.txt
+++ /dev/null
@@ -1 +0,0 @@
-{"code":0,"data":{},"msg":"ok"}
\ No newline at end of file
diff --git a/shortcuts/vc/artifact-No Note Meeting-tok002/transcript.txt b/shortcuts/vc/artifact-No Note Meeting-tok002/transcript.txt
deleted file mode 100644
index 97dd8118..00000000
--- a/shortcuts/vc/artifact-No Note Meeting-tok002/transcript.txt
+++ /dev/null
@@ -1 +0,0 @@
-{"code":0,"data":{},"msg":"ok"}
\ No newline at end of file
diff --git a/shortcuts/vc/artifact-Test Minutes-tok001/transcript.txt b/shortcuts/vc/artifact-Test Minutes-tok001/transcript.txt
deleted file mode 100644
index 97dd8118..00000000
--- a/shortcuts/vc/artifact-Test Minutes-tok001/transcript.txt
+++ /dev/null
@@ -1 +0,0 @@
-{"code":0,"data":{},"msg":"ok"}
\ No newline at end of file
diff --git a/skills/lark-base/references/formula-field-guide.md b/skills/lark-base/references/formula-field-guide.md
index bf673676..6ffe315a 100644
--- a/skills/lark-base/references/formula-field-guide.md
+++ b/skills/lark-base/references/formula-field-guide.md
@@ -1,4 +1,4 @@
-# Bitable Formula Writing Guide
+# Base Formula Writing Guide
## Mandatory Read Acknowledgement
@@ -121,7 +121,7 @@ When using comparison operators (`>`, `>=`, `<`, `<=`, `=`, `!=`), **both sides
## Section 4: Operators
-Bitable formulas **only allow** the following operators. `like`, `in`, `<>`, `**`, `^` etc. are prohibited.
+Base formulas **only allow** the following operators. `like`, `in`, `<>`, `**`, `^` etc. are prohibited.
| Category | Operators | Description |
| ------------- | -------------------------- | -------------------------------------------------------------------------- |
diff --git a/skills/lark-base/references/lark-base-field-create.md b/skills/lark-base/references/lark-base-field-create.md
index 75e6b0f9..398b0732 100644
--- a/skills/lark-base/references/lark-base-field-create.md
+++ b/skills/lark-base/references/lark-base-field-create.md
@@ -24,6 +24,11 @@ lark-cli base +field-create \
--base-token app_xxx \
--table-id tbl_xxx \
--json '{"name":"状态","type":"select","multiple":false,"options":[{"name":"Todo","hue":"Blue","lightness":"Lighter"},{"name":"Done","hue":"Green","lightness":"Light"}]}'
+
+lark-cli base +field-create \
+ --base-token app_xxx \
+ --table-id tbl_xxx \
+ --json '{"name":"负责人","type":"user","multiple":false,"description":"用于标记记录的直接负责人；协作约定可参考[团队字段约定](https://example.com/field-spec)"}'
```
## 参数
@@ -33,7 +38,6 @@ lark-cli base +field-create \
| `--base-token ` | 是 | Base Token |
| `--table-id ` | 是 | 表 ID 或表名 |
| `--json ` | 是 | 字段属性 JSON 对象 |
-
## API 入参详情
**HTTP 方法和路径：**
@@ -46,6 +50,7 @@ POST /open-apis/base/v3/bases/:base_token/tables/:table_id/fields
- `--json` 必须是 **JSON 对象**，顶层直接传字段定义，不要再套一层。
- 顶层最少包含：`name`、`type`。
+- 如需字段说明，直接传 `description`；支持纯文本，也支持 Markdown 链接，如 `协作约定可参考[团队字段约定](https://example.com/field-spec)`。
- `type` 不同，必填子字段不同：
- `select`：用 `multiple` + `options`（`options` 里只传 `name/hue/lightness`，不要传 `id`）。
- `link`：必须有 `link_table`，可选 `bidirectional`、`bidirectional_link_field_name`。
@@ -66,6 +71,17 @@ POST /open-apis/base/v3/bases/:base_token/tables/:table_id/fields
}
```
+**字段说明示例**
+
+```json
+{
+ "name": "负责人",
+ "type": "user",
+ "multiple": false,
+ "description": "用于标记记录的直接负责人；协作约定可参考[团队字段约定](https://example.com/field-spec)"
+}
+```
+
## 返回重点
- 返回 `field` 和 `created: true`。
@@ -78,7 +94,7 @@ POST /open-apis/base/v3/bases/:base_token/tables/:table_id/fields
## 坑点
- ⚠️ 这是写入操作，执行前必须确认。
-- ⚠️ 当 `--json.type` 是 `formula` 或 `lookup` 时，先读对应 guide，再创建。
+- ⚠️ 当 `type` 是 `formula` 或 `lookup` 时，先读对应 guide，再创建。
## 参考
diff --git a/skills/lark-base/references/lark-base-field-update.md b/skills/lark-base/references/lark-base-field-update.md
index f010738b..b4c3d0f1 100644
--- a/skills/lark-base/references/lark-base-field-update.md
+++ b/skills/lark-base/references/lark-base-field-update.md
@@ -12,6 +12,12 @@ lark-cli base +field-update \
--table-id tbl_xxx \
--field-id fld_xxx \
--json '{"name":"状态","type":"select","multiple":false,"options":[{"name":"Todo","hue":"Blue","lightness":"Lighter"},{"name":"Doing","hue":"Orange","lightness":"Light"},{"name":"Done","hue":"Green","lightness":"Light"}]}'
+
+lark-cli base +field-update \
+ --base-token app_xxx \
+ --table-id tbl_xxx \
+ --field-id fld_xxx \
+ --json '{"name":"负责人","type":"user","multiple":false,"description":"用于标记记录的直接负责人；协作约定可参考[团队字段约定](https://example.com/field-spec)"}'
```
## 参数
@@ -22,7 +28,6 @@ lark-cli base +field-update \
| `--table-id ` | 是 | 表 ID 或表名 |
| `--field-id ` | 是 | 字段 ID 或字段名 |
| `--json ` | 是 | 字段属性 JSON 对象 |
-
## API 入参详情
**HTTP 方法和路径：**
@@ -35,6 +40,7 @@ PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id
- `--json` 必须是 **JSON 对象**，顶层直接传字段定义。
- 更新语义是 `PUT`（全量字段配置更新），不要只传零散片段；至少显式包含 `name`、`type`，并补齐该类型所需关键配置。
+- 如需字段说明，直接传 `description`；支持纯文本，也支持 Markdown 链接，如 `协作约定可参考[团队字段约定](https://example.com/field-spec)`。
- `select` 更新时：`options` 仍按对象数组传，避免混入无效字段。
- `link` 更新限制：
- 不能把非 `link` 字段改成 `link`，也不能把 `link` 改成非 `link`。
@@ -55,6 +61,17 @@ PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id
}
```
+**字段说明示例**
+
+```json
+{
+ "name": "负责人",
+ "type": "user",
+ "multiple": false,
+ "description": "用于标记记录的直接负责人；协作约定可参考[团队字段约定](https://example.com/field-spec)"
+}
+```
+
## 返回重点
- 返回 `field` 和 `updated: true`。
@@ -69,7 +86,7 @@ PUT /open-apis/base/v3/bases/:base_token/tables/:table_id/fields/:field_id
- ⚠️ 这是全量字段属性更新语义，不是 patch。
- ⚠️ 这是写入操作，执行前必须确认。
-- ⚠️ 当 `--json.type` 是 `formula` 或 `lookup` 时，先阅读对应指南再执行。
+- ⚠️ 当 `type` 是 `formula` 或 `lookup` 时，先阅读对应指南再执行。
## 参考
diff --git a/skills/lark-base/references/lark-base-shortcut-field-properties.md b/skills/lark-base/references/lark-base-shortcut-field-properties.md
index 8b98ab01..09fbfde5 100644
--- a/skills/lark-base/references/lark-base-shortcut-field-properties.md
+++ b/skills/lark-base/references/lark-base-shortcut-field-properties.md
@@ -8,15 +8,24 @@
- `--json` 必须是 JSON 对象。
- 顶层统一使用：`type` + `name` + 类型特有字段。
+- 如需字段说明，直接传 `description`；支持纯文本，也支持 Markdown 链接。
- 不要使用旧结构：`field_name`、`property`、`ui_type`、数字枚举 `type`。
- `+field-update` 是 `PUT` 语义，建议先 `+field-get` 再全量提交目标字段配置。
- `type=formula` 或 `type=lookup` 创建时，必须先读对应 guide。
+```json
+{
+ "type": "text",
+ "name": "需求背景",
+ "description": "记录需求背景与已知约束；填写口径可参考[说明模板](https://example.com/spec)"
+}
+```
+
## 2. 各类型格式与示例
### 2.1 text
-**要求**：`name` 必填；`style.type` 可选，默认 `plain`。
+**要求**：`name` 必填；可选传 `description`；`style.type` 可选，默认 `plain`。
```json
{
@@ -36,6 +45,7 @@
"properties": {
"type": { "type": "string", "const": "text", "description": "Text field type" },
"name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" },
+ "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" },
"style": {
"type": "object",
"properties": { "type": { "type": "string", "enum": ["plain", "phone", "url", "email", "barcode"], "description": "Text style type" } },
@@ -101,6 +111,7 @@
"properties": {
"type": { "type": "string", "const": "number", "description": "Number field type" },
"name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" },
+ "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" },
"style": {
"anyOf": [
{
@@ -197,6 +208,7 @@
"properties": {
"type": { "type": "string", "const": "select", "description": "Select field type" },
"name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" },
+ "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" },
"multiple": { "type": "boolean", "default": false, "description": "Allow multiple" },
"options": {
"type": "array",
@@ -250,6 +262,7 @@
"properties": {
"type": { "type": "string", "const": "datetime", "description": "Date time type" },
"name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" },
+ "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" },
"style": {
"type": "object",
"properties": { "format": { "type": "string", "enum": ["yyyy/MM/dd", "yyyy/MM/dd HH:mm", "yyyy/MM/dd HH:mm Z", "yyyy-MM-dd", "yyyy-MM-dd HH:mm", "yyyy-MM-dd HH:mm Z", "MM-dd", "MM/dd/yyyy", "dd/MM/yyyy"], "default": "yyyy/MM/dd", "description": "Date format" } },
@@ -273,6 +286,7 @@
"properties": {
"type": { "type": "string", "const": "created_at", "description": "Created time type" },
"name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" },
+ "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" },
"style": {
"type": "object",
"properties": { "format": { "type": "string", "enum": ["yyyy/MM/dd", "yyyy/MM/dd HH:mm", "yyyy/MM/dd HH:mm Z", "yyyy-MM-dd", "yyyy-MM-dd HH:mm", "yyyy-MM-dd HH:mm Z", "MM-dd", "MM/dd/yyyy", "dd/MM/yyyy"], "default": "yyyy/MM/dd", "description": "Date format" } },
@@ -296,6 +310,7 @@
"properties": {
"type": { "type": "string", "const": "updated_at", "description": "Modified time type" },
"name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" },
+ "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" },
"style": {
"type": "object",
"properties": { "format": { "type": "string", "enum": ["yyyy/MM/dd", "yyyy/MM/dd HH:mm", "yyyy/MM/dd HH:mm Z", "yyyy-MM-dd", "yyyy-MM-dd HH:mm", "yyyy-MM-dd HH:mm Z", "MM-dd", "MM/dd/yyyy", "dd/MM/yyyy"], "default": "yyyy/MM/dd", "description": "Date format" } },
@@ -330,7 +345,7 @@
```json
{
"type": "object",
- "properties": { "type": { "type": "string", "const": "user", "description": "User field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, "multiple": { "type": "boolean", "default": true, "description": "Allow multiple" } },
+ "properties": { "type": { "type": "string", "const": "user", "description": "User field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" }, "multiple": { "type": "boolean", "default": true, "description": "Allow multiple" } },
"required": ["type", "name"],
"additionalProperties": false,
"description": "User field",
@@ -343,7 +358,7 @@
```json
{
"type": "object",
- "properties": { "type": { "type": "string", "const": "created_by", "description": "Created by type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" } },
+ "properties": { "type": { "type": "string", "const": "created_by", "description": "Created by type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" } },
"required": ["type", "name"],
"additionalProperties": false,
"description": "Created by field",
@@ -356,7 +371,7 @@
```json
{
"type": "object",
- "properties": { "type": { "type": "string", "const": "updated_by", "description": "Modified by type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" } },
+ "properties": { "type": { "type": "string", "const": "updated_by", "description": "Modified by type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" } },
"required": ["type", "name"],
"additionalProperties": false,
"description": "Modified by field",
@@ -386,6 +401,7 @@
"properties": {
"type": { "type": "string", "const": "link", "description": "Link field type" },
"name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" },
+ "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" },
"link_table": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Linked table" },
"bidirectional": { "type": "boolean", "default": false, "description": "Bidirectional link" },
"bidirectional_link_field_name": { "$ref": "#/properties/name", "description": "Bidirectional link field name" }
@@ -414,7 +430,7 @@
```json
{
"type": "object",
- "properties": { "type": { "type": "string", "const": "formula", "description": "Formula field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, "expression": { "type": "string", "description": "Formula expression" } },
+ "properties": { "type": { "type": "string", "const": "formula", "description": "Formula field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" }, "expression": { "type": "string", "description": "Formula expression" } },
"required": ["type", "name", "expression"],
"additionalProperties": false,
"description": "Formula field",
@@ -451,6 +467,7 @@
"properties": {
"type": { "type": "string", "const": "lookup", "description": "Lookup field type" },
"name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" },
+ "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" },
"from": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Source data table" },
"select": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Field to aggregate from source table" },
"where": {
@@ -545,6 +562,7 @@
"properties": {
"type": { "type": "string", "const": "auto_number", "description": "Auto number type" },
"name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" },
+ "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" },
"style": {
"type": "object",
"properties": {
@@ -620,7 +638,7 @@
```json
{
"type": "object",
- "properties": { "type": { "type": "string", "const": "attachment", "description": "Attachment field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" } },
+ "properties": { "type": { "type": "string", "const": "attachment", "description": "Attachment field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" } },
"required": ["type", "name"],
"additionalProperties": false,
"description": "Attachment field",
@@ -633,7 +651,7 @@
```json
{
"type": "object",
- "properties": { "type": { "type": "string", "const": "location", "description": "Location field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" } },
+ "properties": { "type": { "type": "string", "const": "location", "description": "Location field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" } },
"required": ["type", "name"],
"additionalProperties": false,
"description": "Location field",
@@ -646,7 +664,7 @@
```json
{
"type": "object",
- "properties": { "type": { "type": "string", "const": "checkbox", "description": "Checkbox field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" } },
+ "properties": { "type": { "type": "string", "const": "checkbox", "description": "Checkbox field type" }, "name": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Field name" }, "description": { "type": "string", "description": "Field description; supports plain text or Markdown links" } },
"required": ["type", "name"],
"additionalProperties": false,
"description": "Checkbox field",
diff --git a/skills/lark-base/references/lookup-field-guide.md b/skills/lark-base/references/lookup-field-guide.md
index d5df607b..e99e5771 100644
--- a/skills/lark-base/references/lookup-field-guide.md
+++ b/skills/lark-base/references/lookup-field-guide.md
@@ -1,4 +1,4 @@
-# Bitable Lookup Field Configuration Guide
+# Base Lookup Field Configuration Guide
## Mandatory Read Acknowledgement
diff --git a/skills/lark-calendar/SKILL.md b/skills/lark-calendar/SKILL.md
index 46dd4eb2..056fc084 100644
--- a/skills/lark-calendar/SKILL.md
+++ b/skills/lark-calendar/SKILL.md
@@ -1,7 +1,7 @@
---
name: lark-calendar
version: 1.0.0
-description: "飞书日历（calendar）：提供日历与日程（会议）的全面管理能力。核心场景包括：查看/搜索日程、创建/更新日程、管理参会人、查询忙闲状态及推荐空闲时段。高频操作请优先使用 Shortcuts：+agenda（快速概览今日/近期行程）、+create（创建日程并按需邀请参会人）、+freebusy（查询用户主日历的忙闲信息和rsvp的状态）、+suggestion（针对时间未确定的预约日程需求，提供多个时间推荐方案）。"
+description: "飞书日历（calendar）：提供日历与日程（会议）的全面管理能力。核心场景包括：查看/搜索日程、创建/更新日程、管理参会人、查询忙闲状态及推荐空闲时段。高频操作请优先使用 Shortcuts：+agenda（快速概览今日/近期行程）、+create（创建日程并按需邀请参会人）、+freebusy（查询用户主日历的忙闲信息和rsvp的状态）、+rsvp（回复日程邀请）、+suggestion（针对时间未确定的预约日程需求，提供多个时间推荐方案）。"
metadata:
requires:
bins: ["lark-cli"]
@@ -81,6 +81,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli calendar + [flags]`
| [`+agenda`](references/lark-calendar-agenda.md) | 查看日程安排（默认今天） |
| [`+create`](references/lark-calendar-create.md) | 创建日程并邀请参会人（ISO 8601 时间） |
| [`+freebusy`](references/lark-calendar-freebusy.md) | 查询用户主日历的忙闲信息和rsvp的状态 |
+| [`+rsvp`](references/lark-calendar-rsvp.md) | 回复日程（接受/拒绝/待定） |
| [`+suggestion`](references/lark-calendar-suggestion.md) | 针对时间未确定的预约日程需求，提供多个时间推荐方案 |
## +suggestion 使用
diff --git a/skills/lark-calendar/references/lark-calendar-rsvp.md b/skills/lark-calendar/references/lark-calendar-rsvp.md
new file mode 100644
index 00000000..c6328056
--- /dev/null
+++ b/skills/lark-calendar/references/lark-calendar-rsvp.md
@@ -0,0 +1,42 @@
+# calendar +rsvp
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+回复指定的日程，更新当前用户的 RSVP 状态（接受、拒绝或待定）。
+
+需要的scopes: ["calendar:calendar.event:reply"]
+
+## 命令
+
+```bash
+# 回复日程为接受 (使用主日历)
+lark-cli calendar +rsvp --event-id evt_xxx --rsvp-status accept
+
+# 回复日程为拒绝
+lark-cli calendar +rsvp --event-id evt_xxx --rsvp-status decline
+
+# 回复日程为待定
+lark-cli calendar +rsvp --event-id evt_xxx --rsvp-status tentative
+
+# 指定其他日历下的日程
+lark-cli calendar +rsvp --calendar-id cal_xxx --event-id evt_xxx --rsvp-status accept
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--event-id ` | **是** | 日程 ID |
+| `--rsvp-status ` | **是** | 回复状态，可选值：`accept` (接受), `decline` (拒绝), `tentative` (待定) |
+| `--calendar-id ` | 否 | 日历 ID（省略则使用主日历） |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## 提示
+
+- 只能回复你被邀请的日程。
+- 调用前通常需要通过 `+agenda` 等命令获取到具体的 `event-id`。
+
+## 参考
+
+- [lark-calendar](../SKILL.md) -- 日历全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
diff --git a/skills/lark-doc/references/lark-doc-create.md b/skills/lark-doc/references/lark-doc-create.md
index d0ce0783..b26a162f 100644
--- a/skills/lark-doc/references/lark-doc-create.md
+++ b/skills/lark-doc/references/lark-doc-create.md
@@ -437,7 +437,7 @@ lark-cli docs +create --title "空白画板示例" --markdown '
diff --git a/skills/lark-drive/SKILL.md b/skills/lark-drive/SKILL.md
index 147163bf..a8bcd58a 100644
--- a/skills/lark-drive/SKILL.md
+++ b/skills/lark-drive/SKILL.md
@@ -164,6 +164,11 @@ Shortcut 是对常用操作的高级封装（`lark-cli drive + [flags]`）
| [`+upload`](references/lark-drive-upload.md) | Upload a local file to Drive |
| [`+download`](references/lark-drive-download.md) | Download a file from Drive to local |
| [`+add-comment`](references/lark-drive-add-comment.md) | Add a full-document comment, or a local comment to selected docx text (also supports wiki URL resolving to doc/docx) |
+| [`+export`](references/lark-drive-export.md) | Export a doc/docx/sheet/bitable to a local file with limited polling |
+| [`+export-download`](references/lark-drive-export-download.md) | Download an exported file by file_token |
+| [`+import`](references/lark-drive-import.md) | Import a local file to Drive as a cloud document (docx, sheet, bitable) |
+| [`+move`](references/lark-drive-move.md) | Move a file or folder to another location in Drive |
+| [`+task_result`](references/lark-drive-task-result.md) | Poll async task result for import, export, move, or delete operations |
## API Resources
@@ -177,6 +182,8 @@ lark-cli drive [flags] # 调用 API
### files
- `copy` — 复制文件
+ - `create_folder` — 新建文件夹
+ - `list` — 获取文件夹下的清单
### file.comments
@@ -208,11 +215,21 @@ lark-cli drive [flags] # 调用 API
- `subscription` — 订阅用户、应用维度事件（本次开放评论添加事件）
- `subscription_status` — 查询用户、应用对指定事件的订阅状态
+### file.statistics
+
+ - `get` — 获取文件统计信息
+
+### file.view_records
+
+ - `list` — 获取文档的访问者记录
+
## 权限表
| 方法 | 所需 scope |
|------|-----------|
| `files.copy` | `docs:document:copy` |
+| `files.create_folder` | `space:folder:create` |
+| `files.list` | `space:document:retrieve` |
| `file.comments.batch_query` | `docs:document.comment:read` |
| `file.comments.create_v2` | `docs:document.comment:create` |
| `file.comments.list` | `docs:document.comment:read` |
@@ -228,4 +245,5 @@ lark-cli drive [flags] # 调用 API
| `user.remove_subscription` | `docs:event:subscribe` |
| `user.subscription` | `docs:event:subscribe` |
| `user.subscription_status` | `docs:event:subscribe` |
-
+| `file.statistics.get` | `drive:drive.metadata:readonly` |
+| `file.view_records.list` | `drive:file:view_record:readonly` |
diff --git a/skills/lark-drive/references/lark-drive-export-download.md b/skills/lark-drive/references/lark-drive-export-download.md
new file mode 100644
index 00000000..42c4fdc8
--- /dev/null
+++ b/skills/lark-drive/references/lark-drive-export-download.md
@@ -0,0 +1,50 @@
+
+# drive +export-download
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+根据导出任务产物的 `file_token` 下载本地文件。通常与 `drive +task_result --scenario export` 配合使用。
+
+## 命令
+
+```bash
+# 使用服务端返回的文件名下载到当前目录
+lark-cli drive +export-download \
+ --file-token ""
+
+# 下载到指定目录
+lark-cli drive +export-download \
+ --file-token "" \
+ --output-dir ./exports
+
+# 指定本地文件名
+lark-cli drive +export-download \
+ --file-token "" \
+ --file-name "weekly-report.pdf" \
+ --output-dir ./exports
+
+# 允许覆盖
+lark-cli drive +export-download \
+ --file-token "" \
+ --overwrite
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file-token` | 是 | 导出完成后的产物 token |
+| `--file-name` | 否 | 覆盖默认文件名 |
+| `--output-dir` | 否 | 本地输出目录，默认当前目录 |
+| `--overwrite` | 否 | 覆盖已存在文件 |
+
+## 使用顺序
+
+1. 用 `drive +export` 发起导出
+2. 如果返回 `ticket` / `next_command`，用 `drive +task_result --scenario export --ticket --file-token ` 继续查
+3. 查到 `file_token` 后，用 `drive +export-download` 下载
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
diff --git a/skills/lark-drive/references/lark-drive-export.md b/skills/lark-drive/references/lark-drive-export.md
new file mode 100644
index 00000000..f60917c0
--- /dev/null
+++ b/skills/lark-drive/references/lark-drive-export.md
@@ -0,0 +1,100 @@
+
+# drive +export
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+把 `doc` / `docx` / `sheet` / `bitable` 导出到本地文件。这个 shortcut 内置有限轮询：
+
+- 如果导出任务在轮询窗口内完成，会直接下载到本地目录
+- 如果轮询结束仍未完成，会返回 `ticket`、`ready=false`、`timed_out=true` 和 `next_command`
+- 后续继续查结果时，改用 `drive +task_result --scenario export`
+- 拿到 `file_token` 后，改用 `drive +export-download`
+
+## 命令
+
+```bash
+# 导出新版文档为 pdf，默认保存到当前目录
+lark-cli drive +export \
+ --token "" \
+ --doc-type docx \
+ --file-extension pdf
+
+# 导出旧版文档为 docx
+lark-cli drive +export \
+ --token "" \
+ --doc-type doc \
+ --file-extension docx
+
+# 导出 docx 为 markdown
+# 注意：markdown 只支持 docx，底层走 /open-apis/docs/v1/content
+lark-cli drive +export \
+ --token "" \
+ --doc-type docx \
+ --file-extension markdown
+
+# 导出电子表格为 xlsx
+lark-cli drive +export \
+ --token "" \
+ --doc-type sheet \
+ --file-extension xlsx \
+ --output-dir ./exports
+
+# 导出电子表格或多维表格为 csv 时，必须传 sub_id
+lark-cli drive +export \
+ --token "" \
+ --doc-type "" \
+ --file-extension csv \
+ --sub-id "" \
+ --output-dir ./exports
+
+# 允许覆盖已存在文件
+lark-cli drive +export \
+ --token "" \
+ --doc-type docx \
+ --file-extension pdf \
+ --overwrite
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--token` | 是 | 源文档 token |
+| `--doc-type` | 是 | 源文档类型：`doc` / `docx` / `sheet` / `bitable` |
+| `--file-extension` | 是 | 导出格式：`docx` / `pdf` / `xlsx` / `csv` / `markdown` |
+| `--sub-id` | 条件必填 | 当 `sheet` / `bitable` 导出为 `csv` 时必填 |
+| `--output-dir` | 否 | 本地输出目录，默认当前目录 |
+| `--overwrite` | 否 | 覆盖已存在文件 |
+
+## 关键约束
+
+- `markdown` 只支持 `docx`
+- `sheet` / `bitable` 导出为 `csv` 时必须带 `--sub-id`
+- shortcut 内部固定有限轮询：最多 10 次，每次间隔 5 秒
+- 轮询超时不是失败；会返回 `ticket`、`timed_out=true` 和 `next_command`，供后续继续查询
+
+## 推荐续跑方式
+
+```bash
+# 第一步：先尝试直接导出
+lark-cli drive +export \
+ --token "" \
+ --doc-type docx \
+ --file-extension pdf
+
+# 如果返回 ready=false / timed_out=true，再继续查
+lark-cli drive +task_result \
+ --scenario export \
+ --ticket "" \
+ --file-token ""
+
+# 查到 file_token 后下载
+lark-cli drive +export-download \
+ --file-token "" \
+ --output-dir ./exports
+```
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
diff --git a/skills/lark-drive/references/lark-drive-import.md b/skills/lark-drive/references/lark-drive-import.md
new file mode 100644
index 00000000..58041bda
--- /dev/null
+++ b/skills/lark-drive/references/lark-drive-import.md
@@ -0,0 +1,80 @@
+# drive +import
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+将本地文件（如 Word、TXT、Markdown、Excel 等）导入并转换为飞书在线云文档（docx、sheet、bitable）。底层统一通过 `POST /open-apis/drive/v1/import_tasks` 接口创建导入任务，并在 shortcut 内做有限次数轮询 `GET /open-apis/drive/v1/import_tasks/:ticket`。
+
+## 命令
+
+```bash
+# 导入 Markdown 为新版文档 (docx)
+lark-cli drive +import --file ./README.md --type docx
+
+# 导入 Excel 为电子表格 (sheet)
+lark-cli drive +import --file ./data.xlsx --type sheet
+
+# 导入到指定文件夹，并指定导入后的文件名
+lark-cli drive +import --file ./data.csv --type bitable --folder-token --name "导入数据表"
+
+# 预览底层调用链（上传 -> 创建任务 -> 轮询）
+lark-cli drive +import --file ./README.md --type docx --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file` | 是 | 本地文件路径，根据文件后缀名自动推断 `file_extension`，最大支持 20MB |
+| `--type` | 是 | 导入目标云文档格式。可选值：`docx` (新版文档)、`sheet` (电子表格)、`bitable` (多维表格) |
+| `--folder-token` | 否 | 目标文件夹 token，不传则请求中的 `point.mount_key` 为空字符串，Import API 会将其解释为导入到云空间根目录 |
+| `--name` | 否 | 导入后的在线云文档名称，不传默认使用本地文件名去掉扩展名后的结果 |
+
+## 行为说明
+
+- **三步执行**：此 shortcut 内部封装了完整流程：
+ 1. 自动调用素材上传接口 (`/open-apis/drive/v1/medias/upload_all`) 获取源文件的 `file_token`
+ 2. 调用 `import_tasks` 接口发起导入任务，自动根据本地文件提取扩展名并构造挂载点（`mount_point`）参数
+ 3. 自动轮询查询导入任务状态；如果在内置轮询窗口内完成，则直接返回导入结果；如果仍未完成，则返回 `ticket`、当前状态和后续查询命令
+- **默认根目录行为**：不传 `--folder-token` 时，shortcut 会保留空的 `point.mount_key`，Lark Import API 会将其视为“导入到调用者根目录”。
+
+### 支持的文件类型转换
+
+本地文件扩展名与目标云文档类型的对应关系如下：
+
+| 本地文件扩展名 | 可导入为 | 说明 |
+|--------------|---------|------|
+| `.docx`, `.doc` | `docx` | Microsoft Word 文档 |
+| `.txt` | `docx` | 纯文本文件 |
+| `.md`, `.markdown`, `.mark` | `docx` | Markdown 文档 |
+| `.html` | `docx` | HTML 文档 |
+| `.xlsx`, `.xls` | `sheet`, `bitable` | Microsoft Excel 表格 |
+| `.csv` | `sheet`, `bitable` | CSV 数据文件 |
+
+> [!IMPORTANT]
+> 文件扩展名与目标文档类型必须匹配，否则会返回验证错误：
+> - 文档类文件（.docx, .doc, .txt, .md, .html）**只能**导入为 `docx`
+> - 表格类文件（.xlsx, .xls, .csv）**只能**导入为 `sheet` 或 `bitable`
+> - 例如：`.csv` 文件不能导入为 `docx`，`.md` 文件不能导入为 `sheet`
+
+- 若导入任务执行失败，会返回失败时的 `job_status` 及错误信息。
+- 若内置轮询超时但任务仍在处理中，shortcut 会成功返回，并带上：
+ - `ready=false`
+ - `timed_out=true`
+ - `next_command`：可直接复制执行的后续查询命令，例如 `lark-cli drive +task_result --scenario import --ticket `
+- 如果文件超过 20MB 上限，或者文件扩展名不被支持，执行时将抛出验证错误。
+
+### 超时后的继续查询
+
+当 `+import` 的内置轮询窗口结束但任务尚未完成时，使用返回结果中的 `ticket` 继续查询：
+
+```bash
+lark-cli drive +task_result --scenario import --ticket
+```
+
+> [!CAUTION]
+> `drive +import` 是**写入操作** —— 执行前必须确认用户意图。
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
diff --git a/skills/lark-drive/references/lark-drive-move.md b/skills/lark-drive/references/lark-drive-move.md
new file mode 100644
index 00000000..57d93132
--- /dev/null
+++ b/skills/lark-drive/references/lark-drive-move.md
@@ -0,0 +1,92 @@
+
+# drive +move
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+将文件或文件夹移动到用户云空间的其他位置。
+
+## 命令
+
+```bash
+# 移动文件到指定文件夹
+lark-cli drive +move \
+ --file-token \
+ --type file \
+ --folder-token
+
+# 移动文档到指定文件夹
+lark-cli drive +move \
+ --file-token \
+ --type docx \
+ --folder-token
+
+# 移动文件夹（异步操作，会自动有限轮询任务状态）
+lark-cli drive +move \
+ --file-token \
+ --type folder \
+ --folder-token
+
+# 移动到根文件夹（不指定 --folder-token）
+lark-cli drive +move \
+ --file-token \
+ --type file
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--file-token` | 是 | 需要移动的文件或文件夹 token |
+| `--type` | 是 | 文件类型，可选值：`file` (普通文件)、`docx` (新版文档)、`bitable` (多维表格)、`doc` (旧版文档)、`sheet` (电子表格)、`mindnote` (思维笔记)、`folder` (文件夹)、`slides` (幻灯片) |
+| `--folder-token` | 否 | 目标文件夹 token，不指定则移动到根文件夹 |
+
+## 文件类型说明
+
+| 类型 | 说明 |
+|------|------|
+| `file` | 普通文件 |
+| `docx` | 新版云文档 |
+| `doc` | 旧版云文档 |
+| `sheet` | 电子表格 |
+| `bitable` | 多维表格 |
+| `mindnote` | 思维笔记 |
+| `slides` | 幻灯片 |
+| `folder` | 文件夹（移动文件夹是异步操作） |
+
+## 行为说明
+
+- **普通文件移动**：同步操作，立即完成
+- **文件夹移动**：异步操作，接口返回 `task_id`，shortcut 会先做有限轮询；如果在轮询窗口内完成，则直接返回成功结果
+- **轮询超时不是失败**：文件夹移动内置最多轮询 30 次、每次间隔 2 秒；如果轮询结束任务仍未完成，会返回 `task_id`、`status`、`ready=false`、`timed_out=true` 和 `next_command`
+- **继续查询**：当看到 `next_command` 时，改用 `lark-cli drive +task_result --scenario task_check --task-id ` 继续查询
+- **目标文件夹**：如果不指定 `--folder-token`，文件将被移动到用户的根文件夹（"我的空间"）
+- **权限要求**：需要被移动文件的可管理权限、被移动文件所在位置的编辑权限、目标位置的编辑权限
+
+## 推荐续跑方式
+
+```bash
+# 第一步：先直接移动文件夹
+lark-cli drive +move \
+ --file-token \
+ --type folder \
+ --folder-token
+
+# 如果返回 ready=false / timed_out=true，再继续查
+lark-cli drive +task_result \
+ --scenario task_check \
+ --task-id
+```
+
+## 限制
+
+- 被移动的文件不支持 wiki 文档
+- 该接口不支持并发调用
+- 调用频率上限为 5 QPS 且 10000 次/天
+
+> [!CAUTION]
+> 这是**写入操作** —— 执行前必须确认用户意图。
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
diff --git a/skills/lark-drive/references/lark-drive-task-result.md b/skills/lark-drive/references/lark-drive-task-result.md
new file mode 100644
index 00000000..4c42aaed
--- /dev/null
+++ b/skills/lark-drive/references/lark-drive-task-result.md
@@ -0,0 +1,170 @@
+
+# drive +task_result
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
+
+查询异步任务结果。该 shortcut 聚合了导入、导出、移动/删除文件夹等多种异步任务的结果查询，统一接口方便调用。
+
+## 命令
+
+```bash
+# 查询导入任务结果
+lark-cli drive +task_result \
+ --scenario import \
+ --ticket
+
+# 查询导出任务结果
+lark-cli drive +task_result \
+ --scenario export \
+ --ticket \
+ --file-token
+
+# 查询移动/删除文件夹任务状态
+lark-cli drive +task_result \
+ --scenario task_check \
+ --task-id
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--scenario` | 是 | 任务场景，可选值：`import` (导入任务)、`export` (导出任务)、`task_check` (移动/删除文件夹任务) |
+| `--ticket` | 条件必填 | 异步任务 ticket，**import/export 场景必填** |
+| `--task-id` | 条件必填 | 异步任务 ID，**task_check 场景必填** |
+| `--file-token` | 条件必填 | 导出任务对应的源文档 token，**export 场景必填** |
+
+## 场景说明
+
+| 场景 | 说明 | 所需参数 |
+|------|------|----------|
+| `import` | 文档导入任务（如将本地文件导入为云文档） | `--ticket` |
+| `export` | 文档导出任务（如云文档导出为 PDF/Word） | `--ticket`、`--file-token` |
+| `task_check` | 文件夹移动/删除任务 | `--task-id` |
+
+## 返回结果
+
+### Import 场景返回
+
+```json
+{
+ "scenario": "import",
+ "ticket": "",
+ "type": "sheet",
+ "ready": true,
+ "failed": false,
+ "job_status": 0,
+ "job_status_label": "success",
+ "job_error_msg": "success",
+ "token": "",
+ "url": "https://example.feishu.cn/sheets/",
+ "extra": ["2000"]
+}
+```
+
+**字段说明：**
+- `ready`: 是否已经导入完成，可直接使用 `token` / `url`
+- `failed`: 是否已经失败
+- `job_status`: 服务端返回的原始状态码
+- `job_status_label`: 便于阅读的状态标签，例如 `success` / `processing`
+- `token`: 导入后的文档 token
+- `url`: 导入后的文档链接
+
+### Export 场景返回
+
+```json
+{
+ "scenario": "export",
+ "ticket": "",
+ "ready": true,
+ "failed": false,
+ "file_extension": "pdf",
+ "type": "doc",
+ "file_name": "docName",
+ "file_token": "",
+ "file_size": 34356,
+ "job_error_msg": "success",
+ "job_status": 0,
+ "job_status_label": "success"
+}
+```
+
+**字段说明：**
+- `ready`: 是否已经完成导出，可直接使用 `file_token`
+- `failed`: 是否已经失败
+- `job_status`: 服务端返回的原始状态码
+- `job_status_label`: 便于阅读的状态标签，例如 `success` / `processing`
+- `file_token`: 导出文件的 token，用于下载
+- `file_extension`: 导出文件扩展名
+- `file_size`: 导出文件大小（字节）
+
+### Task_check 场景返回
+
+```json
+{
+ "scenario": "task_check",
+ "task_id": "",
+ "status": "success",
+ "ready": true,
+ "failed": false
+}
+```
+
+**字段说明：**
+- `status`: 任务状态，`success`=成功，`failed`=失败，`pending`=处理中
+- `ready`: 是否已经完成
+- `failed`: 是否已经失败
+
+## 使用场景
+
+### 配合 +import 使用
+
+```bash
+# 1. 创建导入任务
+lark-cli drive +import --file ./data.xlsx --type sheet
+# 若任务很快完成：直接返回 token / url
+# 若内置轮询超时：返回 ready=false、ticket 和 next_command
+
+# 2. 轮询导入结果
+lark-cli drive +task_result --scenario import --ticket
+```
+
+### 配合 +move 使用
+
+```bash
+# 1. 移动文件夹（异步操作）
+lark-cli drive +move --file-token --type folder --folder-token
+# 若轮询窗口内完成：直接返回 ready=true
+# 若内置轮询结束仍未完成：返回 ready=false、task_id 和 next_command
+
+# 2. 轮询移动结果
+lark-cli drive +task_result --scenario task_check --task-id
+```
+
+### 配合 +export 使用
+
+```bash
+# 1. 发起导出
+lark-cli drive +export --token --doc-type docx --file-extension pdf
+# 若轮询窗口内完成：直接下载本地文件
+# 若内置轮询结束仍未完成：返回 ready=false、ticket 和 next_command
+
+# 2. 继续查询导出结果
+lark-cli drive +task_result --scenario export --ticket --file-token
+
+# 3. 拿到 file_token 后下载
+lark-cli drive +export-download --file-token
+```
+
+## 权限要求
+
+| 场景 | 所需 scope |
+|------|-----------|
+| import | `drive:drive.metadata:readonly` |
+| export | `drive:drive.metadata:readonly` |
+| task_check | `drive:drive.metadata:readonly` |
+
+## 参考
+
+- [lark-drive](../SKILL.md) -- 云空间全部命令
+- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数
diff --git a/skills/lark-im/SKILL.md b/skills/lark-im/SKILL.md
index e33ee515..310aca4a 100644
--- a/skills/lark-im/SKILL.md
+++ b/skills/lark-im/SKILL.md
@@ -61,10 +61,10 @@ Shortcut 是对常用操作的高级封装（`lark-cli im + [flags]`）。
| [`+chat-search`](references/lark-im-chat-search.md) | Search visible group chats by keyword and/or member open_ids (e.g. look up chat_id by group name); user/bot; supports member/type filters, sorting, and pagination |
| [`+chat-update`](references/lark-im-chat-update.md) | Update group chat name or description; user/bot; updates a chat's name or description |
| [`+messages-mget`](references/lark-im-messages-mget.md) | Batch get messages by IDs; user/bot; fetches up to 50 om_ message IDs, formats sender names, expands thread replies |
-| [`+messages-reply`](references/lark-im-messages-reply.md) | Reply to a message (supports thread replies) with bot identity; bot-only; supports text/markdown/post/media replies, reply-in-thread, idempotency key |
+| [`+messages-reply`](references/lark-im-messages-reply.md) | Reply to a message (supports thread replies); user/bot; supports text/markdown/post/media replies, reply-in-thread, idempotency key |
| [`+messages-resources-download`](references/lark-im-messages-resources-download.md) | Download images/files from a message; user/bot; downloads image/file resources by message-id and file-key to a safe relative output path |
-| [`+messages-search`](references/lark-im-messages-search.md) | Search messages across chats (supports keyword, sender, time range filters) with user identity; user-only; filters by chat/sender/attachment/time, enriches results via mget and chats batch_query |
-| [`+messages-send`](references/lark-im-messages-send.md) | Send a message to a chat or direct message with bot identity; bot-only; sends to chat-id or user-id with text/markdown/post/media, supports idempotency key |
+| [`+messages-search`](references/lark-im-messages-search.md) | Search messages across chats (supports keyword, sender, time range filters) with user identity; user-only; filters by chat/sender/attachment/time, supports auto-pagination via `--page-all` / `--page-limit`, enriches results via batched mget and chats batch_query |
+| [`+messages-send`](references/lark-im-messages-send.md) | Send a message to a chat or direct message; user/bot; sends to chat-id or user-id with text/markdown/post/media, supports idempotency key |
| [`+threads-messages-list`](references/lark-im-threads-messages-list.md) | List messages in a thread; user/bot; accepts om_/omt_ input, resolves message IDs to thread_id, supports sort/pagination |
## API Resources
@@ -87,6 +87,7 @@ lark-cli im [flags] # 调用 API
### chat.members
- `create` — 将用户或机器人拉入群聊。Identity: supports `user` and `bot`; the caller must be in the target chat; for `bot` calls, added users must be within the app's availability; for internal chats the operator must belong to the same tenant; if only owners/admins can add members, the caller must be an owner/admin, or a chat-creator bot with `im:chat:operate_as_owner`.
+ - `delete` — 将用户或机器人移出群聊。Identity: supports `user` and `bot`; only group owner, admin, or creator bot can remove others; max 50 users or 5 bots per request.
- `get` — 获取群成员列表。Identity: supports `user` and `bot`; the caller must be in the target chat and must belong to the same tenant for internal chats.
### messages
@@ -123,6 +124,7 @@ lark-cli im [flags] # 调用 API
| `chats.list` | `im:chat:read` |
| `chats.update` | `im:chat:update` |
| `chat.members.create` | `im:chat.members:write_only` |
+| `chat.members.delete` | `im:chat.members:write_only` |
| `chat.members.get` | `im:chat.members:read` |
| `messages.delete` | `im:message:recall` |
| `messages.forward` | `im:message` |
@@ -136,4 +138,3 @@ lark-cli im [flags] # 调用 API
| `pins.create` | `im:message.pins:write_only` |
| `pins.delete` | `im:message.pins:write_only` |
| `pins.list` | `im:message.pins:read` |
-
diff --git a/skills/lark-im/references/lark-im-messages-reply.md b/skills/lark-im/references/lark-im-messages-reply.md
index 2e92310d..5b8cd8b9 100644
--- a/skills/lark-im/references/lark-im-messages-reply.md
+++ b/skills/lark-im/references/lark-im-messages-reply.md
@@ -2,7 +2,7 @@
> **Prerequisite:** Read [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) first to understand authentication, global parameters, and safety rules.
-Reply to a specific message. Only supports bot identity. Also supports thread replies.
+Reply to a specific message. Supports both user identity (`--as user`) and bot identity (`--as bot`). Also supports thread replies.
This skill maps to the shortcut: `lark-cli im +messages-reply` (internally calls `POST /open-apis/im/v1/messages/:message_id/reply`).
@@ -12,16 +12,96 @@ Replies sent by this tool are visible to other people. Before calling it, you **
1. Which message to reply to
2. The reply content
-3. Which identity to use (bot only)
+3. Which identity to use (user or bot)
**Do not** send a reply without explicit user approval.
When using `--as bot`, the reply is sent in the app's name, so make sure the app has already been added to the target chat.
+When using `--as user`, the reply is sent as the authorized end user and requires the `im:message.send_as_user` scope.
+
+## Choose The Right Content Flag
+
+| Need | Recommended flag | Why |
+|------|------|------|
+| Reply with plain text exactly as written | `--text` | Wrapped directly to `{"text":"..."}` |
+| Reply with simple Markdown and accept conversion | `--markdown` | Automatically converted to `post` JSON |
+| Precisely control the reply payload | `--content` | You provide the exact JSON |
+| Reply with media | `--image` / `--file` / `--video` / `--audio` | Shortcut uploads local files automatically |
+
+### `--text` vs `--markdown`
+
+- Use `--text` when the reply should remain plain text and you want exact control over line breaks, spacing, indentation, code samples, or literal Markdown characters.
+- Use `--markdown` when you want a lightweight formatted reply and you accept that the shortcut will normalize and rewrite parts of the content before sending.
+- Use `--content` when you need exact `post` JSON, a card, a title, multiple locales, or any structure that `--markdown` cannot express reliably.
+
+## What `--markdown` Really Does
+
+`--markdown` does **not** send arbitrary raw Markdown to the API.
+
+The shortcut:
+
+1. Forces `msg_type=post`
+2. Resolves remote Markdown images like ``
+3. Normalizes the Markdown for Feishu post rendering
+4. Wraps the final content as:
+
+```json
+{"zh_cn":{"content":[[{"tag":"md","text":"..."}]]}}
+```
+
+So `--markdown` is a convenience mode, not a full Markdown compatibility layer.
+
+### Current Markdown Caveats
+
+- It does **not** promise full CommonMark / GitHub Flavored Markdown support.
+- It always becomes a `post` payload with a single `zh_cn` locale.
+- It does **not** let you set a `post` title.
+- Headings are rewritten:
+ - `# Title` becomes `#### Title`
+ - `##` to `######` are normalized to `#####` when the content contains H1-H3
+- Consecutive headings are separated with blank lines after heading normalization.
+- Block spacing and line breaks may be normalized during conversion.
+- Code blocks are preserved as code blocks.
+- Excess blank lines are compressed.
+- Only remote `http://...`, `https://...`, or already-uploaded `img_xxx` Markdown images are kept reliably.
+- Local paths in Markdown image syntax like `` are **not** auto-uploaded by `--markdown`.
+- If remote Markdown image handling fails, that image is removed with a warning.
+
+If you need exact output, use `--msg-type post --content ...` instead of `--markdown`.
+
+## Preserving Formatting
+
+If the reply contains multiple lines, code blocks, indentation, tabs, or a lot of escaping, prefer `$'...'`.
+
+### When formatting must be preserved
+
+Use `--text` plus `$'...'`:
+
+```bash
+lark-cli im +messages-reply --message-id om_xxx --text $'Received\nI will check this today.\nOwner: alice'
+```
+
+```bash
+lark-cli im +messages-reply --message-id om_xxx --text $'```sql\nselect * from jobs;\n```'
+```
+
+This keeps the reply as plain text instead of converting it to a `post`.
+
+### When formatting does not need exact preservation
+
+Use `--markdown`:
+
+```bash
+lark-cli im +messages-reply --message-id om_xxx --markdown $'## Follow-up\n\n- I reproduced it\n- I am fixing it'
+```
+
+This is better for quick readable formatting, but the final payload may still differ from the source text because headings and spacing are normalized before sending.
+
## Commands
```bash
-# Reply to a message (plain text, bot identity, --text is recommended)
+# Reply to a message (plain text, --text is recommended for normal replies)
lark-cli im +messages-reply --message-id om_xxx --text "Received"
# Equivalent manual JSON
@@ -30,13 +110,16 @@ lark-cli im +messages-reply --message-id om_xxx --content '{"text":"Received"}'
# Reply as a bot
lark-cli im +messages-reply --message-id om_xxx --text "bot reply" --as bot
+# Reply with preserved multi-line text
+lark-cli im +messages-reply --message-id om_xxx --text $'Line 1\nLine 2\n indented line'
+
# Reply inside the thread (message appears in the target thread)
lark-cli im +messages-reply --message-id om_xxx --text "Let's discuss this" --reply-in-thread
-# Bot identity + thread reply
-lark-cli im +messages-reply --message-id om_xxx --text "bot reply" --as bot --reply-in-thread
+# Reply with basic Markdown (will be converted to post JSON)
+lark-cli im +messages-reply --message-id om_xxx --markdown $'## Reply\n\n- item 1\n- item 2'
-# Reply with a rich-text message
+# If you need exact post structure, send JSON directly
lark-cli im +messages-reply --message-id om_xxx --msg-type post --content '{"zh_cn":{"title":"Reply","content":[[{"tag":"text","text":"Detailed content"}]]}}'
# Reply with a local image (uploaded automatically before sending)
@@ -52,7 +135,7 @@ lark-cli im +messages-reply --message-id om_xxx --video ./demo.mp4 --video-cover
lark-cli im +messages-reply --message-id om_xxx --text "Received" --idempotency-key my-unique-id
# Preview the request without executing it
-lark-cli im +messages-reply --message-id om_xxx --text "Test" --dry-run
+lark-cli im +messages-reply --message-id om_xxx --markdown $'## Test\n\nhello' --dry-run
```
## Parameters
@@ -60,24 +143,33 @@ lark-cli im +messages-reply --message-id om_xxx --text "Test" --dry-run
| Parameter | Required | Description |
|------|------|------|
| `--message-id ` | Yes | ID of the message being replied to (`om_xxx`) |
-| `--msg-type ` | No | Message type (default `text`): `text`, `post`, `image`, `file`, `audio`, `media`, `interactive`, `share_chat`, `share_user` |
-| `--content ` | One of content options | Reply content as a JSON string; format depends on `msg_type` |
-| `--text ` | One of content options | Plain text message (automatically wrapped as `{"text":"..."}` JSON) |
-| `--markdown ` | One of content options | Markdown text (auto-wrapped as post format with style optimization; image URLs auto-resolved) |
-| `--image ` | One of content options | Local image path, `image_key` (`img_xxx`)|
-| `--file ` | One of content options | Local file path, `file_key` (`file_xxx`)|
-| `--video ` | One of content options | Local video path, `file_key`; **must be used together with `--video-cover`** |
-| `--video-cover ` | **Required with `--video`** | Video cover image path, `image_key` (`img_xxx`) |
-| `--audio ` | One of content options | Local audio path, `file_key` |
+| `--msg-type ` | No | Message type (default `text`). If you use `--text` / `--markdown` / media flags, the effective type is inferred automatically. Explicitly setting a conflicting `--msg-type` fails validation |
+| `--content ` | One content option | Exact reply content as JSON. The JSON must match the effective `--msg-type` |
+| `--text ` | One content option | Plain text reply. Best default when you need exact text and formatting preservation |
+| `--markdown ` | One content option | Convenience Markdown input. Internally converted to `post` JSON with Feishu-specific normalization |
+| `--image ` | One content option | Local image path or `image_key` (`img_xxx`) |
+| `--file ` | One content option | Local file path or `file_key` (`file_xxx`) |
+| `--video ` | One content option | Local video path or `file_key`; **must be used together with `--video-cover`** |
+| `--video-cover ` | **Required with `--video`** | Video cover image path or `image_key` (`img_xxx`) |
+| `--audio ` | One content option | Local audio path or `file_key` |
| `--reply-in-thread` | No | Reply inside the thread. The reply appears in the target message's thread instead of the main chat stream |
| `--idempotency-key ` | No | Idempotency key; the same key sends only one reply within 1 hour |
-| `--as ` | No | Identity type: `bot` only |
+| `--as ` | No | Identity type: `bot` or `user` (default `bot`) |
| `--dry-run` | No | Print the request only, do not execute it |
> **Mutual exclusivity rule:** `--text`, `--markdown`, `--content`, and `--image`/`--file`/`--video`/`--audio` cannot be used together. Media flags are also mutually exclusive with each other.
>
> **Video cover rule:** `--video` **must** be accompanied by `--video-cover`. Omitting `--video-cover` when using `--video` will fail validation. `--video-cover` cannot be used without `--video`.
+## Common Mistakes
+
+- Choosing `--markdown` when you actually need exact plain text. If exact line breaks and spacing matter, use `--text`, usually with `$'...'`.
+- Assuming `--markdown` supports all Markdown features. It does not; it is converted into a Feishu `post` payload and rewritten first.
+- Putting local image paths inside Markdown like ``. `--markdown` does not auto-upload those paths.
+- Using `--content` without making the JSON match the effective `--msg-type`.
+- Explicitly setting `--msg-type` to something that conflicts with `--text`, `--markdown`, or media flags.
+- Mixing `--text`, `--markdown`, or `--content` with media flags in one command.
+
## Return Value
```json
@@ -108,16 +200,23 @@ The reply appears in the target message's thread and does not show up in the mai
## @Mention Format (text / post)
-- @specific user: `name`
+- Recommended format: `name`
- @all: ``
+- The shortcut normalizes common variants like `` and `` into `user_id`, but `user_id` remains the recommended documented form
## Notes
- `--message-id` must be a valid message ID in `om_xxx` format
-- `--content` must be a valid JSON string
-- `--reply-in-thread` is only meaningful in group chats
-- `--image`/`--file`/`--video`/`--audio`/`--video-cover` support local file paths; use relative paths within the current working directory. The shortcut automatically uploads the file first and then sends the reply
-- If the provided value starts with `img_` or `file_`, it is treated as an existing key and used directly
-- When using `--video`, `--video-cover` is **required** as the video cover. Omitting `--video-cover` with `--video` will produce a validation error. `--video-cover` cannot be used without `--video`
+- `--content` must be valid JSON
+- When using `--content`, you are responsible for making the JSON structure match the effective `msg_type`
+- `--reply-in-thread` adds `reply_in_thread=true` to the API request
+- `--reply-in-thread` is mainly meaningful in chats that support thread replies
+- `--image`/`--file`/`--video`/`--audio`/`--video-cover` support local file paths; the shortcut uploads first and then sends the reply; file/image upload is bot-only, so when using `--as user`, the upload step is automatically performed with bot identity, and only the final send uses user identity
+- If the provided media value starts with `img_` or `file_`, it is treated as an existing key and used directly
+- `--markdown` always sends `msg_type=post`
+- If you explicitly set `--msg-type` and it conflicts with the chosen content flag, validation fails
+- When using `--video`, `--video-cover` is required as the video cover
+- `--dry-run` uses placeholder image keys for remote Markdown images and placeholder media keys for local uploads
- Failures return error codes and messages
+- `--as user` uses a user access token (UAT) and requires the `im:message.send_as_user` scope; the reply is sent as the authorized end user
- `--as bot` uses a tenant access token (TAT), and requires the `im:message:send_as_bot` scope
diff --git a/skills/lark-im/references/lark-im-messages-search.md b/skills/lark-im/references/lark-im-messages-search.md
index 4cf3f295..68858395 100644
--- a/skills/lark-im/references/lark-im-messages-search.md
+++ b/skills/lark-im/references/lark-im-messages-search.md
@@ -6,7 +6,7 @@ Search Feishu messages across conversations. This shortcut automatically perform
> **User identity only** (`--as user`). Bot identity is not supported.
-This skill maps to the shortcut: `lark-cli im +messages-search` (internally calls `POST /open-apis/im/v1/messages/search` + `GET /open-apis/im/v1/messages/mget`, then batch-fetches chat context).
+This skill maps to the shortcut: `lark-cli im +messages-search` (internally calls `POST /open-apis/im/v1/messages/search` + batched `GET /open-apis/im/v1/messages/mget`, then batch-fetches chat context).
## Commands
@@ -49,6 +49,12 @@ lark-cli im +messages-search --query "test" --format csv
# Pagination
lark-cli im +messages-search --query "test" --page-token
+# Auto-pagination across multiple pages
+lark-cli im +messages-search --query "test" --page-all --format json
+
+# Auto-pagination with an explicit page cap
+lark-cli im +messages-search --query "test" --page-limit 5 --format json
+
# Preview the request without executing it
lark-cli im +messages-search --query "test" --dry-run
```
@@ -69,6 +75,8 @@ lark-cli im +messages-search --query "test" --dry-run
| `--end