mirror of
https://github.com/larksuite/cli.git
synced 2026-07-07 09:11:44 +08:00
Compare commits
1 Commits
docs/lark-
...
backup/fea
| Author | SHA1 | Date | |
|---|---|---|---|
|
3669313759 |
73
shortcuts/minutes/minutes_summary.go
Normal file
73
shortcuts/minutes/minutes_summary.go
Normal file
@@ -0,0 +1,73 @@
|
||||
// Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
||||
// SPDX-License-Identifier: MIT
|
||||
|
||||
package minutes
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"net/http"
|
||||
"strings"
|
||||
|
||||
"github.com/larksuite/cli/internal/output"
|
||||
"github.com/larksuite/cli/internal/validate"
|
||||
"github.com/larksuite/cli/shortcuts/common"
|
||||
)
|
||||
|
||||
const minutesSummaryMarkdownTip = "Summary accepts any text; unsupported Markdown is saved but may display as literal raw text in Minutes. For best rendering, prefer plain text, line breaks, headings (#, ##, ###), bold (**text**), and lists (-, *, or 1.)."
|
||||
|
||||
// MinutesSummary replaces the AI summary of a minute.
|
||||
var MinutesSummary = common.Shortcut{
|
||||
Service: "minutes",
|
||||
Command: "+summary",
|
||||
Description: "Replace the AI summary of a minute",
|
||||
Risk: "write",
|
||||
Scopes: []string{"minutes:minutes:update"},
|
||||
AuthTypes: []string{"user"},
|
||||
HasFormat: true,
|
||||
Flags: []common.Flag{
|
||||
{Name: "minute-token", Desc: "minute token", Required: true},
|
||||
{Name: "summary", Desc: "replacement summary text (Markdown subset renders best in Minutes)", Required: true, Input: []string{common.File, common.Stdin}},
|
||||
},
|
||||
Tips: []string{
|
||||
minutesSummaryMarkdownTip,
|
||||
"Use `lark-cli vc +notes --minute-tokens <token>` to read the current summary before replacing it.",
|
||||
},
|
||||
Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
|
||||
minuteToken := runtime.Str("minute-token")
|
||||
if minuteToken == "" {
|
||||
return output.ErrValidation("--minute-token is required")
|
||||
}
|
||||
if err := validate.ResourceName(minuteToken, "--minute-token"); err != nil {
|
||||
return output.ErrValidation("%s", err)
|
||||
}
|
||||
summary := strings.TrimSpace(runtime.Str("summary"))
|
||||
if summary == "" {
|
||||
return output.ErrValidation("--summary is required")
|
||||
}
|
||||
return nil
|
||||
},
|
||||
DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
|
||||
return common.NewDryRunAPI().
|
||||
PUT(fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/summary", validate.EncodePathSegment(runtime.Str("minute-token")))).
|
||||
Body(map[string]interface{}{"summary": "<summary markdown>"})
|
||||
},
|
||||
Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
|
||||
minuteToken := runtime.Str("minute-token")
|
||||
summary := strings.TrimSpace(runtime.Str("summary"))
|
||||
|
||||
path := fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/summary", validate.EncodePathSegment(minuteToken))
|
||||
body := map[string]interface{}{
|
||||
"summary": summary,
|
||||
}
|
||||
if _, err := runtime.CallAPI(http.MethodPut, path, nil, body); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
runtime.OutFormat(map[string]interface{}{
|
||||
"minute_token": minuteToken,
|
||||
"updated": true,
|
||||
}, nil, nil)
|
||||
return nil
|
||||
},
|
||||
}
|
||||
371
shortcuts/minutes/minutes_summary_todo_test.go
Normal file
371
shortcuts/minutes/minutes_summary_todo_test.go
Normal file
@@ -0,0 +1,371 @@
|
||||
// Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
||||
// SPDX-License-Identifier: MIT
|
||||
|
||||
package minutes
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/larksuite/cli/internal/cmdutil"
|
||||
"github.com/larksuite/cli/internal/httpmock"
|
||||
)
|
||||
|
||||
func todoStub(token string) *httpmock.Stub {
|
||||
return &httpmock.Stub{
|
||||
Method: "POST",
|
||||
URL: "/open-apis/minutes/v1/minutes/" + token + "/todo",
|
||||
Body: map[string]interface{}{"code": 0, "msg": "ok", "data": map[string]interface{}{}},
|
||||
}
|
||||
}
|
||||
|
||||
func firstTodoItem(t *testing.T, raw []byte) map[string]any {
|
||||
t.Helper()
|
||||
items := todoItems(t, raw)
|
||||
if len(items) != 1 {
|
||||
t.Fatalf("todo_items: want 1 item, got %d (%v)", len(items), items)
|
||||
}
|
||||
return items[0]
|
||||
}
|
||||
|
||||
func todoItems(t *testing.T, raw []byte) []map[string]any {
|
||||
t.Helper()
|
||||
if len(raw) == 0 {
|
||||
t.Fatal("request body was not captured")
|
||||
}
|
||||
var body map[string]any
|
||||
if err := json.Unmarshal(raw, &body); err != nil {
|
||||
t.Fatalf("failed to parse captured body: %v", err)
|
||||
}
|
||||
rawItems, _ := body["todo_items"].([]any)
|
||||
items := make([]map[string]any, 0, len(rawItems))
|
||||
for _, rawItem := range rawItems {
|
||||
item, _ := rawItem.(map[string]any)
|
||||
items = append(items, item)
|
||||
}
|
||||
return items
|
||||
}
|
||||
|
||||
func TestMinutesSummary_DryRun(t *testing.T) {
|
||||
f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
|
||||
warmTokenCache(t)
|
||||
|
||||
err := mountAndRun(t, MinutesSummary, []string{
|
||||
"+summary",
|
||||
"--minute-token", "obcn123456789",
|
||||
"--summary", "**Weekly sync**\n- follow up",
|
||||
"--dry-run",
|
||||
"--as", "user",
|
||||
}, f, stdout)
|
||||
if err != nil {
|
||||
t.Fatalf("unexpected error: %v", err)
|
||||
}
|
||||
|
||||
out := stdout.String()
|
||||
if !strings.Contains(out, "PUT") || !strings.Contains(out, "/open-apis/minutes/v1/minutes/obcn123456789/summary") {
|
||||
t.Fatalf("dry-run output = %q", out)
|
||||
}
|
||||
}
|
||||
|
||||
func TestMinutesTodo_DryRun(t *testing.T) {
|
||||
f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
|
||||
warmTokenCache(t)
|
||||
|
||||
err := mountAndRun(t, MinutesTodo, []string{
|
||||
"+todo",
|
||||
"--minute-token", "obcn123456789",
|
||||
"--operation", "add",
|
||||
"--todo", "- finish deck",
|
||||
"--is-done",
|
||||
"--dry-run",
|
||||
"--as", "user",
|
||||
}, f, stdout)
|
||||
if err != nil {
|
||||
t.Fatalf("unexpected error: %v", err)
|
||||
}
|
||||
|
||||
out := stdout.String()
|
||||
if !strings.Contains(out, "POST") || !strings.Contains(out, "/open-apis/minutes/v1/minutes/obcn123456789/todo") {
|
||||
t.Fatalf("dry-run output = %q", out)
|
||||
}
|
||||
if !strings.Contains(out, "todo_items") {
|
||||
t.Fatalf("dry-run output should contain todo_items, got %q", out)
|
||||
}
|
||||
if !strings.Contains(out, "operation") || !strings.Contains(out, "add") {
|
||||
t.Fatalf("dry-run output should contain the operation, got %q", out)
|
||||
}
|
||||
}
|
||||
|
||||
func TestMinutesTodo_RequiresIsDone(t *testing.T) {
|
||||
f, _, stderr, _ := cmdutil.TestFactory(t, defaultConfig())
|
||||
warmTokenCache(t)
|
||||
|
||||
err := mountAndRun(t, MinutesTodo, []string{
|
||||
"+todo",
|
||||
"--minute-token", "obcn123456789",
|
||||
"--operation", "add",
|
||||
"--todo", "finish deck",
|
||||
"--as", "user",
|
||||
}, f, stderr)
|
||||
if err == nil {
|
||||
t.Fatal("expected validation error for missing --is-done")
|
||||
}
|
||||
if !strings.Contains(err.Error(), "is-done") {
|
||||
t.Fatalf("error = %q, want message mentioning is-done", err.Error())
|
||||
}
|
||||
}
|
||||
|
||||
func TestMinutesTodo_RequiresOperation(t *testing.T) {
|
||||
f, _, stderr, _ := cmdutil.TestFactory(t, defaultConfig())
|
||||
warmTokenCache(t)
|
||||
|
||||
err := mountAndRun(t, MinutesTodo, []string{
|
||||
"+todo",
|
||||
"--minute-token", "obcn123456789",
|
||||
"--todo", "finish deck",
|
||||
"--is-done",
|
||||
"--as", "user",
|
||||
}, f, stderr)
|
||||
if err == nil {
|
||||
t.Fatal("expected validation error for missing --operation")
|
||||
}
|
||||
if !strings.Contains(err.Error(), "operation") {
|
||||
t.Fatalf("error = %q, want message mentioning operation", err.Error())
|
||||
}
|
||||
}
|
||||
|
||||
func TestMinutesTodo_RejectsUnknownOperation(t *testing.T) {
|
||||
f, _, stderr, _ := cmdutil.TestFactory(t, defaultConfig())
|
||||
warmTokenCache(t)
|
||||
|
||||
err := mountAndRun(t, MinutesTodo, []string{
|
||||
"+todo",
|
||||
"--minute-token", "obcn123456789",
|
||||
"--operation", "archive",
|
||||
"--todo", "finish deck",
|
||||
"--is-done",
|
||||
"--as", "user",
|
||||
}, f, stderr)
|
||||
if err == nil {
|
||||
t.Fatal("expected validation error for unknown --operation value")
|
||||
}
|
||||
}
|
||||
|
||||
func TestMinutesTodo_Add_RequestBody(t *testing.T) {
|
||||
f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
|
||||
warmTokenCache(t)
|
||||
stub := todoStub("obcn123456789")
|
||||
reg.Register(stub)
|
||||
|
||||
err := mountAndRun(t, MinutesTodo, []string{
|
||||
"+todo", "--minute-token", "obcn123456789",
|
||||
"--operation", "add",
|
||||
"--todo", "finish deck", "--is-done=false", "--as", "user",
|
||||
}, f, stdout)
|
||||
if err != nil {
|
||||
t.Fatalf("unexpected error: %v", err)
|
||||
}
|
||||
|
||||
item := firstTodoItem(t, stub.CapturedBody)
|
||||
if item["operation"] != "add" {
|
||||
t.Errorf("operation = %v, want add", item["operation"])
|
||||
}
|
||||
if item["content"] != "finish deck" {
|
||||
t.Errorf("content = %v, want finish deck", item["content"])
|
||||
}
|
||||
if item["is_done"] != false {
|
||||
t.Errorf("is_done = %v, want false", item["is_done"])
|
||||
}
|
||||
if _, ok := item["todo_id"]; ok {
|
||||
t.Errorf("add should not send todo_id, got %v", item["todo_id"])
|
||||
}
|
||||
if !strings.Contains(stdout.String(), "add") {
|
||||
t.Errorf("output should report add operation, got %q", stdout.String())
|
||||
}
|
||||
}
|
||||
|
||||
func TestMinutesTodo_Update_RequestBody(t *testing.T) {
|
||||
f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
|
||||
warmTokenCache(t)
|
||||
stub := todoStub("obcn123456789")
|
||||
reg.Register(stub)
|
||||
|
||||
err := mountAndRun(t, MinutesTodo, []string{
|
||||
"+todo", "--minute-token", "obcn123456789",
|
||||
"--operation", "update",
|
||||
"--todo-id", "99", "--todo", "updated deck", "--is-done", "--as", "user",
|
||||
}, f, stdout)
|
||||
if err != nil {
|
||||
t.Fatalf("unexpected error: %v", err)
|
||||
}
|
||||
|
||||
item := firstTodoItem(t, stub.CapturedBody)
|
||||
if item["operation"] != "update" {
|
||||
t.Errorf("operation = %v, want update", item["operation"])
|
||||
}
|
||||
if item["todo_id"] != "99" {
|
||||
t.Errorf("todo_id = %v, want 99", item["todo_id"])
|
||||
}
|
||||
if item["content"] != "updated deck" {
|
||||
t.Errorf("content = %v, want updated deck", item["content"])
|
||||
}
|
||||
if item["is_done"] != true {
|
||||
t.Errorf("is_done = %v, want true", item["is_done"])
|
||||
}
|
||||
}
|
||||
|
||||
func TestMinutesTodo_Delete_RequestBody(t *testing.T) {
|
||||
f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
|
||||
warmTokenCache(t)
|
||||
stub := todoStub("obcn123456789")
|
||||
reg.Register(stub)
|
||||
|
||||
err := mountAndRun(t, MinutesTodo, []string{
|
||||
"+todo", "--minute-token", "obcn123456789",
|
||||
"--operation", "delete",
|
||||
"--todo-id", "88", "--as", "user",
|
||||
}, f, stdout)
|
||||
if err != nil {
|
||||
t.Fatalf("unexpected error: %v", err)
|
||||
}
|
||||
|
||||
item := firstTodoItem(t, stub.CapturedBody)
|
||||
if item["operation"] != "delete" {
|
||||
t.Errorf("operation = %v, want delete", item["operation"])
|
||||
}
|
||||
if item["todo_id"] != "88" {
|
||||
t.Errorf("todo_id = %v, want 88", item["todo_id"])
|
||||
}
|
||||
if _, ok := item["content"]; ok {
|
||||
t.Errorf("delete should not send content, got %v", item["content"])
|
||||
}
|
||||
if _, ok := item["is_done"]; ok {
|
||||
t.Errorf("delete should not send is_done, got %v", item["is_done"])
|
||||
}
|
||||
// the todo id must never be surfaced to the user in the command output
|
||||
if strings.Contains(stdout.String(), "88") {
|
||||
t.Errorf("output must not expose the todo id, got %q", stdout.String())
|
||||
}
|
||||
}
|
||||
|
||||
func TestMinutesTodo_DeleteRejectsIsDone(t *testing.T) {
|
||||
f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
|
||||
warmTokenCache(t)
|
||||
|
||||
err := mountAndRun(t, MinutesTodo, []string{
|
||||
"+todo", "--minute-token", "obcn123456789",
|
||||
"--operation", "delete",
|
||||
"--todo-id", "88", "--is-done", "--as", "user",
|
||||
}, f, nil)
|
||||
if err == nil {
|
||||
t.Fatal("expected validation error when --is-done is used to delete")
|
||||
}
|
||||
}
|
||||
|
||||
func TestMinutesTodo_AddRejectsTodoID(t *testing.T) {
|
||||
f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
|
||||
warmTokenCache(t)
|
||||
|
||||
err := mountAndRun(t, MinutesTodo, []string{
|
||||
"+todo", "--minute-token", "obcn123456789",
|
||||
"--operation", "add",
|
||||
"--todo-id", "88", "--todo", "finish deck", "--is-done", "--as", "user",
|
||||
}, f, nil)
|
||||
if err == nil {
|
||||
t.Fatal("expected validation error when --todo-id is used with operation add")
|
||||
}
|
||||
}
|
||||
|
||||
func TestMinutesTodo_BatchAdd_RequestBody(t *testing.T) {
|
||||
f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
|
||||
warmTokenCache(t)
|
||||
stub := todoStub("obcn123456789")
|
||||
reg.Register(stub)
|
||||
|
||||
err := mountAndRun(t, MinutesTodo, []string{
|
||||
"+todo", "--minute-token", "obcn123456789",
|
||||
"--todos", `[{"operation":"add","content":"晚上好1","is_done":true},{"operation":"add","content":"晚上好2","is_done":false}]`,
|
||||
"--as", "user",
|
||||
}, f, stdout)
|
||||
if err != nil {
|
||||
t.Fatalf("unexpected error: %v", err)
|
||||
}
|
||||
|
||||
items := todoItems(t, stub.CapturedBody)
|
||||
if len(items) != 2 {
|
||||
t.Fatalf("todo_items: want 2 items, got %d", len(items))
|
||||
}
|
||||
if items[0]["content"] != "晚上好1" || items[0]["is_done"] != true {
|
||||
t.Errorf("items[0] = %v", items[0])
|
||||
}
|
||||
if items[1]["content"] != "晚上好2" || items[1]["is_done"] != false {
|
||||
t.Errorf("items[1] = %v", items[1])
|
||||
}
|
||||
}
|
||||
|
||||
func TestMinutesTodo_BatchMixed_RequestBody(t *testing.T) {
|
||||
f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
|
||||
warmTokenCache(t)
|
||||
stub := todoStub("obcn123456789")
|
||||
reg.Register(stub)
|
||||
|
||||
err := mountAndRun(t, MinutesTodo, []string{
|
||||
"+todo", "--minute-token", "obcn123456789",
|
||||
"--todos", `[{"operation":"add","content":"new item","is_done":false},{"operation":"update","todo_id":"99","content":"updated","is_done":true},{"operation":"delete","todo_id":"88"}]`,
|
||||
"--as", "user",
|
||||
}, f, stdout)
|
||||
if err != nil {
|
||||
t.Fatalf("unexpected error: %v", err)
|
||||
}
|
||||
|
||||
items := todoItems(t, stub.CapturedBody)
|
||||
if len(items) != 3 {
|
||||
t.Fatalf("todo_items: want 3 items, got %d", len(items))
|
||||
}
|
||||
if items[0]["operation"] != "add" || items[1]["operation"] != "update" || items[2]["operation"] != "delete" {
|
||||
t.Errorf("operations order = %v, %v, %v", items[0]["operation"], items[1]["operation"], items[2]["operation"])
|
||||
}
|
||||
if items[2]["todo_id"] != "88" {
|
||||
t.Errorf("delete todo_id = %v", items[2]["todo_id"])
|
||||
}
|
||||
if !strings.Contains(stdout.String(), `"count"`) {
|
||||
t.Errorf("output should include count, got %q", stdout.String())
|
||||
}
|
||||
}
|
||||
|
||||
func TestMinutesTodo_BatchRejectsSingleFlags(t *testing.T) {
|
||||
f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
|
||||
warmTokenCache(t)
|
||||
|
||||
err := mountAndRun(t, MinutesTodo, []string{
|
||||
"+todo", "--minute-token", "obcn123456789",
|
||||
"--todos", `[{"operation":"add","content":"a","is_done":false}]`,
|
||||
"--operation", "add",
|
||||
"--as", "user",
|
||||
}, f, nil)
|
||||
if err == nil {
|
||||
t.Fatal("expected validation error when --todos is mixed with --operation")
|
||||
}
|
||||
}
|
||||
|
||||
func TestMinutesTodo_RequiresAnyInput(t *testing.T) {
|
||||
f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
|
||||
warmTokenCache(t)
|
||||
|
||||
err := mountAndRun(t, MinutesTodo, []string{
|
||||
"+todo", "--minute-token", "obcn123456789", "--as", "user",
|
||||
}, f, nil)
|
||||
if err == nil {
|
||||
t.Fatal("expected validation error when --operation is not provided")
|
||||
}
|
||||
}
|
||||
|
||||
func TestMinutesSummaryAndTodo_HelpMetadata(t *testing.T) {
|
||||
for _, tip := range MinutesSummary.Tips {
|
||||
if strings.Contains(tip, "raw text") {
|
||||
return
|
||||
}
|
||||
}
|
||||
t.Fatal("MinutesSummary tips should mention unsupported markdown display behavior")
|
||||
}
|
||||
280
shortcuts/minutes/minutes_todo.go
Normal file
280
shortcuts/minutes/minutes_todo.go
Normal file
@@ -0,0 +1,280 @@
|
||||
// Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
||||
// SPDX-License-Identifier: MIT
|
||||
|
||||
package minutes
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"net/http"
|
||||
"strings"
|
||||
|
||||
"github.com/larksuite/cli/internal/output"
|
||||
"github.com/larksuite/cli/internal/validate"
|
||||
"github.com/larksuite/cli/shortcuts/common"
|
||||
)
|
||||
|
||||
// minuteTodoOp describes a resolved todo_items entry derived from flags or JSON.
|
||||
type minuteTodoOp struct {
|
||||
operation string // add | update | delete
|
||||
item map[string]interface{} // the todo_items entry sent to the API
|
||||
}
|
||||
|
||||
// minuteTodoSpec is the JSON shape for --todos batch input.
|
||||
type minuteTodoSpec struct {
|
||||
Operation string `json:"operation"`
|
||||
Content string `json:"content"`
|
||||
IsDone *bool `json:"is_done"`
|
||||
TodoID string `json:"todo_id"`
|
||||
}
|
||||
|
||||
// MinutesTodo adds, updates, or deletes todo item(s) on a minute.
|
||||
var MinutesTodo = common.Shortcut{
|
||||
Service: "minutes",
|
||||
Command: "+todo",
|
||||
Description: "Add, update, or delete todo item(s) on a minute",
|
||||
Risk: "write",
|
||||
Scopes: []string{"minutes:minutes:update"},
|
||||
AuthTypes: []string{"user"},
|
||||
HasFormat: true,
|
||||
Flags: []common.Flag{
|
||||
{Name: "minute-token", Desc: "minute token (required)", Required: true},
|
||||
{Name: "operation", Desc: "operation for a single todo (required unless --todos)", Enum: []string{"add", "update", "delete"}},
|
||||
{Name: "todo", Desc: "todo plain-text content; required by single add/update", Input: []string{common.File, common.Stdin}},
|
||||
{Name: "is-done", Type: "bool", Desc: "completion flag; required by single add/update"},
|
||||
{Name: "todo-id", Desc: "id of an existing todo; required by single update/delete"},
|
||||
{
|
||||
Name: "todos",
|
||||
Desc: `batch todo_items JSON array; each item has operation add|update|delete (supports @file / @-)`,
|
||||
Input: []string{common.File, common.Stdin},
|
||||
},
|
||||
},
|
||||
Tips: []string{
|
||||
"Single todo: `--operation add --todo \"...\" --is-done=false`.",
|
||||
"Batch: `--todos '[{\"operation\":\"add\",\"content\":\"...\",\"is_done\":false}, ...]'` or `--todos @todos.json`.",
|
||||
"Batch can mix add, update, and delete in one request; array order is preserved in the API body.",
|
||||
"Update: `--operation update --todo-id <id> --todo \"...\" --is-done`.",
|
||||
"Delete: `--operation delete --todo-id <id>`.",
|
||||
"`content` is plain text only; markdown formatting is not supported.",
|
||||
"Use `lark-cli vc +notes --minute-tokens <token>` to read current todos before writing.",
|
||||
},
|
||||
Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
|
||||
minuteToken := runtime.Str("minute-token")
|
||||
if minuteToken == "" {
|
||||
return output.ErrValidation("--minute-token is required")
|
||||
}
|
||||
if err := validate.ResourceName(minuteToken, "--minute-token"); err != nil {
|
||||
return output.ErrValidation("%s", err)
|
||||
}
|
||||
if _, err := resolveMinuteTodoOps(runtime); err != nil {
|
||||
return err
|
||||
}
|
||||
return nil
|
||||
},
|
||||
DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
|
||||
api := common.NewDryRunAPI().
|
||||
POST(fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/todo", validate.EncodePathSegment(runtime.Str("minute-token"))))
|
||||
ops, err := resolveMinuteTodoOps(runtime)
|
||||
if err != nil {
|
||||
return api.Body(map[string]interface{}{
|
||||
"todo_items": "<todo_items array>",
|
||||
})
|
||||
}
|
||||
return api.Body(map[string]interface{}{
|
||||
"todo_items": todoItemsFromOps(ops),
|
||||
})
|
||||
},
|
||||
Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
|
||||
minuteToken := runtime.Str("minute-token")
|
||||
ops, err := resolveMinuteTodoOps(runtime)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
path := fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/todo", validate.EncodePathSegment(minuteToken))
|
||||
body := map[string]interface{}{
|
||||
"todo_items": todoItemsFromOps(ops),
|
||||
}
|
||||
if _, err := runtime.CallAPI(http.MethodPost, path, nil, body); err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
out := map[string]interface{}{
|
||||
"minute_token": minuteToken,
|
||||
"count": len(ops),
|
||||
"updated": true,
|
||||
}
|
||||
if len(ops) == 1 {
|
||||
out["operation"] = ops[0].operation
|
||||
}
|
||||
runtime.OutFormat(out, nil, nil)
|
||||
return nil
|
||||
},
|
||||
}
|
||||
|
||||
func todoItemsFromOps(ops []minuteTodoOp) []interface{} {
|
||||
items := make([]interface{}, len(ops))
|
||||
for i, op := range ops {
|
||||
items[i] = op.item
|
||||
}
|
||||
return items
|
||||
}
|
||||
|
||||
// resolveMinuteTodoOps builds todo_items from either --todos (batch) or single-item flags.
|
||||
func resolveMinuteTodoOps(runtime *common.RuntimeContext) ([]minuteTodoOp, error) {
|
||||
hasTodos := strings.TrimSpace(runtime.Str("todos")) != ""
|
||||
hasSingle := runtime.Changed("operation") || runtime.Changed("todo") ||
|
||||
runtime.Changed("is-done") || runtime.Changed("todo-id")
|
||||
|
||||
if hasTodos && hasSingle {
|
||||
return nil, output.ErrValidation("use either --todos for batch or single-item flags (--operation, --todo, --is-done, --todo-id), not both")
|
||||
}
|
||||
if hasTodos {
|
||||
return resolveMinuteTodoBatch(runtime.Str("todos"))
|
||||
}
|
||||
op, err := resolveMinuteTodoSingle(runtime)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return []minuteTodoOp{*op}, nil
|
||||
}
|
||||
|
||||
func resolveMinuteTodoBatch(raw string) ([]minuteTodoOp, error) {
|
||||
specs, err := parseMinuteTodoSpecs(raw)
|
||||
if err != nil {
|
||||
return nil, output.ErrValidation("--todos: %s", err)
|
||||
}
|
||||
if len(specs) == 0 {
|
||||
return nil, output.ErrValidation("--todos must contain at least one todo item")
|
||||
}
|
||||
ops := make([]minuteTodoOp, 0, len(specs))
|
||||
for i, spec := range specs {
|
||||
item, err := buildMinuteTodoItem(spec)
|
||||
if err != nil {
|
||||
return nil, output.ErrValidation("todos[%d]: %s", i, err)
|
||||
}
|
||||
ops = append(ops, minuteTodoOp{
|
||||
operation: strings.TrimSpace(spec.Operation),
|
||||
item: item,
|
||||
})
|
||||
}
|
||||
return ops, nil
|
||||
}
|
||||
|
||||
func parseMinuteTodoSpecs(raw string) ([]minuteTodoSpec, error) {
|
||||
raw = strings.TrimSpace(raw)
|
||||
if raw == "" {
|
||||
return nil, fmt.Errorf("value is empty")
|
||||
}
|
||||
var specs []minuteTodoSpec
|
||||
if err := json.Unmarshal([]byte(raw), &specs); err != nil {
|
||||
return nil, fmt.Errorf("invalid JSON array: %w", err)
|
||||
}
|
||||
return specs, nil
|
||||
}
|
||||
|
||||
func resolveMinuteTodoSingle(runtime *common.RuntimeContext) (*minuteTodoOp, error) {
|
||||
operation := strings.TrimSpace(runtime.Str("operation"))
|
||||
todo := strings.TrimSpace(runtime.Str("todo"))
|
||||
todoID := strings.TrimSpace(runtime.Str("todo-id"))
|
||||
hasTodo := todo != ""
|
||||
hasTodoID := todoID != ""
|
||||
hasIsDone := runtime.Changed("is-done")
|
||||
|
||||
if operation == "" {
|
||||
return nil, output.ErrValidation("--operation is required for single-item mode (or use --todos for batch)")
|
||||
}
|
||||
|
||||
spec := minuteTodoSpec{Operation: operation}
|
||||
switch operation {
|
||||
case "add":
|
||||
if !hasTodo || !hasIsDone {
|
||||
return nil, output.ErrValidation("operation \"add\" requires --todo and --is-done")
|
||||
}
|
||||
if hasTodoID {
|
||||
return nil, output.ErrValidation("operation \"add\" does not accept --todo-id (it creates a new todo)")
|
||||
}
|
||||
done := runtime.Bool("is-done")
|
||||
spec.Content = todo
|
||||
spec.IsDone = &done
|
||||
case "update":
|
||||
if !hasTodoID || !hasTodo || !hasIsDone {
|
||||
return nil, output.ErrValidation("operation \"update\" requires --todo-id, --todo and --is-done")
|
||||
}
|
||||
done := runtime.Bool("is-done")
|
||||
spec.TodoID = todoID
|
||||
spec.Content = todo
|
||||
spec.IsDone = &done
|
||||
case "delete":
|
||||
if !hasTodoID {
|
||||
return nil, output.ErrValidation("operation \"delete\" requires --todo-id")
|
||||
}
|
||||
if hasTodo || hasIsDone {
|
||||
return nil, output.ErrValidation("operation \"delete\" only accepts --todo-id (omit --todo and --is-done)")
|
||||
}
|
||||
spec.TodoID = todoID
|
||||
default:
|
||||
return nil, output.ErrValidation("--operation is required, allowed: add, update, delete")
|
||||
}
|
||||
|
||||
item, err := buildMinuteTodoItem(spec)
|
||||
if err != nil {
|
||||
return nil, output.ErrValidation("%s", err)
|
||||
}
|
||||
return &minuteTodoOp{operation: operation, item: item}, nil
|
||||
}
|
||||
|
||||
func buildMinuteTodoItem(spec minuteTodoSpec) (map[string]interface{}, error) {
|
||||
operation := strings.TrimSpace(spec.Operation)
|
||||
if operation == "" {
|
||||
return nil, fmt.Errorf("operation is required")
|
||||
}
|
||||
if operation != "add" && operation != "update" && operation != "delete" {
|
||||
return nil, fmt.Errorf("operation %q is invalid, allowed: add, update, delete", operation)
|
||||
}
|
||||
|
||||
content := strings.TrimSpace(spec.Content)
|
||||
todoID := strings.TrimSpace(spec.TodoID)
|
||||
item := map[string]interface{}{"operation": operation}
|
||||
|
||||
switch operation {
|
||||
case "add":
|
||||
if todoID != "" {
|
||||
return nil, fmt.Errorf("operation \"add\" does not accept todo_id")
|
||||
}
|
||||
if content == "" {
|
||||
return nil, fmt.Errorf("operation \"add\" requires content")
|
||||
}
|
||||
if spec.IsDone == nil {
|
||||
return nil, fmt.Errorf("operation \"add\" requires is_done")
|
||||
}
|
||||
item["content"] = content
|
||||
item["is_done"] = *spec.IsDone
|
||||
case "update":
|
||||
if todoID == "" {
|
||||
return nil, fmt.Errorf("operation \"update\" requires todo_id")
|
||||
}
|
||||
if content == "" {
|
||||
return nil, fmt.Errorf("operation \"update\" requires content")
|
||||
}
|
||||
if spec.IsDone == nil {
|
||||
return nil, fmt.Errorf("operation \"update\" requires is_done")
|
||||
}
|
||||
item["todo_id"] = todoID
|
||||
item["content"] = content
|
||||
item["is_done"] = *spec.IsDone
|
||||
case "delete":
|
||||
if todoID == "" {
|
||||
return nil, fmt.Errorf("operation \"delete\" requires todo_id")
|
||||
}
|
||||
if content != "" {
|
||||
return nil, fmt.Errorf("operation \"delete\" must not include content")
|
||||
}
|
||||
if spec.IsDone != nil {
|
||||
return nil, fmt.Errorf("operation \"delete\" must not include is_done")
|
||||
}
|
||||
item["todo_id"] = todoID
|
||||
}
|
||||
return item, nil
|
||||
}
|
||||
166
shortcuts/minutes/minutes_word_replace.go
Normal file
166
shortcuts/minutes/minutes_word_replace.go
Normal file
@@ -0,0 +1,166 @@
|
||||
// Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
||||
// SPDX-License-Identifier: MIT
|
||||
|
||||
package minutes
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"net/http"
|
||||
"strings"
|
||||
|
||||
"github.com/larksuite/cli/internal/output"
|
||||
"github.com/larksuite/cli/internal/validate"
|
||||
"github.com/larksuite/cli/shortcuts/common"
|
||||
)
|
||||
|
||||
const (
|
||||
minutesWordReplaceNoEditPermission = 40005
|
||||
minutesWordReplaceOthersEditing = 40110
|
||||
)
|
||||
|
||||
type transcriptWordReplace struct {
|
||||
SourceWord string `json:"source_word"`
|
||||
TargetWord string `json:"target_word"`
|
||||
}
|
||||
|
||||
// MinutesWordReplace batch-replaces words in a minute's transcript.
|
||||
var MinutesWordReplace = common.Shortcut{
|
||||
Service: "minutes",
|
||||
Command: "+word-replace",
|
||||
Description: "Batch replace words in a minute's transcript",
|
||||
Risk: "write",
|
||||
Scopes: []string{"minutes:minutes:update"},
|
||||
AuthTypes: []string{"user"},
|
||||
HasFormat: true,
|
||||
Flags: []common.Flag{
|
||||
{Name: "minute-token", Desc: "minute token", Required: true},
|
||||
{
|
||||
Name: "replace-words",
|
||||
Desc: `JSON array of replacements, e.g. [{"source_word":"old","target_word":"new"}]`,
|
||||
Required: true,
|
||||
Input: []string{common.File, common.Stdin},
|
||||
},
|
||||
},
|
||||
Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
|
||||
minuteToken := strings.TrimSpace(runtime.Str("minute-token"))
|
||||
if minuteToken == "" {
|
||||
return output.ErrValidation("--minute-token is required")
|
||||
}
|
||||
if err := validate.ResourceName(minuteToken, "--minute-token"); err != nil {
|
||||
return output.ErrValidation("%s", err)
|
||||
}
|
||||
if _, err := parseReplaceWords(runtime.Str("replace-words")); err != nil {
|
||||
return output.ErrValidation("--replace-words: %s", err)
|
||||
}
|
||||
return nil
|
||||
},
|
||||
DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
|
||||
minuteToken := strings.TrimSpace(runtime.Str("minute-token"))
|
||||
replaceWords, _ := parseReplaceWords(runtime.Str("replace-words"))
|
||||
return common.NewDryRunAPI().
|
||||
PUT(fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/transcript/word", validate.EncodePathSegment(minuteToken))).
|
||||
Body(map[string]interface{}{
|
||||
"minute_token": minuteToken,
|
||||
"replace_words": replaceWords,
|
||||
})
|
||||
},
|
||||
Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
|
||||
minuteToken := strings.TrimSpace(runtime.Str("minute-token"))
|
||||
replaceWords, err := parseReplaceWords(runtime.Str("replace-words"))
|
||||
if err != nil {
|
||||
return output.ErrValidation("--replace-words: %s", err)
|
||||
}
|
||||
|
||||
body := map[string]interface{}{
|
||||
"minute_token": minuteToken,
|
||||
"replace_words": replaceWords,
|
||||
}
|
||||
|
||||
_, err = runtime.CallAPI(http.MethodPut,
|
||||
fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/transcript/word", validate.EncodePathSegment(minuteToken)),
|
||||
nil, body)
|
||||
if err != nil {
|
||||
return minutesWordReplaceError(err, minuteToken)
|
||||
}
|
||||
|
||||
outData := map[string]interface{}{
|
||||
"minute_token": minuteToken,
|
||||
"replace_words": replaceWords,
|
||||
}
|
||||
|
||||
runtime.OutFormat(outData, nil, nil)
|
||||
return nil
|
||||
},
|
||||
}
|
||||
|
||||
func parseReplaceWords(raw string) ([]map[string]string, error) {
|
||||
raw = strings.TrimSpace(raw)
|
||||
if raw == "" {
|
||||
return nil, errors.New("value is required")
|
||||
}
|
||||
|
||||
var items []transcriptWordReplace
|
||||
if err := json.Unmarshal([]byte(raw), &items); err != nil {
|
||||
return nil, fmt.Errorf("must be a JSON array of {source_word,target_word} objects: %v", err)
|
||||
}
|
||||
if len(items) == 0 {
|
||||
return nil, errors.New("must include at least one replacement")
|
||||
}
|
||||
|
||||
replaceWords := make([]map[string]string, 0, len(items))
|
||||
seen := make(map[string]struct{}, len(items))
|
||||
for i, item := range items {
|
||||
sourceWord := strings.TrimSpace(item.SourceWord)
|
||||
if sourceWord == "" {
|
||||
return nil, fmt.Errorf("item %d: source_word is required", i)
|
||||
}
|
||||
if _, exists := seen[sourceWord]; exists {
|
||||
return nil, fmt.Errorf("duplicate source_word %q", sourceWord)
|
||||
}
|
||||
seen[sourceWord] = struct{}{}
|
||||
replaceWords = append(replaceWords, map[string]string{
|
||||
"source_word": sourceWord,
|
||||
"target_word": item.TargetWord,
|
||||
})
|
||||
}
|
||||
return replaceWords, nil
|
||||
}
|
||||
|
||||
func minutesWordReplaceError(err error, minuteToken string) error {
|
||||
var exitErr *output.ExitError
|
||||
if !errors.As(err, &exitErr) || exitErr.Detail == nil {
|
||||
return err
|
||||
}
|
||||
|
||||
switch exitErr.Detail.Code {
|
||||
case minutesWordReplaceNoEditPermission:
|
||||
return &output.ExitError{
|
||||
Code: output.ExitAPI,
|
||||
Detail: &output.ErrDetail{
|
||||
Type: "no_edit_permission",
|
||||
Code: minutesWordReplaceNoEditPermission,
|
||||
Message: fmt.Sprintf("No edit permission for minute %q: cannot replace transcript words.", minuteToken),
|
||||
Hint: "Ask the minute owner for minute edit permission",
|
||||
Detail: exitErr.Detail.Detail,
|
||||
},
|
||||
Err: err,
|
||||
}
|
||||
case minutesWordReplaceOthersEditing:
|
||||
return &output.ExitError{
|
||||
Code: output.ExitAPI,
|
||||
Detail: &output.ErrDetail{
|
||||
Type: "others_are_editing",
|
||||
Code: minutesWordReplaceOthersEditing,
|
||||
Message: fmt.Sprintf("Minute %q transcript is being edited by someone else.", minuteToken),
|
||||
Hint: "Wait until the other editor finishes, then retry",
|
||||
Detail: exitErr.Detail.Detail,
|
||||
},
|
||||
Err: err,
|
||||
}
|
||||
}
|
||||
|
||||
return err
|
||||
}
|
||||
210
shortcuts/minutes/minutes_word_replace_test.go
Normal file
210
shortcuts/minutes/minutes_word_replace_test.go
Normal file
@@ -0,0 +1,210 @@
|
||||
// Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
||||
// SPDX-License-Identifier: MIT
|
||||
|
||||
package minutes
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"net/http"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/larksuite/cli/internal/cmdutil"
|
||||
"github.com/larksuite/cli/internal/httpmock"
|
||||
"github.com/larksuite/cli/internal/output"
|
||||
"github.com/spf13/cobra"
|
||||
)
|
||||
|
||||
const minutesWordReplaceTestToken = "obcnexampleminute"
|
||||
|
||||
func TestMinutesWordReplace_Validate(t *testing.T) {
|
||||
t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
|
||||
f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
|
||||
tests := []struct {
|
||||
name string
|
||||
args []string
|
||||
wantErr string
|
||||
}{
|
||||
{
|
||||
name: "missing minute token",
|
||||
args: []string{"+word-replace", "--replace-words", `[{"source_word":"a","target_word":"b"}]`, "--as", "user"},
|
||||
wantErr: "required flag(s) \"minute-token\" not set",
|
||||
},
|
||||
{
|
||||
name: "missing replace words",
|
||||
args: []string{"+word-replace", "--minute-token", "obcn123456", "--as", "user"},
|
||||
wantErr: "required flag(s) \"replace-words\" not set",
|
||||
},
|
||||
{
|
||||
name: "invalid json",
|
||||
args: []string{"+word-replace", "--minute-token", "obcn123456", "--replace-words", "not-json", "--as", "user"},
|
||||
wantErr: "JSON array",
|
||||
},
|
||||
{
|
||||
name: "empty source word",
|
||||
args: []string{"+word-replace", "--minute-token", "obcn123456", "--replace-words", `[{"source_word":"","target_word":"b"}]`, "--as", "user"},
|
||||
wantErr: "source_word is required",
|
||||
},
|
||||
{
|
||||
name: "duplicate source word",
|
||||
args: []string{"+word-replace", "--minute-token", "obcn123456", "--replace-words", `[{"source_word":"a","target_word":"b"},{"source_word":"a","target_word":"c"}]`, "--as", "user"},
|
||||
wantErr: "duplicate source_word",
|
||||
},
|
||||
}
|
||||
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
parent := &cobra.Command{Use: "minutes"}
|
||||
MinutesWordReplace.Mount(parent, f)
|
||||
parent.SetArgs(tt.args)
|
||||
parent.SilenceErrors = true
|
||||
parent.SilenceUsage = true
|
||||
err := parent.Execute()
|
||||
if err == nil {
|
||||
t.Fatalf("expected error, got nil")
|
||||
}
|
||||
if !strings.Contains(err.Error(), tt.wantErr) {
|
||||
t.Errorf("error should contain %q, got: %s", tt.wantErr, err.Error())
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestMinutesWordReplace_DryRun(t *testing.T) {
|
||||
t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
|
||||
f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
|
||||
warmTokenCache(t)
|
||||
|
||||
err := mountAndRun(t, MinutesWordReplace, []string{
|
||||
"+word-replace",
|
||||
"--minute-token", minutesWordReplaceTestToken,
|
||||
"--replace-words", `[{"source_word":"foo","target_word":"bar"}]`,
|
||||
"--dry-run", "--as", "user",
|
||||
}, f, stdout)
|
||||
if err != nil {
|
||||
t.Fatalf("unexpected error: %v", err)
|
||||
}
|
||||
|
||||
out := stdout.String()
|
||||
if !strings.Contains(out, "PUT") {
|
||||
t.Errorf("expected PUT method, got:\n%s", out)
|
||||
}
|
||||
if !strings.Contains(out, "/open-apis/minutes/v1/minutes/"+minutesWordReplaceTestToken+"/transcript/word") {
|
||||
t.Errorf("expected word endpoint, got:\n%s", out)
|
||||
}
|
||||
if !strings.Contains(out, "foo") || !strings.Contains(out, "bar") {
|
||||
t.Errorf("expected replace_words in body, got:\n%s", out)
|
||||
}
|
||||
}
|
||||
|
||||
func TestMinutesWordReplace_Execute(t *testing.T) {
|
||||
t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
|
||||
f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
|
||||
warmTokenCache(t)
|
||||
|
||||
reg.Register(&httpmock.Stub{
|
||||
Method: http.MethodPut,
|
||||
URL: "/open-apis/minutes/v1/minutes/" + minutesWordReplaceTestToken + "/transcript/word",
|
||||
Body: map[string]interface{}{
|
||||
"code": 0,
|
||||
"msg": "ok",
|
||||
"data": map[string]interface{}{},
|
||||
},
|
||||
})
|
||||
|
||||
err := mountAndRun(t, MinutesWordReplace, []string{
|
||||
"+word-replace",
|
||||
"--minute-token", minutesWordReplaceTestToken,
|
||||
"--replace-words", `[{"source_word":"foo","target_word":"bar"}]`,
|
||||
"--format", "json", "--as", "user",
|
||||
}, f, stdout)
|
||||
if err != nil {
|
||||
t.Fatalf("unexpected error: %v", err)
|
||||
}
|
||||
|
||||
var envelope struct {
|
||||
Data struct {
|
||||
MinuteToken string `json:"minute_token"`
|
||||
ReplaceWords []struct {
|
||||
SourceWord string `json:"source_word"`
|
||||
TargetWord string `json:"target_word"`
|
||||
} `json:"replace_words"`
|
||||
} `json:"data"`
|
||||
}
|
||||
if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
|
||||
t.Fatalf("unmarshal stdout: %v", err)
|
||||
}
|
||||
if envelope.Data.MinuteToken != minutesWordReplaceTestToken {
|
||||
t.Errorf("data.minute_token = %q, want %q", envelope.Data.MinuteToken, minutesWordReplaceTestToken)
|
||||
}
|
||||
if len(envelope.Data.ReplaceWords) != 1 || envelope.Data.ReplaceWords[0].SourceWord != "foo" || envelope.Data.ReplaceWords[0].TargetWord != "bar" {
|
||||
t.Errorf("data.replace_words = %#v, want foo->bar", envelope.Data.ReplaceWords)
|
||||
}
|
||||
}
|
||||
|
||||
func TestMinutesWordReplace_NoEditPermission(t *testing.T) {
|
||||
t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
|
||||
f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
|
||||
warmTokenCache(t)
|
||||
|
||||
reg.Register(&httpmock.Stub{
|
||||
Method: http.MethodPut,
|
||||
URL: "/open-apis/minutes/v1/minutes/" + minutesWordReplaceTestToken + "/transcript/word",
|
||||
Body: map[string]interface{}{
|
||||
"code": minutesWordReplaceNoEditPermission,
|
||||
"msg": "permission deny",
|
||||
},
|
||||
})
|
||||
|
||||
err := mountAndRun(t, MinutesWordReplace, []string{
|
||||
"+word-replace",
|
||||
"--minute-token", minutesWordReplaceTestToken,
|
||||
"--replace-words", `[{"source_word":"foo","target_word":"bar"}]`,
|
||||
"--format", "json", "--as", "user",
|
||||
}, f, stdout)
|
||||
if err == nil {
|
||||
t.Fatal("expected no-edit-permission error, got nil")
|
||||
}
|
||||
|
||||
var exitErr *output.ExitError
|
||||
if !errors.As(err, &exitErr) {
|
||||
t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
|
||||
}
|
||||
if exitErr.Detail == nil || exitErr.Detail.Type != "no_edit_permission" {
|
||||
t.Fatalf("expected no_edit_permission detail, got %#v", exitErr.Detail)
|
||||
}
|
||||
}
|
||||
|
||||
func TestMinutesWordReplace_OthersAreEditing(t *testing.T) {
|
||||
t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
|
||||
f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
|
||||
warmTokenCache(t)
|
||||
|
||||
reg.Register(&httpmock.Stub{
|
||||
Method: http.MethodPut,
|
||||
URL: "/open-apis/minutes/v1/minutes/" + minutesWordReplaceTestToken + "/transcript/word",
|
||||
Body: map[string]interface{}{
|
||||
"code": minutesWordReplaceOthersEditing,
|
||||
"msg": "others are editing",
|
||||
},
|
||||
})
|
||||
|
||||
err := mountAndRun(t, MinutesWordReplace, []string{
|
||||
"+word-replace",
|
||||
"--minute-token", minutesWordReplaceTestToken,
|
||||
"--replace-words", `[{"source_word":"foo","target_word":"bar"}]`,
|
||||
"--format", "json", "--as", "user",
|
||||
}, f, stdout)
|
||||
if err == nil {
|
||||
t.Fatal("expected others-are-editing error, got nil")
|
||||
}
|
||||
|
||||
var exitErr *output.ExitError
|
||||
if !errors.As(err, &exitErr) {
|
||||
t.Fatalf("expected *output.ExitError, got %T: %v", err, err)
|
||||
}
|
||||
if exitErr.Detail == nil || exitErr.Detail.Type != "others_are_editing" {
|
||||
t.Fatalf("expected others_are_editing detail, got %#v", exitErr.Detail)
|
||||
}
|
||||
}
|
||||
@@ -12,6 +12,9 @@ func Shortcuts() []common.Shortcut {
|
||||
MinutesDownload,
|
||||
MinutesUpload,
|
||||
MinutesUpdate,
|
||||
MinutesSummary,
|
||||
MinutesTodo,
|
||||
MinutesSpeakerReplace,
|
||||
MinutesWordReplace,
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,67 +1,211 @@
|
||||
|
||||
> **术语说明：** 飞书云空间也常被称为"云盘"或"云存储"，三者指的是同一个产品，是飞书官方的云端文件存储与管理中心。
|
||||
|
||||
## 关键规则速览
|
||||
|
||||
- Wiki 链接里的 `/wiki/<token>` 不是底层文件 token；优先用 `drive +inspect` 解包，完整规则见 [`lark-wiki-token-routing.md`](../lark-shared/references/lark-wiki-token-routing.md)。
|
||||
- 本地文件导入为在线文档统一走 `drive +import`：目标是 Base / 多维表格时用 `--type bitable`（`.xlsx` / `.csv` / `.base`，`.xls` 不支持）；目标是电子表格时用 `--type sheet`（`.xlsx` / `.xls` / `.csv`）；Office / Markdown / HTML / TXT -> `--type docx`，PPTX -> `--type slides`。
|
||||
- 原生 `.md` 文件内容读写、patch、diff 走 [`lark-markdown`](../lark-markdown/SKILL.md)；把 Markdown 转成在线 docx 才走 `drive +import --type docx`。
|
||||
- 评论默认只查未解决评论；review / 审阅场景优先局部评论。评论细节见 [`lark-drive-comments-guide.md`](references/lark-drive-comments-guide.md)。
|
||||
- 权限申请、安全标签、搜索等用户个人资源场景优先 `--as user`；bot 只能处理自己可见或已授权的资源。
|
||||
> **导入分流规则：** 如果用户要把本地 Excel / CSV / `.base` 快照导入成 Base / 多维表格 / bitable，必须优先使用 `lark-cli drive +import --type bitable`。不要先切到 `lark-base`；`lark-base` 只负责导入完成后的表内操作。
|
||||
|
||||
## 快速决策
|
||||
|
||||
- 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间对象**，优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"（`--mine`，owner 语义）、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag。
|
||||
- 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`；`.xls` 不能直接导入为 bitable，需先转 `.xlsx` 或改导入为 sheet。
|
||||
- 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。
|
||||
- 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档，使用 `lark-cli drive +import --type docx`。
|
||||
- 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格，使用 `lark-cli drive +import --type sheet`。
|
||||
- 用户要把本地 `.pptx` 导入成飞书幻灯片，使用 `lark-cli drive +import --type slides`；当前 PPTX 导入上限是 500MB。
|
||||
- 用户要在 Drive 里上传、创建、读取、局部 patch 或覆盖更新**原生 `.md` 文件**（不是导入成 docx），切到 [`lark-markdown`](../lark-markdown/SKILL.md)。
|
||||
- 用户要比较原生 `.md` 文件的历史版本差异，或比较远端 Markdown 与本地草稿，切到 [`lark-markdown`](../lark-markdown/SKILL.md) 的 `lark-cli markdown +diff`；需要版本号时先用 `drive +version-history`。
|
||||
- 用户要查看、下载、回滚或删除文件的历史版本，使用 `drive +version-history`、`drive +version-get`、`drive +version-revert`、`drive +version-delete`；自动化场景优先 `--as bot`。
|
||||
- 用户要在云空间里新建文件夹，优先使用 `lark-cli drive +create-folder`。
|
||||
- 用户要把本地文件上传到知识库 / 文档库里的某个 wiki 节点下，仍然使用 `lark-cli drive +upload --wiki-token <wiki_token>`；不要误切到 `wiki` 域命令。
|
||||
- 用户要修改标题，可用 `drive files patch` 传 `new_title`，支持 docx、sheet、bitable、file、wiki、folder 类型。
|
||||
- `lark-base` 只负责导入完成后的 Base 内部操作（表、字段、记录、视图），不要在“本地文件 -> Base”这一步提前切到 `lark-base`。
|
||||
|
||||
## 身份路由
|
||||
|
||||
| 场景 | 身份建议 |
|
||||
|------|----------|
|
||||
| 搜索用户可见资源、申请权限、查看/更新安全标签 | 使用 `--as user`；这些 shortcut 是 user-only 或强依赖用户可见范围 |
|
||||
| 用户个人云空间、用户拥有的文档/文件夹 | 默认 `--as user` |
|
||||
| bot 自己创建的资源、已授权给 bot 的资源、自动化版本操作 | 可用 `--as bot`；版本命令自动化场景优先 bot |
|
||||
| bot 因资源不可见失败 | 不要反复重试；提示用户切 `--as user`，或先把资源授权给当前应用 |
|
||||
## 修改标题
|
||||
- 使用 `drive files patch` 命令，通过new_title字段可以修改标题，支持 docx、sheet、bitable、file、wiki、folder 类型
|
||||
|
||||
## 核心概念
|
||||
|
||||
- 直接文档 URL（如 `/docx/`、`/doc/`、`/sheets/`、`/drive/folder/`）通常可从路径直接取得对应 token。
|
||||
- Wiki URL（`/wiki/<token>`）必须先解析到底层 `obj_type` 和 `obj_token`，再决定后续调用哪个域。
|
||||
- `drive +inspect` 是跨类型 URL 检视的首选入口；当它输出 `type` 和 `token` 后，后续命令使用该 canonical token。
|
||||
- 原生 API 调用前先运行 `lark-cli schema drive.<resource>.<method>` 查看 `--params` / `--data` 结构；不要猜字段。
|
||||
### 文档类型与 Token
|
||||
|
||||
## 原生 API 快速索引
|
||||
飞书开放平台中，不同类型的文档有不同的 URL 格式和 Token 处理方式。在进行文档操作（如添加评论、下载文件等）时，必须先获取正确的 `file_token`。
|
||||
|
||||
- 评论订阅事件：`drive user.subscription`、`drive user.subscription_status`、`drive user.remove_subscription`。
|
||||
- 公开权限设置：`drive permission.public get|patch`；错误码和处理建议见 [`lark-drive-permission-guide.md`](references/lark-drive-permission-guide.md)。
|
||||
- 协作者权限：`drive permission.members create|auth|transfer_owner`；授权当前应用访问文档见权限 guide，转移 owner 必须单独确认。
|
||||
- 元数据、统计、访问记录：`drive metas batch_query`、`drive file.statistics get`、`drive file.view_records list`。
|
||||
- 评论列表、解决状态、回复：`drive file.comments list|batch_query|patch`、`drive file.comment.replys *`；统计口径见评论 guide。
|
||||
### 文档 URL 格式与 Token 处理
|
||||
|
||||
## 评论与权限
|
||||
| URL 格式 | 示例 | Token 类型 | 处理方式 |
|
||||
|----------|---------------------------------------------------------|-----------|----------|
|
||||
| `/docx/` | `https://example.larksuite.com/docx/doxcnxxxxxxxxx` | `file_token` | URL 路径中的 token 直接作为 `file_token` 使用 |
|
||||
| `/doc/` | `https://example.larksuite.com/doc/doccnxxxxxxxxx` | `file_token` | URL 路径中的 token 直接作为 `file_token` 使用 |
|
||||
| `/wiki/` | `https://example.larksuite.com/wiki/wikcnxxxxxxxxx` | `wiki_token` | ⚠️ **不能直接使用**，需要先查询获取真实的 `obj_token` |
|
||||
| `/sheets/` | `https://example.larksuite.com/sheets/shtcnxxxxxxxxx` | `file_token` | URL 路径中的 token 直接作为 `file_token` 使用 |
|
||||
| `/drive/folder/` | `https://example.larksuite.com/drive/folder/fldcnxxxx` | `folder_token` | URL 路径中的 token 作为文件夹 token 使用 |
|
||||
|
||||
- 添加评论优先使用 [`drive +add-comment`](references/lark-drive-add-comment.md)；查询、统计、回复限制和 reaction 规则见 [`lark-drive-comments-guide.md`](references/lark-drive-comments-guide.md) 与 [`lark-drive-reactions.md`](references/lark-drive-reactions.md)。
|
||||
- 权限申请优先使用 [`drive +apply-permission`](references/lark-drive-apply-permission.md)；公开权限错误码、授权当前应用访问文档等规则见 [`lark-drive-permission-guide.md`](references/lark-drive-permission-guide.md)。
|
||||
### Wiki 链接特殊处理（关键！）
|
||||
|
||||
## 不在本 skill 范围
|
||||
知识库链接（`/wiki/TOKEN`）背后可能是云文档、电子表格、多维表格等不同类型的文档。**不能直接假设 URL 中的 token 就是 file_token**，必须先查询实际类型和真实 token。
|
||||
|
||||
- 文档正文读取、改写、追加、替换、图片/附件插入：切到 [`lark-doc`](../lark-doc/SKILL.md)。
|
||||
- 电子表格单元格、工作表、筛选、公式等表内操作：切到 [`lark-sheets`](../lark-sheets/SKILL.md)。
|
||||
- Base 表、字段、记录、视图、表单、仪表盘、工作流等表内操作：切到 [`lark-base`](../lark-base/SKILL.md)。
|
||||
- 知识空间、Wiki 节点、空间成员管理：切到 [`lark-wiki`](../lark-wiki/SKILL.md)。
|
||||
- Drive 原生 Markdown 文件的创建、读取、patch、overwrite、diff：切到 [`lark-markdown`](../lark-markdown/SKILL.md)。
|
||||
#### 处理流程
|
||||
|
||||
## 参考
|
||||
**推荐方式：使用 `drive +inspect` 自动解包**
|
||||
|
||||
- [`lark-wiki-token-routing.md`](../lark-shared/references/lark-wiki-token-routing.md) — Wiki token / obj_token / obj_type 路由规则
|
||||
- [`lark-drive-comments-guide.md`](references/lark-drive-comments-guide.md) — 评论查询、统计、回复和 review 落点规则
|
||||
- [`lark-drive-permission-guide.md`](references/lark-drive-permission-guide.md) — 权限错误码和应用授权规则
|
||||
```bash
|
||||
lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/wikcnXXX'
|
||||
```
|
||||
|
||||
返回结果包含 `type`（底层文档类型）、`token`（真实 file_token）、`title`、`url` 等字段，直接用于后续操作。
|
||||
|
||||
**手动方式：使用 `wiki.spaces.get_node` 查询节点信息**
|
||||
|
||||
1. **使用 `wiki.spaces.get_node` 查询节点信息**
|
||||
```bash
|
||||
lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'
|
||||
```
|
||||
|
||||
2. **从返回结果中提取关键信息**
|
||||
- `node.obj_type`：文档类型（docx/doc/sheet/bitable/slides/file/mindnote）
|
||||
- `node.obj_token`：**真实的文档 token**（用于后续操作）
|
||||
- `node.title`：文档标题
|
||||
|
||||
3. **根据 `obj_type` 使用对应的 API**
|
||||
|
||||
| obj_type | 说明 | 使用的 API |
|
||||
|----------|------|-----------|
|
||||
| `docx` | 新版云文档 | `drive file.comments.*`、`docx.*` |
|
||||
| `doc` | 旧版云文档 | `drive file.comments.*` |
|
||||
| `sheet` | 电子表格 | `sheets.*` |
|
||||
| `bitable` | 多维表格 | `bitable.*` |
|
||||
| `slides` | 幻灯片 | `drive.*` |
|
||||
| `file` | 文件 | `drive.*` |
|
||||
| `mindnote` | 思维导图 | `drive.*` |
|
||||
|
||||
#### 查询示例
|
||||
|
||||
```bash
|
||||
# 查询 wiki 节点
|
||||
lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'
|
||||
```
|
||||
|
||||
返回结果示例：
|
||||
```json
|
||||
{
|
||||
"node": {
|
||||
"obj_type": "docx",
|
||||
"obj_token": "xxxx",
|
||||
"title": "标题",
|
||||
"node_type": "origin",
|
||||
"space_id": "12345678910"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 资源关系
|
||||
|
||||
```
|
||||
Wiki Space (知识空间)
|
||||
└── Wiki Node (知识库节点)
|
||||
├── obj_type: docx (新版文档)
|
||||
│ └── obj_token (真实文档 token)
|
||||
├── obj_type: doc (旧版文档)
|
||||
│ └── obj_token (真实文档 token)
|
||||
├── obj_type: sheet (电子表格)
|
||||
│ └── obj_token (真实文档 token)
|
||||
├── obj_type: bitable (多维表格)
|
||||
│ └── obj_token (真实文档 token)
|
||||
└── obj_type: file/slides/mindnote
|
||||
└── obj_token (真实文档 token)
|
||||
|
||||
Drive Folder (云空间文件夹)
|
||||
└── File (文件/文档)
|
||||
└── file_token (直接使用)
|
||||
```
|
||||
|
||||
### 常见操作 Token 需求
|
||||
|
||||
| 操作 | 需要的 Token | 说明 |
|
||||
|------|-------------|------|
|
||||
| 读取文档内容 | `file_token` / 通过 `docs +fetch --api-version v2` 自动处理 | `docs +fetch --api-version v2` 支持直接传入 URL |
|
||||
| 添加局部评论（划词评论） | `file_token` | 传 `--block-id` 时，`drive +add-comment` 会创建局部评论；仅支持 `docx`，以及最终解析为 `docx` 的 wiki URL |
|
||||
| 添加全文评论 | `file_token` | 不传 `--block-id` 时，`drive +add-comment` 默认创建全文评论；支持 `docx`、旧版 `doc` URL，以及最终解析为 `doc`/`docx` 的 wiki URL |
|
||||
| 下载文件 | `file_token` | 从文件 URL 中直接提取 |
|
||||
| 上传文件 | `folder_token` / `wiki_node_token` | 目标位置的 token |
|
||||
| 列出文档评论 | `file_token` | 同添加评论 |
|
||||
|
||||
### 评论能力边界（关键！）
|
||||
|
||||
- `drive +add-comment` 支持两种模式。
|
||||
- 全文评论：未传 `--block-id` 时默认启用，也可显式传 `--full-comment`；支持 `docx`、旧版 `doc` URL，以及最终解析为 `doc`/`docx` 的 wiki URL。
|
||||
- 局部评论：传 `--block-id` 时启用；仅支持 `docx`，以及最终解析为 `docx` 的 wiki URL。block ID 可通过 `docs +fetch --api-version v2 --detail with-ids` 获取。
|
||||
- `drive +add-comment` 的 `--content` 需要传 `reply_elements` JSON 数组字符串，例如 `--content '[{"type":"text","text":"正文"}]'`。
|
||||
- 如果 wiki 解析后不是 `doc`/`docx`，不要用 `+add-comment`。
|
||||
- 如果需要更底层地直接调用评论 V2 协议，再走原生 API：先执行 `lark-cli schema drive.file.comments.create_v2`，再执行 `lark-cli drive file.comments create_v2 ...`。全文评论省略 `anchor`，局部评论传 `anchor.block_id`。
|
||||
|
||||
### 评论查询与统计口径（关键！）
|
||||
|
||||
**强制规则**：`drive file.comments list` 默认必须传 `is_solved:false`，即仅查询未解决评论。即使用户说“所有评论”“全部评论”“把评论都列出来”，只要没有明确提到要包含已解决评论，仍然按默认口径查询未解决评论。
|
||||
仅当用户明确要求包含已解决评论时，才可省略 `is_solved` 参数。
|
||||
|
||||
**正确示例：**
|
||||
|
||||
```bash
|
||||
# 默认查询：仅未解决评论（推荐）
|
||||
lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "docx", "is_solved": false}'
|
||||
|
||||
# 查询所有评论（用户未明确要求包含已解决评论）
|
||||
lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "docx", "is_solved": false}'
|
||||
|
||||
# 包含已解决评论（需用户明确要求）
|
||||
lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "docx"}'
|
||||
```
|
||||
|
||||
**错误示例：**
|
||||
|
||||
```bash
|
||||
# 不推荐：用户未明确要求但查询所有评论
|
||||
lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "docx"}'
|
||||
```
|
||||
|
||||
- 查询文档评论时，使用 `drive file.comments list`。
|
||||
- `drive file.comments list` 返回的 `items` 应理解为"评论卡片"列表，每个 `item` 对应用户界面里看到的一张评论卡片，而不是平铺的互动消息列表。
|
||||
- 服务端语义上，创建第一条评论时会同时创建该卡片里的第一条 reply；因此真正承载正文的是每个 `item.reply_list.replies`，其中第一条 reply 在用户视角下就是这张卡片里的"评论本身"。
|
||||
- 当用户要统计"评论数"或"评论卡片数"时，统计 `items` 的长度即可；如果是全量统计，则对所有评论分页返回的 `items` 长度累加。
|
||||
- 当用户要统计"回复数"时，按用户视角应排除每张评论卡片里的首条评论，统计口径是所有 `item.reply_list.replies` 的长度之和减去 `items` 的长度。
|
||||
- 当用户要统计"总互动数"时，统计所有 `item.reply_list.replies` 的长度之和即可；这个口径包含每张评论卡片里的首条评论。
|
||||
- 如果某个 `item.has_more=true`，说明该评论卡片下还有更多回复未包含在当前返回中；此时需要继续调用 `drive file.comment.replys list` 拉全后，再做全量回复数 / 总互动数统计。
|
||||
|
||||
### 评论业务特性与引导（关键！）
|
||||
|
||||
#### 评论排序引导
|
||||
- 一个文档通常有多个评论，评论按 `create_time`（创建时间）排序。
|
||||
- **重要**：只有当用户明确提到"最新评论"、"最后评论"、"最早评论"时，才需要根据 `create_time` 进行排序：
|
||||
- **必须先获取所有评论（处理分页拉完所有数据）**，不能只获取一页就排序
|
||||
- "最新评论" / "最后评论"：按 `create_time` 降序排列，取第一条
|
||||
- "最早评论"：按 `create_time` 升序排列，取第一条
|
||||
- 如果用户只说"第一条评论"，直接使用 `drive file.comments list` 返回的第一条即可，不需要额外排序。
|
||||
|
||||
#### 评论回复限制
|
||||
- **添加评论回复前先检查是否存在以下限制**
|
||||
- **全文评论不支持回复**：`is_whole=true` 的评论（全文评论）无法添加回复，遇到此类评论应提示用户"全文评论不支持回复"。
|
||||
- **已解决评论不支持回复**：`is_solved=true` 的评论无法添加回复，遇到此类评论应提示用户"该评论已被解决，无法回复"。
|
||||
- **注意**：当用户要回复某条评论但该评论因上述限制不能回复时，只提示不能回复即可，**不要自动帮用户找其他可以回复的评论**，避免不符合用户预期。
|
||||
|
||||
#### 批量查询与列表查询的选择
|
||||
- 使用 `drive file.comments batch_query` 是**已知评论 ID 后**的批量查询，需要传入具体的评论 ID 列表。
|
||||
- 使用 `drive file.comments list` 用于分页获取评论列表，适合统计评论总数、遍历所有评论，或获取"最新/最后 N 条评论"等场景。
|
||||
|
||||
#### Reaction / 表情场景
|
||||
- 遇到评论 / 回复上的 reaction（表情、各表情数量、谁点了什么、添加/删除表情）相关问题时，**先阅读 [lark-drive-reactions.md](../../skills/lark-drive/references/lark-drive-reactions.md) 了解如何使用**。
|
||||
|
||||
### 典型错误与解决方案
|
||||
|
||||
| 错误信息 | 原因 | 解决方案 |
|
||||
|----------|------|----------|
|
||||
| `not exist` | 使用了错误的 token | 检查 token 类型，wiki 链接必须先查询获取 `obj_token` |
|
||||
| `permission denied` | 没有相关操作权限 | 引导用户检查当前身份对文档/文件是否有相应操作权限；如果需要，可以授予相应权限 |
|
||||
| `invalid file_type` | file_type 参数错误 | 根据 `obj_type` 传入正确的 file_type（docx/doc/sheet） |
|
||||
|
||||
### 授权当前应用访问文档
|
||||
|
||||
当需要将文档权限授予**当前应用（bot）自身**时，先通过 bot info 接口获取应用的 open_id，再调用权限接口授权：
|
||||
|
||||
```bash
|
||||
# 1. 获取当前应用的 open_id
|
||||
lark-cli api GET /open-apis/bot/v3/info --as bot
|
||||
# 从返回值中取 bot.open_id
|
||||
|
||||
# 2. 授权当前应用访问文档
|
||||
lark-cli drive permission.members create \
|
||||
--params '{"token":"<doc_token>","type":"<resource_type>"}' \
|
||||
--data '{"member_type":"openid","member_id":"<bot_open_id>","perm":"view","type":"user"}'
|
||||
```
|
||||
|
||||
> **注意**：此方式仅适用于需要授权给**当前应用**的场景。授权给其他用户时，直接使用对方的 open_id 即可，无需调用 bot info 接口。
|
||||
|
||||
`<resource_type>` 可选值：`doc`、`docx`、`sheet`、`bitable`、`file`、`folder`、`wiki`。
|
||||
|
||||
@@ -31,7 +31,11 @@ lark-cli {{service}} <resource> <method> [flags] # 调用 API
|
||||
```
|
||||
|
||||
> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
|
||||
> 所需 scope 以 `lark-cli schema {{service}}.<resource>.<method>` 输出为准；skill 主文不展开完整权限表。
|
||||
|
||||
{{resource_sections}}
|
||||
## 权限表
|
||||
|
||||
| 方法 | 所需 scope |
|
||||
|------|-----------|
|
||||
{{permission_rows}}
|
||||
{{/actions}}
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: lark-drive
|
||||
version: 1.0.0
|
||||
description: "飞书云空间（云盘/云存储）：管理文件、文件夹、评论和权限，并将本地 Word/Markdown/Excel/CSV/PPTX/Base 快照导入为飞书在线文档、表格、多维表格或幻灯片。当用户需要上传/下载文件、搜索或整理云空间对象、查看元数据、修改标题、管理评论/权限/评论订阅，或处理 doubao.com 云空间资源 URL/token 时使用。不负责：文档正文编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 内容读写（走 lark-markdown）。"
|
||||
description: "飞书云空间（云盘/云存储）：管理云空间（云盘/云存储）中的文件和文件夹。上传和下载文件、创建文件夹、复制/移动/删除文件、查看文件元数据、管理文档评论、管理文档权限、订阅用户评论变更事件、修改文件标题（docx、sheet、bitable、file、folder、wiki）；也负责把本地 Word/Markdown/Excel/CSV/PPTX 以及 Base 快照（.base）导入为飞书在线云文档（docx、sheet、bitable、slides）。当用户需要上传或下载文件、整理云空间（云盘/云存储）目录、查看文件详情、管理评论、管理文档权限、修改文件标题、订阅用户评论变更事件，或要把本地文件导入成新版文档、电子表格、多维表格/Base/幻灯片 时使用。\"云空间\"、\"云盘\"和\"云存储\"是同一概念，用户说\"云盘\"、\"云存储\"、\"网盘\"、\"我的空间\"时均路由到本 skill。当用户给出 doubao.com 的云空间资源 URL/token，或明确提到豆包里的 file/folder/docx/sheet/bitable/wiki 资源时，也应直接使用本 skill，不要因为域名不是飞书而回退到 WebFetch；路由依据是资源类型、URL 路径模式和 token，而不是域名。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["lark-cli"]
|
||||
@@ -14,98 +14,361 @@ metadata:
|
||||
|
||||
> **术语说明：** 飞书云空间也常被称为"云盘"或"云存储"，三者指的是同一个产品，是飞书官方的云端文件存储与管理中心。
|
||||
|
||||
## 关键规则速览
|
||||
|
||||
- Wiki 链接里的 `/wiki/<token>` 不是底层文件 token；优先用 `drive +inspect` 解包，完整规则见 [`lark-wiki-token-routing.md`](../lark-shared/references/lark-wiki-token-routing.md)。
|
||||
- 本地文件导入为在线文档统一走 `drive +import`：目标是 Base / 多维表格时用 `--type bitable`（`.xlsx` / `.csv` / `.base`，`.xls` 不支持）；目标是电子表格时用 `--type sheet`（`.xlsx` / `.xls` / `.csv`）；Office / Markdown / HTML / TXT -> `--type docx`，PPTX -> `--type slides`。
|
||||
- 原生 `.md` 文件内容读写、patch、diff 走 [`lark-markdown`](../lark-markdown/SKILL.md)；把 Markdown 转成在线 docx 才走 `drive +import --type docx`。
|
||||
- 评论默认只查未解决评论；review / 审阅场景优先局部评论。评论细节见 [`lark-drive-comments-guide.md`](references/lark-drive-comments-guide.md)。
|
||||
- 权限申请、安全标签、搜索等用户个人资源场景优先 `--as user`；bot 只能处理自己可见或已授权的资源。
|
||||
> **导入分流规则：** 如果用户要把本地 Excel / CSV / `.base` 快照导入成 Base / 多维表格 / bitable，必须优先使用 `lark-cli drive +import --type bitable`。不要先切到 `lark-base`；`lark-base` 只负责导入完成后的表内操作。
|
||||
|
||||
## 快速决策
|
||||
|
||||
- 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间对象**，优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"（`--mine`，owner 语义）、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag。
|
||||
- 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`；`.xls` 不能直接导入为 bitable，需先转 `.xlsx` 或改导入为 sheet。
|
||||
- 用户要**搜文档 / Wiki / 电子表格 / 多维表格 / 云空间（云盘/云存储）对象**，优先使用 `lark-cli drive +search`。自然语言里"最近我编辑过的"、"我创建的"（→ `--mine`，实为 owner 语义）、"最近一周我打开过的 xxx"、"某人 owner 的 docx" 等直接映射到扁平 flag，避免手写嵌套 JSON。
|
||||
- 用户要把本地 `.xlsx` / `.csv` / `.base` 导入成 Base / 多维表格 / bitable，第一步必须使用 `lark-cli drive +import --type bitable`。
|
||||
- 用户要把本地 `.md` / `.docx` / `.doc` / `.txt` / `.html` 导入成在线文档，使用 `lark-cli drive +import --type docx`。
|
||||
- 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格，使用 `lark-cli drive +import --type sheet`。
|
||||
- 用户要把本地 `.pptx` 导入成飞书幻灯片，使用 `lark-cli drive +import --type slides`；当前 PPTX 导入上限是 500MB。
|
||||
- 用户要在 Drive 里上传、创建、读取、局部 patch 或覆盖更新**原生 `.md` 文件**（不是导入成 docx），切到 [`lark-markdown`](../lark-markdown/SKILL.md)。
|
||||
- 用户要比较原生 `.md` 文件的历史版本差异，或比较远端 Markdown 与本地草稿，切到 [`lark-markdown`](../lark-markdown/SKILL.md) 的 `lark-cli markdown +diff`；需要版本号时先用 `drive +version-history`。
|
||||
- 用户要查看、下载、回滚或删除文件的历史版本，使用 `drive +version-history`、`drive +version-get`、`drive +version-revert`、`drive +version-delete`；自动化场景优先 `--as bot`。
|
||||
- 用户要在云空间里新建文件夹，优先使用 `lark-cli drive +create-folder`。
|
||||
- 用户要把本地文件上传到知识库 / 文档库里的某个 wiki 节点下，仍然使用 `lark-cli drive +upload --wiki-token <wiki_token>`；不要误切到 `wiki` 域命令。
|
||||
- 用户要修改标题，可用 `drive files patch` 传 `new_title`，支持 docx、sheet、bitable、file、wiki、folder 类型。
|
||||
- 用户要比较原生 `.md` 文件的**历史版本差异**，或比较远端 Markdown 与本地草稿，切到 [`lark-markdown`](../lark-markdown/SKILL.md) 的 `lark-cli markdown +diff`；需要版本号时先用 `drive +version-history`。
|
||||
- 用户要查看、下载、回滚或删除文件的**历史版本**，使用 `drive +version-history`、`drive +version-get`、`drive +version-revert`、`drive +version-delete`；这组命令同时支持 `--as user` 和 `--as bot`，自动化场景优先 `--as bot`。
|
||||
- 用户要把本地 `.xlsx` / `.xls` / `.csv` 导入成电子表格，使用 `lark-cli drive +import --type sheet`。
|
||||
- 用户要在云空间（云盘/云存储）里新建文件夹，优先使用 `lark-cli drive +create-folder`。
|
||||
- 用户要把本地文件上传到知识库 / 文档库里的某个 wiki 节点下时，仍然使用 `lark-cli drive +upload --wiki-token <wiki_token>`；不要误切到 `wiki` 域命令。
|
||||
- `lark-base` 只负责导入完成后的 Base 内部操作（表、字段、记录、视图），不要在“本地文件 -> Base”这一步提前切到 `lark-base`。
|
||||
|
||||
## 身份路由
|
||||
## 修改标题
|
||||
- 使用 `drive files patch` 命令，通过new_title字段可以修改标题，支持 docx、sheet、bitable、file、wiki、folder 类型
|
||||
|
||||
| 场景 | 身份建议 |
|
||||
|------|----------|
|
||||
| 搜索用户可见资源、申请权限、查看/更新安全标签 | 使用 `--as user`；这些 shortcut 是 user-only 或强依赖用户可见范围 |
|
||||
| 用户个人云空间、用户拥有的文档/文件夹 | 默认 `--as user` |
|
||||
| bot 自己创建的资源、已授权给 bot 的资源、自动化版本操作 | 可用 `--as bot`；版本命令自动化场景优先 bot |
|
||||
| bot 因资源不可见失败 | 不要反复重试；提示用户切 `--as user`，或先把资源授权给当前应用 |
|
||||
## 核心概念
|
||||
|
||||
### 文档类型与 Token
|
||||
|
||||
飞书开放平台中，不同类型的文档有不同的 URL 格式和 Token 处理方式。在进行文档操作（如添加评论、下载文件等）时，必须先获取正确的 `file_token`。
|
||||
|
||||
### 文档 URL 格式与 Token 处理
|
||||
|
||||
| URL 格式 | 示例 | Token 类型 | 处理方式 |
|
||||
|----------|---------------------------------------------------------|-----------|----------|
|
||||
| `/docx/` | `https://example.larksuite.com/docx/doxcnxxxxxxxxx` | `file_token` | URL 路径中的 token 直接作为 `file_token` 使用 |
|
||||
| `/doc/` | `https://example.larksuite.com/doc/doccnxxxxxxxxx` | `file_token` | URL 路径中的 token 直接作为 `file_token` 使用 |
|
||||
| `/wiki/` | `https://example.larksuite.com/wiki/wikcnxxxxxxxxx` | `wiki_token` | ⚠️ **不能直接使用**，需要先查询获取真实的 `obj_token` |
|
||||
| `/sheets/` | `https://example.larksuite.com/sheets/shtcnxxxxxxxxx` | `file_token` | URL 路径中的 token 直接作为 `file_token` 使用 |
|
||||
| `/drive/folder/` | `https://example.larksuite.com/drive/folder/fldcnxxxx` | `folder_token` | URL 路径中的 token 作为文件夹 token 使用 |
|
||||
|
||||
### Wiki 链接特殊处理（关键！）
|
||||
|
||||
知识库链接（`/wiki/TOKEN`）背后可能是云文档、电子表格、多维表格等不同类型的文档。**不能直接假设 URL 中的 token 就是 file_token**，必须先查询实际类型和真实 token。
|
||||
|
||||
#### 处理流程
|
||||
|
||||
**推荐方式：使用 `drive +inspect` 自动解包**
|
||||
|
||||
```bash
|
||||
lark-cli drive +inspect --url 'https://xxx.feishu.cn/wiki/wikcnXXX'
|
||||
```
|
||||
|
||||
返回结果包含 `type`（底层文档类型）、`token`（真实 file_token）、`title`、`url` 等字段，直接用于后续操作。
|
||||
|
||||
**手动方式：使用 `wiki.spaces.get_node` 查询节点信息**
|
||||
|
||||
1. **使用 `wiki.spaces.get_node` 查询节点信息**
|
||||
```bash
|
||||
lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'
|
||||
```
|
||||
|
||||
2. **从返回结果中提取关键信息**
|
||||
- `node.obj_type`：文档类型（docx/doc/sheet/bitable/slides/file/mindnote）
|
||||
- `node.obj_token`：**真实的文档 token**（用于后续操作）
|
||||
- `node.title`：文档标题
|
||||
|
||||
3. **根据 `obj_type` 使用对应的 API**
|
||||
|
||||
| obj_type | 说明 | 使用的 API |
|
||||
|----------|------|-----------|
|
||||
| `docx` | 新版云文档 | `drive file.comments.*`、`docx.*` |
|
||||
| `doc` | 旧版云文档 | `drive file.comments.*` |
|
||||
| `sheet` | 电子表格 | `sheets.*` |
|
||||
| `bitable` | 多维表格 | `bitable.*` |
|
||||
| `slides` | 幻灯片 | `drive.*` |
|
||||
| `file` | 文件 | `drive.*` |
|
||||
| `mindnote` | 思维导图 | `drive.*` |
|
||||
|
||||
#### 查询示例
|
||||
|
||||
```bash
|
||||
# 查询 wiki 节点
|
||||
lark-cli wiki spaces get_node --params '{"token":"wiki_token"}'
|
||||
```
|
||||
|
||||
返回结果示例：
|
||||
```json
|
||||
{
|
||||
"node": {
|
||||
"obj_type": "docx",
|
||||
"obj_token": "xxxx",
|
||||
"title": "标题",
|
||||
"node_type": "origin",
|
||||
"space_id": "12345678910"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 资源关系
|
||||
|
||||
```
|
||||
Wiki Space (知识空间)
|
||||
└── Wiki Node (知识库节点)
|
||||
├── obj_type: docx (新版文档)
|
||||
│ └── obj_token (真实文档 token)
|
||||
├── obj_type: doc (旧版文档)
|
||||
│ └── obj_token (真实文档 token)
|
||||
├── obj_type: sheet (电子表格)
|
||||
│ └── obj_token (真实文档 token)
|
||||
├── obj_type: bitable (多维表格)
|
||||
│ └── obj_token (真实文档 token)
|
||||
└── obj_type: file/slides/mindnote
|
||||
└── obj_token (真实文档 token)
|
||||
|
||||
Drive Folder (云空间/云盘/云存储文件夹)
|
||||
└── File (文件/文档)
|
||||
└── file_token (直接使用)
|
||||
```
|
||||
|
||||
### 常见操作 Token 需求
|
||||
|
||||
| 操作 | 需要的 Token | 说明 |
|
||||
|------|-------------|------|
|
||||
| 读取文档内容 | `file_token` / 通过 `docs +fetch --api-version v2` 自动处理 | `docs +fetch --api-version v2` 支持直接传入 URL |
|
||||
| 添加局部评论（划词评论） | `file_token` | 传 `--block-id` 时，`drive +add-comment` 会创建局部评论；`docx` 支持文本定位或 block_id，`sheet` 使用 `<sheetId>!<cell>`，`slides` 使用 `<slide-block-type>!<xml-id>`，且都支持最终解析到对应类型的 wiki URL；Drive file 不支持局部评论 |
|
||||
| 添加全文评论 | `file_token` | 不传 `--block-id` 时，`drive +add-comment` 默认创建全文评论；支持 `docx`、旧版 `doc` URL、白名单扩展名的 Drive file，以及最终解析为 `doc`/`docx`/`file` 的 wiki URL |
|
||||
| 下载文件 | `file_token` | 从文件 URL 中直接提取 |
|
||||
| 上传文件 | `folder_token` / `wiki_node_token` | 目标位置的 token |
|
||||
| 列出文档评论 | `file_token` | 同添加评论 |
|
||||
|
||||
### 评论能力边界（关键！）
|
||||
|
||||
- `drive +add-comment` 支持两种模式。
|
||||
- 全文评论：未传 `--block-id` 时默认启用，也可显式传 `--full-comment`；支持 `docx`、旧版 `doc` URL、白名单扩展名的 Drive file，以及最终解析为 `doc`/`docx`/`file` 的 wiki URL。
|
||||
- 局部评论：传 `--block-id` 时启用；`docx` 支持文本定位或 block id，`sheet` 支持 `<sheetId>!<cell>`，`slides` 支持 `<slide-block-type>!<xml-id>`，wiki URL 解析到这些类型时也支持对应局部评论。Drive file 本次只支持全文评论，不支持局部评论。
|
||||
- Drive file 评论仅支持白名单扩展名：`.md`、`.txt`、`.json`、`.csv`、`.go`、`.js`、`.py`、`.pptx`、`.png`、`.jpg`、`.jpeg`、`.zip`、`.mp3`、`.mp4`。`.pdf`、`.docx`、`.xlsx` 等未在白名单内的普通文件暂不支持，CLI 会直接报错提示当前还不支持这种类型的评论。
|
||||
- Review / 审阅 / 校对 / 逐条指出问题场景优先使用局部评论，不要把多个可定位问题汇总成一条全文评论；具体参数和定位方式见 [`drive +add-comment` 行为说明](references/lark-drive-add-comment.md#行为说明)。
|
||||
- `drive +add-comment` 的 `--content` 需要传 `reply_elements` JSON 数组字符串，例如 `--content '[{"type":"text","text":"正文"}]'`。
|
||||
- `slides` 评论要求显式传 `--block-id <slide-block-type>!<xml-id>`；CLI 会将其拆分后写入 `anchor.block_id` 和 `anchor.slide_block_type`。其中 `<xml-id>` 是 PPT XML 协议中的元素 `id`；不支持 `--selection-with-ellipsis` 和 `--full-comment`。
|
||||
|
||||
- 评论写入内容（添加评论、回复评论、编辑回复）里的文本不能直接出现 `<`、`>`；提交前必须先转义：`<` -> `<`，`>` -> `>`。
|
||||
- 使用 `drive +add-comment` 时，shortcut 会对 `type=text` 的文本元素自动做上述转义兜底；如果直接调用 `drive file.comments create_v2`、`drive file.comment.replys create`、`drive file.comment.replys update`，则需要在请求里自行传入已转义的内容。
|
||||
- 如果 wiki 解析后不是 `doc`/`docx`/`file`/`sheet`/`slides`，不要用 `+add-comment`。
|
||||
- 如果需要更底层地直接调用评论 V2 协议，再走原生 API：先执行 `lark-cli schema drive.file.comments.create_v2`，再执行 `lark-cli drive file.comments create_v2 ...`。全文评论省略 `anchor`，局部评论传 `anchor.block_id`。
|
||||
|
||||
### 评论查询与统计口径（关键！）
|
||||
|
||||
**强制规则**：`drive file.comments list` 默认必须传 `is_solved:false`，即仅查询未解决评论。即使用户说“所有评论”“全部评论”“把评论都列出来”，只要没有明确提到要包含已解决评论，仍然按默认口径查询未解决评论。仅当用户明确要求包含已解决评论时，才可省略 `is_solved` 参数。
|
||||
|
||||
**正确示例：**
|
||||
|
||||
```bash
|
||||
# 默认查询：仅未解决评论（推荐）
|
||||
lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "docx", "is_solved": false}'
|
||||
|
||||
# 查询所有评论（用户未明确要求包含已解决评论）
|
||||
lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "docx", "is_solved": false}'
|
||||
|
||||
# 包含已解决评论（需用户明确要求）
|
||||
lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "docx"}'
|
||||
```
|
||||
|
||||
**错误示例：**
|
||||
|
||||
```bash
|
||||
# 不推荐：用户未明确要求但查询所有评论
|
||||
lark-cli drive file.comments list --params '{"file_token": "xxx", "file_type": "docx"}'
|
||||
```
|
||||
|
||||
- 查询文档评论时，使用 `drive file.comments list`。
|
||||
- `drive file.comments list` 返回的 `items` 应理解为"评论卡片"列表，每个 `item` 对应用户界面里看到的一张评论卡片，而不是平铺的互动消息列表。
|
||||
- 服务端语义上，创建第一条评论时会同时创建该卡片里的第一条 reply；因此真正承载正文的是每个 `item.reply_list.replies`，其中第一条 reply 在用户视角下就是这张卡片里的"评论本身"。
|
||||
- 当用户要统计"评论数"或"评论卡片数"时，统计 `items` 的长度即可；如果是全量统计，则对所有评论分页返回的 `items` 长度累加。
|
||||
- 当用户要统计"回复数"时，按用户视角应排除每张评论卡片里的首条评论，统计口径是所有 `item.reply_list.replies` 的长度之和减去 `items` 的长度。
|
||||
- 当用户要统计"总互动数"时，统计所有 `item.reply_list.replies` 的长度之和即可；这个口径包含每张评论卡片里的首条评论。
|
||||
- 如果某个 `item.has_more=true`，说明该评论卡片下还有更多回复未包含在当前返回中；此时需要继续调用 `drive file.comment.replys list` 拉全后，再做全量回复数 / 总互动数统计。
|
||||
|
||||
### 评论业务特性与引导（关键！）
|
||||
|
||||
#### Review 场景评论落点
|
||||
- 默认策略是“能局部就局部”：用户说 review、审阅、检查文档、标注问题、给修改建议、逐条评论时，优先创建局部评论。
|
||||
- 多个独立问题应分别创建多条局部评论；不要为了省调用次数把 review 发现的问题合并到全文评论。
|
||||
- 只有在目标类型支持全文评论，且出现以下任一情况时，才退回全文评论：用户明确要求全文/总体评论、评论内容确实是文档级总结、目标类型不支持局部评论，或无法稳定定位到具体位置；否则应说明限制并请求用户提供可定位位置。
|
||||
- 具体参数、定位方式和不同文档类型的约束见 [`drive +add-comment` 行为说明](references/lark-drive-add-comment.md#行为说明)。
|
||||
|
||||
#### 评论排序引导
|
||||
- 一个文档通常有多个评论，评论按 `create_time`（创建时间）排序。
|
||||
- **重要**：只有当用户明确提到"最新评论"、"最后评论"、"最早评论"时，才需要根据 `create_time` 进行排序：
|
||||
- **必须先获取所有评论（处理分页拉完所有数据）**，不能只获取一页就排序
|
||||
- "最新评论" / "最后评论"：按 `create_time` 降序排列，取第一条
|
||||
- "最早评论"：按 `create_time` 升序排列，取第一条
|
||||
- 如果用户只说"第一条评论"，直接使用 `drive file.comments list` 返回的第一条即可，不需要额外排序。
|
||||
|
||||
#### 评论回复限制
|
||||
- **添加评论回复前先检查是否存在以下限制**
|
||||
- **全文评论不支持回复**：`is_whole=true` 的评论（全文评论）无法添加回复，遇到此类评论应提示用户"全文评论不支持回复"。
|
||||
- **已解决评论不支持回复**：`is_solved=true` 的评论无法添加回复，遇到此类评论应提示用户"该评论已被解决，无法回复"。
|
||||
- **注意**：当用户要回复某条评论但该评论因上述限制不能回复时，只提示不能回复即可，**不要自动帮用户找其他可以回复的评论**，避免不符合用户预期。
|
||||
|
||||
#### 批量查询与列表查询的选择
|
||||
- 使用 `drive file.comments batch_query` 是**已知评论 ID 后**的批量查询，需要传入具体的评论 ID 列表。
|
||||
- 使用 `drive file.comments list` 用于分页获取评论列表，适合统计评论总数、遍历所有评论，或获取"最新/最后 N 条评论"等场景。
|
||||
|
||||
#### Reaction / 表情场景
|
||||
- 遇到评论 / 回复上的 reaction（表情、各表情数量、谁点了什么、添加/删除表情）相关问题时，**先阅读 [lark-drive-reactions.md](../../skills/lark-drive/references/lark-drive-reactions.md) 了解如何使用**。
|
||||
|
||||
### 典型错误与解决方案
|
||||
|
||||
| 错误信息 | 原因 | 解决方案 |
|
||||
|----------|------|----------|
|
||||
| `not exist` | 使用了错误的 token | 检查 token 类型，wiki 链接必须先查询获取 `obj_token` |
|
||||
| `permission denied` | 没有相关操作权限 | 引导用户检查当前身份对文档/文件是否有相应操作权限；如果需要，可以授予相应权限 |
|
||||
| `invalid file_type` | file_type 参数错误 | 根据 `obj_type` 传入正确的 file_type（docx/doc/sheet/slides） |
|
||||
|
||||
#### `permission.public.patch` 错误码引导
|
||||
|
||||
调用 `lark-cli drive permission.public patch` 更新文档公开权限失败时，如果返回以下错误码，按表格给用户明确下一步。不要把这些错误简单归类为缺少 scope；它们通常表示租户、对外分享或文档密级策略拦截。
|
||||
|
||||
| 错误码 | 含义 | 给用户的引导 |
|
||||
|--------|------------------------|--------------|
|
||||
| `91009` | 对外分享被租户安全策略管控，当前用户无法开启 | 提示用户：对外分享能力被租户安全策略统一管控，无法通过 API 或当前用户直接开启；需要联系租户管理员调整组织级对外分享策略。 |
|
||||
| `91010` | 文档对外分享未打开 | 提示用户：当前文档尚未打开对外分享，请先在文档权限设置中打开对外分享，再重试 `permission.public.patch`。 |
|
||||
| `91011` | 对外分享被文档密级管控 | 提示用户：对外分享被密级策略拦截，需要打开目标文档，在文档内发起密级豁免或进行密级降级后再重试；回复中必须给出目标文档 URL。 |
|
||||
| `91012` | 权限设置被文档密级管控 | 提示用户：该权限设置被密级策略拦截，需要打开目标文档，在文档内发起密级豁免或进行密级降级后再重试；回复中必须给出目标文档 URL。 |
|
||||
|
||||
当用户最初提供的是文档 URL，遇到 `91011` 或 `91012` 时直接把该 URL 原样返回给用户作为操作入口；如果上下文只有 token，需要先尽量通过已有上下文、搜索结果或元数据恢复目标文档 URL，再给出可点击的文档 URL。
|
||||
|
||||
### 授权当前应用访问文档
|
||||
|
||||
当需要将文档权限授予**当前应用（bot）自身**时，先通过 bot info 接口获取应用的 open_id，再调用权限接口授权：
|
||||
|
||||
```bash
|
||||
# 1. 获取当前应用的 open_id
|
||||
lark-cli api GET /open-apis/bot/v3/info --as bot
|
||||
# 从返回值中取 bot.open_id
|
||||
|
||||
# 2. 授权当前应用访问文档
|
||||
lark-cli drive permission.members create \
|
||||
--params '{"token":"<doc_token>","type":"<resource_type>"}' \
|
||||
--data '{"member_type":"openid","member_id":"<bot_open_id>","perm":"view","type":"user"}'
|
||||
```
|
||||
|
||||
> **注意**：此方式仅适用于需要授权给**当前应用**的场景。授权给其他用户时，直接使用对方的 open_id 即可，无需调用 bot info 接口。
|
||||
|
||||
`<resource_type>` 可选值：`doc`、`docx`、`sheet`、`bitable`、`file`、`folder`、`wiki`、`slides`。
|
||||
|
||||
## Shortcuts（推荐优先使用）
|
||||
|
||||
Shortcut 是对常用操作的高级封装（`lark-cli drive +<verb> [flags]`）。有 Shortcut 的操作优先使用。
|
||||
|
||||
| Shortcut | 说明 |
|
||||
|----------|------|
|
||||
| [`+search`](references/lark-drive-search.md) | 搜索飞书文档、Wiki、表格和云空间对象，支持 `--edited-since`、`--mine`、`--doc-types` 等扁平筛选 |
|
||||
| [`+upload`](references/lark-drive-upload.md) | 上传本地文件到 Drive 文件夹或 wiki 节点 |
|
||||
| [`+create-folder`](references/lark-drive-create-folder.md) | 在 Drive 中创建文件夹，支持 bot 创建后自动授权当前用户 |
|
||||
| [`+download`](references/lark-drive-download.md) | 下载 Drive 文件到本地 |
|
||||
| [`+status`](references/lark-drive-status.md) | 比较本地目录与 Drive 文件夹，默认精确 SHA-256，也支持 `--quick` 快速模式 |
|
||||
| [`+pull`](references/lark-drive-pull.md) | 单向同步 Drive 文件夹到本地目录 |
|
||||
| `+sync` | 双向同步本地目录与 Drive 文件夹；默认非破坏性，不删除任一侧文件 |
|
||||
| [`+push`](references/lark-drive-push.md) | 单向同步本地目录到 Drive 文件夹；删除远端需显式 `--delete-remote --yes` |
|
||||
| [`+create-shortcut`](references/lark-drive-create-shortcut.md) | 在其他文件夹中创建指向已有 Drive 文件的快捷方式 |
|
||||
| [`+add-comment`](references/lark-drive-add-comment.md) | 给 doc/docx/file/sheet/slides 添加全文或局部评论，支持可解析到这些类型的 wiki URL |
|
||||
| [`+export`](references/lark-drive-export.md) | 导出 doc/docx/sheet/bitable/slides 到本地文件 |
|
||||
| [`+export-download`](references/lark-drive-export-download.md) | 根据导出任务返回的 file_token 下载导出文件 |
|
||||
| [`+import`](references/lark-drive-import.md) | 将本地文件导入为在线 docx、sheet、bitable 或 slides |
|
||||
| [`+version-history`](references/lark-drive-version-history.md) | 查看文件历史版本列表 |
|
||||
| [`+version-get`](references/lark-drive-version-get.md) | 下载指定历史版本 |
|
||||
| [`+version-revert`](references/lark-drive-version-revert.md) | 回滚到指定历史版本 |
|
||||
| [`+version-delete`](references/lark-drive-version-delete.md) | 删除指定历史版本 |
|
||||
| [`+move`](references/lark-drive-move.md) | 移动 Drive 文件或文件夹 |
|
||||
| [`+delete`](references/lark-drive-delete.md) | 删除 Drive 文件或文件夹，文件夹删除会轮询异步任务 |
|
||||
| [`+task_result`](references/lark-drive-task-result.md) | 轮询 import、export、move、delete 等异步任务结果 |
|
||||
| [`+inspect`](references/lark-drive-inspect.md) | 检视文档 URL 的类型、标题和 canonical token，并自动解包 wiki URL |
|
||||
| [`+apply-permission`](references/lark-drive-apply-permission.md) | 向文档 owner 申请 view/edit 权限，仅支持 user 身份 |
|
||||
| [`+secure-label-list`](references/lark-drive-secure-label.md) | 列出当前用户可用的密级标签 |
|
||||
| [`+secure-label-update`](references/lark-drive-secure-label.md) | 更新 Drive 文件或文档密级标签；降级审批类错误需打开文档 UI 处理 |
|
||||
| Shortcut | 说明 |
|
||||
|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| [`+search`](references/lark-drive-search.md) | Search Lark docs, Wiki, and spreadsheet files with flat filter flags. Natural-language-friendly: `--edited-since`, `--mine`, `--doc-types`, etc. |
|
||||
| [`+upload`](references/lark-drive-upload.md) | Upload a local file to a Drive folder or wiki node |
|
||||
| [`+create-folder`](references/lark-drive-create-folder.md) | Create a Drive folder, optionally under a parent folder, with bot auto-grant support |
|
||||
| [`+download`](references/lark-drive-download.md) | Download a file from Drive to local |
|
||||
| [`+status`](references/lark-drive-status.md) | Compare a local directory with a Drive folder by exact SHA-256 hash by default, or use `--quick` for a best-effort modified-time diff that skips remote downloads; reports `new_local` / `new_remote` / `modified` / `unchanged` plus `detection=exact` or `detection=quick`. Duplicate remote `rel_path` conflicts fail fast with `error.type=duplicate_remote_path` and list every conflicting entry; do not proceed as if one was chosen. `--local-dir` 必须是 cwd 内的相对路径，越界路径 CLI 会直接拒绝；目标在 cwd 外时引导用户切换 agent 工作目录，不要私自 `cd` 绕过。 |
|
||||
| [`+pull`](references/lark-drive-pull.md) | File-level Drive → local mirror. Duplicate remote `rel_path` conflicts fail by default; for duplicate files, `rename` downloads all copies with stable hashed suffixes, while `newest` / `oldest` pick one. `--if-exists` supports `overwrite` / `smart` / `skip` (`smart` is a best-effort modified-time incremental mode for repeat syncs). `--delete-local` requires `--yes`, only removes regular files, and is skipped after item failures. `--local-dir` must stay inside cwd. |
|
||||
| `+sync` | Two-way local ↔ Drive sync. Reuses `+status` diff buckets, pulls `new_remote`, pushes `new_local`, and resolves `modified` via `--on-conflict=remote-wins|local-wins|keep-both|ask`. `--quick` enables best-effort modified-time diffing (timestamp mismatches can still trigger real pull/push actions), `--on-duplicate-remote` supports `fail|newest|oldest`, and the command is intentionally non-destructive (no delete on either side). |
|
||||
| [`+create-shortcut`](references/lark-drive-create-shortcut.md) | Create a shortcut to an existing Drive file in another folder |
|
||||
| [`+add-comment`](references/lark-drive-add-comment.md) | Add a comment to doc/docx/file/sheet/slides, also supports wiki URL resolving to doc/docx/file/sheet/slides; file targets support selected extensions and full comments only |
|
||||
| [`+export`](references/lark-drive-export.md) | Export a doc/docx/sheet/bitable/slides to a local file with limited polling; supports `--file-name` for local naming |
|
||||
| [`+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, slides) |
|
||||
| [`+version-history`](references/lark-drive-version-history.md) | List historical versions of a file with only_tag=true and cursor-based pagination |
|
||||
| [`+version-get`](references/lark-drive-version-get.md) | Download a specific historical version of a file |
|
||||
| [`+version-revert`](references/lark-drive-version-revert.md) | Revert a file to a specific historical version |
|
||||
| [`+version-delete`](references/lark-drive-version-delete.md) | Delete a specific historical version of a file |
|
||||
| [`+move`](references/lark-drive-move.md) | Move a file or folder to another location in Drive |
|
||||
| [`+delete`](references/lark-drive-delete.md) | Delete a Drive file or folder with limited polling for folder deletes |
|
||||
| [`+push`](references/lark-drive-push.md) | File-level local → Drive mirror. Duplicate remote `rel_path` conflicts fail by default; `newest` / `oldest` only apply to duplicate files when you explicitly want to target one remote file. `--if-exists` supports `skip` / `smart` / `overwrite` (`smart` skips files whose remote `modified_time` is already up to date, but falls through to the same overwrite path when the remote is older, so it inherits overwrite's rollout caveat). `--delete-remote` requires `--yes`. `--local-dir` must stay inside cwd. |
|
||||
| [`+task_result`](references/lark-drive-task-result.md) | Poll async task result for import, export, move, or delete operations |
|
||||
| [`+inspect`](references/lark-drive-inspect.md) | Inspect a Lark document URL to get its type, title, and canonical token; auto-unwraps wiki URLs to the underlying document |
|
||||
| [`+apply-permission`](references/lark-drive-apply-permission.md) | Apply to the document owner for view/edit access (user-only; 5/day per document) |
|
||||
| [`+secure-label-list`](references/lark-drive-secure-label.md) | List secure labels available to the current user |
|
||||
| [`+secure-label-update`](references/lark-drive-secure-label.md) | Update a Drive file/document secure label; downgrade approval errors require opening the document UI |
|
||||
|
||||
## 核心概念
|
||||
## API Resources
|
||||
|
||||
- 直接文档 URL（如 `/docx/`、`/doc/`、`/sheets/`、`/drive/folder/`）通常可从路径直接取得对应 token。
|
||||
- Wiki URL（`/wiki/<token>`）必须先解析到底层 `obj_type` 和 `obj_token`，再决定后续调用哪个域。
|
||||
- `drive +inspect` 是跨类型 URL 检视的首选入口；当它输出 `type` 和 `token` 后，后续命令使用该 canonical token。
|
||||
- 原生 API 调用前先运行 `lark-cli schema drive.<resource>.<method>` 查看 `--params` / `--data` 结构；不要猜字段。
|
||||
```bash
|
||||
lark-cli schema drive.<resource>.<method> # 调用 API 前必须先查看参数结构
|
||||
lark-cli drive <resource> <method> [flags] # 调用 API
|
||||
```
|
||||
|
||||
## 原生 API 快速索引
|
||||
> **重要**：使用原生 API 时，必须先运行 `schema` 查看 `--data` / `--params` 参数结构，不要猜测字段格式。
|
||||
|
||||
- 评论订阅事件：`drive user.subscription`、`drive user.subscription_status`、`drive user.remove_subscription`。
|
||||
- 公开权限设置：`drive permission.public get|patch`；错误码和处理建议见 [`lark-drive-permission-guide.md`](references/lark-drive-permission-guide.md)。
|
||||
- 协作者权限：`drive permission.members create|auth|transfer_owner`；授权当前应用访问文档见权限 guide，转移 owner 必须单独确认。
|
||||
- 元数据、统计、访问记录：`drive metas batch_query`、`drive file.statistics get`、`drive file.view_records list`。
|
||||
- 评论列表、解决状态、回复：`drive file.comments list|batch_query|patch`、`drive file.comment.replys *`；统计口径见评论 guide。
|
||||
### files
|
||||
|
||||
## 评论与权限
|
||||
- `copy` — 复制文件
|
||||
- `create_folder` — 新建文件夹
|
||||
- `list` — 获取文件夹下的清单
|
||||
- `patch` — 修改文件标题
|
||||
|
||||
- 添加评论优先使用 [`drive +add-comment`](references/lark-drive-add-comment.md)；查询、统计、回复限制和 reaction 规则见 [`lark-drive-comments-guide.md`](references/lark-drive-comments-guide.md) 与 [`lark-drive-reactions.md`](references/lark-drive-reactions.md)。
|
||||
- 权限申请优先使用 [`drive +apply-permission`](references/lark-drive-apply-permission.md)；公开权限错误码、授权当前应用访问文档等规则见 [`lark-drive-permission-guide.md`](references/lark-drive-permission-guide.md)。
|
||||
### file.comments
|
||||
|
||||
## 不在本 skill 范围
|
||||
- `batch_query` — 批量获取评论
|
||||
- `create_v2` — 添加全文/局部（划词）评论
|
||||
- `list` — 分页获取文档评论
|
||||
- `patch` — 解决/恢复 评论
|
||||
|
||||
- 文档正文读取、改写、追加、替换、图片/附件插入：切到 [`lark-doc`](../lark-doc/SKILL.md)。
|
||||
- 电子表格单元格、工作表、筛选、公式等表内操作：切到 [`lark-sheets`](../lark-sheets/SKILL.md)。
|
||||
- Base 表、字段、记录、视图、表单、仪表盘、工作流等表内操作：切到 [`lark-base`](../lark-base/SKILL.md)。
|
||||
- 知识空间、Wiki 节点、空间成员管理：切到 [`lark-wiki`](../lark-wiki/SKILL.md)。
|
||||
- Drive 原生 Markdown 文件的创建、读取、patch、overwrite、diff：切到 [`lark-markdown`](../lark-markdown/SKILL.md)。
|
||||
### file.comment.replys
|
||||
|
||||
## 参考
|
||||
- `create` — 添加回复
|
||||
- `delete` — 删除回复
|
||||
- `list` — 获取回复
|
||||
- `update` — 更新回复
|
||||
|
||||
- [`lark-wiki-token-routing.md`](../lark-shared/references/lark-wiki-token-routing.md) — Wiki token / obj_token / obj_type 路由规则
|
||||
- [`lark-drive-comments-guide.md`](references/lark-drive-comments-guide.md) — 评论查询、统计、回复和 review 落点规则
|
||||
- [`lark-drive-permission-guide.md`](references/lark-drive-permission-guide.md) — 权限错误码和应用授权规则
|
||||
### permission.members
|
||||
|
||||
- `auth` —
|
||||
- `create` — 增加协作者权限
|
||||
- `transfer_owner` —
|
||||
|
||||
### metas
|
||||
|
||||
- `batch_query` — 获取文档元数据
|
||||
|
||||
### user
|
||||
|
||||
- `remove_subscription` — 取消订阅用户、应用维度事件
|
||||
- `subscription` — 订阅用户、应用维度事件（本次开放评论添加事件）
|
||||
- `subscription_status` — 查询用户、应用对指定事件的订阅状态
|
||||
|
||||
### file.statistics
|
||||
|
||||
- `get` — 获取文件统计信息
|
||||
|
||||
### file.view_records
|
||||
|
||||
- `list` — 获取文档的访问者记录
|
||||
|
||||
### file.comment.reply.reactions
|
||||
|
||||
- `update_reaction` — 添加/删除 reaction
|
||||
|
||||
## 权限表
|
||||
|
||||
| 方法 | 所需 scope |
|
||||
|------------------------------------------------|-----------------------------------|
|
||||
| `files.copy` | `docs:document:copy` |
|
||||
| `files.create_folder` | `space:folder:create` |
|
||||
| `files.list` | `space:document:retrieve` |
|
||||
| `files.patch` | `docx:document:write_only` |
|
||||
| `file.comments.batch_query` | `docs:document.comment:read` |
|
||||
| `file.comments.create_v2` | `docs:document.comment:create` |
|
||||
| `file.comments.list` | `docs:document.comment:read` |
|
||||
| `file.comments.patch` | `docs:document.comment:update` |
|
||||
| `file.comment.replys.create` | `docs:document.comment:create` |
|
||||
| `file.comment.replys.delete` | `docs:document.comment:delete` |
|
||||
| `file.comment.replys.list` | `docs:document.comment:read` |
|
||||
| `file.comment.replys.update` | `docs:document.comment:update` |
|
||||
| `permission.members.auth` | `docs:permission.member:auth` |
|
||||
| `permission.members.create` | `docs:permission.member:create` |
|
||||
| `permission.members.transfer_owner` | `docs:permission.member:transfer` |
|
||||
| `permission.public.get` | `docs:permission.setting:read` |
|
||||
| `permission.public.patch` | `docs:permission.setting:write_only` |
|
||||
| `metas.batch_query` | `drive:drive.metadata:readonly` |
|
||||
| `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` |
|
||||
| `file.comment.reply.reactions.update_reaction` | `docs:document.comment:create` |
|
||||
|
||||
@@ -1,66 +0,0 @@
|
||||
# drive comments guide
|
||||
|
||||
> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 了解 Drive 入口、身份路由和 Wiki token 解包规则；再阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证与全局参数。
|
||||
|
||||
## 创建评论
|
||||
|
||||
- 添加评论优先使用 `drive +add-comment`。
|
||||
- 全文评论：未传 `--block-id` 时默认启用，也可显式传 `--full-comment`；支持 `docx`、旧版 `doc` URL、白名单扩展名普通文件，以及最终解析为这些类型的 Wiki URL。
|
||||
- 局部评论：传 `--block-id` 时启用；支持 `docx`、`sheet`、`slides`，以及最终解析为这些类型的 Wiki URL。docx block ID 可通过 `docs +fetch --api-version v2 --detail with-ids` 获取；sheet 使用 `<sheetId>!<cell>`；slides 使用 `<slide-block-type>!<xml-id>`。
|
||||
- 如果 Wiki URL 解包后不是 `doc` / `docx` / `file` / `sheet` / `slides`，不要使用 `+add-comment`。
|
||||
- Drive 普通文件评论仅支持平台允许的文件类型，常见后缀包括 `.md`、`.txt`、`.json`、`.csv`、`.go`、`.js`、`.py`、`.pptx`、`.png`、`.jpg`、`.jpeg`、`.zip`、`.mp3`、`.mp4`；普通文件只支持全文评论。
|
||||
- `--content` 需要传 `reply_elements` JSON 数组字符串，例如 `--content '[{"type":"text","text":"正文"}]'`。
|
||||
- 如果直接调用原生评论 V2 API，先执行 `lark-cli schema drive.file.comments.create_v2` 并优先参考 [`lark-drive-add-comment.md`](lark-drive-add-comment.md)。全文评论省略 `anchor`；doc/docx 局部评论传 `anchor.block_id`；sheet 评论使用 `anchor.block_id` + `sheet_col` + `sheet_row`；slides 评论使用 `anchor.block_id` + `slide_block_type`。
|
||||
|
||||
## Review 场景
|
||||
|
||||
- 代码、文案、方案 review 场景优先创建局部评论。
|
||||
- 不同问题尽量拆成多条局部评论，便于逐条解决和追踪。
|
||||
- Drive 普通文件不支持局部锚点，只能创建全文评论。
|
||||
|
||||
## 内容与转义
|
||||
|
||||
- 评论内容使用 `reply_elements` 表达，不要把纯 Markdown 当作结构化评论正文。
|
||||
- `drive +add-comment` 会处理常见文本转义；直接调原生 API 时需要自行转义 `<` 和 `>`，避免被平台当作标签片段。
|
||||
- 需要在评论中表达代码或 JSON 时，优先作为普通文本元素传入，不要猜测不在 schema 里的富文本字段。
|
||||
|
||||
## 查询与统计
|
||||
|
||||
- `drive file.comments list` 默认必须传 `is_solved:false`，即仅查询未解决评论。
|
||||
- 即使用户说“所有评论”“全部评论”“把评论都列出来”，只要没有明确要求包含已解决评论，仍按未解决评论查询。
|
||||
- 只有用户明确要求包含已解决评论时，才省略 `is_solved`。
|
||||
|
||||
```bash
|
||||
# 默认查询：仅未解决评论
|
||||
lark-cli drive file.comments list --params '{"file_token":"<DOC_TOKEN>","file_type":"docx","is_solved":false}'
|
||||
|
||||
# 用户明确要求包含已解决评论时
|
||||
lark-cli drive file.comments list --params '{"file_token":"<DOC_TOKEN>","file_type":"docx"}'
|
||||
```
|
||||
|
||||
- `items` 是评论卡片列表，不是平铺的互动消息列表。
|
||||
- 创建第一条评论时会同时创建该卡片里的第一条 reply；真正承载正文的是 `item.reply_list.replies`。
|
||||
- 统计“评论数”或“评论卡片数”：统计 `items` 数量，分页场景累加所有页。
|
||||
- 统计“回复数”：所有 `item.reply_list.replies` 数量之和减去 `items` 数量。
|
||||
- 统计“总互动数”：所有 `item.reply_list.replies` 数量之和，包含每张评论卡片的首条评论。
|
||||
- 如果 `item.has_more=true`，继续调用 `drive file.comment.replys list` 拉全该卡片下的回复，再做全量统计。
|
||||
|
||||
## 排序
|
||||
|
||||
- 只有用户明确提到“最新评论”“最后评论”“最早评论”时，才需要按 `create_time` 排序。
|
||||
- 排序前必须先处理分页，拉完所有评论；不要只取第一页排序。
|
||||
- “最新评论” / “最后评论”：按 `create_time` 降序取第一条。
|
||||
- “最早评论”：按 `create_time` 升序取第一条。
|
||||
- 用户只说“第一条评论”时，直接使用 `drive file.comments list` 返回的第一条，不额外排序。
|
||||
|
||||
## 回复限制
|
||||
|
||||
- 全文评论不支持回复：`is_whole=true` 的评论无法添加回复。
|
||||
- 已解决评论不支持回复：`is_solved=true` 的评论无法添加回复。
|
||||
- 用户要回复某条评论但该评论不能回复时，只提示限制原因；不要自动替用户寻找其他可回复评论。
|
||||
|
||||
## 批量查询与 reaction
|
||||
|
||||
- `drive file.comments batch_query` 只用于已知评论 ID 后的批量查询，需要传入具体 comment ID 列表。
|
||||
- 遍历、统计、获取最新/最早评论等场景使用 `drive file.comments list`。
|
||||
- reaction（表情、点赞、谁点了什么、添加/删除表情）场景先阅读 [`lark-drive-reactions.md`](lark-drive-reactions.md)。
|
||||
@@ -1,49 +0,0 @@
|
||||
# drive permission guide
|
||||
|
||||
> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 了解 Drive 入口、身份路由和 Wiki token 解包规则；再阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证与全局参数。
|
||||
|
||||
## 权限申请
|
||||
|
||||
- 向文档 owner 申请 view / edit 权限时，优先使用 `drive +apply-permission`。
|
||||
- `drive +apply-permission` 仅支持 user 身份；不要用 bot 反复重试用户个人资源。
|
||||
- 如果用户只给 token，先尽量用 `drive +inspect` 或上下文恢复 URL / 类型，再申请权限。
|
||||
|
||||
## 公开权限错误码
|
||||
|
||||
调用 `drive.permission.public.patch` 修改公开权限时，常见业务错误码按下表处理：
|
||||
|
||||
| 错误码 | 处理建议 |
|
||||
|--------|----------|
|
||||
| `91009` | 当前文件已设置更高安全等级或受组织策略限制，无法开放到目标范围；提示用户在文档 UI 或安全设置中处理 |
|
||||
| `91010` | 文件 owner 或管理员设置不允许修改公开权限；需要 owner / 管理员调整策略 |
|
||||
| `91011` | 当前身份没有修改公开权限的权限；切换到有权限的 user，或让 owner 授权 |
|
||||
| `91012` | 目标公开范围不符合当前租户策略；不要继续扩大权限，提示用户按组织策略处理 |
|
||||
|
||||
如果错误信息与上表不一致，以接口返回的 `msg` / `error` 为准，并给出下一步可执行动作。
|
||||
|
||||
## 授权当前应用访问文档
|
||||
|
||||
当需要把文档权限授予**当前应用（bot）自身**时，先获取当前 bot 的 `open_id`，再授权给该 `open_id`：
|
||||
|
||||
```bash
|
||||
# 1. 获取当前应用的 open_id
|
||||
lark-cli api GET /open-apis/bot/v3/info --as bot
|
||||
|
||||
# 2. 授权当前应用访问文档
|
||||
lark-cli drive permission.members create \
|
||||
--params '{"token":"<doc_token>","type":"<resource_type>"}' \
|
||||
--data '{"member_type":"openid","member_id":"<bot_open_id>","perm":"view","type":"user"}'
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 此方式只适用于授权给当前应用自身。
|
||||
- 授权给其他用户时，直接使用对方的 `open_id`，不要调用 bot info。
|
||||
- 不要转移 owner，除非用户明确要求且已说明影响。
|
||||
- `<resource_type>` 常见值：`doc`、`docx`、`sheet`、`bitable`、`file`、`folder`、`wiki`、`slides`。
|
||||
|
||||
## 身份判断
|
||||
|
||||
- 用户个人云空间、用户拥有的文档、公开权限申请、密级标签等场景优先 `--as user`。
|
||||
- bot 创建或已授权给 bot 的资源可使用 `--as bot`。
|
||||
- bot 因资源不可见失败时，说明资源可见性问题；建议切换 user 身份或先给 bot 授权，不要盲目重试。
|
||||
@@ -1,6 +1,6 @@
|
||||
# drive reactions
|
||||
|
||||
> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 了解 Drive 入口与身份路由；再阅读 [`lark-drive-comments-guide.md`](lark-drive-comments-guide.md) 了解评论卡片模型、评论数/回复数统计口径、`file_token` / `file_type` 规则；最后阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 了解 Drive 评论卡片模型、评论数/回复数统计口径、`file_token` / `file_type` 规则；再阅读 [`../../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
处理文档评论 / 回复上的 reaction（点赞、表情、各表情数量、谁点了什么、添加/删除表情）。这个场景不常见，但规则比较集中：查询时只有在用户明确需要 reaction 信息时才带 `need_reaction=true`；写入时统一使用 `drive file.comment.reply.reactions update_reaction`，操作对象始终是 `reply_id`。
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: lark-markdown
|
||||
version: 1.2.0
|
||||
description: "飞书 Markdown：查看、创建、上传、编辑和比较 Drive 原生 Markdown 文件。当用户需要创建或编辑 `.md` 文件、读取、修改、局部 patch 或比较差异时使用。不负责：把 Markdown 导入成飞书在线文档 docx（走 lark-drive 的 drive +import --type docx）、文件搜索/权限/评论/移动/删除等云空间管理操作（走 lark-drive）。"
|
||||
description: "飞书 Markdown：查看、创建、上传、编辑和比较 Markdown 文件。当用户需要创建或编辑 Markdown 文件、读取、修改、局部 patch 或比较差异时使用。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["lark-cli"]
|
||||
@@ -23,13 +23,6 @@ metadata:
|
||||
- 用户要把本地 Markdown **导入成在线新版文档（docx）**，不要用本 skill，改用 [`lark-drive`](../lark-drive/SKILL.md) 的 `lark-cli drive +import --type docx`
|
||||
- 用户要对 Markdown 文件做**rename / move / delete / 搜索 / 权限 / 评论**等云空间（云盘/云存储）操作，不要留在本 skill，切到 [`lark-drive`](../lark-drive/SKILL.md)
|
||||
|
||||
## 身份策略
|
||||
|
||||
- 所有 markdown shortcut 同时支持 `--as user` 和 `--as bot`
|
||||
- 访问用户个人云空间或用户拥有的文件时，优先使用 `--as user`
|
||||
- CI / 自动化场景、bot 自己创建或已被授权访问的 Markdown 文件，可使用 `--as bot`
|
||||
- 如果 bot 因看不到用户资源而失败，不要反复重试；提示用户改用 `--as user` 或先给 bot 授权
|
||||
|
||||
## 核心边界
|
||||
|
||||
- 本 skill 处理的是 **Drive 中作为普通文件存储的 Markdown**，不是 docx 文档
|
||||
@@ -41,7 +34,7 @@ metadata:
|
||||
- `markdown +patch` 的内部语义是：**先完整下载 Markdown，再本地替换，再整文件覆盖上传**
|
||||
- `markdown +patch` 不是服务端原子 patch；它是 CLI 侧编排出来的局部更新能力
|
||||
- `markdown +patch` 当前只支持**单组** `--pattern` / `--content`
|
||||
- `markdown +patch` 替换后的最终内容**不能为空**；Drive 不支持 0 字节 Markdown，且空结果通常代表误清空，CLI 会直接报错，不会上传空文件
|
||||
- `markdown +patch` 替换后的最终内容**不能为空**；如果替换后整篇 Markdown 变成空字符串，CLI 会直接报错，不会上传空文件
|
||||
- `--file` 只接受本地 `.md` 文件路径
|
||||
|
||||
## Shortcuts（推荐优先使用）
|
||||
@@ -50,11 +43,11 @@ Shortcut 是对常用操作的高级封装（`lark-cli markdown +<verb> [flags]`
|
||||
|
||||
| Shortcut | 说明 |
|
||||
|----------|------|
|
||||
| [`+create`](references/lark-markdown-create.md) | 在 Drive 中创建原生 Markdown 文件 |
|
||||
| [`+diff`](references/lark-markdown-diff.md) | 比较两个远端 Markdown 历史版本，或比较远端 Markdown 与本地文件 |
|
||||
| [`+fetch`](references/lark-markdown-fetch.md) | 读取 Drive 中的原生 Markdown 文件 |
|
||||
| [`+patch`](references/lark-markdown-patch.md) | 通过下载、替换、覆盖上传的方式局部更新 Markdown 文件 |
|
||||
| [`+overwrite`](references/lark-markdown-overwrite.md) | 覆盖更新 Drive 中已有的 Markdown 文件 |
|
||||
| [`+create`](references/lark-markdown-create.md) | Create a Markdown file in Drive |
|
||||
| [`+diff`](references/lark-markdown-diff.md) | Compare two remote Markdown versions, or compare remote Markdown against a local file |
|
||||
| [`+fetch`](references/lark-markdown-fetch.md) | Fetch a Markdown file from Drive |
|
||||
| [`+patch`](references/lark-markdown-patch.md) | Patch a Markdown file in Drive via fetch-local-replace-overwrite |
|
||||
| [`+overwrite`](references/lark-markdown-overwrite.md) | Overwrite an existing Markdown file in Drive |
|
||||
|
||||
## 参考
|
||||
|
||||
|
||||
@@ -63,42 +63,9 @@ lark-cli markdown +patch \
|
||||
- `--content` 必须显式传入，但允许为空字符串
|
||||
- 未加 `--regex` 时，行为等价于对整份 Markdown 文本执行 `strings.ReplaceAll`
|
||||
- 加了 `--regex` 时，行为等价于对整份 Markdown 文本执行 RE2 全量替换；`--content` 里的 `$1`、`${name}` 会按 Go regexp replacement template 解释，字面 `$` 请写成 `$$`
|
||||
- 替换后的最终 Markdown 不能为空；Drive 不支持 0 字节 Markdown，且空结果通常代表误清空，CLI 会直接报错，不会上传空文件
|
||||
- 替换后的最终 Markdown 不能为空；如果 patch 结果是空字符串，CLI 会直接报错，不会上传空文件
|
||||
- `0` 命中时命令仍然成功返回，但不会上传新版本
|
||||
|
||||
## GOOD / BAD：正则转义
|
||||
|
||||
`--pattern` 默认是字面量，不需要正则转义。只有传 `--regex` 时，`--pattern` 才按 Go RE2 正则解释。
|
||||
|
||||
```bash
|
||||
# GOOD：默认字面量模式，括号和点号按普通文本匹配
|
||||
lark-cli markdown +patch \
|
||||
--file-token boxcnxxxx \
|
||||
--pattern 'TODO(v1.2)' \
|
||||
--content 'DONE(v1.2)'
|
||||
|
||||
# BAD：开启 --regex 后，未转义的 . 会匹配任意字符，括号会变成分组
|
||||
lark-cli markdown +patch \
|
||||
--file-token boxcnxxxx \
|
||||
--regex \
|
||||
--pattern 'TODO(v1.2)' \
|
||||
--content 'DONE'
|
||||
|
||||
# GOOD：开启 --regex 后，按 RE2 规则转义字面括号和点号
|
||||
lark-cli markdown +patch \
|
||||
--file-token boxcnxxxx \
|
||||
--regex \
|
||||
--pattern 'TODO\\(v1\\.2\\)' \
|
||||
--content 'DONE'
|
||||
|
||||
# GOOD：replacement 里需要字面 $ 时写成 $$
|
||||
lark-cli markdown +patch \
|
||||
--file-token boxcnxxxx \
|
||||
--regex \
|
||||
--pattern 'price: (\\d+)' \
|
||||
--content 'price: $$1'
|
||||
```
|
||||
|
||||
## 实现边界
|
||||
|
||||
- 该命令的内部语义是：**download -> local replace -> overwrite upload**
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: lark-minutes
|
||||
version: 1.0.0
|
||||
description: "飞书妙记：妙记相关基本功能。1.查询妙记列表（按关键词/所有者/参与者/时间范围）；2.获取妙记基础信息（标题、封面、时长 等）；3.下载妙记音视频文件；4.获取妙记相关 AI 产物（总结、待办、章节）；5.上传音视频生成妙记，也支持将本地音视频文件转成纪要、逐字稿、文字稿、撰写文字等产物；6.更新妙记标题（重命名妙记）；7.替换妙记逐字稿中的说话人。遇到这类请求时，应优先使用本 skill。飞书妙记 URL 格式: http(s)://<host>/minutes/<minute-token>"
|
||||
description: "飞书妙记：妙记相关基本功能。1.查询妙记列表（按关键词/所有者/参与者/时间范围）；2.获取妙记基础信息（标题、封面、时长 等）；3.下载妙记音视频文件；4.获取/编辑妙记 AI 产物（总结、待办、章节）；5.上传音视频生成妙记，也支持将本地音视频文件转成纪要、逐字稿、文字稿、撰写文字等产物；6.更新妙记标题（重命名妙记）；7.替换妙记逐字稿中的说话人；8.在指定妙记中新增/更新/删除 AI 待办（minutes +todo，不是飞书任务 Task）。遇到这类请求时，应优先使用本 skill。飞书妙记 URL 格式: http(s)://<host>/minutes/<minute-token>"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["lark-cli"]
|
||||
@@ -46,20 +46,19 @@ metadata:
|
||||
|
||||
> **注意**：`+download` 只负责音视频媒体文件。如果用户需要的是逐字稿、总结、待办、章节等纪要内容，请使用 [vc +notes --minute-tokens](../lark-vc/references/lark-vc-notes.md)。
|
||||
|
||||
### 4. 获取妙记的逐字稿、总结、待办、章节
|
||||
### 4. 读取妙记的逐字稿、总结、待办、章节（只读）
|
||||
|
||||
1. 当用户说"这个妙记的逐字稿""总结""待办""章节"时，**不属于本 skill**。
|
||||
2. 应使用 [vc +notes --minute-tokens](../lark-vc/references/lark-vc-notes.md) 获取对应的纪要产物。
|
||||
3. 如果当前上下文中已有 `minute_token`，可直接传给 `vc +notes`；如果只有妙记 URL，先提取 `minute_token`。
|
||||
4. 如果用户给的是**本地音视频文件**，但目标是"转成纪要""转成逐字稿""转成文字稿""转成撰写文字"，也支持；此时应先按下文第 5 节上传文件生成妙记，再把返回的 `minute_url` 提取成 `minute_token`，继续调用 `vc +notes --minute-tokens`。
|
||||
5. 用户如果直接给出本地文件名或路径，并要求"转逐字稿""转文字稿""整理成撰写文字"，这也是本 skill 的明确触发信号。
|
||||
1. 当用户要**查看 / 读取**"这个妙记的逐字稿""总结""待办""章节"时，使用 [vc +notes --minute-tokens](../lark-vc/references/lark-vc-notes.md)。
|
||||
2. 如果当前上下文中已有 `minute_token`，可直接传给 `vc +notes`；如果只有妙记 URL，先提取 `minute_token`。
|
||||
3. 如果用户给的是**本地音视频文件**，但目标是"转成纪要""转成逐字稿""转成文字稿""转成撰写文字"，应先按下文第 5 节上传文件生成妙记，再把返回的 `minute_url` 提取成 `minute_token`，继续调用 `vc +notes --minute-tokens`。
|
||||
4. 用户如果直接给出本地文件名或路径，并要求"转逐字稿""转文字稿""整理成撰写文字"，这也是本 skill 的明确触发信号。
|
||||
|
||||
```bash
|
||||
# 通过 minute_token 获取纪要产物（逐字稿、总结、待办、章节）
|
||||
lark-cli vc +notes --minute-tokens <minute_token>
|
||||
```
|
||||
|
||||
> **跨 skill 路由**：逐字稿、AI 总结、待办、章节等纪要内容由 [lark-vc](../lark-vc/SKILL.md) 的 `+notes` 命令提供
|
||||
> **读 vs 写**：`vc +notes` 只负责**读取** AI 产物。用户要**新建 / 修改 / 删除**妙记内的 AI 待办或替换 AI 总结，见下文第 6 节，**不要**走 [lark-task](../lark-task/SKILL.md)。
|
||||
|
||||
### 5. 上传音视频文件生成妙记（并可继续获取纪要 / 逐字稿）
|
||||
|
||||
@@ -74,6 +73,42 @@ lark-cli vc +notes --minute-tokens <minute_token>
|
||||
>
|
||||
> **不要误走本地转写工具**：当用户目标是把本地音视频文件转成纪要、逐字稿、文字稿、撰写文字时，不要改用 `ffmpeg`、`whisper` 或其他本地 ASR/转码命令；标准路径就是 `drive +upload -> minutes +upload -> vc +notes --minute-tokens`。
|
||||
|
||||
### 6. 编辑妙记的 AI 待办与 AI 总结（写入）
|
||||
|
||||
当用户要在**某条妙记内**操作 AI 待办或 AI 总结时使用本节。**不是**飞书任务（Task）清单里的待办。
|
||||
|
||||
**触发信号（任一命中即走本 skill，禁止走 lark-task）**：
|
||||
|
||||
- "在（某条）妙记里新建 / 添加 / 修改 / 删除待办"
|
||||
- "把妙记 A 的待办改成已完成 / 未完成"
|
||||
- "妙记里的任务1 / 任务2"（上下文已明确是妙记）
|
||||
- 已给出 `minute_token` 或妙记 URL，且要改待办 / 总结
|
||||
|
||||
**妙记 AI 待办 vs 飞书任务 Task**：
|
||||
|
||||
| 用户意图 | 正确命令 | 错误命令 |
|
||||
|---------|---------|---------|
|
||||
| 妙记里加待办 | `minutes +todo --operation add` 或 `--todos '[...]'` | `task +create` / `task tasklists list` |
|
||||
| 妙记里改待办 | `minutes +todo --operation update --todo-id ...` | `task +update` |
|
||||
| 妙记里删待办 | `minutes +todo --operation delete --todo-id ...` | `task tasks delete` |
|
||||
| 我的任务清单 | — | 走 [lark-task](../lark-task/SKILL.md) |
|
||||
|
||||
**新建多条待办**：优先用 `--todos` 一次提交；单条则用多次 `--operation add`：
|
||||
|
||||
```bash
|
||||
# 批量：任务1 已完成 + 任务2 未完成
|
||||
lark-cli minutes +todo --minute-token <token> --as user --todos '[
|
||||
{"operation":"add","content":"晚上好1","is_done":true},
|
||||
{"operation":"add","content":"晚上好2","is_done":false}
|
||||
]'
|
||||
```
|
||||
|
||||
**更新 / 删除前**：先用 `vc +notes --minute-tokens <token>` 读取 `todos[].todo_id`（按 `content` 匹配目标条目；列表顺序不保证稳定，**不要**用"第 2 条"代替 `todo_id`）。
|
||||
|
||||
**替换 AI 总结全文**：见 [minutes +summary](references/lark-minutes-summary.md)。
|
||||
|
||||
> 使用 `+todo` 前必须阅读 [references/lark-minutes-todo.md](references/lark-minutes-todo.md)；使用 `+summary` 前必须阅读 [references/lark-minutes-summary.md](references/lark-minutes-summary.md)。
|
||||
|
||||
## 资源关系
|
||||
|
||||
```text
|
||||
@@ -82,24 +117,27 @@ Minutes (妙记) ← minute_token 标识
|
||||
└── MediaFile (音频/视频文件) → minutes +download
|
||||
```
|
||||
|
||||
> **能力边界**：`minutes` 负责 **搜索妙记、查看基础元信息、下载音视频文件、上传音视频生成妙记**。
|
||||
> **能力边界**：`minutes` 负责 **搜索妙记、查看基础元信息、下载/上传音视频、编辑妙记 AI 待办与 AI 总结、重命名、逐字稿说话人/关键词替换**。
|
||||
>
|
||||
> **路由规则**：
|
||||
>
|
||||
> - 用户说"妙记列表 / 搜索妙记 / 某个关键词的妙记" → `minutes +search`
|
||||
> - 用户只是想看"我的妙记 / 某段时间内的妙记 / 妙记列表"，不要先走 [lark-vc](../lark-vc/SKILL.md)，而应直接使用本 skill
|
||||
> - 用户如果同时提到"会议 / 会 / 开会 / 某场会"，即使也提到了"妙记"，也应优先走 [lark-vc](../lark-vc/SKILL.md) 先定位会议，再通过 [vc +recording](../lark-vc/references/lark-vc-recording.md) 获取 `minute_token`
|
||||
> - 用户如果要的是妙记基础信息，拿到 `minute_token` 后用 `minutes minutes get`；用户如果要的是逐字稿、文字稿、撰写文字、总结、待办、章节，再走 `vc +notes --minute-tokens`
|
||||
> - 用户如果要的是妙记基础信息，拿到 `minute_token` 后用 `minutes minutes get`；用户如果要**读取**逐字稿、文字稿、撰写文字、总结、待办、章节，再走 `vc +notes --minute-tokens`
|
||||
> - “我的妙记”“参与的妙记”等自然语言映射细则，以 [minutes +search](references/lark-minutes-search.md) 为准
|
||||
> - 结果有多页时，使用 `page_token` 持续翻页，直到确认没有更多结果
|
||||
> - `minutes +search` 单次最多返回 `200` 条；结果总数没有固定上限
|
||||
> - 用户说"这个妙记的标题 / 时长 / 封面 / 链接" → `minutes minutes get`
|
||||
> - 用户说"下载这个妙记的视频 / 音频 / 媒体文件" → `minutes +download`
|
||||
> - 用户说"这个妙记的逐字稿 / 文字稿 / 撰写文字 / 总结 / 待办 / 章节" → 使用 [vc +notes --minute-tokens](../lark-vc/references/lark-vc-notes.md)
|
||||
> - 用户要**读取**"这个妙记的逐字稿 / 文字稿 / 撰写文字 / 总结 / 待办 / 章节" → [vc +notes --minute-tokens](../lark-vc/references/lark-vc-notes.md)
|
||||
> - 用户要在**妙记内新建 / 修改 / 删除 AI 待办**（含「妙记里加待办」「任务1 已完成」等）→ [`minutes +todo`](references/lark-minutes-todo.md)，**禁止**走 lark-task
|
||||
> - 用户要**替换妙记 AI 总结全文** → [`minutes +summary`](references/lark-minutes-summary.md)
|
||||
> - 用户说"通过文件生成妙记 / 把音视频转妙记" → 先上传获取 `file_token`，然后使用 `minutes +upload`
|
||||
> - 用户说"把音视频文件转成纪要 / 逐字稿 / 文字稿 / 撰写文字 / 总结 / 待办 / 章节" → 先上传获取 `file_token`，调用 `minutes +upload` 生成 `minute_url`，再提取 `minute_token` 走 `vc +notes --minute-tokens`
|
||||
> - 用户说"重命名妙记 / 改妙记标题 / 修改妙记名字" → `minutes +update`
|
||||
> - 用户说"替换说话人 / 把 A 的发言改成 B / 重新归属发言人" → `minutes +speaker-replace`
|
||||
> - 用户说"批量替换逐字稿关键词" → `minutes +word-replace`
|
||||
|
||||
## Shortcuts（推荐优先使用）
|
||||
|
||||
@@ -112,12 +150,16 @@ Shortcut 是对常用操作的高级封装（`lark-cli minutes +<verb> [flags]`
|
||||
| [`+upload`](references/lark-minutes-upload.md) | Upload a media file token to generate a minute |
|
||||
| [`+update`](references/lark-minutes-update.md) | Update a minute's title |
|
||||
| [`+speaker-replace`](references/lark-minutes-speaker-replace.md) | Replace a speaker in a minute's transcript (rebind from one user to another) |
|
||||
| [`+summary`](references/lark-minutes-summary.md) | Replace the full AI summary text of a minute |
|
||||
| [`+todo`](references/lark-minutes-todo.md) | Add, update, or delete **AI todo(s) inside a minute** (single or batch via `--todos`; not Feishu Task) |
|
||||
|
||||
- 使用 `+search` 命令时，必须阅读 [references/lark-minutes-search.md](references/lark-minutes-search.md)，了解搜索参数和返回值结构。
|
||||
- 使用 `+download` 命令时，必须阅读 [references/lark-minutes-download.md](references/lark-minutes-download.md)，了解下载参数和返回值结构。
|
||||
- 使用 `+upload` 命令时，必须阅读 [references/lark-minutes-upload.md](references/lark-minutes-upload.md)，了解生成参数和返回值结构。
|
||||
- 使用 `+update` 命令时，必须阅读 [references/lark-minutes-update.md](references/lark-minutes-update.md)，了解修改参数和返回值结构。
|
||||
- 使用 `+speaker-replace` 命令时，必须阅读 [references/lark-minutes-speaker-replace.md](references/lark-minutes-speaker-replace.md)，了解参数和限制（仅支持用户 ID，不支持姓名）。
|
||||
- 使用 `+summary` 命令时，必须阅读 [references/lark-minutes-summary.md](references/lark-minutes-summary.md)，了解全文替换参数。
|
||||
- 使用 `+todo` 命令时，必须阅读 [references/lark-minutes-todo.md](references/lark-minutes-todo.md)，了解单条与 `--todos` 批量模式；**不要**用 lark-task。
|
||||
|
||||
<!-- AUTO-GENERATED-START — gen-skills.py 管理，勿手动编辑 -->
|
||||
|
||||
@@ -143,5 +185,7 @@ lark-cli minutes <resource> <method> [flags] # 调用 API
|
||||
| `+download` | `minutes:minutes.media:export` |
|
||||
| `+update` | `minutes:minutes:update` |
|
||||
| `+speaker-replace` | `minutes:minutes:update` |
|
||||
| `+summary` | `minutes:minutes:update` |
|
||||
| `+todo` | `minutes:minutes:update` |
|
||||
|
||||
<!-- AUTO-GENERATED-END -->
|
||||
|
||||
122
skills/lark-minutes/references/lark-minutes-summary.md
Normal file
122
skills/lark-minutes/references/lark-minutes-summary.md
Normal file
@@ -0,0 +1,122 @@
|
||||
# minutes +summary
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
替换妙记的 AI 总结内容。写操作，会覆盖当前总结。
|
||||
|
||||
本 skill 对应 shortcut：`lark-cli minutes +summary`（调用 `PUT /open-apis/minutes/v1/minutes/{minute_token}/summary`）。
|
||||
|
||||
## 典型触发表达
|
||||
|
||||
- "把这条妙记的总结改成……"
|
||||
- "更新 / 替换妙记的 AI 总结"
|
||||
- "修正总结内容后写回妙记"
|
||||
|
||||
## 命令
|
||||
|
||||
```bash
|
||||
# 直接传入总结内容（Markdown 子集）
|
||||
lark-cli minutes +summary --minute-token obcnxxxxxxxxxxxxxxxxxxxx --summary "**会议结论**\n- 方案 A 通过\n- 下周跟进排期"
|
||||
|
||||
# 从文件读取总结内容
|
||||
lark-cli minutes +summary --minute-token obcnxxxxxxxxxxxxxxxxxxxx --summary @summary.md
|
||||
|
||||
# 从 stdin 读取
|
||||
echo "**结论**" | lark-cli minutes +summary --minute-token obcnxxxxxxxxxxxxxxxxxxxx --summary @-
|
||||
|
||||
# 预览 API 调用
|
||||
lark-cli minutes +summary --minute-token obcnxxxxxxxxxxxxxxxxxxxx --summary @summary.md --dry-run
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--minute-token <token>` | 是 | 妙记 Token |
|
||||
| `--summary <text>` | 是 | 替换后的总结内容，支持 `@file` / `@-`（stdin） |
|
||||
| `--dry-run` | 否 | 预览 API 调用，不执行 |
|
||||
|
||||
## 核心约束
|
||||
|
||||
### 1. 先读后写
|
||||
|
||||
替换前建议先用 `lark-cli vc +notes --minute-tokens <token>` 读取当前总结，确认 `minute_token` 与待替换内容无误。
|
||||
|
||||
### 2. Markdown 展示说明
|
||||
|
||||
接口接受任意总结文本，**不会因 Markdown 格式校验失败而拒绝请求**。妙记客户端通常只能良好渲染以下 Markdown 子集；不支持的语法（如链接、代码块、四级标题等）会**按原始文本展示**（保留 Markdown 标记字符，不会渲染成对应样式）。Agent 写入时应优先使用可展示语法，避免用户在妙记里看到字面量的 `[链接](url)`、`` `code` `` 等：
|
||||
|
||||
| 支持 | 写法 | 示例 |
|
||||
|------|------|------|
|
||||
| 纯文本 | 普通段落 | `本次会议讨论了 Q2 预算` |
|
||||
| 换行 | `\n` 或空行 | 分段落书写 |
|
||||
| 一级标题 | `# ` + 标题文字 | `# 会议结论` |
|
||||
| 二级标题 | `## ` + 标题文字 | `## 行动项` |
|
||||
| 三级标题 | `### ` + 标题文字 | `### 跟进事项` |
|
||||
| 加粗 | `**文字**` | `**重点结论**` |
|
||||
| 无序列表 | `- ` 或 `* ` | `- 跟进预算审批` |
|
||||
| 有序列表 | `1. ` | `1. 确认需求` |
|
||||
|
||||
> 标题语法建议：`#` 后保留空格，并优先使用 1～3 级（`#` / `##` / `###`）。四级及以上（`####`）无法渲染，会以原始文本形式展示。
|
||||
|
||||
**不建议使用**（会按原始文本展示）：链接、图片、代码块、表格、引用块、斜体、删除线、四级及以上标题等。
|
||||
|
||||
合法示例：
|
||||
|
||||
```markdown
|
||||
# 会议结论
|
||||
|
||||
## 核心讨论
|
||||
|
||||
**方案 A 通过**，下周启动排期。
|
||||
|
||||
### 待跟进
|
||||
- 预算审批
|
||||
- 排期确认
|
||||
|
||||
1. 张三负责预算
|
||||
2. 李四负责排期
|
||||
```
|
||||
|
||||
### 3. 所需权限
|
||||
|
||||
| 身份 | 所需权限 |
|
||||
|------|---------|
|
||||
| user | `minutes:minutes:update` |
|
||||
|
||||
## 输出结果
|
||||
|
||||
```json
|
||||
{
|
||||
"minute_token": "obcnxxxxxxxxxxxxxxxxxxxx",
|
||||
"updated": true
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `minute_token` | 妙记 Token |
|
||||
| `updated` | 是否已成功更新 |
|
||||
|
||||
## 如何获取 minute_token
|
||||
|
||||
| 来源 | 获取方式 |
|
||||
|------|---------|
|
||||
| 妙记 URL | 从 URL 末尾提取，如 `https://sample.feishu.cn/minutes/obcnxxxxxxxxxxxxxxxxxxxx` |
|
||||
| 妙记搜索 | `lark-cli minutes +search --query "关键词"` |
|
||||
| 会议产物查询 | `lark-cli vc +notes --minute-tokens <token>` |
|
||||
|
||||
## 常见错误与排查
|
||||
|
||||
| 错误现象 | 错误码 | 根本原因 | 解决方案 |
|
||||
|---------|--------|---------|---------|
|
||||
| 总结展示为原始 Markdown 文本 | — | 总结含链接、四级标题等妙记端无法渲染的语法 | 改用标题（#～###）、加粗、列表等可展示格式；接口不会因此报错 |
|
||||
| 参数无效 | — | `minute_token` 缺失或格式错误 | 检查 token 是否完整 |
|
||||
| 权限不足 | — | 缺少 `minutes:minutes:update` | 运行 `auth login --scope "minutes:minutes:update"` |
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-minutes](../SKILL.md) — 妙记全部命令
|
||||
- [minutes +todo](lark-minutes-todo.md) — 替换待办项
|
||||
- [lark-vc-notes](../../lark-vc/references/lark-vc-notes.md) — 读取总结、待办等 AI 产物
|
||||
- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数
|
||||
137
skills/lark-minutes/references/lark-minutes-todo.md
Normal file
137
skills/lark-minutes/references/lark-minutes-todo.md
Normal file
@@ -0,0 +1,137 @@
|
||||
# minutes +todo
|
||||
|
||||
> **路由**：本命令操作**妙记内的 AI 待办**，不是飞书任务（Task）。用户说「在妙记里新建待办」时**必须**用本命令，**禁止**走 `lark-cli task` / `tasklists list` / `task +create`。详见 [lark-minutes/SKILL.md](../SKILL.md) 第 6 节。
|
||||
|
||||
> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。
|
||||
|
||||
对妙记中的待办做新增 / 更新 / 删除（单条或批量）。写操作。
|
||||
|
||||
本 skill 对应 shortcut：`lark-cli minutes +todo`（调用 `POST /open-apis/minutes/v1/minutes/{minute_token}/todo`）。
|
||||
|
||||
## 典型触发表达
|
||||
|
||||
- "给这条妙记加一条/多条待办"
|
||||
- "把某条待办改成……"
|
||||
- "标记某条待办为已完成 / 取消完成"
|
||||
- "删除某条待办"
|
||||
|
||||
## 命令
|
||||
|
||||
**单条模式**：`--operation` + 对应字段。
|
||||
**批量模式**：`--todos` JSON 数组（与单条 flags 互斥），一次请求可混合 `add` / `update` / `delete`。
|
||||
|
||||
```bash
|
||||
# 单条：新增
|
||||
lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --operation add --todo "跟进预算审批" --is-done=false --as user
|
||||
|
||||
# 批量：一次新增两条
|
||||
lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --as user --todos '[
|
||||
{"operation":"add","content":"晚上好1","is_done":true},
|
||||
{"operation":"add","content":"晚上好2","is_done":false}
|
||||
]'
|
||||
|
||||
# 批量：混合增删改
|
||||
lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --as user --todos '[
|
||||
{"operation":"add","content":"新待办","is_done":false},
|
||||
{"operation":"update","todo_id":"1234567890","content":"已更新","is_done":true},
|
||||
{"operation":"delete","todo_id":"9876543210"}
|
||||
]'
|
||||
|
||||
# 从文件读取
|
||||
lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --as user --todos @todos.json
|
||||
|
||||
# 单条：更新 / 删除
|
||||
lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --operation update --todo-id 1234567890 --todo "整理会议纪要" --is-done --as user
|
||||
lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --operation delete --todo-id 1234567890 --as user
|
||||
|
||||
# 预览
|
||||
lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --operation add --todo "新待办" --is-done --dry-run --as user
|
||||
```
|
||||
|
||||
## 参数
|
||||
|
||||
| 参数 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `--minute-token <token>` | 是 | 妙记 Token |
|
||||
| `--operation <op>` | 单条模式 | `add` / `update` / `delete`；与 `--todos` 互斥 |
|
||||
| `--todo <text>` | 单条 add/update | 待办纯文本 |
|
||||
| `--is-done` | 单条 add/update | `--is-done` = true，`--is-done=false` = false |
|
||||
| `--todo-id <id>` | 单条 update/delete | 已有待办 id |
|
||||
| `--todos <json>` | 批量模式 | JSON 数组，支持 `@file` / `@-`；与单条 flags 互斥 |
|
||||
| `--dry-run` | 否 | 预览 API 调用，不执行 |
|
||||
|
||||
## 单条模式
|
||||
|
||||
| `--operation` | 必填参数 | 禁止参数 |
|
||||
|---------------|----------|----------|
|
||||
| `add` | `--todo` + `--is-done` | `--todo-id` |
|
||||
| `update` | `--todo-id` + `--todo` + `--is-done` | — |
|
||||
| `delete` | `--todo-id` | `--todo`、`--is-done` |
|
||||
|
||||
## 批量模式：`--todos`
|
||||
|
||||
每条元素字段与 API `todo_items[]` 一致：
|
||||
|
||||
| JSON 字段 | add | update | delete |
|
||||
|-----------|-----|--------|--------|
|
||||
| `operation` | 必填 | 必填 | 必填 |
|
||||
| `content` | 必填 | 必填 | 禁止 |
|
||||
| `is_done` | 必填 | 必填 | 禁止 |
|
||||
| `todo_id` | 禁止 | 必填 | 必填 |
|
||||
|
||||
示例 `todos.json`：
|
||||
|
||||
```json
|
||||
[
|
||||
{"operation": "add", "content": "晚上好1", "is_done": true},
|
||||
{"operation": "add", "content": "晚上好2", "is_done": false}
|
||||
]
|
||||
```
|
||||
|
||||
数组顺序会原样写入请求体；端上展示顺序仍可能受完成状态分组影响。
|
||||
|
||||
## 核心约束
|
||||
|
||||
### 1. 先读后写，待办 id 如何获取
|
||||
|
||||
更新 / 删除前先用 `lark-cli vc +notes --minute-tokens <token>` 读取当前待办。返回的每条待办带 `todo_id` 字段。
|
||||
|
||||
> 待办 id 仅用于程序内部定位，不必展示给用户。
|
||||
|
||||
### 2. 待办内容为纯文本
|
||||
|
||||
`content` **不是 Markdown**，请直接传入待办描述文字。
|
||||
|
||||
### 3. 所需权限
|
||||
|
||||
| 身份 | 所需 scope |
|
||||
|------|-----------|
|
||||
| user | `minutes:minutes:update` |
|
||||
|
||||
## 输出结果
|
||||
|
||||
```json
|
||||
{
|
||||
"minute_token": "obcnxxxxxxxxxxxxxxxxxxxx",
|
||||
"count": 2,
|
||||
"updated": true
|
||||
}
|
||||
```
|
||||
|
||||
单条模式额外包含 `"operation": "add"`。
|
||||
|
||||
## 常见错误与排查
|
||||
|
||||
| 错误现象 | 解决方案 |
|
||||
|---------|---------|
|
||||
| 未指定操作 | 单条模式传 `--operation`，或批量传 `--todos` |
|
||||
| `--todos` 与单条 flags 冲突 | 二选一 |
|
||||
| `todos[i]` 校验失败 | 检查该条 `operation` 与字段组合 |
|
||||
| 权限不足 | `auth login --scope "minutes:minutes:update"` |
|
||||
|
||||
## 参考
|
||||
|
||||
- [lark-minutes](../SKILL.md)
|
||||
- [minutes +summary](lark-minutes-summary.md)
|
||||
- [lark-vc-notes](../../lark-vc/references/lark-vc-notes.md)
|
||||
- [lark-shared](../../lark-shared/SKILL.md)
|
||||
@@ -1,48 +0,0 @@
|
||||
# Wiki token routing
|
||||
|
||||
> **前置条件：** 先阅读 [`../SKILL.md`](../SKILL.md) 了解认证、全局参数、身份选择和错误处理。
|
||||
|
||||
Wiki 链接里的 `/wiki/<token>` 是知识库节点 token，不是底层文档、表格、Base、幻灯片或文件 token。处理 Wiki URL 时先解包，再按底层对象类型路由到对应 skill 或 API。
|
||||
|
||||
## 推荐入口
|
||||
|
||||
优先使用 `drive +inspect` 自动识别 URL 类型并解包 Wiki 节点：
|
||||
|
||||
```bash
|
||||
lark-cli drive +inspect --url 'https://example.feishu.cn/wiki/<wiki_token>'
|
||||
```
|
||||
|
||||
返回里的 `type`、`token`、`title`、`url` 是后续操作的 canonical 信息。后续命令使用返回的 canonical token，不要继续把 Wiki 节点 token 当作文件 token 传入。
|
||||
|
||||
## 手动解包
|
||||
|
||||
当 shortcut 不满足需求时，用 Wiki 节点接口查询底层对象：
|
||||
|
||||
```bash
|
||||
lark-cli wiki spaces get_node --params '{"token":"<wiki_token>"}'
|
||||
```
|
||||
|
||||
从返回结果中读取：
|
||||
|
||||
- `node.obj_type`：底层对象类型
|
||||
- `node.obj_token`：底层对象 token
|
||||
- `node.space_id`：知识空间 ID
|
||||
- `node.title`：节点标题
|
||||
|
||||
## 路由表
|
||||
|
||||
| `obj_type` | 后续处理 |
|
||||
|------------|----------|
|
||||
| `docx` / `doc` | 文档正文读取和编辑走 `lark-doc`；评论、权限、导出、文件元数据走 `lark-drive` |
|
||||
| `sheet` | 单元格、工作表、导出等表格操作走 `lark-sheets`；评论、权限、文件元数据走 `lark-drive` |
|
||||
| `bitable` | 表、字段、记录、视图、表单、仪表盘、工作流走 `lark-base`；评论、权限、文件元数据走 `lark-drive` |
|
||||
| `slides` | 幻灯片内容编辑走 `lark-slides`；导出、评论、权限、文件元数据走 `lark-drive` |
|
||||
| `file` | 普通文件上传、下载、移动、删除、权限、评论走 `lark-drive` |
|
||||
| `mindnote` | 按当前 CLI 支持能力优先走 `lark-drive`；缺口再评估原生 OpenAPI |
|
||||
|
||||
## 规则
|
||||
|
||||
- 不要把 Wiki 节点 token 直接当作 `doc_token`、`file_token`、`spreadsheet_token`、`app_token` 或 `presentation_token`。
|
||||
- Wiki 节点、空间目录、成员管理等知识库结构操作保留 Wiki 节点 token，走 `lark-wiki`。
|
||||
- 内容、评论、权限、导出等底层对象操作使用解包后的 `obj_token`。
|
||||
- 如果用户只给 Wiki URL，先解析类型；不要凭标题、路径或上下文猜底层对象类型。
|
||||
@@ -16,7 +16,11 @@ metadata:
|
||||
> **任务清单搜索技巧**：任务清单也遵循同样的判断逻辑。先区分用户是否**特地指定使用搜索 skill**，以及是否真的提供了**清单查询关键字**（例如清单名称、关键词、片段描述）。如果用户特地指定使用搜索 skill，或明确给出了清单查询关键字，则优先使用 `+tasklist-search`。如果用户没有特地指定使用搜索 skill，且意图里没有查询关键字，只有范围条件（例如“由我创建的任务清单”“今年以来创建的清单”），并且使用搜索或原生列取清单都能达到目的时，应优先使用原生 `tasklists.list` 接口列取清单（先 `schema task.tasklists.list`，再 `lark-cli task tasklists list --as user ...`），再按 `creator`、`created_at` 等字段做本地筛选和分页控制。
|
||||
> **意图区分补充**：像“搜索飞书中今年以来我关注的任务”这类表达，虽然字面带有“搜索”，但如果没有真正的查询关键字，且本质是在限定“与我相关 + 时间范围”，则应优先走 `+get-related-tasks`；像“搜索飞书中由我创建的任务清单”这类表达，如果没有清单关键字，且本质是在限定“清单范围 + 创建者”，则应优先走原生 `tasklists.list` 后筛选，而不是直接走搜索型 shortcut。
|
||||
> **用户身份识别**：在用户身份（user identity）场景下，如果用户提到了“我”（例如“分配给我”、“由我创建”），请默认获取当前登录用户的 `open_id` 作为对应的参数值。
|
||||
> **术语理解**：如果用户提到 “todo”（待办），应当思考其是否是指“task”（任务），并优先尝试使用本 Skill 提供的命令来处理。
|
||||
> **术语理解 — 待办 disambiguation（必读）**：
|
||||
> - 用户提到「待办 / todo / 任务」时，**先判断归属**，不要默认走本 skill。
|
||||
> - **走 [lark-minutes](../lark-minutes/SKILL.md) 的 `minutes +todo`**（禁止本 skill）：上下文含 **妙记 / 会议纪要 / minute_token / 妙记 URL**（`/minutes/`）；或「在某某妙记里新建/修改待办」「妙记 AI 待办」「会议录制里的待办」。
|
||||
> - **走本 skill（lark-task）**：任务清单、分配给我、项目待办、截止日期/提醒、子任务、任务清单成员；或 applink 含 `client/todo/task?guid=`；或明确说「飞书任务」「任务中心」「我的任务清单」。
|
||||
> - **禁止**：用户要在妙记里加待办时，**不要**调用 `task tasklists list`、`task +create` 或任何 task 命令去「找清单再放任务」。
|
||||
> **友好输出**：在输出任务（或清单）的执行结果给用户时，建议同时提取并输出命令返回结果中的 `url` 字段（任务链接），以便用户可以直接点击跳转查看详情。
|
||||
|
||||
> **创建/更新注意**：
|
||||
|
||||
@@ -91,7 +91,7 @@ lark-cli vc +notes --meeting-ids 69xxxxxxxxxxxxx28 --dry-run
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `artifacts.summary` | AI 总结（JSON 内联） |
|
||||
| `artifacts.todos` | 待办事项（JSON 内联） |
|
||||
| `artifacts.todos` | 待办事项（JSON 内联，**只读**）；每条含 `content`、`is_done` 及 `todo_id`。`todo_id` 仅供 [`minutes +todo`](../../lark-minutes/references/lark-minutes-todo.md) 更新/删除待办时使用，不必展示给用户。**新建**妙记内待办请用 `minutes +todo`，不要用 lark-task |
|
||||
| `artifacts.chapters` | 章节纪要（JSON 内联） |
|
||||
| `artifacts.keywords` | 妙记推荐关键词（JSON 内联） |
|
||||
| `artifacts.transcript_file` | 逐字稿本地文件路径。默认落到 `./minutes/{minute_token}/transcript.txt`（与 `minutes +download` 聚合）；显式 `--output-dir` 时走旧布局 `./{output-dir}/artifact-{title}-{token}/transcript.txt` |
|
||||
|
||||
39
tests/cli_e2e/minutes/minutes_word_replace_test.go
Normal file
39
tests/cli_e2e/minutes/minutes_word_replace_test.go
Normal file
@@ -0,0 +1,39 @@
|
||||
// Copyright (c) 2026 Lark Technologies Pte. Ltd.
|
||||
// SPDX-License-Identifier: MIT
|
||||
|
||||
package minutes
|
||||
|
||||
import (
|
||||
"context"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
clie2e "github.com/larksuite/cli/tests/cli_e2e"
|
||||
"github.com/stretchr/testify/assert"
|
||||
"github.com/stretchr/testify/require"
|
||||
)
|
||||
|
||||
func TestMinutesWordReplace_DryRun(t *testing.T) {
|
||||
setDryRunConfigEnv(t)
|
||||
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
|
||||
t.Cleanup(cancel)
|
||||
|
||||
result, err := clie2e.RunCmd(ctx, clie2e.Request{
|
||||
Args: []string{
|
||||
"minutes", "+word-replace",
|
||||
"--minute-token", "obcnexampleminute",
|
||||
"--replace-words", `[{"source_word":"foo","target_word":"bar"}]`,
|
||||
"--dry-run",
|
||||
},
|
||||
DefaultAs: "user",
|
||||
})
|
||||
require.NoError(t, err)
|
||||
result.AssertExitCode(t, 0)
|
||||
|
||||
output := result.Stdout
|
||||
assert.True(t, strings.Contains(output, "PUT"), "dry-run should contain PUT method, got: %s", output)
|
||||
assert.True(t, strings.Contains(output, "/open-apis/minutes/v1/minutes/obcnexampleminute/transcript/word"), "dry-run should contain API path, got: %s", output)
|
||||
assert.True(t, strings.Contains(output, "foo"), "dry-run should contain source_word, got: %s", output)
|
||||
assert.True(t, strings.Contains(output, "bar"), "dry-run should contain target_word, got: %s", output)
|
||||
}
|
||||
Reference in New Issue
Block a user