From 0ed63b02e41e5be7ec5c25cf01c4faa3545f9f45 Mon Sep 17 00:00:00 2001
From: SunPeiYang996 <sunpeiyang.996@bytedance.com>
Date: Mon, 11 May 2026 14:35:00 +0800
Subject: [PATCH] chore(doc): inject docs scene into v2 requests (#808)

Change-Id: I4f23880e24164c8b229a5403942bfa1b7ddb0ce6
---
 shortcuts/doc/docs_create_v2.go     |  1 +
 shortcuts/doc/docs_fetch_v2.go      |  1 +
 shortcuts/doc/docs_fetch_v2_test.go | 95 +++++++++++++++++++++++++++++
 shortcuts/doc/docs_update_v2.go     |  1 +
 shortcuts/doc/helpers.go            | 19 ++++++
 5 files changed, 117 insertions(+)
 create mode 100644 shortcuts/doc/docs_fetch_v2_test.go

diff --git a/shortcuts/doc/docs_create_v2.go b/shortcuts/doc/docs_create_v2.go
index 413c4cbf..68ae824c 100644
--- a/shortcuts/doc/docs_create_v2.go
+++ b/shortcuts/doc/docs_create_v2.go
@@ -67,6 +67,7 @@ func buildCreateBody(runtime *common.RuntimeContext) map[string]interface{} {
 	if v := runtime.Str("parent-position"); v != "" {
 		body["parent_position"] = v
 	}
+	injectDocsScene(runtime, body)
 	return body
 }
 
diff --git a/shortcuts/doc/docs_fetch_v2.go b/shortcuts/doc/docs_fetch_v2.go
index 0b3eaee3..f5a0df2c 100644
--- a/shortcuts/doc/docs_fetch_v2.go
+++ b/shortcuts/doc/docs_fetch_v2.go
@@ -109,6 +109,7 @@ func buildFetchBody(runtime *common.RuntimeContext) map[string]interface{} {
 	if ro := buildReadOption(runtime); ro != nil {
 		body["read_option"] = ro
 	}
+	injectDocsScene(runtime, body)
 
 	return body
 }
diff --git a/shortcuts/doc/docs_fetch_v2_test.go b/shortcuts/doc/docs_fetch_v2_test.go
new file mode 100644
index 00000000..5a3294c9
--- /dev/null
+++ b/shortcuts/doc/docs_fetch_v2_test.go
@@ -0,0 +1,95 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package doc
+
+import (
+	"context"
+	"testing"
+
+	"github.com/larksuite/cli/shortcuts/common"
+	"github.com/spf13/cobra"
+)
+
+func TestBuildFetchBodyIncludesSceneFromContext(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.WithValue(context.Background(), docsSceneContextKey, " DoubaoCLI ")
+	runtime := newFetchBodyTestRuntime(ctx)
+
+	body := buildFetchBody(runtime)
+	if got := body["scene"]; got != "DoubaoCLI" {
+		t.Fatalf("scene = %#v, want %q", got, "DoubaoCLI")
+	}
+}
+
+func TestBuildCreateBodyIncludesSceneFromContext(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.WithValue(context.Background(), docsSceneContextKey, "DoubaoCLI")
+	runtime := newCreateBodyTestRuntime(ctx)
+
+	body := buildCreateBody(runtime)
+	if got := body["scene"]; got != "DoubaoCLI" {
+		t.Fatalf("scene = %#v, want %q", got, "DoubaoCLI")
+	}
+}
+
+func TestBuildUpdateBodyIncludesSceneFromContext(t *testing.T) {
+	t.Parallel()
+
+	ctx := context.WithValue(context.Background(), docsSceneContextKey, "DoubaoCLI")
+	runtime := newUpdateBodyTestRuntime(ctx)
+
+	body := buildUpdateBody(runtime)
+	if got := body["scene"]; got != "DoubaoCLI" {
+		t.Fatalf("scene = %#v, want %q", got, "DoubaoCLI")
+	}
+}
+
+func TestBuildFetchBodyOmitsEmptyScene(t *testing.T) {
+	t.Parallel()
+
+	runtime := newFetchBodyTestRuntime(context.Background())
+
+	body := buildFetchBody(runtime)
+	if _, ok := body["scene"]; ok {
+		t.Fatalf("did not expect empty scene in fetch body: %#v", body)
+	}
+}
+
+func newFetchBodyTestRuntime(ctx context.Context) *common.RuntimeContext {
+	cmd := &cobra.Command{Use: "+fetch"}
+	cmd.Flags().String("doc-format", "xml", "")
+	cmd.Flags().String("detail", "simple", "")
+	cmd.Flags().Int("revision-id", -1, "")
+	cmd.Flags().String("scope", "full", "")
+	cmd.Flags().String("start-block-id", "", "")
+	cmd.Flags().String("end-block-id", "", "")
+	cmd.Flags().String("keyword", "", "")
+	cmd.Flags().Int("context-before", 0, "")
+	cmd.Flags().Int("context-after", 0, "")
+	cmd.Flags().Int("max-depth", -1, "")
+	return common.TestNewRuntimeContextWithCtx(ctx, cmd, nil)
+}
+
+func newCreateBodyTestRuntime(ctx context.Context) *common.RuntimeContext {
+	cmd := &cobra.Command{Use: "+create"}
+	cmd.Flags().String("doc-format", "xml", "")
+	cmd.Flags().String("content", "<title>hello</title>", "")
+	cmd.Flags().String("parent-token", "", "")
+	cmd.Flags().String("parent-position", "", "")
+	return common.TestNewRuntimeContextWithCtx(ctx, cmd, nil)
+}
+
+func newUpdateBodyTestRuntime(ctx context.Context) *common.RuntimeContext {
+	cmd := &cobra.Command{Use: "+update"}
+	cmd.Flags().String("doc-format", "xml", "")
+	cmd.Flags().String("command", "append", "")
+	cmd.Flags().Int("revision-id", 0, "")
+	cmd.Flags().String("content", "<p>hello</p>", "")
+	cmd.Flags().String("pattern", "", "")
+	cmd.Flags().String("block-id", "", "")
+	cmd.Flags().String("src-block-ids", "", "")
+	return common.TestNewRuntimeContextWithCtx(ctx, cmd, nil)
+}
diff --git a/shortcuts/doc/docs_update_v2.go b/shortcuts/doc/docs_update_v2.go
index 62b1f0cb..8501be01 100644
--- a/shortcuts/doc/docs_update_v2.go
+++ b/shortcuts/doc/docs_update_v2.go
@@ -162,5 +162,6 @@ func buildUpdateBody(runtime *common.RuntimeContext) map[string]interface{} {
 	if v := runtime.Str("src-block-ids"); v != "" {
 		body["src_block_ids"] = v
 	}
+	injectDocsScene(runtime, body)
 	return body
 }
diff --git a/shortcuts/doc/helpers.go b/shortcuts/doc/helpers.go
index 2538e439..c3446d3b 100644
--- a/shortcuts/doc/helpers.go
+++ b/shortcuts/doc/helpers.go
@@ -4,6 +4,7 @@
 package doc
 
 import (
+	"context"
 	"encoding/json"
 	"strings"
 
@@ -11,6 +12,10 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
+// docsSceneContextKey lets in-process embedders pass a server-owned docs_ai
+// scene without exposing it as a user-controlled CLI flag.
+const docsSceneContextKey = "lark_cli_docs_scene"
+
 type documentRef struct {
 	Kind  string
 	Token string
@@ -65,6 +70,20 @@ func doDocAPI(runtime *common.RuntimeContext, method, apiPath string, body inter
 	return runtime.DoAPIJSONWithLogID(method, apiPath, nil, body)
 }
 
+func docsSceneFromContext(ctx context.Context) string {
+	if ctx == nil {
+		return ""
+	}
+	scene, _ := ctx.Value(docsSceneContextKey).(string)
+	return strings.TrimSpace(scene)
+}
+
+func injectDocsScene(runtime *common.RuntimeContext, body map[string]interface{}) {
+	if scene := docsSceneFromContext(runtime.Ctx()); scene != "" {
+		body["scene"] = scene
+	}
+}
+
 func buildDriveRouteExtra(docID string) (string, error) {
 	extra, err := json.Marshal(map[string]string{"drive_route_token": docID})
 	if err != nil {