chore(release): v1.0.45 (#1207)

CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.45] - 2026-06-01
+
+### Features
+
+- **errors**: Add typed envelope contract for auth-domain errors (#1135)
+- **platform**: Support multiple policy rules per plugin (#1182)
+
+### Bug Fixes
+
+- **vc**: Add domain boundaries and enrich `+notes` (#1172)
+- **whiteboard**: Fix whiteboard skill (#1180)
+
+### Refactor
+
+- **auth**: Update login hint and split-flow docs (#1201)
+
 ## [v1.0.44] - 2026-05-29
 
 ### Features
@@ -948,6 +964,7 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.45]: https://github.com/larksuite/cli/releases/tag/v1.0.45
 [v1.0.44]: https://github.com/larksuite/cli/releases/tag/v1.0.44
 [v1.0.43]: https://github.com/larksuite/cli/releases/tag/v1.0.43
 [v1.0.42]: https://github.com/larksuite/cli/releases/tag/v1.0.42

cmd/auth/login.go

@@ -279,7 +279,13 @@ func authLoginRun(opts *LoginOptions) error {
 			"verification_url": authResp.VerificationUriComplete,
 			"device_code":      authResp.DeviceCode,
 			"expires_in":       authResp.ExpiresIn,
-			"hint":             fmt.Sprintf("**MUST generate QR code AND display it:** You MUST call lark-cli auth qrcode to convert verification_url into a QR code. This is a required step, do NOT skip it. Prefer PNG QR code (--output); use ASCII (--ascii) only when the user explicitly requests it.**CRITICAL: You MUST include the QR image in your response.** Generating the file alone is NOT enough—use image tags, inline images, or file attachments to display it.**Display order:** Output the URL first, then place the QR code image below the URL.**URL Output Rules:** Treat verification_url as an opaque string that cannot be modified. Do NOT URL-encode/decode or add spaces/punctuation. For agent harnesses that only deliver final turn messages, make the QR code image (or URL) the final message of the turn and return control to the user; do not block on --device-code in the same turn. After the user confirms authorization in a later step, run: lark-cli auth login --device-code %s", authResp.DeviceCode),
+			"hint": "**MUST generate QR code AND display it:** You MUST call lark-cli auth qrcode to convert verification_url into a QR code. This is a required step, do NOT skip it. Prefer PNG QR code (--output); use ASCII (--ascii) only when the user explicitly requests it." +
+				"**CRITICAL: You MUST include the QR image in your response.** Generating the file alone is NOT enough—use image tags, inline images, or file attachments to display it." +
+				"**Display order:** Output the URL first, then place the QR code image below the URL." +
+				"**URL Output Rules:** Treat verification_url as an opaque string that cannot be modified. Do NOT URL-encode/decode or add spaces/punctuation." +
+				"For agent harnesses that only deliver final turn messages, make the QR code image (or URL) the final message of the turn and return control to the user; do not block on --device-code in the same turn. **Before ending the turn, tell the user to come back and notify you after completing authorization.**" +
+				"**After the user confirms authorization:** YOU must execute `lark-cli auth login --device-code <device_code>` yourself." +
+				"**Do NOT cache verification_url or device_code for future use.** Always run `lark-cli auth login --no-wait --json` fresh when authorization is needed.",
 		}
 		encoder := json.NewEncoder(f.IOStreams.Out)
 		encoder.SetEscapeHTML(false)

cmd/auth/login_test.go

@@ -1042,8 +1042,11 @@ func TestAuthLoginRun_NoWaitJSONHintIncludesRawURLGuidance(t *testing.T) {
 		"final message of the turn",
 		"return control to the user",
 		"do not block on --device-code in the same turn",
-		"After the user confirms authorization in a later step",
-		"lark-cli auth login --device-code device-code",
+		"come back and notify",
+		"YOU must execute",
+		"lark-cli auth login --device-code <device_code>",
+		"Do NOT cache",
+		"lark-cli auth login --no-wait --json",
 	} {
 		if !strings.Contains(hint, want) {
 			t.Fatalf("hint missing %q, got:\n%s", want, hint)

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larksuite/cli",
-  "version": "1.0.44",
+  "version": "1.0.45",
   "description": "The official CLI for Lark/Feishu open platform",
   "bin": {
     "lark-cli": "scripts/run.js"

shortcuts/vc/vc_notes.go

@@ -38,6 +38,8 @@ import (
 var (
 	scopesMeetingIDs = []string{
 		"vc:meeting.meetingevent:read",
+		"vc:note:read",
+		"vc:record:readonly",
 	}
 	scopesMinuteTokens = []string{
 		"minutes:minutes:readonly",
@@ -48,6 +50,7 @@ var (
 		"calendar:calendar:read",
 		"calendar:calendar.event:read",
 		"vc:meeting.meetingevent:read",
+		"vc:record:readonly",
 	}
 )
 
@@ -59,6 +62,37 @@ const (
 
 const logPrefix = "[vc +notes]"
 
+const (
+	minutesNoReadPermissionCode = 2091005
+
+	// recording API specific error codes (used to surface meeting minute_token state).
+	recordingNotFoundCode     = 121004 // 该会议没有妙记文件
+	recordingNoPermissionCode = 121005 // 非会议参与者无权查看
+	recordingGeneratingCode   = 124002 // 录制/妙记文件仍在生成中
+
+	// note detail API specific error code.
+	noteNoPermissionCode = 121005 // 调用者没有该纪要的阅读权限
+)
+
+func minutesReadError(err error, minuteToken string) error {
+	var exitErr *output.ExitError
+	if !errors.As(err, &exitErr) || exitErr.Detail == nil || exitErr.Detail.Code != minutesNoReadPermissionCode {
+		return err
+	}
+
+	return &output.ExitError{
+		Code: output.ExitAPI,
+		Detail: &output.ErrDetail{
+			Type:    "no_read_permission",
+			Code:    minutesNoReadPermissionCode,
+			Message: fmt.Sprintf("No read permission for minute %s: cannot query the minute.", minuteToken),
+			Hint:    "Ask the minute owner for minute file read permission",
+			Detail:  exitErr.Detail.Detail,
+		},
+		Err: err,
+	}
+}
+
 // validMinuteToken matches the server's minute-token format and blocks any
 // user-supplied token from reaching filesystem paths unsanitized.
 var validMinuteToken = regexp.MustCompile(`^[a-z0-9]+$`)
@@ -196,7 +230,10 @@ func fetchNoteByCalendarEventID(ctx context.Context, runtime *common.RuntimeCont
 	for _, meetingID := range relInfo.MeetingIDs {
 		fmt.Fprintf(errOut, "%s event %s → meeting_id=%s\n", logPrefix, sanitizeLogValue(instanceID), sanitizeLogValue(meetingID))
 		noteResult := fetchNoteByMeetingID(ctx, runtime, meetingID)
-		if noteResult["error"] == nil {
+		// success means note detail was retrieved, regardless of whether the
+		// recording API (minute_token) call succeeded — minute_token failures
+		// surface as part of the merged `error` string for downstream visibility.
+		if _, ok := noteResult["note_doc_token"].(string); ok {
 			for k, v := range noteResult {
 				result[k] = v
 			}
@@ -246,7 +283,51 @@ func asStringSlice(v any) []string {
 	return ss
 }
 
-// fetchNoteByMeetingID queries notes via meeting_id.
+// fetchMeetingMinuteToken queries the recording API of a meeting and returns
+// the associated minute_token (parsed from the recording URL) and an
+// optional human-friendly error message. On success token is non-empty and
+// errMsg is empty; on failure token is empty and errMsg describes the cause:
+//   - 121004: meeting has no minute file
+//   - 121005: caller has no permission for the meeting recording
+//   - 124002: recording / minute file is still being generated
+//
+// Other failures fall back to the raw API error description so Agents can
+// still parse the underlying cause.
+func fetchMeetingMinuteToken(runtime *common.RuntimeContext, meetingID string) (token, errMsg string) {
+	data, err := runtime.DoAPIJSON(http.MethodGet,
+		fmt.Sprintf("/open-apis/vc/v1/meetings/%s/recording", validate.EncodePathSegment(meetingID)),
+		nil, nil)
+	if err != nil {
+		var exitErr *output.ExitError
+		if errors.As(err, &exitErr) && exitErr.Detail != nil {
+			switch exitErr.Detail.Code {
+			case recordingNotFoundCode:
+				return "", "no minute file for this meeting"
+			case recordingNoPermissionCode:
+				return "", "no permission to access this meeting's minute; ask the meeting owner to share the minute"
+			case recordingGeneratingCode:
+				return "", "minute file is still being generated; please retry later"
+			}
+		}
+		return "", fmt.Sprintf("failed to query recording: %v", err)
+	}
+
+	recording, _ := data["recording"].(map[string]any)
+	if recording == nil {
+		return "", "no recording available for this meeting"
+	}
+	recordingURL, _ := recording["url"].(string)
+	if t := extractMinuteToken(recordingURL); t != "" {
+		return t, ""
+	}
+	return "", "no minute_token found in recording URL"
+}
+
+// fetchNoteByMeetingID queries notes via meeting_id and additionally fetches
+// the meeting's minute_token via the recording API. The two paths are queried
+// independently; their failures are merged into a single `error` field
+// (semicolon-separated) so Agents always see all causes at once. The
+// `minute_token` field is only populated on success.
 func fetchNoteByMeetingID(ctx context.Context, runtime *common.RuntimeContext, meetingID string) map[string]any {
 	data, err := runtime.DoAPIJSON(http.MethodGet, fmt.Sprintf("/open-apis/vc/v1/meetings/%s", validate.EncodePathSegment(meetingID)),
 		larkcore.QueryParams{"with_participants": []string{"false"}, "query_mode": []string{"0"}}, nil)
@@ -259,16 +340,60 @@ func fetchNoteByMeetingID(ctx context.Context, runtime *common.RuntimeContext, m
 		return map[string]any{"meeting_id": meetingID, "error": "meeting not found"}
 	}
 
-	noteID, _ := meeting["note_id"].(string)
-	if noteID == "" {
-		return map[string]any{"meeting_id": meetingID, "error": "no notes available for this meeting"}
+	// Always attempt to query the meeting's minute_token via the recording API,
+	// regardless of whether the meeting has a note_id, so callers always see
+	// minute state for follow-up calls (e.g. `vc +notes --minute-tokens=...`).
+	minuteToken, minuteErr := fetchMeetingMinuteToken(runtime, meetingID)
+
+	var result map[string]any
+	var noteErr string
+	if noteID, _ := meeting["note_id"].(string); noteID != "" {
+		result = fetchNoteDetail(ctx, runtime, noteID)
+		if msg, _ := result["error"].(string); msg != "" {
+			noteErr = msg
+			delete(result, "error")
+		}
+	} else {
+		result = map[string]any{}
+		noteErr = "no notes available for this meeting"
 	}
 
-	result := fetchNoteDetail(ctx, runtime, noteID)
 	result["meeting_id"] = meetingID
+	if minuteToken != "" {
+		result["minute_token"] = minuteToken
+	}
+	if combined := joinErrors(noteErr, minuteErr); combined != "" {
+		result["error"] = combined
+	}
 	return result
 }
 
+// joinErrors merges multiple non-empty error messages with "; " so Agents can
+// see all causes at once when both note and minute paths fail.
+func joinErrors(msgs ...string) string {
+	parts := make([]string, 0, len(msgs))
+	for _, m := range msgs {
+		if m != "" {
+			parts = append(parts, m)
+		}
+	}
+	return strings.Join(parts, "; ")
+}
+
+// hasNotesPayload reports whether a result map carries any usable note or
+// minute payload, irrespective of partial failures surfaced via `error`.
+func hasNotesPayload(m map[string]any) bool {
+	if m == nil {
+		return false
+	}
+	for _, k := range []string{"note_doc_token", "verbatim_doc_token", "minute_token", "meeting_notes", "shared_doc_tokens", "artifacts"} {
+		if v, ok := m[k]; ok && v != nil && v != "" {
+			return true
+		}
+	}
+	return false
+}
+
 // fetchNoteByMinuteToken queries notes via minute_token.
 // Fetches both note detail (doc tokens) and AI artifacts (summary/todos/chapters inline +
 // transcript to file) independently, merging into a single result map for Agent consumption.
@@ -277,7 +402,13 @@ func fetchNoteByMinuteToken(ctx context.Context, runtime *common.RuntimeContext,
 
 	data, err := runtime.DoAPIJSON(http.MethodGet, fmt.Sprintf("/open-apis/minutes/v1/minutes/%s", validate.EncodePathSegment(minuteToken)), nil, nil)
 	if err != nil {
-		return map[string]any{"minute_token": minuteToken, "error": fmt.Sprintf("failed to query minutes: %v", err)}
+		err = minutesReadError(err, minuteToken)
+		result := map[string]any{"minute_token": minuteToken, "error": err.Error()}
+		var exitErr *output.ExitError
+		if errors.As(err, &exitErr) && exitErr.Detail != nil && exitErr.Detail.Hint != "" {
+			result["hint"] = exitErr.Detail.Hint
+		}
+		return result
 	}
 
 	minute, _ := data["minute"].(map[string]any)
@@ -472,6 +603,10 @@ func extractDocTokens(refs []any) []string {
 func fetchNoteDetail(_ context.Context, runtime *common.RuntimeContext, noteID string) map[string]any {
 	data, err := runtime.DoAPIJSON(http.MethodGet, fmt.Sprintf("/open-apis/vc/v1/notes/%s", validate.EncodePathSegment(noteID)), nil, nil)
 	if err != nil {
+		var exitErr *output.ExitError
+		if errors.As(err, &exitErr) && exitErr.Detail != nil && exitErr.Detail.Code == noteNoPermissionCode {
+			return map[string]any{"error": fmt.Sprintf("[%v]: no read permission for this meeting note", exitErr.Detail.Code)}
+		}
 		return map[string]any{"error": fmt.Sprintf("failed to query note detail: %v", err)}
 	}
 
@@ -568,8 +703,9 @@ var VCNotes = common.Shortcut{
 			return common.NewDryRunAPI().
 				GET("/open-apis/vc/v1/meetings/{meeting_id}").
 				GET("/open-apis/vc/v1/notes/{note_id}").
+				GET("/open-apis/vc/v1/meetings/{meeting_id}/recording").
 				Set("meeting_ids", common.SplitCSV(ids)).
-				Set("steps", "meeting.get → note_id → note detail API")
+				Set("steps", "meeting.get → note_id → note detail API + recording API → minute_token")
 		}
 		if tokens := runtime.Str("minute-tokens"); tokens != "" {
 			return common.NewDryRunAPI().
@@ -586,8 +722,9 @@ var VCNotes = common.Shortcut{
 			POST("/open-apis/calendar/v4/calendars/{calendar_id}/events/mget_instance_relation_info").
 			GET("/open-apis/vc/v1/meetings/{meeting_id}").
 			GET("/open-apis/vc/v1/notes/{note_id}").
+			GET("/open-apis/vc/v1/meetings/{meeting_id}/recording").
 			Set("calendar_event_ids", common.SplitCSV(ids)).
-			Set("steps", "primary calendar → mget_instance_relation_info → meeting_id → meeting.get → note detail API")
+			Set("steps", "primary calendar → mget_instance_relation_info → meeting_id → meeting.get → note detail API + recording API → minute_token")
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		errOut := runtime.IO().ErrOut
@@ -641,11 +778,13 @@ var VCNotes = common.Shortcut{
 			}
 		}
 
-		// count results
+		// count results: a result counts as "successful" when it carries any
+		// note/minute payload, even if the merged `error` field surfaces a
+		// partial failure (e.g. note ok but minute_token lookup failed).
 		successCount := 0
 		for _, r := range results {
 			m, _ := r.(map[string]any)
-			if m["error"] == nil {
+			if hasNotesPayload(m) {
 				successCount++
 			}
 		}

shortcuts/vc/vc_notes_test.go

@@ -728,3 +728,352 @@ func TestNotes_TranscriptExplicitOutputDir_PreservesLegacyLayout(t *testing.T) {
 		t.Errorf("minutes/ should not be created when --output-dir is explicit")
 	}
 }
+
+// ---------------------------------------------------------------------------
+// Tests for joinErrors / hasNotesPayload (pure helpers)
+// ---------------------------------------------------------------------------
+
+func TestJoinErrors(t *testing.T) {
+	tests := []struct {
+		name string
+		in   []string
+		want string
+	}{
+		{"all empty", []string{"", "", ""}, ""},
+		{"single", []string{"only"}, "only"},
+		{"two non-empty", []string{"a", "b"}, "a; b"},
+		{"skip empties", []string{"", "a", "", "b", ""}, "a; b"},
+		{"three", []string{"x", "y", "z"}, "x; y; z"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := joinErrors(tt.in...); got != tt.want {
+				t.Errorf("joinErrors(%v) = %q, want %q", tt.in, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestHasNotesPayload(t *testing.T) {
+	tests := []struct {
+		name string
+		in   map[string]any
+		want bool
+	}{
+		{"nil", nil, false},
+		{"empty", map[string]any{}, false},
+		{"only meta", map[string]any{"meeting_id": "m1", "error": "fail"}, false},
+		{"empty values", map[string]any{"note_doc_token": "", "minute_token": ""}, false},
+		{"has note_doc_token", map[string]any{"note_doc_token": "doc1"}, true},
+		{"has verbatim_doc_token", map[string]any{"verbatim_doc_token": "v1"}, true},
+		{"has minute_token", map[string]any{"minute_token": "obc"}, true},
+		{"has meeting_notes", map[string]any{"meeting_notes": []string{"d1"}}, true},
+		{"has shared_doc_tokens", map[string]any{"shared_doc_tokens": []string{"s1"}}, true},
+		{"has artifacts", map[string]any{"artifacts": map[string]any{"summary": "s"}}, true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := hasNotesPayload(tt.in); got != tt.want {
+				t.Errorf("hasNotesPayload(%v) = %v, want %v", tt.in, got, tt.want)
+			}
+		})
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Tests for fetchMeetingMinuteToken — recording API → minute_token mapping
+// ---------------------------------------------------------------------------
+
+// recordingStub is a small helper for shaping `/v1/meetings/{id}/recording` responses.
+func recordingStub(meetingID string, body map[string]any) *httpmock.Stub {
+	return &httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/vc/v1/meetings/" + meetingID + "/recording",
+		Body:   body,
+	}
+}
+
+func recordingErrStub(meetingID string, code int, msg string) *httpmock.Stub {
+	return recordingStub(meetingID, map[string]any{"code": code, "msg": msg})
+}
+
+func recordingOKStub(meetingID, url string) *httpmock.Stub {
+	return recordingStub(meetingID, map[string]any{
+		"code": 0, "msg": "ok",
+		"data": map[string]any{
+			"recording": map[string]any{"url": url},
+		},
+	})
+}
+
+func TestFetchMeetingMinuteToken_Success(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(recordingOKStub("m_ok", "https://meetings.feishu.cn/minutes/obctoken_ok"))
+
+	if err := botExec(t, "fmmt-ok", f, func(_ context.Context, rctx *common.RuntimeContext) error {
+		token, msg := fetchMeetingMinuteToken(rctx, "m_ok")
+		if token != "obctoken_ok" {
+			t.Errorf("token = %q, want obctoken_ok", token)
+		}
+		if msg != "" {
+			t.Errorf("errMsg = %q, want empty", msg)
+		}
+		return nil
+	}); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestFetchMeetingMinuteToken_KnownErrorCodes(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	cases := []struct {
+		name      string
+		meetingID string
+		code      int
+		wantMsg   string
+	}{
+		{"121004 not found", "m_121004", 121004, "no minute file for this meeting"},
+		{"121005 no permission", "m_121005", 121005, "no permission to access this meeting's minute"},
+		{"124002 generating", "m_124002", 124002, "minute file is still being generated"},
+	}
+	for _, tt := range cases {
+		t.Run(tt.name, func(t *testing.T) {
+			f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+			reg.Register(recordingErrStub(tt.meetingID, tt.code, "err"))
+
+			if err := botExec(t, "fmmt-"+tt.meetingID, f, func(_ context.Context, rctx *common.RuntimeContext) error {
+				token, msg := fetchMeetingMinuteToken(rctx, tt.meetingID)
+				if token != "" {
+					t.Errorf("token = %q, want empty on error", token)
+				}
+				if !strings.Contains(msg, tt.wantMsg) {
+					t.Errorf("errMsg = %q, want contains %q", msg, tt.wantMsg)
+				}
+				return nil
+			}); err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+		})
+	}
+}
+
+func TestFetchMeetingMinuteToken_GenericAPIError(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(recordingErrStub("m_other", 99999, "weird"))
+
+	if err := botExec(t, "fmmt-generic", f, func(_ context.Context, rctx *common.RuntimeContext) error {
+		token, msg := fetchMeetingMinuteToken(rctx, "m_other")
+		if token != "" {
+			t.Errorf("token = %q, want empty", token)
+		}
+		if !strings.Contains(msg, "failed to query recording") {
+			t.Errorf("errMsg = %q, want contains 'failed to query recording'", msg)
+		}
+		return nil
+	}); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestFetchMeetingMinuteToken_NoRecording(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(recordingStub("m_norec", map[string]any{
+		"code": 0, "msg": "ok",
+		"data": map[string]any{},
+	}))
+
+	if err := botExec(t, "fmmt-norec", f, func(_ context.Context, rctx *common.RuntimeContext) error {
+		token, msg := fetchMeetingMinuteToken(rctx, "m_norec")
+		if token != "" {
+			t.Errorf("token = %q, want empty", token)
+		}
+		if !strings.Contains(msg, "no recording available") {
+			t.Errorf("errMsg = %q, want contains 'no recording available'", msg)
+		}
+		return nil
+	}); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestFetchMeetingMinuteToken_URLWithoutToken(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(recordingOKStub("m_notok", "https://example.com/no/minute/path"))
+
+	if err := botExec(t, "fmmt-notok", f, func(_ context.Context, rctx *common.RuntimeContext) error {
+		token, msg := fetchMeetingMinuteToken(rctx, "m_notok")
+		if token != "" {
+			t.Errorf("token = %q, want empty", token)
+		}
+		if !strings.Contains(msg, "no minute_token found") {
+			t.Errorf("errMsg = %q, want contains 'no minute_token found'", msg)
+		}
+		return nil
+	}); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Integration: fetchNoteByMeetingID — note + minute_token combined behavior
+// ---------------------------------------------------------------------------
+
+// extractFirstNote runs +notes via --meeting-ids and returns the single result map.
+func extractFirstNote(t *testing.T, stdout *bytes.Buffer) map[string]any {
+	t.Helper()
+	var resp map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse output: %v\n%s", err, stdout.String())
+	}
+	data, _ := resp["data"].(map[string]any)
+	notes, _ := data["notes"].([]any)
+	if len(notes) != 1 {
+		t.Fatalf("expected 1 note, got %d (%v)", len(notes), notes)
+	}
+	note, _ := notes[0].(map[string]any)
+	return note
+}
+
+// assertNoteError verifies the result map's `error` field contains every
+// substring in wantSubstrs (order-independent). Pass an empty slice to assert
+// the field is absent. Centralized here so tests don't have to repeat the same
+// "for each substring, Contains + Errorf" pattern.
+func assertNoteError(t *testing.T, note map[string]any, wantSubstrs ...string) {
+	t.Helper()
+	errMsg, _ := note["error"].(string)
+	if len(wantSubstrs) == 0 {
+		if e, has := note["error"]; has {
+			t.Errorf("error should be absent, got %v", e)
+		}
+		return
+	}
+	for _, sub := range wantSubstrs {
+		if !strings.Contains(errMsg, sub) {
+			t.Errorf("error %q missing substring %q", errMsg, sub)
+		}
+	}
+}
+
+// assertNoteFieldAbsent fails the test if any of the named fields is present.
+func assertNoteFieldAbsent(t *testing.T, note map[string]any, fields ...string) {
+	t.Helper()
+	for _, f := range fields {
+		if v, has := note[f]; has {
+			t.Errorf("%s should be absent, got %v", f, v)
+		}
+	}
+}
+
+func TestNotes_MeetingPath_NoteAndMinuteBothOK(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(meetingGetStub("m_both", "note_both"))
+	reg.Register(noteDetailStub("note_both"))
+	reg.Register(recordingOKStub("m_both", "https://meetings.feishu.cn/minutes/obc_both"))
+
+	if err := mountAndRun(t, VCNotes, []string{"+notes", "--meeting-ids", "m_both", "--as", "user"}, f, stdout); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	note := extractFirstNote(t, stdout)
+	if got := note["note_doc_token"]; got != "doc_main" {
+		t.Errorf("note_doc_token = %v, want doc_main", got)
+	}
+	if got := note["minute_token"]; got != "obc_both" {
+		t.Errorf("minute_token = %v, want obc_both", got)
+	}
+	assertNoteError(t, note)
+}
+
+func TestNotes_MeetingPath_OnlyMinuteFails_PartialSuccess(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(meetingGetStub("m_minfail", "note_minfail"))
+	reg.Register(noteDetailStub("note_minfail"))
+	reg.Register(recordingErrStub("m_minfail", 121005, "no permission"))
+
+	if err := mountAndRun(t, VCNotes, []string{"+notes", "--meeting-ids", "m_minfail", "--as", "user"}, f, stdout); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	note := extractFirstNote(t, stdout)
+	if got := note["note_doc_token"]; got != "doc_main" {
+		t.Errorf("note_doc_token = %v, want doc_main", got)
+	}
+	assertNoteFieldAbsent(t, note, "minute_token")
+	assertNoteError(t, note, "no permission to access this meeting's minute")
+}
+
+func TestNotes_MeetingPath_NoNote_ButMinuteOK(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	// note_id missing on the meeting object → no notes, but minute_token present
+	reg.Register(meetingGetStub("m_nonote", ""))
+	reg.Register(recordingOKStub("m_nonote", "https://meetings.feishu.cn/minutes/obc_nonote"))
+
+	if err := mountAndRun(t, VCNotes, []string{"+notes", "--meeting-ids", "m_nonote", "--as", "user"}, f, stdout); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	note := extractFirstNote(t, stdout)
+	if got := note["minute_token"]; got != "obc_nonote" {
+		t.Errorf("minute_token = %v, want obc_nonote", got)
+	}
+	assertNoteError(t, note, "no notes available for this meeting")
+}
+
+func TestNotes_MeetingPath_BothFail_ErrorJoinedWithSemicolon(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	// no note_id → "no notes available..."; recording 121004 → "no minute file..."
+	reg.Register(meetingGetStub("m_bothfail", ""))
+	reg.Register(recordingErrStub("m_bothfail", 121004, "data not found"))
+
+	// Two-path failure with no payload should make the batch return ErrAPI.
+	err := mountAndRun(t, VCNotes, []string{"+notes", "--meeting-ids", "m_bothfail", "--as", "user"}, f, stdout)
+	if err == nil {
+		t.Fatalf("expected batch failure error, got nil")
+	}
+
+	note := extractFirstNote(t, stdout)
+	assertNoteFieldAbsent(t, note, "minute_token")
+	assertNoteError(t, note,
+		"no notes available for this meeting",
+		"no minute file for this meeting",
+		"; ", // causes joined with semicolon
+	)
+}
+
+// noteDetailErrStub returns a stub that emits an error response from
+// /open-apis/vc/v1/notes/{note_id}.
+func noteDetailErrStub(noteID string, code int, msg string) *httpmock.Stub {
+	return &httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/vc/v1/notes/" + noteID,
+		Body:   map[string]any{"code": code, "msg": msg},
+	}
+}
+
+func TestNotes_MeetingPath_NoteNoPermission_FriendlyHint(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	// note 接口返回 121005 → 阅读权限不足；同时 recording 也返回 121005，
+	// 用以验证两路错误都会被合并到顶层 error 字段（用 "; " 拼接）。
+	reg.Register(meetingGetStub("m_noteperm", "note_noperm"))
+	reg.Register(noteDetailErrStub("note_noperm", 121005, "no permission"))
+	reg.Register(recordingErrStub("m_noteperm", 121005, "no permission"))
+
+	err := mountAndRun(t, VCNotes, []string{"+notes", "--meeting-ids", "m_noteperm", "--as", "user"}, f, stdout)
+	if err == nil {
+		t.Fatalf("expected batch failure error, got nil")
+	}
+
+	note := extractFirstNote(t, stdout)
+	assertNoteFieldAbsent(t, note, "note_doc_token", "minute_token")
+	assertNoteError(t, note,
+		"[121005]",
+		"no read permission for this meeting note",
+		"; ", // note + minute causes joined with semicolon
+	)
+}

shortcuts/vc/vc_search.go

@@ -172,7 +172,7 @@ func meetingSearchDescription(item map[string]interface{}) string {
 var VCSearch = common.Shortcut{
 	Service:     "vc",
 	Command:     "+search",
-	Description: "Search meeting records (requires at least one filter)",
+	Description: "Search meeting records by keyword, time range, participant, organizer, or meeting room (requires at least one filter)",
 	Risk:        "read",
 	Scopes:      []string{"vc:meeting.search:read"},
 	AuthTypes:   []string{"user"},

skill-template/domains/drive.md

@@ -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`。

skill-template/skill-template.md

@@ -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}}

skills/lark-drive/SKILL.md

@@ -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`。
+
+- 评论写入内容（添加评论、回复评论、编辑回复）里的文本不能直接出现 `<`、`>`；提交前必须先转义：`<` -> `&lt;`，`>` -> `&gt;`。
+- 使用 `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`    |

skills/lark-drive/references/lark-drive-comments-guide.md

@@ -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)。

skills/lark-drive/references/lark-drive-permission-guide.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 授权，不要盲目重试。

skills/lark-drive/references/lark-drive-reactions.md

@@ -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`。
 

skills/lark-markdown/SKILL.md

@@ -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 |
 
 ## 参考
 

skills/lark-markdown/references/lark-markdown-patch.md

@@ -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**

skills/lark-minutes/SKILL.md

@@ -12,6 +12,12 @@ metadata:
 
 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
 
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-vc/references/vc-domain-boundaries.md`](../lark-vc/references/vc-domain-boundaries.md)**，不读将导致命令使用、会议产物决策、领域边界职责判断错误：
+> 1. 了解日历 & VC、会议产物 & 文档的关联关系和职责划分
+> 2. 了解会议产物（妙记和纪要）之间的关联关系，例如：**妙记和纪要产生条件相互独立**
+> 3. 了解不同会议产物的组成部分，以便根据需求决策使用哪种产物的数据
+> 4. 了解会议总结、分析和信息提取的标准流程
+
 ## 核心概念
 
 - **妙记（Minutes）**：来源于飞书视频会议的录制产物或用户上传的音视频文件，通过 `minute_token` 标识。
@@ -134,6 +140,8 @@ lark-cli minutes <resource> <method> [flags] # 调用 API
 
 - `get` — 获取妙记信息
 
+> **权限错误**：如果返回 `[2091005] permission deny`，表示用户没有对应妙记文件的阅读权限，需提示用户联系妙记 owner 申请权限。
+
 ## 权限表
 
 | 方法            | 所需 scope                       |

skills/lark-shared/SKILL.md

@@ -81,6 +81,29 @@ lark-cli auth login --scope "calendar:calendar:readonly" --no-wait --json
 lark-cli auth login --device-code <device_code>
 ```
 
+**Split-Flow 完整步骤**：
+
+**第一步：发起授权（当前轮）**
+
+1. 执行 `lark-cli auth login --scope "xxx" --no-wait --json`（必须加 `--no-wait --json`）
+2. 从 JSON 输出中提取 `verification_url` 和 `device_code`
+3. 生成二维码：`lark-cli auth qrcode <verification_url> --output "xxx"`
+4. 将 URL 和二维码展示给用户（先 URL，后二维码）
+5. **结束本轮对话前，必须明确告知用户**："请完成授权后，回来告诉我已授权完成，我会帮你完成后续步骤"
+
+**第二步：完成授权（后续轮）**
+
+1. 等待用户回复"已完成授权"
+2. **由你（AI agent）亲自执行**：`lark-cli auth login --device-code <device_code>`
+3. 此命令会轮询授权状态并完成登录
+4. 如果返回授权成功，流程结束
+
+**关键规则**：
+
+- **你必须亲自执行 `--device-code` 命令**，不要指示用户自行执行
+- **不要在同一轮中展示 URL 后立刻执行 `--device-code`**，这会导致用户看不到 URL
+- **禁止缓存 `verification_url` 或 `device_code`**：每次需要授权时，必须重新执行 `lark-cli auth login --no-wait --json` 生成新的链接。不要将授权链接和 device code 存入上下文供后续复用
+
 ## 更新检查
 
 lark-cli 命令执行后，如果检测到新版本，JSON 输出中会包含 `_notice.update` 字段（含 `message`、`command` 等）。

skills/lark-shared/references/lark-wiki-token-routing.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，先解析类型；不要凭标题、路径或上下文猜底层对象类型。

skills/lark-vc/SKILL.md

@@ -12,11 +12,17 @@ metadata:
 
 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**
 
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`references/vc-domain-boundaries.md`](references/vc-domain-boundaries.md)**，不读将导致命令使用、会议产物决策、领域边界职责判断错误：
+> 1. 了解日历 & VC、会议产物 & 文档的关联关系和职责划分
+> 2. 了解会议产物（妙记和纪要）之间的关联关系，例如：**妙记和纪要产生条件相互独立**
+> 3. 了解不同会议产物的组成部分，以便根据需求决策使用哪种产物的数据
+> 4. 了解会议总结、分析和信息提取的标准流程
+
 ## 核心概念
 
-- **视频会议（Meeting）**：飞书视频会议实例，通过 meeting\_id 标识。已结束的会议支持通过关键词、时间段、参会人、组织者、会议室等条件搜索（见 `+search`）。
-- **会议纪要（Note）**：视频会议结束后生成的结构化文档，包含纪要文档（包含总结、待办、章节）和逐字稿文档。
-- **妙记（Minutes）**：来源于飞书视频会议的录制产物或用户上传的音视频文件，支持视频/音频的转写和会议纪要，通过 minute\_token 标识。
+- **视频会议（Meeting）**：飞书视频会议实例，通过 meeting_id 标识。已结束的会议支持通过关键词、时间段、参会人、组织者、会议室等条件搜索（见 `+search`）。
+- **会议纪要（Note）**：视频会议结束后生成的结构化文档，包含纪要文档（包含总结、待办）和逐字稿文档。
+- **妙记（Minutes）**：来源于飞书视频会议的录制产物或用户上传的音视频文件，支持视频/音频的转写，包含总结、待办、章节和文字记录，通过 minute_token 标识。
 - **纪要文档（MainDoc）**：AI 智能纪要的主文档，包含 AI 生成的总结和待办，对应 `note_doc_token`。
 - **用户会议纪要（MeetingNotes）**：用户主动绑定到会议的纪要文档，对应 `meeting_notes`。仅通过 `--calendar-event-ids` 路径返回。
 - **逐字稿（VerbatimDoc）**：会议的逐句文字记录，包含说话人和时间戳。
@@ -29,8 +35,23 @@ metadata:
 3. 搜索结果存在多条数据时，务必注意分页数据获取，不要遗漏任何会议记录。
 
 ### 2. 整理会议纪要
-1. 整理纪要文档时默认给出纪要文档和逐字稿链接即可，无需读取纪要文档或逐字稿内容。
-2. 用户明确需要获取纪要文档中的总结、待办、章节产物时，再读取文档获取具体内容。
+
+> ⚠️ 在选择读取哪个产物前，请先确认你理解 AI 总结链路 vs 录制链路的区别。如不确定，先读 [`references/vc-domain-boundaries.md`](references/vc-domain-boundaries.md) 的「两条链路的独立性」章节。
+
+**⚠️ 产物选择决策 — 根据用户意图严格区分：**
+
+| 用户意图 | 必须读取的产物 | 禁止 |
+|---------|-------------|------|
+| **提炼/总结/重新总结/整理会议内容/回顾会议** | 逐字稿（`verbatim_doc_token`）或妙记文字记录（Transcript），基于原始对话独立分析 | 禁止直接搬运 AI 纪要（`note_doc_token`）的总结作为最终输出|
+| **查看待办/章节** | AI 纪要（`note_doc_token`）或妙记产物 — AI 待办更友好（含提出人和负责人），章节按话题划分更结构化 | — |
+| **查看纪要链接/文档地址** | 仅返回文档链接，无需读取内容 | — |
+| **直接看 AI 总结结果** | AI 纪要（`note_doc_token`） | — |
+| **谁说了什么/完整发言记录** | 逐字稿（`verbatim_doc_token`） | — |
+
+> **为什么"提炼/总结"必须从逐字稿出发？** AI 纪要是模型对会议的二次压缩，可能遗漏讨论细节、争论过程和隐含决策。用户要求"提炼"或"重新总结"时，期望的是基于原始对话的独立分析，而非对 AI 产物的重新排版。AI 纪要可作为补充参考，但不能作为唯一信息源。
+
+1. 整理纪要文档时默认给出纪要文档、逐字稿、妙记链接即可，无需读取纪要文档或逐字稿内容。
+2. 用户明确需要获取总结、待办、章节产物时，再读取文档获取具体内容。
 3. 读取智能纪要（`note_doc_token`）内容时，纪要文档的**第一个 `<whiteboard>`** 标签是封面图（AI 生成的总结可视化），应同时下载展示给用户：
 ```bash
 # 1. 读取纪要内容
@@ -43,7 +64,7 @@ lark-cli docs +media-download --type whiteboard --token <whiteboard_token> --out
 > **产物目录规范**：同一会议的所有下载产物（录像、逐字稿、封面图等）统一放到 `./minutes/{minute_token}/` 目录下。这与 `minutes +download` 和 `vc +notes --minute-tokens` 的默认落点保持一致，便于 Agent 聚合。显式路径（如封面图）需手动对齐到同一目录。
 
 > **纪要相关文档 — 根据用户意图选择：**
-> - `note_doc_token` → **AI 智能纪要**（AI 总结 + 待办 + 章节）
+> - `note_doc_token` → **AI 智能纪要**（AI 总结 + 待办）
 > - `meeting_notes` → **用户绑定的会议纪要**（用户主动关联到会议的文档，仅 `--calendar-event-ids` 路径返回）
 > - `verbatim_doc_token` → **逐字稿**（完整的逐句文字记录，含说话人和时间戳）— 用户说"逐字稿""完整记录""谁说了什么"时用这个
 > - 用户说"纪要""总结""纪要内容"时，应同时返回 `note_doc_token` 和 `meeting_notes`（如有）
@@ -119,7 +140,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli vc +<verb> [flags]`）。
 | Shortcut | 说明 |
 |----------|------|
 | [`+search`](references/lark-vc-search.md) | Search meeting records (requires at least one filter) |
-| [`+notes`](references/lark-vc-notes.md) | Query meeting notes (via meeting-ids, minute-tokens, or calendar-event-ids) |
+| [`+notes`](references/lark-vc-notes.md) | Query meeting notes and minutes (via meeting-ids, minute-tokens, or calendar-event-ids) |
 | [`+recording`](references/lark-vc-recording.md) | Query minute_token from meeting-ids or calendar-event-ids |
 
 - 使用 `+search` 命令时，必须阅读 [references/lark-vc-search.md](references/lark-vc-search.md)，了解搜索参数和返回值结构。
@@ -158,9 +179,9 @@ lark-cli vc meeting get --params '{"meeting_id": "<meeting_id>", "with_participa
 
 | 方法 | 所需 scope |
 |------|-----------|
-| `+notes --meeting-ids` | `vc:meeting.meetingevent:read`、`vc:note:read` |
+| `+notes --meeting-ids` | `vc:meeting.meetingevent:read`、`vc:note:read`、 `vc:record:readonly` |
 | `+notes --minute-tokens` | `vc:note:read`、`minutes:minutes:readonly`、`minutes:minutes.artifacts:read`、`minutes:minutes.transcript:export` |
-| `+notes --calendar-event-ids` | `calendar:calendar:read`、`calendar:calendar.event:read`、`vc:meeting.meetingevent:read`、`vc:note:read` |
+| `+notes --calendar-event-ids` | `calendar:calendar:read`、`calendar:calendar.event:read`、`vc:meeting.meetingevent:read`、`vc:note:read`、 `vc:record:readonly` |
 | `+recording --meeting-ids` | `vc:record:readonly` |
 | `+recording --calendar-event-ids` | `vc:record:readonly`、`calendar:calendar:read`、`calendar:calendar.event:read` |
 | `+search` | `vc:meeting.search:read` |

skills/lark-vc/references/lark-vc-notes.md

@@ -63,9 +63,9 @@ lark-cli vc +notes --meeting-ids 69xxxxxxxxxxxxx28 --dry-run
 
 | 输入 | 所需权限 |
 |------|---------|
-| `--meeting-ids` | `vc:meeting.meetingevent:read`、`vc:note:read` |
+| `--meeting-ids` | `vc:meeting.meetingevent:read`、`vc:note:read`、`vc:record:readonly` |
 | `--minute-tokens` | `vc:note:read`、`minutes:minutes:readonly`、`minutes:minutes.artifacts:read`、`minutes:minutes.transcript:export` |
-| `--calendar-event-ids` | `calendar:calendar:read`、`calendar:calendar.event:read`、`vc:meeting.meetingevent:read`、`vc:note:read` |
+| `--calendar-event-ids` | `calendar:calendar:read`、`calendar:calendar.event:read`、`vc:meeting.meetingevent:read`、`vc:note:read`、`vc:record:readonly` |
 
 ## 输出结果
 
@@ -75,6 +75,8 @@ lark-cli vc +notes --meeting-ids 69xxxxxxxxxxxxx28 --dry-run
 
 | 字段 | 说明 |
 |------|------|
+| `meeting_id` | 会议 ID（`--meeting-ids` / `--calendar-event-ids` 路径） |
+| `minute_token` | **会议对应的妙记 Token**（`--meeting-ids` / `--calendar-event-ids` 路径自动通过录制 API 反查并附加）|
 | `note_doc_token` | **AI 智能纪要**文档 Token — AI 生成的总结、待办、章节 |
 | `meeting_notes` | **用户绑定的会议纪要**文档 Token 列表 — 用户主动关联到会议的文档（仅 `--calendar-event-ids` 路径返回） |
 | `verbatim_doc_token` | **逐字稿**文档 Token — 完整的逐句文字记录，含说话人和时间戳 |
@@ -83,6 +85,8 @@ lark-cli vc +notes --meeting-ids 69xxxxxxxxxxxxx28 --dry-run
 | `create_time` | 创建时间（格式化） |
 
 > **选择哪个 token？** 用户说"会议纪要""总结""待办""纪要内容" → 返回 `note_doc_token` 和 `meeting_notes`（如有）。用户说"逐字稿""完整记录""谁说了什么" → 用 `verbatim_doc_token`。意图不明确时，展示所有文档链接让用户选择。
+>
+> 📌 不确定该返回哪个 token？参见 [`vc-domain-boundaries.md`](vc-domain-boundaries.md) 的产物链路对比表，了解 AI 总结链路 vs 录制链路的区别。
 
 ### minute-tokens 路径的 AI 产物
 

skills/lark-vc/references/vc-domain-boundaries.md

@@ -0,0 +1,154 @@
+# Calendar/VC/Doc 跨领域关联关系、领域知识和职责边界说明
+
+本文档说明飞书日历（Calendar）、视频会议（VC）、云文档（Doc）三个域之间的关联关系，帮助理解跨域数据流转和产物依赖。
+
+## Calendar 域
+
+- **lark-calendar skill** 负责日历与日程管理，包括创建、查询、修改、删除日程等操作。
+- **日程与会议的关系**：日程可以用于提前预约会议，确定会议时间、参与人、会议室、会议主题等信息。日程上可以关联飞书/Lark 视频会议。
+- **并非所有会议都通过日程发起**：即时会议不经过日程预约，直接创建。因此，仅查询日程数据无法覆盖所有会议，搜索历史会议应优先使用 `vc +search`。
+- **日程上的用户会议纪要**：用户可以在日程上绑定自己的会议纪要文档（MeetingNotes），用于手动记录会议相关信息。该文档与 AI 生成的智能纪要（`note_doc_token`）是不同的文档，相互独立。
+
+> **路由规则**：查询过去已结束的会议 → `lark-vc`；查询未来日程/待开的会 → `lark-calendar`；查询"今天有哪些会议" → 两者结合（`vc +search` 查已结束 + `calendar` 查未开始）。
+
+## VC 域
+
+- **lark-vc skill** 负责视频会议管理，包括搜索历史会议、查询会议产物（智能纪要、逐字稿、妙记等）、查询参会人快照等操作。
+- **会议类型**：会议可以是日程会议（由日程发起，有对应的 `calendar_event_id`），也可以是即时会议等其他类型。
+
+### 会议产物
+
+会议产物取决于会中开启的功能，分为两条独立链路：
+
+#### 链路一：开启「AI 总结」
+
+会中开启「AI 总结」功能后，产生以下产物：
+
+| 产物 | Token 字段 | 本质 | 说明 |
+|------|-----------|------|------|
+| 智能纪要 | `note_doc_token` | 飞书文档 | AI 生成的会议总结与待办 |
+| 逐字稿 | `verbatim_doc_token` | 飞书文档 | 完整的逐句发言记录（含说话人、时间戳） |
+| 共享文档 | `shared_doc_token` | 飞书文档 | 会中投屏共享的文档信息 |
+
+此外，还存在**用户会议纪要（MeetingNotes）**，对应 `meeting_notes` 字段。这是用户主动绑定到会议的纪要文档，通常用于会前记录会议相关内容，与智能纪要文档相互独立。仅通过 `+notes --calendar-event-ids` 路径返回。
+
+#### 链路二：开启「录制」
+
+会中开启「录制」功能后，产生**妙记产物**（`minute_token`）。注意：妙记不一定是会中产生的，用户上传音视频文件或录音也会产生妙记。妙记本身包含以下子产物：
+
+| 子产物 | 说明 |
+|--------|------|
+| Summary（总结） | 对整场会议的智能总结 |
+| Todo（待办） | 会议中识别出的待处理任务列表 |
+| Chapter（章节） | 按讨论话题划分的核心内容摘要 |
+| Transcript（文字记录） | 整场会议最原始的逐人发言记录 |
+
+#### 两条链路的独立性
+
+- 智能纪要（AI 总结链路）和妙记（录制链路）**相互独立、互不影响**。
+- 一场会议可能同时拥有两类产物，也可能只有其中一类，也可能都没有。
+- 当两者都存在时，Summary/Todo 内容可能重叠，应根据用户意图选择优先读取哪个。
+
+> **产物选择决策**：
+> - **AI 产物 vs 原始记录**：智能总结、待办、章节都属于 AI 分析产物，可能只包含最终结论和关键信息。
+>   - **用户要求"提炼/总结/重新总结/整理/回顾"会议内容时** → **内容总结必须从逐字稿/文字记录出发，基于原始对话独立分析**。禁止直接搬运 AI 纪要的总结作为最终输出——那只是对 AI 产物的重新排版，不是独立提炼。AI 纪要可作为补充参考，但不能作为内容总结的唯一信息源。
+>   - **用户要求查看待办或章节时** → **应参考 AI 产物的待办和章节**，因为 AI 产物的待办更友好（包含提出人和负责人），章节按话题划分更结构化。
+>   - **用户只想直接看 AI 总结结果** → 使用 AI 产物的总结。
+> - **链路优先级**：如果用户没有明确偏好，对于重复的内容（如智能总结、待办），**优先查询智能纪要（Note），不存在时再降级到妙记（Minutes）**。
+
+#### 逐字稿与文字记录的格式
+
+智能纪要的逐字稿（`verbatim_doc_token`）和妙记的文字记录（Transcript）都记录了用户原始对话内容，格式一致：
+
+```
+发言人名称 相对时间戳
+<发言内容>
+```
+
+示例：
+
+```
+张三 00:00:00.195
+我们接下来讨论一下项目进度。
+```
+
+- 第一行为发言人信息，包含用户名称和发言的相对时间（从会议开始计算的偏移量）。
+- 后续行为该发言人的发言内容，直到下一个发言人标记出现。
+
+### 会议总结和分析流程
+
+#### Step 1: 定位会议
+
+根据关键字、组织者、参与人、会议室等条件搜索会议，获取会议列表。
+
+```bash
+lark-cli vc +search --start "<YYYY-MM-DD>" --end "<YYYY-MM-DD>" --format json
+```
+
+详细用法请阅读 [`lark-vc-search.md`](lark-vc-search.md)。
+
+#### Step 2: 根据 meeting_id 查询产物
+
+##### 获取会议产物
+
+```bash
+lark-cli vc +notes --meeting-ids '<meeting_id1>,<meeting_id2>'
+```
+
+可获取会议的所有产物信息，包括：
+- 智能纪要（`note_doc_token`）— AI 生成的总结和待办信息
+- 逐字稿（`verbatim_doc_token`）— 完整的会中发言记录
+- 共享文档（`shared_doc_token`）— 会中投屏共享的文档
+- 妙记 Token（`minute_token`）— 如存在录制产物则返回
+
+详细用法请阅读 [`lark-vc-notes.md`](lark-vc-notes.md)。
+
+如果返回了 `minute_token`，可通过以下命令获取妙记的详细信息（总结、待办、章节、文字记录）：
+
+```bash
+lark-cli vc +notes --minute-tokens '<minute_token1>,<minute_token2>'
+```
+
+可获取妙记的总结、待办、章节、文字记录等信息。详细用法请阅读 [`lark-vc-notes.md`](lark-vc-notes.md)。
+
+#### Step 3: Doc 域拉取文档内容
+
+智能纪要和逐字稿都是飞书文档，需使用 `docs +fetch` 读取正文内容：
+
+```bash
+lark-cli docs +fetch --api-version v2 --doc <doc_token> --doc-format markdown
+```
+
+详细用法请参考 [lark-doc](../../lark-doc/SKILL.md) skill。
+
+#### Step 4: 判断用户需要的产物内容
+
+- 根据用户诉求（总结/待办/章节/完整发言记录等），选择合适的产物进行分析和信息提取
+- 如果两种产物都不存在或没有权限，需如实告知用户
+
+## Doc 域
+
+- **lark-doc skill** 负责飞书云文档管理，包括获取文档元信息、读取文档内容、创建和编辑文档等操作。
+- **会议产物的文档本质**：智能纪要（`note_doc_token`）、逐字稿（`verbatim_doc_token`）都是飞书文档，需要通过 `lark-doc` 的 API（如 `docs +fetch`）查询其内容和元信息。
+- **文档元信息查询**：获取文档名称、URL 等基本信息时，使用 `drive metas batch_query`；获取文档正文内容时，使用 `docs +fetch --api-version v2`。
+
+## 三域关联总览
+
+```
+Calendar (日程) ──── 发起预约 ────► VC (会议)
+                                       │
+                    ┌──────────────────┤
+                    │                  │
+              AI 总结链路           录制链路
+                    │                  │
+                    ▼                  ▼
+            智能纪要 (Doc)        妙记 (Minutes)
+            逐字稿 (Doc)         ├── Summary
+            共享文档 (Doc)        ├── Todo
+            用户纪要 (Doc)        ├── Chapter
+                                └── Transcript
+```
+
+- Calendar 提供会议预约入口，但并非所有会议都来自日程。
+- VC 是会议数据的中心，管理会议记录和产物关联。
+- Doc 是会议产物的载体，智能纪要和逐字稿都以飞书文档形式沉淀，需通过 Doc 域 API 读取。

skills/lark-workflow-meeting-summary/SKILL.md

@@ -11,6 +11,12 @@ metadata:
 
 **CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)，其中包含认证、权限处理**。然后阅读 [`../lark-vc/SKILL.md`](../lark-vc/SKILL.md)，了解会议纪要相关操作。
 
+**CRITICAL — 开始前 MUST 先用 Read 工具读取 [`../lark-vc/references/vc-domain-boundaries.md`](../lark-vc/references/vc-domain-boundaries.md)**，不读将导致命令使用、会议产物决策、领域边界职责判断错误：
+> 1. 了解日历 & VC、会议产物 & 文档的关联关系和职责划分
+> 2. 了解会议产物（妙记和纪要）之间的关联关系，例如：**妙记和纪要产生条件相互独立**
+> 3. 了解不同会议产物的组成部分，以便根据需求决策使用哪种产物的数据
+> 4. 了解会议总结、分析和信息提取的标准流程
+
 ## 适用场景
 
 - "帮我整理这周的会议纪要" / "总结最近的会议" / "生成会议周报"