-
Notifications
You must be signed in to change notification settings - Fork 585
feat: add docs media-preview shortcut #334
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,120 @@ | ||
| // Copyright (c) 2026 Lark Technologies Pte. Ltd. | ||
| // SPDX-License-Identifier: MIT | ||
|
|
||
| package doc | ||
|
|
||
| import ( | ||
| "context" | ||
| "fmt" | ||
| "net/http" | ||
| "path/filepath" | ||
| "strings" | ||
|
|
||
| larkcore "github.com/larksuite/oapi-sdk-go/v3/core" | ||
|
|
||
| "github.com/larksuite/cli/internal/output" | ||
| "github.com/larksuite/cli/internal/validate" | ||
| "github.com/larksuite/cli/internal/vfs" | ||
| "github.com/larksuite/cli/shortcuts/common" | ||
| ) | ||
|
|
||
| var previewMimeToExt = 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", | ||
| "text/plain": ".txt", | ||
| } | ||
|
|
||
| const PreviewType_SOURCE_FILE = "16" | ||
|
|
||
| var DocMediaPreview = common.Shortcut{ | ||
| Service: "docs", | ||
| Command: "+media-preview", | ||
| Description: "Preview document media file (auto-detects extension)", | ||
| Risk: "read", | ||
| Scopes: []string{"docs:document.media:download"}, | ||
| AuthTypes: []string{"user", "bot"}, | ||
| Flags: []common.Flag{ | ||
| {Name: "token", Desc: "media file token", Required: true}, | ||
| {Name: "output", Desc: "local save path", Required: true}, | ||
| {Name: "overwrite", Type: "bool", Desc: "overwrite existing output file"}, | ||
| }, | ||
| DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI { | ||
| token := runtime.Str("token") | ||
| outputPath := runtime.Str("output") | ||
| return common.NewDryRunAPI(). | ||
| GET("/open-apis/drive/v1/medias/:token/preview_download"). | ||
| Desc("Preview document media file"). | ||
| Params(map[string]interface{}{"preview_type": PreviewType_SOURCE_FILE}). | ||
| Set("token", token).Set("output", outputPath) | ||
| }, | ||
| Execute: func(ctx context.Context, runtime *common.RuntimeContext) error { | ||
| token := runtime.Str("token") | ||
| outputPath := runtime.Str("output") | ||
| overwrite := runtime.Bool("overwrite") | ||
|
|
||
| if err := validate.ResourceName(token, "--token"); err != nil { | ||
| return output.ErrValidation("%s", err) | ||
| } | ||
| // Early path validation before API call (final validation after auto-extension below) | ||
| if _, err := validate.SafeOutputPath(outputPath); err != nil { | ||
| return output.ErrValidation("unsafe output path: %s", err) | ||
| } | ||
|
wittam-01 marked this conversation as resolved.
|
||
|
|
||
| fmt.Fprintf(runtime.IO().ErrOut, "Previewing: media %s\n", common.MaskToken(token)) | ||
|
|
||
| encodedToken := validate.EncodePathSegment(token) | ||
| apiPath := fmt.Sprintf("/open-apis/drive/v1/medias/%s/preview_download", encodedToken) | ||
|
|
||
| resp, err := runtime.DoAPIStream(ctx, &larkcore.ApiReq{ | ||
| HttpMethod: http.MethodGet, | ||
| ApiPath: apiPath, | ||
| QueryParams: larkcore.QueryParams{ | ||
| "preview_type": []string{PreviewType_SOURCE_FILE}, | ||
| }, | ||
|
greptile-apps[bot] marked this conversation as resolved.
|
||
| }) | ||
| if err != nil { | ||
| return output.ErrNetwork("preview failed: %v", err) | ||
|
wittam-01 marked this conversation as resolved.
|
||
| } | ||
| defer resp.Body.Close() | ||
|
|
||
| finalPath := outputPath | ||
| currentExt := filepath.Ext(outputPath) | ||
| if currentExt == "" { | ||
| contentType := resp.Header.Get("Content-Type") | ||
| mimeType := strings.Split(contentType, ";")[0] | ||
| mimeType = strings.TrimSpace(mimeType) | ||
| if ext, ok := previewMimeToExt[mimeType]; ok { | ||
| finalPath = outputPath + ext | ||
| } | ||
| } | ||
|
|
||
| safePath, err := validate.SafeOutputPath(finalPath) | ||
| if err != nil { | ||
| return output.ErrValidation("unsafe output path: %s", err) | ||
| } | ||
| if err := common.EnsureWritableFile(safePath, overwrite); err != nil { | ||
| return err | ||
| } | ||
|
wittam-01 marked this conversation as resolved.
|
||
|
|
||
| if err := vfs.MkdirAll(filepath.Dir(safePath), 0700); err != nil { | ||
| return output.Errorf(output.ExitInternal, "io", "cannot create parent directory: %v", err) | ||
| } | ||
|
|
||
| sizeBytes, err := validate.AtomicWriteFromReader(safePath, resp.Body, 0600) | ||
| if err != nil { | ||
| return output.Errorf(output.ExitInternal, "io", "cannot create file: %v", err) | ||
| } | ||
|
|
||
| runtime.Out(map[string]interface{}{ | ||
| "saved_path": safePath, | ||
| "size_bytes": sizeBytes, | ||
| "content_type": resp.Header.Get("Content-Type"), | ||
| }, nil) | ||
| return nil | ||
| }, | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,41 @@ | ||
|
|
||
| # docs +media-preview（预览文档素材） | ||
|
|
||
| > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 | ||
|
|
||
| 优先用于查看、预览文档中的图片或文件素材（`file_token`）。命令会把素材保存到本地路径，便于后续打开查看内容。 | ||
|
|
||
| ## 选择规则 | ||
|
|
||
| - 用户说“看一下素材 / 图片 / 附件”“预览一下”时，优先使用 `docs +media-preview` | ||
| - 用户明确说“下载”时，使用 [`docs +media-download`](lark-doc-media-download.md) | ||
| - 如果目标明确是画板 / whiteboard / 画板缩略图，不要使用 `+media-preview`，改用 `docs +media-download --type whiteboard` | ||
|
|
||
| ## 命令 | ||
|
|
||
| ```bash | ||
| # 预览图片/文件素材 | ||
| lark-cli docs +media-preview --token "Z1Fjxxxxxxxx" --output ./asset | ||
|
|
||
| # 指定输出文件名（带扩展名则不会自动补全） | ||
| lark-cli docs +media-preview --token "Z1Fjxxxxxxxx" --output ./asset.png | ||
| ``` | ||
|
|
||
| ## 参数 | ||
|
|
||
| | 参数 | 必填 | 说明 | | ||
| |------|------|------| | ||
| | `--token <token>` | 是 | 素材 token，即 `file_token` | | ||
| | `--output <path>` | 是 | 本地保存路径；不带扩展名会自动补全 | | ||
|
wittam-01 marked this conversation as resolved.
|
||
|
|
||
| ## token 从哪里来 | ||
|
|
||
| - 若你是从文档内容里提取：`lark-doc-fetch` 返回的 Markdown 里可能包含： | ||
| - 图片：`<image token="..." .../>` | ||
| - 文件：`<file token="..." name="..."/>` | ||
|
|
||
| ## 参考 | ||
|
|
||
| - [lark-doc-fetch](lark-doc-fetch.md) — 获取文档内容（用于提取 token） | ||
| - [lark-doc-media-download](lark-doc-media-download.md) — 明确下载素材，或下载画板缩略图 | ||
| - [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数 | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.