fix: default meeting events to normalized output

2026-07-07 09:11:44 +08:00 · 2026-06-24 12:18:49 +08:00
parent 7986f17d57
commit 0883f452fe
5 changed files with 24 additions and 119 deletions
--- a/shortcuts/vc/vc_meeting_events.go
+++ b/shortcuts/vc/vc_meeting_events.go
@@ -32,13 +32,6 @@ const (

 var meetingDisplayLocation = time.FixedZone("UTC+8", 8*60*60)

-type meetingEventsView string
-
-const (
-	meetingEventsViewCompact meetingEventsView = "compact"
-	meetingEventsViewRaw     meetingEventsView = "raw"
-)
-
 // toUnixSeconds converts a supported CLI time input into a Unix seconds string.
 func toUnixSeconds(input string, hint ...string) (string, error) {
 	ts, err := common.ParseTime(input, hint...)
@@ -67,15 +60,11 @@ var VCMeetingEvents = common.Shortcut{
 		{Name: "page-token", Desc: "page token for the next page"},
 		{Name: "page-size", Default: "20", Desc: "page size, 20-100 (default 20)"},
 		{Name: "page-all", Type: "bool", Desc: "automatically paginate through all available pages"},
-		{Name: "view", Default: string(meetingEventsViewCompact), Desc: "output view: compact or raw"},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		if err := validateMeetingEventsMeetingID(runtime.Str("meeting-id")); err != nil {
 			return err
 		}
-		if _, err := meetingEventsOutputView(runtime); err != nil {
-			return err
-		}
 		if _, err := meetingEventsPageSize(runtime); err != nil {
 			return err
 		}
@@ -112,12 +101,6 @@ var VCMeetingEvents = common.Shortcut{
 		if err != nil {
 			return err
 		}
-		if view, err := meetingEventsOutputView(runtime); err != nil {
-			return err
-		} else if view == meetingEventsViewRaw {
-			runtime.Out(data, &output.Meta{Count: len(events)})
-			return nil
-		}
 		events = compactMeetingEvents(events)
 		identity, err := meetingEventsCurrentIdentity(runtime)
 		if err != nil {
@@ -192,24 +175,6 @@ type normalizedMeetingEvent struct {
 	Raw       map[string]interface{} `json:"raw,omitempty"`
 }

-func meetingEventsOutputView(runtime *common.RuntimeContext) (meetingEventsView, error) {
-	view := strings.TrimSpace(runtime.Str("view"))
-	if view == "" {
-		view = string(meetingEventsViewCompact)
-	}
-	switch meetingEventsView(view) {
-	case meetingEventsViewCompact:
-		return meetingEventsViewCompact, nil
-	case meetingEventsViewRaw:
-		if runtime.Format != "" && runtime.Format != "json" {
-			return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--view raw only supports --format json").WithParam("--view")
-		}
-		return meetingEventsViewRaw, nil
-	default:
-		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--view must be compact or raw, got %q", view).WithParam("--view")
-	}
-}
-
 func buildNormalizedMeetingEvents(data map[string]interface{}, events []interface{}, currentRoster []interface{}, identity normalizedIdentity) normalizedMeetingEventsOutput {
 	normalized := normalizedMeetingEventsOutput{
 		Identity:  identity,
--- a/shortcuts/vc/vc_meeting_events_test.go
+++ b/shortcuts/vc/vc_meeting_events_test.go
@@ -27,7 +27,6 @@ func newMeetingEventsRuntime() *common.RuntimeContext {
 	cmd.Flags().String("page-token", "", "")
 	cmd.Flags().String("page-size", "", "")
 	cmd.Flags().Bool("page-all", false, "")
-	cmd.Flags().String("view", "compact", "")
 	return common.TestNewRuntimeContext(cmd, defaultConfig())
 }

@@ -592,39 +591,6 @@ func TestMeetingEvents_ExecuteJSON_UserIdentitySkipsBotInfo(t *testing.T) {
 	}
 }

-func TestMeetingEvents_ExecuteRawJSONSkipsBotInfo(t *testing.T) {
-	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
-	reg.Register(meetingEventsStub([]interface{}{participantJoinedEvent()}, true, "1710000000000000000"))
-
-	err := mountAndRun(t, VCMeetingEvents, []string{
-		"+meeting-events",
-		"--meeting-id", "7628568141510692381",
-		"--format", "json",
-		"--view", "raw",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-	reg.Verify(t)
-
-	out := strings.ReplaceAll(stdout.String(), " ", "")
-	out = strings.ReplaceAll(out, "\n", "")
-	for _, want := range []string{
-		`"events":[`,
-		`"event_type":"participant_joined"`,
-		`"has_more":true`,
-		`"page_token":"1710000000000000000"`,
-	} {
-		if !strings.Contains(out, want) {
-			t.Fatalf("raw json output missing %q: %s", want, stdout.String())
-		}
-	}
-	if strings.Contains(out, `"current_roster"`) || strings.Contains(out, `"identity":{`) || strings.Contains(out, `"bot":{`) {
-		t.Fatalf("raw json should preserve legacy events envelope without normalized fields: %s", stdout.String())
-	}
-}
-
 func TestMeetingEvents_ExecuteNDJSONIncludesMetadataRow(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
 	reg.Register(meetingEventsStub([]interface{}{participantJoinedEvent()}, true, "1710000000000000000"))
@@ -664,25 +630,6 @@ func TestMeetingEvents_ExecuteNDJSONIncludesMetadataRow(t *testing.T) {
 	}
 }

-func TestMeetingEvents_Validation_RawRejectsPretty(t *testing.T) {
-	runtime := newMeetingEventsRuntime()
-	mustSetMeetingEventsFlag(t, runtime, "meeting-id", "7628568141510692381")
-	mustSetMeetingEventsFlag(t, runtime, "view", "raw")
-	runtime.Format = "pretty"
-
-	err := VCMeetingEvents.Validate(context.Background(), runtime)
-	if err == nil {
-		t.Fatal("expected validation error for raw pretty")
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("expected *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Param != "--view" {
-		t.Errorf("Param = %q, want %q", ve.Param, "--view")
-	}
-}
-
 func TestMeetingEvents_ExecuteJSON_PrunesEmptySlices(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
 	reg.Register(meetingEventsStub([]interface{}{chatReceivedEvent()}, false, ""))
--- a/skills/lark-vc-agent/SKILL.md
+++ b/skills/lark-vc-agent/SKILL.md
@@ -72,7 +72,7 @@ metadata:
   - 再根据 `note_display_type`、`note_id`、`minute_token` 和用户意图，按 [`lark-vc`](../lark-vc/SKILL.md) 的产物决策读取正文、逐字稿或妙记。
   - 想看参会人快照：用 `vc meeting get --with-participants`（见 [`lark-vc`](../lark-vc/SKILL.md)）
 5. **默认必须使用** **`--page-all`**，除非用户明确要求“只查一页”，或确实需要控制返回体大小。
-6. 默认 `--view compact` 输出 normalized 契约：`meeting`、`identity`、`current_roster`、`events`、`has_more`、`page_token`，参会人含 `participant_type`、`role`、`is_self` 和可读 `label`。需要兼容旧事件包时用 `--view raw --format json`，raw 不支持 pretty/ndjson。
+6. 命令默认输出 normalized 事件契约：`meeting`、`identity`、`current_roster`、`events`、`has_more`、`page_token`，参会人含 `participant_type`、`role`、`is_self` 和可读 `label`；事件中的原始细节保留在 `payload/raw`。
 7. 输出格式默认优先 `--format pretty`（时间线更易读，并带当前身份与当前名单标签）；需要结构化处理时用 `--format json`；需要流式消费事件时用 `--format ndjson`。
 8. **必须识别分页信号**：只要响应里出现 `has_more=true`、pretty 里的 `more available`，或返回了非空 `page_token`，就不能把当前结果当作完整事件流；默认应继续分页，或明确告诉用户当前只是部分结果。
 9. 保留响应里的 `page_token`，下次增量拉取直接续，不要从头再拉。
@@ -106,7 +106,7 @@ MID=$(echo "$JOIN" | jq -r '.data.meeting.id')
 # 2. 会中轮询事件
 #    默认用 --page-all 拉全当前可见事件；下次增量优先复用 page_token
 #    典型间隔 10-30 秒
-lark-cli vc +meeting-events --as bot --meeting-id "$MID" --page-all --view compact --format pretty
+lark-cli vc +meeting-events --as bot --meeting-id "$MID" --page-all --format pretty

 # 3. 会后可选：进入 lark-vc 获取会议产物信息，再按 note_display_type / minute_token 决策读取
 lark-cli vc +notes --meeting-ids "$MID"
@@ -118,14 +118,14 @@ lark-cli vc +notes --meeting-ids "$MID"

 ```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 <id> --page-all --view compact --format pretty
+lark-cli vc +meeting-events --as bot --meeting-id <id> --page-all --format pretty
 ```

 如果只是回答当前登录用户所在会议发生了什么，使用用户身份一路查：

 ```bash
 lark-cli vc +meeting-list-active --as user --format json
-lark-cli vc +meeting-events --as user --meeting-id <meeting_id> --page-all --view compact --format pretty
+lark-cli vc +meeting-events --as user --meeting-id <meeting_id> --page-all --format pretty
 ```

 ## Shortcuts
--- a/skills/lark-vc-agent/references/lark-vc-agent-meeting-events.md
+++ b/skills/lark-vc-agent/references/lark-vc-agent-meeting-events.md
@@ -14,17 +14,14 @@
 ## 命令

 ```bash
-# 默认用法：全量拉取当前身份可见事件，输出 normalized compact 契约
-lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-all --view compact --format pretty
+# 默认用法：全量拉取当前身份可见事件；输出 normalized 事件契约
+lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-all --format pretty

 # 指定时间范围，并拉全该时间窗内当前可见事件
-lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --start 2026-04-17T15:00:00+08:00 --end 2026-04-17T16:00:00+08:00 --page-all --view compact --format pretty
+lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --start 2026-04-17T15:00:00+08:00 --end 2026-04-17T16:00:00+08:00 --page-all --format pretty

 # 基于上一次保存的 page_token 继续查新增事件
-lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-token <last_page_token> --page-all --view compact --format pretty
-
-# 兼容旧事件包或调试服务端原始响应时，使用 raw escape hatch
-lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-size 20 --view raw --format json
+lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-token <last_page_token> --page-all --format pretty
 ```

 ## 参数
@@ -37,7 +34,6 @@ lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-size 2
 | `--page-token <token>` | 否 | 从指定分页游标继续拉取下一页 |
 | `--page-size <n>` | 否 | 单页模式每页大小。CLI 会自动夹紧到 `20-100`；传 `--page-all` 时固定使用 `100` |
 | `--page-all` | 否 | 自动分页，直到没有更多页面为止（内部有安全上限） |
-| `--view compact\|raw` | 否 | 输出视图。默认 `compact` 为 agent-facing normalized 契约；`raw` 只支持 `--format json` 并保留旧事件包 |

 ## 核心约束

@@ -69,21 +65,21 @@ lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-size 2
 lark-cli vc +meeting-join --as bot --meeting-number 123456789

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

 如果应用机器人已经在会中，也可以先通过 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 <id> --page-all --view compact --format pretty
+lark-cli vc +meeting-events --as bot --meeting-id <id> --page-all --format pretty
 ```

 如果只是用当前登录用户发现会议：

 ```bash
 lark-cli vc +meeting-list-active --as user --format json
-lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --view compact --format pretty
+lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format pretty
 ```

 若应用机器人已离会、未入会、或会议已经无法再判断身份，后端通常会报：
@@ -106,20 +102,19 @@ lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --view compac

 执行准则：

- **默认命令模板**：`lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-all --view compact --format pretty`
+- **默认命令模板**：`lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-all --format pretty`
 - 如果你发现自己执行成了不带 `--page-all` 的单页查询，而响应里又出现 `has_more=true` / `more available` / 非空 `page_token`，应立刻意识到这只是部分结果。
- 遇到上述情况，默认补救方式是继续使用返回的 `page_token` 续拉，例如：`lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-token <returned_page_token> --page-all --view compact --format pretty`
+- 遇到上述情况，默认补救方式是继续使用返回的 `page_token` 续拉，例如：`lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-token <returned_page_token> --page-all --format pretty`
 - 只有在用户明确要求“就看第一页”“先不要翻页”时，才不要默认带 `--page-all`
 - 只要你是基于 `+meeting-events` 来回答一场**正在进行中的会议内容**，就不能直接复用上一次查询结果。无论用户是在问“现在是谁在说话”“刚刚发生了什么”“最新事件有哪些”，还是让你“总结一下这个会议讲什么”，都必须先重新执行一次 `+meeting-events`，确认拿到的是最新事件流，再回答用户。只有在用户明确要求基于某次历史快照继续分析时，才可以复用旧结果。

-### 5. compact / raw / pretty / json / ndjson 输出差异
+### 5. 输出格式差异

- `--view compact --format json`：默认结构化契约，顶层包含 `meeting`、`identity`、`current_roster`、`events`、`has_more`、`page_token`。参会人身份统一含 `participant_type`、`role`、`is_self`、`label`。
- `--view compact --format pretty`：输出当前身份、当前名单和逐条时间线，适合快速理解“发生了什么”。
- `--view compact --format ndjson`：输出事件行，并带 metadata 行，适合流式消费。
- `--view raw --format json`：保留旧 `events/has_more/page_token` 服务端事件包，不预取 identity 或 current roster。raw 不支持 pretty/ndjson。
+- `--format json`：结构化契约，顶层包含 `meeting`、`identity`、`current_roster`、`events`、`has_more`、`page_token`。参会人身份统一含 `participant_type`、`role`、`is_self`、`label`；每条事件保留 `payload/raw` 便于追溯原始细节。
+- `--format pretty`：输出当前身份、当前名单和逐条时间线，适合快速理解“发生了什么”。
+- `--format ndjson`：输出事件行，并带 metadata 行，适合流式消费。

-**选型原则**：只要目标是告诉用户“发生了什么”，默认就用 `--page-all --view compact --format pretty`；需要稳定字段给 agent 消费时用 compact JSON；只有需要兼容旧事件包时才用 raw JSON。
+**选型原则**：只在 `pretty`、`json`、`ndjson` 之间选择。目标是告诉用户“发生了什么”时，用 `--page-all --format pretty`；需要稳定字段给 agent 消费时用 `--format json`；需要流式消费时用 `--format ndjson`。

 > **注意**：pretty 输出中的正文文本会做单行转义，真实换行会显示为 `\n`，避免打乱时间线布局。

@@ -136,10 +131,10 @@ lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --view compac

 执行准则：

- 如果上下文已有明确 `meeting_id`，沿用该 `meeting_id` 的来源身份执行 `+meeting-events --page-all --view compact --format json`。
+- 如果上下文已有明确 `meeting_id`，沿用该 `meeting_id` 的来源身份执行 `+meeting-events --page-all --format json`。
 - 如果上下文没有明确 `meeting_id`，先按用户当前意图选择身份：问“我/当前用户所在会议”用 `lark-cli vc +meeting-list-active --as user --format pretty`；问“应用机器人可见的目标用户会议”用 `lark-cli vc +meeting-list-active --as bot --user-id <user_open_id> --format pretty`。返回多个会议时先让用户选择。
 - 如果上下文只有 9 位会议号，先按当前身份执行 `+meeting-list-active` 并按 `meeting_no` 匹配；匹配到唯一会议后再查事件。不要为了总结会议而自动调用 `+meeting-join`。
- 这类问题拿到 `meeting_id` 后，用同一身份执行 `lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-all --view compact --format json` 拉取最新事件流。
+- 这类问题拿到 `meeting_id` 后，用同一身份执行 `lark-cli vc +meeting-events --as <same_identity> --meeting-id <id> --page-all --format json` 拉取最新事件流。
 - 如果事件中出现共享文档线索，例如：
  - `magic_share_started`
  - `share_doc.title`
@@ -211,21 +206,21 @@ lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --view compac
 lark-cli vc +meeting-join --as bot --meeting-number 123456789

 # 第 2 步：查询事件流
-lark-cli vc +meeting-events --as bot --meeting-id <id> --page-all --view compact --format pretty
+lark-cli vc +meeting-events --as bot --meeting-id <id> --page-all --format pretty
 ```

 ### 场景 1b：应用机器人已在会中，先发现 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 <id> --page-all --view compact --format pretty
+lark-cli vc +meeting-events --as bot --meeting-id <id> --page-all --format pretty
 ```

 ### 场景 1c：当前登录用户正在会中，先发现 meeting_id 再读事件

 ```bash
 lark-cli vc +meeting-list-active --as user --format json
-lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --view compact --format pretty
+lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format pretty
 ```

 ### 场景 2：过滤某段时间内的事件
@@ -237,7 +232,6 @@ lark-cli vc +meeting-events \
  --start 2026-04-17T15:00:00+08:00 \
  --end 2026-04-17T16:00:00+08:00 \
  --page-all \
-  --view compact \
  --format pretty
 ```

@@ -251,7 +245,6 @@ lark-cli vc +meeting-events \
  --meeting-id <id> \
  --page-token <last_page_token> \
  --page-all \
-  --view compact \
  --format pretty
 ```

--- 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
@@ -46,7 +46,7 @@ lark-cli vc +meeting-events --as bot --meeting-id <id> --page-all --format prett

 # 方式 3：只回答当前登录用户所在会议发生了什么
 lark-cli vc +meeting-list-active --as user --format json
-lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --view compact --format pretty
+lark-cli vc +meeting-events --as user --meeting-id <id> --page-all --format pretty
 ```

 ## 多会议选择