diff --git a/shortcuts/calendar/calendar_create.go b/shortcuts/calendar/calendar_create.go index 7178027dc..effb5f677 100644 --- a/shortcuts/calendar/calendar_create.go +++ b/shortcuts/calendar/calendar_create.go @@ -306,6 +306,9 @@ var CalendarCreate = common.Shortcut{ "start": startStr, "end": endStr, } + if recurrence, _ := event["recurrence"].(string); recurrence != "" { + resultData["recurrence"] = recurrence + } runtime.OutFormat(resultData, nil, func(w io.Writer) { var rows []map[string]interface{} diff --git a/shortcuts/calendar/calendar_get.go b/shortcuts/calendar/calendar_get.go new file mode 100644 index 000000000..a49fb1fbb --- /dev/null +++ b/shortcuts/calendar/calendar_get.go @@ -0,0 +1,279 @@ +// Copyright (c) 2026 Lark Technologies Pte. Ltd. +// SPDX-License-Identifier: MIT +// +// calendar +get — get a single calendar event detail by calendar_id and event_id + +package calendar + +import ( + "context" + "encoding/json" + "fmt" + "io" + "strconv" + "strings" + "time" + + "github.com/larksuite/cli/errs" + "github.com/larksuite/cli/internal/output" + "github.com/larksuite/cli/internal/validate" + "github.com/larksuite/cli/shortcuts/common" +) + +// calendarEventTime mirrors start_time / end_time in the API response. +type calendarEventTime struct { + Date string `json:"date,omitempty"` + Timestamp string `json:"timestamp,omitempty"` + Timezone string `json:"timezone,omitempty"` +} + +// calendarEventVChat mirrors the vchat block in the API response. +type calendarEventVChat struct { + VCType string `json:"vc_type,omitempty"` + IconType string `json:"icon_type,omitempty"` + Description string `json:"description,omitempty"` + MeetingURL string `json:"meeting_url,omitempty"` +} + +// calendarEventLocation mirrors the location block in the API response. +type calendarEventLocation struct { + Name string `json:"name,omitempty"` + Address string `json:"address,omitempty"` + Latitude float64 `json:"latitude,omitempty"` + Longitude float64 `json:"longitude,omitempty"` +} + +// calendarEventReminder mirrors a reminder entry. +type calendarEventReminder struct { + Minutes int `json:"minutes"` +} + +// calendarEventOrganizer mirrors event_organizer. +type calendarEventOrganizer struct { + UserID string `json:"user_id,omitempty"` + DisplayName string `json:"display_name,omitempty"` +} + +// calendarEventAttachment mirrors a single attachment entry. +type calendarEventAttachment struct { + FileToken string `json:"file_token,omitempty"` + FileSize string `json:"file_size,omitempty"` + Name string `json:"name,omitempty"` +} + +// calendarEventCheckInTime mirrors check_in_start_time / check_in_end_time. +type calendarEventCheckInTime struct { + TimeType string `json:"time_type,omitempty"` + Duration int `json:"duration"` +} + +// calendarEventCheckIn mirrors event_check_in. +type calendarEventCheckIn struct { + EnableCheckIn bool `json:"enable_check_in"` + CheckInStartTime *calendarEventCheckInTime `json:"check_in_start_time,omitempty"` + CheckInEndTime *calendarEventCheckInTime `json:"check_in_end_time,omitempty"` + NeedNotifyAttendees bool `json:"need_notify_attendees"` +} + +// calendarEvent mirrors the event object inside the API response. +type calendarEvent struct { + EventID string `json:"event_id,omitempty"` + OrganizerCalendarID string `json:"organizer_calendar_id,omitempty"` + Summary string `json:"summary,omitempty"` + Description string `json:"description,omitempty"` + StartTime *calendarEventTime `json:"start_time,omitempty"` + EndTime *calendarEventTime `json:"end_time,omitempty"` + VChat *calendarEventVChat `json:"vchat,omitempty"` + Visibility string `json:"visibility,omitempty"` + AttendeeAbility string `json:"attendee_ability,omitempty"` + FreeBusyStatus string `json:"free_busy_status,omitempty"` + SelfRsvpStatus string `json:"self_rsvp_status,omitempty"` + Location *calendarEventLocation `json:"location,omitempty"` + Color int `json:"color,omitempty"` + Reminders []calendarEventReminder `json:"reminders,omitempty"` + Recurrence string `json:"recurrence,omitempty"` + Status string `json:"status,omitempty"` + IsException bool `json:"is_exception,omitempty"` + RecurringEventID string `json:"recurring_event_id,omitempty"` + CreateTime string `json:"create_time,omitempty"` + EventOrganizer *calendarEventOrganizer `json:"event_organizer,omitempty"` + AppLink string `json:"app_link,omitempty"` + Attachments []calendarEventAttachment `json:"attachments,omitempty"` + EventCheckIn *calendarEventCheckIn `json:"event_check_in,omitempty"` +} + +// parseCalendarEvent decodes the API response data into a typed calendarEvent. +func parseCalendarEvent(data map[string]any) (*calendarEvent, error) { + rawEvent, ok := data["event"] + if !ok || rawEvent == nil { + return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "calendar event response missing 'event' field") + } + raw, err := json.Marshal(rawEvent) + if err != nil { + return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "calendar event response: marshal failed: %s", err).WithCause(err) + } + var event calendarEvent + if err := json.Unmarshal(raw, &event); err != nil { + return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "calendar event response: unmarshal failed: %s", err).WithCause(err) + } + return &event, nil +} + +// buildCalendarEventOutput converts the typed event into the output map and +// applies the four transformation rules: +// 1. create_time -> RFC3339 +// 2. start_time / end_time timestamp -> datetime (RFC3339), drop timestamp +// 3. flatten event into the top-level result +// 4. when status != "cancelled", drop status (and adjust all-day end date) +func buildCalendarEventOutput(event *calendarEvent) (map[string]interface{}, error) { + raw, err := json.Marshal(event) + if err != nil { + return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "calendar event marshal failed: %s", err).WithCause(err) + } + var out map[string]interface{} + if err := json.Unmarshal(raw, &out); err != nil { + return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "calendar event unmarshal failed: %s", err).WithCause(err) + } + + if ctStr, ok := out["create_time"].(string); ok && ctStr != "" { + if ts, err := strconv.ParseInt(ctStr, 10, 64); err == nil { + out["create_time"] = time.Unix(ts, 0).Local().Format(time.RFC3339) + } + } + + if startMap, ok := out["start_time"].(map[string]interface{}); ok { + if tsStr, ok := startMap["timestamp"].(string); ok && tsStr != "" { + if ts, err := strconv.ParseInt(tsStr, 10, 64); err == nil { + startMap["datetime"] = time.Unix(ts, 0).Local().Format(time.RFC3339) + delete(startMap, "timestamp") + } + } + } + if endMap, ok := out["end_time"].(map[string]interface{}); ok { + if tsStr, ok := endMap["timestamp"].(string); ok && tsStr != "" { + if ts, err := strconv.ParseInt(tsStr, 10, 64); err == nil { + endMap["datetime"] = time.Unix(ts, 0).Local().Format(time.RFC3339) + delete(endMap, "timestamp") + } + } + // All-day event: end date is exclusive in the API; rewind by 1s and reformat. + if dt, _ := endMap["datetime"].(string); dt == "" { + if dateStr, ok := endMap["date"].(string); ok && dateStr != "" { + if t, err := time.ParseInLocation("2006-01-02", dateStr, time.UTC); err == nil { + endMap["date"] = t.Add(-1 * time.Second).Format("2006-01-02") + } + } + } + } + + if status, _ := out["status"].(string); status != "cancelled" { + delete(out, "status") + } + + return out, nil +} + +// CalendarGet gets a single calendar event detail. +var CalendarGet = common.Shortcut{ + Service: "calendar", + Command: "+get", + Description: "Get a single calendar event detail by calendar-id and event-id", + Risk: "read", + Scopes: []string{"calendar:calendar.event:read"}, + AuthTypes: []string{"user", "bot"}, + HasFormat: true, + Flags: []common.Flag{ + {Name: "calendar-id", Desc: "calendar ID (default: primary)"}, + {Name: "event-id", Desc: "event ID", Required: true}, + }, + Validate: func(ctx context.Context, runtime *common.RuntimeContext) error { + if err := rejectCalendarAutoBotFallback(runtime); err != nil { + return err + } + for _, flag := range []string{"calendar-id", "event-id"} { + if val := strings.TrimSpace(runtime.Str(flag)); val != "" { + if err := common.RejectDangerousCharsTyped("--"+flag, val); err != nil { + return err + } + } + } + eventId := strings.TrimSpace(runtime.Str("event-id")) + if eventId == "" { + return errs.NewValidationError(errs.SubtypeInvalidArgument, "event-id cannot be empty").WithParam("--event-id") + } + return nil + }, + DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI { + calendarId := strings.TrimSpace(runtime.Str("calendar-id")) + d := common.NewDryRunAPI() + switch calendarId { + case "": + d.Desc("(calendar-id omitted) Will use primary calendar") + calendarId = "" + case "primary": + calendarId = "" + } + eventId := strings.TrimSpace(runtime.Str("event-id")) + return d. + GET("/open-apis/calendar/v4/calendars/:calendar_id/events/:event_id"). + Set("calendar_id", calendarId). + Set("event_id", eventId) + }, + Execute: func(ctx context.Context, runtime *common.RuntimeContext) error { + calendarId := strings.TrimSpace(runtime.Str("calendar-id")) + if calendarId == "" { + calendarId = PrimaryCalendarIDStr + } + eventId := strings.TrimSpace(runtime.Str("event-id")) + + data, err := runtime.CallAPITyped("GET", + fmt.Sprintf("/open-apis/calendar/v4/calendars/%s/events/%s", + validate.EncodePathSegment(calendarId), + validate.EncodePathSegment(eventId)), + nil, nil) + if err != nil { + return err + } + + event, err := parseCalendarEvent(data) + if err != nil { + return err + } + + out, err := buildCalendarEventOutput(event) + if err != nil { + return err + } + + runtime.OutFormat(out, nil, func(w io.Writer) { + summary, _ := out["summary"].(string) + if summary == "" { + summary = "(untitled)" + } + startMap, _ := out["start_time"].(map[string]interface{}) + endMap, _ := out["end_time"].(map[string]interface{}) + startStr, _ := startMap["datetime"].(string) + if startStr == "" { + startStr, _ = startMap["date"].(string) + } + endStr, _ := endMap["datetime"].(string) + if endStr == "" { + endStr, _ = endMap["date"].(string) + } + eventIdOut, _ := out["event_id"].(string) + freeBusyStatus, _ := out["free_busy_status"].(string) + selfRsvpStatus, _ := out["self_rsvp_status"].(string) + row := map[string]interface{}{ + "event_id": eventIdOut, + "summary": summary, + "start": startStr, + "end": endStr, + "free_busy_status": freeBusyStatus, + "self_rsvp_status": selfRsvpStatus, + } + output.PrintTable(w, []map[string]interface{}{row}) + fmt.Fprintln(w) + }) + return nil + }, +} diff --git a/shortcuts/calendar/calendar_test.go b/shortcuts/calendar/calendar_test.go index 56014b7c2..5453ee682 100644 --- a/shortcuts/calendar/calendar_test.go +++ b/shortcuts/calendar/calendar_test.go @@ -2304,17 +2304,17 @@ func TestResolveStartEnd_ExplicitValues(t *testing.T) { // Shortcuts() registration test // --------------------------------------------------------------------------- -func TestShortcuts_Returns9(t *testing.T) { +func TestShortcuts_Returns10(t *testing.T) { shortcuts := Shortcuts() - if len(shortcuts) != 9 { - t.Fatalf("expected 9 shortcuts, got %d", len(shortcuts)) + if len(shortcuts) != 10 { + t.Fatalf("expected 10 shortcuts, got %d", len(shortcuts)) } names := map[string]bool{} for _, s := range shortcuts { names[s.Command] = true } - for _, want := range []string{"+agenda", "+create", "+update", "+freebusy", "+room-find", "+rsvp", "+suggestion"} { + for _, want := range []string{"+agenda", "+create", "+update", "+freebusy", "+room-find", "+rsvp", "+suggestion", "+get"} { if !names[want] { t.Errorf("missing shortcut %s", want) } @@ -3178,3 +3178,193 @@ func TestSuggestion_RejectsDangerousTimezone_Typed(t *testing.T) { t.Errorf("param=%q, want --timezone", ve.Param) } } + +// --------------------------------------------------------------------------- +// CalendarGet tests +// --------------------------------------------------------------------------- + +func TestGet_Success_FlattensAndConvertsTimes(t *testing.T) { + f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig()) + + reg.Register(&httpmock.Stub{ + Method: "GET", + URL: "/open-apis/calendar/v4/calendars/cal_test123/events/evt_001", + Body: map[string]interface{}{ + "code": 0, "msg": "success", + "data": map[string]interface{}{ + "event": map[string]interface{}{ + "event_id": "evt_001", + "summary": "Daily Sync", + "create_time": "1602504000", + "start_time": map[string]interface{}{ + "timestamp": "1742515200", + "timezone": "Asia/Shanghai", + }, + "end_time": map[string]interface{}{ + "timestamp": "1742518800", + "timezone": "Asia/Shanghai", + }, + "status": "confirmed", + }, + }, + }, + }) + + err := mountAndRun(t, CalendarGet, []string{ + "+get", + "--calendar-id", "cal_test123", + "--event-id", "evt_001", + "--as", "bot", + }, f, stdout) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + + out := stdout.String() + // Expect flattened — fields appear directly under "data", not under "data.event" + if strings.Contains(out, "\"event\": {") { + t.Errorf("payload should be flattened (no event wrapper), got: %s", out) + } + if !strings.Contains(out, "\"event_id\": \"evt_001\"") { + t.Errorf("expected event_id in output, got: %s", out) + } + // status=confirmed should be dropped + if strings.Contains(out, "\"status\": \"confirmed\"") { + t.Errorf("status should be dropped when not cancelled, got: %s", out) + } + // timestamp must be replaced with datetime + if strings.Contains(out, "\"timestamp\":") { + t.Errorf("timestamp should be replaced with datetime, got: %s", out) + } + if !strings.Contains(out, "\"datetime\":") { + t.Errorf("expected datetime in output, got: %s", out) + } + // create_time must be RFC3339 (contain 'T' and timezone) + if !strings.Contains(out, "\"create_time\": \"2020-10-12T") { + t.Errorf("expected RFC3339 create_time, got: %s", out) + } +} + +func TestGet_CancelledStatus_PreservesStatus(t *testing.T) { + f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig()) + + reg.Register(&httpmock.Stub{ + Method: "GET", + URL: "/open-apis/calendar/v4/calendars/cal_test123/events/evt_002", + Body: map[string]interface{}{ + "code": 0, "msg": "success", + "data": map[string]interface{}{ + "event": map[string]interface{}{ + "event_id": "evt_002", + "summary": "Cancelled Meeting", + "create_time": "1602504000", + "start_time": map[string]interface{}{"timestamp": "1742515200"}, + "end_time": map[string]interface{}{"timestamp": "1742518800"}, + "status": "cancelled", + }, + }, + }, + }) + + err := mountAndRun(t, CalendarGet, []string{ + "+get", + "--calendar-id", "cal_test123", + "--event-id", "evt_002", + "--as", "bot", + }, f, stdout) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + + out := stdout.String() + if !strings.Contains(out, "\"status\": \"cancelled\"") { + t.Errorf("status should be preserved when cancelled, got: %s", out) + } +} + +func TestGet_AllDayEvent_AdjustsEndDate(t *testing.T) { + f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig()) + + // All-day event: start 2025-03-21, end 2025-03-22 (exclusive in API). + reg.Register(&httpmock.Stub{ + Method: "GET", + URL: "/open-apis/calendar/v4/calendars/cal_test123/events/evt_003", + Body: map[string]interface{}{ + "code": 0, "msg": "success", + "data": map[string]interface{}{ + "event": map[string]interface{}{ + "event_id": "evt_003", + "summary": "All-day", + "start_time": map[string]interface{}{"date": "2025-03-21"}, + "end_time": map[string]interface{}{"date": "2025-03-22"}, + "status": "confirmed", + }, + }, + }, + }) + + err := mountAndRun(t, CalendarGet, []string{ + "+get", + "--calendar-id", "cal_test123", + "--event-id", "evt_003", + "--as", "bot", + }, f, stdout) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + + out := stdout.String() + // end date 2025-03-22 should rewind by 1s -> 2025-03-21 + if !strings.Contains(out, "\"date\": \"2025-03-21\"") { + t.Errorf("expected end date adjusted to 2025-03-21, got: %s", out) + } +} + +func TestGet_EmptyEventID_Typed(t *testing.T) { + f, _, _, _ := cmdutil.TestFactory(t, defaultConfig()) + err := mountAndRun(t, CalendarGet, []string{ + "+get", + "--event-id", " ", + "--as", "bot", + }, f, nil) + if err == nil { + t.Fatal("want error for empty event-id") + } + var ve *errs.ValidationError + if !errors.As(err, &ve) { + t.Fatalf("want *errs.ValidationError, got %T", err) + } + if ve.Param != "--event-id" { + t.Errorf("param=%q, want --event-id", ve.Param) + } +} + +func TestGet_MissingEventField_TypedInternal(t *testing.T) { + f, _, _, reg := cmdutil.TestFactory(t, defaultConfig()) + + reg.Register(&httpmock.Stub{ + Method: "GET", + URL: "/open-apis/calendar/v4/calendars/cal_test123/events/evt_404", + Body: map[string]interface{}{ + "code": 0, "msg": "success", + "data": map[string]interface{}{}, + }, + }) + + err := mountAndRun(t, CalendarGet, []string{ + "+get", + "--calendar-id", "cal_test123", + "--event-id", "evt_404", + "--as", "bot", + }, f, nil) + if err == nil { + t.Fatal("want error when event field is missing") + } + var ie *errs.InternalError + if !errors.As(err, &ie) { + t.Fatalf("want *errs.InternalError, got %T", err) + } + if ie.Subtype != errs.SubtypeInvalidResponse { + t.Errorf("subtype=%q, want invalid_response", ie.Subtype) + } +} diff --git a/shortcuts/calendar/shortcuts.go b/shortcuts/calendar/shortcuts.go index b927bf78e..92b63f7f3 100644 --- a/shortcuts/calendar/shortcuts.go +++ b/shortcuts/calendar/shortcuts.go @@ -17,5 +17,6 @@ func Shortcuts() []common.Shortcut { CalendarSuggestion, CalendarMeeting, CalendarSearchEvent, + CalendarGet, } } diff --git a/shortcuts/minutes/minutes_detail.go b/shortcuts/minutes/minutes_detail.go index 8a7f4f1aa..17afade0c 100644 --- a/shortcuts/minutes/minutes_detail.go +++ b/shortcuts/minutes/minutes_detail.go @@ -28,7 +28,12 @@ import ( const minutesDetailLogPrefix = "[minutes +detail]" // Error codes from the minutes API. -const minutesDetailNoReadPermissionCode = 2091005 +const ( + minutesDetailProcessingCode = 2091003 + minutesDetailNoReadPermissionCode = 2091005 + minutesDetailWaitTimeoutDefault = 300 + minutesDetailWaitIntervalDefault = 15 +) var validMinuteTokenDetail = regexp.MustCompile(`^[a-z0-9]+$`) @@ -40,19 +45,31 @@ var scopesDetailMinuteTokens = []string{ // minuteDetailItem represents a single minute detail result. type minuteDetailItem struct { MinuteToken string `json:"minute_token"` + Status string `json:"status,omitempty"` Title string `json:"title"` NoteID string `json:"note_id"` Artifacts map[string]any `json:"artifacts,omitempty"` + Retryable bool `json:"retryable,omitempty"` Error string `json:"error,omitempty"` + Hint string `json:"hint,omitempty"` + NextCommand string `json:"next_command,omitempty"` } // fetchMinuteDetail queries a single minute's metadata and selected artifacts. func fetchMinuteDetail(ctx context.Context, runtime *common.RuntimeContext, minuteToken string) *minuteDetailItem { - data, err := runtime.CallAPITyped(http.MethodGet, - fmt.Sprintf("/open-apis/minutes/v1/minutes/%s", validate.EncodePathSegment(minuteToken)), nil, nil) + artifactFlags := requestedMinutesDetailArtifactFlags(runtime) + waitReady := runtime.Bool("wait-ready") + waitTimeout, waitInterval := minutesDetailWaitConfig(runtime) + + data, err := callMinutesDetailAPIUntilReady(ctx, runtime, waitReady, waitTimeout, waitInterval, func() (map[string]interface{}, error) { + return runtime.CallAPITyped(http.MethodGet, + fmt.Sprintf("/open-apis/minutes/v1/minutes/%s", validate.EncodePathSegment(minuteToken)), nil, nil) + }) if err != nil { result := &minuteDetailItem{MinuteToken: minuteToken} - if p, ok := errs.ProblemOf(err); ok && p.Code == minutesDetailNoReadPermissionCode { + if isMinutesDetailProcessingError(err) { + markMinutesDetailProcessing(result, minuteToken, artifactFlags, "minute metadata is still being generated") + } else if p, ok := errs.ProblemOf(err); ok && p.Code == minutesDetailNoReadPermissionCode { result.Error = fmt.Sprintf("No read permission for minute %s. Ask the minute owner for minute file read permission", minuteToken) } else { result.Error = fmt.Sprintf("failed to query minute: %v", err) @@ -81,10 +98,16 @@ func fetchMinuteDetail(ctx context.Context, runtime *common.RuntimeContext, minu needKeyword := runtime.Bool("keyword") if needSummary || needTodo || needChapter || needTranscript || needKeyword { - artData, err := runtime.CallAPITyped(http.MethodGet, - fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/artifacts", validate.EncodePathSegment(minuteToken)), nil, nil) + artData, err := callMinutesDetailAPIUntilReady(ctx, runtime, waitReady, waitTimeout, waitInterval, func() (map[string]interface{}, error) { + return runtime.CallAPITyped(http.MethodGet, + fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/artifacts", validate.EncodePathSegment(minuteToken)), nil, nil) + }) if err != nil { - fmt.Fprintf(runtime.IO().ErrOut, "%s failed to fetch artifacts for %s: %v\n", minutesDetailLogPrefix, minuteToken, err) + if isMinutesDetailProcessingError(err) { + markMinutesDetailProcessing(result, minuteToken, artifactFlags, "minute artifacts are still being generated") + } else { + result.Error = fmt.Sprintf("failed to query minute artifacts: %v", err) + } } else { artifacts := make(map[string]any) if needSummary { @@ -133,6 +156,78 @@ func fetchMinuteDetail(ctx context.Context, runtime *common.RuntimeContext, minu return result } +func isMinutesDetailProcessingError(err error) bool { + if p, ok := errs.ProblemOf(err); ok && p.Code == minutesDetailProcessingCode { + return true + } + return false +} + +func minutesDetailWaitConfig(runtime *common.RuntimeContext) (time.Duration, time.Duration) { + timeoutSeconds, intervalSeconds := normalizeMinutesDetailWaitSeconds(runtime.Int("wait-timeout-seconds"), runtime.Int("wait-interval-seconds")) + return time.Duration(timeoutSeconds) * time.Second, time.Duration(intervalSeconds) * time.Second +} + +func normalizeMinutesDetailWaitSeconds(timeoutSeconds, intervalSeconds int) (int, int) { + if timeoutSeconds <= 0 { + timeoutSeconds = minutesDetailWaitTimeoutDefault + } + if intervalSeconds <= 0 { + intervalSeconds = minutesDetailWaitIntervalDefault + } + return timeoutSeconds, intervalSeconds +} + +func callMinutesDetailAPIUntilReady(ctx context.Context, runtime *common.RuntimeContext, waitReady bool, timeout, interval time.Duration, call func() (map[string]interface{}, error)) (map[string]interface{}, error) { + deadline := time.Now().Add(timeout) + for { + data, err := call() + if err == nil || !waitReady || !isMinutesDetailProcessingError(err) { + return data, err + } + if ctxErr := ctx.Err(); ctxErr != nil { + return nil, ctxErr + } + remaining := time.Until(deadline) + if remaining <= 0 || interval > remaining { + return nil, err + } + fmt.Fprintf(runtime.IO().ErrOut, "%s minute is still processing; retrying in %s\n", minutesDetailLogPrefix, interval) + timer := time.NewTimer(interval) + select { + case <-ctx.Done(): + timer.Stop() + return nil, ctx.Err() + case <-timer.C: + } + } +} + +func requestedMinutesDetailArtifactFlags(runtime *common.RuntimeContext) []string { + var flags []string + for _, flag := range []string{"summary", "todo", "chapter", "keyword", "transcript"} { + if runtime.Bool(flag) { + flags = append(flags, "--"+flag) + } + } + return flags +} + +func markMinutesDetailProcessing(result *minuteDetailItem, minuteToken string, artifactFlags []string, reason string) { + result.Status = "processing" + result.Retryable = true + result.Error = reason + result.Hint = "The minute is still being generated. Retry later, or rerun the next_command to wait until it is ready." + result.NextCommand = minutesDetailNextCommand(minuteToken, artifactFlags) +} + +func minutesDetailNextCommand(minuteToken string, artifactFlags []string) string { + parts := []string{"lark-cli", "minutes", "+detail", "--minute-tokens", minuteToken} + parts = append(parts, artifactFlags...) + parts = append(parts, "--wait-ready") + return strings.Join(parts, " ") +} + // saveDetailTranscript persists transcript bytes to the canonical artifact path. // With --output-dir, transcripts land under /artifact--<token>/ // to mirror the legacy `vc +notes` layout. Otherwise falls back to the default @@ -201,6 +296,9 @@ var MinutesDetail = common.Shortcut{ {Name: "keyword", Type: "bool", Desc: "include keywords"}, {Name: "output-dir", Desc: "output directory for transcript files (default: ./minutes/{minute_token}/)"}, {Name: "overwrite", Type: "bool", Desc: "overwrite existing transcript files"}, + {Name: "wait-ready", Type: "bool", Desc: "wait until minute metadata/artifacts are ready", Hidden: true}, + {Name: "wait-timeout-seconds", Type: "int", Default: "300", Desc: "maximum seconds to wait for readiness", Hidden: true}, + {Name: "wait-interval-seconds", Type: "int", Default: "15", Desc: "seconds between readiness checks", Hidden: true}, }, Validate: func(ctx context.Context, runtime *common.RuntimeContext) error { tokens := common.SplitCSV(runtime.Str("minute-tokens")) @@ -282,8 +380,15 @@ var MinutesDetail = common.Shortcut{ for _, r := range results { row := map[string]interface{}{"minute_token": r.MinuteToken} if r.Error != "" { - row["status"] = "FAIL" + if r.Status == "processing" { + row["status"] = "PROCESSING" + } else { + row["status"] = "FAIL" + } row["error"] = r.Error + if r.NextCommand != "" { + row["next_command"] = r.NextCommand + } } else { row["status"] = "OK" row["title"] = r.Title diff --git a/shortcuts/minutes/minutes_detail_test.go b/shortcuts/minutes/minutes_detail_test.go index b5c8f46d8..fdf1e3dad 100644 --- a/shortcuts/minutes/minutes_detail_test.go +++ b/shortcuts/minutes/minutes_detail_test.go @@ -9,6 +9,7 @@ import ( "encoding/json" "errors" "fmt" + "net/http" "os" "strings" "sync" @@ -108,6 +109,17 @@ func detailArtifactsStub(token, transcript string) *httpmock.Stub { } } +func detailProcessingStub(path string) *httpmock.Stub { + return &httpmock.Stub{ + Method: "GET", + URL: path, + Body: map[string]interface{}{ + "code": 2091003, + "msg": "minute is processing", + }, + } +} + func TestDetail_Validation_MissingMinuteTokens(t *testing.T) { f, _, _, _ := cmdutil.TestFactory(t, defaultConfig()) err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--as", "user"}, f, nil) @@ -172,6 +184,34 @@ func TestDetail_DryRun_WithArtifactFlags(t *testing.T) { } } +func TestDetail_HiddenWaitFlags(t *testing.T) { + f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig()) + parent := &cobra.Command{Use: "minutes"} + MinutesDetail.Mount(parent, f) + parent.SetOut(stdout) + parent.SetArgs([]string{"+detail", "--help"}) + parent.SilenceErrors = true + parent.SilenceUsage = true + if err := parent.Execute(); err != nil { + t.Fatalf("help failed: %v", err) + } + help := stdout.String() + for _, hidden := range []string{"wait-ready", "wait-timeout-seconds", "wait-interval-seconds"} { + if strings.Contains(help, hidden) { + t.Fatalf("hidden flag %q should not appear in help:\n%s", hidden, help) + } + } + + stdout.Reset() + err := detailMountAndRun(t, MinutesDetail, []string{ + "+detail", "--minute-tokens", "tok001", "--summary", "--wait-ready", + "--wait-timeout-seconds", "0", "--wait-interval-seconds", "0", "--dry-run", "--as", "user", + }, f, stdout) + if err != nil { + t.Fatalf("hidden wait flags should parse: %v", err) + } +} + // --------------------------------------------------------------------------- // Execute tests with mocked HTTP // --------------------------------------------------------------------------- @@ -355,6 +395,136 @@ func TestDetail_Execute_MinuteNotFound(t *testing.T) { } } +func TestDetail_Execute_MetadataProcessing(t *testing.T) { + f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig()) + reg.Register(detailProcessingStub("/open-apis/minutes/v1/minutes/tokpending")) + + err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", "tokpending", "--summary", "--as", "user"}, f, stdout) + if err == nil { + t.Fatal("expected partial failure error") + } + var pfErr *output.PartialFailureError + if !errors.As(err, &pfErr) { + t.Fatalf("expected *output.PartialFailureError, got %T: %v", err, err) + } + m := firstDetailMinute(t, stdout.Bytes()) + if m["status"] != "processing" { + t.Fatalf("status = %v, want processing", m["status"]) + } + if m["retryable"] != true { + t.Fatalf("retryable = %v, want true", m["retryable"]) + } + if !strings.Contains(fmt.Sprint(m["next_command"]), "minutes +detail --minute-tokens tokpending --summary --wait-ready") { + t.Fatalf("next_command = %v", m["next_command"]) + } +} + +func TestDetail_Execute_ArtifactsProcessing(t *testing.T) { + f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig()) + reg.Register(detailMinuteGetStub("tokartpending", "note_pending", "Pending Artifacts")) + reg.Register(detailProcessingStub("/open-apis/minutes/v1/minutes/tokartpending/artifacts")) + + err := detailMountAndRun(t, MinutesDetail, []string{"+detail", "--minute-tokens", "tokartpending", "--summary", "--todo", "--as", "user"}, f, stdout) + if err == nil { + t.Fatal("expected partial failure error") + } + m := firstDetailMinute(t, stdout.Bytes()) + if m["status"] != "processing" { + t.Fatalf("status = %v, want processing", m["status"]) + } + if m["title"] != "Pending Artifacts" || m["note_id"] != "note_pending" { + t.Fatalf("metadata should be preserved on artifacts processing, got title=%v note_id=%v", m["title"], m["note_id"]) + } + if !strings.Contains(fmt.Sprint(m["next_command"]), "--summary --todo --wait-ready") { + t.Fatalf("next_command = %v", m["next_command"]) + } +} + +func TestDetail_WaitReady_MetadataEventuallyReady(t *testing.T) { + f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig()) + reg.Register(detailProcessingStub("/open-apis/minutes/v1/minutes/tokwaitmeta")) + reg.Register(detailMinuteGetStub("tokwaitmeta", "", "Ready Metadata")) + + err := detailMountAndRun(t, MinutesDetail, []string{ + "+detail", "--minute-tokens", "tokwaitmeta", "--wait-ready", + "--wait-timeout-seconds", "5", "--wait-interval-seconds", "1", "--as", "user", + }, f, stdout) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + m := firstDetailMinute(t, stdout.Bytes()) + if m["title"] != "Ready Metadata" { + t.Fatalf("title = %v, want Ready Metadata", m["title"]) + } + if _, ok := m["artifacts"]; ok { + t.Fatal("artifacts should not be fetched without artifact flags") + } +} + +func TestDetail_WaitReady_ArtifactsEventuallyReady(t *testing.T) { + f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig()) + reg.Register(detailMinuteGetStub("tokwaitart", "note_wait", "Ready Artifacts")) + reg.Register(detailProcessingStub("/open-apis/minutes/v1/minutes/tokwaitart/artifacts")) + reg.Register(detailArtifactsStub("tokwaitart", "")) + + err := detailMountAndRun(t, MinutesDetail, []string{ + "+detail", "--minute-tokens", "tokwaitart", "--summary", "--wait-ready", + "--wait-timeout-seconds", "5", "--wait-interval-seconds", "1", "--as", "user", + }, f, stdout) + if err != nil { + t.Fatalf("unexpected error: %v", err) + } + m := firstDetailMinute(t, stdout.Bytes()) + arts, _ := m["artifacts"].(map[string]any) + if arts == nil { + t.Fatal("expected artifacts") + } + if arts["summary"] != "Test summary content" { + t.Fatalf("summary = %v", arts["summary"]) + } +} + +func TestDetail_WaitReady_TimeoutUsesProcessingResult(t *testing.T) { + f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig()) + reg.Register(detailMinuteGetStub("toktimeout", "note_timeout", "Timeout Artifacts")) + reg.Register(detailProcessingStub("/open-apis/minutes/v1/minutes/toktimeout/artifacts")) + + err := detailMountAndRun(t, MinutesDetail, []string{ + "+detail", "--minute-tokens", "toktimeout", "--summary", "--wait-ready", + "--wait-timeout-seconds", "1", "--wait-interval-seconds", "2", "--as", "user", + }, f, stdout) + if err == nil { + t.Fatal("expected partial failure error") + } + m := firstDetailMinute(t, stdout.Bytes()) + if m["status"] != "processing" || m["title"] != "Timeout Artifacts" || m["note_id"] != "note_timeout" { + t.Fatalf("timeout should preserve processing status and metadata, got %+v", m) + } +} + +func TestDetail_WaitReady_DoesNotPollNonProcessingErrors(t *testing.T) { + f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig()) + var callCount int + reg.Register(&httpmock.Stub{ + Method: "GET", + URL: "/open-apis/minutes/v1/minutes/tokmissing", + Body: map[string]interface{}{"code": 2091004, "msg": "not found"}, + Reusable: true, + OnMatch: func(req *http.Request) { callCount++ }, + }) + + err := detailMountAndRun(t, MinutesDetail, []string{ + "+detail", "--minute-tokens", "tokmissing", "--wait-ready", + "--wait-timeout-seconds", "5", "--wait-interval-seconds", "1", "--as", "user", + }, f, stdout) + if err == nil { + t.Fatal("expected partial failure error") + } + if callCount != 1 { + t.Fatalf("non-processing error should not be retried, callCount=%d", callCount) + } +} + // --------------------------------------------------------------------------- // Pure function tests // --------------------------------------------------------------------------- @@ -378,6 +548,36 @@ func TestValidMinuteTokenDetail(t *testing.T) { } } +func TestNormalizeMinutesDetailWaitSeconds(t *testing.T) { + timeout, interval := normalizeMinutesDetailWaitSeconds(0, 0) + if timeout != minutesDetailWaitTimeoutDefault || interval != minutesDetailWaitIntervalDefault { + t.Fatalf("normalize(0,0) = (%d,%d), want defaults (%d,%d)", timeout, interval, minutesDetailWaitTimeoutDefault, minutesDetailWaitIntervalDefault) + } + timeout, interval = normalizeMinutesDetailWaitSeconds(-1, -2) + if timeout != minutesDetailWaitTimeoutDefault || interval != minutesDetailWaitIntervalDefault { + t.Fatalf("normalize(negative) = (%d,%d), want defaults", timeout, interval) + } + timeout, interval = normalizeMinutesDetailWaitSeconds(9, 3) + if timeout != 9 || interval != 3 { + t.Fatalf("normalize(9,3) = (%d,%d)", timeout, interval) + } +} + +func firstDetailMinute(t *testing.T, raw []byte) map[string]any { + t.Helper() + var resp map[string]any + if err := json.Unmarshal(raw, &resp); err != nil { + t.Fatalf("failed to parse output: %v\n%s", err, string(raw)) + } + data, _ := resp["data"].(map[string]any) + minutes, _ := data["minutes"].([]any) + if len(minutes) != 1 { + t.Fatalf("expected 1 minute, got %d in %s", len(minutes), string(raw)) + } + m, _ := minutes[0].(map[string]any) + return m +} + // chdirForDetailTest switches cwd to a temp dir for the test. func chdirForDetailTest(t *testing.T) string { t.Helper() diff --git a/shortcuts/minutes/minutes_upload.go b/shortcuts/minutes/minutes_upload.go index 0f2f1f288..8911e82c5 100644 --- a/shortcuts/minutes/minutes_upload.go +++ b/shortcuts/minutes/minutes_upload.go @@ -5,6 +5,8 @@ package minutes import ( "context" + "net/url" + "strings" "github.com/larksuite/cli/errs" "github.com/larksuite/cli/internal/validate" @@ -65,8 +67,25 @@ var MinutesUpload = common.Shortcut{ outData := map[string]interface{}{ "minute_url": minuteURL, } + if minuteToken := extractUploadedMinuteToken(minuteURL); minuteToken != "" { + outData["minute_token"] = minuteToken + } runtime.OutFormat(outData, nil, nil) return nil }, } + +func extractUploadedMinuteToken(minuteURL string) string { + u, err := url.Parse(minuteURL) + if err != nil { + return "" + } + parts := strings.Split(strings.TrimRight(u.Path, "/"), "/") + for i, part := range parts { + if part == "minutes" && i+1 < len(parts) { + return parts[i+1] + } + } + return "" +} diff --git a/shortcuts/minutes/minutes_upload_test.go b/shortcuts/minutes/minutes_upload_test.go index 26f661828..f7d62306f 100644 --- a/shortcuts/minutes/minutes_upload_test.go +++ b/shortcuts/minutes/minutes_upload_test.go @@ -143,4 +143,28 @@ func TestMinutesUpload_Execute(t *testing.T) { if dataMap["minute_url"] != "https://sample.feishu.cn/minutes/obcnq3b9jl72l83w4f149w9c" { t.Errorf("expected minute_url https://sample.feishu.cn/minutes/obcnq3b9jl72l83w4f149w9c, got %v", dataMap["minute_url"]) } + if dataMap["minute_token"] != "obcnq3b9jl72l83w4f149w9c" { + t.Errorf("expected minute_token obcnq3b9jl72l83w4f149w9c, got %v", dataMap["minute_token"]) + } +} + +func TestExtractUploadedMinuteToken(t *testing.T) { + tests := []struct { + name string + url string + want string + }{ + {name: "standard", url: "https://sample.feishu.cn/minutes/obcnq3b9jl72l83w4f149w9c", want: "obcnq3b9jl72l83w4f149w9c"}, + {name: "query", url: "https://sample.feishu.cn/minutes/obcn123?from=upload", want: "obcn123"}, + {name: "trailing slash", url: "https://sample.feishu.cn/minutes/obcn123/", want: "obcn123"}, + {name: "invalid", url: "://bad", want: ""}, + {name: "no minutes path", url: "https://sample.feishu.cn/docx/abc", want: ""}, + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + if got := extractUploadedMinuteToken(tt.url); got != tt.want { + t.Fatalf("extractUploadedMinuteToken(%q) = %q, want %q", tt.url, got, tt.want) + } + }) + } } diff --git a/skills/lark-calendar/SKILL.md b/skills/lark-calendar/SKILL.md index c5b1d5f87..197436018 100644 --- a/skills/lark-calendar/SKILL.md +++ b/skills/lark-calendar/SKILL.md @@ -12,7 +12,7 @@ metadata: 开始前先读 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md)（认证、权限处理）。 -**CRITICAL — 凡涉及预约日程/会议或查询/搜索会议室，第一步 MUST 读 [`references/lark-calendar-schedule-meeting.md`](references/lark-calendar-schedule-meeting.md)。禁止跳过此步直接调用 API 或 Shortcut！** +**CRITICAL — 凡涉及预约日程/会议室、调整时间或查询/搜索会议室，第一步 MUST 读 [`references/lark-calendar-schedule-meeting.md`](references/lark-calendar-schedule-meeting.md)。仅编辑字段（改标题/描述）或增删参会人（不涉及时间和会议室）时可跳过，直接读 [`references/lark-calendar-update.md`](references/lark-calendar-update.md)。** ## 身份 @@ -30,26 +30,80 @@ lark-cli calendar +agenda --as user | Shortcut | 说明 | |----------|------| -| [`+agenda`](references/lark-calendar-agenda.md) | 查看日程安排（默认今天） | -| [`+search-event`](references/lark-calendar-search-event.md) | 按关键词、时间范围和参会人搜索日程, 仅返回 日程ID/主题/时间等信息，详情需走 `events get` | +| `+agenda` | 查看日程安排（默认今天） | | [`+meeting`](references/lark-calendar-meeting.md) | 通过日程事件 ID 获取关联的视频会议信息（meeting_id、meeting_note），日程开过视频会议才会有meeting_id | | [`+create`](references/lark-calendar-create.md) | 创建日程并邀请参会人（ISO 8601 时间） | | [`+update`](references/lark-calendar-update.md) | 更新既有日程字段，或独立增量添加/移除参会人和会议室 | -| [`+freebusy`](references/lark-calendar-freebusy.md) | 查询用户主日历的忙闲信息和 RSVP 状态 | +| `+freebusy` | 查询用户主日历的忙闲信息和 RSVP 状态（纯查询场景；预约场景走 `+suggestion`） | | [`+room-find`](references/lark-calendar-room-find.md) | 针对一个或多个**明确的**时间块查找可用会议室（无明确时间时禁止直接调用，需先走 +suggestion） | | [`+rsvp`](references/lark-calendar-rsvp.md) | 回复日程（接受/拒绝/待定） | | [`+suggestion`](references/lark-calendar-suggestion.md) | 根据非明确时间或一段时间范围，推荐多个可用时间块方案 | +### `+get` — 单日程详情 + +通过 `calendar_id` + `event_id` 获取**单个日程**详情。 + +```bash +# calendar_id不传，默认primary +lark-cli calendar +get --calendar-id <calendar_id> --event-id <event_id> +``` + +### `+search-event` — 按关键词、时间范围和参会人搜索日程 + +仅返回基础字段（`event_id`/`summary`/`start`/`end` 等），需要详情请走 `+get`。 + +```bash +# query 按关键词 可选 +# start/end 按时间范围（ISO 8601 或 YYYY-MM-DD）可选 +# attendee-ids 按参会人（自动识别 ou_ 用户 / oc_ 群聊 / omm_ 会议室前缀）可选 +# page-token 分页游标，用于继续翻页 可选 +# page-size 每页数量，默认 30 可选 +lark-cli calendar +search-event --query "周会" --start 2026-04-20 --end 2026-04-27 --attendee-ids "ou_user1,oc_chat1,omm_room1" --page-token <page_token> --page-size 30 +``` + +### `+agenda` — 查看近期日程安排 + +默认查询当天。结果应整理为按日期分组、按开始时间升序的易读时间线。 + +```bash +# start/end 时间范围（ISO 8601 / YYYY-MM-DD / Unix 秒），均可选；默认当天 +# calendar-id 日历 ID（默认primary）可选 +lark-cli calendar +agenda --start 2026-03-10 --end 2026-03-17 --calendar-id <calendar_id> +``` + +注意： +- 已取消的日程自动过滤；无日程时直接告知"日程清空"。 +- 时间范围超过 40 天会自动拆分查询并合并结果。 + +### `+freebusy` — 查询主日历忙闲时段和 RSVP 状态 + +仅返回忙碌时段起止时间，不含日程标题等隐私信息；其他订阅日历不在范围内。 + +```bash +# start/end 时间范围（ISO 8601 / YYYY-MM-DD / Unix 秒），均可选；默认当天 +# user-id 目标用户 open_id（ou_ 前缀）可选；默认当前登录用户，bot 身份必须显式指定 +lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-12 --user-id ou_xxx +``` + +用法提示： +- **仅判断是否有空** → `+freebusy`；**需要日程详情** → `+agenda`。 +- 检查多人可用性：分别调用并对比，找共同空闲。 +- 预约/改约场景下，调用规则（参与人过多、含群组、来自 `+suggestion` 等）详见 [schedule-clear-time.md § 查询忙闲](references/lark-calendar-schedule-clear-time.md#2-查询忙闲)。 + ## 前置条件路由 | 场景 | 前置要求 | |------|----------| -| 预约日程/会议、查会议室 | 先读 [lark-calendar-schedule-meeting.md](references/lark-calendar-schedule-meeting.md) | -| 编辑已有日程 | 先定位目标日程 `event_id` | +| 预约日程/会议、调整时间、查会议室 | 先读 [lark-calendar-schedule-meeting.md](references/lark-calendar-schedule-meeting.md) | +| 仅编辑字段（标题/描述）或增删参会人 | 先定位 `event_id`，再读 [lark-calendar-update.md](references/lark-calendar-update.md) | +| 编辑已有日程（涉及时间或会议室） | 先定位目标日程 `event_id`；若是重复性日程，必须定位到具体实例的 `event_id`（禁止使用原重复日程 ID） | | 编辑/删除重复性日程 | 先读 [重复性日程操作规范](references/lark-calendar-recurring.md)，按操作范围（仅此次/全部/此次及后续）执行 | -| 删除/修改后验证 | 等待 2 秒再查询（API 最终一致性），不要告知用户你等待了 | | 调用任何 Shortcut | 先读其对应 reference 文档 | +## 写操作反馈 + +创建、更新、删除、RSVP 等写操作完成后，直接基于命令返回结果反馈用户；不要为了“确认是否生效”主动发起二次查询。只有用户明确要求复查，或命令返回信息不足以回答用户问题时，才需要再查询。 + ## 核心概念 - **日程实例（Instance）**：重复性日程展开后的具体时间实例。「仅此次」操作时使用具体实例的 `event_id`；「全部」或「此次及后续」操作时需对原重复性日程操作（使用原日程 `event_id`），并按需处理例外。 @@ -72,7 +126,8 @@ lark-cli calendar +agenda --as user | 按关键词搜索日程 | 本 skill（`+search-event`） | | 从日程获取关联的视频会议 ID 或用户绑定的会议纪要文档 | 本 skill（`+meeting`） | | 从日程进一步拿 AI 智能纪要 / 逐字稿 / 妙记产物 | 先 `+meeting` 取 `meeting_id`，再 [`vc +detail`](../lark-vc/references/lark-vc-detail.md) → [`note +detail`](../lark-note/references/lark-note-detail.md) / [`minutes +detail`](../lark-minutes/references/lark-minutes-detail.md) | -| 预约/改约日程、添加/移除参会人、添加/更换会议室、调整时间 | 先判断新建 vs 编辑，再进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md) | +| 预约/改约日程、调整时间、添加/更换会议室、查会议室 | 先判断新建 vs 编辑，再进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md) | +| 仅编辑日程字段（标题/描述）或增删参会人（不涉及时间和会议室） | 先定位 `event_id`，再读 [+update](references/lark-calendar-update.md) 执行变更 | | 编辑/删除重复性日程（「改这个重复日程」「删掉后面的」「全部取消」等） | 先读 [重复性日程操作规范](references/lark-calendar-recurring.md)，确认操作范围后执行 | ## 任务类型分流 @@ -90,7 +145,7 @@ lark-cli calendar +agenda --as user ## 会议室规则 -- 凡是"预定/查询/搜索可用会议室"，都必须进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md)。 +- 凡是"预定/查询/搜索可用会议室"，都必须进入 [schedule-meeting 工作流](references/lark-calendar-schedule-meeting.md)，会议室参数规范详见 [+room-find](references/lark-calendar-room-find.md)。 - `+room-find` 的时间输入必须是确定时间块，不能是时间区间搜索。 - 用户仅要求"查会议室"但未提供明确时间时，必须先调用 `+suggestion` 获取可用时间块，再将时间块交给 `+room-find`。严禁猜测时间盲目调用。 - 编辑已有日程时，"添加会议室"默认是增量语义，保留已有会议室；只有用户明确说"更换会议室""移除会议室"时才删除旧会议室。 @@ -98,42 +153,45 @@ lark-cli calendar +agenda --as user ## API Resources ```bash +# 通用调用格式 lark-cli calendar <resource> <method> [flags] + +# 查询用户主日历 +lark-cli calendar calendars primary + +# 获取日程分享链接 +lark-cli calendar events share_info --calendar-id <calendar_id> --event-id <event_id> + +# 删除日程 +lark-cli calendar events delete --calendar-id <calendar_id> --event-id <event_id> ``` -### calendars +> `calendar_id` 可以直接传 `primary`，代表当前调用身份的主日历 ID。 - - `create` — 创建共享日历 - - `delete` — 删除共享日历 - - `get` — 查询日历信息 - - `list` — 查询日历列表 - - `patch` — 更新日历信息 - - `primary` — 查询用户主日历 - - `search` — 搜索日历 +### 查询资源的方法列表以及方法的使用方式 -### event.attendees +- 列出某资源下的方法：`lark-cli calendar <resource> -h` +- 查看方法的cli flag：`lark-cli calendar <resource> <method> -h` +- 查看方法API参数：`lark-cli schema calendar.<resource>.<method>` - - `batch_delete` — 删除日程参与人 - - `create` — 添加日程参与人 - - `list` — 获取日程参与人列表 +`<resource>` 为 `calendars`（日历本身）/ `events`（日程）/ `event.attendees`（参与人）/ `freebusys`（忙闲）。例：`lark-cli schema calendar.events.delete`。 -### events +## 常用其他域命令 - - `create` — 创建日程 - - `delete` — 删除日程 - - `get` — 获取日程 - - `instance_view` — 查询日程视图 - - `patch` — 更新日程 - - `share_info` — 获取日程分享链接 +```bash +# 搜索用户，更多参数详见 lark-contact +lark-cli contact +search-user --query <query> --as user -### freebusys - - - `list` — 查询主日历日程忙闲信息 +# 搜索群聊，更多参数详见 lark-im +lark-cli im +chat-search --query <query> --as user +``` ## 不在本 skill 范围 - 查询过去的视频会议记录 → [lark-vc](../lark-vc/SKILL.md) - 待办任务管理 → [lark-task](../lark-task/SKILL.md) +- 通讯录 → [lark-contact](../lark-contact/SKILL.md) +- 即时通讯 → [lark-im](../lark-im/SKILL.md) - 会议室物理设施管理 → 管理员后台 **注意（强制性）：** diff --git a/skills/lark-calendar/references/lark-calendar-agenda.md b/skills/lark-calendar/references/lark-calendar-agenda.md deleted file mode 100644 index 86405ba8b..000000000 --- a/skills/lark-calendar/references/lark-calendar-agenda.md +++ /dev/null @@ -1,78 +0,0 @@ - -# calendar +agenda - -> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 - -查看近期日程安排。只读操作，不修改任何日程。 - -需要的scopes: ["calendar:calendar.event:read"] - -## 命令 - -```bash -# 查看今天日程（默认） -lark-cli calendar +agenda - -# 自定义时间范围（ISO 8601） -lark-cli calendar +agenda --start "2026-03-10T00:00+08:00" --end "2026-03-17T00:00+08:00" - -# 自定义时间范围（仅日期） -lark-cli calendar +agenda --start 2026-03-10 --end 2026-03-17 - -# 人类可读格式输出 -lark-cli calendar +agenda --format pretty - -# 指定日历 -lark-cli calendar +agenda --calendar-id cal_xxx -``` - -## 参数 - -| 参数 | 必填 | 说明 | -|------|------|------| -| `--start <time>` | 否 | 开始时间（ISO 8601 或仅日期，默认当天） | -| `--end <time>` | 否 | 结束时间（默认与 `--start` 属于同一天，自动取当天结束时间） | -| `--calendar-id <id>` | 否 | 日历 ID（省略则使用主日历） | -| `--format` | 否 | 输出格式：json（默认） \| pretty | -| `--dry-run` | 否 | 预览 API 调用，不执行 | - -## 时间格式 - -`--start` 和 `--end` 支持以下格式： - -| 格式 | 示例 | 说明 | -|------|------|------| -| ISO 8601 | `2026-03-10T14:00:00+08:00` | 完整格式 | -| 日期+时间 | `2026-03-10 14:00:00` | 自动补全时区 | -| 仅日期 | `2026-03-10` | start 取 00:00:00，end 取 23:59:59 | -| Unix 时间戳 | `1741564800` | 秒级时间戳 | - -## 输出格式 - -**将结果整理为易读的日程表：** - -``` -## 2026-03-10 周一 - -09:00 - 09:30 站会 -10:00 - 11:00 产品评审 -14:00 - 15:00 与 Alice 1:1 - -## 2026-03-11 周二 - -（无日程） -``` - -**注意：按日期分组，并严格按照开始时间升序（从早到晚的时间线）排序输出。** 显示标题、时长 - -## 提示 - -- 已取消的日程会自动过滤，无需额外处理。 -- 如无日程，告知用户"日程清空"。 -- 大于 40 天的时间范围会自动拆分查询并合并结果。 -- 查看多个日历：先用 `lark-cli calendar calendars list --page-all` 列出日历列表，再逐个查询。 - -## 参考 - -- [lark-calendar](../SKILL.md) -- 日历全部命令 -- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数 diff --git a/skills/lark-calendar/references/lark-calendar-create.md b/skills/lark-calendar/references/lark-calendar-create.md index 6bef8a11c..4036de2ba 100644 --- a/skills/lark-calendar/references/lark-calendar-create.md +++ b/skills/lark-calendar/references/lark-calendar-create.md @@ -1,12 +1,9 @@ # calendar +create -> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 创建日程并按需邀请参会人。 -需要的scopes: ["calendar:calendar.event:create","calendar:calendar.event:update"] - ## 推荐命令 ```bash @@ -38,10 +35,10 @@ lark-cli calendar +create --summary "..." --start "..." --end "..." \ | `--description <text>` | 否 | 日程详细描述。提供会议议程、活动内容、注意事项或链接等。与 summary 配合使用，仅关注当前日程信息 | | `--attendee-ids <id_list>` | 否 | 参与人 ID 列表（逗号分隔）。支持用户（`ou_`）、群组（`oc_`）和会议室（`omm_`）。AI 提取时请务必保留对应前缀 | | `--calendar-id <id>` | 否 | 日历 ID（省略则使用主日历） | -| `--rrule <rrule>` | 否 | 重复日程的重复性规则，规则设置方式参考rfc5545。**【⚠️注意：系统绝对不支持 COUNT，如需限制重复次数，必须转为 UNTIL】**。示例值："FREQ=DAILY;INTERVAL=1" | +| `--rrule <rrule>` | 否 | 重复日程的重复性规则，规则设置方式参考rfc5545。示例值："FREQ=DAILY;INTERVAL=1;UNTIL=<具体日期>" | | `--dry-run` | 否 | 预览 API 调用，不执行 | -> **⚠️ `rrule` 规则限制：飞书日历系统不支持 `COUNT` 参数。遇到限制重复次数的需求，必须根据开始时间和频率自行推算并转换成 `UNTIL=<具体日期>` 格式。** +> 当用户表达'每周 X'、'每周重复'、'连续 N 周'时，必须使用 rrule 创建重复性日程，而非创建多个独立日程 > 自动设置 `attendee_ability: "can_modify_event"`，参会人可查看彼此并编辑日程。 > 自动设置 `free_busy_status: "busy"`，默认日程忙闲状态为忙碌。 > 自动设置 `reminders: [{"minutes": 5}]`，默认日程开始前 5 分钟提醒。 @@ -56,44 +53,16 @@ lark-cli calendar +create --summary "..." --start "..." --end "..." \ - 全天日程的开始日期和结束日期必须分别是日程开始的第一天和结束的最后一天。如果只有一天的话，开始日期和结束日期是相同。 ```bash -# 第一步：创建日程（含高级参数） -## 查看完整参数定义 -lark-cli schema calendar.events.create -## 创建日程 -lark-cli calendar events create \ - --params '{"calendar_id":"<CALENDAR_ID>"}' \ - --data '{ - "summary": "技术分享：CLI 架构设计", - "start_time": { "timestamp": "1741586400" }, - "end_time": { "timestamp": "1741593600" } -}' - -# 第二步：添加参会人（使用第一步返回的 calendar_id 和 event_id） -## 查看完整参数定义 -lark-cli schema calendar.event.attendees.create -## 添加参会人 -lark-cli calendar event.attendees create \ - --as user \ - --params '{"calendar_id":"<CALENDAR_ID>","event_id":"<EVENT_ID>"}' \ - --data '{"attendees": [{"type": "user", "user_id": "ou_xxx"}]}' - ## 添加需要审批的会议室（approval_reason 最大 200 字符） lark-cli calendar event.attendees create \ --as user \ --params '{"calendar_id":"<CALENDAR_ID>","event_id":"<EVENT_ID>"}' \ --data '{"attendees": [{"type": "resource", "room_id": "omm_xxx", "approval_reason": "申请原因"}]}' -# 可选第三步（推荐）：若第二步失败，回滚删除空日程 -## 查看完整参数定义 -lark-cli schema calendar.events.delete -## 删除空日程 -lark-cli calendar events delete \ - --params '{"calendar_id":"<CALENDAR_ID>","event_id":"<EVENT_ID>","need_notification":false}' - -``` - -> 完整 API 命令的时间参数是 **Unix 秒字符串**（非 ISO 8601）。 -> 当你手动拆成两步执行时，建议保留“失败后回滚删除”的第三步，避免遗留空日程。 +完整 API 命令的关键差异： +- 时间参数是 **Unix 秒字符串**（非 ISO 8601）。 +- 全天日程的开始日期和结束日期必须分别是日程开始的第一天和结束的最后一天；单日全天日程两者相同。 +- 手动拆成“创建日程 + 添加参会人”两步时，若第二步失败，建议删除刚创建的空日程，避免遗留无参会人的日程。 ## 参会人类型 @@ -109,6 +78,5 @@ lark-cli calendar events delete \ ## 参考 -- [lark-calendar](../SKILL.md) -- 日历全部命令 -- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数 +- [lark-calendar](../SKILL.md) -- skill 入口与路由 - [lark-calendar-suggestion](lark-calendar-suggestion.md) -- 根据非明确时间或一段时间范围，推荐多个可用时间块方案 diff --git a/skills/lark-calendar/references/lark-calendar-freebusy.md b/skills/lark-calendar/references/lark-calendar-freebusy.md deleted file mode 100644 index bd59f933e..000000000 --- a/skills/lark-calendar/references/lark-calendar-freebusy.md +++ /dev/null @@ -1,124 +0,0 @@ - -# calendar +freebusy - -> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)。 - -查询用户主日历的忙闲信息，返回指定时间范围内的忙碌时段列表和rsvp的状态。 - -需要的scopes: ["calendar:calendar.free_busy:read"] - -## 命令 - -```bash -# 查询当前用户今天的忙闲（默认） -lark-cli calendar +freebusy - -# 自定义时间范围（仅日期） -lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-12 - -# 自定义时间范围（完整 ISO 8601） -lark-cli calendar +freebusy --start "2026-03-11T08:00:00+08:00" --end "2026-03-11T18:00:00+08:00" - -# 查询指定用户的忙闲信息 -lark-cli calendar +freebusy --start 2026-03-11 --end 2026-03-12 --user-id ou_xxx - -# 人类可读格式输出 -lark-cli calendar +freebusy --format pretty -``` - -## 参数 - -| 参数 | 必填 | 说明 | -|------|------|------| -| `--start <time>` | 否 | 查询开始时间（ISO 8601 或仅日期，默认当天） | -| `--end <time>` | 否 | 查询结束时间（默认与 `--start` 属于同一天，自动取当天结束时间） | -| `--user-id <open_id>` | 否 | 目标查询用户 ID（`ou_` 前缀）。省略时默认查询当前登录用户，bot 身份调用时必须明确指定 | -| `--format` | 否 | 输出格式：json（默认） \| pretty | -| `--dry-run` | 否 | 预览 API 调用，不执行 | - -## 时间格式 - -`--start` 和 `--end` 支持以下格式： - -| 格式 | 示例 | 说明 | -|------|------|------| -| ISO 8601 | `2026-03-11T09:00:00+08:00` | 完整格式 | -| 日期+时间 | `2026-03-11 09:00:00` | 自动补全时区 | -| 仅日期 | `2026-03-11` | start 取 00:00:00，end 取 23:59:59 | -| Unix 时间戳 | `1741564800` | 秒级时间戳 | - -## 输出示例 - -### 表格格式 - -``` -start end rsvp_status ----------------- ---------------- ----------- -2026-03-11 10:00 2026-03-11 10:30 接受 -2026-03-11 14:00 2026-03-11 15:00 待定 - -共 2 个忙碌时段 -``` - -### JSON 格式 - -```json -[ - { - "start_time": "2026-03-11T10:00:00+08:00", - "end_time": "2026-03-11T10:30:00+08:00", - "rsvp_status": "accept" - }, - { - "start_time": "2026-03-11T14:00:00+08:00", - "end_time": "2026-03-11T15:00:00+08:00", - "rsvp_status": "tentative" - } -] -``` - -## 典型场景 - -### 1. 查找日程会议空闲时段 - -```bash -# 查询今天的忙碌时段 -lark-cli calendar +freebusy - -# 查询工作时间段 -lark-cli calendar +freebusy \ - --start "2026-03-11T08:00:00+08:00" \ - --end "2026-03-11T18:00:00+08:00" -``` - -### 2. 检查团队成员可用性 - -```bash -# 查询多个成员，对比找出共同空闲时间 -lark-cli calendar +freebusy --start 2026-03-12 --user-id ou_member_a -lark-cli calendar +freebusy --start 2026-03-12 --user-id ou_member_b -``` - -## 注意事项 - -1. **只查询主日历** — 此命令只返回用户主日历的忙闲信息，不包括其他订阅日历 -2. **隐私保护** — 只返回忙碌时段的起止时间，不包含日程标题、描述等详细信息 -3. **bot 身份** — bot 必须通过 `--user-id` 指定要查询的用户 - -## 与其他命令对比 - -| 命令 | 用途 | 输出内容 | -|------|------|----------| -| `calendar +freebusy` | 查询忙闲时段 | 只返回忙碌时段列表（无日程详情） | -| `calendar +agenda` | 查看日程安排 | 返回完整日程列表（含标题、描述等） | - -**选择建议**： -- **仅需了解是否有空** → 使用 `+freebusy`（更快，隐私保护） -- **需要查看日程详情** → 使用 `+agenda` - -## 参考 - -- [lark-calendar-agenda](lark-calendar-agenda.md) — 查看日程安排 -- [lark-calendar-create](lark-calendar-create.md) — 创建日程 -- [lark-calendar-suggestion](lark-calendar-suggestion.md) — 根据非明确时间或一段时间范围，推荐多个可用时间块方案 -- [lark-calendar](../SKILL.md) — 日历完整 API diff --git a/skills/lark-calendar/references/lark-calendar-room-find.md b/skills/lark-calendar/references/lark-calendar-room-find.md index 0a94e1eec..bf1ed14a1 100644 --- a/skills/lark-calendar/references/lark-calendar-room-find.md +++ b/skills/lark-calendar/references/lark-calendar-room-find.md @@ -1,11 +1,8 @@ # calendar +room-find -> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)。 针对一个或多个时间块查找/搜索可用会议室。会议室是日程的一种资源型参与人，不能脱离日程单独预定。 -需要的 scopes: ["calendar:calendar.free_busy:read"] - ## 适用场景 - 已知一个或多个待选时间块，需要查找可用会议室 @@ -50,7 +47,7 @@ lark-cli calendar +room-find \ | `--city <text>` | 否 | 会议室所在城市强约束。**仅当**用户明确说出具体城市（如北京、上海）时才提取，**严禁**根据园区或楼宇名称自行联想或补全。 | | `--building <text>` | 否 | 会议室所在楼宇强约束，承载城市以下、楼层以上的办公区/园区/楼栋描述。| | `--floor <text>` | 否 | 仅用于筛选会议室所在楼层。应先做归一化，再传递规范值；例如 `2楼` / `二楼` / `2F` 统一为 `F2`。注意：此参数只筛选楼层，不可混入区域定位（如“A区”）或具体会议室号。 | -| `--room-name <text>` | 否 | 会议室名称约束，支持以**英文逗号**分隔传入多个名称。仅当用户明确提到会议室专名或会议室号（如"木星""02"）时使用。当用户需要在一组编号会议室中搜索时（如"帮我约 16~20 号的会议室"），应将编号展开为逗号分隔列表，如 `"16,17,18,19,20"`。应优先传递去后缀、去冗余后的规范名，例如 `木星会议室` → `木星`，`会议室 02` / `02会议室` → `02`。 | +| `--room-name <text>` | 否 | 会议室名称约束，支持以**英文逗号**分隔传入多个名称。仅当用户明确提到会议室专名、会议室号或编号区间时使用。 | | `--min-capacity <n>` | 否 | 会议室最小容纳人数。当用户明确参会人数或提出“至少容纳N人”等要求时，提取数字放入此参数，必须为正整数。 | | `--max-capacity <n>` | 否 | 会议室最大容纳人数。用于过滤过大空间，必须为正整数。 | | `--attendee-ids <id_list>` | 否 | 参会对象 ID 列表。支持用户 ID（`ou_` 前缀）和群组 ID（`oc_` 前缀），多个 ID 以逗号分隔。 | @@ -67,7 +64,7 @@ lark-cli calendar +room-find \ - 同一语义槽位只保留一个规范值。例如用户说“2楼”，应转换为 `--floor "F2"`；**禁止**同时传 `2楼 F2` 这类重复楼层信息。 - 参数归类顺序应为：`city/building/floor` > `floor + room-name` 复合表达 > `room-name`。若短词更像楼层/区域定位（如 `2L`、`2F`），优先落到 `--floor`，不要默认落到 `--room-name`。像 `学清2层` 这种表达，通常拆为 `--building "学清"` 与 `--floor "F2"`。 - 对会议室名要做轻量归一化：`木星会议室` 应提取为 `--room-name "木星"`；`会议室 02` / `02会议室` 应提取为 `--room-name "02"`。 -- **多会议室名称场景**：当用户表达"帮我约 XX 到 YY 号之间的会议室"或一次提及多个会议室名称时，应将所有目标名称用英文逗号拼接传入 `--room-name`。例如： +- 当用户表达"帮我约 XX 到 YY 号之间的会议室"或一次提及多个会议室名称时，应将所有目标名称用英文逗号拼接传入 `--room-name`。例如： - "帮我约 16~20 号的会议室" → `--room-name "16,17,18,19,20"` - "查下木星和火星是否有空" → `--room-name "木星,火星"` - "看看 01、02、03 会议室" → `--room-name "01,02,03"` @@ -90,9 +87,8 @@ lark-cli calendar +room-find \ ``` > **AI 行为指导：** -> - **结构化展示时间块与会议室**：默认按“时间块 -> 会议室候选”的层级结构展示。**严禁将时间与会议室名称输出在同一行**。以清晰的分行列表呈现可用会议室，并直接询问用户意向。默认原样展示完整 `room_name`；不要擅自缩写、截断、改写，或仅提取楼层及会议室号替代完整名称。 +> - **结构化展示时间块与会议室**：默认按“时间块 -> 会议室候选”的层级结构展示，并直接询问用户意向。 > - **`room_name` 必须逐字透传**：展示给用户的会议室名称，必须直接使用 CLI/API 返回的 `room_name` 原值。禁止提取楼层、会议室号、容量、视频能力后重组成新的名称，禁止意译、缩写、去前缀、去后缀，或仅保留"便于阅读"的摘要名。 -> - **主动识别区间/多名称意图**：当用户提到"帮我约 XX 到 YY 号的会议室""XX~YY 之间的会议室"或一次列出多个会议室名称时，将所有目标名称展开为英文逗号分隔列表，传入 `--room-name`。例如"帮我约 16 到 20 号的会议室"应生成 `--room-name "16,17,18,19,20"`。 > - **重复日程要明确阻断原因与自动缩短**：若某候选会议室的 `reserve_until_time` 无法覆盖重复性日程，**必须**向用户明确说明该会议室最长可约至何时。若用户确认继续选用该会议室，你必须**自动将日程的重复规则结束时间缩短**至该 `reserve_until_time`，以防止会议室预约失败。不能直接按原规则继续。 > - **正确解释推荐结果**：如果返回结果与用户输入条件不完全字面一致，先说明底层可能返回邻近位置或相近条件的推荐候选，不要直接将其判定为异常。 > - **默认减少用户输入成本**：应主动引导用户不必一开始就提供很详细的会议室搜索条件。只要时间块已明确，用户直接表达“想约会议室”即可，先基于当前信息查询候选；只有在用户对结果不满意时，再引导其补充更具体的楼宇、楼层、会议室名或容量条件。 @@ -102,7 +98,7 @@ lark-cli calendar +room-find \ | 字段名 | 说明 | | :--- | :--- | | `room_id` | 会议室唯一标识，用于后续创建日程时添加为会议室参与人使用。 | -| `room_name` | 会议室名称，默认原样完整展示给用户，不要自行缩写、截断、改写，也不要用楼层及会议室号摘要替代原值。 | +| `room_name` | 会议室名称，展示给用户时必须使用原值。 | | `capacity` | 会议室最大容纳人数。 | | `reserve_until_time` | 该会议室当前允许被预约到的最晚时间点，用于校验重复性日程是否超期。 | @@ -110,4 +106,4 @@ lark-cli calendar +room-find \ - [lark-calendar-create](lark-calendar-create.md) - [lark-calendar-suggestion](lark-calendar-suggestion.md) -- [lark-calendar](../SKILL.md) — 日历完整 API +- [lark-calendar](../SKILL.md) — skill 入口与路由 diff --git a/skills/lark-calendar/references/lark-calendar-rsvp.md b/skills/lark-calendar/references/lark-calendar-rsvp.md index c63280560..796183f2e 100644 --- a/skills/lark-calendar/references/lark-calendar-rsvp.md +++ b/skills/lark-calendar/references/lark-calendar-rsvp.md @@ -1,11 +1,8 @@ # calendar +rsvp -> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 回复指定的日程，更新当前用户的 RSVP 状态（接受、拒绝或待定）。 -需要的scopes: ["calendar:calendar.event:reply"] - ## 命令 ```bash @@ -38,5 +35,4 @@ lark-cli calendar +rsvp --calendar-id cal_xxx --event-id evt_xxx --rsvp-status a ## 参考 -- [lark-calendar](../SKILL.md) -- 日历全部命令 -- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数 +- [lark-calendar](../SKILL.md) -- skill 入口与路由 diff --git a/skills/lark-calendar/references/lark-calendar-schedule-clear-time.md b/skills/lark-calendar/references/lark-calendar-schedule-clear-time.md new file mode 100644 index 000000000..fdc9a6d84 --- /dev/null +++ b/skills/lark-calendar/references/lark-calendar-schedule-clear-time.md @@ -0,0 +1,59 @@ +# 明确时间分支：room-find + freebusy + 冲突处理 + +> 本文档处理**时间已明确**的场景。"明确时间"来源：用户直接表达（如"明天下午3点"）、编辑流中已定位日程的原始 start/end、或经用户确认的 suggestion 时间块。 + +## 前置条件 + +进入此分支前，调度器（[schedule-meeting.md](./lark-calendar-schedule-meeting.md)）已完成： +- 任务类型判定（新建 / 编辑） +- 编辑流：目标 event_id 已定位 +- 新建流：默认值已补全 +- 时间已判定为**明确** + +## 流程 + +### 1. 查询会议室（如需） + +若用户需要会议室，先调用 `+room-find`。详见 [`lark-calendar-room-find.md`](./lark-calendar-room-find.md)。 + +```bash +lark-cli calendar +room-find \ + --slot "<start>~<end>" \ + --attendee-ids "<ids>" \ + --city "<city>" \ + --building "<building>" \ + --floor "<F2>" \ + --room-name "<room_name>" +``` + +时间块确定规则： +- **编辑流且不改时间，只新增会议室**：`--slot` 必须来自已定位日程的当前 `start/end` +- **编辑流且既改时间又加会议室**：`--slot` 必须来自候选新时间，而不是旧时间 + +详见 [`lark-calendar-room-find.md`](./lark-calendar-room-find.md)。 + +### 2. 查询忙闲 + +```bash +lark-cli calendar +freebusy --start "<start>" --end "<end>" +``` + +规则： +- 参与人过多（超过 5 人）：仅查询**当前用户**及少数核心人员忙闲即可 +- 参与人含**群组**：无需展开群组成员查询忙闲 +- 如果用户是从 `+suggestion` 确认了时间块后进入本分支的，**无需再调用 `+freebusy`** + +### 3. 冲突处理 + +- **无冲突**：直接让用户选择会议室（如需），进入落地操作 +- **有冲突**：必须先说明冲突情况，询问用户： + - **继续当前时间** → 让用户选择会议室（如需），进入落地操作 + - **换时间** → 转入 [模糊时间分支](./lark-calendar-schedule-fuzzy-time.md) + +## 落地 + +根据任务类型： +- 新建 → [`+create`](./lark-calendar-create.md) +- 编辑 → [`+update`](./lark-calendar-update.md) + +落地规则详见 [schedule-meeting.md § 落地日程变更](./lark-calendar-schedule-meeting.md#落地日程变更)。 diff --git a/skills/lark-calendar/references/lark-calendar-schedule-fuzzy-time.md b/skills/lark-calendar/references/lark-calendar-schedule-fuzzy-time.md new file mode 100644 index 000000000..2c75b65a2 --- /dev/null +++ b/skills/lark-calendar/references/lark-calendar-schedule-fuzzy-time.md @@ -0,0 +1,88 @@ +# 模糊时间 / 无时间信息分支：suggestion + 批量查询 + +> 本文档处理**时间模糊**（如"明天下午""下周找个时间"）或**完全无时间信息**的场景。核心动作是调用 `+suggestion` 产出候选时间块，再根据是否需要会议室决定后续步骤。 + +## 前置条件 + +进入此分支前，调度器（[schedule-meeting.md](./lark-calendar-schedule-meeting.md)）已完成： +- 任务类型判定（新建 / 编辑） +- 编辑流：目标 event_id 已定位 +- 新建流：默认值已补全 +- 时间已判定为**模糊**或**无时间信息** + +## 流程 + +### 1. 调用 suggestion + +详见 [`lark-calendar-suggestion.md`](./lark-calendar-suggestion.md)。 + +```bash +lark-cli calendar +suggestion \ + --start "<range_start>" \ + --end "<range_end>" \ + --attendee-ids "<ids>" \ + --duration-minutes <n> \ + --event-rrule "<rrule>" +``` + +规则： +- 用户完全没有提供时间信息时，先默认一个合理区间（如"今天剩余时间"或"近两天"）再调用 +- 编辑流中，若用户说"改到明天下午""下周找个时间再约"，基于用户期望的**新时间范围**调用，不要沿用旧时间 +- **不要在用户完全没给时间时反问"你想约什么时候"** — 先补合理区间再进入 suggestion + +### 2. 分支处理 + +#### 不需要会议室 + +获取多个推荐时间块后，直接向用户展示候选时间，用户确认后进入落地操作。 + +#### 需要会议室 + +获取候选时间块后，**不要急于让用户只选时间**。先将这些时间块一次性交给 `+room-find` 批量查询可用会议室，然后将【候选时间】与【对应的可用会议室列表】结构化展示，让用户一次性完成选择。 + +> **注意**：即使用户最初只说"查会议室"且未带时间，也必须强制走 suggestion → room-find 路径。 + +详见 [`lark-calendar-room-find.md`](./lark-calendar-room-find.md)。 + +### 3. 用户确认后 + +- 用户选中 `+suggestion` 返回的时间块后，**无需再次调用 `+freebusy`**，直接进入落地操作 +- **BLOCKING REQUIREMENT**：必须先向用户展示选项并等待确认，禁止在未获用户确认时直接创建/更新日程 + +## 模糊语义消解与长期记忆 + +针对存在歧义的时间场景，严禁主观臆断。典型例子： +- "上班后" / "下班前" +- 未明确上下午的 12 小时制时间 + +处理规则： +- 主动澄清真实意图，不自行猜测 +- 用户澄清后，将个性化定义沉淀为长期偏好 + +## 用户展示格式 + +向用户展示多个时间块及对应会议室时，**必须结构化分行排版**，严禁将时间与会议室放在同一行： + +```text +## 2026-03-27 周五 + +[选项 1] 14:00 - 15:00（参会人均空闲） + 可用会议室： + 1. 学清嘉创大厦B座-F2-02🎦(7人) + 2. 学清嘉创大厦B座-F2-05🎦(10人) + +[选项 2] 16:00 - 17:00（参会人均空闲） + 可用会议室： + 1. 学清嘉创大厦B座-F3-01🎦(6人) + 2. 学清嘉创大厦B座-F3-06🎦(8人) + +💡 请回复您倾向的选项编号以及对应的会议室序号，我来为您完成预定。 +``` + +## 落地 + +根据任务类型： +- 新建 → [`+create`](./lark-calendar-create.md) +- 编辑 → [`+update`](./lark-calendar-update.md) + +落地规则详见 [schedule-meeting.md § 落地日程变更](./lark-calendar-schedule-meeting.md#落地日程变更)。 diff --git a/skills/lark-calendar/references/lark-calendar-schedule-meeting.md b/skills/lark-calendar/references/lark-calendar-schedule-meeting.md index 57187ce9a..3430ef248 100644 --- a/skills/lark-calendar/references/lark-calendar-schedule-meeting.md +++ b/skills/lark-calendar/references/lark-calendar-schedule-meeting.md @@ -1,206 +1,95 @@ # 预约/改约日程或会议、查询/搜索可用会议室的工作流 -## CRITICAL 执行摘要（先按这个骨架执行，再看下方细则） +## 执行摘要 -- **第一步永远是判断任务类型：新建日程，还是编辑已有日程。** 不要把“预约/查会议室”默认等同于“新建”。 -- **编辑已有日程时，必须先定位目标日程或实例的 `event_id`。** 用户一旦给出了既有日程锚点（标题、时间段、`这个日程`、`这场会`）并表达修改动作（加人、删人、改时间、换会议室等），默认走编辑流。 -- **默认做智能助理，不做表单填写机。** 能根据上下文补全的默认值就直接补全，避免把用户带入表单式问答。 -- **新建流先补默认值，编辑流先继承已定位日程信息。** 默认值包括标题、参会人、时长，以及在“完全无时间信息”时的默认时间范围；编辑流则优先复用已定位日程的标题、时间、已有参与人和会议室信息作为基线。 -- **只有三类场景才主动追问用户**：存在时间冲突、搜索结果无法唯一确定、时间语义本身有歧义。 -- **编辑流的时间基准必须明确。** 如果编辑时不改时间，则后续会议室搜索必须基于已定位日程的原始起止时间；如果既改时间又加会议室，必须先确定最终时间，再基于该时间搜索会议室。 -- **编辑流中“新增会议室”默认是增量语义。** 如果用户说的是“加会议室/再加一个会议室”，最终 `+update` 只做 `add`，默认保留已有会议室；只有在用户明确说“更换会议室/移除会议室”时，才执行旧会议室删除。 -- **明确时间**：若需要会议室，先 `+room-find`；再 `+freebusy` 判断参会人忙闲；有冲突时先说明冲突，再让用户决定继续当前时间还是改走 `+suggestion`。 -- **模糊时间或无时间信息**：先 `+suggestion` 产出候选时间块；若需要会议室，再把这些时间块批量交给 `+room-find`，将“候选时间 + 对应可用会议室”一次性展示给用户选择。 -- **BLOCKING REQUIREMENT: 只要面临时间方案（模糊时间/无时间）或会议室方案（需要会议室）的选择，必须先向用户展示选项并等待用户明确确认，绝对禁止在未获用户确认的情况下直接执行创建新日程或更新既有日程。** -- **用户选中了 `+suggestion` 返回的候选时间块后，不要再次调用 `+freebusy`。** 用户确认后直接进入最终落地操作：创建新日程，或更新既有日程。 -- **当用户说“查会议室”“找会议室”“搜可用会议室”时，默认意图是查会议室可用性，不是检索会议室资源名录。** -- **必须按顺序执行。** 不要跳过“任务类型判定”“目标日程定位（编辑流）”“补默认值/继承基线信息”“判断时间明确性”这些前置步骤。 - -> **💡 核心原则：做智能助理，充分利用默认值规则（如默认标题、时长、参与人等）自动补全信息。极力避免像“表单填写机”一样频繁打断并反问用户，仅在必须决策的冲突或无法唯一确定的场景下才发起询问。** +- **第一步永远是判断任务类型：新建日程，还是编辑已有日程。** +- **编辑已有日程时，必须先定位目标日程或实例的 `event_id`。** +- **默认做智能助理，不做表单填写机。** 能根据上下文补全的默认值就直接补全，仅在必须决策的冲突或无法唯一确定的场景下才发起询问。 +- **新建流先补默认值，编辑流先继承已定位日程信息。** +- **明确时间** → 进入 [明确时间分支](./lark-calendar-schedule-clear-time.md) +- **模糊时间或无时间信息** → 进入 [模糊时间分支](./lark-calendar-schedule-fuzzy-time.md) +- **BLOCKING REQUIREMENT**: 面临时间方案或会议室方案的选择时，必须先向用户展示选项并等待确认，禁止未经确认直接创建/更新日程。 +- **必须按顺序执行。** 不要跳过"任务类型判定""目标日程定位（编辑流）""补默认值/继承基线信息""判断时间明确性"这些前置步骤。 ## 严禁行为 -- **严禁在未读取对应子命令文档（如 `lark-calendar-room-find.md`、`lark-calendar-suggestion.md`）的情况下直接调用命令！** 必须先阅读文档掌握最新参数要求与规范。 -- **严禁在尚未判断“新建”还是“编辑”之前，就直接进入创建日程或查会议室动作。** -- **严禁把“给明天上午的‘产品发布会’加人/加群/加会议室”这类带有既有日程锚点 + 修改动词的请求，当成新建日程。** 这类请求必须先定位目标日程。 -- **严禁在编辑已有日程时跳过目标定位步骤。** 未拿到唯一的 `event_id` 前，不得调用 `+update`、也不得基于猜测时间去查会议室。 -- **严禁在用户仅要求“查会议室”但未提供明确时间时，直接调用 `+room-find`！** 必须先默认一个合理时间范围，调用 `+suggestion` 拿到候选时间块，再将时间块传给 `+room-find`。 -- **不要在用户完全没给时间时，直接反问“你想约什么时候”。** 先补一个合理时间范围，再进入 `+suggestion`。 -- **不要在“需要会议室 + 时间模糊”的场景下，先让用户只选时间。** 应先批量查出每个候选时间对应的可用会议室，再让用户一次性完成选择。 -- **不要在用户已经选中 `+suggestion` 候选时间后，再重复调用 `+freebusy`。** -- **不要在用户未明确说出城市时，仅凭园区/办公室名自动补城市。** -- **严禁在面临时间方案或会议室方案的选择时（模糊时间、无时间或需要会议室），未经用户确认就擅自创建新日程或更新既有日程。** +- **严禁在未读取对应子命令文档前直接调用命令。** +- **严禁在尚未判断"新建"还是"编辑"之前，就直接进入创建日程或查会议室动作。** +- **严禁把带有既有日程锚点 + 修改动词的请求当成新建日程。** +- **严禁在编辑已有日程时跳过目标定位步骤。** 未拿到唯一 `event_id` 前，不得调用 `+update`。 +- **严禁在面临时间/会议室方案选择时，未经用户确认就擅自创建/更新日程。** ## 适用场景 -- “帮我约个会” -- “下周找时间和 XX 开会” -- “帮我订个会议室” -- “帮我找/搜索一个可用的会议室” -- “帮我推荐一个我以前常用的会议室” -- “查询明天下午可用的会议室” -- “明天下午3点约个日程/日历” -- “把明天上午的日程‘产品发布会’加上 小明 -- “给下周一的周会换个会议室” -- “把这个日程改到明天下午，并加上学清 F201” +- "帮我约个会" / "下周找时间和 XX 开会" +- "帮我订/找/搜索一个可用会议室" +- "明天下午3点约个日程" +- "把明天上午的日程加上 小明" +- "给下周一的周会换个会议室" +- "把这个日程改到明天下午，并加上学清 F201" ## 核心概念 -- **会议室是日程的一种参与人（attendee / resource），不能脱离日程单独预定。** -- **预定或查找会议室，均需先确定时间块。** 在推荐可用会议室后，应顺势引导用户完成最终的**日程落地**操作：创建新日程，或更新既有日程。 - -## CRITICAL 约束 - -- **在调用任何具体的 CLI 子命令（如 `+room-find`、`+suggestion`、`+freebusy`、`+create`）前，必须先读取其对应的 Markdown 文档。** 禁止仅凭记忆组装命令参数，以确保符合各命令最新的业务约束和格式规范。 -- **当用户说“查会议室”“找会议室”“搜可用会议室”等，默认意图是查询会议室可用性，而不是检索会议室资源名录。** -- **必须严格按照下方【工作流】的步骤顺序完成任务。特别是单独查会议室时，若无明确时间，强制先走“模糊时间/无时间信息”分支调用 `+suggestion`。** +- **会议室是日程的一种参与人（attendee / resource），不能脱离日程单独预定。** +- **预定或查找会议室，均需先确定时间块。** +- **当用户说"查会议室""找会议室"，默认意图是查会议室可用性，不是检索会议室资源名录。** ## 任务类型判定 | 类型 | 典型语言信号 | 第一动作 | |------|--------------|----------| -| 新建日程 | “约个会”“安排一个会议”“新建日程”“帮我订个会议室开会” | 补默认值，再进入时间判断 | -| 编辑已有日程 | “给某个日程加人/删人/加群/加会议室”“把某个日程改到…”“给这场会换个会议室” | 先定位目标日程 `event_id`，再进入后续流程 | +| 新建日程 | "约个会""安排会议""新建日程""订个会议室开会" | 补默认值，再进入时间判断 | +| 编辑已有日程 | "给某日程加人/删人/加会议室""把某日程改到…""换会议室" | 先定位目标 `event_id` | -进一步规则： +规则： +- 只要同时出现**既有日程锚点**（标题、时间段、`这个日程`、`这场会`）和**修改动词**（添加、移除、改到、换），默认判定为编辑。 +- 对重复性日程的编辑，必须先定位到对应实例的 `event_id`。 -- 只要同时出现**既有日程锚点**（标题、时间段、`这个日程`、`这场会`、某次实例）和**修改动词**（添加、移除、调整、改到、换、延后、提前），默认判定为**编辑已有日程**。 -- 对重复性日程的编辑，必须先定位到对应实例的 `event_id`，不能直接拿原重复日程的 `event_id` 做更新。 - -## 工作流 - -### 1. 编辑已有日程：先定位目标日程 - -一旦判定为编辑流，必须先定位目标日程；没有 `event_id` 就不能继续后续修改动作。 +## 编辑流：先定位目标日程 定位规则： +- 优先利用用户给出的标题、日期、时间范围等锚点，通过 `+agenda`、`+search-event` 或实例视图缩小范围 +- 命中多个候选日程时，必须向用户展示候选项并要求确认 +- 重复性日程必须继续定位到该次实例的 `event_id` -- 优先利用用户给出的标题、日期、时间范围、`这个日程/这场会` 等锚点，通过 `+agenda`、`+search-event` 或实例视图缩小范围。 -- 如果命中多个候选日程，必须向用户展示候选项并要求确认，禁止自行猜测。 -- 如果是重复性日程的某一次实例，必须继续定位到该次实例的 `event_id`。 +编辑流分支路由： -编辑流分支规则： +| 编辑子场景 | 下一步 | +|-----------|--------| +| 仅增删普通参会人/群组，不改时间，不涉及会议室 | 直接 `+update`（详见 [lark-calendar-update.md](./lark-calendar-update.md)） | +| 新增会议室，不改时间 | 基于已定位日程 start/end → [明确时间分支](./lark-calendar-schedule-clear-time.md) | +| 只改时间，不涉及会议室 | 判断时间明确性 → 对应分支 | +| 既改时间，又新增/更换会议室 | 先确定最终时间 → 再查会议室 → 落地 | -- **仅增删普通参会人/群组，不改时间，也不涉及会议室**：定位完成后可直接进入最终 `+update`。 -- **新增会议室，但不改时间**：必须基于已定位日程的当前 `start/end` 作为时间块执行 `+room-find`，不能因为用户没重复说时间就退回“无时间信息”。 -- **既改时间，又新增会议室**：必须先处理时间，拿到最终候选时间块后，再基于该时间执行 `+room-find`；最终只增量添加新会议室，不自动删除已有会议室。 -- **既改时间，又更换会议室**：必须先处理时间，拿到最终候选时间块后，再基于该时间执行 `+room-find`；只有在用户明确表达“更换”时，最终才执行“移除旧会议室 + 添加新会议室”。 -- **只改时间，不涉及会议室**：沿用下方时间工作流，但最终落地必须是 `+update`，不是 `+create`。 +## 新建日程：智能推断默认值 -### 2. 新建日程：智能推断默认值 -以下信息智能推断，减少频繁询问用户： +- **标题**：根据上下文自动生成；如无法推断，默认"会议" +- **参会人**：如未指定，默认仅用户自己 +- **时长**：基于上下文推断；默认 30 分钟 +- **无时间信息**：默认推断合理区间（如"今天"或"近两天"），进入时间推荐流程，禁止询问用户 -- **标题**：根据上下文自动生成，例如“沟通对齐”“需求讨论”；如无法推断，默认为“会议” -- **参会人**：如未明确指定其他人，默认参会人仅为**用户自己** -- **时长**：基于会议类型和上下文动态推断；如无法推断，默认为 30 分钟 -- **无任何时间信息**：默认推断一个合理区间（如“今天”或“近两天”），并进入时间推荐流程，禁止询问用户 +搜索参与人出现多个结果无法唯一确定时，必须询问用户并记录长期记忆。 -当搜索特定参与人（人、群）出现多个结果无法唯一确定时，必须询问用户进行选择确认，并将该偏好记录为长期记忆，以便后续自动识别。 - -### 3. 判断时间是否明确 - -这一步判断的是**最终要落地的目标时间**，不是只看用户原句里有没有重复说时间。 +## 判断时间是否明确 时间基准规则： +- **新建流**：使用用户给出的时间，或默认补全出的时间范围 +- **编辑流且不改时间**：已定位日程的当前 `start/end` 就是明确时间 +- **编辑流且改时间**：用户想改到的新时间；若表达模糊，进入模糊时间分支 +**注意**: 在执行修改日程/会议时间的任务时，必须先获取原日程的持续时长。如果用户只提供了新的开始时间，你必须根据原时长自动计算出新的结束时间，严格保持原时长不变，禁止擅自改变原日程的时长。 -- **新建流**：使用用户给出的时间，或默认补全出的时间范围作为时间基准。 -- **编辑流且不改时间**：已定位日程的当前 `start/end` 就是时间基准。后续如需查会议室，直接使用这个明确时间块。 -- **编辑流且改时间**：用户想改到的新时间才是时间基准；若表达模糊，则进入 `+suggestion`。 +## 分支路由 -分两类处理： +| 判定结果 | 下一步读取 | +|----------|-----------| +| 明确时间 | [schedule-clear-time.md](./lark-calendar-schedule-clear-time.md) | +| 模糊时间 / 无时间信息 | [schedule-fuzzy-time.md](./lark-calendar-schedule-fuzzy-time.md) | -- **明确时间**：如“明天下午3点” -- **模糊时间**：如“明天下午”“下周找个时间” - -### 4. 明确时间 - -明确时间时，需先判断是否需要会议室，如果需要，提前查询会议室；然后判断是否有时间冲突。这里的“明确时间”既可以来自用户直接表达，也可以来自已定位日程的原始时间。 -详见 [`+room-find`](./lark-calendar-room-find.md) 与 [`+freebusy`](./lark-calendar-freebusy.md)。 - -```bash -# 1. 如果需要会议室，提前查询会议室 -lark-cli calendar +room-find \ - --slot "<start>~<end>" \ - --attendee-ids "<ids>" \ - --city "<city>" \ - --building "<building>" \ - --floor "<F2>" \ - --room-name "<room_name>" - -# 2. 查询当前用户及其他参会人忙闲 -# （如果有多名参会人，需分别调用查询：--user-id "<ou_xxx>"） -lark-cli calendar +freebusy --start "<start>" --end "<end>" -``` - -规则： - -- **参会人过多或包含群组时的处理**： - - 如果参与人过多（例如超过 5 人），为避免高耗时，仅需查询**当前用户（自己）**及少数核心人员的忙闲状态即可。 - - 如果参与人中包含**群组**，无需展开群组成员查询其忙闲状态。 -- **编辑已有日程且不改时间，只新增会议室时**：这里的 `--slot` 必须来自已定位日程的当前 `start/end`。 -- **编辑已有日程且既改时间又加会议室时**：这里的 `--slot` 必须来自候选新时间，而不是旧时间；如果用户是“新增会议室”，后续落地只做添加，不删除旧会议室。 -- **如果没有冲突**：直接让用户选择会议室（如需），然后进入最终落地操作：创建新日程，或更新既有日程 -- **如果有冲突**：必须先说明冲突情况，询问用户继续选择这个时间还是换个时间 - - **如果说换个时间**：放弃当前时间，转入【模糊时间】流程，调用 `+suggestion` 推荐多个可用时间块 - - **如果继续选择这个时间**：直接让用户选择会议室（如需），然后进入最终落地操作：创建新日程，或更新既有日程 -- 位置信息要优先拆到结构化字段：用户明确说了城市才提取 `--city`；`--building` 不要再重复携带城市前缀。 -- 参数归类顺序应为：`city/building/floor` > `floor + room-name` 复合表达 > `room-name`。像 `2L`、`2F` 这类更像楼层或区域定位的短词，优先视为 `--floor`，不要默认当作 `--room-name`。像 `学清2层` 这种表达，通常拆为 `--building "学清"` 与 `--floor "F2"`。 -- 会议室名要做轻量归一化：`木星会议室` -> `--room-name "木星"`；`会议室 02` / `02会议室` -> `--room-name "02"`。 -- 对 `F3-05` / `F5-07` / `3楼-08` 这类复合表达，若能稳定识别楼层与会议室号，应优先提取为 `--floor + --room-name`，不要把整段直接退化成 `--room-name`。 - -### 5. 模糊时间或无时间信息 - -先调用： -详见 [`+suggestion`](./lark-calendar-suggestion.md)；若需要会议室，再结合 [`+room-find`](./lark-calendar-room-find.md)。 - -```bash -lark-cli calendar +suggestion \ - --start "<range_start>" \ - --end "<range_end>" \ - --attendee-ids "<ids>" \ - --duration-minutes <n> \ - --event-rrule "<rrule>" -``` - -规则： - -- 若用户完全没有提供时间信息，应先默认一个合理区间后再调用 `+suggestion` -- 编辑流中，若用户表达的是“改到明天下午”“下周找个时间再约”这类模糊新时间，则基于用户期望的新时间范围调用 `+suggestion`；不要继续沿用旧时间。 -- **不需要会议室**：获取多个推荐时间块后，直接向用户展示候选时间，用户确认后进入最终落地操作：创建新日程，或更新既有日程。 -- **需要会议室**：获取多个候选时间块后，**不要急于让用户选时间**。先将这些时间块一次性交给 `calendar +room-find` 批量查询可用会议室，然后将【候选时间】与【对应的可用会议室列表】结构化分行展示，让用户一次性完成选择。（**注意：即使用户最初只说“查会议室”，且未带时间，也必须强制走到这一步，先 suggestion 再 room-find**）。 -- 用户一旦选择了 `+suggestion` 返回的时间块，**无需再次调用 `+freebusy`** - -### 6. 模糊语义消解与长期记忆构建 - -针对用户专属的时间表达习惯或存在歧义的时间场景，严禁主观臆断。典型例子包括： - -- “上班后” -- “下班前” -- 未明确上下午的 12 小时制时间表达 - -处理规则： - -- 应主动澄清真实意图，而不是自行猜测 -- 当用户给出澄清后，应将这类个性化定义沉淀为长期偏好，推动后续直接理解类似表达 - -### 7. 重复性日程 - -若当前会议为重复性日程，调用 `+room-find` 时需携带 `--event-rrule`。 - -必须检查返回中的： - -- `reserve_until_time` - -若候选会议室的可预约上限早于重复规则覆盖范围，**不要直接按原规则落地日程**。应： - -- 向用户明确说明该会议室最长可约至何时。 -- 若用户确认继续选用该会议室，你必须**自动将日程的重复规则结束时间缩短**至该 `reserve_until_time`，以防止会议室预约失败。 - -### 8. 落地日程变更 +## 落地日程变更 用户确认后调用： -如果是新建会议，详见 [`+create`](./lark-calendar-create.md)。 -如果是更新既有日程，详见 [`+update`](./lark-calendar-update.md)。必须先定位目标 `event_id`，再按用户意图用 `+update` 独立执行字段更新、添加参会人/会议室、移除参会人/会议室，或组合这些动作。若用户意图是“新增会议室”，默认仅追加 `room_id`，不移除已有会议室。 +- 新建 → [`+create`](./lark-calendar-create.md) +- 编辑 → [`+update`](./lark-calendar-update.md) ```bash lark-cli calendar +create \ @@ -214,52 +103,20 @@ lark-cli calendar +update \ --start "<start>" \ --end "<end>" \ --add-attendee-ids "omm_new_room" - -# 仅当用户明确要求“更换会议室”时，才同时移除旧会议室并添加新会议室 -lark-cli calendar +update \ - --event-id "<event_id>" \ - --remove-attendee-ids "omm_old_room" \ - --add-attendee-ids "omm_new_room" ``` -规则： -- 新建日程时，可使用 `+create` -- 更新既有日程时，优先使用 `+update`。改时间/标题/描述、添加参会人/会议室、移除参会人/会议室可以分别独立执行； -- 编辑流必须始终沿用前面定位得到的目标 `event_id`；禁止在最后一步重新按标题猜测一次目标日程。 -- 编辑流中如果只是新增群组或普通参会人，不涉及时间和会议室，可直接 `+update --add-attendee-ids ...`。 -- 编辑流中如果是“新增会议室但不改时间”，必须先基于目标日程原始时间查到可用会议室，再 `+update --add-attendee-ids "<room_id>"`；默认保留已有会议室。 -- 编辑流中如果是“既改时间又新增会议室”，顺序必须是：先确定最终时间，再查会议室，最后一次性 `+update` 时间与新增会议室；默认保留已有会议室。 -- 编辑流中如果是“既改时间又更换会议室”，顺序必须是：先确定最终时间，再查会议室，最后一次性 `+update` 时间、移除旧会议室并添加新会议室。 -- 需要会议室时，将选中的 `room_id` 写入最终落地请求的参与人列表 -- 展示会议室候选时，必须保留 CLI/API 返回的完整 `room_name` 原值；允许附加“推断说明”，但禁止用摘要名、楼层及会议室号、容量/视频标签重组后的名称替换原值 - -## 用户展示建议 - -当向用户展示多个时间块及对应的多个会议室时，**必须使用结构化清晰的格式排版**。**严禁将时间与会议室名称放在同一行展示**，必须分行并使用编号列表呈现可用会议室，严禁将所有信息揉成一团纯文本堆叠。 - -**推荐展示格式参考：** - -```text -## 2026-03-27 周五 - -[选项 1] 14:00 - 15:00（参会人均空闲） - 可用会议室： - 1. 学清嘉创大厦B座-F2-02🎦(7人) - 2. 学清嘉创大厦B座-F2-05🎦(10人) - -[选项 2] 16:00 - 17:00（参会人均空闲） - 可用会议室： - 1. 学清嘉创大厦B座-F3-01🎦(6人) - 2. 学清嘉创大厦B座-F3-06🎦(8人) - -💡 请回复您倾向的选项编号以及对应的会议室序号，我来为您完成预定。 -``` +落地规则： +- 编辑流必须始终沿用前面定位得到的目标 `event_id`；禁止在最后一步重新猜测目标日程 +- 编辑流中"新增会议室"默认仅追加 `room_id`，不移除已有会议室 +- 仅当用户明确说"更换会议室"时，才同时 `--remove-attendee-ids` 旧 + `--add-attendee-ids` 新 +- 需要会议室时，将选中的 `room_id` 写入参与人列表 ## 参考 +- [lark-calendar-schedule-clear-time.md](./lark-calendar-schedule-clear-time.md) +- [lark-calendar-schedule-fuzzy-time.md](./lark-calendar-schedule-fuzzy-time.md) - [lark-calendar-room-find.md](./lark-calendar-room-find.md) -- [lark-calendar-freebusy.md](./lark-calendar-freebusy.md) - [lark-calendar-suggestion.md](./lark-calendar-suggestion.md) - [lark-calendar-create.md](./lark-calendar-create.md) -- [lark-shared](../../lark-shared/SKILL.md) -- [lark-calendar](../SKILL.md) +- [lark-calendar-update.md](./lark-calendar-update.md) +- [SKILL.md](../SKILL.md) diff --git a/skills/lark-calendar/references/lark-calendar-search-event.md b/skills/lark-calendar/references/lark-calendar-search-event.md deleted file mode 100644 index e2addb5cb..000000000 --- a/skills/lark-calendar/references/lark-calendar-search-event.md +++ /dev/null @@ -1,29 +0,0 @@ - -# calendar +search-event - -按关键词、时间范围和参会人搜索日历日程。只读。 - -## 命令 - -```bash -# 按关键词 -lark-cli calendar +search-event --query "周会" - -# 按时间范围（ISO 8601 或 YYYY-MM-DD） -lark-cli calendar +search-event --start "2026-04-20T00:00:00+08:00" --end "2026-04-27T23:59:59+08:00" - -# 按参会人（自动识别 ou_ 用户 / oc_ 群聊 / omm_ 会议室前缀） -lark-cli calendar +search-event --attendee-ids "ou_user1,oc_chat1,omm_room1" - -# 组合 -lark-cli calendar +search-event --query "周会" --start 2026-04-20 --end 2026-04-27 --attendee-ids "ou_user1" -``` - -## 输出字段 - -`items` 列表每条返回 `event_id` / `summary` / `start` / `end` / `is_all_day` / `app_link`；外层有 `has_more`、`page_token`。**仅返回基础字段，要拿日程详情用 `calendar events get`。** - -## 注意事项 - -- 分页：`has_more=true` 时持续用 `page_token` 翻页直到 false，不要遗漏；`page-size` 最大 30。 -- 已结束的会议优先用 `vc +search`——日历不收录"即时会议"，只查日程会漏。 diff --git a/skills/lark-calendar/references/lark-calendar-suggestion.md b/skills/lark-calendar/references/lark-calendar-suggestion.md index 1606ebd4c..102568af9 100644 --- a/skills/lark-calendar/references/lark-calendar-suggestion.md +++ b/skills/lark-calendar/references/lark-calendar-suggestion.md @@ -1,6 +1,5 @@ # calendar +suggestion -> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)。 根据非明确时间或一段时间范围，推荐多个可用时间块方案。帮助用户解决协调时间的难题。 @@ -8,8 +7,6 @@ - ✅ **当用户需求涉及寻找时间块，且时间未完全确定**（如`今天`、`近三天`、`本周`、`下午`, `无时间描述`）时，调用此工具来获取推荐时间块给用户选择（包括但不限于预约日程）。 - ❌ **当用户已经明确了具体的时间点**（如`今天下午3点`），则**不需要**调用此工具 -需要的scopes: ["calendar:calendar.free_busy:read"] - ## 命令 ```bash @@ -121,5 +118,4 @@ lark-cli calendar +suggestion \ ## 参考 - [lark-calendar-create](lark-calendar-create.md) — 创建日程 -- [lark-calendar-freebusy](lark-calendar-freebusy.md) — 查询忙闲时段和rsvp状态 -- [lark-calendar](../SKILL.md) — 日历完整 API \ No newline at end of file +- [lark-calendar](../SKILL.md) — skill 入口与路由 diff --git a/skills/lark-calendar/references/lark-calendar-update.md b/skills/lark-calendar/references/lark-calendar-update.md index cd5ee90e1..9d879e08d 100644 --- a/skills/lark-calendar/references/lark-calendar-update.md +++ b/skills/lark-calendar/references/lark-calendar-update.md @@ -1,13 +1,10 @@ # calendar +update -> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 更新既有日程字段，或独立增量添加/移除参会人和会议室。 `+update` 支持三类互相独立的动作：更新日程字段、添加参会人/会议室、移除参会人/会议室。它们可以单独执行，也可以在同一次命令中组合执行。 -需要的 scopes: ["calendar:calendar.event:update"] - ## 推荐命令 ```bash @@ -66,8 +63,8 @@ lark-cli calendar +update \ - 如需替换某个参与人、群组或会议室，使用 `--remove-attendee-ids <旧ID>` + `--add-attendee-ids <新ID>`。 - 会议室是 resource attendee，必须使用 `omm_` ID 添加到参会人列表，不能脱离日程单独预定。 - 更新重复性日程时，必须先确定操作范围（仅此次/全部/此次及后续），然后按 [重复性日程操作规范](lark-calendar-recurring.md) 执行。 -- 如果需要验证更新结果，等待至少 2 秒后再查询，避免同步延迟导致读到旧数据。 - 当同一次命令组合多个动作时，执行顺序为“日程字段 -> 移除参会人 -> 添加参会人”。若中途失败，不会自动回滚已成功步骤；错误信息会说明已完成的步骤。 +**⚠️ 高风险操作**: 修改时间时必须先读取原日程时长并计算新 end。如果 end 计算错误，会导致日程时长变化，用户会直接感知，禁止擅自改变原日程的时长。 ## 高级用法（完整 API 命令） @@ -98,8 +95,6 @@ lark-cli calendar +update \ ## 参考 -- [lark-calendar](../SKILL.md) -- 日历全部命令 -- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数 +- [lark-calendar](../SKILL.md) -- skill 入口与路由 - [lark-calendar-schedule-meeting](lark-calendar-schedule-meeting.md) -- 预约/改约会议与会议室工作流 - [lark-calendar-room-find](lark-calendar-room-find.md) -- 查找可用会议室 -- [lark-calendar-freebusy](lark-calendar-freebusy.md) -- 查询忙闲 diff --git a/skills/lark-minutes/references/lark-minutes-download.md b/skills/lark-minutes/references/lark-minutes-download.md index b2bac61f7..7b8de1697 100644 --- a/skills/lark-minutes/references/lark-minutes-download.md +++ b/skills/lark-minutes/references/lark-minutes-download.md @@ -1,7 +1,6 @@ # minutes +download -> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 下载妙记的音视频媒体文件到本地，或获取有效期 1 天的下载链接。只读操作。 @@ -134,4 +133,3 @@ API 限流 5 次/秒，批量下载时需注意控制频率。 - [lark-minutes](../SKILL.md) — 妙记全部命令 - [lark-minutes-detail](lark-minutes-detail.md) — 妙记详情与 AI 产物查询 -- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数 diff --git a/skills/lark-minutes/references/lark-minutes-search.md b/skills/lark-minutes/references/lark-minutes-search.md index ecbd4ce07..05d3b4904 100644 --- a/skills/lark-minutes/references/lark-minutes-search.md +++ b/skills/lark-minutes/references/lark-minutes-search.md @@ -1,6 +1,5 @@ # minutes +search -> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 搜索妙记列表，支持关键词、所有者、参与者以及时间范围等多条件过滤。所有者与参与者都支持传入多个 open\_id，也支持传入 `me` 表示当前用户。只读操作，不修改任何妙记数据。 @@ -199,6 +198,5 @@ lark-cli minutes +detail --minute-tokens <minute_token> --summary - [lark-minutes](../SKILL.md) -- 妙记相关命令 - [lark-minutes-detail](lark-minutes-detail.md) -- 基于 `minute_token` 获取逐字稿、总结、待办、章节等产物 -- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数 - [lark-vc](../../lark-vc/SKILL.md) -- 视频会议全部命令 diff --git a/skills/lark-minutes/references/lark-minutes-speaker-replace.md b/skills/lark-minutes/references/lark-minutes-speaker-replace.md index 9cf982dc0..82492ac13 100644 --- a/skills/lark-minutes/references/lark-minutes-speaker-replace.md +++ b/skills/lark-minutes/references/lark-minutes-speaker-replace.md @@ -1,6 +1,5 @@ # minutes +speaker-replace -> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 替换妙记逐字稿中的说话人身份：把妙记逐字稿里"原说话人"对应的所有发言段，重新归属到"新说话人"。常用于解决妙记自动识别错说话人，或需要把外部/非飞书说话人改绑到正确飞书用户的场景。 @@ -106,4 +105,3 @@ Agent 必须先 `lark-cli api GET .../speakerlist`，再 `+speaker-replace`；`- ## 参考 - [lark-minutes](../SKILL.md) -- 妙记相关功能说明 -- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数 diff --git a/skills/lark-minutes/references/lark-minutes-summary.md b/skills/lark-minutes/references/lark-minutes-summary.md index a1fd8e8d3..29b03d397 100644 --- a/skills/lark-minutes/references/lark-minutes-summary.md +++ b/skills/lark-minutes/references/lark-minutes-summary.md @@ -1,6 +1,5 @@ # minutes +summary -> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 替换妙记的 AI 总结内容。写操作，会覆盖当前总结。 @@ -119,4 +118,3 @@ lark-cli minutes +summary --minute-token obcnxxxxxxxxxxxxxxxxxxxx --summary @sum - [lark-minutes](../SKILL.md) — 妙记全部命令 - [minutes +todo](lark-minutes-todo.md) — 替换待办项 - [minutes +detail](lark-minutes-detail.md) — 读取总结、待办等 AI 产物 -- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数 diff --git a/skills/lark-minutes/references/lark-minutes-todo.md b/skills/lark-minutes/references/lark-minutes-todo.md index de98c75d8..d86bcd6d6 100644 --- a/skills/lark-minutes/references/lark-minutes-todo.md +++ b/skills/lark-minutes/references/lark-minutes-todo.md @@ -2,7 +2,6 @@ > **路由**：本命令操作**妙记内的 AI 待办**，不是飞书任务（Task）。用户说「在妙记里新建待办」时**必须**用本命令，**禁止**走 `lark-cli task` / `tasklists list` / `task +create`。详见 [lark-minutes/SKILL.md](../SKILL.md) 第 6 节。 -> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 对妙记中的待办做新增 / 更新 / 删除（单条或批量）。写操作。 @@ -135,4 +134,3 @@ lark-cli minutes +todo --minute-token obcnxxxxxxxxxxxxxxxxxxxx --operation add - - [lark-minutes](../SKILL.md) - [minutes +summary](lark-minutes-summary.md) - [minutes +detail](lark-minutes-detail.md) -- [lark-shared](../../lark-shared/SKILL.md) diff --git a/skills/lark-minutes/references/lark-minutes-update.md b/skills/lark-minutes/references/lark-minutes-update.md index 780066093..7baa2948d 100644 --- a/skills/lark-minutes/references/lark-minutes-update.md +++ b/skills/lark-minutes/references/lark-minutes-update.md @@ -1,6 +1,5 @@ # minutes +update -> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 修改飞书妙记的标题（topic）。 @@ -38,4 +37,3 @@ lark-cli minutes +update --minute-token xxx --topic "周会纪要 2026-05-18" ## 参考 - [lark-minutes](../SKILL.md) -- 妙记相关功能说明 -- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数 diff --git a/skills/lark-minutes/references/lark-minutes-upload.md b/skills/lark-minutes/references/lark-minutes-upload.md index 0142df6d8..29c96107b 100644 --- a/skills/lark-minutes/references/lark-minutes-upload.md +++ b/skills/lark-minutes/references/lark-minutes-upload.md @@ -1,6 +1,5 @@ # minutes +upload -> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 上传音视频文件到飞书妙记并生成妙记（Minute）。 @@ -31,12 +30,12 @@ ``` - 命令执行成功后，将返回生成的妙记链接 `minute_url`。 -3. **如需纪要 / 逐字稿 / 文字稿 / 撰写文字，继续提取 `minute_token` 调用 `minutes +detail`** - - 从返回的 `minute_url` 中提取路径最后一段，得到 `minute_token`。 - - 如果用户要的是纪要、逐字稿、文字稿、撰写文字、总结、待办或章节，继续调用： +3. **如需纪要 / 逐字稿 / 文字稿 / 撰写文字，使用返回的 `minute_token` 调用 `minutes +detail`** + - 如果用户要的是纪要、逐字稿、文字稿、撰写文字、总结、待办或章节，使用上一步返回的 `minute_token` 继续调用： ```bash - lark-cli minutes +detail --minute-tokens <minute_token> --summary --todo --chapter --keyword --transcript + lark-cli minutes +detail --minute-tokens <minute_token> --wait-ready --summary --todo --chapter --keyword --transcript ``` + - `--wait-ready` 参数表示等待妙记生成完毕后再获取产物，上传后立即读取详情时必须加上此参数。 - `minutes +detail --minute-tokens` 会返回妙记产物（总结、待办、章节、关键词、逐字稿）；必要时还会把逐字稿落地到本地文件。 > **异步生成提示**：API 会立即返回 `minute_url`，但妙记可能仍在异步生成中，您可以直接通过该妙记链接查看当前的处理状态和转写结果。 @@ -47,8 +46,8 @@ # 通过已上传到云空间（云盘/云存储）的 file_token 生成妙记 lark-cli minutes +upload --file-token boxcnxxxxxxxxxxxxxxxx -# 通过 minute_token 继续获取妙记产物（--summary --todo --chapter --keyword --transcript 按需传入） -lark-cli minutes +detail --minute-tokens obcnxxxxxxxxxxxxxxxx --summary +# 上传后立即获取妙记产物，需加 --wait-ready 等待生成完毕（--summary --todo --chapter --keyword --transcript 按需传入） +lark-cli minutes +detail --minute-tokens obcnxxxxxxxxxxxxxxxx --wait-ready --summary ``` ## 参数 @@ -81,7 +80,7 @@ lark-cli minutes +detail --minute-tokens obcnxxxxxxxxxxxxxxxx --summary 1. 使用 `lark-cli drive +upload --file <path>` 上传本地音视频文件到云空间（云盘/云存储） 2. 从返回结果中取出 `file_token` 3. 调用 `lark-cli minutes +upload --file-token <file_token>` 生成妙记 -4. 如果目标是纪要、逐字稿、文字稿、撰写文字、总结、待办或章节，再从 `minute_url` 提取 `minute_token`，继续调用 `lark-cli minutes +detail --minute-tokens <minute_token>` +4. 如果目标是纪要、逐字稿、文字稿、撰写文字、总结、待办或章节，使用返回的 `minute_token`，继续调用 `lark-cli minutes +detail --minute-tokens <minute_token> --wait-ready` > **边界说明**：`minutes +upload` 本身只负责把文件转成妙记并返回 `minute_url`。纪要内容、逐字稿、文字稿、撰写文字、总结、待办、章节属于后续产物获取，应由 [minutes +detail](lark-minutes-detail.md) 承接。 @@ -89,16 +88,17 @@ lark-cli minutes +detail --minute-tokens obcnxxxxxxxxxxxxxxxx --summary ```json { - "minute_url": "http(s)://<host>/minutes/<minute-token>" + "minute_url": "http(s)://<host>/minutes/<minute-token>", + "minute_token": "<minute-token>" } ``` | 字段 | 说明 | |------|------| | `minute_url` | 生成的妙记访问链接 | +| `minute_token` | 从 `minute_url` 提取出的妙记 Token，可直接传给 `minutes +detail --minute-tokens` | ## 参考 - [lark-minutes](../SKILL.md) -- 妙记相关功能说明 - [drive +upload](../../lark-drive/references/lark-drive-upload.md) -- 上传文件到云空间（云盘/云存储） -- [lark-shared](../../lark-shared/SKILL.md) -- 认证和全局参数 diff --git a/skills/lark-vc/references/lark-vc-recording.md b/skills/lark-vc/references/lark-vc-recording.md index 5f52e2480..1d6d58ee1 100644 --- a/skills/lark-vc/references/lark-vc-recording.md +++ b/skills/lark-vc/references/lark-vc-recording.md @@ -1,7 +1,6 @@ # vc +recording -> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。 通过 meeting_id 或 calendar_event_id 查询对应的 minute_token。这是 VC 域和 Minutes 域之间的桥梁命令。只读操作。 @@ -151,4 +150,3 @@ lark-cli minutes +download --minute-tokens <minute_token> - [lark-vc](../SKILL.md) — 视频会议全部命令 - [lark-vc-search](lark-vc-search.md) — 搜索历史会议（获取 meeting_id） - [lark-minutes-detail](../../lark-minutes/references/lark-minutes-detail.md) — 获取会议纪要 -- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数