From 2a9fcaeed56554fbed8624795c337255f3eaa867 Mon Sep 17 00:00:00 2001
From: "zhangjun.1" <zhangjun.1@bytedance.com>
Date: Wed, 8 Jul 2026 21:13:24 +0800
Subject: [PATCH] event description support rich text

---
 shortcuts/calendar/calendar_create.go         |  6 +-
 shortcuts/calendar/calendar_update.go         | 12 ++-
 .../references/lark-calendar-create.md        |  3 +-
 .../references/lark-calendar-update.md        |  8 +-
 .../calendar_description_rich_dryrun_test.go  | 84 +++++++++++++++++++
 5 files changed, 106 insertions(+), 7 deletions(-)
 create mode 100644 tests/cli_e2e/calendar/calendar_description_rich_dryrun_test.go

diff --git a/shortcuts/calendar/calendar_create.go b/shortcuts/calendar/calendar_create.go
index effb5f677..7c787e8df 100644
--- a/shortcuts/calendar/calendar_create.go
+++ b/shortcuts/calendar/calendar_create.go
@@ -33,6 +33,9 @@ func buildEventData(runtime *common.RuntimeContext, startTs, endTs string) map[s
 	if rrule := runtime.Str("rrule"); rrule != "" {
 		eventData["recurrence"] = rrule
 	}
+	if descriptionRich := runtime.Str("description-rich"); descriptionRich != "" {
+		eventData["description_rich"] = descriptionRich
+	}
 	return eventData
 }
 
@@ -99,7 +102,8 @@ var CalendarCreate = common.Shortcut{
 		{Name: "summary", Desc: "event title"},
 		{Name: "start", Desc: "start time (ISO 8601)", Required: true},
 		{Name: "end", Desc: "end time (ISO 8601)", Required: true},
-		{Name: "description", Desc: "event description"},
+		{Name: "description", Desc: "event description (plain text)"},
+		{Name: "description-rich", Desc: "rich-text description as Markdown (@file or - for stdin); supports bold/italic/underline/strikethrough, links, and lists", Input: []string{common.File, common.Stdin}},
 		{Name: "attendee-ids", Desc: "attendee IDs, comma-separated (supports user ou_, chat oc_, room omm_)"},
 		{Name: "calendar-id", Desc: "calendar ID (default: primary)"},
 		{Name: "rrule", Desc: "recurrence rule (rfc5545)"},
diff --git a/shortcuts/calendar/calendar_update.go b/shortcuts/calendar/calendar_update.go
index 17f9cc897..4d670383a 100644
--- a/shortcuts/calendar/calendar_update.go
+++ b/shortcuts/calendar/calendar_update.go
@@ -29,7 +29,8 @@ var CalendarUpdate = common.Shortcut{
 		{Name: "event-id", Desc: "event ID to update", Required: true},
 		{Name: "calendar-id", Desc: "calendar ID (default: primary)"},
 		{Name: "summary", Desc: "event title"},
-		{Name: "description", Desc: "event description"},
+		{Name: "description", Desc: "event description (plain text)"},
+		{Name: "description-rich", Desc: "rich-text description as Markdown (@file or - for stdin); supports bold/italic/underline/strikethrough, links, and lists", Input: []string{common.File, common.Stdin}},
 		{Name: "start", Desc: "new start time (ISO 8601); requires --end"},
 		{Name: "end", Desc: "new end time (ISO 8601); requires --start"},
 		{Name: "rrule", Desc: "recurrence rule (rfc5545)"},
@@ -70,7 +71,7 @@ func validateCalendarUpdate(runtime *common.RuntimeContext) error {
 		return err
 	}
 	if !hasCalendarUpdateOperation(runtime) {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "nothing to update: specify at least one of --summary, --description, --start/--end, --rrule, --add-attendee-ids, or --remove-attendee-ids")
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "nothing to update: specify at least one of --summary, --description, --description-rich, --start/--end, --rrule, --add-attendee-ids, or --remove-attendee-ids")
 	}
 	return nil
 }
@@ -114,6 +115,10 @@ func buildCalendarUpdateEventData(runtime *common.RuntimeContext) (map[string]in
 			hasFields = true
 		}
 	}
+	if runtime.Cmd.Flags().Changed("description-rich") {
+		body["description_rich"] = runtime.Str("description-rich")
+		hasFields = true
+	}
 	if runtime.Cmd.Flags().Changed("rrule") {
 		rrule := strings.TrimSpace(runtime.Str("rrule"))
 		if rrule != "" {
@@ -353,6 +358,9 @@ func calendarUpdateResult(eventID string, event map[string]interface{}, addedCou
 	if description, _ := event["description"].(string); description != "" {
 		result["description"] = description
 	}
+	if descriptionRich, _ := event["description_rich"].(string); descriptionRich != "" {
+		result["description_rich"] = descriptionRich
+	}
 	if start := formatCalendarEventTime(event["start_time"]); start != "" {
 		result["start"] = start
 	}
diff --git a/skills/lark-calendar/references/lark-calendar-create.md b/skills/lark-calendar/references/lark-calendar-create.md
index 4036de2ba..a67daae86 100644
--- a/skills/lark-calendar/references/lark-calendar-create.md
+++ b/skills/lark-calendar/references/lark-calendar-create.md
@@ -32,7 +32,8 @@ lark-cli calendar +create --summary "..." --start "..." --end "..." \
 | `--summary <text>` | 否 | 日程标题。注意：标题中不应该出现时间、地点、人物信息 |
 | `--start <time>` | 是 | 开始时间（ISO 8601，如 `2026-03-12T14:00+08:00`） |
 | `--end <time>` | 是 | 结束时间（ISO 8601） |
-| `--description <text>` | 否 | 日程详细描述。提供会议议程、活动内容、注意事项或链接等。与 summary 配合使用，仅关注当前日程信息 |
+| `--description <text>` | 否 | 日程纯文本描述。提供会议议程、活动内容、注意事项或链接等。与 summary 配合使用，仅关注当前日程信息 |
+| `--description-rich <markdown>` | 否 | 日程富文本描述，使用 **Markdown** 格式。支持加粗、斜体、下划线（`<u>...</u>`）、删除线、链接 `[文本](url)`、有序/无序列表。支持 `@文件路径` 或 `-`（stdin）读取。需要富文本格式（如带链接）时使用此参数而非 `--description` |
 | `--attendee-ids <id_list>` | 否 | 参与人 ID 列表（逗号分隔）。支持用户（`ou_`）、群组（`oc_`）和会议室（`omm_`）。AI 提取时请务必保留对应前缀 |
 | `--calendar-id <id>` | 否 | 日历 ID（省略则使用主日历） |
 | `--rrule <rrule>` | 否 | 重复日程的重复性规则，规则设置方式参考rfc5545。示例值："FREQ=DAILY;INTERVAL=1;UNTIL=<具体日期>" |
diff --git a/skills/lark-calendar/references/lark-calendar-update.md b/skills/lark-calendar/references/lark-calendar-update.md
index 9d879e08d..fae08b18f 100644
--- a/skills/lark-calendar/references/lark-calendar-update.md
+++ b/skills/lark-calendar/references/lark-calendar-update.md
@@ -43,7 +43,8 @@ lark-cli calendar +update \
 | `--event-id <id>` | 是 | 要更新的日程 ID。重复性日程请根据操作范围选择 ID，详见 [重复性日程操作规范](lark-calendar-recurring.md) |
 | `--calendar-id <id>` | 否 | 日历 ID（省略则使用 `primary`） |
 | `--summary <text>` | 否 | 新日程标题。仅在显式传入 `--summary` 时更新；若传空字符串，会把标题清空 |
-| `--description <text>` | 否 | 新日程描述。目前 API 方式不支持编辑富文本描述；如果日程描述通过客户端编辑为富文本内容，则使用 API 更新描述会导致富文本格式丢失。仅在显式传入 `--description` 时更新；若传空字符串，会把描述清空 |
+| `--description <text>` | 否 | 新日程纯文本描述。仅在显式传入 `--description` 时更新；若传空字符串，会把描述清空。注意：只传 `--description`（不带 `--description-rich`）会覆盖并清空原有富文本描述 |
+| `--description-rich <markdown>` | 否 | 新日程富文本描述，使用 **Markdown** 格式（加粗、斜体、下划线 `<u>...</u>`、删除线、链接 `[文本](url)`、有序/无序列表）。支持 `@文件路径` 或 `-`（stdin）读取。仅在显式传入时更新。需保留富文本格式时使用此参数而非 `--description` |
 | `--start <time>` | 否 | 新开始时间（ISO 8601，如 `2026-03-12T14:00+08:00`）。更新日程时间时必须同时传 `--end` |
 | `--end <time>` | 否 | 新结束时间（ISO 8601）。更新日程时间时必须同时传 `--start` |
 | `--rrule <rrule>` | 否 | 新重复规则（RFC5545）。**不要使用 COUNT；如需限制次数，推算后转为 UNTIL** |
@@ -52,12 +53,13 @@ lark-cli calendar +update \
 | `--notify` | 否 | 是否发送更新通知，默认 `true`。可用 `--notify=false` 静默更新 |
 | `--dry-run` | 否 | 预览 API 调用，不执行 |
 
-至少需要提供一个动作：`--summary`、`--description`、`--start/--end`、`--rrule`、`--add-attendee-ids` 或 `--remove-attendee-ids`。
+至少需要提供一个动作：`--summary`、`--description`、`--description-rich`、`--start/--end`、`--rrule`、`--add-attendee-ids` 或 `--remove-attendee-ids`。
 
 ## 使用规则
 
 - `--add-attendee-ids` 是**增量添加**，不是替换最终参与人列表。不要用它表达“只保留这些人”。
-- 对 `--summary`、`--description`，CLI 以“是否显式传入该 flag”判断是否更新，而不是以“值是否为空”判断；如果显式传入空字符串，会把对应字段清空。
+- 对 `--summary`、`--description`、`--description-rich`，CLI 以“是否显式传入该 flag”判断是否更新，而不是以“值是否为空”判断；如果显式传入空字符串，会把对应字段清空。
+- 富文本描述与纯文本描述互斥存储：需要保留/写入富文本时用 `--description-rich`；只传 `--description` 会清空原有富文本。
 - 只想增删参会人或会议室时，不需要同时传 `--summary`、`--start`、`--end` 等日程字段。
 - 只想修改标题、描述、时间或重复规则时，不需要同时传 `--add-attendee-ids` 或 `--remove-attendee-ids`。
 - 如需替换某个参与人、群组或会议室，使用 `--remove-attendee-ids <旧ID>` + `--add-attendee-ids <新ID>`。
diff --git a/tests/cli_e2e/calendar/calendar_description_rich_dryrun_test.go b/tests/cli_e2e/calendar/calendar_description_rich_dryrun_test.go
new file mode 100644
index 000000000..0d9e59068
--- /dev/null
+++ b/tests/cli_e2e/calendar/calendar_description_rich_dryrun_test.go
@@ -0,0 +1,84 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package calendar
+
+import (
+	"context"
+	"testing"
+	"time"
+
+	clie2e "github.com/larksuite/cli/tests/cli_e2e"
+	"github.com/stretchr/testify/require"
+	"github.com/tidwall/gjson"
+)
+
+// richTextMarkdown is a Markdown rich-text payload carrying a doc link and
+// styling. The CLI forwards it verbatim in description_rich; the OpenAPI service
+// converts Markdown <-> ClientVars.
+const richTextMarkdown = "见 [设计文档](https://bytedance.feishu.cn/docx/abc) 和 **重点**"
+
+// TestCalendar_CreateDescriptionRichDryRun verifies that +create forwards the
+// rich-text payload as-is under the description_rich body field.
+func TestCalendar_CreateDescriptionRichDryRun(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	t.Setenv("LARKSUITE_CLI_APP_ID", "app")
+	t.Setenv("LARKSUITE_CLI_APP_SECRET", "secret")
+	t.Setenv("LARKSUITE_CLI_BRAND", "feishu")
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"calendar", "+create",
+			"--calendar-id", "cal_dry",
+			"--summary", "rich dry-run",
+			"--start", "2026-04-25T10:00:00+08:00",
+			"--end", "2026-04-25T11:00:00+08:00",
+			"--description", "plain fallback",
+			"--description-rich", richTextMarkdown,
+			"--dry-run",
+		},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+
+	out := result.Stdout
+	require.Equal(t, "POST", gjson.Get(out, "api.0.method").String(), "stdout:\n%s", out)
+	require.Equal(t, "/open-apis/calendar/v4/calendars/cal_dry/events", gjson.Get(out, "api.0.url").String(), "stdout:\n%s", out)
+	require.Equal(t, "plain fallback", gjson.Get(out, "api.0.body.description").String(), "stdout:\n%s", out)
+	require.Equal(t, richTextMarkdown, gjson.Get(out, "api.0.body.description_rich").String(), "stdout:\n%s", out)
+}
+
+// TestCalendar_UpdateDescriptionRichDryRun verifies that +update forwards the
+// rich-text payload as-is under the description_rich body field.
+func TestCalendar_UpdateDescriptionRichDryRun(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	t.Setenv("LARKSUITE_CLI_APP_ID", "app")
+	t.Setenv("LARKSUITE_CLI_APP_SECRET", "secret")
+	t.Setenv("LARKSUITE_CLI_BRAND", "feishu")
+
+	ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	t.Cleanup(cancel)
+
+	result, err := clie2e.RunCmd(ctx, clie2e.Request{
+		Args: []string{
+			"calendar", "+update",
+			"--calendar-id", "cal_dry",
+			"--event-id", "evt_dry",
+			"--description-rich", richTextMarkdown,
+			"--notify=false",
+			"--dry-run",
+		},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+
+	out := result.Stdout
+	require.Equal(t, "PATCH", gjson.Get(out, "api.0.method").String(), "stdout:\n%s", out)
+	require.Equal(t, "/open-apis/calendar/v4/calendars/cal_dry/events/evt_dry", gjson.Get(out, "api.0.url").String(), "stdout:\n%s", out)
+	require.Equal(t, richTextMarkdown, gjson.Get(out, "api.0.body.description_rich").String(), "stdout:\n%s", out)
+}