feat: support vc agent active meetings

2026-07-08 10:08:02 +08:00 · 2026-06-15 14:51:18 +08:00
parent a0e83c7e59
commit dd95f5eb4a
12 changed files with 534 additions and 35 deletions
--- a/shortcuts/vc/shortcuts.go
+++ b/shortcuts/vc/shortcuts.go
@@ -13,6 +13,7 @@ func Shortcuts() []common.Shortcut {
 		VCRecording,
 		VCMeetingJoin,
 		VCMeetingLeave,
+		VCMeetingListActive,
 		VCMeetingEvents,
 	}
 }
--- a/shortcuts/vc/vc_meeting_events.go
+++ b/shortcuts/vc/vc_meeting_events.go
@@ -48,7 +48,7 @@ var VCMeetingEvents = common.Shortcut{
 	Description: "List bot meeting events by meeting ID",
 	Risk:        "read",
 	Scopes:      []string{"vc:meeting.meetingevent:read"},
-	AuthTypes:   []string{"user"},
+	AuthTypes:   []string{"user", "bot"},
 	HasFormat:   true,
 	Flags: []common.Flag{
 		{Name: "meeting-id", Required: true, Desc: "meeting ID to query"},
--- a/shortcuts/vc/vc_meeting_events_test.go
+++ b/shortcuts/vc/vc_meeting_events_test.go
@@ -818,7 +818,7 @@ func TestVCShortcuts_RegistersMeetingAgentCommands(t *testing.T) {
 	for _, shortcut := range got {
 		commands = append(commands, shortcut.Command)
 	}
-	want := []string{"+search", "+notes", "+recording", "+meeting-join", "+meeting-leave", "+meeting-events"}
+	want := []string{"+search", "+notes", "+recording", "+meeting-join", "+meeting-leave", "+meeting-list-active", "+meeting-events"}
 	if !reflect.DeepEqual(commands, want) {
 		t.Fatalf("shortcut commands = %#v, want %#v", commands, want)
 	}
--- a/shortcuts/vc/vc_meeting_join.go
+++ b/shortcuts/vc/vc_meeting_join.go
@@ -28,7 +28,7 @@ var VCMeetingJoin = common.Shortcut{
 	Description: "Join a meeting by meeting number (bot join)",
 	Risk:        "write",
 	Scopes:      []string{"vc:meeting.bot.join:write"},
-	AuthTypes:   []string{"user"},
+	AuthTypes:   []string{"user", "bot"},
 	HasFormat:   true,
 	Flags: []common.Flag{
 		{Name: "meeting-number", Required: true, Desc: "meeting number to join"},
--- a/shortcuts/vc/vc_meeting_leave.go
+++ b/shortcuts/vc/vc_meeting_leave.go
@@ -20,7 +20,7 @@ var VCMeetingLeave = common.Shortcut{
 	Description: "Leave a meeting by meeting ID",
 	Risk:        "write",
 	Scopes:      []string{"vc:meeting.bot.join:write"},
-	AuthTypes:   []string{"user"},
+	AuthTypes:   []string{"user", "bot"},
 	HasFormat:   true,
 	Flags: []common.Flag{
 		{Name: "meeting-id", Required: true, Desc: "meeting ID to leave"},
--- a/shortcuts/vc/vc_meeting_list_active.go
+++ b/shortcuts/vc/vc_meeting_list_active.go
@@ -0,0 +1,113 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package vc
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const vcMeetingListActiveAPIPath = "/open-apis/vc/v1/bots/user_active_meeting"
+
+// VCMeetingListActive lists meetings the current or target user is actively in.
+var VCMeetingListActive = common.Shortcut{
+	Service:     "vc",
+	Command:     "+meeting-list-active",
+	Description: "List active meetings for the current identity or target user",
+	Risk:        "read",
+	Scopes:      []string{"vc:meeting.active:read"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "user-id", Desc: "target user ID when using bot identity"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return validateMeetingListActiveUserID(runtime)
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		params, err := buildMeetingListActiveParams(runtime)
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		dryRun := common.NewDryRunAPI().GET(vcMeetingListActiveAPIPath)
+		if len(params) > 0 {
+			dryRun.Params(params)
+		}
+		return dryRun
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		params, err := buildMeetingListActiveParams(runtime)
+		if err != nil {
+			return err
+		}
+		data, err := runtime.CallAPITyped(http.MethodGet, vcMeetingListActiveAPIPath, params, nil)
+		if err != nil {
+			return err
+		}
+		if data == nil {
+			data = map[string]interface{}{}
+		}
+		meetings := common.GetSlice(data, "meetings")
+		runtime.OutFormat(data, &output.Meta{Count: len(meetings)}, func(w io.Writer) {
+			if len(meetings) == 0 {
+				fmt.Fprintln(w, "No active meetings.")
+				return
+			}
+			for i, raw := range meetings {
+				meeting, _ := raw.(map[string]interface{})
+				if meeting == nil {
+					continue
+				}
+				if i > 0 {
+					fmt.Fprintln(w)
+				}
+				title := common.GetString(meeting, "meeting_title")
+				if title == "" {
+					title = "Untitled meeting"
+				}
+				fmt.Fprintf(w, "%s\n", title)
+				if id := common.GetString(meeting, "meeting_id"); id != "" {
+					fmt.Fprintf(w, "  Meeting ID:  %s\n", id)
+				}
+				if no := common.GetString(meeting, "meeting_no"); no != "" {
+					fmt.Fprintf(w, "  Meeting No:  %s\n", no)
+				}
+			}
+		})
+		return nil
+	},
+}
+
+func validateMeetingListActiveUserID(runtime *common.RuntimeContext) error {
+	if !runtime.IsBot() {
+		return nil
+	}
+	userID := strings.TrimSpace(runtime.Str("user-id"))
+	if userID == "" {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--user-id is required when --as bot").WithParam("--user-id")
+	}
+	if _, err := common.ValidateUserIDTyped("--user-id", userID); err != nil {
+		return err
+	}
+	return nil
+}
+
+func buildMeetingListActiveParams(runtime *common.RuntimeContext) (map[string]interface{}, error) {
+	if err := validateMeetingListActiveUserID(runtime); err != nil {
+		return nil, err
+	}
+	params := map[string]interface{}{}
+	if runtime.IsBot() {
+		userID := strings.TrimSpace(runtime.Str("user-id"))
+		params["user_id"] = userID
+	}
+	return params, nil
+}
--- a/shortcuts/vc/vc_meeting_test.go
+++ b/shortcuts/vc/vc_meeting_test.go
@@ -8,6 +8,7 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"net/http"
 	"strings"
 	"testing"

@@ -15,6 +16,7 @@ import (

 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
 	"github.com/larksuite/cli/shortcuts/common"
 )
@@ -589,6 +591,270 @@ func TestMeetingLeave_Execute_APIError(t *testing.T) {
 	}
 }

+func TestMeetingListActive_DryRun_UserIdentity(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := mountAndRun(t, VCMeetingListActive, []string{
+		"+meeting-list-active", "--dry-run", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	if !strings.Contains(out, "/open-apis/vc/v1/bots/user_active_meeting") {
+		t.Errorf("dry-run should include API path, got: %s", out)
+	}
+	if strings.Contains(out, "user_id") {
+		t.Errorf("user identity should not send user_id by default, got: %s", out)
+	}
+}
+
+func TestMeetingListActive_DryRun_UserIdentityIgnoresUserID(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := mountAndRun(t, VCMeetingListActive, []string{
+		"+meeting-list-active", "--dry-run", "--as", "user", "--user-id", "not-open-id",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if strings.Contains(stdout.String(), "user_id") {
+		t.Errorf("user identity should not send user_id, got: %s", stdout.String())
+	}
+}
+
+func TestMeetingListActive_Execute_UserIdentityIgnoresInvalidUserID(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	var gotUserID string
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/vc/v1/bots/user_active_meeting",
+		OnMatch: func(req *http.Request) {
+			gotUserID = req.URL.Query().Get("user_id")
+		},
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{"meetings": []interface{}{}},
+		},
+	})
+
+	err := mountAndRun(t, VCMeetingListActive, []string{
+		"+meeting-list-active", "--as", "user", "--user-id", "not-open-id", "--format", "json",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotUserID != "" {
+		t.Fatalf("user identity should not send user_id, got %q", gotUserID)
+	}
+}
+
+func TestMeetingListActive_Validate_BotRequiresUserID(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := mountAndRun(t, VCMeetingListActive, []string{"+meeting-list-active", "--as", "bot"}, f, nil)
+	if err == nil {
+		t.Fatal("expected error when --as bot omits --user-id")
+	}
+	assertMeetingListActiveUserIDValidationError(t, err)
+}
+
+func TestMeetingListActive_Validate_UserIDOpenIDFormat(t *testing.T) {
+	f, _, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := mountAndRun(t, VCMeetingListActive, []string{
+		"+meeting-list-active", "--as", "bot", "--user-id", "300",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected error for non-open_id user-id")
+	}
+	assertMeetingListActiveUserIDValidationError(t, err)
+}
+
+func TestMeetingListActive_Execute_BotPassesUserID(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	var gotUserID string
+	stub := &httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/vc/v1/bots/user_active_meeting",
+		OnMatch: func(req *http.Request) {
+			gotUserID = req.URL.Query().Get("user_id")
+		},
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"meetings": []interface{}{
+					map[string]interface{}{
+						"meeting_id":    "9001",
+						"meeting_no":    "123456789",
+						"meeting_title": "Standup",
+					},
+				},
+			},
+		},
+	}
+	reg.Register(stub)
+
+	err := mountAndRun(t, VCMeetingListActive, []string{
+		"+meeting-list-active", "--user-id", "ou_300",
+		"--format", "json", "--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if gotUserID != "ou_300" {
+		t.Fatalf("user_id query = %q, want ou_300", gotUserID)
+	}
+
+	var resp map[string]any
+	if err := json.Unmarshal(stdout.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to parse stdout: %v", err)
+	}
+	data, _ := resp["data"].(map[string]any)
+	meetings, _ := data["meetings"].([]any)
+	if len(meetings) != 1 {
+		t.Fatalf("meetings = %d, want 1 (envelope: %s)", len(meetings), stdout.String())
+	}
+}
+
+func TestMeetingListActive_DryRun_BotValidationErrorEnvelope(t *testing.T) {
+	cmd := &cobra.Command{Use: "+meeting-list-active"}
+	cmd.Flags().String("user-id", "", "")
+	runtime := common.TestNewRuntimeContextWithIdentity(cmd, defaultConfig(), core.AsBot)
+
+	dry := VCMeetingListActive.DryRun(context.Background(), runtime)
+	if dry == nil {
+		t.Fatal("DryRun returned nil")
+	}
+	raw, err := json.Marshal(dry)
+	if err != nil {
+		t.Fatalf("failed to marshal dry-run output: %v", err)
+	}
+	got := string(raw)
+	if !strings.Contains(got, "--user-id") {
+		t.Fatalf("dry-run error = %q, want user-id validation", got)
+	}
+}
+
+func TestMeetingListActive_DryRun_BotSendsUserID(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+	err := mountAndRun(t, VCMeetingListActive, []string{
+		"+meeting-list-active", "--dry-run", "--as", "bot", "--user-id", "ou_300",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "user_id") || !strings.Contains(stdout.String(), "ou_300") {
+		t.Fatalf("dry-run should include user_id=ou_300, got: %s", stdout.String())
+	}
+}
+
+func TestMeetingListActive_Execute_ValidationError(t *testing.T) {
+	cmd := &cobra.Command{Use: "+meeting-list-active"}
+	cmd.Flags().String("user-id", "", "")
+	runtime := common.TestNewRuntimeContextWithIdentity(cmd, defaultConfig(), core.AsBot)
+
+	err := VCMeetingListActive.Execute(context.Background(), runtime)
+	if err == nil {
+		t.Fatal("expected validation error")
+	}
+	assertMeetingListActiveUserIDValidationError(t, err)
+}
+
+func TestMeetingListActive_ExecutePretty_Empty(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/vc/v1/bots/user_active_meeting",
+		Body:   map[string]interface{}{"code": 0, "msg": "ok"},
+	})
+
+	err := mountAndRun(t, VCMeetingListActive, []string{
+		"+meeting-list-active", "--format", "pretty", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "No active meetings.") {
+		t.Fatalf("pretty output = %q, want empty-state message", stdout.String())
+	}
+}
+
+func TestMeetingListActive_ExecutePretty_MultipleMeetings(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/vc/v1/bots/user_active_meeting",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"meetings": []interface{}{
+					map[string]interface{}{
+						"meeting_id":    "9001",
+						"meeting_no":    "123456789",
+						"meeting_title": "Standup",
+					},
+					"ignored",
+					map[string]interface{}{},
+				},
+			},
+		},
+	})
+
+	err := mountAndRun(t, VCMeetingListActive, []string{
+		"+meeting-list-active", "--format", "pretty", "--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	for _, want := range []string{"Standup", "Meeting ID:  9001", "Meeting No:  123456789", "Untitled meeting"} {
+		if !strings.Contains(out, want) {
+			t.Fatalf("pretty output missing %q: %s", want, out)
+		}
+	}
+}
+
+func TestMeetingListActive_Execute_APIError(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/vc/v1/bots/user_active_meeting",
+		Body:   map[string]interface{}{"code": 121005, "msg": "no permission"},
+	})
+
+	err := mountAndRun(t, VCMeetingListActive, []string{
+		"+meeting-list-active", "--format", "json", "--as", "user",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected API error")
+	}
+	if p, ok := errs.ProblemOf(err); !ok || p.Category != errs.CategoryAuthorization {
+		t.Fatalf("error problem = (%+v, %t), want authorization problem", p, ok)
+	} else if p.Subtype != errs.SubtypePermissionDenied {
+		t.Fatalf("error subtype = %q, want %q", p.Subtype, errs.SubtypePermissionDenied)
+	}
+}
+
+func assertMeetingListActiveUserIDValidationError(t *testing.T, err error) {
+	t.Helper()
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T: %v", err, err)
+	}
+	if p.Category != errs.CategoryValidation {
+		t.Errorf("Category = %q, want %q", p.Category, errs.CategoryValidation)
+	}
+	if p.Subtype != errs.SubtypeInvalidArgument {
+		t.Errorf("Subtype = %q, want %q", p.Subtype, errs.SubtypeInvalidArgument)
+	}
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
+	}
+	if ve.Param != "--user-id" {
+		t.Errorf("Param = %q, want %q", ve.Param, "--user-id")
+	}
+}
+
 // ---------------------------------------------------------------------------
 // Typed error lock assertions
 // ---------------------------------------------------------------------------
--- a/skills/lark-vc-agent/SKILL.md
+++ b/skills/lark-vc-agent/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: lark-vc-agent
 version: 1.0.0
-description: "飞书视频会议：让机器人代当前用户加入/离开正在进行的会议，并读取会议期间的实时事件（参会人加入与离开、发言、聊天、屏幕共享等）。1. 用户提供 9 位会议号、要求代为入会或离会时使用 +meeting-join / +meeting-leave——会真实产生入会/离会记录。2. 会议进行中用户想知道“谁加入了”“谁离开了”“谁在发言”“有人共享屏幕吗”等会中动态时，机器人入会后用 +meeting-events 读取事件时间线。3. 典型场景：参会机器人、会中助手、代为旁听、代为参会。前提：机器人只能读到它自己参会过且仍在进行中的会议的事件；查询已结束会议的参会名单、纪要或逐字稿请使用 lark-vc 技能。"
+description: "飞书视频会议：让机器人代当前用户加入/离开正在进行的会议，并读取会议期间的实时事件（参会人加入与离开、发言、聊天、屏幕共享等）。1. 用户提供 9 位会议号、要求代为入会或离会时使用 +meeting-join / +meeting-leave——会真实产生入会/离会记录。2. 会议进行中用户想知道“谁加入了”“谁离开了”“谁在发言”“有人共享屏幕吗”等会中动态时，用 +meeting-events 读取事件时间线：UAT 要求当前 user 在会中；TAT 要求 bot 在会中，meeting_id 来自 +meeting-join 返回或 +meeting-list-active。3. 典型场景：参会机器人、会中助手、代为旁听、代为参会。查询已结束会议的参会名单、纪要或逐字稿请使用 lark-vc 技能。"
 metadata:
  requires:
    bins: ["lark-cli"]
@@ -33,7 +33,8 @@ metadata:
 | 用户意图示例                                                     | 应路由到                                                                                                                                                  |
 | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
 | "帮我入会 123456789"、"代我参会"、"让机器人进会旁听"                         | **本 skill** `+meeting-join`                                                                                                                           |
-| "会议现在还开着，谁刚加入了"、"会议里谁在发言"、"有人共享屏幕吗"（**进行中会议**，且**机器人已入会**） | **本 skill** `+meeting-events`                                                                                                                         |
+| "会议现在还开着，谁刚加入了"、"会议里谁在发言"、"有人共享屏幕吗"（**进行中会议**）             | **本 skill** `+meeting-events`                                                                                                                         |
+| "我/某个用户现在在哪个会里"、"给我找当前可拉事件的 meeting_id"                         | **本 skill** `+meeting-list-active`                                                                                                                     |
 | "退出会议"、"让机器人离开"                                            | **本 skill** `+meeting-leave`                                                                                                                          |
 | "昨天那场会有谁参加过"、"搜昨天的会"、"查纪要/逐字稿/录制"                          | [`lark-vc`](../lark-vc/SKILL.md)                                                                                                                      |
 | "帮我参会，结束后把纪要发到群" 等跨阶段场景                                    | 按序编排：本 skill（入会 → 读事件）→ 会议结束后用 [`lark-vc`](../lark-vc/SKILL.md) / [`lark-minutes`](../lark-minutes/SKILL.md) 拉纪要 → [`lark-im`](../lark-im/SKILL.md) 发群 |
@@ -46,14 +47,17 @@ metadata:
 2. `+meeting-join --meeting-number` 只接受 **9 位纯数字**会议号，不是会议链接整串、也不是 `meeting_id`。
 3. 返回体中的 `meeting.id` **必须立刻记录**——后续 `+meeting-events` / `+meeting-leave` 都靠它，**不能用 9 位会议号替代**。
 4. 入会对所有参会人可见，执行前核实 9 位会议号来源，避免误入错会。
-5. 仅支持 `user` 身份，需提前 `lark-cli auth login`。
+5. 优先使用 `--as bot` 执行真实 bot 入会；若误用 `--as user` 且服务端返回“user access token is not supported”，切到 bot 身份重试。
 6. 若入会失败，优先查看 `+meeting-join` reference 的错误排查段落，重点确认会议号、密码、会议状态、等候室 / 审批以及会议是否禁止当前身份加入。

 ### 2. 感知会中事件（读操作）

 1. 用户要看"会议里正在发生什么"（参会人加入/离开、聊天、转写、屏幕共享）时，用 `+meeting-events`。
 2. 输入是 **`meeting_id`**（长数字 ID），不是 9 位会议号。
-3. Bot 必须**真实参会过**（先 `+meeting-join`），否则事件流通常不可见。具体的状态边界、结束后宽限窗口与错误码（如 `10005 / 20001 / 20002`）请查看 `+meeting-events` reference。
+3. 身份语义必须区分清楚：
+   - UAT / `--as user`：当前 user 在会中即可读取该会事件。
+   - TAT / `--as bot`：bot 必须在会中或参会过；meeting_id 优先来自 `+meeting-join` 返回的 `meeting.id`，也可以先用 `+meeting-list-active --as bot --user-id <user_open_id>` 找到 bot 也在的当前会。
+   - 不要把 TAT 理解成“任意 meeting_id 都能读”。如果 bot 没进过该会，事件流不可见。
 4. **不能做会后复盘**，**不能替代参会人快照查询**。如果会议已结束：
   - 想拿纪要文档或逐字稿文档 token：用 `lark-cli vc +notes --meeting-ids <meeting.id>`
   - 想拿 AI 产物（summary / todos / chapters）或导出逐字稿文件：先用 `lark-cli vc +recording --meeting-ids <meeting.id>` 拿 `minute_token`，再用 `lark-cli vc +notes --minute-tokens <minute_token>`
@@ -66,12 +70,19 @@ metadata:

 ### 3. 离开会议（写操作）

-1. 只有用户明确要求机器人退出 / 离开 / 结束参会时，才用 `+meeting-leave --meeting-id <从 +meeting-join 拿到的 meeting.id>`；不要把任务完成当作离会指令。
+1. 只有用户明确要求机器人退出 / 离开 / 结束参会时，才用 `+meeting-leave --meeting-id <从 +meeting-join 或 +meeting-list-active 拿到的 meeting.id>`；不应因任务完成而执行离会。
 2. `--meeting-id` **必须**是 `+meeting-join` 返回的长数字 `meeting.id`，**不接受 9 位会议号**。
 3. 离会**立即生效**，机器人从会议的参会人列表中消失，对其他参会人可见；若需要重新入会，再跑一次 `+meeting-join` 即可（非真正"不可逆"）。
-4. 仅支持 `user` 身份。
+4. 优先使用与入会相同的 bot 身份离会。

-### 4. Agent 参会示范
+### 4. 获取当前可用的进行中会议 ID（读操作）
+
+1. `+meeting-list-active` 用来发现当前进行中的会议，并拿到后续 `+meeting-events` 需要的长数字 `meeting_id`。
+2. UAT / `--as user`：不需要传 `--user-id`，返回当前登录用户正在参加的会议。
+3. TAT / `--as bot`：必须传 `--user-id <user_open_id>`，即 `ou_...`；返回该用户当前正在参加且 bot 也在会中的会议。它不是全量会议搜索接口。
+4. 如果 TAT 返回空，说明没有找到“目标用户在会中且 bot 也在会中”的当前会；先让 bot 通过 `+meeting-join` 入会，或确认传入的 `user_id` 和会议状态。
+
+### 5. Agent 参会示范

 ```bash
 # 1. 入会，捕获 meeting.id
@@ -89,6 +100,13 @@ lark-cli vc +notes --meeting-ids "$MID"

 如果用户随后明确要求退出 / 离开 / 结束参会，再单独调用 `lark-cli vc +meeting-leave --meeting-id "$MID"`。

+如果已经知道目标用户 `open_id`，且 bot 已在会中，也可以先发现当前会：
+
+```bash
+lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json
+lark-cli vc +meeting-events --as bot --meeting-id <meeting_id> --page-all --format pretty
+```
+
 ## Shortcuts

 Shortcut 是对常用操作的高级封装（`lark-cli vc +<verb> [flags]`）。
@@ -96,11 +114,13 @@ Shortcut 是对常用操作的高级封装（`lark-cli vc +<verb> [flags]`）。
 | Shortcut                                                        | 类型 | 说明                                                                         |
 | --------------------------------------------------------------- | -- | -------------------------------------------------------------------------- |
 | [`+meeting-join`](references/lark-vc-agent-meeting-join.md)     | 写  | Join an in-progress meeting by 9-digit meeting number                      |
+| [`+meeting-list-active`](references/lark-vc-agent-meeting-list-active.md) | 读  | List active meetings and discover meeting_id for event reads               |
 | [`+meeting-events`](references/lark-vc-agent-meeting-events.md) | 读  | List bot meeting events (participant joined/left, transcript, chat, share) |
 | [`+meeting-leave`](references/lark-vc-agent-meeting-leave.md)   | 写  | Leave a meeting by meeting\_id                                             |

 - 使用 `+meeting-join` 前**必须**阅读 [references/lark-vc-agent-meeting-join.md](references/lark-vc-agent-meeting-join.md)，了解入参格式与写操作可见性风险。
- 使用 `+meeting-events` 前**必须**阅读 [references/lark-vc-agent-meeting-events.md](references/lark-vc-agent-meeting-events.md)，了解 `meeting_id` 来源、分页、错误码（10005 / 20001 / 20002）与 "bot 仍在会中" 硬约束。
+- 使用 `+meeting-list-active` 前**必须**阅读 [references/lark-vc-agent-meeting-list-active.md](references/lark-vc-agent-meeting-list-active.md)，了解 UAT/TAT 的 `user_id` 和 bot-in-meeting 过滤语义。
+- 使用 `+meeting-events` 前**必须**阅读 [references/lark-vc-agent-meeting-events.md](references/lark-vc-agent-meeting-events.md)，了解 `meeting_id` 来源、分页、错误码（10005 / 20001 / 20002）与 UAT/TAT 身份边界。
 - 使用 `+meeting-leave` 前**必须**阅读 [references/lark-vc-agent-meeting-leave.md](references/lark-vc-agent-meeting-leave.md)，了解 `meeting_id` 的来源与写操作可见性。

 ## 权限表
@@ -108,6 +128,7 @@ Shortcut 是对常用操作的高级封装（`lark-cli vc +<verb> [flags]`）。
 | Shortcut          | 所需 scope                       |
 | ----------------- | ------------------------------ |
 | `+meeting-join`   | `vc:meeting.bot.join:write`    |
+| `+meeting-list-active` | `vc:meeting.active:read` |
 | `+meeting-events` | `vc:meeting.meetingevent:read` |
 | `+meeting-leave`  | `vc:meeting.bot.join:write`    |

--- a/skills/lark-vc-agent/references/lark-vc-agent-meeting-events.md
+++ b/skills/lark-vc-agent/references/lark-vc-agent-meeting-events.md
@@ -3,10 +3,15 @@

 > **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、全局参数和安全规则。

-查询当前 bot 在一场正在进行的视频会议中收到的会中事件列表。该命令是**读操作**。对进行中会议，要求 bot 当前仍在会中；对已结束会议，存在一个**结束后 5 分钟内的宽限窗口**，只要 bot 曾经在这场会里出现过，仍可继续拉取事件。
+查询一场正在进行的视频会议中的会中事件列表。该命令是**读操作**。UAT / `--as user` 要求当前 user 在会中；TAT / `--as bot` 要求 bot 在会中或参会过。对已结束会议，存在一个**结束后 5 分钟内的宽限窗口**，只要对应身份曾经在这场会里出现过，仍可继续拉取事件。

 本 skill 对应 shortcut：`lark-cli vc +meeting-events`（调用 `GET /open-apis/vc/v1/bots/events`）。

+身份边界：
+
+- UAT / `--as user`：当前 user 在该会中即可读取事件。
+- TAT / `--as bot`：bot 必须在该会中或参会过；`meeting_id` 通常来自 `+meeting-join` 返回的 `meeting.id`，也可以通过 `+meeting-list-active --as bot --user-id <user_open_id>` 发现。TAT 不表示可以读取任意 meeting_id。
+
 ## 命令

 ```bash
@@ -45,31 +50,38 @@ lark-cli vc +meeting-events --meeting-id 69xxxxxxxxxxxxx28 --dry-run

 `--meeting-id` 必须是会议的长数字 ID。它通常来自：
 - `+meeting-join` 返回体中的 `meeting.id`
+- `+meeting-list-active` 返回体中的 `meeting_id`
 - `+search` 结果中的 `id`

 **不要**把 9 位会议号（`--meeting-number`）传给这个命令。

-### 2. 仅支持 user 身份
+### 2. 支持 UAT 和 TAT，但权限锚点不同

-该命令仅支持 `user` 身份。
+- UAT / `--as user`：当前 user 在会中即可。
+- TAT / `--as bot`：bot 必须在会中或参会过；不要拿任意 meeting_id 直接查。

-### 3. bot 必须在会中，或在会议结束后的 5 分钟宽限窗口内曾经在会中
+### 3. 读取事件前必须先拿到可见的 meeting_id

-这是查询“bot 在会中观察到的事件”的接口。若 bot 已离会、未入会、或会议已经无法再判断 bot 身份，后端通常会报：
- `bot is not in meeting, no permission`
-
-因此，最稳妥的调用顺序通常是：
+TAT 场景最稳妥的调用顺序通常是：

 ```bash
-# 先入会
-lark-cli vc +meeting-join --meeting-number 123456789
-
-# 记录返回的 meeting.id
+# 方式 1：先入会，直接记录返回的 meeting.id
+lark-cli vc +meeting-join --as bot --meeting-number 123456789

 # 再查询事件
-lark-cli vc +meeting-events --meeting-id <meeting.id>
+lark-cli vc +meeting-events --as bot --meeting-id <meeting.id>
 ```

+如果 bot 已经在会中，也可以先通过 active meeting 找会：
+
+```bash
+lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json
+lark-cli vc +meeting-events --as bot --meeting-id <meeting_id> --page-all --format pretty
+```
+
+若对应身份已离会、未入会、或会议已经无法再判断身份，后端通常会报：
+- `bot is not in meeting, no permission`
+
 更精确地说，后端当前的判断规则是：

 - **会议进行中**：要求 bot **当前仍在会中**
@@ -171,7 +183,7 @@ lark-cli vc +meeting-events --meeting-id <meeting.id>

 | 输入参数 | 获取方式 |
 |---------|---------|
-| `meeting-id` | `+meeting-join` 返回的 `meeting.id`；或 `+search` 结果中的 `id` |
+| `meeting-id` | `+meeting-join` 返回的 `meeting.id`；或 `+meeting-list-active` 返回的 `meeting_id`；或 `+search` 结果中的 `id` |
 | `start` / `end` | 用户给出的时间范围；如未给出则默认取全量可见事件 |
 | `page-token` | 上一页或上一次查询结果中保存的 `page_token`；建议持久化保存，便于下次继续拉取新增事件 |

@@ -187,6 +199,13 @@ lark-cli vc +meeting-join --meeting-number 123456789
 lark-cli vc +meeting-events --meeting-id <meeting.id> --page-all --format pretty
 ```

+### 场景 1b：TAT 下 bot 已在会中，先发现 meeting_id 再读事件
+
+```bash
+lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json
+lark-cli vc +meeting-events --as bot --meeting-id <meeting_id> --page-all --format pretty
+```
+
 ### 场景 2：过滤某段时间内的事件

 ```bash
@@ -238,6 +257,7 @@ lark-cli vc +meeting-events \
 ## 参考

 - [lark-vc-agent-meeting-join](lark-vc-agent-meeting-join.md) — 先真实入会
+- [lark-vc-agent-meeting-list-active](lark-vc-agent-meeting-list-active.md) — 发现当前可读事件的进行中会议 ID
 - [lark-vc-agent-meeting-leave](lark-vc-agent-meeting-leave.md) — 用户明确要求时离会
 - [lark-vc-search](../../lark-vc/references/lark-vc-search.md) — 搜索历史会议（获取 meeting_id）
 - [lark-vc-recording](../../lark-vc/references/lark-vc-recording.md) — 查询 minute_token
--- a/skills/lark-vc-agent/references/lark-vc-agent-meeting-join.md
+++ b/skills/lark-vc-agent/references/lark-vc-agent-meeting-join.md
@@ -38,9 +38,9 @@ lark-cli vc +meeting-join --meeting-number 123456789 --dry-run

 ## 核心约束

-### 1. 仅支持 user 身份
+### 1. 优先使用 bot 身份

-该命令仅支持 `user` 身份。
+这是 bot 入会能力，优先使用 `--as bot`。如果误用 `--as user` 且服务端返回“user access token is not supported”，切到 bot 身份重试。

 ### 2. 会议号格式严格校验

@@ -94,6 +94,12 @@ lark-cli vc +meeting-join --meeting-number 123456789
 lark-cli vc +meeting-events --meeting-id <meeting.id> --page-all --format pretty
 ```

+如果 bot 已经在会中，也可以通过 active meeting 找回 `meeting_id`：
+
+```bash
+lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json
+```
+
 ### 场景 2：加入会议 → 会后拉取纪要 / 录制

 ```bash
@@ -126,6 +132,7 @@ lark-cli vc +notes --meeting-ids <meeting.id>
 ## 参考

 - [lark-vc-agent-meeting-leave](lark-vc-agent-meeting-leave.md) — 对应的离会命令
+- [lark-vc-agent-meeting-list-active](lark-vc-agent-meeting-list-active.md) — 发现当前可读事件的进行中会议 ID
 - [lark-vc-agent-meeting-events](lark-vc-agent-meeting-events.md) — 会中事件流
 - [lark-vc-search](../../lark-vc/references/lark-vc-search.md) — 搜索历史会议记录
 - [lark-vc-recording](../../lark-vc/references/lark-vc-recording.md) — 查询 minute_token
--- a/skills/lark-vc-agent/references/lark-vc-agent-meeting-leave.md
+++ b/skills/lark-vc-agent/references/lark-vc-agent-meeting-leave.md
@@ -32,11 +32,11 @@ lark-cli vc +meeting-leave --meeting-id 69xxxxxxxxxxxxx28 --dry-run

 ### 1. 入参是 meeting_id，不是会议号

-`--meeting-id` 必须是会议的长数字 ID，通常由 `+meeting-join` 返回体中的 `meeting.id` 提供，也可从 `+search` 结果中的 `id` 字段获取。**传 9 位会议号会失败**。
+`--meeting-id` 必须是会议的长数字 ID，通常由 `+meeting-join` 返回体中的 `meeting.id` 提供，也可从 `+meeting-list-active` 返回体中的 `meeting_id` 获取。**传 9 位会议号会失败**。

-### 2. 仅支持 user 身份
+### 2. 优先使用 bot 身份

-该命令仅支持 `user` 身份。只能让当前身份自己离会，无法强制移出其他参会人。
+这是 bot 离会能力，优先使用与入会相同的 `--as bot`。只能让当前身份自己离会，无法强制移出其他参会人。

 ### 3. 当前身份必须在会议中

@@ -55,7 +55,7 @@ lark-cli vc +meeting-leave --meeting-id 69xxxxxxxxxxxxx28 --dry-run

 | 输入参数 | 获取方式 |
 |---------|---------|
-| `meeting-id` | `+meeting-join` 返回的 `meeting.id`；或 `+search` 结果中的 `id` 字段 |
+| `meeting-id` | `+meeting-join` 返回的 `meeting.id`；或 `+meeting-list-active` 返回的 `meeting_id` |

 ## Agent 组合场景

@@ -63,13 +63,13 @@ lark-cli vc +meeting-leave --meeting-id 69xxxxxxxxxxxxx28 --dry-run

 ```bash
 # 第 1 步：加入会议，记录 meeting.id
-lark-cli vc +meeting-join --meeting-number 123456789
+lark-cli vc +meeting-join --as bot --meeting-number 123456789

 # 第 2 步：在会中处理用户请求（如监听发言、记录信息等）
 # ...

 # 第 3 步：仅在用户明确要求退出 / 离开 / 结束参会时，使用上一步记录的 meeting.id 离会
-lark-cli vc +meeting-leave --meeting-id <meeting.id>
+lark-cli vc +meeting-leave --as bot --meeting-id <meeting.id>
 ```

 ### 场景 2：会后补拉产物（不需要离会）
@@ -96,11 +96,12 @@ lark-cli vc +notes --meeting-ids <meeting.id>

 - 只有用户明确要求退出 / 离开 / 结束参会时才调用；离会会让机器人从参会列表消失，对其他参会人可见。若需要重新入会直接再 `+meeting-join`，不是真正的"不可逆"。参数格式不确定时可选 `--dry-run` 预览。
 - `+meeting-leave` 依赖 `+meeting-join` 返回的 `meeting.id`，但不是每次 join 后都必须调用 leave。
- `meeting_id` 优先使用 `+meeting-join` 返回的 `meeting.id`；如果来自 `+search`，也必须先确认当前身份就在该会议中。不要用 9 位会议号。
+- `meeting_id` 优先使用 `+meeting-join` 返回的 `meeting.id`；如果来自 `+meeting-list-active`，也必须确认当前身份就在该会议中。不要用 9 位会议号。

 ## 参考

 - [lark-vc-agent-meeting-join](lark-vc-agent-meeting-join.md) — 对应的入会命令
+- [lark-vc-agent-meeting-list-active](lark-vc-agent-meeting-list-active.md) — 发现当前可读事件的进行中会议 ID
 - [lark-vc-agent-meeting-events](lark-vc-agent-meeting-events.md) — 会中事件流
 - [lark-vc-search](../../lark-vc/references/lark-vc-search.md) — 搜索历史会议（获取 meeting_id）
 - [lark-vc-recording](../../lark-vc/references/lark-vc-recording.md) — 查询 minute_token
--- a/skills/lark-vc-agent/references/lark-vc-agent-meeting-list-active.md
+++ b/skills/lark-vc-agent/references/lark-vc-agent-meeting-list-active.md
@@ -0,0 +1,70 @@
+# vc +meeting-list-active
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md) 了解认证、身份切换和权限处理。
+
+列出当前进行中的会议，用来发现 `+meeting-events` 需要的长数字 `meeting_id`。
+
+本 skill 对应 shortcut：`lark-cli vc +meeting-list-active`（调用 `GET /open-apis/vc/v1/bots/user_active_meeting`）。
+
+## 命令
+
+```bash
+# UAT：查询当前登录用户正在参加的会议
+lark-cli vc +meeting-list-active --as user --format pretty
+
+# TAT：查询指定 open_id 当前参加、且 bot 也在会中的会议
+lark-cli vc +meeting-list-active --as bot --user-id ou_xxx --format json
+
+# 预览 API 调用
+lark-cli vc +meeting-list-active --as bot --user-id ou_xxx --dry-run
+```
+
+## 参数
+
+| 参数 | 必填 | 说明 |
+|------|------|------|
+| `--user-id <id>` | TAT 必填，UAT 不需要 | 目标用户 open_id，格式为 `ou_...`。CLI 直接透传给接口，不接受 internal user_id 或数字 ID |
+| `--format <fmt>` | 否 | 输出格式：json / pretty / table / ndjson / csv |
+| `--dry-run` | 否 | 预览 API 调用，不执行 |
+
+## 身份语义
+
+### UAT / `--as user`
+
+- 不传 `--user-id`。
+- 返回当前登录用户正在参加的会议。
+- 后续可直接用返回的 `meeting_id` 调用：
+
+```bash
+lark-cli vc +meeting-events --as user --meeting-id <meeting_id> --page-all --format pretty
+```
+
+### TAT / `--as bot`
+
+- 必须传 `--user-id <user_open_id>`，即 `ou_...`。
+- 返回该用户当前正在参加、且 bot 也在会中的会议。
+- 如果返回空，不代表用户不在任何会议中，只能说明没有找到“用户在会中且 bot 也在会中”的当前会。
+- TAT 读取事件仍然要求 bot 在会中。常见流程是：
+
+```bash
+# 方式 1：先让 bot 入会，直接从 join 响应拿 meeting.id
+lark-cli vc +meeting-join --as bot --meeting-number 123456789 --format json
+lark-cli vc +meeting-events --as bot --meeting-id <meeting.id> --page-all --format pretty
+
+# 方式 2：bot 已经在会中时，用 active meeting 发现 meeting_id
+lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format json
+lark-cli vc +meeting-events --as bot --meeting-id <meeting_id> --page-all --format pretty
+```
+
+## 常见错误与排查
+
+| 错误现象 | 根本原因 | 解决方案 |
+|---------|---------|---------|
+| `--user-id is required when --as bot` | TAT 未传目标用户 | 传入目标用户 open_id |
+| 返回空列表 | 没有满足“目标用户在会中且 bot 也在会中”的当前会 | 先让 bot 入会，或确认 `user_id` 和会议状态 |
+| `--user-id` 格式错误 | 传入了 internal user_id 或其他非 `ou_...` 值 | 改传目标用户 open_id |
+
+## 参考
+
+- [lark-vc-agent-meeting-join](lark-vc-agent-meeting-join.md) — 让 bot 真实入会并拿 `meeting.id`
+- [lark-vc-agent-meeting-events](lark-vc-agent-meeting-events.md) — 使用 `meeting_id` 读取会中事件