docs: clarify mindnote token discovery

shortcuts/mail/mail_read_help_test.go

@@ -94,7 +94,7 @@ func TestMailTriageTableHintRoutesSingleAndMultipleReads(t *testing.T) {
 	registerTriageReadHintStubs(reg)
 
 	err := runMountedMailShortcut(t, MailTriage, []string{
-		"+triage", "--format", "table", "--max", "1",
+		"+triage", "--max", "1",
 	}, f, stdout)
 	if err != nil {
 		t.Fatalf("triage returned error: %v", err)

shortcuts/mail/mail_triage.go

@@ -55,7 +55,7 @@ var MailTriage = common.Shortcut{
 	Scopes:      []string{"mail:user_mailbox.message:readonly", "mail:user_mailbox.message.address:read", "mail:user_mailbox.message.subject:read", "mail:user_mailbox.message.body:read"},
 	AuthTypes:   []string{"user", "bot"},
 	Flags: []common.Flag{
-		{Name: "format", Default: "json", Enum: []string{"table", "json", "data"}, Desc: "output format: table | json | data (json/data output object with pagination fields)"},
+		{Name: "format", Default: "table", Enum: []string{"table", "json", "data"}, Desc: "output format: table | json | data (json/data output object with pagination fields)"},
 		{Name: "max", Type: "int", Default: "20", Desc: "maximum number of messages to fetch (1-400; auto-paginates internally)"},
 		{Name: "page-size", Type: "int", Desc: "alias for --max"},
 		{Name: "page-token", Desc: "pagination token from a previous response to fetch the next page"},

shortcuts/mail/mail_triage_test.go

@@ -1655,39 +1655,6 @@ func TestMailTriageMissingMessageMetadataStillGetsMailboxID(t *testing.T) {
 	}
 }
 
-// TestMailTriageDefaultFormatIsJSON verifies that with no --format flag the
-// command defaults to json and prints the paginated object to stdout, not the
-// human table.
-func TestMailTriageDefaultFormatIsJSON(t *testing.T) {
-	f, stdout, _, reg := mailShortcutTestFactory(t)
-	defer reg.Verify(t)
-
-	registerMailTriageListStub(reg, "me", []string{"msg_ok"}, false, "")
-	registerMailTriageBatchStub(reg, "me", []map[string]interface{}{
-		mailTriageBatchMessage("msg_ok", "Present"),
-	})
-
-	err := runMountedMailShortcut(t, MailTriage, []string{
-		"+triage",
-		"--filter", `{"folder_id":"INBOX"}`,
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	data := decodeMailTriageJSONOutput(t, stdout) // fails to unmarshal if default were table
-	messages := mailTriageMessagesFromOutput(t, data)
-	if len(messages) != 1 {
-		t.Fatalf("expected 1 message, got %d", len(messages))
-	}
-	if _, ok := data["count"]; !ok {
-		t.Fatalf("default json output missing count field: %#v", data)
-	}
-	if _, ok := data["has_more"]; !ok {
-		t.Fatalf("default json output missing has_more field: %#v", data)
-	}
-}
-
 // TestMailTriageTableOutputPreservesMailboxContext verifies public mailbox table hints.
 func TestMailTriageTableOutputPreservesMailboxContext(t *testing.T) {
 	tests := []struct {
@@ -1711,7 +1678,7 @@ func TestMailTriageTableOutputPreservesMailboxContext(t *testing.T) {
 				mailTriageBatchMessage("msg_001", "Table message"),
 			})
 
-			args := []string{"+triage", "--format", "table", "--max", "1", "--filter", `{"folder_id":"INBOX"}`}
+			args := []string{"+triage", "--max", "1", "--filter", `{"folder_id":"INBOX"}`}
 			if tt.mailbox != "me" {
 				args = append(args, "--mailbox", tt.mailbox)
 			}
@@ -1752,7 +1719,6 @@ func TestMailTriageDefaultTableOutputPrintsSearchNoticeToStderr(t *testing.T) {
 
 	if err := runMountedMailShortcut(t, MailTriage, []string{
 		"+triage",
-		"--format", "table",
 		"--query", strings.Repeat("q", 81),
 	}, f, stdout); err != nil {
 		t.Fatalf("unexpected error: %v", err)

shortcuts/mail/mail_watch.go

@@ -99,7 +99,7 @@ var MailWatch = common.Shortcut{
 	Scopes:      []string{"mail:event", "mail:user_mailbox.event.mail_address:read", "mail:user_mailbox:readonly", "mail:user_mailbox.message:readonly", "mail:user_mailbox.message.address:read", "mail:user_mailbox.message.subject:read", "mail:user_mailbox.message.body:read"},
 	AuthTypes:   []string{"user"},
 	Flags: []common.Flag{
-		{Name: "format", Default: "json", Enum: []string{"json", "data"}, Desc: "json: NDJSON stream with ok/data envelope; data: bare NDJSON stream"},
+		{Name: "format", Default: "data", Enum: []string{"json", "data"}, Desc: "json: NDJSON stream with ok/data envelope; data: bare NDJSON stream"},
 		{Name: "msg-format", Default: "metadata", Desc: "message payload mode: metadata(headers + meta, for triage/notification) | minimal(IDs and state only, no headers, for tracking read/folder changes) | plain_text_full(all metadata fields + full plain-text body) | event(raw WebSocket event, no API call, for debug) | full(full message including HTML body and attachments)"},
 		{Name: "output-dir", Desc: "Write each message as a JSON file (always full payload, regardless of --msg-format)"},
 		{Name: "mailbox", Default: "me", Desc: "email address (default: me)"},
@@ -385,7 +385,12 @@ var MailWatch = common.Shortcut{
 				}
 			}
 
-			output.PrintNdjson(out, watchOutputValue(outFormat, string(runtime.As()), outputData))
+			switch outFormat {
+			case "json", "":
+				output.PrintNdjson(out, output.Envelope{OK: true, Identity: string(runtime.As()), Data: outputData})
+			case "data":
+				output.PrintNdjson(out, outputData)
+			}
 		}
 
 		rawHandler := func(ctx context.Context, event *larkevent.EventReq) error {
@@ -682,17 +687,6 @@ func minimalWatchMessage(message map[string]interface{}) map[string]interface{}
 	return out
 }
 
-// watchOutputValue selects the per-event value that +watch prints as NDJSON:
-// "data" emits the bare payload; every other format (json — the default) wraps
-// it in an ok/identity/data envelope. Extracted from Execute so the default
-// envelope behavior is unit-testable without a live WebSocket.
-func watchOutputValue(outFormat, identity string, outputData interface{}) interface{} {
-	if outFormat == "data" {
-		return outputData
-	}
-	return output.Envelope{OK: true, Identity: identity, Data: outputData}
-}
-
 func watchFetchFailureValue(messageID, fetchFormat string, err error, eventBody map[string]interface{}) map[string]interface{} {
 	payload := map[string]interface{}{
 		"ok": false,

shortcuts/mail/mail_watch_test.go

@@ -885,59 +885,3 @@ func dryRunAPIsForMailWatchTest(t *testing.T, dry *common.DryRunAPI) []struct {
 	}
 	return payload.API
 }
-
-// TestWatchOutputValueDefaultIsJSONEnvelope verifies +watch's default format
-// (json) wraps each event in an ok/identity/data envelope, while --format data
-// emits the bare payload. Covers the default-format behavior without a live
-// WebSocket (addresses the coderabbitai review ask).
-func TestWatchOutputValueDefaultIsJSONEnvelope(t *testing.T) {
-	payload := map[string]interface{}{"message": map[string]interface{}{"message_id": "m1"}}
-
-	// default (json) → ok/identity/data envelope
-	b, err := json.Marshal(watchOutputValue("json", "user", payload))
-	if err != nil {
-		t.Fatalf("marshal json value: %v", err)
-	}
-	var env map[string]interface{}
-	if err := json.Unmarshal(b, &env); err != nil {
-		t.Fatalf("unmarshal json value: %v", err)
-	}
-	if env["ok"] != true {
-		t.Fatalf("default json must have ok:true, got %s", b)
-	}
-	if env["identity"] != "user" {
-		t.Fatalf("default json must carry identity, got %s", b)
-	}
-	if _, ok := env["data"]; !ok {
-		t.Fatalf("default json must have data field, got %s", b)
-	}
-
-	// empty format (safety) also defaults to the json envelope
-	b3, err := json.Marshal(watchOutputValue("", "bot", payload))
-	if err != nil {
-		t.Fatalf("marshal empty-format value: %v", err)
-	}
-	var env3 map[string]interface{}
-	if err := json.Unmarshal(b3, &env3); err != nil {
-		t.Fatalf("unmarshal empty-format value: %v", err)
-	}
-	if env3["ok"] != true {
-		t.Fatalf("empty format should default to json envelope, got %s", b3)
-	}
-
-	// --format data → bare payload, no envelope
-	b2, err := json.Marshal(watchOutputValue("data", "user", payload))
-	if err != nil {
-		t.Fatalf("marshal data value: %v", err)
-	}
-	var bare map[string]interface{}
-	if err := json.Unmarshal(b2, &bare); err != nil {
-		t.Fatalf("unmarshal data value: %v", err)
-	}
-	if _, hasOK := bare["ok"]; hasOK {
-		t.Fatalf("--format data must be bare (no envelope), got %s", b2)
-	}
-	if _, hasMsg := bare["message"]; !hasMsg {
-		t.Fatalf("--format data payload should carry message, got %s", b2)
-	}
-}

skills/lark-doc/SKILL.md

@@ -46,7 +46,7 @@ lark-cli docs +update --doc "文档URL或token" --command append --content '<p>
 - 用户明确说"下载/更新/删除文档封面图" → 用 `lark-cli docs +resource-download/+resource-update/+resource-delete --type cover`
 - `resource-*` 目前仅支持 Docx 封面资源；其他图片、附件或素材请走 `+media-*`
 - 如果目标是画板/whiteboard/画板缩略图 → 只能用 `lark-cli docs +media-download --type whiteboard`（不要用 `+media-preview`）
-- 用户明确要操作思维笔记时；已有**思维笔记**，走 [思维笔记链路](references/lark-doc-mindnote.md)；新建**思维笔记**，走 [lark-doc-whiteboard](references/lark-doc-whiteboard.md)
+- 用户明确要操作思维笔记时；已有**思维笔记**，走 [思维笔记链路](references/lark-doc-mindnote.md)，未给 URL/token 时先用 `lark-cli drive +search --doc-types mindnote` 定位 Mindnote 文档 token；新建**思维笔记**，走 [lark-doc-whiteboard](references/lark-doc-whiteboard.md)
 - 拿到 spreadsheet URL/token 后 → 切到 `lark-sheets` 做对象内部操作
 - 用户需要统计文档的**总字数 / 总字符数**（word count / character count）时，先读取 [`lark-doc-word-stat.md`](references/lark-doc-word-stat.md)，并按其中流程调用 [`scripts/doc_word_stat.py`](scripts/doc_word_stat.py)；统计口径以该脚本为准，不要改用其他方式自行计算。
 - 用户说"给文档加评论""查看评论""回复评论""给评论加/删除表情 reaction" → 切到 `lark-drive` 处理

skills/lark-doc/references/lark-doc-mindnote.md

@@ -9,6 +9,32 @@
 > `mindnotes nodes create` 是新增/更新节点命令，**不是**新建一个新的思维笔记。
 > 如果用户要**新建思维笔记**，不要走本链路，改走 [lark-doc-whiteboard](lark-doc-whiteboard.md)。
 
+## 获取 `mindnote_id`
+
+`--mindnote-id` 传 **Mindnote 文档 token**，不是节点 ID。`lark-cli mindnotes` 只负责读取和写入思维笔记内部节点，不提供按标题列出 Mindnote 文档的入口；找文档要先走 Drive。
+
+```bash
+# 用户给了 Mindnote URL，或给了可能包着 Mindnote 的 Wiki URL
+lark-cli drive +inspect --url "<mindnote_or_wiki_url>"
+
+# 用户只给了标题、关键词，或需要在云空间里找思维笔记
+lark-cli drive +search --query "<关键词>" --doc-types mindnote --format table
+
+# 用户想浏览自己负责的思维笔记
+lark-cli drive +search --doc-types mindnote --mine --sort edit_time --format table
+```
+
+处理规则：
+
+- 普通 Mindnote URL：`drive +inspect` 返回的 Mindnote token 可作为 `--mindnote-id`。
+- Wiki URL：不要把 `/wiki/` 路径里的 wiki token 当作 `--mindnote-id`；必须先 `drive +inspect` 解包，确认底层类型是 `mindnote` 后再使用返回的真实 token。直接把 wiki token 传给 `mindnotes nodes list` 通常会返回 `3410003 resource not found`。
+- 标题 / 关键词：用 `drive +search --doc-types mindnote` 定位；多候选时先让用户确认目标，不要猜。
+
+## 所需权限
+
+- 读取节点：需要用户授权包含 `mindnote:node:read`。
+- 创建 / 更新节点：需要用户授权包含对应写入 scope；如果命令返回 `missing_scope`，按 [`lark-shared`](../../lark-shared/SKILL.md) 的授权恢复流程，用错误里的 `hint` 或 `missing_scopes` 重新执行 `lark-cli auth login --scope ...`。
+
 ## 命令
 
 ```bash
@@ -96,8 +122,8 @@ lark-cli mindnotes nodes create \
 
 1. 先判断用户目标是不是“新建一个思维笔记”。
 2. 如果是新建思维笔记，切到 [lark-doc-whiteboard](lark-doc-whiteboard.md)。
-3. 如果是操作已有思维笔记，先通过 token 类别判断。
-4. 确认是 **Mindnote** 后再拿到 `mindnote_id`。
+3. 如果是操作已有思维笔记，先按上方「获取 `mindnote_id`」定位 Mindnote 文档 token。
+4. 确认目标类型是 **Mindnote** 后，把真实 Mindnote token 作为 `--mindnote-id`。
 5. 先执行 `mindnotes nodes list`，确认目标 `parent_id`。
 6. 新增子节点时，在 `nodes[]` 里传 `parent_id`；更新已有节点时，在 `nodes[]` 里传已有 `node_id`。
 7. 再执行 `mindnotes nodes create`。
@@ -110,4 +136,5 @@ lark-cli mindnotes nodes create \
 
 - [lark-doc-fetch](lark-doc-fetch.md) — 获取文档内容
 - [lark-doc-whiteboard](lark-doc-whiteboard.md) — 新建思维笔记走画板链路
+- [lark-drive](../../lark-drive/SKILL.md) — 搜索和解析 Mindnote / Wiki 等云空间资源
 - [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

skills/lark-mail/references/lark-mail-triage.md

@@ -49,7 +49,7 @@ lark-cli mail +triage --page-size 10
 |------|------|------|
 | `--filter <json>` | — | 筛选条件（见下方字段说明） |
 | `--query <text>` | — | 全文搜索关键词 |
-| `--format <mode>` | `json` | `json`（默认，输出含分页信息的对象）/ `data`（同 `json`）/ `table`（人类可读表格） |
+| `--format <mode>` | `table` | `table` / `json` / `data`（`json` 和 `data` 均输出含分页信息的对象） |
 | `--max <n>` | `20` | 最大返回条数（1-400），内部自动分页拉取 |
 | `--page-size <n>` | — | `--max` 的别名，两者含义相同；同时指定时 `--page-size` 优先 |
 | `--page-token <token>` | — | 上一次响应返回的分页令牌，传入后从该位置继续拉取。令牌带 `search:` 或 `list:` 前缀，标识来源路径，不可混用 |

skills/lark-mail/references/lark-mail-watch.md

@@ -47,7 +47,7 @@ lark-cli mail +watch --print-output-schema
 |------|------|------|
 | `--mailbox <id>` | `me` | 订阅目标邮箱 |
 | `--msg-format <mode>` | `metadata` | 输出模式：`metadata` / `minimal` / `plain_text_full` / `full` / `event` |
-| `--format <mode>` | `json` | 输出样式：`json`（默认，带 ok/data 信封的 NDJSON 流）/ `data`（裸 NDJSON 流） |
+| `--format <mode>` | `data` | 输出样式：`json`（带 ok/data 信封的 NDJSON 流）/ `data`（裸 NDJSON 流） |
 | `--folder-ids <json-array>` | — | 文件夹 ID 过滤，如 `["INBOX","SENT"]` |
 | `--folders <json-array>` | — | 文件夹名称过滤（与 `--folder-ids` 取并集） |
 | `--label-ids <json-array>` | — | 标签 ID 过滤，如 `["FLAGGED","IMPORTANT"]` |