feat: support docs create title option

SunPeiYang996 · SunPeiYang996 · commit e58d61be22ee · 2026-06-22T17:20:35.000+08:00
Change-Id: I6fd840fe813e5e664ea9ec680765fd41375cdebf
diff --git a/shortcuts/doc/doc_errors_test.go b/shortcuts/doc/doc_errors_test.go
@@ -203,6 +203,13 @@ func TestValidateCreateV2Contract(t *testing.T) {
 	}
 }
 
+func TestValidateCreateV2AllowsTitleWithoutContent(t *testing.T) {
+	rt := docValidateRuntime(t, map[string]string{"title": "Only Title"}, nil, nil)
+	if err := validateCreateV2(context.Background(), rt); err != nil {
+		t.Fatalf("validateCreateV2() error = %v, want nil", err)
+	}
+}
+
 func TestValidateFetchV2Contract(t *testing.T) {
 	cases := []struct {
 		name       string
diff --git a/shortcuts/doc/docs_create_test.go b/shortcuts/doc/docs_create_test.go
@@ -282,7 +282,6 @@ func TestDocsCreateRejectsLegacyV1Flags(t *testing.T) {
 	f, stdout, _, _ := cmdutil.TestFactory(t, docsCreateTestConfig(t, ""))
 	err := runDocsCreateShortcut(t, f, stdout, []string{
 		"+create",
-		"--title", "项目计划",
 		"--markdown", "## 目标",
 		"--as", "user",
 	})
@@ -292,8 +291,7 @@ func TestDocsCreateRejectsLegacyV1Flags(t *testing.T) {
 	for _, want := range []string{
 		"docs +create is v2-only",
 		"the old v1 interface has been shut down",
-		"legacy v1 flag(s) --title, --markdown are no longer supported",
-		"--title -> put the title in --content",
+		"legacy v1 flag(s) --markdown are no longer supported",
 		"--markdown -> use --content with --doc-format markdown",
 		"lark-cli skills read lark-doc references/lark-doc-create.md",
 		"lark-cli skills read lark-doc references/lark-doc-xml.md",
diff --git a/shortcuts/doc/docs_create_v2.go b/shortcuts/doc/docs_create_v2.go
@@ -4,7 +4,9 @@
 package doc
 
 import (
+	"bytes"
 	"context"
+	"encoding/xml"
 	"strings"
 
 	"github.com/larksuite/cli/errs"
@@ -14,6 +16,7 @@ import (
 // v2CreateFlags returns the flag definitions for the v2 (OpenAPI) create path.
 func v2CreateFlags() []common.Flag {
 	return []common.Flag{
+		{Name: "title", Desc: "document title; when provided, the CLI prepends it to --content as <title>...</title> so the title wins over later content titles"},
 		{Name: "content", Desc: "document body; XML by default or Markdown when --doc-format markdown. " + docsContentSkillHelp + "; use --help for the latest command flags", Input: []string{common.File, common.Stdin}},
 		{Name: "doc-format", Desc: "content format; xml is default and supports richer DocxXML blocks, markdown imports plain Markdown", Default: "xml", Enum: []string{"xml", "markdown"}},
 		{Name: "parent-token", Desc: "parent folder token or wiki node token; mutually exclusive with --parent-position"},
@@ -25,8 +28,12 @@ func validateCreateV2(_ context.Context, runtime *common.RuntimeContext) error {
 	if err := validateDocsV2Only(runtime, "+create", docsCreateLegacyFlags()); err != nil {
 		return err
 	}
-	if runtime.Str("content") == "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--content is required").WithParam("--content")
+	title := strings.TrimSpace(runtime.Str("title"))
+	if runtime.Changed("title") && title == "" {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--title must not be empty").WithParam("--title")
+	}
+	if runtime.Str("content") == "" && title == "" {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--content is required unless --title is provided").WithParam("--content")
 	}
 	if runtime.Str("parent-token") != "" && runtime.Str("parent-position") != "" {
 		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--parent-token and --parent-position are mutually exclusive").WithParams(
@@ -66,7 +73,7 @@ func executeCreateV2(_ context.Context, runtime *common.RuntimeContext) error {
 func buildCreateBody(runtime *common.RuntimeContext) map[string]interface{} {
 	body := map[string]interface{}{
 		"format":  runtime.Str("doc-format"),
-		"content": runtime.Str("content"),
+		"content": buildCreateContent(runtime),
 	}
 	if v := runtime.Str("parent-token"); v != "" {
 		body["parent_token"] = v
@@ -78,6 +85,26 @@ func buildCreateBody(runtime *common.RuntimeContext) map[string]interface{} {
 	return body
 }
 
+func buildCreateContent(runtime *common.RuntimeContext) string {
+	content := runtime.Str("content")
+	title := strings.TrimSpace(runtime.Str("title"))
+	if title == "" {
+		return content
+	}
+
+	titleTag := "<title>" + escapeDocTitleText(title) + "</title>"
+	if content == "" {
+		return titleTag
+	}
+	return titleTag + "\n" + content
+}
+
+func escapeDocTitleText(title string) string {
+	var buf bytes.Buffer
+	_ = xml.EscapeText(&buf, []byte(title))
+	return buf.String()
+}
+
 // augmentDocsCreatePermission grants full_access to the current CLI user when
 // the document was created with bot identity.
 func augmentDocsCreatePermission(runtime *common.RuntimeContext, data map[string]interface{}) {
diff --git a/shortcuts/doc/docs_fetch_v2_test.go b/shortcuts/doc/docs_fetch_v2_test.go
@@ -40,6 +40,23 @@ func TestBuildCreateBodyIncludesSceneFromContext(t *testing.T) {
 	}
 }
 
+func TestBuildCreateBodyPrependsTitleToContent(t *testing.T) {
+	t.Parallel()
+
+	runtime := newCreateBodyTestRuntime(context.Background())
+	if err := runtime.Cmd.Flags().Set("title", "A & B <C>"); err != nil {
+		t.Fatalf("set title: %v", err)
+	}
+	if err := runtime.Cmd.Flags().Set("content", "## Body"); err != nil {
+		t.Fatalf("set content: %v", err)
+	}
+
+	body := buildCreateBody(runtime)
+	if got, want := body["content"], "<title>A &amp; B &lt;C&gt;</title>\n## Body"; got != want {
+		t.Fatalf("content = %#v, want %q", got, want)
+	}
+}
+
 func TestBuildUpdateBodyIncludesSceneFromContext(t *testing.T) {
 	t.Parallel()
 
@@ -351,6 +368,7 @@ func newFetchShortcutTestRuntime(t *testing.T, apiVersion string, setFlags map[s
 func newCreateBodyTestRuntime(ctx context.Context) *common.RuntimeContext {
 	cmd := &cobra.Command{Use: "+create"}
 	cmd.Flags().String("doc-format", "xml", "")
+	cmd.Flags().String("title", "", "")
 	cmd.Flags().String("content", "<title>hello</title>", "")
 	cmd.Flags().String("parent-token", "", "")
 	cmd.Flags().String("parent-position", "", "")
diff --git a/shortcuts/doc/v2_only.go b/shortcuts/doc/v2_only.go
@@ -25,7 +25,6 @@ func docsAPIVersionCompatFlag() common.Flag {
 
 func docsCreateLegacyFlags() []docsLegacyFlag {
 	return []docsLegacyFlag{
-		{Name: "title", Replacement: "put the title in --content, for example <title>Title</title>"},
 		{Name: "markdown", Replacement: "use --content with --doc-format markdown"},
 		{Name: "folder-token", Replacement: "use --parent-token"},
 		{Name: "wiki-node", Replacement: "use --parent-token"},
diff --git a/skills/lark-doc/SKILL.md b/skills/lark-doc/SKILL.md
@@ -17,7 +17,7 @@ metadata:
 ```bash
 # 常用示例
 lark-cli docs +fetch  --api-version v2 --doc "文档URL或token"
-lark-cli docs +create --api-version v2 --content '<title>标题</title><p>内容</p>'
+lark-cli docs +create --api-version v2 --title "标题" --content '<p>内容</p>'
 lark-cli docs +update --api-version v2 --doc "文档URL或token" --command append --content '<p>内容</p>'
 ```
 
diff --git a/skills/lark-doc/references/lark-doc-create.md b/skills/lark-doc/references/lark-doc-create.md
@@ -16,16 +16,16 @@
 
 ```bash
 # 创建 XML 文档（默认格式，推荐）
-lark-cli docs +create --api-version v2 --content '<title>项目计划</title><h1>目标</h1><ul><li>目标 1</li><li>目标 2</li></ul>'
+lark-cli docs +create --api-version v2 --title "项目计划" --content '<h1>目标</h1><ul><li>目标 1</li><li>目标 2</li></ul>'
 
 # 创建到指定文件夹（XML）
-lark-cli docs +create --api-version v2 --parent-token fldcnXXXX --content '<title>标题</title><p>首段内容</p>'
+lark-cli docs +create --api-version v2 --parent-token fldcnXXXX --title "标题" --content '<p>首段内容</p>'
 
 # 创建到个人知识库（XML）
-lark-cli docs +create --api-version v2 --parent-position my_library --content '<title>标题</title><p>内容</p>'
+lark-cli docs +create --api-version v2 --parent-position my_library --title "标题" --content '<p>内容</p>'
 
-# 仅当用户明确要求时才使用 Markdown；文档标题必须是开头唯一的一级标题，正文从二级标题开始
-lark-cli docs +create --api-version v2 --doc-format markdown --content $'# 项目计划\n\n## 目标\n\n- 目标 1\n- 目标 2'
+# 仅当用户明确要求时才使用 Markdown；文档标题用 --title，正文标题按内容自然组织
+lark-cli docs +create --api-version v2 --doc-format markdown --title "项目计划" --content $'## 目标\n\n- 目标 1\n- 目标 2'
 ```
 
 ## 返回值
@@ -66,15 +66,18 @@ lark-cli docs +create --api-version v2 --doc-format markdown --content $'# 项
 | 参数                  | 必填 | 说明                                          |
 | ------------------- | -- |---------------------------------------------|
 | `--api-version`     | 是  | 固定传 `v2`                                    |
-| `--content`         | 是  | 文档内容（XML 或 Markdown 格式）                     |
+| `--title`           | 否  | 文档标题；传入后 CLI 会在 `--content` 开头补 `<title>...</title>` |
+| `--content`         | 视情况 | 文档内容（XML 或 Markdown 格式）；不传 `--content` 时必须传 `--title` |
 | `--doc-format`      | 否  | 内容格式：`xml`（默认，始终优先使用）\| `markdown`（仅用户明确要求时） |
 | `--parent-token`    | 否  | 父文件夹或知识库节点 token（与 `--parent-position` 互斥）  |
 | `--parent-position` | 否  | 父节点位置，如 `my_library`（与 `--parent-token` 互斥） |
 
 ## 最佳实践
 
-- 文档标题从内容中自动提取：XML 使用 `<title>`；Markdown 使用文档开头唯一的一级标题（`# 标题`），正文从 `##` 开始。不要在内容开头重复写标题，也不要在 Markdown 正文中使用多个一级标题。
-- **创建较长的文档时只建骨架**：`--content` 仅传标题 + 各级 heading + 简短占位摘要；正文留给后续 `block_insert_after --block-id <章节标题 block_id>` 分段追加。一次性塞超长 `--content` 既容易触发参数限制，调试也更难。
+- 文档标题优先用 `--title`。CLI 会把它补成内容开头的 `<title>`；如果内容里又出现 `<title>`，SDK 会保留第一个标题并过滤后续标题，同时在 `warnings` / `degrade_details` 中提示。
+- XML 内容也可以直接写 `<title>`；但不要同时传 `--title` 和手写另一个 `<title>`，除非你明确接受后者被过滤。
+- Markdown 创建时用 `--title` 指定文档标题，不再要求正文开头必须是唯一一级标题；正文 heading 按内容自然组织即可。
+- **创建较长的文档时只建骨架**：用 `--title` 传文档标题，`--content` 仅传各级 heading + 简短占位摘要；正文留给后续 `block_insert_after --block-id <章节标题 block_id>` 分段追加。一次性塞超长 `--content` 既容易触发参数限制，调试也更难。
 - **表达形式**：由用户目标和内容决定。需要结构化表达时可参考 [`lark-doc-style.md`](style/lark-doc-style.md)，但不要默认套用固定开头、固定富 block 比例或固定图表
 
 ## 参考
diff --git a/skills/lark-doc/references/lark-doc-md.md b/skills/lark-doc/references/lark-doc-md.md
@@ -4,7 +4,15 @@
 
 ## 创建文档标题
 
-使用 `docs +create --doc-format markdown` 创建文档时，文档标题必须写成内容开头唯一的一级标题：`# 标题`。正文标题从 `##` 开始，不要使用多个一级标题；否则标题可能无法被提取并显示为 `Untitled`。
+使用 `docs +create --doc-format markdown` 创建文档时，优先用 `--title` 指定文档标题：
+
+```bash
+lark-cli docs +create --api-version v2 --doc-format markdown --title "项目计划" --content @content.md
+```
+
+CLI 会把 `--title` 注入为内容开头的 `<title>...</title>`。正文 Markdown 不再需要为了文档标题强制使用唯一一级标题；可以按内容自然使用 `#` / `##` 等 heading。
+
+如果 `--content` 中也包含 `<title>`，SDK 会以第一个 `<title>` 为准，过滤后续标题，并通过 `warnings` / `degrade_details` 告知有标题被过滤。
 
 ## 转义规则
 
diff --git a/skills/lark-doc/references/lark-doc-xml.md b/skills/lark-doc/references/lark-doc-xml.md
@@ -12,7 +12,7 @@ p, h1-h9, ul, ol, li, table, thead, tbody, tr, th, td, blockquote, pre, code, hr
 
 ## 创建文档标题
 
-使用 `docs +create` 创建 XML 文档时，文档标题必须写成 `<title>标题</title>`，且每篇文档只写一个 `<title>`。
+使用 `docs +create` 创建 XML 文档时，文档标题可以通过 `--title "标题"` 指定，也可以在内容开头写 `<title>标题</title>`。每篇文档只保留一个文档标题；如果出现多个 `<title>`，SDK 以第一个为准，过滤后续标题，并通过 `warnings` / `degrade_details` 提示。
 
 ## 容器标签
 |标签|说明|关键属性|
diff --git a/tests/cli_e2e/docs/coverage.md b/tests/cli_e2e/docs/coverage.md
@@ -10,14 +10,15 @@
 - TestDocs_CreateAndFetchWorkflowAsUser: proves the same shortcut pair with UAT injection via `create as user` and `fetch as user`; creates its own Drive folder fixture first, then reads back the created doc by token.
 - TestDocs_UpdateWorkflow: proves `docs +update` via `update-title-and-content as bot`, then re-fetches the same doc in `verify as bot` to assert persisted title/content changes.
 - TestDocs_DryRunDefaultsToV2OpenAPI: proves `docs +create`, `docs +fetch`, and `docs +update` dry-run all emit `/open-apis/docs_ai/v1/...` requests without MCP or `--api-version` guidance.
+- TestDocs_CreateTitleDryRunPrependsContent: proves `docs +create --title` dry-run prepends an escaped `<title>...</title>` tag to request body `content`.
 - Setup note: docs workflows create a Drive folder through `drive files create_folder` in `helpers_test.go`; that helper is external to the docs domain and is not counted here.
 - Blocked area: media and search shortcuts still need deterministic fixtures and local file orchestration.
 
 ## Command Table
 
 | Status | Cmd | Type | Testcase | Key parameter shapes | Notes / uncovered reason |
 | --- | --- | --- | --- | --- | --- |
-| ✓ | docs +create | shortcut | docs/helpers_test.go::createDocWithRetry; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflowAsUser/create as user; docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/create | `--parent-token`; `--doc-format markdown`; `--content` | helper asserts returned doc id from `data.document.document_id` |
+| ✓ | docs +create | shortcut | docs/helpers_test.go::createDocWithRetry; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflowAsUser/create as user; docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/create; docs_update_dryrun_test.go::TestDocs_CreateTitleDryRunPrependsContent | `--parent-token`; `--doc-format markdown`; `--content`; `--title` | helper asserts returned doc id from `data.document.document_id`; dry-run asserts title is prepended into request body content |
 | ✓ | docs +fetch | shortcut | docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflow/fetch as bot; docs_update_test.go::TestDocs_UpdateWorkflow/verify as bot; docs_create_fetch_test.go::TestDocs_CreateAndFetchWorkflowAsUser/fetch as user; docs_update_dryrun_test.go::TestDocs_DryRunDefaultsToV2OpenAPI/fetch | `--doc <docToken>`; `--doc-format markdown` | |
 | ✕ | docs +media-download | shortcut |  | none | no media fixture workflow yet |
 | ✕ | docs +media-insert | shortcut |  | none | requires deterministic upload fixture and rollback assertions |
diff --git a/tests/cli_e2e/docs/docs_update_dryrun_test.go b/tests/cli_e2e/docs/docs_update_dryrun_test.go
@@ -11,6 +11,7 @@ import (
 
 	clie2e "github.com/larksuite/cli/tests/cli_e2e"
 	"github.com/stretchr/testify/require"
+	"github.com/tidwall/gjson"
 )
 
 func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
@@ -106,3 +107,31 @@ func TestDocs_DryRunDefaultsToV2OpenAPI(t *testing.T) {
 		})
 	}
 }
+
+func TestDocs_CreateTitleDryRunPrependsContent(t *testing.T) {
+	// Fake creds are enough — dry-run short-circuits before any real API call.
+	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{
+			"docs", "+create",
+			"--title", "Dry Run & Title",
+			"--doc-format", "markdown",
+			"--content", "## Body",
+			"--dry-run",
+		},
+		DefaultAs: "bot",
+	})
+	require.NoError(t, err)
+	result.AssertExitCode(t, 0)
+
+	out := result.Stdout
+	require.Equal(t, "/open-apis/docs_ai/v1/documents", gjson.Get(out, "api.0.url").String(), "stdout:\n%s", out)
+	require.Equal(t, "markdown", gjson.Get(out, "api.0.body.format").String(), "stdout:\n%s", out)
+	require.Equal(t, "<title>Dry Run &amp; Title</title>\n## Body", gjson.Get(out, "api.0.body.content").String(), "stdout:\n%s", out)
+}

Original file line number	Diff line number	Diff line change
`@@ -203,6 +203,13 @@ func TestValidateCreateV2Contract(t *testing.T) {`
`203`	`203`	`}`
`204`	`204`	`}`
`205`	`205`
	`206`	`+func TestValidateCreateV2AllowsTitleWithoutContent(t *testing.T) {`
	`207`	`+ rt := docValidateRuntime(t, map[string]string{"title": "Only Title"}, nil, nil)`
	`208`	`+ if err := validateCreateV2(context.Background(), rt); err != nil {`
	`209`	`+ t.Fatalf("validateCreateV2() error = %v, want nil", err)`
	`210`	`+ }`
	`211`	`+}`
	`212`	`+`
`206`	`213`	`func TestValidateFetchV2Contract(t *testing.T) {`
`207`	`214`	`cases := []struct {`
`208`	`215`	`name string`