docs(wiki): address node routing review feedback

* feat(apps): add cache debug commands (+cache-get/-delete/-clear)

Add three apps-domain cache debug shortcuts for inspecting/clearing an app's
runtime cache:
- +cache-get: read a business key's value + metadata (hit/miss)
- +cache-delete: delete a single key (idempotent, write)
- +cache-clear: clear all cache in an environment (high-risk-write, --yes)

value renders raw on --format json, deserialized on --format pretty;
value_size_bytes is computed CLI-side; --environment auto-selects the branch
when omitted. Includes unit tests (hit/miss/dry-run/confirmation) and the
lark-apps cache skill reference.

* fix(apps): normalize cache numeric output fields and tidy comments

Follow-up hardening for the cache debug commands (+cache-get/-delete/-clear):

- Normalize ttl_ms / deleted_key_count via a new cacheInt() helper so
  --format json emits a stable JSON number (or null) regardless of whether
  the server sends the value as a number or a string. Aligns with the
  repo convention that numeric wire fields may arrive as strings; previously
  these were passed through raw, leaving the output type at the server's mercy.
- Add unit tests locking the string-wire -> JSON number contract for both
  cache-get ttl_ms and cache-delete deleted_key_count.
- Tidy two comments: soften cacheBool's speculative "historical wire form"
  claim to a defensive-tolerance note, and drop implementation jargon from
  cache-delete's risk-level rationale.

.github/CODEOWNERS

@@ -1,4 +1,7 @@
+/go.mod @liangshuo-1
+/go.sum @liangshuo-1
 /internal/ @liangshuo-1
+/shortcuts/common/ @liangshuo-1
 
 # Last match wins: existing domains below are exempt, only new skills/ entries need review.
 /skills/ @liangshuo-1

.github/workflows/ci.yml

@@ -99,22 +99,6 @@ jobs:
       - name: Run tests
         run: go test -v -race -count=1 -timeout=5m ./cmd/... ./internal/... ./shortcuts/... ./extension/...
 
-  windows-compat:
-    needs: fast-gate
-    runs-on: windows-latest
-    steps:
-      - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
-      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
-        with:
-          go-version-file: go.mod
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
-        with:
-          python-version: '3.x'
-      - name: Fetch meta data
-        run: python scripts/fetch_meta.py
-      - name: Run Windows compatibility tests
-        run: go test -count=1 -timeout=5m . ./shortcuts/doc/...
-
   lint:
     needs: fast-gate
     runs-on: ubuntu-latest

.github/workflows/semantic-review.yml

@@ -25,19 +25,16 @@ jobs:
         with:
           script: |
             const run = context.payload.workflow_run;
-            if (run.name !== "CI") throw new Error(`unexpected workflow name: ${run.name}`);
-            let workflowPath = run.path || "";
-            if (!workflowPath) {
-              const workflowId = Number(run.workflow_id || 0);
-              if (!Number.isInteger(workflowId) || workflowId <= 0) throw new Error("missing workflow id");
-              const { data: workflow } = await github.rest.actions.getWorkflow({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                workflow_id: workflowId,
-              });
-              workflowPath = workflow.path || "";
-            }
-            if (workflowPath !== ".github/workflows/ci.yml") throw new Error(`unexpected workflow path: ${workflowPath}`);
+            const workflowId = Number(run.workflow_id || 0);
+            if (!Number.isInteger(workflowId) || workflowId <= 0) throw new Error("missing workflow id");
+            const { data: workflow } = await github.rest.actions.getWorkflow({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              workflow_id: workflowId,
+            });
+            if (workflow.name !== "CI") throw new Error(`unexpected workflow name: ${workflow.name}`);
+            if (workflow.path !== ".github/workflows/ci.yml") throw new Error(`unexpected workflow path: ${workflow.path}`);
+            if (run.path && run.path !== workflow.path) throw new Error(`workflow path mismatch: ${run.path}`);
             if (run.event !== "pull_request") throw new Error(`unexpected event: ${run.event}`);
             if (run.repository.id !== context.payload.repository.id) throw new Error("repository id mismatch");
             if (run.repository.full_name !== context.payload.repository.full_name) throw new Error("repository name mismatch");
@@ -253,19 +250,16 @@ jobs:
         with:
           script: |
             const run = context.payload.workflow_run;
-            if (run.name !== "CI") throw new Error(`unexpected workflow name: ${run.name}`);
-            let workflowPath = run.path || "";
-            if (!workflowPath) {
-              const workflowId = Number(run.workflow_id || 0);
-              if (!Number.isInteger(workflowId) || workflowId <= 0) throw new Error("missing workflow id");
-              const { data: workflow } = await github.rest.actions.getWorkflow({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                workflow_id: workflowId,
-              });
-              workflowPath = workflow.path || "";
-            }
-            if (workflowPath !== ".github/workflows/ci.yml") throw new Error(`unexpected workflow path: ${workflowPath}`);
+            const workflowId = Number(run.workflow_id || 0);
+            if (!Number.isInteger(workflowId) || workflowId <= 0) throw new Error("missing workflow id");
+            const { data: workflow } = await github.rest.actions.getWorkflow({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              workflow_id: workflowId,
+            });
+            if (workflow.name !== "CI") throw new Error(`unexpected workflow name: ${workflow.name}`);
+            if (workflow.path !== ".github/workflows/ci.yml") throw new Error(`unexpected workflow path: ${workflow.path}`);
+            if (run.path && run.path !== workflow.path) throw new Error(`workflow path mismatch: ${run.path}`);
             if (run.event !== "pull_request") throw new Error(`unexpected event: ${run.event}`);
             if (run.conclusion !== "success") throw new Error(`unexpected conclusion: ${run.conclusion}`);
             if (run.repository.id !== context.payload.repository.id) throw new Error("repository id mismatch");

.gitignore

@@ -42,7 +42,6 @@ tests/mail/reports/
 
 # Generated / test artifacts
 .hammer/
-.lark-cli-e2e-test/reports/
 .lark-slides/
 /notes/
 /minutes/

CHANGELOG.md

@@ -2,6 +2,90 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.80] - 2026-07-29
+
+### Features
+
+- **drive**: add +member-list shortcut (#1795)
+- **drive**: add +permission-get-setting shortcut (#1738)
+- propagate invocation metadata (#2097)
+
+### Documentation
+
+- **slides**: 补齐 shortcut 参数说明，修正 +xml-get --output 必填标注 (#2088)
+- **slides**: +create 的参数下沉到 create.md，主 skill 只留路由 (#2096)
+
+### Tests
+
+- **e2e**: wait for base role update visibility (#2087)
+
+### Misc
+
+- Feat/detect line text overlap (#2069)
+
+## [v1.0.79] - 2026-07-28
+
+### Features
+
+- **slides**: update xsd (#2067)
+
+### Bug Fixes
+
+- **ci**: validate static workflow identity (#2015)
+- **sheets**: recognize OFL0X local office tokens (#2063)
+
+### Documentation
+
+- **calendar**: clarify identity selection by event ownership (#2071)
+- **slides**: add formula inline element syntax to quick-ref (#2077)
+
+## [v1.0.78] - 2026-07-27
+
+### Features
+
+- event description support rich text (#1975)
+
+### Bug Fixes
+
+- **slides**: restrict canvas overflow checks
+- **slides**: upgrade text overflow to error above 10px threshold
+- **slides**: detect letterSpacing-driven text overflow
+- **slides**: downgrade background-decoration text overflow to info
+- **slides**: allow chartParsedValues roundtrip tag
+- refine character width estimation for lark-slides text lint
+- **slides**: preserve info lint severity
+- **slides**: text may over flow shape
+- exempt ghost text from slides lint
+
+## [v1.0.77] - 2026-07-24
+
+### Features
+
+- introducing official card icon (#1973)
+- **apps**: validate +file-list --page-size against server (0, 200] range (#2007)
+- **apps**: support absolute and relative upload paths (#2005)
+- **slides**: fill xml-schema-quick-ref gaps that forced XSD fallback (#2026)
+- **slides**: add layout density lint for sparse/empty containers (#2022)
+- add risk-control protection (#1910)
+
+### Bug Fixes
+
+- **slides**: normalize presentation flag aliases (#2032)
+- **base**: classify +form-submit as high-risk-write (#1969)
+- **slides**: declare screenshot scope
+- **slides**: support CSV multi-value for --slide-id in screenshot (#2047)
+
+### Documentation
+
+- **skill**: clarify scope handling for query expansion (#2030)
+- **base**: clarify complete and partial updates (#1993)
+- **skills**: clarify callout child rules (#2048)
+
+### Misc
+
+- fix/task id handling (#2023)
+- fix/task search pagination (#2041)
+
 ## [v1.0.75] - 2026-07-22
 
 ### Features
@@ -1638,6 +1722,10 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.80]: https://github.com/larksuite/cli/releases/tag/v1.0.80
+[v1.0.79]: https://github.com/larksuite/cli/releases/tag/v1.0.79
+[v1.0.78]: https://github.com/larksuite/cli/releases/tag/v1.0.78
+[v1.0.77]: https://github.com/larksuite/cli/releases/tag/v1.0.77
 [v1.0.75]: https://github.com/larksuite/cli/releases/tag/v1.0.75
 [v1.0.74]: https://github.com/larksuite/cli/releases/tag/v1.0.74
 [v1.0.73]: https://github.com/larksuite/cli/releases/tag/v1.0.73

README.md

@@ -285,6 +285,29 @@ To reduce these risks, the tool enables default security protections at multiple
 
 We recommend using the Lark/Feishu bot integrated with this tool as a private conversational assistant. Do not add it to group chats or allow other users to interact with it, to avoid abuse of permissions or data leakage.
 
+To reduce the security risks associated with access token theft, the CLI sends a minimal set of risk-control signals with OpenAPI requests made to exact official Feishu/Lark HTTPS domains. These signals are used to help identify anomalous API activity. This protection is enabled by default. The information sent is limited to:
+
+- Operating system type: macOS, Windows, or Linux
+- Device hardware model: for example, Mac17,9
+
+To disable this protection for the current workspace, run:
+
+```bash
+lark-cli config risk-control off
+```
+
+To enable this protection for the current workspace, run:
+
+```bash
+lark-cli config risk-control on
+```
+
+To restore the default policy for the current workspace, run:
+
+```bash
+lark-cli config risk-control default
+```
+
 Please fully understand all usage risks. By using this tool, you are deemed to voluntarily assume all related responsibilities.
 
 ## Star History

README.zh.md

@@ -286,6 +286,29 @@ lark-cli schema im.messages.delete
 
 我们建议您将对接本工具的飞书机器人作为私人对话助手使用，请勿将其拉入群聊或允许其他用户与其交互，以避免权限被滥用或数据泄露。
 
+为降低访问令牌被盗用后的安全风险，CLI 在向飞书/Lark 官方 HTTPS 精确域名发起 OpenAPI 请求时，会随请求发送一组最小化的风控信号，用于辅助识别异常调用行为。该保护默认开启，发送的信息仅包括：
+
+- 操作系统类型：macOS、Windows 或 Linux
+- 设备的硬件产品型号：例如 Mac17,9
+
+如需让当前 workspace 退出该保护，可执行以下命令：
+
+```bash
+lark-cli config risk-control off
+```
+
+如需开启当前 workspace 的保护，可执行以下命令：
+
+```bash
+lark-cli config risk-control on
+```
+
+恢复当前 workspace 默认策略可执行：
+
+```bash
+lark-cli config risk-control default
+```
+
 请您充分知悉全部使用风险，使用本工具即视为您自愿承担相关所有责任。
 
 ## Star History

affordance/contact.md

@@ -23,6 +23,41 @@ lark-cli contact +search-user --query "alice" --as user
 lark-cli contact +search-user --user-ids "ou_3a8b****6a7b,me" --as user
 ```
 
+## +search-bot
+Search bots (apps) by keyword. Pass `--query` or `--queries`; use `--chat-ids` to search within specific chats.
+
+### Skills
+- lark-contact/references/lark-contact-search-bot.md
+
+### Avoid when
+- Looking for a person rather than a bot → use [[+search-user]]
+- Running as a bot — this shortcut is user-only
+
+### Tips
+- `has_more=true` means the search is incomplete; refine the keyword or search scope instead of paginating
+
+### Examples
+
+**Find bots by keyword**
+```bash
+lark-cli contact +search-bot --query "会议助手" --as user
+```
+
+**Search inside one chat**
+```bash
+lark-cli contact +search-bot --query "助手" --chat-ids "oc_3a8b****6a7b" --as user
+```
+
+**Find bots you've chatted with**
+```bash
+lark-cli contact +search-bot --query "助手" --has-chatted --as user
+```
+
+**Search several bot keywords in one call**
+```bash
+lark-cli contact +search-bot --queries "会议助手,日报助手,审批助手" --as user
+```
+
 ## +get-user
 Fetch one user's profile by id, or your own with --user-id omitted. Use it under bot identity — `+search-user` is user-only.
 

cmd/build_bench_test.go

@@ -1,105 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package cmd
-
-import (
-	"context"
-	"runtime"
-	"testing"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/spf13/cobra"
-	"github.com/spf13/pflag"
-)
-
-// BenchmarkBuild_Default measures the per-Build cost for the default
-// configuration (service commands + shortcuts + plugins + strict mode).
-// This is the hot-path baseline for repeated Build invocations.
-func BenchmarkBuild_Default(b *testing.B) {
-	// Warm one-time caches first
-	_ = Build(context.Background(), cmdutil.InvocationContext{})
-	runtime.GC()
-
-	b.ResetTimer()
-	b.ReportAllocs()
-	for i := 0; i < b.N; i++ {
-		_ = Build(context.Background(), cmdutil.InvocationContext{})
-	}
-}
-
-// BenchmarkBuild_WithoutServiceCommands measures the Build cost without
-// service command registration. The delta from Default gives the
-// service-command registration cost.
-func BenchmarkBuild_WithoutServiceCommands(b *testing.B) {
-	_ = Build(context.Background(), cmdutil.InvocationContext{}, WithoutServiceCommands())
-	runtime.GC()
-
-	b.ResetTimer()
-	b.ReportAllocs()
-	for i := 0; i < b.N; i++ {
-		_ = Build(context.Background(), cmdutil.InvocationContext{}, WithoutServiceCommands())
-	}
-}
-
-// BenchmarkBuild_WithoutPlugins measures the Build cost without plugins.
-// The delta from Default gives the plugin + policy + hook cost.
-func BenchmarkBuild_WithoutPlugins(b *testing.B) {
-	_ = Build(context.Background(), cmdutil.InvocationContext{}, WithoutPlugins())
-	runtime.GC()
-
-	b.ResetTimer()
-	b.ReportAllocs()
-	for i := 0; i < b.N; i++ {
-		_ = Build(context.Background(), cmdutil.InvocationContext{}, WithoutPlugins())
-	}
-}
-
-// BenchmarkBuild_WithoutServiceAndPlugins measures the Build cost with
-// neither service commands nor plugins. This isolates the base cost
-// (root command + builtins + shortcuts).
-func BenchmarkBuild_WithoutServiceAndPlugins(b *testing.B) {
-	_ = Build(context.Background(), cmdutil.InvocationContext{}, WithoutServiceCommands(), WithoutPlugins())
-	runtime.GC()
-
-	b.ResetTimer()
-	b.ReportAllocs()
-	for i := 0; i < b.N; i++ {
-		_ = Build(context.Background(), cmdutil.InvocationContext{}, WithoutServiceCommands(), WithoutPlugins())
-	}
-}
-
-// TestBuild_CommandTreeStats counts the total number of commands,
-// runnable commands, and flags in the default build. This gives us
-// the scale of the command tree to reason about optimization targets.
-func TestBuild_CommandTreeStats(t *testing.T) {
-	root := Build(context.Background(), cmdutil.InvocationContext{}, WithoutPlugins())
-
-	var totalCmds, runnableCmds, groupCmds int
-	var totalFlags int
-
-	var walk func(cmd *cobra.Command)
-	walk = func(cmd *cobra.Command) {
-		totalCmds++
-		if cmd.RunE != nil || cmd.Run != nil {
-			runnableCmds++
-		} else {
-			groupCmds++
-		}
-		if cmd.Flags() != nil {
-			cmd.Flags().VisitAll(func(f *pflag.Flag) {
-				totalFlags++
-			})
-		}
-		for _, child := range cmd.Commands() {
-			walk(child)
-		}
-	}
-	walk(root)
-
-	t.Logf("Command tree stats:")
-	t.Logf("  Total commands: %d", totalCmds)
-	t.Logf("  Runnable commands: %d", runnableCmds)
-	t.Logf("  Group commands: %d", groupCmds)
-	t.Logf("  Total flags: %d", totalFlags)
-}

cmd/config/config.go

@@ -31,6 +31,7 @@ func NewCmdConfig(f *cmdutil.Factory) *cobra.Command {
 	cmd.AddCommand(NewCmdConfigShow(f, nil))
 	cmd.AddCommand(NewCmdConfigDefaultAs(f))
 	cmd.AddCommand(NewCmdConfigStrictMode(f))
+	cmd.AddCommand(NewCmdConfigRiskControl(f))
 	cmd.AddCommand(NewCmdConfigPolicy(f))
 	cmd.AddCommand(NewCmdConfigPlugins(f))
 	cmd.AddCommand(NewCmdConfigKeychainDowngrade(f))

cmd/config/risk_control.go

@@ -0,0 +1,80 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package config
+
+import (
+	"fmt"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+)
+
+// NewCmdConfigRiskControl creates the workspace risk-control policy command.
+func NewCmdConfigRiskControl(f *cmdutil.Factory) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "risk-control [on|off|default]",
+		Short: "Manage workspace account-protection policy",
+		Long: `View or set the account-protection risk-control policy for this workspace.
+
+Account protection is on by default. Use off to opt this workspace out, on to
+opt it back in explicitly, or default to remove the explicit preference.`,
+		Args: cobra.MaximumNArgs(1),
+		// This is persistent workspace policy, not credential management.
+		PersistentPreRunE: func(cmd *cobra.Command, _ []string) error {
+			cmd.SilenceUsage = true
+			return nil
+		},
+		RunE: func(cmd *cobra.Command, args []string) error {
+			config, err := core.LoadOrNotConfigured()
+			if err != nil {
+				return err
+			}
+			if len(args) == 0 {
+				printRiskControl(f, config)
+				return nil
+			}
+
+			switch args[0] {
+			case "on":
+				enabled := true
+				config.RiskControl = &enabled
+			case "off":
+				enabled := false
+				config.RiskControl = &enabled
+			case "default":
+				config.RiskControl = nil
+			default:
+				return errs.NewValidationError(errs.SubtypeInvalidArgument,
+					"invalid risk-control value %q, valid values: on | off | default", args[0])
+			}
+
+			if err := core.SaveMultiAppConfig(config); err != nil {
+				return errs.NewInternalError(errs.SubtypeStorage,
+					"failed to save risk-control policy: %v", err).WithCause(err)
+			}
+			fmt.Fprintf(f.IOStreams.ErrOut, "Risk control set to %s (workspace)\n", args[0])
+			return nil
+		},
+	}
+	cmdutil.SetRisk(cmd, cmdutil.RiskWrite)
+	return cmd
+}
+
+func printRiskControl(f *cmdutil.Factory, config *core.MultiAppConfig) {
+	source := "default"
+	if config.RiskControl != nil {
+		source = "workspace"
+	}
+	fmt.Fprintf(f.IOStreams.Out, "risk-control: %s (source: %s)\n", riskControlState(config.RiskControlEnabled()), source)
+}
+
+func riskControlState(enabled bool) string {
+	if enabled {
+		return "on"
+	}
+	return "off"
+}

cmd/config/risk_control_test.go

@@ -0,0 +1,130 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package config
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+)
+
+func TestRiskControlWorkspacePolicy(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	config := &core.MultiAppConfig{Apps: []core.AppConfig{{
+		AppId: "cli_test", AppSecret: core.PlainSecret("secret"), Brand: core.BrandFeishu,
+	}}}
+	if err := core.SaveMultiAppConfig(config); err != nil {
+		t.Fatal(err)
+	}
+
+	f, stdout, stderr, _ := cmdutil.TestFactory(t, nil)
+	cmd := NewCmdConfigRiskControl(f)
+	cmd.SetArgs([]string{"off"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("set off: %v", err)
+	}
+	loaded, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if loaded.RiskControl == nil || *loaded.RiskControl {
+		t.Fatalf("RiskControl = %v, want explicit false", loaded.RiskControl)
+	}
+	if !strings.Contains(stderr.String(), "set to off") {
+		t.Fatalf("stderr = %q", stderr.String())
+	}
+
+	stdout.Reset()
+	cmd = NewCmdConfigRiskControl(f)
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("show: %v", err)
+	}
+	if got := stdout.String(); got != "risk-control: off (source: workspace)\n" {
+		t.Fatalf("stdout = %q", got)
+	}
+
+	cmd = NewCmdConfigRiskControl(f)
+	cmd.SetArgs([]string{"on"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("set on: %v", err)
+	}
+	loaded, err = core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if loaded.RiskControl == nil || !*loaded.RiskControl {
+		t.Fatalf("RiskControl = %v, want explicit true", loaded.RiskControl)
+	}
+
+	cmd = NewCmdConfigRiskControl(f)
+	cmd.SetArgs([]string{"default"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("reset default: %v", err)
+	}
+	loaded, err = core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if loaded.RiskControl != nil {
+		t.Fatalf("RiskControl = %v, want nil", loaded.RiskControl)
+	}
+
+	stdout.Reset()
+	cmd = NewCmdConfigRiskControl(f)
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("show default: %v", err)
+	}
+	if got := stdout.String(); got != "risk-control: on (source: default)\n" {
+		t.Fatalf("stdout = %q", got)
+	}
+}
+
+func TestRiskControlWorkspacePolicyRejectsInvalidValue(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+	if err := core.SaveMultiAppConfig(&core.MultiAppConfig{Apps: []core.AppConfig{{
+		AppId: "cli_test", AppSecret: core.PlainSecret("secret"), Brand: core.BrandFeishu,
+	}}}); err != nil {
+		t.Fatal(err)
+	}
+
+	f, _, _, _ := cmdutil.TestFactory(t, nil)
+	cmd := NewCmdConfigRiskControl(f)
+	cmd.SetArgs([]string{"invalid"})
+	err := cmd.Execute()
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("error = %T %v, want *errs.ValidationError", err, err)
+	}
+	if validationErr.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("subtype = %q, want %q", validationErr.Subtype, errs.SubtypeInvalidArgument)
+	}
+}
+
+func TestRiskControlWorkspacePolicyAllowedWithExternalCredentials(t *testing.T) {
+	f := newConfigFactoryWithExternalProvider(t)
+	config := &core.MultiAppConfig{Apps: []core.AppConfig{{
+		AppId: "cli_test", AppSecret: core.PlainSecret("secret"), Brand: core.BrandFeishu,
+	}}}
+	if err := core.SaveMultiAppConfig(config); err != nil {
+		t.Fatal(err)
+	}
+
+	cmd := NewCmdConfig(f)
+	cmd.SetArgs([]string{"risk-control", "off"})
+	if err := cmd.Execute(); err != nil {
+		t.Fatalf("set off with external credentials: %v", err)
+	}
+
+	loaded, err := core.LoadMultiAppConfig()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if loaded.RiskControl == nil || *loaded.RiskControl {
+		t.Fatalf("RiskControl = %v, want explicit false", loaded.RiskControl)
+	}
+}

cmd/root_upgrade.go

@@ -65,7 +65,17 @@ func offerRootUpgrade(f *cmdutil.Factory, cmd *cobra.Command) {
 	if info == nil {
 		return
 	}
-	fmt.Fprintf(ios.ErrOut, "lark-cli %s available (current %s). Upgrade now? [y/N]: ", info.Latest, info.Current)
+	// Deliberately no target version here: info.Latest comes from the on-disk
+	// cache, which has no expiry (the 24h TTL only throttles refreshes, and a
+	// failed refresh leaves the old value in place), so it can name a version
+	// that is no longer the one npm would install. The version actually
+	// installed is resolved live by the update subcommand, which prints
+	// "Updating lark-cli <cur> -> <latest> via <pm> ..." before installing —
+	// that is where the user sees the real target. Keep going through the
+	// update subcommand rather than calling RunNpmInstall directly, otherwise
+	// that line disappears and the user approves a global install without ever
+	// being told what gets installed.
+	fmt.Fprintf(ios.ErrOut, "A newer lark-cli is available (current %s). Upgrade now? [y/N]: ", info.Current)
 	if !readYes(ios.In) {
 		return
 	}

cmd/root_upgrade_test.go

@@ -128,6 +128,17 @@ func TestOfferRootUpgrade(t *testing.T) {
 			if gotPrompt != tc.wantPrompt {
 				t.Errorf("prompt: got %v want %v (stderr=%q)", gotPrompt, tc.wantPrompt, errBuf.String())
 			}
+			// The prompt must not name a target version: info.Latest comes from
+			// the on-disk cache and can be stale, while the version actually
+			// installed is resolved live by the update subcommand.
+			if tc.wantPrompt {
+				if strings.Contains(errBuf.String(), tc.latest) {
+					t.Errorf("prompt must not name the cached target version %q (stderr=%q)", tc.latest, errBuf.String())
+				}
+				if !strings.Contains(errBuf.String(), build.Version) {
+					t.Errorf("prompt must name the current version %q (stderr=%q)", build.Version, errBuf.String())
+				}
+			}
 			if called != tc.wantRun {
 				t.Errorf("runRootUpgrade called: got %v want %v", called, tc.wantRun)
 			}

extension/fileio/types.go

@@ -42,15 +42,6 @@ type FileIO interface {
 	Save(path string, opts SaveOptions, body io.Reader) (SaveResult, error)
 }
 
-// TempDirFileCreator is an optional FileIO capability for atomically creating
-// a unique directory and an empty named file inside it. The directory pattern
-// follows os.MkdirTemp semantics: the last '*' is replaced with a random
-// value. Implementations return a relative file path that can be passed back
-// to FileIO.
-type TempDirFileCreator interface {
-	CreateTempDirFile(directoryPattern, fileName string) (string, error)
-}
-
 // FileInfo is a minimal subset of os.FileInfo covering actual CLI usage.
 // os.FileInfo satisfies this interface.
 type FileInfo interface {

go.mod

@@ -18,7 +18,6 @@ require (
 	github.com/spf13/pflag v1.0.9
 	github.com/stretchr/testify v1.11.1
 	github.com/tidwall/gjson v1.18.0
-	github.com/yuin/goldmark v1.7.16
 	github.com/zalando/go-keyring v0.2.8
 	golang.org/x/net v0.33.0
 	golang.org/x/sync v0.15.0

go.sum

@@ -131,8 +131,6 @@ github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e h1:JVG44RsyaB9T2KIHavM
 github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e/go.mod h1:RbqR21r5mrJuqunuUZ/Dhy/avygyECGrLceyNeo4LiM=
 github.com/yuin/goldmark v1.1.27/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
 github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
-github.com/yuin/goldmark v1.7.16 h1:n+CJdUxaFMiDUNnWC3dMWCIQJSkxH4uz3ZwQBkAlVNE=
-github.com/yuin/goldmark v1.7.16/go.mod h1:ip/1k0VRfGynBgxOz0yCqHrbZXhcjxyuS66Brc7iBKg=
 github.com/zalando/go-keyring v0.2.8 h1:6sD/Ucpl7jNq10rM2pgqTs0sZ9V3qMrqfIIy5YPccHs=
 github.com/zalando/go-keyring v0.2.8/go.mod h1:tsMo+VpRq5NGyKfxoBVjCuMrG47yj8cmakZDO5QGii0=
 go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=

internal/cmdutil/factory_default.go

@@ -22,6 +22,7 @@ import (
 	"github.com/larksuite/cli/internal/credential"
 	"github.com/larksuite/cli/internal/keychain"
 	"github.com/larksuite/cli/internal/registry"
+	"github.com/larksuite/cli/internal/riskcontrol"
 	_ "github.com/larksuite/cli/internal/security/contentsafety" // register content safety provider
 	"github.com/larksuite/cli/internal/transport"
 	_ "github.com/larksuite/cli/internal/vfs/localfileio" // register default FileIO provider
@@ -33,7 +34,7 @@ import (
 //	Phase 1: HttpClient (no credential dependency)
 //	Phase 2: Credential (sole data source for account info)
 //	Phase 3: Config derived from Credential
-//	Phase 4: LarkClient derived from Credential
+//	Phase 4: LarkClient derived from Credential and workspace policy
 func NewDefault(streams *IOStreams, inv InvocationContext) *Factory {
 	streams = normalizeStreams(streams)
 	f := &Factory{
@@ -54,9 +55,10 @@ func NewDefault(streams *IOStreams, inv InvocationContext) *Factory {
 
 	// Phase 0: FileIO provider (no dependency)
 	f.FileIOProvider = fileio.GetProvider()
+	workspaceConfig := core.NewConfigSnapshot()
 
 	// Phase 1: HttpClient (no credential dependency)
-	f.HttpClient = cachedHttpClientFunc(f)
+	f.HttpClient = cachedHttpClientFunc(f, workspaceConfig)
 
 	// Phase 2: Credential (sole data source)
 	// Keychain is read via closure so callers can replace f.Keychain after construction.
@@ -67,7 +69,7 @@ func NewDefault(streams *IOStreams, inv InvocationContext) *Factory {
 		ErrOut:     f.IOStreams.ErrOut,
 	})
 
-	// Phase 3: Config derived from Credential via an explicit conversion boundary.
+	// Phase 3: Runtime config contains resolved account data only.
 	f.Config = sync.OnceValues(func() (*core.CliConfig, error) {
 		acct, err := f.Credential.ResolveAccount(context.Background())
 		if err != nil {
@@ -78,8 +80,9 @@ func NewDefault(streams *IOStreams, inv InvocationContext) *Factory {
 		return cfg, nil
 	})
 
-	// Phase 4: LarkClient from Credential (placeholder AppSecret)
-	f.LarkClient = cachedLarkClientFunc(f)
+	// Phase 4: LarkClient composes account data and workspace policy at the SDK
+	// transport boundary.
+	f.LarkClient = cachedLarkClientFunc(f, workspaceConfig)
 
 	return f
 }
@@ -108,13 +111,16 @@ func safeRedirectPolicy(req *http.Request, via []*http.Request) error {
 // .StderrIsTerminal field, which tests set directly.
 var warnIfProxied = transport.WarnIfProxied
 
-func cachedHttpClientFunc(f *Factory) func() (*http.Client, error) {
+func cachedHttpClientFunc(f *Factory, workspaceConfig workspaceConfigSource) func() (*http.Client, error) {
 	return sync.OnceValues(func() (*http.Client, error) {
 		if f.IOStreams.StderrIsTerminal {
 			warnIfProxied(f.IOStreams.ErrOut)
 		}
 
+		hostSignalSource := resolveSDKHostSignalSource(workspaceConfig)
+
 		var rt http.RoundTripper = transport.Shared()
+		rt = riskcontrol.NewTransport(rt, hostSignalSource)
 		rt = &RetryTransport{Base: rt}
 		rt = &SecurityHeaderTransport{Base: rt}
 		rt = &auth.SecurityPolicyTransport{Base: rt} // Add our global response interceptor
@@ -128,7 +134,7 @@ func cachedHttpClientFunc(f *Factory) func() (*http.Client, error) {
 	})
 }
 
-func cachedLarkClientFunc(f *Factory) func() (*lark.Client, error) {
+func cachedLarkClientFunc(f *Factory, workspaceConfig workspaceConfigSource) func() (*lark.Client, error) {
 	return sync.OnceValues(func() (*lark.Client, error) {
 		acct, err := f.Credential.ResolveAccount(context.Background())
 		if err != nil {
@@ -142,8 +148,15 @@ func cachedLarkClientFunc(f *Factory) func() (*lark.Client, error) {
 		if f.IOStreams.StderrIsTerminal {
 			warnIfProxied(f.IOStreams.ErrOut)
 		}
+		hostSignalSource := resolveSDKHostSignalSource(workspaceConfig)
+		var sdkBase http.RoundTripper = transport.Shared()
+		// The innermost SDK boundary always strips reserved host-signal headers;
+		// a nil source makes it strip-only when workspace policy disables signal
+		// collection.
+		sdkBase = riskcontrol.NewTransport(sdkBase, hostSignalSource)
+		sdkTransport := wrapSDKTransport(sdkBase)
 		opts = append(opts, lark.WithHttpClient(&http.Client{
-			Transport:     buildSDKTransport(),
+			Transport:     sdkTransport,
 			CheckRedirect: safeRedirectPolicy,
 		}))
 		ep := core.ResolveEndpoints(acct.Brand)
@@ -152,9 +165,8 @@ func cachedLarkClientFunc(f *Factory) func() (*lark.Client, error) {
 	})
 }
 
-func buildSDKTransport() http.RoundTripper {
-	var sdkTransport http.RoundTripper = transport.Shared()
-	sdkTransport = &RetryTransport{Base: sdkTransport}
+func wrapSDKTransport(next http.RoundTripper) http.RoundTripper {
+	var sdkTransport http.RoundTripper = &RetryTransport{Base: next}
 	sdkTransport = &UserAgentTransport{Base: sdkTransport}
 	sdkTransport = &BuildHeaderTransport{Base: sdkTransport}
 	sdkTransport = &auth.SecurityPolicyTransport{Base: sdkTransport}

internal/cmdutil/factory_http_test.go

@@ -6,10 +6,15 @@ package cmdutil
 import (
 	"io"
 	"testing"
+
+	"github.com/larksuite/cli/internal/core"
 )
 
 func TestCachedHttpClientFunc_ReturnsSameInstance(t *testing.T) {
-	fn := cachedHttpClientFunc(&Factory{IOStreams: &IOStreams{ErrOut: io.Discard}})
+	isEnabled := false
+	f, _, _, _ := TestFactory(t, &core.CliConfig{AppID: "test-app"})
+	f.IOStreams.ErrOut = io.Discard
+	fn := cachedHttpClientFunc(f, staticWorkspaceConfig{config: &core.MultiAppConfig{RiskControl: &isEnabled}})
 
 	c1, err := fn()
 	if err != nil {
@@ -29,7 +34,10 @@ func TestCachedHttpClientFunc_ReturnsSameInstance(t *testing.T) {
 }
 
 func TestCachedHttpClientFunc_HasTimeout(t *testing.T) {
-	fn := cachedHttpClientFunc(&Factory{IOStreams: &IOStreams{ErrOut: io.Discard}})
+	isEnabled := false
+	f, _, _, _ := TestFactory(t, &core.CliConfig{AppID: "test-app"})
+	f.IOStreams.ErrOut = io.Discard
+	fn := cachedHttpClientFunc(f, staticWorkspaceConfig{config: &core.MultiAppConfig{RiskControl: &isEnabled}})
 	c, _ := fn()
 	if c.Timeout == 0 {
 		t.Error("expected non-zero timeout")
@@ -37,7 +45,10 @@ func TestCachedHttpClientFunc_HasTimeout(t *testing.T) {
 }
 
 func TestCachedHttpClientFunc_HasRedirectPolicy(t *testing.T) {
-	fn := cachedHttpClientFunc(&Factory{IOStreams: &IOStreams{ErrOut: io.Discard}})
+	isEnabled := false
+	f, _, _, _ := TestFactory(t, &core.CliConfig{AppID: "test-app"})
+	f.IOStreams.ErrOut = io.Discard
+	fn := cachedHttpClientFunc(f, staticWorkspaceConfig{config: &core.MultiAppConfig{RiskControl: &isEnabled}})
 	c, _ := fn()
 	if c.CheckRedirect == nil {
 		t.Error("expected CheckRedirect to be set (safeRedirectPolicy)")

internal/cmdutil/factory_proxy_warn_test.go

@@ -8,6 +8,7 @@ import (
 	"testing"
 
 	_ "github.com/larksuite/cli/extension/credential/env" // registers the env-backed account provider
+	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/envvars"
 )
 
@@ -36,13 +37,15 @@ var proxyWarnGateCases = []struct {
 // TestCachedHttpClientFunc_ProxyWarnGate verifies the http-client init path
 // invokes WarnIfProxied only when stderr is an interactive terminal.
 func TestCachedHttpClientFunc_ProxyWarnGate(t *testing.T) {
+	isEnabled := false
 	for _, tc := range proxyWarnGateCases {
 		t.Run(tc.name, func(t *testing.T) {
 			calls := installProxyWarnSpy(t)
 
-			fn := cachedHttpClientFunc(&Factory{IOStreams: &IOStreams{
-				ErrOut: io.Discard, StderrIsTerminal: tc.terminal,
-			}})
+			f, _, _, _ := TestFactory(t, &core.CliConfig{AppID: "test-app"})
+			f.IOStreams.ErrOut = io.Discard
+			f.IOStreams.StderrIsTerminal = tc.terminal
+			fn := cachedHttpClientFunc(f, staticWorkspaceConfig{config: &core.MultiAppConfig{RiskControl: &isEnabled}})
 			if _, err := fn(); err != nil {
 				t.Fatalf("http client init: %v", err)
 			}
@@ -73,7 +76,7 @@ func TestCachedLarkClientFunc_ProxyWarnGate(t *testing.T) {
 			// normalizeStreams copies the struct (out := *s), so the
 			// StderrIsTerminal field survives into f.IOStreams.
 			f := NewDefault(&IOStreams{ErrOut: io.Discard, StderrIsTerminal: tc.terminal}, InvocationContext{})
-			if _, err := cachedLarkClientFunc(f)(); err != nil {
+			if _, err := cachedLarkClientFunc(f, nil)(); err != nil {
 				t.Fatalf("lark client init: %v", err)
 			}
 

internal/cmdutil/risk_control.go

@@ -0,0 +1,28 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmdutil
+
+import (
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/riskcontrol"
+)
+
+type workspaceConfigSource interface {
+	MultiAppConfig() (*core.MultiAppConfig, error)
+}
+
+// resolveSDKHostSignalSource applies workspace policy at the SDK transport
+// boundary.
+func resolveSDKHostSignalSource(config workspaceConfigSource) riskcontrol.Source {
+	if config == nil {
+		return nil
+	}
+	workspace, configErr := config.MultiAppConfig()
+	// Default-on means an existing config with no explicit preference. Absent
+	// or unreadable config cannot authorize host-signal collection.
+	if configErr != nil || !workspace.RiskControlEnabled() {
+		return nil
+	}
+	return riskcontrol.NewHostSource()
+}

internal/cmdutil/risk_control_test.go

@@ -0,0 +1,45 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package cmdutil
+
+import (
+	"errors"
+	"testing"
+
+	"github.com/larksuite/cli/internal/core"
+)
+
+type staticWorkspaceConfig struct {
+	config *core.MultiAppConfig
+	err    error
+}
+
+func (s staticWorkspaceConfig) MultiAppConfig() (*core.MultiAppConfig, error) {
+	return s.config, s.err
+}
+
+func TestResolveSDKHostSignalSource(t *testing.T) {
+	disabled := false
+	tests := []struct {
+		name       string
+		config     workspaceConfigSource
+		wantSource bool
+	}{
+		{name: "workspace default on", config: staticWorkspaceConfig{config: &core.MultiAppConfig{}}, wantSource: true},
+		{name: "workspace opt-out", config: staticWorkspaceConfig{config: &core.MultiAppConfig{RiskControl: &disabled}}},
+		{name: "missing config", config: staticWorkspaceConfig{err: errors.New("file does not exist")}},
+		{name: "unreadable config", config: staticWorkspaceConfig{err: errors.New("permission denied")}},
+		{name: "nil config value", config: staticWorkspaceConfig{}},
+		{name: "nil config source"},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			got := resolveSDKHostSignalSource(test.config)
+			if (got != nil) != test.wantSource {
+				t.Fatalf("resolveSDKHostSignalSource() = %T, wantSource %t", got, test.wantSource)
+			}
+		})
+	}
+}

internal/cmdutil/secheader.go

@@ -26,6 +26,7 @@ const (
 	HeaderShortcut    = "X-Cli-Shortcut"
 	HeaderExecutionId = "X-Cli-Execution-Id"
 	HeaderAgentTrace  = "X-Agent-Trace"
+	HeaderAgentName   = "X-Agent-Name"
 
 	SourceValue = "lark-cli"
 
@@ -55,6 +56,9 @@ func BaseSecurityHeaders() http.Header {
 	if v := envvars.AgentTrace(); v != "" {
 		h.Set(HeaderAgentTrace, v)
 	}
+	if v := envvars.AgentName(); v != "" {
+		h.Set(HeaderAgentName, v)
+	}
 	return h
 }
 

internal/cmdutil/secheader_test.go

@@ -263,9 +263,34 @@ func TestBaseSecurityHeaders_AllRequiredHeaders(t *testing.T) {
 }
 
 // ---------------------------------------------------------------------------
-// HeaderAgentTrace injection (via BaseSecurityHeaders)
+// Agent headers injected via BaseSecurityHeaders
 // ---------------------------------------------------------------------------
 
+func TestBaseSecurityHeaders_NoAgentNameHeaderWhenEnvUnset(t *testing.T) {
+	t.Setenv(envvars.CliAgentName, "")
+	h := BaseSecurityHeaders()
+	if v := h.Get(HeaderAgentName); v != "" {
+		t.Fatalf("BaseSecurityHeaders() included %s = %q, want absent when env unset", HeaderAgentName, v)
+	}
+}
+
+func TestBaseSecurityHeaders_IncludesAgentNameHeaderWhenEnvSet(t *testing.T) {
+	const agentName = "sample-agent"
+	t.Setenv(envvars.CliAgentName, agentName)
+	h := BaseSecurityHeaders()
+	if v := h.Get(HeaderAgentName); v != agentName {
+		t.Fatalf("BaseSecurityHeaders()[%s] = %q, want %q", HeaderAgentName, v, agentName)
+	}
+}
+
+func TestBaseSecurityHeaders_NoAgentNameHeaderWhenEnvInvalid(t *testing.T) {
+	t.Setenv(envvars.CliAgentName, "agent\r\nX-Evil: attack")
+	h := BaseSecurityHeaders()
+	if v := h.Get(HeaderAgentName); v != "" {
+		t.Fatalf("BaseSecurityHeaders() included %s = %q, want absent for invalid input", HeaderAgentName, v)
+	}
+}
+
 func TestBaseSecurityHeaders_NoAgentTraceHeaderWhenEnvUnset(t *testing.T) {
 	t.Setenv(envvars.CliAgentTrace, "")
 	h := BaseSecurityHeaders()

internal/cmdutil/transport_test.go

@@ -15,6 +15,7 @@ import (
 
 	exttransport "github.com/larksuite/cli/extension/transport"
 	internalauth "github.com/larksuite/cli/internal/auth"
+	"github.com/larksuite/cli/internal/riskcontrol"
 )
 
 type roundTripFunc func(*http.Request) (*http.Response, error)
@@ -91,13 +92,13 @@ func TestRetryTransport_DefaultNoRetry(t *testing.T) {
 }
 
 // ---------------------------------------------------------------------------
-// buildSDKTransport chain composition
+// wrapSDKTransport chain composition
 // ---------------------------------------------------------------------------
 
-func TestBuildSDKTransport_IncludesRetryTransport(t *testing.T) {
-	transport := buildSDKTransport()
+func TestWrapSDKTransport_IncludesRetryTransport(t *testing.T) {
+	transport := wrapSDKTransport(riskcontrol.NewTransport(http.DefaultTransport, nil))
 
-	// Chain: SecurityPolicy → BuildHeader → UserAgent → Retry → Base
+	// Chain: SecurityPolicy → BuildHeader → UserAgent → Retry → RiskControl → Base
 	sec, ok := transport.(*internalauth.SecurityPolicyTransport)
 	if !ok {
 		t.Fatalf("outer transport type = %T, want *auth.SecurityPolicyTransport", transport)
@@ -110,18 +111,23 @@ func TestBuildSDKTransport_IncludesRetryTransport(t *testing.T) {
 	if !ok {
 		t.Fatalf("layer after BuildHeader = %T, want *UserAgentTransport", bh.Base)
 	}
-	if _, ok := ua.Base.(*RetryTransport); !ok {
+	retry, ok := ua.Base.(*RetryTransport)
+	if !ok {
 		t.Fatalf("inner transport type = %T, want *RetryTransport", ua.Base)
 	}
+	if _, ok := retry.Base.(*riskcontrol.Transport); !ok {
+		t.Fatalf("layer after Retry = %T, want *riskcontrol.Transport", retry.Base)
+	}
 }
 
-func TestBuildSDKTransport_WithExtension(t *testing.T) {
+func TestWrapSDKTransport_WithExtension(t *testing.T) {
+	previous := exttransport.GetProvider()
 	exttransport.Register(&stubTransportProvider{})
-	t.Cleanup(func() { exttransport.Register(nil) })
+	t.Cleanup(func() { exttransport.Register(previous) })
 
-	transport := buildSDKTransport()
+	transport := wrapSDKTransport(riskcontrol.NewTransport(http.DefaultTransport, nil))
 
-	// Chain: extensionMiddleware → SecurityPolicy → BuildHeader → UserAgent → Retry → Base
+	// Chain: extensionMiddleware → SecurityPolicy → BuildHeader → UserAgent → Retry → RiskControl → Base
 	mid, ok := transport.(*extensionMiddleware)
 	if !ok {
 		t.Fatalf("outer transport type = %T, want *extensionMiddleware", transport)
@@ -138,17 +144,23 @@ func TestBuildSDKTransport_WithExtension(t *testing.T) {
 	if !ok {
 		t.Fatalf("layer after BuildHeader = %T, want *UserAgentTransport", bh.Base)
 	}
-	if _, ok := ua.Base.(*RetryTransport); !ok {
+	retry, ok := ua.Base.(*RetryTransport)
+	if !ok {
 		t.Fatalf("innermost transport type = %T, want *RetryTransport", ua.Base)
 	}
+	if _, ok := retry.Base.(*riskcontrol.Transport); !ok {
+		t.Fatalf("layer after Retry = %T, want *riskcontrol.Transport", retry.Base)
+	}
 }
 
-func TestBuildSDKTransport_WithoutExtension(t *testing.T) {
+func TestWrapSDKTransport_WithoutExtension(t *testing.T) {
+	previous := exttransport.GetProvider()
 	exttransport.Register(nil)
+	t.Cleanup(func() { exttransport.Register(previous) })
 
-	transport := buildSDKTransport()
+	transport := wrapSDKTransport(riskcontrol.NewTransport(http.DefaultTransport, nil))
 
-	// Chain: SecurityPolicy → BuildHeader → UserAgent → Retry → Base
+	// Chain: SecurityPolicy → BuildHeader → UserAgent → Retry → RiskControl → Base
 	sec, ok := transport.(*internalauth.SecurityPolicyTransport)
 	if !ok {
 		t.Fatalf("outer transport type = %T, want *auth.SecurityPolicyTransport", transport)
@@ -161,9 +173,13 @@ func TestBuildSDKTransport_WithoutExtension(t *testing.T) {
 	if !ok {
 		t.Fatalf("layer after BuildHeader = %T, want *UserAgentTransport", bh.Base)
 	}
-	if _, ok := ua.Base.(*RetryTransport); !ok {
+	retry, ok := ua.Base.(*RetryTransport)
+	if !ok {
 		t.Fatalf("inner transport type = %T, want *RetryTransport", ua.Base)
 	}
+	if _, ok := retry.Base.(*riskcontrol.Transport); !ok {
+		t.Fatalf("layer after Retry = %T, want *riskcontrol.Transport", retry.Base)
+	}
 }
 
 // ---------------------------------------------------------------------------
@@ -261,6 +277,40 @@ func (buildTamperingInterceptor) PreRoundTrip(req *http.Request) func(*http.Resp
 	return nil
 }
 
+type riskHeaderTamperingInterceptor struct{}
+
+func (riskHeaderTamperingInterceptor) PreRoundTrip(req *http.Request) func(*http.Response, error) {
+	req.Header.Set(riskcontrol.HeaderOSType, "extension-value")
+	req.Header.Set(riskcontrol.HeaderProductModel, "extension-value")
+	return nil
+}
+
+func TestWrapSDKTransport_StripsExtensionRiskHeaders(t *testing.T) {
+	previous := exttransport.GetProvider()
+	exttransport.Register(&stubTransportProvider{interceptor: riskHeaderTamperingInterceptor{}})
+	t.Cleanup(func() { exttransport.Register(previous) })
+
+	var received http.Header
+	network := roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		received = req.Header.Clone()
+		return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody}, nil
+	})
+	req, err := http.NewRequest(http.MethodGet, "https://open.feishu.cn/open-apis/test", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	req.Header.Set("Authorization", "Bearer token")
+
+	resp, err := wrapSDKTransport(riskcontrol.NewTransport(network, nil)).RoundTrip(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	resp.Body.Close()
+	if received.Get(riskcontrol.HeaderOSType) != "" || received.Get(riskcontrol.HeaderProductModel) != "" {
+		t.Fatalf("extension risk headers reached network: %v", received)
+	}
+}
+
 // TestBuildHeaderTransport_SDKChain_OverridesTamperedHeader verifies that the
 // X-Cli-Build header is force-written by BuildHeaderTransport in the SDK
 // transport chain, even when an extension tries to delete or spoof it. This
@@ -277,7 +327,7 @@ func TestBuildHeaderTransport_SDKChain_OverridesTamperedHeader(t *testing.T) {
 	exttransport.Register(&stubTransportProvider{interceptor: buildTamperingInterceptor{}})
 	t.Cleanup(func() { exttransport.Register(nil) })
 
-	// Replicate the SDK chain layering used by buildSDKTransport.
+	// Replicate the SDK chain layering used by wrapSDKTransport.
 	var base http.RoundTripper = http.DefaultTransport
 	base = &RetryTransport{Base: base}
 	base = &UserAgentTransport{Base: base}

internal/core/config.go

@@ -60,11 +60,18 @@ func (a *AppConfig) ProfileName() string {
 // MultiAppConfig is the multi-app config file format.
 type MultiAppConfig struct {
 	StrictMode  StrictMode  `json:"strictMode,omitempty"`
+	RiskControl *bool       `json:"riskControl,omitempty"`
 	CurrentApp  string      `json:"currentApp,omitempty"`
 	PreviousApp string      `json:"previousApp,omitempty"`
 	Apps        []AppConfig `json:"apps"`
 }
 
+// RiskControlEnabled resolves the workspace policy. An omitted preference
+// keeps the default-on account-protection behavior.
+func (m *MultiAppConfig) RiskControlEnabled() bool {
+	return m != nil && (m.RiskControl == nil || *m.RiskControl)
+}
+
 // CurrentAppConfig returns the currently active app config.
 // Resolution priority: profileOverride > CurrentApp field > Apps[0].
 func (m *MultiAppConfig) CurrentAppConfig(profileOverride string) *AppConfig {

internal/core/config_snapshot.go

@@ -0,0 +1,37 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package core
+
+import (
+	"io/fs"
+	"sync"
+)
+
+// ConfigSnapshot lazily captures one stable view of config.json for a CLI
+// invocation. All runtime consumers share the same load result so account and
+// workspace policy resolution cannot observe different file revisions. Callers
+// must treat the returned config as read-only.
+type ConfigSnapshot struct {
+	load func() (*MultiAppConfig, error)
+}
+
+// NewConfigSnapshot creates a lazily loaded invocation-scoped config snapshot.
+func NewConfigSnapshot() *ConfigSnapshot {
+	return newConfigSnapshot(LoadMultiAppConfig)
+}
+
+func newConfigSnapshot(load func() (*MultiAppConfig, error)) *ConfigSnapshot {
+	if load == nil {
+		return &ConfigSnapshot{}
+	}
+	return &ConfigSnapshot{load: sync.OnceValues(load)}
+}
+
+// MultiAppConfig returns the captured persistent config and load error.
+func (s *ConfigSnapshot) MultiAppConfig() (*MultiAppConfig, error) {
+	if s == nil || s.load == nil {
+		return nil, fs.ErrNotExist
+	}
+	return s.load()
+}

internal/core/config_snapshot_test.go

@@ -0,0 +1,58 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package core
+
+import (
+	"errors"
+	"io/fs"
+	"testing"
+)
+
+func TestConfigSnapshotLoadsOnce(t *testing.T) {
+	calls := 0
+	want := &MultiAppConfig{}
+	snapshot := newConfigSnapshot(func() (*MultiAppConfig, error) {
+		calls++
+		return want, nil
+	})
+
+	for range 2 {
+		config, err := snapshot.MultiAppConfig()
+		if err != nil {
+			t.Fatal(err)
+		}
+		if config != want {
+			t.Fatal("snapshot returned a different config instance")
+		}
+	}
+	if calls != 1 {
+		t.Fatalf("config loads = %d, want 1", calls)
+	}
+}
+
+func TestConfigSnapshotZeroValueIsMissing(t *testing.T) {
+	config, err := (&ConfigSnapshot{}).MultiAppConfig()
+	if config != nil || !errors.Is(err, fs.ErrNotExist) {
+		t.Fatalf("MultiAppConfig() = (%v, %v), want (nil, fs.ErrNotExist)", config, err)
+	}
+}
+
+func TestConfigSnapshotCachesError(t *testing.T) {
+	calls := 0
+	want := errors.New("load failed")
+	snapshot := newConfigSnapshot(func() (*MultiAppConfig, error) {
+		calls++
+		return nil, want
+	})
+
+	for range 2 {
+		config, err := snapshot.MultiAppConfig()
+		if config != nil || !errors.Is(err, want) {
+			t.Fatalf("MultiAppConfig() = (%v, %v), want (nil, %v)", config, err, want)
+		}
+	}
+	if calls != 1 {
+		t.Fatalf("config loads = %d, want 1", calls)
+	}
+}

internal/core/config_test.go

@@ -60,7 +60,9 @@ func TestAppConfig_LangOmitEmpty(t *testing.T) {
 }
 
 func TestMultiAppConfig_RoundTrip(t *testing.T) {
+	disabled := false
 	config := &MultiAppConfig{
+		RiskControl: &disabled,
 		Apps: []AppConfig{{
 			AppId: "cli_test", AppSecret: PlainSecret("s"),
 			Brand: BrandLark, Lang: "zh", Users: []AppUser{},
@@ -84,6 +86,9 @@ func TestMultiAppConfig_RoundTrip(t *testing.T) {
 	if got.Apps[0].Brand != BrandLark {
 		t.Errorf("Brand = %q, want %q", got.Apps[0].Brand, BrandLark)
 	}
+	if got.RiskControl == nil || *got.RiskControl {
+		t.Errorf("RiskControl = %v, want explicit false", got.RiskControl)
+	}
 }
 
 func TestResolveConfigFromMulti_RejectsSecretKeyMismatch(t *testing.T) {

internal/envvars/read_test.go

@@ -16,16 +16,18 @@ func TestAgentName_EmptyWhenEnvUnset(t *testing.T) {
 }
 
 func TestAgentName_ReturnsCleanValue(t *testing.T) {
-	t.Setenv(CliAgentName, "claude-code")
-	if got := AgentName(); got != "claude-code" {
-		t.Fatalf("AgentName() = %q, want %q", got, "claude-code")
+	const agentName = "sample-agent"
+	t.Setenv(CliAgentName, agentName)
+	if got := AgentName(); got != agentName {
+		t.Fatalf("AgentName() = %q, want %q", got, agentName)
 	}
 }
 
 func TestAgentName_TrimsWhitespace(t *testing.T) {
-	t.Setenv(CliAgentName, "  cursor  ")
-	if got := AgentName(); got != "cursor" {
-		t.Fatalf("AgentName() = %q, want %q (whitespace trimmed)", got, "cursor")
+	const agentName = "sample-agent"
+	t.Setenv(CliAgentName, "  "+agentName+"  ")
+	if got := AgentName(); got != agentName {
+		t.Fatalf("AgentName() = %q, want %q (whitespace trimmed)", got, agentName)
 	}
 }
 

internal/httpmock/registry.go

@@ -38,6 +38,10 @@ type Stub struct {
 	// matches after the first hit. Each match appends to CapturedBodies.
 	Reusable bool
 
+	// Optional (optional): when true, Verify does not require this stub to be
+	// matched. Useful for negative assertions via OnMatch.
+	Optional bool
+
 	// CapturedHeaders records the request headers of the matched request.
 	// Populated after RoundTrip matches this stub.
 	CapturedHeaders http.Header
@@ -137,6 +141,9 @@ func (r *Registry) Verify(t testing.TB) {
 		if s.matched {
 			continue
 		}
+		if s.Optional {
+			continue
+		}
 		// Reusable stubs never set s.matched; treat any captured hit as a match.
 		if s.Reusable && len(s.CapturedBodies) > 0 {
 			continue

internal/qualitygate/config/README.md

@@ -45,6 +45,18 @@ Adding a new row requires approval from the matching CODEOWNERS or quality gate
 
 `legacy-commands.txt` only covers hand-authored legacy commands. Generated OpenAPI service commands are intentionally excluded from `command-manifest.json`; they are included in `command-index.json` only so command references can be checked against the real CLI surface.
 
+## Public Domain Allowlists
+
+`internal/qualitygate/config/allowlists/public-domains.txt` contains supported public hostnames approved for Go source. `fixture-domains.txt` contains test-only hostnames used by `*_test.go`, the repository-root `tests/` directory, or any `testdata/` directory; fixture entries do not apply to production Go files or `skills/`.
+
+Keep one lowercase exact hostname per line, sorted alphabetically. Wildcards, suffix rules, duplicates, schemes, ports, and paths are rejected; approving `larkoffice.com` does not approve its subdomains.
+
+RFC 2606 reserves the `.test`, `.example`, `.invalid`, and `.localhost` namespaces plus the exact names `example.com`, `example.net`, and `example.org`. These names are accepted without an allowlist entry and must not be listed.
+
+Every public entry needs a current non-fixture Go use, evidence that it is a supported public endpoint, and CODEOWNER approval. Other test-only hostnames belong in the fixture list. Tenant-specific, private-control-plane, and internal API hostnames are not eligible.
+
+`lint/domaincontract` validates both lists and scans complete Go files. In CI, unapproved-host findings are limited to values whose expressions intersect added lines; list validation and unused-entry checks remain repository-wide. See `lint/README.md` for scanner semantics.
+
 ## Semantic Blocker Policy
 
 The semantic reviewer can propose findings, but the local gatekeeper recomputes whether each finding is reproducible from `facts.json`. A finding blocks only when all of these are true:

internal/qualitygate/config/allowlists/fixture-domains.txt

@@ -0,0 +1,24 @@
+# Exact test-only hostnames. Keep sorted.
+abc.feishu.cn
+attacker.example.com
+bytedance.feishu.cn
+cdn.feishu.cn
+evil.example.com
+example.feishu.cn
+example.larkoffice.com
+example.larksuite.com
+feishu.cn
+feishu.doubao.com
+gateway.docker.internal
+host.containers.internal
+host.docker.internal
+host.lima.internal
+lf3-static.bytednsdoc.com
+meetings.feishu.cn
+meetings.larksuite.com
+p3-lark-file.byteimg.com
+passport.feishu.cn
+sample.feishu.cn
+x.feishu.cn
+xxx.feishu.cn
+xxx.larksuite.com

internal/qualitygate/config/allowlists/public-domains.txt

@@ -0,0 +1,18 @@
+# Exact public hostnames. Keep sorted.
+accounts.feishu.cn
+accounts.larksuite.com
+applink.feishu.cn
+applink.larksuite.com
+ark.ap-southeast.bytepluses.com
+github.com
+larkoffice.com
+lf-larkemail.bytetos.com
+mcp.feishu.cn
+mcp.larksuite.com
+open.feishu.cn
+open.larksuite.com
+registry.npmjs.org
+registry.npmmirror.com
+sf16-sg.tiktokcdn.com
+www.feishu.cn
+www.larksuite.com

internal/riskcontrol/osmodel.go

@@ -0,0 +1,142 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+// Package deviceinfo collects the platform hardware product model and the
+// platform values used by device-related risk-control headers.
+package riskcontrol
+
+import (
+	"runtime"
+	"strings"
+	"sync"
+	"unicode"
+	"unicode/utf8"
+
+	"golang.org/x/net/http/httpguts"
+)
+
+// OSType is the server-side risk-control operating-system enum.
+type OSType string
+
+// OS type enum values for X-Agent-Os-Type.
+const (
+	OSTypeUnknown = "0"
+	OSTypeWindows = "1"
+	OSTypeLinux   = "2"
+	OSTypeMacOS   = "3"
+)
+
+const (
+	// TerminalTypePC is the fixed X-Agent-Terminal-Type value for the CLI.
+	TerminalTypePC = "1"
+
+	// Unknown is used when the hardware product model cannot be collected.
+	Unknown = "Unknown"
+
+	// deviceModelMaxBytes bounds the value added to X-Agent-Device-Type.
+	// Device models are short identifiers; a larger value is treated as
+	// malformed rather than truncated so the header never misrepresents it.
+	deviceModelMaxBytes = 256
+)
+
+// Snapshot contains the deliberately small risk-control signal set.
+// ProductModel is omitted when the platform cannot provide a safe value.
+type Snapshot struct {
+	OSType       OSType
+	ProductModel string
+}
+
+// Source supplies one immutable process-level snapshot.
+type Source interface {
+	Snapshot() Snapshot
+}
+
+// HostSource lazily reads host signals once, after outbound policy authorizes
+// the first request. Failed probes are cached and are not retried per request.
+type HostSource struct {
+	once      sync.Once
+	value     Snapshot
+	readModel func() string
+}
+
+// NewHostSource creates the production host signal source.
+func NewHostSource() *HostSource {
+	return &HostSource{readModel: readDeviceModel}
+}
+
+// Snapshot returns the cached host signal snapshot.
+func (s *HostSource) Snapshot() Snapshot {
+	if s == nil {
+		return Snapshot{}
+	}
+	s.once.Do(func() {
+		readModel := s.readModel
+		if readModel == nil {
+			readModel = readDeviceModel
+		}
+		s.value = Snapshot{
+			OSType:       GetOSType(OSName()),
+			ProductModel: normalizeDeviceModel(readModel()),
+		}
+	})
+	return s.value
+}
+
+// normalizeModel removes non-printable characters and returns a model only
+// when the remaining text is safe to use as an HTTP header value. Input that
+// cannot produce a valid model is rejected so Get can fall back to Unknown.
+func normalizeDeviceModel(model string) string {
+	if !utf8.ValidString(model) {
+		return ""
+	}
+	model = strings.Map(func(r rune) rune {
+		switch {
+		case r == '\r' || r == '\n' || r == '\x00':
+			return -1
+		case unicode.IsSpace(r):
+			return ' '
+		case unicode.IsPrint(r):
+			return r
+		default:
+			return -1
+		}
+	}, model)
+
+	model = strings.Join(strings.Fields(model), " ")
+
+	if model == "" || len(model) > deviceModelMaxBytes {
+		return ""
+	}
+	if !httpguts.ValidHeaderFieldValue(model) {
+		return ""
+	}
+	return model
+}
+
+// GetOSType maps a platform name to the X-Agent-Os-Type enum.
+func GetOSType(osName string) OSType {
+	switch osName {
+	case "Windows":
+		return OSTypeWindows
+	case "Linux":
+		return OSTypeLinux
+	case "MacOS":
+		return OSTypeMacOS
+	default:
+		return OSTypeUnknown
+	}
+}
+
+// OSName returns the platform name used by GetOSType.
+func OSName() string {
+	switch runtime.GOOS {
+	case "darwin":
+		return "MacOS"
+	case "windows":
+		return "Windows"
+	case "linux":
+		return "Linux"
+	default:
+		return runtime.GOOS
+	}
+}

internal/riskcontrol/osmodel_darwin.go

@@ -0,0 +1,27 @@
+//go:build darwin
+
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package riskcontrol
+
+import "golang.org/x/sys/unix"
+
+// readDeviceModel reads the current product key first and falls back to the
+// legacy model key. Trying both keys is more robust than branching on a macOS
+// version because virtualized or restricted environments may expose only one.
+func readDeviceModel() string {
+	return readDarwinDeviceModel(unix.Sysctl)
+}
+
+func readDarwinDeviceModel(readSysctl func(string) (string, error)) string {
+	for _, key := range [...]string{"hw.product", "hw.model"} {
+		model, err := readSysctl(key)
+		if err == nil {
+			if model = normalizeDeviceModel(model); model != "" {
+				return model
+			}
+		}
+	}
+	return ""
+}

internal/riskcontrol/osmodel_darwin_test.go

@@ -0,0 +1,48 @@
+//go:build darwin
+
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package riskcontrol
+
+import (
+	"errors"
+	"reflect"
+	"testing"
+)
+
+func TestReadDarwinDeviceModelPrefersProductAndFallsBackToModel(t *testing.T) {
+	t.Run("product available", func(t *testing.T) {
+		var keys []string
+		got := readDarwinDeviceModel(func(key string) (string, error) {
+			keys = append(keys, key)
+			if key == "hw.product" {
+				return "Mac16,1", nil
+			}
+			return "", errors.New("unexpected fallback")
+		})
+		if got != "Mac16,1" {
+			t.Fatalf("model = %q, want %q", got, "Mac16,1")
+		}
+		if want := []string{"hw.product"}; !reflect.DeepEqual(keys, want) {
+			t.Fatalf("sysctl keys = %v, want %v", keys, want)
+		}
+	})
+
+	t.Run("product unavailable", func(t *testing.T) {
+		var keys []string
+		got := readDarwinDeviceModel(func(key string) (string, error) {
+			keys = append(keys, key)
+			if key == "hw.model" {
+				return "MacBookPro18,3", nil
+			}
+			return "", errors.New("not available")
+		})
+		if got != "MacBookPro18,3" {
+			t.Fatalf("model = %q, want %q", got, "MacBookPro18,3")
+		}
+		if want := []string{"hw.product", "hw.model"}; !reflect.DeepEqual(keys, want) {
+			t.Fatalf("sysctl keys = %v, want %v", keys, want)
+		}
+	})
+}

internal/riskcontrol/osmodel_linux.go

@@ -0,0 +1,17 @@
+//go:build linux
+
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package riskcontrol
+
+// readDeviceModel returns a stable device model for Linux. DMI and device-tree
+// values vary widely and can expose the host or virtualization platform when
+// the CLI runs in a container or sandbox.
+func readDeviceModel() string {
+	return readLinuxDeviceModel()
+}
+
+func readLinuxDeviceModel() string {
+	return "linux"
+}

internal/riskcontrol/osmodel_linux_test.go

@@ -0,0 +1,20 @@
+//go:build linux
+
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package riskcontrol
+
+import "testing"
+
+func TestReadDeviceModelReturnsLinux(t *testing.T) {
+	if got := readDeviceModel(); got != "linux" {
+		t.Fatalf("readDeviceModel() = %q, want %q", got, "linux")
+	}
+}
+
+func TestReadLinuxDeviceModel(t *testing.T) {
+	if got := readLinuxDeviceModel(); got != "linux" {
+		t.Fatalf("readLinuxDeviceModel() = %q, want %q", got, "linux")
+	}
+}

internal/riskcontrol/osmodel_other.go

@@ -0,0 +1,11 @@
+//go:build !darwin && !windows && !linux
+
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package riskcontrol
+
+// readDeviceModel returns an empty model on unsupported platforms.
+func readDeviceModel() string {
+	return ""
+}

internal/riskcontrol/osmodel_test.go

@@ -0,0 +1,143 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package riskcontrol
+
+import (
+	"fmt"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"unicode"
+)
+
+func TestHostSourceCachesNonEmptyModel(t *testing.T) {
+	calls := 0
+	s := &HostSource{readModel: func() string {
+		calls++
+		return "  MacBookPro18,3\n"
+	}}
+
+	if got := s.Snapshot(); got.ProductModel != "MacBookPro18,3" {
+		t.Fatalf("first Snapshot().ProductModel = %q, want %q", got.ProductModel, "MacBookPro18,3")
+	}
+	if got := s.Snapshot(); got.ProductModel != "MacBookPro18,3" {
+		t.Fatalf("second Snapshot().ProductModel = %q, want cached model", got.ProductModel)
+	}
+	if calls != 1 {
+		t.Fatalf("read called %d times, want 1", calls)
+	}
+}
+
+func TestHostSourceCachesEmptyModel(t *testing.T) {
+	calls := 0
+	s := &HostSource{readModel: func() string {
+		calls++
+		return ""
+	}}
+
+	if got := s.Snapshot(); got.ProductModel != "" {
+		t.Fatalf("first Snapshot().ProductModel = %q, want empty", got.ProductModel)
+	}
+	if got := s.Snapshot(); got.ProductModel != "" {
+		t.Fatalf("second Snapshot().ProductModel = %q, want cached empty result", got.ProductModel)
+	}
+	if calls != 1 {
+		t.Fatalf("read called %d times, want 1", calls)
+	}
+}
+
+func TestHostSourceReadsOnceAcrossConcurrentCalls(t *testing.T) {
+	var calls atomic.Int32
+	s := &HostSource{readModel: func() string {
+		calls.Add(1)
+		return "ThinkPad X1 Carbon"
+	}}
+
+	const goroutines = 32
+	var wg sync.WaitGroup
+	wg.Add(goroutines)
+	for i := 0; i < goroutines; i++ {
+		go func() {
+			defer wg.Done()
+			snapshot := s.Snapshot()
+			if snapshot.ProductModel != "ThinkPad X1 Carbon" {
+				t.Errorf("Snapshot().ProductModel = %q, want %q", snapshot.ProductModel, "ThinkPad X1 Carbon")
+			}
+		}()
+	}
+	wg.Wait()
+
+	if got := calls.Load(); got != 1 {
+		t.Fatalf("read called %d times, want 1", got)
+	}
+}
+
+func TestNormalizeDeviceModel(t *testing.T) {
+	tests := []struct {
+		name  string
+		model string
+		want  string
+	}{
+		{name: "trims surrounding whitespace", model: "  MacBookPro18,3\n", want: "MacBookPro18,3"},
+		{name: "trims device tree terminator", model: "Raspberry Pi 5\x00", want: "Raspberry Pi 5"},
+		{name: "allows printable Unicode", model: "联想 ThinkPad X1", want: "联想 ThinkPad X1"},
+		{name: "rejects empty", model: " \t\r\n"},
+		{name: "rejects invalid UTF-8", model: string([]byte{'M', 0xff, '1'})},
+		{name: "removes CRLF", model: "model\r\nname", want: "modelname"},
+		{name: "normalizes tab", model: "model\tname", want: "model name"},
+		{name: "removes NUL", model: "model\x00name", want: "modelname"},
+		{name: "removes control character", model: "model\x1fname", want: "modelname"},
+		{name: "removes DEL", model: "model\x7fname", want: "modelname"},
+		{name: "normalizes Unicode line separator", model: "model\u2028name", want: "model name"},
+		{name: "collapses whitespace", model: "  model\t \u00a0 name  ", want: "model name"},
+		{name: "accepts maximum byte length", model: strings.Repeat("a", deviceModelMaxBytes), want: strings.Repeat("a", deviceModelMaxBytes)},
+		{name: "rejects overlong value", model: strings.Repeat("a", deviceModelMaxBytes+1)},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := normalizeDeviceModel(tt.model); got != tt.want {
+				t.Fatalf("normalizeDeviceModel(%q) = %q, want %q", tt.model, got, tt.want)
+			}
+		})
+	}
+}
+
+func TestNormalizeDeviceModelRemovesHTTPControlBytes(t *testing.T) {
+	for value := 0; value <= 0x7f; value++ {
+		if value >= 0x20 && value < 0x7f {
+			continue
+		}
+		t.Run(fmt.Sprintf("0x%02x", value), func(t *testing.T) {
+			model := "model" + string(rune(value)) + "name"
+			want := "modelname"
+			if value != '\r' && value != '\n' && value != '\x00' && unicode.IsSpace(rune(value)) {
+				want = "model name"
+			}
+			if got := normalizeDeviceModel(model); got != want {
+				t.Fatalf("normalizeDeviceModel(%q) = %q, want %q", model, got, want)
+			}
+		})
+	}
+}
+
+func TestGetOSType(t *testing.T) {
+	tests := []struct {
+		name string
+		want OSType
+	}{
+		{name: "Windows", want: OSTypeWindows},
+		{name: "Linux", want: OSTypeLinux},
+		{name: "MacOS", want: OSTypeMacOS},
+		{name: "unknown", want: OSTypeUnknown},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := GetOSType(tt.name); got != tt.want {
+				t.Errorf("GetOSType(%q) = %q, want %q", tt.name, got, tt.want)
+			}
+		})
+	}
+}

internal/riskcontrol/osmodel_windows.go

@@ -0,0 +1,44 @@
+//go:build windows
+
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package riskcontrol
+
+import "golang.org/x/sys/windows/registry"
+
+// systemInfoRegistryPaths lists registry locations in device-model lookup order.
+var systemInfoRegistryPaths = [...]string{
+	`HARDWARE\DESCRIPTION\System\BIOS`,
+	`SYSTEM\CurrentControlSet\Control\SystemInformation`,
+	`SYSTEM\HardwareConfig\Current`,
+}
+
+// readDeviceModel returns the first product name found in the Windows registry.
+func readDeviceModel() string {
+	return readWindowsDeviceModel(readWindowsRegistryModel)
+}
+
+func readWindowsRegistryModel(path string) (string, error) {
+	key, err := registry.OpenKey(registry.LOCAL_MACHINE, path, registry.READ)
+	if err != nil {
+		return "", err
+	}
+	defer key.Close()
+
+	model, _, err := key.GetStringValue("SystemProductName")
+	return model, err
+}
+
+func readWindowsDeviceModel(readRegistryModel func(string) (string, error)) string {
+	for _, path := range systemInfoRegistryPaths {
+		model, err := readRegistryModel(path)
+		if err != nil {
+			continue
+		}
+		if model = normalizeDeviceModel(model); model != "" {
+			return model
+		}
+	}
+	return ""
+}

internal/riskcontrol/osmodel_windows_test.go

@@ -0,0 +1,78 @@
+//go:build windows
+
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package riskcontrol
+
+import (
+	"errors"
+	"reflect"
+	"testing"
+)
+
+func TestReadWindowsDeviceModelFallback(t *testing.T) {
+	readError := errors.New("registry read failed")
+	tests := []struct {
+		name      string
+		values    map[string]string
+		errors    map[string]error
+		want      string
+		wantPaths []string
+	}{
+		{
+			name:      "first path wins",
+			values:    map[string]string{systemInfoRegistryPaths[0]: "Surface Laptop"},
+			want:      "Surface Laptop",
+			wantPaths: []string{systemInfoRegistryPaths[0]},
+		},
+		{
+			name: "read failure falls back",
+			errors: map[string]error{
+				systemInfoRegistryPaths[0]: readError,
+			},
+			values: map[string]string{
+				systemInfoRegistryPaths[1]: "ThinkPad X1 Carbon",
+			},
+			want:      "ThinkPad X1 Carbon",
+			wantPaths: systemInfoRegistryPaths[:2],
+		},
+		{
+			name: "empty normalized value falls back",
+			values: map[string]string{
+				systemInfoRegistryPaths[0]: " \r\n\x00",
+				systemInfoRegistryPaths[1]: "Latitude 7450",
+			},
+			want:      "Latitude 7450",
+			wantPaths: systemInfoRegistryPaths[:2],
+		},
+		{
+			name: "all paths fail",
+			errors: map[string]error{
+				systemInfoRegistryPaths[0]: readError,
+				systemInfoRegistryPaths[1]: readError,
+				systemInfoRegistryPaths[2]: readError,
+			},
+			wantPaths: systemInfoRegistryPaths[:],
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var paths []string
+			got := readWindowsDeviceModel(func(path string) (string, error) {
+				paths = append(paths, path)
+				if err := tt.errors[path]; err != nil {
+					return "", err
+				}
+				return tt.values[path], nil
+			})
+			if got != tt.want {
+				t.Fatalf("model = %q, want %q", got, tt.want)
+			}
+			if !reflect.DeepEqual(paths, tt.wantPaths) {
+				t.Fatalf("registry paths = %v, want %v", paths, tt.wantPaths)
+			}
+		})
+	}
+}

internal/riskcontrol/transport.go

@@ -0,0 +1,138 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package riskcontrol
+
+import (
+	"net/http"
+	"net/url"
+	"strings"
+
+	"github.com/larksuite/cli/internal/core"
+	internaltransport "github.com/larksuite/cli/internal/transport"
+)
+
+const (
+	HeaderProductModel = "X-Agent-Device-Type"
+	HeaderOSType       = "X-Agent-Os-Type"
+)
+
+var restrictedHeaders = [...]string{HeaderProductModel, HeaderOSType}
+
+// Transport is the feature's final outbound boundary. It removes caller- or
+// extension-supplied signal headers first and writes trusted values only after
+// authorizing an official SDK origin and authentication state.
+type Transport struct {
+	next   http.RoundTripper
+	source Source
+}
+
+// NewTransport creates the final SDK outbound policy boundary. A nil source
+// disables collection and injection while preserving restricted-header
+// stripping for opt-out and extension-credential requests.
+func NewTransport(next http.RoundTripper, source Source) *Transport {
+	if next == nil {
+		next = internaltransport.Fallback()
+	}
+	return &Transport{
+		next:   next,
+		source: source,
+	}
+}
+
+// RoundTrip implements http.RoundTripper.
+func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error) {
+	req = req.Clone(req.Context())
+	if req.Header == nil {
+		req.Header = make(http.Header)
+	}
+	stripRestrictedHeaders(req.Header)
+
+	if t.source != nil && t.routeAllowsSignals(req) {
+		snapshot := t.source.Snapshot()
+		if isSupportedOSType(snapshot.OSType) {
+			req.Header.Set(HeaderOSType, string(snapshot.OSType))
+		}
+		if model := normalizeDeviceModel(snapshot.ProductModel); model != "" {
+			req.Header.Set(HeaderProductModel, model)
+		}
+	}
+	return t.next.RoundTrip(req)
+}
+
+func isSupportedOSType(value OSType) bool {
+	switch value {
+	case OSTypeWindows, OSTypeLinux, OSTypeMacOS:
+		return true
+	default:
+		return false
+	}
+}
+
+func stripRestrictedHeaders(header http.Header) {
+	for name := range header {
+		for _, restricted := range restrictedHeaders {
+			if strings.EqualFold(name, restricted) {
+				delete(header, name)
+				break
+			}
+		}
+	}
+}
+
+type origin struct {
+	scheme string
+	host   string
+	port   string
+}
+
+var officialFeishuOrigins = [...]origin{
+	apiOrigin(core.BrandFeishu, core.ResolveEndpoints(core.BrandFeishu).Open),
+	apiOrigin(core.BrandLark, core.ResolveEndpoints(core.BrandLark).Open),
+	apiOrigin(core.BrandFeishu, core.ResolveEndpoints(core.BrandFeishu).Accounts),
+	apiOrigin(core.BrandLark, core.ResolveEndpoints(core.BrandLark).Accounts),
+}
+
+func (t *Transport) routeAllowsSignals(req *http.Request) bool {
+	if req == nil || req.URL == nil {
+		return false
+	}
+	return isOfficialFeishuOrigin(originOf(req.URL))
+}
+
+func originOf(value *url.URL) origin {
+	if value == nil {
+		return origin{}
+	}
+	scheme := strings.ToLower(value.Scheme)
+	port := value.Port()
+	if port == "" {
+		switch scheme {
+		case "https":
+			port = "443"
+		case "http":
+			port = "80"
+		}
+	}
+	return origin{scheme: scheme, host: strings.ToLower(value.Hostname()), port: port}
+}
+
+func apiOrigin(brand core.LarkBrand, endpointURL string) origin {
+	endpoint, err := url.Parse(endpointURL)
+	if err != nil {
+		return origin{}
+	}
+	return originOf(endpoint)
+}
+
+func isOfficialFeishuOrigin(candidate origin) bool {
+	if candidate.scheme != "https" || candidate.port != "443" {
+		return false
+	}
+	for _, official := range officialFeishuOrigins {
+		if candidate == official {
+			return true
+		}
+	}
+	return false
+}

internal/riskcontrol/transport_test.go

@@ -0,0 +1,124 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package riskcontrol
+
+import (
+	"net/http"
+	"strings"
+	"sync/atomic"
+	"testing"
+)
+
+type roundTripFunc func(*http.Request) (*http.Response, error)
+
+func (f roundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) {
+	return f(req)
+}
+
+type countingSource struct {
+	calls atomic.Int32
+}
+
+func (s *countingSource) Snapshot() Snapshot {
+	s.calls.Add(1)
+	return Snapshot{OSType: OSTypeMacOS, ProductModel: "Mac16,1"}
+}
+
+type staticSource Snapshot
+
+func (s staticSource) Snapshot() Snapshot { return Snapshot(s) }
+
+func TestTransportAuthorizesBeforeCollecting(t *testing.T) {
+	tests := []struct {
+		name          string
+		requestURL    string
+		authorization string
+		wantSignals   bool
+	}{
+		{name: "authenticated official HTTPS", requestURL: "https://open.feishu.cn/open-apis/test", authorization: "Bearer token", wantSignals: true},
+		{name: "Lark official HTTPS", requestURL: "https://open.larksuite.com/open-apis/test", authorization: "Bearer token", wantSignals: true},
+		{name: "official explicit HTTPS port", requestURL: "https://OPEN.FEISHU.CN:443/open-apis/test", authorization: "Bearer token", wantSignals: true},
+		{name: "unauthenticated", requestURL: "https://open.feishu.cn/open-apis/test", wantSignals: true},
+		{name: "official non-OpenAPI origin", requestURL: "https://accounts.feishu.cn/open-apis/test", authorization: "Bearer token", wantSignals: true},
+		{name: "off domain", requestURL: "https://example.com/test", authorization: "Bearer token", wantSignals: false},
+		{name: "lookalike", requestURL: "https://open.feishu.cn.evil.example/test", authorization: "Bearer token", wantSignals: false},
+		{name: "plain HTTP", requestURL: "http://open.feishu.cn/test", authorization: "Bearer token", wantSignals: false},
+		{name: "non-default port", requestURL: "https://open.feishu.cn:8443/test", authorization: "Bearer token", wantSignals: false},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			source := &countingSource{}
+			var received http.Header
+			base := roundTripFunc(func(req *http.Request) (*http.Response, error) {
+				received = req.Header.Clone()
+				return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody}, nil
+			})
+			req, err := http.NewRequest(http.MethodGet, test.requestURL, nil)
+			if err != nil {
+				t.Fatal(err)
+			}
+			req.Header.Set("Authorization", test.authorization)
+			req.Header.Set(HeaderOSType, "caller-value")
+			req.Header.Set(HeaderProductModel, "caller-value")
+			req.Header["x-agent-device-type"] = []string{"non-canonical-caller-value"}
+
+			resp, err := NewTransport(base, source).RoundTrip(req)
+			if err != nil {
+				t.Fatal(err)
+			}
+			resp.Body.Close()
+
+			gotSignals := received.Get(HeaderOSType) != ""
+			if gotSignals != test.wantSignals {
+				t.Fatalf("signals present = %t, want %t; headers=%v", gotSignals, test.wantSignals, received)
+			}
+			wantCalls := int32(0)
+			if test.wantSignals {
+				wantCalls = 1
+			}
+			if got := source.calls.Load(); got != wantCalls {
+				t.Fatalf("Snapshot calls = %d, want %d", got, wantCalls)
+			}
+			if got := req.Header.Get(HeaderOSType); got != "caller-value" {
+				t.Fatalf("caller request OS header = %q, want unchanged", got)
+			}
+			if got := req.Header.Get(HeaderProductModel); got != "caller-value" {
+				t.Fatalf("caller request product-model header = %q, want unchanged", got)
+			}
+			if !test.wantSignals {
+				for name := range received {
+					if strings.EqualFold(name, HeaderProductModel) || strings.EqualFold(name, HeaderOSType) {
+						t.Fatalf("restricted header leaked as %q", name)
+					}
+				}
+			}
+		})
+	}
+}
+
+func TestTransportValidatesSourceSnapshot(t *testing.T) {
+	var received http.Header
+	base := roundTripFunc(func(req *http.Request) (*http.Response, error) {
+		received = req.Header.Clone()
+		return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody}, nil
+	})
+	req, err := http.NewRequest(http.MethodGet, "https://open.feishu.cn/open-apis/test", nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	req.Header.Set("Authorization", "Bearer token")
+
+	resp, err := NewTransport(base, staticSource{
+		OSType:       OSType("unsupported"),
+		ProductModel: "unsafe\nvalue",
+	}).RoundTrip(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	resp.Body.Close()
+	if received.Get(HeaderOSType) == "" && received.Get(HeaderProductModel) == "" {
+		t.Fatalf("no signals collected: %v", received)
+	}
+}

internal/vfs/localfileio/localfileio.go

@@ -5,14 +5,10 @@ package localfileio
 
 import (
 	"context"
-	"fmt"
 	"io"
-	"os"
 	"path/filepath"
-	"strings"
 
 	"github.com/larksuite/cli/extension/fileio"
-	"github.com/larksuite/cli/internal/charcheck"
 	"github.com/larksuite/cli/internal/vfs"
 )
 
@@ -34,8 +30,6 @@ func init() {
 // and atomic writes are handled internally.
 type LocalFileIO struct{}
 
-var _ fileio.TempDirFileCreator = (*LocalFileIO)(nil)
-
 // Open opens a local file for reading after validating the path.
 func (l *LocalFileIO) Open(name string) (fileio.File, error) {
 	safePath, err := SafeInputPath(name)
@@ -68,46 +62,6 @@ func (l *LocalFileIO) ResolvePath(path string) (string, error) {
 	return resolved, nil
 }
 
-// CreateTempDirFile atomically creates a unique directory in the current
-// working directory, then creates the requested empty file inside it.
-func (l *LocalFileIO) CreateTempDirFile(directoryPattern, fileName string) (string, error) {
-	if err := validateTempDirectoryPattern(directoryPattern); err != nil {
-		return "", &fileio.PathValidationError{Err: err}
-	}
-	if err := validateTempFileName(fileName); err != nil {
-		return "", &fileio.PathValidationError{Err: err}
-	}
-	tempDir, err := vfs.MkdirTemp(".", directoryPattern)
-	if err != nil {
-		return "", &fileio.MkdirError{Err: err}
-	}
-	path := filepath.Join(tempDir, fileName)
-	tempFile, err := vfs.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600)
-	if err != nil {
-		_ = vfs.RemoveAll(tempDir)
-		return "", &fileio.WriteError{Err: err}
-	}
-	if err := tempFile.Close(); err != nil {
-		_ = vfs.RemoveAll(tempDir)
-		return "", &fileio.WriteError{Err: fmt.Errorf("close temporary file: %w", err)}
-	}
-	return filepath.Join(filepath.Base(tempDir), fileName), nil
-}
-
-func validateTempDirectoryPattern(pattern string) error {
-	if strings.TrimSpace(pattern) == "" || strings.ContainsAny(pattern, `/\\`) || strings.Count(pattern, "*") != 1 {
-		return fmt.Errorf("temporary directory pattern must be one non-empty path component containing exactly one '*'")
-	}
-	return charcheck.RejectControlChars(pattern, "temporary directory pattern")
-}
-
-func validateTempFileName(fileName string) error {
-	if strings.TrimSpace(fileName) == "" || fileName != filepath.Base(fileName) || strings.ContainsAny(fileName, "/\\\t\r\n") {
-		return fmt.Errorf("temporary file name must be one non-empty path component")
-	}
-	return charcheck.RejectControlChars(fileName, "temporary file name")
-}
-
 // Save writes body to path atomically after validating the output path.
 // Parent directories are created as needed. The body is streamed directly
 // to a temp file and renamed, avoiding full in-memory buffering.

internal/vfs/localfileio/localfileio_test.go

@@ -4,12 +4,10 @@
 package localfileio
 
 import (
-	"errors"
 	"io"
 	"os"
 	"path/filepath"
 	"strings"
-	"sync"
 	"testing"
 
 	"github.com/larksuite/cli/extension/fileio"
@@ -252,81 +250,6 @@ func TestLocalFileIO_ResolvePath_RejectsAbsolute(t *testing.T) {
 	}
 }
 
-func TestLocalFileIO_CreateTempDirFileIsUniqueUnderConcurrency(t *testing.T) {
-	dir := t.TempDir()
-	testChdir(t, dir)
-
-	const count = 32
-	type result struct {
-		path string
-		err  error
-	}
-	results := make(chan result, count)
-	var wg sync.WaitGroup
-	for i := 0; i < count; i++ {
-		wg.Add(1)
-		go func() {
-			defer wg.Done()
-			path, err := (&LocalFileIO{}).CreateTempDirFile("川西_*_folder", "川西.xml")
-			results <- result{path: path, err: err}
-		}()
-	}
-	wg.Wait()
-	close(results)
-
-	seen := make(map[string]struct{}, count)
-	for result := range results {
-		if result.err != nil {
-			t.Fatalf("CreateTempDirFile failed: %v", result.err)
-		}
-		directory := filepath.Dir(result.path)
-		if filepath.Base(result.path) != "川西.xml" || filepath.Base(directory) != directory ||
-			!strings.HasPrefix(directory, "川西_") || !strings.HasSuffix(directory, "_folder") {
-			t.Fatalf("CreateTempDirFile path = %q, want 川西_<random>_folder/川西.xml", result.path)
-		}
-		if _, ok := seen[directory]; ok {
-			t.Fatalf("CreateTempDirFile returned duplicate directory %q", directory)
-		}
-		seen[directory] = struct{}{}
-		info, err := os.Stat(result.path)
-		if err != nil {
-			t.Fatalf("stat temporary file %q: %v", result.path, err)
-		}
-		if info.Size() != 0 {
-			t.Fatalf("temporary file %q size = %d, want 0", result.path, info.Size())
-		}
-	}
-	if len(seen) != count {
-		t.Fatalf("unique temporary files = %d, want %d", len(seen), count)
-	}
-}
-
-func TestLocalFileIO_CreateTempDirFileRejectsUnsafeComponents(t *testing.T) {
-	dir := t.TempDir()
-	testChdir(t, dir)
-	fio := &LocalFileIO{}
-
-	for _, test := range []struct {
-		pattern  string
-		fileName string
-	}{
-		{pattern: "../lark-doc-*", fileName: "draft.xml"},
-		{pattern: "lark-doc-*", fileName: "../draft.xml"},
-		{pattern: "lark-doc-*", fileName: `folder\draft.xml`},
-	} {
-		if _, err := fio.CreateTempDirFile(test.pattern, test.fileName); !errors.Is(err, fileio.ErrPathValidation) {
-			t.Errorf("CreateTempDirFile(%q, %q) error = %v, want path validation", test.pattern, test.fileName, err)
-		}
-	}
-	entries, err := os.ReadDir(dir)
-	if err != nil {
-		t.Fatalf("read work directory: %v", err)
-	}
-	if len(entries) != 0 {
-		t.Fatalf("invalid inputs created files: %+v", entries)
-	}
-}
-
 // ── Error message consistency ──
 
 func TestLocalFileIO_ErrorMessages_ContainCorrectFlagName(t *testing.T) {

lint/README.md

@@ -19,7 +19,7 @@ lint/
 ├── lintapi/            # shared types every domain returns
 │   └── violation.go    # Violation, Action, ActionReject / ActionLabel / ActionWarning
 └── errscontract/       # first domain: typed-error contract guards
-    ├── scan.go         # ScanRepo(root) ([]lintapi.Violation, error)  ← public entry
+    ├── scan.go         # ScanRepoWithOptions(root, opts)  ← public entry
     ├── runner.go
     ├── typecheck.go
     ├── violation.go    # local type aliases to lintapi
@@ -30,16 +30,19 @@ lint/
     ├── rule_subtype_classifier.go
     ├── rule_typed_error_completeness.go
     └── *_test.go
-└── domaincontract/     # endpoint domain contract: no hardcoded resolver hosts
-    ├── scan.go         # ScanRepo(root) ([]lintapi.Violation, error)  ← public entry
-    └── scan_test.go
+└── domaincontract/     # resolver ownership + approved public hostname policy
+    ├── scan.go         # ScanRepoWithOptions(root, opts)  ← public entry
+    ├── unapproved.go   # Go AST/type-aware hostname extraction
+    ├── policy.go       # exact public/fixture allowlist validation
+    ├── diff.go         # added-line attribution
+    └── *_test.go
 ```
 
 ## Endpoint domain contract (`domaincontract`)
 
-`domaincontract` is a syntax-level regression guard for the resolver-owned
-Open, Accounts, MCP, and AppLink hosts used by the Go CLI. In production `.go`
-files it rejects:
+`domaincontract` contains two complementary Go source guards.
+
+The resolver-ownership guard rejects:
 
 - string literals containing a resolver-owned host FQDN
   (`{open,accounts,mcp,applink}.{feishu.cn,larksuite.com}`), and
@@ -59,17 +62,54 @@ parse-level guard). The forbidden-host list is bound to the resolver source by
 `TestForbiddenHostsMatchResolver`, so adding a resolver domain without updating
 the guard fails the lint module's tests.
 
-This is not a general outbound-URL or data-flow analyzer. It does not inspect
-non-Go assets, hosts assembled from string fragments, SDK constructor option
-flow, or previously unknown Feishu/Lark hosts. The literal rule and code review
-remain the backstop for those cases.
+The approved-domain guard parses every Git-tracked Go file in full. In CI,
+unapproved-host findings are limited to values whose expressions intersect an
+added line; policy validation and unused-entry checks remain repository-wide.
+It rejects an exact hostname unless it is present in one of:
 
-To add or change an outbound endpoint, edit the resolver — never hardcode a host.
+- `internal/qualitygate/config/allowlists/public-domains.txt`, for production
+  and test code; or
+- `internal/qualitygate/config/allowlists/fixture-domains.txt`, only for
+  `*_test.go`, the repository-root `tests/`, and any `testdata/` (never
+  `skills/`).
+
+RFC 2606 example/test names are accepted independently of those lists. This
+includes the reserved `.test`, `.example`, `.invalid`, and `.localhost`
+namespaces and the exact names `example.com`, `example.net`, and `example.org`;
+they are safe placeholders rather than supported public endpoints.
+
+High-confidence evidence is deliberately limited to static string expressions
+assigned to `host`, `hostname`, or `domain` semantic names (including common
+case/plural forms and collections), plus static strings whose entire value is
+an absolute `http`, `https`, `ws`, or `wss` URL. It supports Go literals,
+escapes, compile-time concatenation, constant references, grouped declarations,
+multi-value assignments, and multiline expressions. Bare domain-shaped strings
+without hostname semantics are not blocked.
+
+Sequence values are scanned individually. For a hostname-semantic map, a key or
+value is evidence only when it is the sole hostname-shaped side of that entry;
+ambiguous string-to-string entries are not guessed. Struct fields use Go type
+information so known non-network `Host` / `Domain` fields do not become hostname
+evidence merely because an enum or command category contains a dot.
+
+Allowlist matching is lowercase and exact: there are no wildcard, suffix, DNS,
+or public-suffix exceptions. Entries must be sorted and unique, use ASCII
+hostnames, and have a current in-scope use. See
+`internal/qualitygate/config/README.md` for admission and approval rules.
+
+This is not a general outbound-URL or cross-language data-flow analyzer. It does
+not inspect non-Go assets or dynamically constructed values.
+
+To add or change a resolver-owned Feishu/Lark endpoint, edit the resolver rather
+than hardcoding the host elsewhere.
 
 ## Running
 
 ```bash
-# from the repo root (one level above lint/)
+# PR-scoped scan from the repo root (one level above lint/)
+go run -C lint . --changed-from <base-revision> ..
+
+# Full inventory (also reports historical unapproved hostnames)
 go run -C lint . ..
 ```
 
@@ -100,10 +140,14 @@ Exit codes follow `lint/main.go`:
 
    import "github.com/larksuite/cli/lint/lintapi"
 
-   // ScanRepo walks root and returns every violation produced by this
-   // domain's checks. Domains MUST return []lintapi.Violation so the
-   // top-level dispatcher can aggregate uniformly.
-   func ScanRepo(root string) ([]lintapi.Violation, error) { ... }
+   type ScanOptions struct {
+       ChangedFrom string
+   }
+
+   // ScanRepoWithOptions walks root and returns every violation produced
+   // by this domain's checks. Domains MUST return []lintapi.Violation so
+   // the top-level dispatcher can aggregate uniformly.
+   func ScanRepoWithOptions(root string, opts ScanOptions) ([]lintapi.Violation, error) { ... }
    ```
 
 3. Per-rule files are named `rule_<name>.go` with sibling
@@ -114,8 +158,12 @@ Exit codes follow `lint/main.go`:
 
    ```go
    var scanners = []scanner{
-       {name: "errscontract", fn: errscontract.ScanRepo},
-       {name: "<domain>",     fn: <domain>.ScanRepo},  // ← add here
+       {name: "errscontract", fn: errscontract.ScanRepoWithOptions},
+       {name: "<domain>", fn: func(root string, opts errscontract.ScanOptions) ([]lintapi.Violation, error) {
+           return <domain>.ScanRepoWithOptions(root, <domain>.ScanOptions{
+               ChangedFrom: opts.ChangedFrom,
+           })
+       }},
    }
    ```
 

lint/domaincontract/diff.go

@@ -0,0 +1,171 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package domaincontract
+
+import (
+	"bytes"
+	"fmt"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+)
+
+type addedLineRange struct {
+	Start int
+	End   int
+}
+
+type changedGoPath struct {
+	Old string
+	New string
+}
+
+var unifiedHunkRE = regexp.MustCompile(`^@@ -[0-9]+(?:,[0-9]+)? \+([0-9]+)(?:,([0-9]+))? @@`)
+
+func changedGoLineRanges(root, from string) (map[string][]addedLineRange, error) {
+	if from == "" {
+		return nil, nil
+	}
+	names, err := gitCommandOutput(
+		root,
+		"diff",
+		"--name-status",
+		"-z",
+		"--find-renames",
+		"--diff-filter=ACMR",
+		from+"...HEAD",
+		"--",
+	)
+	if err != nil {
+		return nil, fmt.Errorf("list changed Go files: %w", err)
+	}
+	paths, err := parseChangedGoPaths(names)
+	if err != nil {
+		return nil, fmt.Errorf("parse changed Go files: %w", err)
+	}
+
+	out := map[string][]addedLineRange{}
+	for _, path := range paths {
+		args := []string{
+			"diff",
+			"--unified=0",
+			"--no-color",
+			"--no-ext-diff",
+			"--find-renames",
+			"--diff-filter=ACMR",
+			from + "...HEAD",
+			"--",
+		}
+		if path.Old != path.New {
+			args = append(args, path.Old)
+		}
+		args = append(args, path.New)
+		patch, err := gitCommandOutput(root, args...)
+		if err != nil {
+			return nil, fmt.Errorf("read diff for %s: %w", path.New, err)
+		}
+		ranges, err := parseAddedLineRanges(patch)
+		if err != nil {
+			return nil, fmt.Errorf("parse diff for %s: %w", path.New, err)
+		}
+		out[path.New] = ranges
+	}
+	return out, nil
+}
+
+func parseChangedGoPaths(raw []byte) ([]changedGoPath, error) {
+	fields := bytes.Split(raw, []byte{0})
+	var out []changedGoPath
+	for i := 0; i < len(fields); {
+		status := string(fields[i])
+		i++
+		if status == "" {
+			break
+		}
+		if i >= len(fields) || len(fields[i]) == 0 {
+			return nil, fmt.Errorf("truncated name-status record")
+		}
+		oldPath := filepath.ToSlash(string(fields[i]))
+		i++
+		newPath := oldPath
+		if status[0] == 'R' || status[0] == 'C' {
+			if i >= len(fields) || len(fields[i]) == 0 {
+				return nil, fmt.Errorf("truncated rename/copy record for %q", oldPath)
+			}
+			newPath = filepath.ToSlash(string(fields[i]))
+			i++
+			if status[0] == 'C' {
+				// A copy introduces every destination line. Diff only the new
+				// path so Git presents it as an added file rather than a
+				// metadata-only copy with no added-line ranges.
+				oldPath = newPath
+			}
+		}
+		if !strings.HasSuffix(newPath, ".go") {
+			continue
+		}
+		out = append(out, changedGoPath{Old: oldPath, New: newPath})
+	}
+	return out, nil
+}
+
+func parseAddedLineRanges(patch []byte) ([]addedLineRange, error) {
+	var out []addedLineRange
+	for _, raw := range bytes.Split(patch, []byte{'\n'}) {
+		line := string(raw)
+		if !strings.HasPrefix(line, "@@") {
+			continue
+		}
+		match := unifiedHunkRE.FindStringSubmatch(line)
+		if match == nil {
+			return nil, fmt.Errorf("unsupported unified hunk header %q", line)
+		}
+		start, err := strconv.Atoi(match[1])
+		if err != nil {
+			return nil, fmt.Errorf("parse added start line in %q: %w", line, err)
+		}
+		count := 1
+		if match[2] != "" {
+			count, err = strconv.Atoi(match[2])
+			if err != nil {
+				return nil, fmt.Errorf("parse added line count in %q: %w", line, err)
+			}
+		}
+		if count == 0 {
+			continue
+		}
+		out = append(out, addedLineRange{Start: start, End: start + count - 1})
+	}
+	return out, nil
+}
+
+func firstAddedLineInSpan(ranges []addedLineRange, start, end int) (int, bool) {
+	for _, r := range ranges {
+		if start <= r.End && end >= r.Start {
+			if start > r.Start {
+				return start, true
+			}
+			return r.Start, true
+		}
+	}
+	return 0, false
+}
+
+func gitCommandOutput(root string, args ...string) ([]byte, error) {
+	cmd := exec.Command("git", args...)
+	cmd.Dir = root
+	out, err := cmd.Output()
+	if err == nil {
+		return out, nil
+	}
+	if exitErr, ok := err.(*exec.ExitError); ok {
+		stderr := strings.TrimSpace(string(exitErr.Stderr))
+		if stderr != "" {
+			return nil, fmt.Errorf("%w: %s", err, stderr)
+		}
+	}
+	return nil, err
+}

lint/domaincontract/diff_test.go

@@ -0,0 +1,96 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package domaincontract
+
+import "testing"
+
+func TestParseChangedGoPaths(t *testing.T) {
+	raw := []byte("M\x00changed.go\x00R100\x00old.go\x00renamed.go\x00C100\x00source.go\x00copied.go\x00A\x00README.md\x00")
+	got, err := parseChangedGoPaths(raw)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []changedGoPath{
+		{Old: "changed.go", New: "changed.go"},
+		{Old: "old.go", New: "renamed.go"},
+		{Old: "copied.go", New: "copied.go"},
+	}
+	if len(got) != len(want) {
+		t.Fatalf("paths = %#v, want %#v", got, want)
+	}
+	for i := range got {
+		if got[i] != want[i] {
+			t.Fatalf("paths = %#v, want %#v", got, want)
+		}
+	}
+}
+
+func TestParseChangedGoPathsRejectsTruncatedRename(t *testing.T) {
+	if _, err := parseChangedGoPaths([]byte("R100\x00old.go\x00")); err == nil {
+		t.Fatal("expected truncated rename error")
+	}
+}
+
+func TestParseAddedLineRanges(t *testing.T) {
+	patch := []byte(`diff --git a/x.go b/x.go
+index 1111111..2222222 100644
+--- a/x.go
++++ b/x.go
+@@ -2,0 +3,2 @@
++first
++second
+@@ -10 +12 @@
+-old
++new
+@@ -20 +21,0 @@
+-deleted
+`)
+	got, err := parseAddedLineRanges(patch)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []addedLineRange{{Start: 3, End: 4}, {Start: 12, End: 12}}
+	if len(got) != len(want) {
+		t.Fatalf("ranges = %#v, want %#v", got, want)
+	}
+	for i := range got {
+		if got[i] != want[i] {
+			t.Fatalf("ranges = %#v, want %#v", got, want)
+		}
+	}
+}
+
+func TestParseAddedLineRangesRejectsUnknownHunk(t *testing.T) {
+	if _, err := parseAddedLineRanges([]byte("@@@ unsupported @@@\n")); err == nil {
+		t.Fatal("expected unsupported hunk error")
+	}
+}
+
+func TestFirstAddedLineInSpan(t *testing.T) {
+	ranges := []addedLineRange{{Start: 5, End: 7}, {Start: 10, End: 10}}
+	tests := []struct {
+		start, end int
+		line       int
+		ok         bool
+	}{
+		{start: 1, end: 4, ok: false},
+		{start: 4, end: 6, line: 5, ok: true},
+		{start: 6, end: 9, line: 6, ok: true},
+		{start: 8, end: 12, line: 10, ok: true},
+	}
+	for _, tc := range tests {
+		line, ok := firstAddedLineInSpan(ranges, tc.start, tc.end)
+		if line != tc.line || ok != tc.ok {
+			t.Errorf(
+				"firstAddedLineInSpan(%d, %d) = (%d, %v), want (%d, %v)",
+				tc.start,
+				tc.end,
+				line,
+				ok,
+				tc.line,
+				tc.ok,
+			)
+		}
+	}
+}

lint/domaincontract/policy.go

@@ -0,0 +1,126 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package domaincontract
+
+import (
+	"bufio"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+const (
+	publicDomainsPath  = "internal/qualitygate/config/allowlists/public-domains.txt"
+	fixtureDomainsPath = "internal/qualitygate/config/allowlists/fixture-domains.txt"
+)
+
+type domainPolicyEntry struct {
+	Host string
+	File string
+	Line int
+}
+
+type domainPolicy struct {
+	Public   map[string]domainPolicyEntry
+	Fixtures map[string]domainPolicyEntry
+}
+
+// isReservedExampleHostname recognizes only names reserved by RFC 2606 for
+// examples, testing, invalid-name examples, and localhost use. These names are
+// safe source placeholders and are policy exceptions, not supported public
+// endpoints.
+func isReservedExampleHostname(host string) bool {
+	host = strings.TrimSuffix(strings.ToLower(strings.TrimSpace(host)), ".")
+	switch host {
+	case "example.com", "example.net", "example.org":
+		return true
+	}
+	labels := strings.Split(host, ".")
+	switch labels[len(labels)-1] {
+	case "test", "example", "invalid", "localhost":
+		return true
+	default:
+		return false
+	}
+}
+
+func loadDomainPolicy(root string) (domainPolicy, error) {
+	public, err := loadDomainList(root, publicDomainsPath)
+	if err != nil {
+		return domainPolicy{}, err
+	}
+	fixtures, err := loadDomainList(root, fixtureDomainsPath)
+	if err != nil {
+		return domainPolicy{}, err
+	}
+	for host, entry := range fixtures {
+		if publicEntry, ok := public[host]; ok {
+			return domainPolicy{}, fmt.Errorf(
+				"%s:%d: hostname %q is already listed at %s:%d",
+				entry.File, entry.Line, host, publicEntry.File, publicEntry.Line,
+			)
+		}
+	}
+	return domainPolicy{Public: public, Fixtures: fixtures}, nil
+}
+
+func loadDomainList(root, rel string) (map[string]domainPolicyEntry, error) {
+	path := filepath.Join(root, filepath.FromSlash(rel))
+	file, err := os.Open(path)
+	if err != nil {
+		return nil, fmt.Errorf("open domain allowlist %s: %w", rel, err)
+	}
+	defer file.Close()
+
+	entries := map[string]domainPolicyEntry{}
+	var previous string
+	scanner := bufio.NewScanner(file)
+	for line := 1; scanner.Scan(); line++ {
+		host := strings.TrimSpace(scanner.Text())
+		if host == "" || strings.HasPrefix(host, "#") {
+			continue
+		}
+		if host != strings.ToLower(host) {
+			return nil, fmt.Errorf("%s:%d: hostname must be lowercase: %q", rel, line, host)
+		}
+		if err := validatePolicyHostname(host); err != nil {
+			return nil, fmt.Errorf("%s:%d: %w", rel, line, err)
+		}
+		if previous != "" && host <= previous {
+			return nil, fmt.Errorf("%s:%d: hostnames must be unique and sorted: %q", rel, line, host)
+		}
+		entries[host] = domainPolicyEntry{Host: host, File: rel, Line: line}
+		previous = host
+	}
+	if err := scanner.Err(); err != nil {
+		return nil, fmt.Errorf("read domain allowlist %s: %w", rel, err)
+	}
+	if len(entries) == 0 {
+		return nil, fmt.Errorf("%s: domain list must not be empty", rel)
+	}
+	return entries, nil
+}
+
+func validatePolicyHostname(host string) error {
+	if len(host) > 253 || !strings.Contains(host, ".") || strings.HasSuffix(host, ".") {
+		return fmt.Errorf("invalid exact hostname %q", host)
+	}
+	labels := strings.Split(host, ".")
+	for _, label := range labels {
+		if len(label) == 0 || len(label) > 63 || label[0] == '-' || label[len(label)-1] == '-' {
+			return fmt.Errorf("invalid exact hostname %q", host)
+		}
+		for _, r := range label {
+			if (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9') || r == '-' {
+				continue
+			}
+			return fmt.Errorf("invalid exact hostname %q", host)
+		}
+	}
+	if !strings.ContainsAny(labels[len(labels)-1], "abcdefghijklmnopqrstuvwxyz") {
+		return fmt.Errorf("invalid exact hostname %q", host)
+	}
+	return nil
+}

lint/domaincontract/policy_test.go

@@ -0,0 +1,120 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package domaincontract
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestLoadDomainPolicy(t *testing.T) {
+	root := t.TempDir()
+	writeFile(t, root, publicDomainsPath, "# public\napi.example.com\nwww.example.com\n")
+	writeFile(t, root, fixtureDomainsPath, "# fixtures\nfixture.example.com\n")
+
+	policy, err := loadDomainPolicy(root)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(policy.Public) != 2 || len(policy.Fixtures) != 1 {
+		t.Fatalf("unexpected policy sizes: public=%d fixtures=%d", len(policy.Public), len(policy.Fixtures))
+	}
+	if policy.Public["api.example.com"].Line != 2 {
+		t.Fatalf("api.example.com line = %d, want 2", policy.Public["api.example.com"].Line)
+	}
+}
+
+func TestLoadDomainPolicyRejectsInvalidLists(t *testing.T) {
+	tests := []struct {
+		name     string
+		public   string
+		fixtures string
+		want     string
+	}{
+		{
+			name:     "uppercase",
+			public:   "API.example.com\n",
+			fixtures: "fixture.example.com\n",
+			want:     "must be lowercase",
+		},
+		{
+			name:     "unsorted",
+			public:   "www.example.com\napi.example.com\n",
+			fixtures: "fixture.example.com\n",
+			want:     "unique and sorted",
+		},
+		{
+			name:     "duplicate",
+			public:   "api.example.com\napi.example.com\n",
+			fixtures: "fixture.example.com\n",
+			want:     "unique and sorted",
+		},
+		{
+			name:     "wildcard",
+			public:   "*.example.com\n",
+			fixtures: "fixture.example.com\n",
+			want:     "invalid exact hostname",
+		},
+		{
+			name:     "scheme",
+			public:   "https://example.com\n",
+			fixtures: "fixture.example.com\n",
+			want:     "invalid exact hostname",
+		},
+		{
+			name:     "path",
+			public:   "api.example.com/v1\n",
+			fixtures: "fixture.example.com\n",
+			want:     "invalid exact hostname",
+		},
+		{
+			name:     "port",
+			public:   "api.example.com:443\n",
+			fixtures: "fixture.example.com\n",
+			want:     "invalid exact hostname",
+		},
+		{
+			name:     "cross-list duplicate",
+			public:   "api.example.com\n",
+			fixtures: "api.example.com\n",
+			want:     "already listed",
+		},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			root := t.TempDir()
+			writeFile(t, root, publicDomainsPath, tc.public)
+			writeFile(t, root, fixtureDomainsPath, tc.fixtures)
+			_, err := loadDomainPolicy(root)
+			if err == nil || !strings.Contains(err.Error(), tc.want) {
+				t.Fatalf("loadDomainPolicy() error = %v, want substring %q", err, tc.want)
+			}
+		})
+	}
+}
+
+func TestReservedExampleHostname(t *testing.T) {
+	for _, host := range []string{
+		"example.com",
+		"example.net",
+		"example.org",
+		"example.test",
+		"docs.example",
+		"missing.invalid",
+		"service.localhost",
+	} {
+		if !isReservedExampleHostname(host) {
+			t.Errorf("%q should be a reserved example hostname", host)
+		}
+	}
+	for _, host := range []string{
+		"attacker.example.com",
+		"example.dev",
+		"private.corp.internal",
+	} {
+		if isReservedExampleHostname(host) {
+			t.Errorf("%q must still require policy approval", host)
+		}
+	}
+}

lint/domaincontract/scan.go

@@ -1,8 +1,8 @@
 // Copyright (c) 2026 Lark Technologies Pte. Ltd.
 // SPDX-License-Identifier: MIT
 
-// Package domaincontract guards the Go CLI against direct reuse of the current
-// resolver-owned host FQDNs outside core.ResolveEndpoints.
+// Package domaincontract guards resolver ownership and rejects newly introduced
+// static Go hostnames that are not covered by the repository domain policy.
 package domaincontract
 
 import (
@@ -11,6 +11,7 @@ import (
 	"go/token"
 	"io/fs"
 	"path/filepath"
+	"sort"
 	"strconv"
 	"strings"
 
@@ -75,10 +76,40 @@ func skipDir(name string) bool {
 	return false
 }
 
-// ScanRepo walks production .go files under root and flags string literals
-// containing a forbidden resolver host outside the allowlist. Comments and
-// _test.go files are not scanned.
+// ScanRepo runs the resolver-owned endpoint guard and a full repository domain
+// inventory. CI should use ScanRepoWithOptions with a changed-from revision so
+// historical unapproved domains are not attributed to an unrelated change.
 func ScanRepo(root string) ([]lintapi.Violation, error) {
+	return ScanRepoWithOptions(root, ScanOptions{})
+}
+
+type ScanOptions struct {
+	ChangedFrom string
+}
+
+func ScanRepoWithOptions(root string, opts ScanOptions) ([]lintapi.Violation, error) {
+	out, err := scanHardcodedEndpoints(root)
+	if err != nil {
+		return nil, err
+	}
+	domainViolations, err := scanUnapprovedDomains(root, opts)
+	if err != nil {
+		return nil, err
+	}
+	out = append(out, domainViolations...)
+	sort.SliceStable(out, func(i, j int) bool {
+		if out[i].File != out[j].File {
+			return out[i].File < out[j].File
+		}
+		if out[i].Line != out[j].Line {
+			return out[i].Line < out[j].Line
+		}
+		return out[i].Rule < out[j].Rule
+	})
+	return out, nil
+}
+
+func scanHardcodedEndpoints(root string) ([]lintapi.Violation, error) {
 	var out []lintapi.Violation
 	err := filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
 		if err != nil {

lint/domaincontract/unapproved.go

@@ -0,0 +1,911 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package domaincontract
+
+import (
+	"fmt"
+	"go/ast"
+	"go/constant"
+	"go/parser"
+	"go/token"
+	"go/types"
+	"net"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"unicode"
+
+	"github.com/larksuite/cli/lint/lintapi"
+	"golang.org/x/tools/go/packages"
+)
+
+const (
+	unapprovedDomainRule = "unapproved-domain"
+	unusedDomainRule     = "domain-allowlist-unused"
+	incompleteDomainRule = "domain-scan-incomplete"
+)
+
+type typedGoFile struct {
+	File *ast.File
+	Fset *token.FileSet
+	Info *types.Info
+}
+
+type domainEvidence struct {
+	Host string
+	Kind string
+	Expr ast.Expr
+}
+
+type evidenceKey struct {
+	Host       string
+	Start, End token.Pos
+}
+
+type fileDomainScan struct {
+	File             *ast.File
+	Fset             *token.FileSet
+	Info             *types.Info
+	Evidence         []domainEvidence
+	TypeInfoRequired []ast.Expr
+	seen             map[evidenceKey]bool
+	parents          map[ast.Node]ast.Node
+}
+
+type collectionCompositeKind uint8
+
+const (
+	notCollectionComposite collectionCompositeKind = iota
+	sequenceComposite
+	mapComposite
+)
+
+type hostnameFieldID struct {
+	Type  string
+	Field string
+}
+
+var nonNetworkHostnameFields = map[hostnameFieldID]bool{
+	{Type: "github.com/larksuite/cli/events/im.CardActionTriggerOutput", Field: "Host"}: true,
+	{Type: "github.com/larksuite/cli/internal/cmdmeta.Meta", Field: "Domain"}:           true,
+}
+
+func scanUnapprovedDomains(root string, opts ScanOptions) ([]lintapi.Violation, error) {
+	root, err := filepath.Abs(root)
+	if err != nil {
+		return nil, fmt.Errorf("resolve repository root: %w", err)
+	}
+	publicPath := filepath.Join(root, filepath.FromSlash(publicDomainsPath))
+	if _, err := os.Stat(publicPath); err != nil {
+		if os.IsNotExist(err) {
+			if _, goModErr := os.Stat(filepath.Join(root, "go.mod")); os.IsNotExist(goModErr) {
+				return nil, nil
+			}
+		}
+		return nil, fmt.Errorf("domain policy unavailable: %w", err)
+	}
+	policy, err := loadDomainPolicy(root)
+	if err != nil {
+		return nil, err
+	}
+	added, err := changedGoLineRanges(root, opts.ChangedFrom)
+	if err != nil {
+		return nil, err
+	}
+	typed, typeLoadErr := loadTypedGoFiles(root)
+	goFiles, err := trackedGoFiles(root)
+	if err != nil {
+		return nil, err
+	}
+
+	observedPublic := map[string]bool{}
+	observedFixtures := map[string]bool{}
+	inventoryComplete := typeLoadErr == nil
+	var out []lintapi.Violation
+	parseFailureReported := false
+	typeInfoGapReported := false
+	for _, rel := range goFiles {
+		path := filepath.Join(root, filepath.FromSlash(rel))
+		parsedFset := token.NewFileSet()
+		parsedFile, parseErr := parser.ParseFile(parsedFset, path, nil, 0)
+		if parseErr != nil {
+			inventoryComplete = false
+			if opts.ChangedFrom == "" {
+				out = append(out, incompleteDomainViolation(rel, parseErr))
+				parseFailureReported = true
+			} else if _, changed := added[rel]; changed {
+				out = append(out, incompleteDomainViolation(rel, parseErr))
+				parseFailureReported = true
+			}
+			continue
+		}
+		tf, ok := typed[filepath.Clean(path)]
+		if !ok {
+			tf = typedGoFile{File: parsedFile, Fset: parsedFset}
+		}
+
+		scan := newFileDomainScan(tf)
+		scan.collectSemanticEvidence()
+		scan.collectAbsoluteURLEvidence()
+		if len(scan.TypeInfoRequired) > 0 {
+			// Inventory completeness is a property of the whole HEAD. Whether
+			// this PR owns an incomplete-scan diagnostic is decided separately
+			// by the added-line intersection below.
+			inventoryComplete = false
+		}
+		for _, expr := range scan.TypeInfoRequired {
+			start := tf.Fset.Position(expr.Pos()).Line
+			end := tf.Fset.Position(expr.End()).Line
+			line := start
+			if opts.ChangedFrom != "" {
+				var intersects bool
+				line, intersects = firstAddedLineInSpan(added[rel], start, end)
+				if !intersects {
+					continue
+				}
+			}
+			typeInfoGapReported = true
+			out = append(out, incompleteDomainViolationAt(
+				rel,
+				line,
+				fmt.Errorf("Go type information unavailable for hostname-oriented field evidence"),
+			))
+			break
+		}
+		fixture := isDomainFixturePath(rel)
+		// The detector's own policy literals and contract corpus may be
+		// scanned, but they cannot justify keeping an allowlist entry.
+		policyOwner := strings.HasPrefix(rel, "lint/domaincontract/")
+		for _, evidence := range scan.Evidence {
+			if isReservedExampleHostname(evidence.Host) {
+				continue
+			}
+			if _, ok := policy.Public[evidence.Host]; ok {
+				if !fixture && !policyOwner {
+					observedPublic[evidence.Host] = true
+				}
+				continue
+			}
+			if _, ok := policy.Fixtures[evidence.Host]; ok && fixture {
+				if !policyOwner {
+					observedFixtures[evidence.Host] = true
+				}
+				continue
+			}
+			start := tf.Fset.Position(evidence.Expr.Pos()).Line
+			end := tf.Fset.Position(evidence.Expr.End()).Line
+			line := start
+			if opts.ChangedFrom != "" {
+				var intersects bool
+				line, intersects = firstAddedLineInSpan(added[rel], start, end)
+				if !intersects {
+					continue
+				}
+			}
+			suggestion := "remove the hostname or replace it with an approved public endpoint; " +
+				"public allowlist additions require evidence and CODEOWNER approval"
+			if _, fixtureOnly := policy.Fixtures[evidence.Host]; fixtureOnly && !fixture {
+				suggestion = "remove the fixture-only hostname or move this use into an approved fixture scope; " +
+					"fixture entries are not approved for production Go code or skills"
+			}
+			out = append(out, lintapi.Violation{
+				Rule:   unapprovedDomainRule,
+				Action: lintapi.ActionReject,
+				File:   rel,
+				Line:   line,
+				Message: fmt.Sprintf(
+					"unapproved hostname %q found in %s",
+					evidence.Host,
+					evidence.Kind,
+				),
+				Suggestion: suggestion,
+			})
+		}
+	}
+
+	// A syntax error is also surfaced by go/packages. Prefer the file-specific
+	// parse diagnostic when one was already reported; otherwise make a
+	// repository-wide type-loading failure explicit instead of silently
+	// continuing without the type information required by field evidence.
+	if typeLoadErr != nil && !parseFailureReported && !typeInfoGapReported {
+		out = append(out, incompleteDomainViolation("go.mod", typeLoadErr))
+	}
+
+	if inventoryComplete {
+		for host, entry := range policy.Public {
+			if !observedPublic[host] {
+				out = append(out, unusedDomainViolation(entry))
+			}
+		}
+		for host, entry := range policy.Fixtures {
+			if !observedFixtures[host] {
+				out = append(out, unusedDomainViolation(entry))
+			}
+		}
+	}
+	return out, nil
+}
+
+func trackedGoFiles(root string) ([]string, error) {
+	out, err := gitCommandOutput(root, "ls-files", "-z", "--", "*.go")
+	if err != nil {
+		return nil, fmt.Errorf("list tracked Go files: %w", err)
+	}
+	var files []string
+	for _, raw := range strings.Split(string(out), "\x00") {
+		if raw == "" {
+			continue
+		}
+		rel := filepath.ToSlash(raw)
+		if strings.HasPrefix(rel, "vendor/") || strings.HasPrefix(rel, "node_modules/") {
+			continue
+		}
+		files = append(files, rel)
+	}
+	return files, nil
+}
+
+func loadTypedGoFiles(root string) (map[string]typedGoFile, error) {
+	moduleDirs, err := trackedGoModuleDirs(root)
+	if err != nil {
+		return nil, err
+	}
+	out := map[string]typedGoFile{}
+	var firstLoadErr error
+	var loadErrCount int
+	for _, moduleDir := range moduleDirs {
+		moduleRoot := root
+		if moduleDir != "." {
+			moduleRoot = filepath.Join(root, filepath.FromSlash(moduleDir))
+		}
+		files, err := loadTypedGoModule(moduleRoot)
+		for path, file := range files {
+			out[path] = file
+		}
+		if err != nil {
+			loadErrCount++
+			if firstLoadErr == nil {
+				firstLoadErr = err
+			}
+		}
+	}
+	if loadErrCount == 1 {
+		return out, firstLoadErr
+	}
+	if loadErrCount > 1 {
+		return out, fmt.Errorf("%w (and %d more module errors)", firstLoadErr, loadErrCount-1)
+	}
+	return out, nil
+}
+
+func trackedGoModuleDirs(root string) ([]string, error) {
+	raw, err := gitCommandOutput(root, "ls-files", "-z")
+	if err != nil {
+		return nil, fmt.Errorf("list tracked Go modules: %w", err)
+	}
+	var dirs []string
+	for _, path := range strings.Split(string(raw), "\x00") {
+		path = filepath.ToSlash(path)
+		if path != "go.mod" && !strings.HasSuffix(path, "/go.mod") {
+			continue
+		}
+		dir := filepath.ToSlash(filepath.Dir(path))
+		dirs = append(dirs, dir)
+	}
+	return dirs, nil
+}
+
+func loadTypedGoModule(moduleRoot string) (map[string]typedGoFile, error) {
+	fset := token.NewFileSet()
+	cfg := &packages.Config{
+		Mode: packages.NeedName |
+			packages.NeedFiles |
+			packages.NeedCompiledGoFiles |
+			packages.NeedImports |
+			packages.NeedDeps |
+			packages.NeedTypes |
+			packages.NeedSyntax |
+			packages.NeedTypesInfo,
+		Dir:   moduleRoot,
+		Fset:  fset,
+		Tests: true,
+	}
+	pkgs, err := packages.Load(cfg, "./...")
+	if err != nil {
+		return nil, fmt.Errorf("load Go type information: %w", err)
+	}
+	out := map[string]typedGoFile{}
+	var firstPackageErr string
+	var packageErrCount int
+	packages.Visit(pkgs, nil, func(pkg *packages.Package) {
+		if pkg == nil {
+			return
+		}
+		for _, pkgErr := range pkg.Errors {
+			packageErrCount++
+			if firstPackageErr == "" {
+				firstPackageErr = pkgErr.Error()
+			}
+		}
+		if pkg.TypesInfo == nil || pkg.Fset == nil {
+			return
+		}
+		for i, file := range pkg.Syntax {
+			if i >= len(pkg.CompiledGoFiles) {
+				break
+			}
+			path := filepath.Clean(pkg.CompiledGoFiles[i])
+			if _, exists := out[path]; exists {
+				continue
+			}
+			out[path] = typedGoFile{File: file, Fset: pkg.Fset, Info: pkg.TypesInfo}
+		}
+	})
+	if packageErrCount == 1 {
+		return out, fmt.Errorf("load Go type information: %s", firstPackageErr)
+	}
+	if packageErrCount > 1 {
+		return out, fmt.Errorf(
+			"load Go type information: %s (and %d more package errors)",
+			firstPackageErr,
+			packageErrCount-1,
+		)
+	}
+	return out, nil
+}
+
+func newFileDomainScan(file typedGoFile) *fileDomainScan {
+	return &fileDomainScan{
+		File:    file.File,
+		Fset:    file.Fset,
+		Info:    file.Info,
+		seen:    map[evidenceKey]bool{},
+		parents: astParentMap(file.File),
+	}
+}
+
+func (s *fileDomainScan) collectSemanticEvidence() {
+	ast.Inspect(s.File, func(node ast.Node) bool {
+		switch n := node.(type) {
+		case *ast.AssignStmt:
+			if len(n.Lhs) != len(n.Rhs) {
+				return true
+			}
+			for i, lhs := range n.Lhs {
+				if s.Info == nil &&
+					potentialHostnameSelectorTarget(lhs) &&
+					s.hasStaticBareHostnameValue(n.Rhs[i]) {
+					s.requireTypeInfo(n.Rhs[i])
+				}
+				if index, ok := stripParens(lhs).(*ast.IndexExpr); ok {
+					switch {
+					case s.isHostnameTarget(index.X):
+						s.addMapPair(index.Index, n.Rhs[i])
+					case s.isHostnameMapKey(index.Index):
+						s.addHostValue(n.Rhs[i], "host assignment")
+					}
+					continue
+				}
+				if s.isHostnameTarget(lhs) {
+					s.addHostValue(n.Rhs[i], "host assignment")
+				}
+			}
+		case *ast.ValueSpec:
+			if len(n.Names) != len(n.Values) {
+				return true
+			}
+			for i, name := range n.Names {
+				if isHostnameSemanticName(name.Name) {
+					s.addHostValue(n.Values[i], "host assignment")
+				}
+			}
+		case *ast.KeyValueExpr:
+			if s.Info == nil && s.keyValueNeedsTypeInfo(n) {
+				s.requireTypeInfo(n.Value)
+			}
+			if s.isHostnameKeyValue(n) {
+				s.addHostValue(n.Value, "host assignment")
+			}
+		}
+		return true
+	})
+}
+
+func (s *fileDomainScan) requireTypeInfo(expr ast.Expr) {
+	for _, existing := range s.TypeInfoRequired {
+		if existing.Pos() == expr.Pos() && existing.End() == expr.End() {
+			return
+		}
+	}
+	s.TypeInfoRequired = append(s.TypeInfoRequired, expr)
+}
+
+func (s *fileDomainScan) hasStaticBareHostnameValue(expr ast.Expr) bool {
+	value, ok := staticStringValue(expr, s.Info, nil)
+	if !ok {
+		return false
+	}
+	host, ok := semanticHostname(value)
+	return ok && !isReservedExampleHostname(host)
+}
+
+func (s *fileDomainScan) keyValueNeedsTypeInfo(pair *ast.KeyValueExpr) bool {
+	composite, ok := s.parents[pair].(*ast.CompositeLit)
+	if !ok {
+		return false
+	}
+	if _, explicitMap := composite.Type.(*ast.MapType); explicitMap {
+		return false
+	}
+	key, ok := pair.Key.(*ast.Ident)
+	return ok && isHostnameSemanticName(key.Name) && s.hasStaticBareHostnameValue(pair.Value)
+}
+
+func potentialHostnameSelectorTarget(expr ast.Expr) bool {
+	switch n := stripParens(expr).(type) {
+	case *ast.SelectorExpr:
+		return isHostnameSemanticName(n.Sel.Name)
+	case *ast.StarExpr:
+		return potentialHostnameSelectorTarget(n.X)
+	case *ast.IndexExpr:
+		return potentialHostnameSelectorTarget(n.X)
+	default:
+		return false
+	}
+}
+
+func (s *fileDomainScan) collectAbsoluteURLEvidence() {
+	ast.Inspect(s.File, func(node ast.Node) bool {
+		expr, ok := node.(ast.Expr)
+		if !ok {
+			return true
+		}
+		if ident, ok := expr.(*ast.Ident); ok && s.Info != nil && s.Info.Defs[ident] != nil {
+			// A declaration name may carry the constant value in types.Info,
+			// but it is not a second source expression.
+			return true
+		}
+		value, ok := staticStringValue(expr, s.Info, nil)
+		if !ok {
+			return true
+		}
+		if s.hasStaticStringContainer(expr) {
+			return true
+		}
+		host, ok := absoluteURLHostname(value)
+		if ok {
+			s.addEvidence(host, "absolute URL", expr)
+		}
+		return true
+	})
+}
+
+func (s *fileDomainScan) hasStaticStringContainer(expr ast.Expr) bool {
+	parent, ok := s.parents[expr].(ast.Expr)
+	if !ok {
+		return false
+	}
+	switch parent.(type) {
+	case *ast.BinaryExpr, *ast.ParenExpr:
+		_, ok := staticStringValue(parent, s.Info, nil)
+		return ok
+	default:
+		return false
+	}
+}
+
+func (s *fileDomainScan) addHostValue(expr ast.Expr, kind string) {
+	expr = stripParens(expr)
+	if composite, ok := expr.(*ast.CompositeLit); ok {
+		switch s.collectionCompositeKind(composite) {
+		case sequenceComposite:
+			for _, element := range composite.Elts {
+				if valueExpr, ok := element.(ast.Expr); ok {
+					s.addHostValue(valueExpr, "host collection")
+				}
+			}
+		case mapComposite:
+			for _, element := range composite.Elts {
+				pair, ok := element.(*ast.KeyValueExpr)
+				if !ok {
+					continue
+				}
+				keyExpr, ok := pair.Key.(ast.Expr)
+				if !ok {
+					continue
+				}
+				s.addMapPair(keyExpr, pair.Value)
+			}
+		default:
+			if s.Info == nil {
+				s.requireTypeInfoForUnclassifiedCollection(composite)
+			}
+			return
+		}
+		return
+	}
+	if evidence, ok := s.hostnameEvidence(expr, kind); ok {
+		s.addEvidence(evidence.Host, evidence.Kind, evidence.Expr)
+	}
+}
+
+func (s *fileDomainScan) requireTypeInfoForUnclassifiedCollection(composite *ast.CompositeLit) {
+	for _, element := range composite.Elts {
+		if pair, ok := element.(*ast.KeyValueExpr); ok {
+			keyExpr, ok := pair.Key.(ast.Expr)
+			if !ok {
+				continue
+			}
+			keyIsHost := s.hasStaticBareHostnameValue(keyExpr)
+			valueIsHost := s.hasStaticBareHostnameValue(pair.Value)
+			if keyIsHost == valueIsHost {
+				continue
+			}
+			if keyIsHost {
+				s.requireTypeInfo(keyExpr)
+			} else {
+				s.requireTypeInfo(pair.Value)
+			}
+			continue
+		}
+		valueExpr, ok := element.(ast.Expr)
+		if ok && s.hasStaticBareHostnameValue(valueExpr) {
+			s.requireTypeInfo(valueExpr)
+		}
+	}
+}
+
+// addMapPair reports a map side only when it is the sole hostname-shaped
+// static value. A semantic map name does not establish whether a string map
+// is hostname->metadata or alias->hostname, so reporting both sides would turn
+// filenames such as client.pem into blocking hostname evidence.
+func (s *fileDomainScan) addMapPair(key, value ast.Expr) {
+	keyEvidence, keyOK := s.hostnameEvidence(key, "host collection")
+	valueEvidence, valueOK := s.hostnameEvidence(value, "host collection")
+	if keyOK == valueOK {
+		return
+	}
+	if keyOK {
+		s.addEvidence(keyEvidence.Host, keyEvidence.Kind, keyEvidence.Expr)
+		return
+	}
+	s.addEvidence(valueEvidence.Host, valueEvidence.Kind, valueEvidence.Expr)
+}
+
+func (s *fileDomainScan) hostnameEvidence(expr ast.Expr, kind string) (domainEvidence, bool) {
+	expr = stripParens(expr)
+	value, ok := staticStringValue(expr, s.Info, nil)
+	if !ok {
+		return domainEvidence{}, false
+	}
+	if host, ok := absoluteURLHostname(value); ok {
+		return domainEvidence{Host: host, Kind: "absolute URL", Expr: expr}, true
+	}
+	if host, ok := semanticHostname(value); ok {
+		return domainEvidence{Host: host, Kind: kind, Expr: expr}, true
+	}
+	return domainEvidence{}, false
+}
+
+func (s *fileDomainScan) collectionCompositeKind(expr *ast.CompositeLit) collectionCompositeKind {
+	if s.Info != nil {
+		if tv, ok := s.Info.Types[expr]; ok && tv.Type != nil {
+			switch tv.Type.Underlying().(type) {
+			case *types.Array, *types.Slice:
+				return sequenceComposite
+			case *types.Map:
+				return mapComposite
+			}
+		}
+	}
+	switch expr.Type.(type) {
+	case *ast.ArrayType:
+		return sequenceComposite
+	case *ast.MapType:
+		return mapComposite
+	default:
+		return notCollectionComposite
+	}
+}
+
+func (s *fileDomainScan) addEvidence(host, kind string, expr ast.Expr) {
+	key := evidenceKey{Host: host, Start: expr.Pos(), End: expr.End()}
+	if s.seen[key] {
+		return
+	}
+	s.seen[key] = true
+	s.Evidence = append(s.Evidence, domainEvidence{Host: host, Kind: kind, Expr: expr})
+}
+
+func staticStringValue(expr ast.Expr, info *types.Info, seen map[*ast.Object]bool) (string, bool) {
+	if info != nil {
+		if tv, ok := info.Types[expr]; ok && tv.Value != nil && tv.Value.Kind() == constant.String {
+			return constant.StringVal(tv.Value), true
+		}
+	}
+	switch n := expr.(type) {
+	case *ast.BasicLit:
+		if n.Kind != token.STRING {
+			return "", false
+		}
+		value, err := strconv.Unquote(n.Value)
+		return value, err == nil
+	case *ast.ParenExpr:
+		return staticStringValue(n.X, info, seen)
+	case *ast.BinaryExpr:
+		if n.Op != token.ADD {
+			return "", false
+		}
+		left, ok := staticStringValue(n.X, info, seen)
+		if !ok {
+			return "", false
+		}
+		right, ok := staticStringValue(n.Y, info, seen)
+		if !ok {
+			return "", false
+		}
+		return left + right, true
+	case *ast.Ident:
+		if info != nil {
+			if obj := info.ObjectOf(n); obj != nil {
+				if c, ok := obj.(*types.Const); ok {
+					if c.Val().Kind() == constant.String {
+						return constant.StringVal(c.Val()), true
+					}
+				}
+			}
+		}
+		if n.Obj == nil || n.Obj.Kind != ast.Con {
+			return "", false
+		}
+		if seen == nil {
+			seen = map[*ast.Object]bool{}
+		}
+		if seen[n.Obj] {
+			return "", false
+		}
+		seen[n.Obj] = true
+		defer delete(seen, n.Obj)
+		spec, ok := n.Obj.Decl.(*ast.ValueSpec)
+		if !ok {
+			return "", false
+		}
+		for i, name := range spec.Names {
+			if name.Name == n.Name && i < len(spec.Values) {
+				return staticStringValue(spec.Values[i], info, seen)
+			}
+		}
+	}
+	return "", false
+}
+
+func absoluteURLHostname(value string) (string, bool) {
+	value = strings.TrimSpace(value)
+	parsed, err := url.Parse(value)
+	if err != nil || parsed.Host == "" {
+		return "", false
+	}
+	switch strings.ToLower(parsed.Scheme) {
+	case "http", "https", "ws", "wss":
+	default:
+		return "", false
+	}
+	return normalizeCandidateHostname(parsed.Hostname())
+}
+
+func semanticHostname(value string) (string, bool) {
+	value = strings.TrimSpace(value)
+	if value == "" || strings.ContainsAny(value, `/\?#@`) || strings.ContainsAny(value, " \t\r\n") {
+		return "", false
+	}
+	parsed, err := url.Parse("//" + value)
+	if err != nil || parsed.Host == "" || parsed.Path != "" {
+		return "", false
+	}
+	return normalizeCandidateHostname(parsed.Hostname())
+}
+
+func normalizeCandidateHostname(host string) (string, bool) {
+	host = strings.TrimSuffix(strings.ToLower(strings.TrimSpace(host)), ".")
+	if host == "" || !strings.Contains(host, ".") || net.ParseIP(host) != nil {
+		return "", false
+	}
+	labels := strings.Split(host, ".")
+	for _, label := range labels {
+		if label == "" || strings.HasPrefix(label, "-") || strings.HasSuffix(label, "-") {
+			return "", false
+		}
+		for _, r := range label {
+			if unicode.IsLetter(r) || unicode.IsDigit(r) || r == '-' {
+				continue
+			}
+			return "", false
+		}
+	}
+	return host, true
+}
+
+func (s *fileDomainScan) isHostnameTarget(expr ast.Expr) bool {
+	switch n := stripParens(expr).(type) {
+	case *ast.Ident:
+		return isHostnameSemanticName(n.Name)
+	case *ast.SelectorExpr:
+		return s.isHostnameSelector(n)
+	case *ast.StarExpr:
+		return s.isHostnameTarget(n.X)
+	default:
+		return false
+	}
+}
+
+func (s *fileDomainScan) isHostnameKeyValue(pair *ast.KeyValueExpr) bool {
+	composite, ok := s.parents[pair].(*ast.CompositeLit)
+	if !ok {
+		return false
+	}
+	switch s.collectionCompositeKind(composite) {
+	case mapComposite:
+		key, ok := pair.Key.(ast.Expr)
+		return ok && s.isHostnameMapKey(key)
+	case notCollectionComposite:
+		ident, ok := pair.Key.(*ast.Ident)
+		return ok && s.isHostnameStructField(composite, ident.Name)
+	default:
+		return false
+	}
+}
+
+func (s *fileDomainScan) isHostnameMapKey(expr ast.Expr) bool {
+	value, ok := staticStringValue(expr, s.Info, nil)
+	return ok && isHostnameSemanticName(value)
+}
+
+func (s *fileDomainScan) isHostnameSelector(selector *ast.SelectorExpr) bool {
+	if s.Info == nil || !isHostnameSemanticName(selector.Sel.Name) {
+		return false
+	}
+	selection := s.Info.Selections[selector]
+	if selection == nil || selection.Kind() != types.FieldVal {
+		return false
+	}
+	return !nonNetworkHostnameFields[hostnameFieldID{
+		Type:  namedTypeID(selection.Recv()),
+		Field: selector.Sel.Name,
+	}]
+}
+
+func (s *fileDomainScan) isHostnameStructField(composite *ast.CompositeLit, field string) bool {
+	if s.Info == nil || !isHostnameSemanticName(field) {
+		return false
+	}
+	typeID := namedTypeID(s.Info.TypeOf(composite))
+	if typeID == "" {
+		return false
+	}
+	return !nonNetworkHostnameFields[hostnameFieldID{Type: typeID, Field: field}]
+}
+
+func namedTypeID(typ types.Type) string {
+	for {
+		switch t := typ.(type) {
+		case *types.Pointer:
+			typ = t.Elem()
+		case *types.Named:
+			obj := t.Obj()
+			if obj == nil || obj.Pkg() == nil {
+				return ""
+			}
+			return obj.Pkg().Path() + "." + obj.Name()
+		default:
+			return ""
+		}
+	}
+}
+
+func isHostnameSemanticName(name string) bool {
+	lower := strings.ToLower(name)
+	switch lower {
+	case "host", "hosts", "hostname", "hostnames", "domain", "domains":
+		return true
+	}
+	for _, marker := range []string{
+		"HostBy", "HostsBy", "HostnameBy", "HostnamesBy", "DomainBy", "DomainsBy",
+	} {
+		if i := strings.Index(name, marker); i >= 0 {
+			end := i + len(marker)
+			if end < len(name) && unicode.IsUpper(rune(name[end])) {
+				return true
+			}
+		}
+	}
+	for _, prefix := range []string{
+		"hostBy", "hostsBy", "hostnameBy", "hostnamesBy", "domainBy", "domainsBy",
+	} {
+		if strings.HasPrefix(name, prefix) &&
+			len(name) > len(prefix) &&
+			unicode.IsUpper(rune(name[len(prefix)])) {
+			return true
+		}
+	}
+	if i := strings.LastIndexAny(name, "_-"); i >= 0 {
+		return isHostnameSemanticName(name[i+1:])
+	}
+	for _, suffix := range []string{"Hostnames", "Hostname", "Domains", "Domain", "Hosts", "Host"} {
+		if strings.HasSuffix(name, suffix) && len(name) > len(suffix) {
+			return true
+		}
+	}
+	return false
+}
+
+func stripParens(expr ast.Expr) ast.Expr {
+	for {
+		paren, ok := expr.(*ast.ParenExpr)
+		if !ok {
+			return expr
+		}
+		expr = paren.X
+	}
+}
+
+func astParentMap(root ast.Node) map[ast.Node]ast.Node {
+	parents := map[ast.Node]ast.Node{}
+	var stack []ast.Node
+	ast.Inspect(root, func(node ast.Node) bool {
+		if node == nil {
+			stack = stack[:len(stack)-1]
+			return false
+		}
+		if len(stack) > 0 {
+			parents[node] = stack[len(stack)-1]
+		}
+		stack = append(stack, node)
+		return true
+	})
+	return parents
+}
+
+func isDomainFixturePath(rel string) bool {
+	rel = filepath.ToSlash(rel)
+	if strings.HasPrefix(rel, "skills/") {
+		return false
+	}
+	if strings.HasSuffix(rel, "_test.go") || strings.HasPrefix(rel, "tests/") {
+		return true
+	}
+	for _, part := range strings.Split(rel, "/") {
+		if part == "testdata" {
+			return true
+		}
+	}
+	return false
+}
+
+func unusedDomainViolation(entry domainPolicyEntry) lintapi.Violation {
+	return lintapi.Violation{
+		Rule:       unusedDomainRule,
+		Action:     lintapi.ActionReject,
+		File:       entry.File,
+		Line:       entry.Line,
+		Message:    fmt.Sprintf("domain allowlist entry %q has no in-scope Go reference", entry.Host),
+		Suggestion: "remove the unused entry; allowlist entries must be justified by a current in-scope reference",
+	}
+}
+
+func incompleteDomainViolation(file string, err error) lintapi.Violation {
+	return incompleteDomainViolationAt(file, 1, err)
+}
+
+func incompleteDomainViolationAt(file string, line int, err error) lintapi.Violation {
+	return lintapi.Violation{
+		Rule:       incompleteDomainRule,
+		Action:     lintapi.ActionReject,
+		File:       file,
+		Line:       line,
+		Message:    "domain scan incomplete: " + err.Error(),
+		Suggestion: "fix the Go parse or type-loading error so hostname analysis can complete",
+	}
+}

lint/domaincontract/unapproved_repo_test.go

@@ -0,0 +1,462 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package domaincontract
+
+import (
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/lint/lintapi"
+)
+
+func gitTestCommand(t *testing.T, root string, args ...string) string {
+	t.Helper()
+	cmd := exec.Command("git", args...)
+	cmd.Dir = root
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		t.Fatalf("git %s: %v\n%s", strings.Join(args, " "), err, out)
+	}
+	return strings.TrimSpace(string(out))
+}
+
+func setupDomainDiffRepo(t *testing.T, target string) (root, base string) {
+	t.Helper()
+	root = t.TempDir()
+	writeFile(t, root, "go.mod", "module example.com/domainfixture\n\ngo 1.23.0\n")
+	writeFile(t, root, publicDomainsPath, "# public\npublic.example.com\n")
+	writeFile(t, root, fixtureDomainsPath, "# fixtures\nfixture.example.com\n")
+	writeFile(t, root, "policy_refs.go", "package sample\n\nvar APIHost = \"public.example.com\"\n")
+	writeFile(t, root, "policy_refs_test.go", "package sample\n\nvar FixtureHost = \"fixture.example.com\"\n")
+	writeFile(t, root, "target.go", target)
+
+	gitTestCommand(t, root, "init", "-q")
+	gitTestCommand(t, root, "config", "user.name", "Domain Contract Test")
+	gitTestCommand(t, root, "config", "user.email", "domain-contract@example.com")
+	gitTestCommand(t, root, "add", ".")
+	gitTestCommand(t, root, "-c", "commit.gpgsign=false", "commit", "-qm", "base")
+	return root, gitTestCommand(t, root, "rev-parse", "HEAD")
+}
+
+func commitDomainDiff(t *testing.T, root, message string) {
+	t.Helper()
+	gitTestCommand(t, root, "add", "-A")
+	gitTestCommand(t, root, "-c", "commit.gpgsign=false", "commit", "-qm", message)
+}
+
+func violationsForRule(vs []lintapi.Violation, rule string) []lintapi.Violation {
+	var out []lintapi.Violation
+	for _, v := range vs {
+		if v.Rule == rule {
+			out = append(out, v)
+		}
+	}
+	return out
+}
+
+func scanDomainDiff(t *testing.T, root, base string) []lintapi.Violation {
+	t.Helper()
+	vs, err := ScanRepoWithOptions(root, ScanOptions{ChangedFrom: base})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return vs
+}
+
+func TestUnapprovedDomainDiffContract(t *testing.T) {
+	t.Run("new PR 1975 case", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t, "package sample\n\nvar unrelated = 1\n")
+		writeFile(t, root, "target.go",
+			"package sample\n\nvar unrelated = 1\nvar APIHost = \"internal-api-drive-stream.larkoffice.com\"\n")
+		commitDomainDiff(t, root, "add internal host")
+
+		got := violationsForRule(scanDomainDiff(t, root, base), unapprovedDomainRule)
+		if len(got) != 1 || !strings.Contains(got[0].Message, "internal-api-drive-stream.larkoffice.com") {
+			t.Fatalf("violations = %+v, want PR 1975 hostname", got)
+		}
+	})
+
+	t.Run("hostname field in nested Go module", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t, "package sample\n\nvar unrelated = 1\n")
+		writeFile(t, root, "nested/go.mod", "module example.com/nested\n\ngo 1.23.0\n")
+		writeFile(t, root, "nested/target.go",
+			"package nested\n\ntype Config struct{ Host string }\n\n"+
+				"var config = Config{Host: \"private.corp.internal\"}\n")
+		commitDomainDiff(t, root, "add nested module hostname")
+
+		all := scanDomainDiff(t, root, base)
+		got := violationsForRule(all, unapprovedDomainRule)
+		if len(got) != 1 || filepath.ToSlash(got[0].File) != "nested/target.go" ||
+			!strings.Contains(got[0].Message, "private.corp.internal") {
+			t.Fatalf("violations = %+v, want nested-module hostname rejection", got)
+		}
+		if incomplete := violationsForRule(all, incompleteDomainRule); len(incomplete) != 0 {
+			t.Fatalf("nested module must have complete type information: %+v", incomplete)
+		}
+	})
+
+	t.Run("changed excluded field reports incomplete scan", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t, "package sample\n\nvar unrelated = 1\n")
+		writeFile(t, root, "excluded.go",
+			"//go:build domaincontract_never && !domaincontract_never\n\npackage sample\n\n"+
+				"type Config struct{ Host string }\n\n"+
+				"var config = Config{Host: \"private.corp.internal\"}\n")
+		commitDomainDiff(t, root, "add excluded hostname field")
+
+		all := scanDomainDiff(t, root, base)
+		got := violationsForRule(all, incompleteDomainRule)
+		if len(got) != 1 || filepath.Base(got[0].File) != "excluded.go" || got[0].Line != 7 {
+			t.Fatalf("violations = %+v, want changed field scan-incomplete at line 7", got)
+		}
+		if unapproved := violationsForRule(all, unapprovedDomainRule); len(unapproved) != 0 {
+			t.Fatalf("untyped field must not produce an unverified hostname finding: %+v", unapproved)
+		}
+	})
+
+	t.Run("changed excluded selector reports incomplete scan", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t, "package sample\n\nvar unrelated = 1\n")
+		writeFile(t, root, "excluded.go",
+			"//go:build domaincontract_never && !domaincontract_never\n\npackage sample\n\n"+
+				"type Config struct{ Host string }\n\n"+
+				"func configure(config *Config) { config.Host = \"private.corp.internal\" }\n")
+		commitDomainDiff(t, root, "add excluded hostname selector")
+
+		got := violationsForRule(scanDomainDiff(t, root, base), incompleteDomainRule)
+		if len(got) != 1 || filepath.Base(got[0].File) != "excluded.go" || got[0].Line != 7 {
+			t.Fatalf("violations = %+v, want changed selector scan-incomplete at line 7", got)
+		}
+	})
+
+	t.Run("changed excluded named slice reports incomplete scan", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t, "package sample\n\nvar unrelated = 1\n")
+		writeFile(t, root, "excluded.go",
+			"//go:build domaincontract_never && !domaincontract_never\n\npackage sample\n\n"+
+				"type HostList []string\n\n"+
+				"var AllowedHosts = HostList{\n\t\"attacker.zip\",\n}\n")
+		commitDomainDiff(t, root, "add excluded hostname slice")
+
+		all := scanDomainDiff(t, root, base)
+		got := violationsForRule(all, incompleteDomainRule)
+		if len(got) != 1 || filepath.Base(got[0].File) != "excluded.go" || got[0].Line != 8 {
+			t.Fatalf("violations = %+v, want named-slice scan-incomplete at line 8", got)
+		}
+		if unapproved := violationsForRule(all, unapprovedDomainRule); len(unapproved) != 0 {
+			t.Fatalf("untyped named slice must not produce an unverified hostname finding: %+v", unapproved)
+		}
+	})
+
+	t.Run("changed excluded named map reports incomplete scan", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t, "package sample\n\nvar unrelated = 1\n")
+		writeFile(t, root, "excluded.go",
+			"//go:build domaincontract_never && !domaincontract_never\n\npackage sample\n\n"+
+				"type HostSet map[string]struct{}\n\n"+
+				"var AllowedHosts = HostSet{\n\t\"attacker.zip\": {},\n}\n")
+		commitDomainDiff(t, root, "add excluded hostname map")
+
+		all := scanDomainDiff(t, root, base)
+		got := violationsForRule(all, incompleteDomainRule)
+		if len(got) != 1 || filepath.Base(got[0].File) != "excluded.go" || got[0].Line != 8 {
+			t.Fatalf("violations = %+v, want named-map scan-incomplete at line 8", got)
+		}
+		if unapproved := violationsForRule(all, unapprovedDomainRule); len(unapproved) != 0 {
+			t.Fatalf("untyped named map must not produce an unverified hostname finding: %+v", unapproved)
+		}
+	})
+
+	t.Run("changed excluded unrelated code stays allowed", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t, "package sample\n\nvar unrelated = 1\n")
+		writeFile(t, root, "excluded.go",
+			"//go:build domaincontract_never && !domaincontract_never\n\npackage sample\n\nvar unrelated = 2\n")
+		commitDomainDiff(t, root, "add excluded unrelated code")
+
+		if got := violationsForRule(scanDomainDiff(t, root, base), incompleteDomainRule); len(got) != 0 {
+			t.Fatalf("unrelated excluded code must not require hostname type information: %+v", got)
+		}
+	})
+
+	t.Run("new element in existing collection", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t,
+			"package sample\n\nvar ExtraHosts = []string{\n\t\"public.example.com\",\n}\n")
+		writeFile(t, root, "target.go",
+			"package sample\n\nvar ExtraHosts = []string{\n\t\"public.example.com\",\n\t\"attacker.zip\",\n}\n")
+		commitDomainDiff(t, root, "add collection host")
+
+		got := violationsForRule(scanDomainDiff(t, root, base), unapprovedDomainRule)
+		if len(got) != 1 || !strings.Contains(got[0].Message, "attacker.zip") {
+			t.Fatalf("violations = %+v, want attacker.zip", got)
+		}
+		if got[0].Line != 5 {
+			t.Fatalf("violation line = %d, want 5", got[0].Line)
+		}
+	})
+
+	t.Run("multiline expression changed segment", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t,
+			"package sample\n\nvar ExtraHost = \"private.corp.\" +\n\t\"example.com\"\n")
+		writeFile(t, root, "target.go",
+			"package sample\n\nvar ExtraHost = \"private.corp.\" +\n\t\"internal\"\n")
+		commitDomainDiff(t, root, "change concatenated host")
+
+		got := violationsForRule(scanDomainDiff(t, root, base), unapprovedDomainRule)
+		if len(got) != 1 || !strings.Contains(got[0].Message, "private.corp.internal") {
+			t.Fatalf("violations = %+v, want private.corp.internal", got)
+		}
+		if got[0].Line != 4 {
+			t.Fatalf("violation line = %d, want changed line 4", got[0].Line)
+		}
+	})
+
+	t.Run("unrelated change beside historical hostname", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t,
+			"package sample\n\nvar HistoricalHost = \"historical.private.internal\"\n")
+		writeFile(t, root, "target.go",
+			"package sample\n\nvar HistoricalHost = \"historical.private.internal\"\nvar unrelated = 1\n")
+		commitDomainDiff(t, root, "add unrelated value")
+
+		if got := violationsForRule(scanDomainDiff(t, root, base), unapprovedDomainRule); len(got) != 0 {
+			t.Fatalf("unexpected historical-domain violation: %+v", got)
+		}
+	})
+
+	t.Run("historical hostname expression changed", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t,
+			"package sample\n\nvar HistoricalHost = \"historical.private.internal\"\n")
+		writeFile(t, root, "target.go",
+			"package sample\n\nvar HistoricalHost = \"replacement.private.internal\"\n")
+		commitDomainDiff(t, root, "change historical host")
+
+		got := violationsForRule(scanDomainDiff(t, root, base), unapprovedDomainRule)
+		if len(got) != 1 || !strings.Contains(got[0].Message, "replacement.private.internal") {
+			t.Fatalf("violations = %+v, want replacement.private.internal", got)
+		}
+	})
+
+	t.Run("new assignment references existing constant", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t,
+			"package sample\n\nconst existingConst = \"private.corp.internal\"\n")
+		writeFile(t, root, "target.go",
+			"package sample\n\nconst existingConst = \"private.corp.internal\"\nvar APIHost = existingConst\n")
+		commitDomainDiff(t, root, "use existing hostname constant")
+
+		got := violationsForRule(scanDomainDiff(t, root, base), unapprovedDomainRule)
+		if len(got) != 1 || !strings.Contains(got[0].Message, "private.corp.internal") {
+			t.Fatalf("violations = %+v, want private.corp.internal", got)
+		}
+		if got[0].Line != 4 {
+			t.Fatalf("violation line = %d, want 4", got[0].Line)
+		}
+	})
+
+	t.Run("allowlisted hostname", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t, "package sample\n\nvar unrelated = 1\n")
+		writeFile(t, root, "target.go",
+			"package sample\n\nvar unrelated = 1\nvar BackupHost = \"public.example.com\"\n")
+		commitDomainDiff(t, root, "add public host")
+
+		if got := violationsForRule(scanDomainDiff(t, root, base), unapprovedDomainRule); len(got) != 0 {
+			t.Fatalf("unexpected public-domain violation: %+v", got)
+		}
+	})
+
+	t.Run("reserved example URL", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t, "package sample\n\nvar unrelated = 1\n")
+		writeFile(t, root, "target.go",
+			"package sample\n\nvar unrelated = 1\nfunc fakeValue() string { return \"https://example.test/resource\" }\n")
+		commitDomainDiff(t, root, "add safe example URL")
+
+		if got := violationsForRule(scanDomainDiff(t, root, base), unapprovedDomainRule); len(got) != 0 {
+			t.Fatalf("unexpected reserved-example violation: %+v", got)
+		}
+	})
+
+	t.Run("historical type gap suppresses unused policy diagnostics", func(t *testing.T) {
+		root, _ := setupDomainDiffRepo(t, "package sample\n\nvar unrelated = 1\n")
+		writeFile(t, root, publicDomainsPath,
+			"# public\nplatform.example.com\npublic.example.com\n")
+		writeFile(t, root, "excluded.go",
+			"//go:build domaincontract_never && !domaincontract_never\n\npackage sample\n\n"+
+				"type Config struct{ Host string }\n\n"+
+				"var config = Config{Host: \"platform.example.com\"}\n")
+		commitDomainDiff(t, root, "add historical platform hostname")
+		base := gitTestCommand(t, root, "rev-parse", "HEAD")
+
+		writeFile(t, root, "target.go", "package sample\n\nvar unrelated = 2\n")
+		commitDomainDiff(t, root, "change unrelated code")
+
+		all := scanDomainDiff(t, root, base)
+		if got := violationsForRule(all, incompleteDomainRule); len(got) != 0 {
+			t.Fatalf("historical type gap must not be attributed to this change: %+v", got)
+		}
+		if got := violationsForRule(all, unusedDomainRule); len(got) != 0 {
+			t.Fatalf("incomplete inventory must not produce unused-policy diagnostics: %+v", got)
+		}
+	})
+
+	t.Run("allowlist does not approve subdomains", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t, "package sample\n\nvar unrelated = 1\n")
+		writeFile(t, root, "target.go",
+			"package sample\n\nvar unrelated = 1\nvar BackupHost = \"evil.public.example.com\"\n")
+		commitDomainDiff(t, root, "add unapproved public subdomain")
+
+		got := violationsForRule(scanDomainDiff(t, root, base), unapprovedDomainRule)
+		if len(got) != 1 || !strings.Contains(got[0].Message, "evil.public.example.com") {
+			t.Fatalf("violations = %+v, want evil.public.example.com", got)
+		}
+	})
+
+	t.Run("multi assignment pairs names and values", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t, "package sample\n\nvar unrelated = 1\n")
+		writeFile(t, root, publicDomainsPath,
+			"# public\nopen.larksuite.com\npublic.example.com\n")
+		writeFile(t, root, "target.go",
+			"package sample\n\nvar unrelated = 1\nvar APIHost, BackupHost = \"open.larksuite.com\", \"attacker.zip\"\n")
+		commitDomainDiff(t, root, "add multiple hosts")
+
+		got := violationsForRule(scanDomainDiff(t, root, base), unapprovedDomainRule)
+		if len(got) != 1 || !strings.Contains(got[0].Message, "attacker.zip") {
+			t.Fatalf("violations = %+v, want only attacker.zip", got)
+		}
+	})
+
+	t.Run("IDN hostname is rejected", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t, "package sample\n\nvar unrelated = 1\n")
+		writeFile(t, root, "target.go",
+			"package sample\n\nvar unrelated = 1\nvar BackupHost = \"例子.公司.cn\"\n")
+		commitDomainDiff(t, root, "add IDN hostname")
+
+		got := violationsForRule(scanDomainDiff(t, root, base), unapprovedDomainRule)
+		if len(got) != 1 || !strings.Contains(got[0].Message, "例子.公司.cn") {
+			t.Fatalf("violations = %+v, want IDN hostname", got)
+		}
+	})
+
+	t.Run("fixture limited to test files", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t, "package sample\n\nvar unrelated = 1\n")
+		writeFile(t, root, "target.go",
+			"package sample\n\nvar unrelated = 1\nvar ProductionHost = \"fixture.example.com\"\n")
+		commitDomainDiff(t, root, "use fixture in production")
+
+		got := violationsForRule(scanDomainDiff(t, root, base), unapprovedDomainRule)
+		if len(got) != 1 || !strings.Contains(got[0].Message, "fixture.example.com") {
+			t.Fatalf("violations = %+v, want production fixture rejection", got)
+		}
+		if !strings.Contains(got[0].Suggestion, "fixture-only hostname") ||
+			strings.Contains(got[0].Suggestion, "public allowlist") {
+			t.Fatalf("suggestion = %q, want fixture-scope guidance", got[0].Suggestion)
+		}
+	})
+
+	t.Run("fixture accepted in test file", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t, "package sample\n\nvar unrelated = 1\n")
+		writeFile(t, root, "new_target_test.go",
+			"package sample\n\nvar BackupHost = \"fixture.example.com\"\n")
+		commitDomainDiff(t, root, "use fixture in test")
+
+		if got := violationsForRule(scanDomainDiff(t, root, base), unapprovedDomainRule); len(got) != 0 {
+			t.Fatalf("unexpected fixture-domain violation: %+v", got)
+		}
+	})
+
+	t.Run("fixture allowlist does not approve subdomains", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t, "package sample\n\nvar unrelated = 1\n")
+		writeFile(t, root, "new_target_test.go",
+			"package sample\n\nvar BackupHost = \"evil.fixture.example.com\"\n")
+		commitDomainDiff(t, root, "use unapproved fixture subdomain")
+
+		got := violationsForRule(scanDomainDiff(t, root, base), unapprovedDomainRule)
+		if len(got) != 1 || !strings.Contains(got[0].Message, "evil.fixture.example.com") {
+			t.Fatalf("violations = %+v, want exact fixture match", got)
+		}
+	})
+
+	t.Run("fixture rejected in skills", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t, "package sample\n\nvar unrelated = 1\n")
+		writeFile(t, root, "skills/example/example_test.go",
+			"package example\n\nvar BackupHost = \"fixture.example.com\"\n")
+		commitDomainDiff(t, root, "use fixture in skill")
+
+		got := violationsForRule(scanDomainDiff(t, root, base), unapprovedDomainRule)
+		if len(got) != 1 || !strings.Contains(got[0].Message, "fixture.example.com") {
+			t.Fatalf("violations = %+v, want skill fixture rejection", got)
+		}
+	})
+
+	t.Run("pure rename", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t,
+			"package sample\n\nvar HistoricalHost = \"historical.private.internal\"\n")
+		gitTestCommand(t, root, "mv", "target.go", "renamed.go")
+		commitDomainDiff(t, root, "rename file")
+
+		if got := violationsForRule(scanDomainDiff(t, root, base), unapprovedDomainRule); len(got) != 0 {
+			t.Fatalf("unexpected rename violation: %+v", got)
+		}
+	})
+}
+
+func TestUnapprovedDomainPolicyAndFailurePaths(t *testing.T) {
+	t.Run("unused policy entry", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t, "package sample\n\nvar unrelated = 1\n")
+		writeFile(t, root, publicDomainsPath,
+			"# public\npublic.example.com\nunused.example.com\n")
+		commitDomainDiff(t, root, "add unused policy")
+
+		got := violationsForRule(scanDomainDiff(t, root, base), unusedDomainRule)
+		if len(got) != 1 || !strings.Contains(got[0].Message, "unused.example.com") {
+			t.Fatalf("violations = %+v, want unused.example.com", got)
+		}
+	})
+
+	t.Run("public entry used only by fixture", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t, "package sample\n\nvar unrelated = 1\n")
+		writeFile(t, root, publicDomainsPath,
+			"# public\npublic.example.com\ntest-only.example.com\n")
+		writeFile(t, root, "public_only_test.go",
+			"package sample\n\nvar BackupHost = \"test-only.example.com\"\n")
+		commitDomainDiff(t, root, "add test-only public policy")
+
+		got := violationsForRule(scanDomainDiff(t, root, base), unusedDomainRule)
+		if len(got) != 1 || !strings.Contains(got[0].Message, "test-only.example.com") {
+			t.Fatalf("violations = %+v, want test-only.example.com", got)
+		}
+	})
+
+	t.Run("changed Go parse failure", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t, "package sample\n\nvar unrelated = 1\n")
+		writeFile(t, root, "target.go", "package sample\n\nfunc broken(\n")
+		commitDomainDiff(t, root, "break source")
+
+		all := scanDomainDiff(t, root, base)
+		got := violationsForRule(all, incompleteDomainRule)
+		if len(got) != 1 || filepath.Base(got[0].File) != "target.go" {
+			t.Fatalf("violations = %+v, want target.go scan-incomplete", got)
+		}
+		if unused := violationsForRule(all, unusedDomainRule); len(unused) != 0 {
+			t.Fatalf("parse failure must not produce unreliable unused-policy diagnostics: %+v", unused)
+		}
+	})
+
+	t.Run("repository type loading failure", func(t *testing.T) {
+		root, base := setupDomainDiffRepo(t, "package sample\n\nvar unrelated = 1\n")
+		writeFile(t, root, "go.mod", "module example.com/domainfixture\n\ngo 1.23.0\n\n"+
+			"require example.com/missing v0.0.0\n\nreplace example.com/missing => ./missing\n")
+		writeFile(t, root, "target.go",
+			"package sample\n\nimport _ \"example.com/missing\"\n\n"+
+				"type Config struct{ Host string }\nvar config = Config{Host: \"malicious.corp.internal\"}\n")
+		commitDomainDiff(t, root, "break type loading")
+
+		all := scanDomainDiff(t, root, base)
+		got := violationsForRule(all, incompleteDomainRule)
+		if len(got) != 1 || filepath.Base(got[0].File) != "go.mod" {
+			t.Fatalf("violations = %+v, want go.mod scan-incomplete", got)
+		}
+		if !strings.Contains(got[0].Message, "load Go type information") {
+			t.Fatalf("message = %q, want type-loading failure", got[0].Message)
+		}
+		if unused := violationsForRule(all, unusedDomainRule); len(unused) != 0 {
+			t.Fatalf("type-loading failure must not produce unreliable unused-policy diagnostics: %+v", unused)
+		}
+	})
+}

lint/domaincontract/unapproved_test.go

@@ -0,0 +1,380 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package domaincontract
+
+import (
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"go/types"
+	"sort"
+	"testing"
+)
+
+func scanDomainEvidence(t *testing.T, source string) []domainEvidence {
+	t.Helper()
+	fset := token.NewFileSet()
+	file, err := parser.ParseFile(fset, "fixture.go", source, 0)
+	if err != nil {
+		t.Fatalf("parse fixture: %v\n%s", err, source)
+	}
+	scan := newFileDomainScan(typedGoFile{File: file, Fset: fset})
+	scan.collectSemanticEvidence()
+	scan.collectAbsoluteURLEvidence()
+	sort.Slice(scan.Evidence, func(i, j int) bool {
+		if scan.Evidence[i].Host != scan.Evidence[j].Host {
+			return scan.Evidence[i].Host < scan.Evidence[j].Host
+		}
+		return scan.Evidence[i].Expr.Pos() < scan.Evidence[j].Expr.Pos()
+	})
+	return scan.Evidence
+}
+
+func scanTypedDomainEvidence(t *testing.T, source string) []domainEvidence {
+	t.Helper()
+	return scanTypedDomainEvidenceInPackage(t, "fixture", source)
+}
+
+func scanTypedDomainEvidenceInPackage(t *testing.T, packagePath, source string) []domainEvidence {
+	t.Helper()
+	fset := token.NewFileSet()
+	file, err := parser.ParseFile(fset, "fixture.go", source, 0)
+	if err != nil {
+		t.Fatalf("parse fixture: %v\n%s", err, source)
+	}
+	info := &types.Info{
+		Types:      map[ast.Expr]types.TypeAndValue{},
+		Defs:       map[*ast.Ident]types.Object{},
+		Uses:       map[*ast.Ident]types.Object{},
+		Selections: map[*ast.SelectorExpr]*types.Selection{},
+	}
+	if _, err := (&types.Config{}).Check(packagePath, fset, []*ast.File{file}, info); err != nil {
+		t.Fatalf("type-check fixture: %v\n%s", err, source)
+	}
+	scan := newFileDomainScan(typedGoFile{File: file, Fset: fset, Info: info})
+	scan.collectSemanticEvidence()
+	scan.collectAbsoluteURLEvidence()
+	sort.Slice(scan.Evidence, func(i, j int) bool {
+		if scan.Evidence[i].Host != scan.Evidence[j].Host {
+			return scan.Evidence[i].Host < scan.Evidence[j].Host
+		}
+		return scan.Evidence[i].Expr.Pos() < scan.Evidence[j].Expr.Pos()
+	})
+	return scan.Evidence
+}
+
+func evidenceHosts(evidence []domainEvidence) []string {
+	hosts := make([]string, 0, len(evidence))
+	for _, item := range evidence {
+		hosts = append(hosts, item.Host)
+	}
+	return hosts
+}
+
+func TestTypedAbsoluteURLDeclarationProducesOneFinding(t *testing.T) {
+	evidence := scanTypedDomainEvidence(t,
+		"package p\nconst DomainContractE2EURL = \"https://private.corp.internal/v1\"\n")
+	if got := evidenceHosts(evidence); len(got) != 1 || got[0] != "private.corp.internal" {
+		t.Fatalf("hosts = %v, want [private.corp.internal]", got)
+	}
+}
+
+func TestGoDomainEvidenceTruePositives(t *testing.T) {
+	tests := []struct {
+		name   string
+		source string
+		want   []string
+	}{
+		{
+			name:   "PR 1975 Feishu assignment",
+			source: "package p\nfunc f() { host := \"internal-api-drive-stream.feishu.cn\"; _ = host }\n",
+			want:   []string{"internal-api-drive-stream.feishu.cn"},
+		},
+		{
+			name:   "PR 1975 Lark assignment",
+			source: "package p\nfunc f() { var host string; host = \"internal-api-drive-stream.larksuite.com\"; _ = host }\n",
+			want:   []string{"internal-api-drive-stream.larksuite.com"},
+		},
+		{
+			name:   "uppercase snake target",
+			source: "package p\nfunc f() { API_HOST := \"private.corp.internal\"; _ = API_HOST }\n",
+			want:   []string{"private.corp.internal"},
+		},
+		{
+			name:   "typed declaration",
+			source: "package p\nconst APIHost string = \"attacker.zip\"\n",
+			want:   []string{"attacker.zip"},
+		},
+		{
+			name:   "grouped const declaration",
+			source: "package p\nconst (\n APIHost string = \"attacker.zip\"\n)\n",
+			want:   []string{"attacker.zip"},
+		},
+		{
+			name:   "grouped var declaration",
+			source: "package p\nvar (\n APIHost string = \"attacker.zip\"\n)\n",
+			want:   []string{"attacker.zip"},
+		},
+		{
+			name: "multi assignment",
+			source: "package p\nfunc f() {\n" +
+				" APIHost, BackupHost := \"public.example.com\", \"attacker.zip\"\n" +
+				" _, _ = APIHost, BackupHost\n}\n",
+			want: []string{"attacker.zip", "public.example.com"},
+		},
+		{
+			name:   "map semantic key",
+			source: "package p\nvar c = map[string]string{\"host\": \"private.corp.internal\"}\n",
+			want:   []string{"private.corp.internal"},
+		},
+		{
+			name:   "map semantic key assignment",
+			source: "package p\nfunc f() { c := map[string]string{}; c[\"host\"] = \"private.corp.internal\" }\n",
+			want:   []string{"private.corp.internal"},
+		},
+		{
+			name:   "host collection values",
+			source: "package p\nvar ALLOWED_HOSTS = []string{\"private.corp.internal\", \"attacker.zip\"}\n",
+			want:   []string{"attacker.zip", "private.corp.internal"},
+		},
+		{
+			name:   "host collection map keys",
+			source: "package p\nvar allowedHosts = map[string]struct{}{\"attacker.zip\": {}}\n",
+			want:   []string{"attacker.zip"},
+		},
+		{
+			name:   "host collection bool map keys",
+			source: "package p\nvar AllowedHosts = map[string]bool{\"api.example.com\": true}\n",
+			want:   []string{"api.example.com"},
+		},
+		{
+			name:   "host collection map values",
+			source: "package p\nvar HostsByRegion = map[string]string{\"sg\": \"api.example.com\"}\n",
+			want:   []string{"api.example.com"},
+		},
+		{
+			name: "host collection map value assignment",
+			source: "package p\nfunc f() {\n" +
+				" HostsByRegion := map[string]string{}\n" +
+				" HostsByRegion[\"sg\"] = \"api.example.com\"\n" +
+				"}\n",
+			want: []string{"api.example.com"},
+		},
+		{
+			name:   "static concatenation",
+			source: "package p\nvar APIHost = \"attacker.\" + \"zip\"\n",
+			want:   []string{"attacker.zip"},
+		},
+		{
+			name:   "multiline assignment",
+			source: "package p\nfunc f() {\n APIHost :=\n  \"attacker.zip\"\n _ = APIHost\n}\n",
+			want:   []string{"attacker.zip"},
+		},
+		{
+			name:   "escaped hostname",
+			source: "package p\nvar APIHost = \"private\\u002ecorp\\u002einternal\"\n",
+			want:   []string{"private.corp.internal"},
+		},
+		{
+			name:   "hex escaped hostname",
+			source: "package p\nvar APIHost = \"private\\x2ecorp\\x2einternal\"\n",
+			want:   []string{"private.corp.internal"},
+		},
+		{
+			name:   "octal escaped hostname",
+			source: "package p\nvar APIHost = \"private\\056corp\\056internal\"\n",
+			want:   []string{"private.corp.internal"},
+		},
+		{
+			name:   "raw hostname",
+			source: "package p\nvar APIHost = `private.corp.internal`\n",
+			want:   []string{"private.corp.internal"},
+		},
+		{
+			name: "same-file constant reference",
+			source: "package p\nconst existingConst = \"private.corp.internal\"\n" +
+				"func f() { APIHost := existingConst; _ = APIHost }\n",
+			want: []string{"private.corp.internal"},
+		},
+		{
+			name:   "absolute URL",
+			source: "package p\nvar message = \"https://private.corp.internal/v1\"\n",
+			want:   []string{"private.corp.internal"},
+		},
+		{
+			name:   "websocket URL with port",
+			source: "package p\nvar endpoint = \"wss://private.corp.internal:443/v1\"\n",
+			want:   []string{"private.corp.internal"},
+		},
+		{
+			name:   "URL userinfo query and fragment",
+			source: "package p\nvar endpoint = \" https://user:pass@private.corp.internal:8443/v1?q=1#result \"\n",
+			want:   []string{"private.corp.internal"},
+		},
+		{
+			name:   "IDN hostname",
+			source: "package p\nvar APIHost = \"例子.公司.cn\"\n",
+			want:   []string{"例子.公司.cn"},
+		},
+		{
+			name:   "case port and trailing dot normalization",
+			source: "package p\nvar APIHost = \"EXAMPLE.COM.:443\"\n",
+			want:   []string{"example.com"},
+		},
+	}
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			got := evidenceHosts(scanDomainEvidence(t, tc.source))
+			if len(got) != len(tc.want) {
+				t.Fatalf("hosts = %v, want %v", got, tc.want)
+			}
+			for i := range got {
+				if got[i] != tc.want[i] {
+					t.Fatalf("hosts = %v, want %v", got, tc.want)
+				}
+			}
+		})
+	}
+}
+
+func TestGoDomainEvidenceTrueNegatives(t *testing.T) {
+	source := `package p
+
+import _ "github.com/larksuite/oapi-sdk-go/v3"
+
+var file = "archive.zip"
+var event = "card.action.trigger"
+var schema = "im.messages.list"
+var configFile = "service.prod.json"
+var version = "v1.2.3"
+var email = "name@example.com"
+var lowConfidence = "attacker.zip"
+var downloadURL = "archive.zip/file"
+var prose = "See https://private.corp.internal/v1 for details"
+// https://private.corp.internal/v1
+var ghost = "private.corp.internal"
+var hostnameParser = "private.corp.internal"
+var domainError = "private.corp.internal"
+var APIHost = "localhost"
+var BackupHost = "127.0.0.1"
+var hosts = struct{ File string }{File: "archive.zip"}
+var AllowedHosts = map[string]string{"api.example.com": "client.pem"}
+
+func dynamicValue() string { return "private.corp.internal" }
+var DynamicHost = dynamicValue()
+
+func setAmbiguousHostMetadata() {
+	AllowedHosts["api.example.com"] = "client.pem"
+}
+`
+	if got := scanDomainEvidence(t, source); len(got) != 0 {
+		t.Fatalf("unexpected evidence: %+v", got)
+	}
+}
+
+func TestTypedStructFieldHostnameSemantics(t *testing.T) {
+	t.Run("network fields", func(t *testing.T) {
+		source := `package source
+
+type Config struct { Host string }
+type FeishuSource struct { Domain string }
+
+var config = Config{Host: "api.example.com"}
+var source = FeishuSource{Domain: "events.example.com"}
+`
+		got := evidenceHosts(scanTypedDomainEvidenceInPackage(
+			t,
+			"github.com/larksuite/cli/internal/event/source",
+			source,
+		))
+		want := []string{"api.example.com", "events.example.com"}
+		if len(got) != len(want) || got[0] != want[0] || got[1] != want[1] {
+			t.Fatalf("hosts = %v, want %v", got, want)
+		}
+	})
+
+	t.Run("command metadata domain", func(t *testing.T) {
+		source := `package cmdmeta
+
+type Meta struct { Domain string }
+
+var meta = Meta{Domain: "im.messages"}
+func update(meta *Meta) { meta.Domain = "docs.pages" }
+`
+		if got := scanTypedDomainEvidenceInPackage(
+			t,
+			"github.com/larksuite/cli/internal/cmdmeta",
+			source,
+		); len(got) != 0 {
+			t.Fatalf("unexpected command metadata evidence: %+v", got)
+		}
+	})
+
+	t.Run("card action host", func(t *testing.T) {
+		source := `package im
+
+type CardActionTriggerOutput struct { Host string }
+
+var output = CardActionTriggerOutput{Host: "card.action"}
+func update(output *CardActionTriggerOutput) { output.Host = "im.message" }
+`
+		if got := scanTypedDomainEvidenceInPackage(
+			t,
+			"github.com/larksuite/cli/events/im",
+			source,
+		); len(got) != 0 {
+			t.Fatalf("unexpected card host evidence: %+v", got)
+		}
+	})
+
+	t.Run("unknown field ownership is conservative", func(t *testing.T) {
+		source := "package p\ntype Config struct { Host string }\nvar c = Config{Host: \"api.example.com\"}\n"
+		if got := scanDomainEvidence(t, source); len(got) != 0 {
+			t.Fatalf("unexpected untyped field evidence: %+v", got)
+		}
+	})
+}
+
+func TestHostnameSemanticNames(t *testing.T) {
+	for _, name := range []string{
+		"host", "HOST", "hosts", "hostname", "domains",
+		"api_host", "API_HOST", "ALLOWED_HOSTS",
+		"apiHost", "APIHost", "backupHostname",
+		"HostsByRegion", "APIHostsByRegion", "hostsByRegion",
+	} {
+		if !isHostnameSemanticName(name) {
+			t.Errorf("%q should be hostname-semantic", name)
+		}
+	}
+	for _, name := range []string{
+		"ghost", "hostnameParser", "domainError", "hostValue", "downloadURL", "endpoint", "origin",
+		"HostBypass", "APIHostBypass",
+	} {
+		if isHostnameSemanticName(name) {
+			t.Errorf("%q must not be hostname-semantic", name)
+		}
+	}
+}
+
+func TestDomainFixturePaths(t *testing.T) {
+	for _, path := range []string{
+		"internal/x/x_test.go",
+		"tests/cli_e2e/x.go",
+		"internal/x/testdata/sample.go",
+	} {
+		if !isDomainFixturePath(path) {
+			t.Errorf("%q should be fixture scope", path)
+		}
+	}
+	for _, path := range []string{
+		"internal/x/test_helper.go",
+		"examples/demo.go",
+		"skills/example/testdata/sample.go",
+		"skills/example/example_test.go",
+	} {
+		if isDomainFixturePath(path) {
+			t.Errorf("%q must not be fixture scope", path)
+		}
+	}
+}

lint/main.go

@@ -3,7 +3,7 @@
 
 // Command lintcheck runs repository source-contract guards that golangci-lint
 // cannot express directly. It currently covers typed-error contracts and the
-// resolver-owned endpoint contract.
+// resolver-owned endpoint and approved-domain contracts.
 //
 // lintcheck lives in its own Go module under lint/ so its build-time
 // dependency on golang.org/x/tools/go/packages does not leak into the
@@ -43,8 +43,10 @@ type scanner struct {
 
 var scanners = []scanner{
 	{name: "errscontract", fn: errscontract.ScanRepoWithOptions},
-	{name: "domaincontract", fn: func(root string, _ errscontract.ScanOptions) ([]lintapi.Violation, error) {
-		return domaincontract.ScanRepo(root)
+	{name: "domaincontract", fn: func(root string, opts errscontract.ScanOptions) ([]lintapi.Violation, error) {
+		return domaincontract.ScanRepoWithOptions(root, domaincontract.ScanOptions{
+			ChangedFrom: opts.ChangedFrom,
+		})
 	}},
 }
 
@@ -57,7 +59,7 @@ func main() {
 				"Runs every registered lint domain against repo-root (default: current directory).\n")
 		flag.PrintDefaults()
 	}
-	flag.StringVar(&changedFrom, "changed-from", "", "base revision for incremental boundary-error checks")
+	flag.StringVar(&changedFrom, "changed-from", "", "base revision for incremental source-contract checks")
 	flag.BoolVar(&printLegacyCommandErrorCandidates, "print-legacy-command-error-candidates", false, "print existing command boundary bare errors as allowlist candidates")
 	flag.Parse()
 

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@larksuite/cli",
-  "version": "1.0.76",
+  "version": "1.0.80",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@larksuite/cli",
-      "version": "1.0.76",
+      "version": "1.0.80",
       "cpu": [
         "x64",
         "arm64",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larksuite/cli",
-  "version": "1.0.76",
+  "version": "1.0.80",
   "description": "The official CLI for Lark/Feishu open platform",
   "bin": {
     "lark-cli": "scripts/run.js"

scripts/semantic-review-workflow.test.sh

@@ -176,7 +176,15 @@ if ! grep -Fq "if: always() && github.event.workflow_run.conclusion == 'success'
   exit 1
 fi
 
-require_in_step "$summary_verify_step" 'workflowPath !== ".github/workflows/ci.yml"' "PR quality summary must verify the triggering workflow path"
+if grep -Fq 'run.name !== "CI"' "$workflow"; then
+  echo "semantic-review must not use the dynamic workflow run name as workflow identity" >&2
+  exit 1
+fi
+
+require_in_step "$summary_verify_step" 'github.rest.actions.getWorkflow' "PR quality summary must resolve static workflow metadata"
+require_in_step "$summary_verify_step" 'workflow.name !== "CI"' "PR quality summary must verify the static workflow name"
+require_in_step "$summary_verify_step" 'workflow.path !== ".github/workflows/ci.yml"' "PR quality summary must verify the static workflow path"
+require_in_step "$summary_verify_step" 'run.path && run.path !== workflow.path' "PR quality summary must reject workflow path metadata mismatches"
 require_in_step "$summary_verify_step" 'run.event !== "pull_request"' "PR quality summary must only handle pull_request workflow_run events"
 require_in_step "$summary_verify_step" 'run.repository.id !== context.payload.repository.id' "PR quality summary must verify workflow_run repository id"
 require_in_step "$summary_verify_step" 'const targetHeadSha = run.head_sha' "PR quality summary must use the CI run head SHA as the verified PR head"
@@ -201,7 +209,10 @@ require_in_step "$summary_publish_step" 'CI_QUALITY_SUMMARY_BASE_SHA' "PR qualit
 require_in_step "$summary_publish_step" 'CI_QUALITY_SUMMARY_RUN_ID' "PR quality summary publisher must receive verified workflow run id"
 require_in_step "$summary_publish_step" 'require("./scripts/ci-quality-summary-publish.js")' "PR quality summary publisher must use the shared CI publisher script"
 
-require_in_step "$verify_step" 'workflowPath !== ".github/workflows/ci.yml"' "semantic-review must verify the triggering workflow path"
+require_in_step "$verify_step" 'github.rest.actions.getWorkflow' "semantic-review must resolve static workflow metadata"
+require_in_step "$verify_step" 'workflow.name !== "CI"' "semantic-review must verify the static workflow name"
+require_in_step "$verify_step" 'workflow.path !== ".github/workflows/ci.yml"' "semantic-review must verify the static workflow path"
+require_in_step "$verify_step" 'run.path && run.path !== workflow.path' "semantic-review must reject workflow path metadata mismatches"
 require_in_step "$verify_step" 'run.repository.id !== context.payload.repository.id' "semantic-review must verify workflow_run repository id"
 require_in_step "$verify_step" 'run.event !== "pull_request"' "semantic-review must only handle pull_request workflow_run events"
 require_in_step "$verify_step" 'run.conclusion !== "success"' "semantic-review must only consume successful CI runs"

shortcuts/apps/apps_cache_clear.go

@@ -0,0 +1,71 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"fmt"
+	"io"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// AppsCacheClear clears all cache entries for the app in the given environment.
+//
+// POST /apps/{app_id}/cache/clear，body {env}。清空当前应用指定环境下全部缓存，用于无法定位
+// 具体 key 的快速恢复；影响面大，定 high-risk-write（框架自动注入 --yes 确认）。
+var AppsCacheClear = common.Shortcut{
+	Service:     appsService,
+	Command:     "+cache-clear",
+	Description: "Clear all cache entries for the app in the given environment",
+	Risk:        "high-risk-write",
+	Tips: []string{
+		"Example: lark-cli apps +cache-clear --app-id <app_id> --environment dev --yes",
+	},
+	Scopes:    []string{"spark:app:write"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		cacheEnvFlag(),
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		_, err := requireAppID(rctx.Str("app-id"))
+		return err
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			POST(appCacheClearPath(appID)).
+			Desc("Clear all cache entries for the app in the given environment").
+			Body(dbEnvParams(rctx, map[string]interface{}{}))
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		data, err := rctx.CallAPITyped("POST", appCacheClearPath(appID), nil, dbEnvParams(rctx, map[string]interface{}{}))
+		if err != nil {
+			return withAppsHint(err, appIDListHint)
+		}
+		out := map[string]interface{}{
+			"environment":       resolvedEnv(data, rctx),
+			"deleted_key_count": cacheInt(data["deleted_key_count"]),
+		}
+		rctx.OutFormat(out, nil, func(w io.Writer) {
+			renderCacheClearPretty(w, out)
+		})
+		return nil
+	},
+}
+
+// renderCacheClearPretty 打 "✓ cache cleared: N entries (env)"。
+func renderCacheClearPretty(w io.Writer, out map[string]interface{}) {
+	n := int64(0)
+	if f, ok := numericAsFloat(out["deleted_key_count"]); ok {
+		n = int64(f)
+	}
+	fmt.Fprintf(w, "✓ cache cleared: %d entries (%s)\n", n, common.GetString(out, "environment"))
+}

shortcuts/apps/apps_cache_delete.go

@@ -0,0 +1,75 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"fmt"
+	"io"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// AppsCacheDelete deletes a single business cache key (idempotent).
+//
+// DELETE /apps/{app_id}/cache?env=&key=。缓存是派生数据、删单 key 影响面小且可重建，
+// 故定 write（非 high-risk-write、不需 --yes）。目标不存在按幂等成功处理（deleted_key_count=0）。
+var AppsCacheDelete = common.Shortcut{
+	Service:     appsService,
+	Command:     "+cache-delete",
+	Description: "Delete a single business cache key (idempotent)",
+	Risk:        "write",
+	Tips: []string{
+		"Example: lark-cli apps +cache-delete --app-id <app_id> --environment dev --key <key>",
+	},
+	Scopes:    []string{"spark:app:write"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		{Name: "key", Desc: "business cache key", Required: true},
+		cacheEnvFlag(),
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		_, err := requireAppID(rctx.Str("app-id"))
+		return err
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			DELETE(appCachePath(appID)).
+			Desc("Delete a Miaoda app runtime cache key").
+			Params(dbEnvParams(rctx, map[string]interface{}{"key": rctx.Str("key")}))
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		key := rctx.Str("key")
+		data, err := rctx.CallAPITyped("DELETE", appCachePath(appID), dbEnvParams(rctx, map[string]interface{}{"key": key}), nil)
+		if err != nil {
+			return withAppsHint(err, appIDListHint)
+		}
+		out := map[string]interface{}{
+			"key":               key,
+			"environment":       resolvedEnv(data, rctx),
+			"deleted_key_count": cacheInt(data["deleted_key_count"]),
+		}
+		rctx.OutFormat(out, nil, func(w io.Writer) {
+			renderCacheDeletePretty(w, out)
+		})
+		return nil
+	},
+}
+
+// renderCacheDeletePretty 命中打 "✓ cache deleted"，幂等未命中打 "✓ cache already absent"（措辞区分，都成功）。
+func renderCacheDeletePretty(w io.Writer, out map[string]interface{}) {
+	key := common.GetString(out, "key")
+	if n, ok := numericAsFloat(out["deleted_key_count"]); ok && n > 0 {
+		fmt.Fprintf(w, "✓ cache deleted: %s\n", key)
+		return
+	}
+	fmt.Fprintf(w, "✓ cache already absent: %s\n", key)
+}

shortcuts/apps/apps_cache_get.go

@@ -0,0 +1,105 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"context"
+	"fmt"
+	"io"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// AppsCacheGet reads a single business cache key's value + metadata.
+//
+// GET /apps/{app_id}/cache?env=&key=。value 在 wire 上是 JSON 字符串透传：--format json
+// 原样输出该字符串（不反序列化），--format pretty 反序列化后缩进展开。value_size_bytes 由 CLI
+// 按 value 字节长度算出（端点不返回）；未命中（exists=false）时不带 value，ttl_ms/value_size_bytes 为 null。
+var AppsCacheGet = common.Shortcut{
+	Service:     appsService,
+	Command:     "+cache-get",
+	Description: "Get a business cache key's value and metadata",
+	Risk:        "read",
+	Tips: []string{
+		"Example: lark-cli apps +cache-get --app-id <app_id> --key spotbonus:2026:winners:list:v1",
+		"Example: lark-cli apps +cache-get --app-id <app_id> --environment online --key <key>",
+	},
+	Scopes:    []string{"spark:app:read"},
+	AuthTypes: []string{"user"},
+	HasFormat: true,
+	Flags: []common.Flag{
+		{Name: "app-id", Desc: "Miaoda app id", Required: true},
+		{Name: "key", Desc: "business cache key", Required: true},
+		cacheEnvFlag(),
+	},
+	Validate: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		_, err := requireAppID(rctx.Str("app-id"))
+		return err
+	},
+	DryRun: func(ctx context.Context, rctx *common.RuntimeContext) *common.DryRunAPI {
+		appID, _ := requireAppID(rctx.Str("app-id"))
+		return common.NewDryRunAPI().
+			GET(appCachePath(appID)).
+			Desc("Get a Miaoda app runtime cache key").
+			Params(dbEnvParams(rctx, map[string]interface{}{"key": rctx.Str("key")}))
+	},
+	Execute: func(ctx context.Context, rctx *common.RuntimeContext) error {
+		appID, err := requireAppID(rctx.Str("app-id"))
+		if err != nil {
+			return err
+		}
+		key := rctx.Str("key")
+		data, err := rctx.CallAPITyped("GET", appCachePath(appID), dbEnvParams(rctx, map[string]interface{}{"key": key}), nil)
+		if err != nil {
+			return withAppsHint(err, appIDListHint)
+		}
+		out := projectCacheGet(data, key, rctx)
+		rctx.OutFormat(out, nil, func(w io.Writer) {
+			renderCacheGetPretty(w, out)
+		})
+		return nil
+	},
+}
+
+// projectCacheGet 组装 cache-get 输出：key 回显、environment 取 resolved env、exists 直读；
+// 命中时带 ttl_ms + value（原始串）+ value_size_bytes（CLI 算），未命中时 ttl_ms/value_size_bytes 为 null、无 value。
+func projectCacheGet(data map[string]interface{}, key string, rctx *common.RuntimeContext) map[string]interface{} {
+	exists := cacheBool(data["exists"])
+	out := map[string]interface{}{
+		"key":         key,
+		"environment": resolvedEnv(data, rctx),
+		"exists":      exists,
+	}
+	if exists {
+		val := common.GetString(data, "value")
+		out["ttl_ms"] = cacheInt(data["ttl_ms"])
+		out["value_size_bytes"] = len([]byte(val))
+		out["value"] = val
+	} else {
+		out["ttl_ms"] = nil
+		out["value_size_bytes"] = nil
+	}
+	return out
+}
+
+// renderCacheGetPretty 打元信息块（key/environment/exists，命中再加 ttl/value_size），命中时末尾展开 value。
+func renderCacheGetPretty(w io.Writer, out map[string]interface{}) {
+	exists, _ := out["exists"].(bool)
+	pairs := [][2]string{
+		{"key", common.GetString(out, "key")},
+		{"environment", common.GetString(out, "environment")},
+		{"exists", fmt.Sprintf("%v", exists)},
+	}
+	if exists {
+		pairs = append(pairs,
+			[2]string{"ttl", formatCacheTTL(out["ttl_ms"])},
+			[2]string{"value_size", humanBytes(out["value_size_bytes"])},
+		)
+	}
+	renderKeyValuePairs(w, pairs)
+	if exists {
+		fmt.Fprintln(w, "value:")
+		printCacheValuePretty(w, common.GetString(out, "value"))
+	}
+}

shortcuts/apps/apps_cache_test.go

@@ -0,0 +1,357 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+const (
+	cacheURL      = "/open-apis/spark/v1/apps/app_x/cache"
+	cacheClearURL = "/open-apis/spark/v1/apps/app_x/cache/clear"
+)
+
+// cacheValueStr 是服务端在 wire 上透传的原始 JSON 字符串（value 不反序列化）。
+const cacheValueStr = `[{"name":"Alice","award":"Gold"},{"name":"Bob","award":"Silver"}]`
+
+// ── cache-get ──
+
+// TestAppsCacheGet_HitJSON：命中时 json 默认——value 原样透传（不反序列化），
+// value_size_bytes 由 CLI 按 value 字节长度算出，environment 取服务端 resolved env。
+func TestAppsCacheGet_HitJSON(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: cacheURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"env": "online", "exists": true, "ttl_ms": 272000, "value": cacheValueStr,
+		}},
+	})
+	if err := runAppsShortcut(t, AppsCacheGet,
+		[]string{"+cache-get", "--app-id", "app_x", "--environment", "online", "--key", "k:1", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	d := parseEnvelopeData(t, stdout)
+	if d["key"] != "k:1" || d["environment"] != "online" || d["exists"] != true {
+		t.Fatalf("get hit data=%v", d)
+	}
+	if v, _ := d["value"].(string); v != cacheValueStr {
+		t.Fatalf("value must be raw passthrough string, got %v", d["value"])
+	}
+	if sz, _ := numericAsFloat(d["value_size_bytes"]); int(sz) != len(cacheValueStr) {
+		t.Fatalf("value_size_bytes = %v, want %d", d["value_size_bytes"], len(cacheValueStr))
+	}
+	// ttl_ms 必须是 JSON number（透传服务端数字，不得变成字符串）；JSON 解析后为 float64。
+	if _, ok := d["ttl_ms"].(float64); !ok {
+		t.Fatalf("ttl_ms must be a JSON number, got %T (%v)", d["ttl_ms"], d["ttl_ms"])
+	}
+}
+
+// TestAppsCacheGet_HitPretty：pretty 把 value 反序列化后展开（含缩进后的字段），并打元信息标签。
+func TestAppsCacheGet_HitPretty(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: cacheURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"env": "online", "exists": true, "ttl_ms": 272000, "value": cacheValueStr,
+		}},
+	})
+	if err := runAppsShortcut(t, AppsCacheGet,
+		[]string{"+cache-get", "--app-id", "app_x", "--environment", "online", "--key", "k:1", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	got := stdout.String()
+	for _, want := range []string{"key", "environment", "exists", "value", "Alice"} {
+		if !strings.Contains(got, want) {
+			t.Errorf("pretty missing %q:\n%s", want, got)
+		}
+	}
+}
+
+// TestAppsCacheGet_Miss：未命中——exists=false，无 value，ttl_ms / value_size_bytes 为 null。
+func TestAppsCacheGet_Miss(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: cacheURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"env": "online", "exists": false,
+		}},
+	})
+	if err := runAppsShortcut(t, AppsCacheGet,
+		[]string{"+cache-get", "--app-id", "app_x", "--environment", "online", "--key", "k:1", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	d := parseEnvelopeData(t, stdout)
+	if d["exists"] != false {
+		t.Fatalf("miss exists=%v", d["exists"])
+	}
+	if _, ok := d["value"]; ok {
+		t.Fatalf("miss must not carry value: %v", d)
+	}
+	if d["ttl_ms"] != nil || d["value_size_bytes"] != nil {
+		t.Fatalf("miss ttl_ms/value_size_bytes must be null: %v", d)
+	}
+}
+
+// TestAppsCacheGet_ExistsAsString：服务端把 exists 返成字符串 "true" 时仍按命中处理
+// （cacheBool 容错，防 exists 以字符串形态出现被误判成未命中、hit→miss 翻转）。
+func TestAppsCacheGet_ExistsAsString(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: cacheURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"env": "online", "exists": "true", "ttl_ms": 272000, "value": cacheValueStr,
+		}},
+	})
+	if err := runAppsShortcut(t, AppsCacheGet,
+		[]string{"+cache-get", "--app-id", "app_x", "--environment", "online", "--key", "k:1", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	d := parseEnvelopeData(t, stdout)
+	if d["exists"] != true {
+		t.Fatalf("exists string \"true\" 应按命中解析, got exists=%v", d["exists"])
+	}
+	if v, _ := d["value"].(string); v != cacheValueStr {
+		t.Fatalf("命中应带 value, got %v", d["value"])
+	}
+}
+
+// TestAppsCacheGet_PrettyNonJSONFallback：pretty 下 value 不是合法 JSON 时降级原样输出
+// （safeParseJSON 解析失败→原样打印，不报错、不吞值）。补齐 HitPretty 只覆盖了"能反序列化"路径的缺口。
+func TestAppsCacheGet_PrettyNonJSONFallback(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: cacheURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"env": "online", "exists": true, "ttl_ms": 272000, "value": "hello-plain-not-json",
+		}},
+	})
+	if err := runAppsShortcut(t, AppsCacheGet,
+		[]string{"+cache-get", "--app-id", "app_x", "--environment", "online", "--key", "k:1", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	if !strings.Contains(stdout.String(), "hello-plain-not-json") {
+		t.Fatalf("非 JSON value 应原样输出（降级）, got:\n%s", stdout.String())
+	}
+}
+
+// TestAppsCacheGet_TTLAsStringNormalized：服务端把 ttl_ms 返成字符串 "272000" 时，
+// 输出的 ttl_ms 必须归一成 JSON number（cacheInt），不得随 wire 形态漂移成字符串。
+func TestAppsCacheGet_TTLAsStringNormalized(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "GET", URL: cacheURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{
+			"env": "online", "exists": true, "ttl_ms": "272000", "value": cacheValueStr,
+		}},
+	})
+	if err := runAppsShortcut(t, AppsCacheGet,
+		[]string{"+cache-get", "--app-id", "app_x", "--environment", "online", "--key", "k:1", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	d := parseEnvelopeData(t, stdout)
+	f, ok := d["ttl_ms"].(float64)
+	if !ok {
+		t.Fatalf("ttl_ms string wire 应归一成 JSON number, got %T (%v)", d["ttl_ms"], d["ttl_ms"])
+	}
+	if int(f) != 272000 {
+		t.Fatalf("ttl_ms = %v, want 272000", f)
+	}
+}
+
+// TestAppsCacheDelete_CountAsStringNormalized：服务端把 deleted_key_count 返成字符串 "1" 时，
+// 输出必须归一成 JSON number（cacheInt）。
+func TestAppsCacheDelete_CountAsStringNormalized(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE", URL: cacheURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"env": "dev", "deleted_key_count": "1"}},
+	})
+	if err := runAppsShortcut(t, AppsCacheDelete,
+		[]string{"+cache-delete", "--app-id", "app_x", "--environment", "dev", "--key", "k:1", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	d := parseEnvelopeData(t, stdout)
+	if _, ok := d["deleted_key_count"].(float64); !ok {
+		t.Fatalf("deleted_key_count string wire 应归一成 JSON number, got %T (%v)", d["deleted_key_count"], d["deleted_key_count"])
+	}
+}
+
+// TestAppsCacheGet_DryRunOmitsEnv：不传 --environment 时 dry-run query 不带 env（服务端自动选），但带 key。
+func TestAppsCacheGet_DryRunOmitsEnv(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsCacheGet,
+		[]string{"+cache-get", "--app-id", "app_x", "--key", "k:1", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	a := firstDryRunAPI(t, stdout.String())
+	if a.Method != "GET" || a.URL != cacheURL {
+		t.Fatalf("dry-run = %s %s", a.Method, a.URL)
+	}
+	if _, ok := a.Params["env"]; ok {
+		t.Fatalf("no --environment → env must be omitted, params=%v", a.Params)
+	}
+	if a.Params["key"] != "k:1" {
+		t.Fatalf("key must be in query, params=%v", a.Params)
+	}
+}
+
+// TestAppsCacheGet_DryRunWithEnv：显式 --environment dev → query 带 env=dev。
+func TestAppsCacheGet_DryRunWithEnv(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsCacheGet,
+		[]string{"+cache-get", "--app-id", "app_x", "--environment", "dev", "--key", "k:1", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	a := firstDryRunAPI(t, stdout.String())
+	if a.Params["env"] != "dev" {
+		t.Fatalf("env must be dev, params=%v", a.Params)
+	}
+}
+
+// TestAppsCacheGet_RequiresKey：缺 --key → 校验错。
+func TestAppsCacheGet_RequiresKey(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsCacheGet,
+		[]string{"+cache-get", "--app-id", "app_x", "--as", "user"}, factory, stdout); err == nil {
+		t.Fatalf("expected required --key error")
+	}
+}
+
+// ── cache-delete ──
+
+// TestAppsCacheDelete_Hit：删中命中的 key → deleted_key_count=1；pretty 打 "✓ cache deleted"。
+func TestAppsCacheDelete_Hit(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE", URL: cacheURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"env": "dev", "deleted_key_count": 1}},
+	})
+	if err := runAppsShortcut(t, AppsCacheDelete,
+		[]string{"+cache-delete", "--app-id", "app_x", "--environment", "dev", "--key", "k:1", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	if !strings.Contains(stdout.String(), "✓ cache deleted") {
+		t.Fatalf("pretty: %s", stdout.String())
+	}
+}
+
+// TestAppsCacheDelete_AbsentJSON：目标不存在 → 幂等成功，deleted_key_count=0，pretty 措辞区分。
+func TestAppsCacheDelete_AbsentJSON(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE", URL: cacheURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"env": "dev", "deleted_key_count": 0}},
+	})
+	if err := runAppsShortcut(t, AppsCacheDelete,
+		[]string{"+cache-delete", "--app-id", "app_x", "--environment", "dev", "--key", "k:1", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	d := parseEnvelopeData(t, stdout)
+	if sz, _ := numericAsFloat(d["deleted_key_count"]); int(sz) != 0 || d["key"] != "k:1" || d["environment"] != "dev" {
+		t.Fatalf("absent data=%v", d)
+	}
+}
+
+// TestAppsCacheDelete_AbsentPretty：不存在 pretty 打 "✓ cache already absent"。
+func TestAppsCacheDelete_AbsentPretty(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE", URL: cacheURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"env": "dev", "deleted_key_count": 0}},
+	})
+	if err := runAppsShortcut(t, AppsCacheDelete,
+		[]string{"+cache-delete", "--app-id", "app_x", "--environment", "dev", "--key", "k:1", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	if !strings.Contains(stdout.String(), "already absent") {
+		t.Fatalf("pretty: %s", stdout.String())
+	}
+}
+
+// TestAppsCacheDelete_DryRun：DELETE 方法、/cache 路由，query 带 key + env。
+func TestAppsCacheDelete_DryRun(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsCacheDelete,
+		[]string{"+cache-delete", "--app-id", "app_x", "--environment", "dev", "--key", "k:1", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	a := firstDryRunAPI(t, stdout.String())
+	if a.Method != "DELETE" || a.URL != cacheURL {
+		t.Fatalf("dry-run = %s %s", a.Method, a.URL)
+	}
+	if a.Params["key"] != "k:1" || a.Params["env"] != "dev" {
+		t.Fatalf("params=%v", a.Params)
+	}
+}
+
+// ── cache-clear ──
+
+// TestAppsCacheClear_Success：清空成功 → deleted_key_count=128；pretty 打 "✓ cache cleared: 128 entries (dev)"。
+func TestAppsCacheClear_Success(t *testing.T) {
+	factory, stdout, reg := newAppsExecuteFactory(t)
+	reg.Register(&httpmock.Stub{
+		Method: "POST", URL: cacheClearURL,
+		Body: map[string]interface{}{"code": 0, "data": map[string]interface{}{"env": "dev", "deleted_key_count": 128}},
+	})
+	if err := runAppsShortcut(t, AppsCacheClear,
+		[]string{"+cache-clear", "--app-id", "app_x", "--environment", "dev", "--yes", "--format", "pretty", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("execute err=%v", err)
+	}
+	if !strings.Contains(stdout.String(), "✓ cache cleared: 128 entries (dev)") {
+		t.Fatalf("pretty: %s", stdout.String())
+	}
+}
+
+// TestAppsCacheClear_RequiresConfirmation：high-risk-write 无 --yes → 被确认门拦截。
+func TestAppsCacheClear_RequiresConfirmation(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsCacheClear,
+		[]string{"+cache-clear", "--app-id", "app_x", "--environment", "dev", "--as", "user"}, factory, stdout); err == nil {
+		t.Fatalf("expected confirmation gate without --yes")
+	}
+}
+
+// TestAppsCacheClear_DryRunBodyWithEnv：dry-run POST /cache/clear，body 带 env=dev。
+func TestAppsCacheClear_DryRunBodyWithEnv(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsCacheClear,
+		[]string{"+cache-clear", "--app-id", "app_x", "--environment", "dev", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	a := firstDryRunAPI(t, stdout.String())
+	if a.Method != "POST" || a.URL != cacheClearURL {
+		t.Fatalf("dry-run = %s %s", a.Method, a.URL)
+	}
+	if a.Body["env"] != "dev" {
+		t.Fatalf("body must carry env=dev, body=%v", a.Body)
+	}
+}
+
+// TestAppsCacheClear_DryRunBodyOmitsEnv：不传 --environment → body 不带 env（服务端自动选）。
+func TestAppsCacheClear_DryRunBodyOmitsEnv(t *testing.T) {
+	factory, stdout, _ := newAppsExecuteFactory(t)
+	if err := runAppsShortcut(t, AppsCacheClear,
+		[]string{"+cache-clear", "--app-id", "app_x", "--dry-run", "--as", "user"}, factory, stdout); err != nil {
+		t.Fatalf("dry-run err=%v", err)
+	}
+	a := firstDryRunAPI(t, stdout.String())
+	if _, ok := a.Body["env"]; ok {
+		t.Fatalf("no --environment → body env must be omitted, body=%v", a.Body)
+	}
+}
+
+// firstDryRunAPI 解析 dry-run 输出的第一个 api[] 项（method/url/params/body）。
+// 复用本包规范的 dryRunAPIEnvelope（api 现嵌在 data.api 下，见 dryrun_test.go）。
+func firstDryRunAPI(t *testing.T, s string) dryRunAPICall {
+	t.Helper()
+	var env dryRunAPIEnvelope
+	if err := json.Unmarshal([]byte(s), &env); err != nil || len(env.API) == 0 {
+		t.Fatalf("bad dry-run json: %v\n%s", err, s)
+	}
+	return env.API[0]
+}

shortcuts/apps/cache_common.go

@@ -0,0 +1,99 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package apps
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"strings"
+	"time"
+
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// 应用运行时缓存（Cache）调试命令共享件：路由 + 环境 flag + 渲染。
+//
+// 三条命令都走 spark OpenAPI `/apps/{app_id}/cache[/clear]`，按运行环境（env→dbBranch）隔离：
+// 环境 flag 用 cacheEnvFlag()（只 --environment，不带 db 家族的旧名 --env），env 值经 dbEnv 读、
+// 经 dbEnvParams 注入——get/delete 放 query，clear 放 body（省略即服务端自动选分支）。
+
+// appCachePath 返回缓存单 key 读/删 URL：cache（GET 读、DELETE 删，靠方法区分）。
+func appCachePath(appID string) string {
+	return fmt.Sprintf("%s/apps/%s/cache", apiBasePath, validate.EncodePathSegment(appID))
+}
+
+// appCacheClearPath 返回清空指定环境缓存 URL：cache/clear。
+func appCacheClearPath(appID string) string {
+	return fmt.Sprintf("%s/apps/%s/cache/clear", apiBasePath, validate.EncodePathSegment(appID))
+}
+
+// cacheEnvFlag 返回缓存命令的运行环境 flag。cache 是全新命令、从无旧名 --env，
+// 故只注册干净的 --environment（不带 db 家族那套隐藏 --env + 拒收逻辑）。
+// 省略即服务端按应用多环境状态自动选分支（多环境→dev，非多环境→online）。
+func cacheEnvFlag() common.Flag {
+	return common.Flag{
+		Name: "environment",
+		Enum: []string{"dev", "online"},
+		Desc: "target runtime environment; leave unset to auto-select (multi-env app uses dev, single-env uses online), or pass dev/online",
+	}
+}
+
+// cacheBool 防御性解析布尔：真 bool 直接用；若服务端把 exists 返成字符串 "true"/"false" 也归一成 bool，
+// 其它类型按 false。避免 exists 万一以字符串形态出现时被误判成未命中（hit→miss 翻转）。
+func cacheBool(v interface{}) bool {
+	switch x := v.(type) {
+	case bool:
+		return x
+	case string:
+		return strings.EqualFold(strings.TrimSpace(x), "true")
+	}
+	return false
+}
+
+// cacheInt 把服务端下发的数值字段归一成 int64（无法解析→nil）。本仓惯例：数值可能以字符串下发
+// （见 numericAsFloat 的 string 分支），若直接透传，--format json 的字段类型会随服务端 wire 形态漂移
+// （number ↔ string）。归一后输出类型恒定为数字或 null，消费方无需自己容忍字符串。
+func cacheInt(raw interface{}) interface{} {
+	if f, ok := numericAsFloat(raw); ok {
+		return int64(f)
+	}
+	return nil
+}
+
+// resolvedEnv 取服务端回吐的 resolved env；缺失时兜底成请求侧 --environment（可能为空）。
+// 省略 --environment 时服务端自动选分支，靠服务端回吐才知道实际命中 dev / online。
+func resolvedEnv(data map[string]interface{}, rctx *common.RuntimeContext) string {
+	if env := common.GetString(data, "env"); env != "" {
+		return env
+	}
+	return dbEnv(rctx)
+}
+
+// formatCacheTTL 把剩余 TTL（毫秒）格式化成 4m32s 这样的时长串；非数字返回 "—"。
+func formatCacheTTL(ms interface{}) string {
+	f, ok := numericAsFloat(ms)
+	if !ok {
+		return "—"
+	}
+	return (time.Duration(int64(f)) * time.Millisecond).String()
+}
+
+// printCacheValuePretty 把 value 反序列化后缩进展开（pretty 口径）；非 JSON 则原样打印。
+// 与「json 原样字符串、pretty 才反序列化」的设计一致。
+func printCacheValuePretty(w io.Writer, raw string) {
+	v := safeParseJSON(raw)
+	if s, ok := v.(string); ok {
+		fmt.Fprintln(w, s)
+		return
+	}
+	b, err := json.MarshalIndent(v, "", "  ")
+	if err != nil {
+		fmt.Fprintln(w, raw)
+		return
+	}
+	w.Write(b)
+	fmt.Fprintln(w)
+}

shortcuts/apps/shortcuts.go

@@ -64,6 +64,9 @@ func Shortcuts() []common.Shortcut {
 		AppsFileUpload,
 		AppsFileDelete,
 		AppsFileQuotaGet,
+		AppsCacheGet,
+		AppsCacheDelete,
+		AppsCacheClear,
 		AppsGitCredentialInit,
 		AppsGitCredentialList,
 		AppsGitCredentialRemove,

shortcuts/apps/shortcuts_test.go

@@ -20,13 +20,14 @@ import (
 //   - 3 git-credential
 //   - 5 session（create/list/get/stop/chat）+ 1 session-messages-list
 //   - 8 openapi-key（list/get/create/update/enable/disable/delete/reset）
+//   - 3 cache（get/delete/clear）
 //   - 3 plugin（install/uninstall/list）
 //   - 6 automation（list/get/create/update/enable/disable）
-//   - 9 role（role CRUD + role-member list/add/remove + role-match-list）= 79。
-func TestAppsShortcuts_Returns79(t *testing.T) {
+//   - 9 role（role CRUD + role-member list/add/remove + role-match-list）= 82。
+func TestAppsShortcuts_Returns82(t *testing.T) {
 	got := Shortcuts()
-	if len(got) != 79 {
-		t.Fatalf("Shortcuts() returned %d entries, want 79", len(got))
+	if len(got) != 82 {
+		t.Fatalf("Shortcuts() returned %d entries, want 82", len(got))
 	}
 }
 

shortcuts/base/base_form_execute_test.go

@@ -4,6 +4,7 @@
 package base
 
 import (
+	"encoding/json"
 	"strings"
 	"testing"
 
@@ -250,7 +251,8 @@ func TestBaseFormQuestionsExecuteList(t *testing.T) {
 				"total": 2,
 				"questions": []interface{}{
 					map[string]interface{}{"id": "q_001", "title": "您的姓名", "required": true, "description": nil},
-					map[string]interface{}{"id": "q_002", "title": "您的年龄", "required": false, "description": nil},
+					map[string]interface{}{"id": "q_002", "title": "发票抬头", "required": false, "description": nil,
+						"visible_rule": map[string]interface{}{"logic": "and", "conditions": []interface{}{[]interface{}{"q_001", "==", "是"}}}},
 				},
 			},
 		},
@@ -258,9 +260,14 @@ func TestBaseFormQuestionsExecuteList(t *testing.T) {
 	if err := runShortcut(t, BaseFormQuestionsList, []string{"+form-questions-list", "--base-token", "app_x", "--table-id", "tbl_x", "--form-id", "vew_form1"}, factory, stdout); err != nil {
 		t.Fatalf("err=%v", err)
 	}
-	if got := stdout.String(); !strings.Contains(got, `"q_001"`) || !strings.Contains(got, `"total": 2`) {
+	got := stdout.String()
+	if !strings.Contains(got, `"q_001"`) || !strings.Contains(got, `"total": 2`) {
 		t.Fatalf("stdout=%s", got)
 	}
+	// The list output must forward visible_rule verbatim so agents can read existing display conditions.
+	if !strings.Contains(got, `"visible_rule"`) {
+		t.Fatalf("visible_rule missing from list output: %s", got)
+	}
 }
 
 func TestBaseFormQuestionsExecuteCreate(t *testing.T) {
@@ -296,11 +303,49 @@ func TestBaseFormQuestionsExecuteCreate(t *testing.T) {
 			t.Fatalf("expected error for invalid questions JSON")
 		}
 	})
+
+	t.Run("visible_rule passthrough", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		stub := &httpmock.Stub{
+			Method: "POST",
+			URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/forms/vew_form1/questions",
+			Body: map[string]interface{}{
+				"code": 0,
+				"data": map[string]interface{}{
+					"questions": []interface{}{
+						map[string]interface{}{"id": "q_new1", "title": "发票抬头"},
+					},
+				},
+			},
+		}
+		reg.Register(stub)
+		args := []string{"+form-questions-create", "--base-token", "app_x", "--table-id", "tbl_x", "--form-id", "vew_form1",
+			"--questions", `[{"type":"text","title":"发票抬头","visible_rule":{"logic":"and","conditions":[["是否需要发票","==","是"]]}}]`}
+		if err := runShortcut(t, BaseFormQuestionsCreate, args, factory, stdout); err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		var body struct {
+			Questions []map[string]interface{} `json:"questions"`
+		}
+		if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
+			t.Fatalf("captured body json err=%v body=%s", err, string(stub.CapturedBody))
+		}
+		if len(body.Questions) != 1 {
+			t.Fatalf("questions=%#v", body.Questions)
+		}
+		rule, ok := body.Questions[0]["visible_rule"].(map[string]interface{})
+		if !ok {
+			t.Fatalf("visible_rule not forwarded verbatim: body=%s", string(stub.CapturedBody))
+		}
+		if rule["logic"] != "and" {
+			t.Fatalf("visible_rule logic not preserved: %#v", rule)
+		}
+	})
 }
 
 func TestBaseFormQuestionsExecuteUpdate(t *testing.T) {
 	factory, stdout, reg := newExecuteFactory(t)
-	reg.Register(&httpmock.Stub{
+	stub := &httpmock.Stub{
 		Method: "PATCH",
 		URL:    "/open-apis/base/v3/bases/app_x/tables/tbl_x/forms/vew_form1/questions",
 		Body: map[string]interface{}{
@@ -311,15 +356,29 @@ func TestBaseFormQuestionsExecuteUpdate(t *testing.T) {
 				},
 			},
 		},
-	})
+	}
+	reg.Register(stub)
 	args := []string{"+form-questions-update", "--base-token", "app_x", "--table-id", "tbl_x", "--form-id", "vew_form1",
-		"--questions", `[{"id":"q_001","title":"更新后的问题","required":true}]`}
+		"--questions", `[{"id":"q_001","title":"更新后的问题","required":true,"visible_rule":{"logic":"and","conditions":[["q_002","==","是"]]}}]`}
 	if err := runShortcut(t, BaseFormQuestionsUpdate, args, factory, stdout); err != nil {
 		t.Fatalf("err=%v", err)
 	}
 	if got := stdout.String(); !strings.Contains(got, `"questions"`) || !strings.Contains(got, `"q_001"`) {
 		t.Fatalf("stdout=%s", got)
 	}
+	// visible_rule must be forwarded verbatim to the API (transcribe faithfully).
+	var body struct {
+		Questions []map[string]interface{} `json:"questions"`
+	}
+	if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
+		t.Fatalf("captured body json err=%v body=%s", err, string(stub.CapturedBody))
+	}
+	if len(body.Questions) != 1 {
+		t.Fatalf("questions=%#v", body.Questions)
+	}
+	if _, ok := body.Questions[0]["visible_rule"].(map[string]interface{}); !ok {
+		t.Fatalf("visible_rule not forwarded verbatim: body=%s", string(stub.CapturedBody))
+	}
 }
 
 func TestBaseFormQuestionsExecuteDelete(t *testing.T) {

shortcuts/base/base_form_questions_create.go

@@ -25,14 +25,21 @@ var BaseFormQuestionsCreate = common.Shortcut{
 		{Name: "base-token", Desc: "Base token (base_token)", Required: true},
 		{Name: "table-id", Desc: "table ID", Required: true},
 		{Name: "form-id", Desc: "form ID", Required: true},
-		{Name: "questions", Desc: `questions JSON array, max 10 items. Each item requires "title"(field title) and "type"(text/number/select/datetime/user/attachment/location). Optional fields: "description"(plain text or markdown link like [text](https://example.com)),"required","option_display_mode"(0=dropdown/1=vertical/2=horizontal,select only),"multiple"(bool,select/user),"options"([{"name":"opt","hue":"Blue"}],select only),"style"({"type":"plain/phone/url/email/barcode/rating","precision":2,"format":"yyyy/MM/dd","icon":"star","min":1,"max":5}). E.g. '[{"type":"text","title":"Your name","required":true}]'`, Required: true},
+		{Name: "questions", Desc: `questions JSON array, max 10 items. Each item requires "title"(field title) and "type"(text/number/select/datetime/user/attachment/location). Optional fields: "description"(plain text or markdown link like [text](https://example.com)),"required","option_display_mode"(0=dropdown/1=vertical/2=horizontal,select only),"multiple"(bool,select/user),"options"([{"name":"opt","hue":"Blue"}],select only),"style"({"type":"plain/phone/url/email/barcode/rating","precision":2,"format":"yyyy/MM/dd","icon":"star","min":1,"max":5}),"visible_rule"(display condition; same shape as view filter {"logic":"and","conditions":[["前序题目","==","是"]]}, field references another question's title/id, empty/absent = always shown). E.g. '[{"type":"text","title":"Your name","required":true}]'`, Required: true},
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		return common.NewDryRunAPI().
+		api := common.NewDryRunAPI().
 			POST("/open-apis/base/v3/bases/:base_token/tables/:table_id/forms/:form_id/questions").
 			Set("base_token", runtime.Str("base-token")).
 			Set("table_id", runtime.Str("table-id")).
 			Set("form_id", runtime.Str("form-id"))
+		// Transcribe the questions body verbatim so the preview shows exactly
+		// what would be sent (including optional fields like visible_rule).
+		var questions []interface{}
+		if err := json.Unmarshal([]byte(runtime.Str("questions")), &questions); err == nil {
+			api.Body(map[string]interface{}{"questions": questions})
+		}
+		return api
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		baseToken := runtime.Str("base-token")

shortcuts/base/base_form_questions_update.go

@@ -25,14 +25,26 @@ var BaseFormQuestionsUpdate = common.Shortcut{
 		{Name: "base-token", Desc: "Base token (base_token)", Required: true},
 		{Name: "table-id", Desc: "table ID", Required: true},
 		{Name: "form-id", Desc: "form ID", Required: true},
-		{Name: "questions", Desc: `questions JSON array, max 10 items, each item must include "id". Supported fields: "id"(required),"title","description"(plain text or markdown link like [text](https://example.com)),"required","option_display_mode"(0=dropdown,1=vertical,2=horizontal,select only). E.g. '[{"id":"q_001","title":"Updated?","required":true}]'`, Required: true},
+		{Name: "questions", Desc: `questions JSON array, max 10 items, each item must include "id". Update uses full question overwrite semantics: omitted/empty fields are written as defaults/empty, so run +form-questions-list first and include existing values you want to keep. Supported fields: "id"(required),"title","description"(plain text or markdown link like [text](https://example.com)),"required","option_display_mode"(0=dropdown,1=vertical,2=horizontal,select only),"visible_rule"(display condition; same shape as view filter {"logic":"and","conditions":[["前序题目","==","是"]]}, field references another question's title/id; pass null or omit to clear). E.g. '[{"id":"q_001","title":"Updated?","required":true}]'`, Required: true},
+	},
+	Tips: []string{
+		"Update uses full question overwrite semantics, not a patch.",
+		"Run +form-questions-list first and include existing title/description/required/option_display_mode/visible_rule values you want to keep.",
+		"Omitted fields reset to defaults; empty strings, null, and empty arrays are written as empty/clear when accepted by the API.",
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-		return common.NewDryRunAPI().
+		api := common.NewDryRunAPI().
 			PATCH("/open-apis/base/v3/bases/:base_token/tables/:table_id/forms/:form_id/questions").
 			Set("base_token", runtime.Str("base-token")).
 			Set("table_id", runtime.Str("table-id")).
 			Set("form_id", runtime.Str("form-id"))
+		// Transcribe the questions body verbatim so the preview shows exactly
+		// what would be sent (including optional fields like visible_rule).
+		var questions []interface{}
+		if err := json.Unmarshal([]byte(runtime.Str("questions")), &questions); err == nil {
+			api.Body(map[string]interface{}{"questions": questions})
+		}
+		return api
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		baseToken := runtime.Str("base-token")

shortcuts/base/base_resolve.go

@@ -29,6 +29,7 @@ var BaseURLResolve = common.Shortcut{
 	Risk:        "read",
 	Scopes:      []string{},
 	ConditionalScopes: []string{
+		"base:block:read",
 		"base:field:read",
 		"base:record:read",
 		"wiki:node:retrieve",
@@ -40,7 +41,7 @@ var BaseURLResolve = common.Shortcut{
 		{Name: "query", Hidden: true, Desc: "Alias for --url; accepted to recover from AI routing mistakes"},
 	},
 	Tips: []string{
-		`Example: lark-cli base +url-resolve --url "https://example.larkoffice.com/base/<base_token>?table=<table_id>&view=<view_id>"`,
+		`Example: lark-cli base +url-resolve --url "https://example.larkoffice.com/base/<base_token>?table=<block_id>&view=<view_id>"`,
 		"Only URLs are accepted. For Base titles or keywords, use +title-resolve --title.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
@@ -57,10 +58,34 @@ var BaseURLResolve = common.Shortcut{
 			return common.NewDryRunAPI().Set("error", err.Error())
 		}
 		switch classifyBaseURL(parsed) {
+		case "base_url":
+			baseToken := firstPathSegmentAfter(parsed.Path, "/base/")
+			if selectedBlockID := strings.TrimSpace(parsed.Query().Get("table")); selectedBlockID != "" {
+				return common.NewDryRunAPI().
+					POST("/open-apis/base/v3/bases/:base_token/blocks/list").
+					Body(map[string]interface{}{}).
+					Set("base_token", baseToken).
+					Set("selected_block_id", selectedBlockID)
+			}
+			return common.NewDryRunAPI().Set("url", raw).Set("resolution", "local")
 		case "wiki_url":
-			return common.NewDryRunAPI().
-				GET("/open-apis/wiki/v2/spaces/get_node").
+			dry := common.NewDryRunAPI()
+			selectedBlockID := strings.TrimSpace(parsed.Query().Get("table"))
+			if selectedBlockID == "" {
+				return dry.
+					GET("/open-apis/wiki/v2/spaces/get_node").
+					Params(map[string]interface{}{"token": firstPathSegmentAfter(parsed.Path, "/wiki/")})
+			}
+			dry.Desc("2-step: resolve the Wiki node to a Base, then identify the selected Base block")
+			dry.GET("/open-apis/wiki/v2/spaces/get_node").
+				Desc("[1] Resolve the Wiki node to its underlying Base").
 				Params(map[string]interface{}{"token": firstPathSegmentAfter(parsed.Path, "/wiki/")})
+			dry.POST("/open-apis/base/v3/bases/:base_token/blocks/list").
+				Desc("[2] List Base blocks and match selected_block_id").
+				Body(map[string]interface{}{})
+			return dry.
+				Set("base_token", "<obj_token from step 1>").
+				Set("selected_block_id", selectedBlockID)
 		case "record_share_url":
 			return common.NewDryRunAPI().
 				GET("/open-apis/base/v3/record_share/:record_share_token/meta").
@@ -170,7 +195,7 @@ func executeBaseURLResolve(runtime *common.RuntimeContext) error {
 	switch classifyBaseURL(parsed) {
 	case "base_url":
 		out := resolveBaseURL(parsed)
-		enrichBaseResolveHint(runtime, out)
+		enrichBaseResolveHint(runtime, out, resolveBaseURLSelection(parsed))
 		runtime.OutFormat(out, nil, nil)
 		return nil
 	case "wiki_url":
@@ -178,6 +203,9 @@ func executeBaseURLResolve(runtime *common.RuntimeContext) error {
 		if err != nil {
 			return err
 		}
+		selection := resolveBaseURLSelection(parsed)
+		applyBaseURLSelection(out, selection)
+		enrichBaseResolveHint(runtime, out, selection)
 		runtime.OutFormat(out, nil, nil)
 		return nil
 	case "record_share_url":
@@ -251,24 +279,50 @@ func classifyBaseURL(u *url.URL) string {
 }
 
 func resolveBaseURL(u *url.URL) map[string]interface{} {
-	query := u.Query()
 	out := map[string]interface{}{
 		"input_type":    "base_url",
 		"resource_type": "bitable",
 		"base_token":    firstPathSegmentAfter(u.Path, "/base/"),
 	}
-	if tableID := strings.TrimSpace(query.Get("table")); tableID != "" {
-		out["table_id"] = tableID
-	}
-	if viewID := strings.TrimSpace(query.Get("view")); viewID != "" {
-		out["view_id"] = viewID
-	}
-	if recordID := strings.TrimSpace(query.Get("record")); recordID != "" {
-		out["record_id"] = recordID
-	}
+	applyBaseURLSelection(out, resolveBaseURLSelection(u))
 	return out
 }
 
+type baseURLSelection struct {
+	blockID  string
+	viewID   string
+	recordID string
+}
+
+func resolveBaseURLSelection(u *url.URL) baseURLSelection {
+	query := u.Query()
+	return baseURLSelection{
+		blockID:  strings.TrimSpace(query.Get("table")),
+		viewID:   strings.TrimSpace(query.Get("view")),
+		recordID: strings.TrimSpace(query.Get("record")),
+	}
+}
+
+func applyBaseURLSelection(out map[string]interface{}, selection baseURLSelection) {
+	if selection.blockID != "" {
+		// The Base web UI historically uses the query key "table" for the
+		// currently selected top-level block. Its value can identify a table,
+		// dashboard, workflow, or another block type. Keep it neutral until the
+		// block directory confirms the resource type.
+		out["block_id"] = selection.blockID
+		out["selection_source"] = "url_query"
+	}
+}
+
+func applyResolvedTableSelection(out map[string]interface{}, selection baseURLSelection) {
+	if selection.viewID != "" {
+		out["view_id"] = selection.viewID
+	}
+	if selection.recordID != "" {
+		out["record_id"] = selection.recordID
+	}
+}
+
 func resolveWikiBaseURL(runtime *common.RuntimeContext, u *url.URL) (map[string]interface{}, error) {
 	token := firstPathSegmentAfter(u.Path, "/wiki/")
 	data, err := runtime.CallAPITyped("GET", "/open-apis/wiki/v2/spaces/get_node", map[string]interface{}{"token": token}, nil)
@@ -368,13 +422,89 @@ func executeBaseTitleResolve(runtime *common.RuntimeContext) error {
 	}
 }
 
-func enrichBaseResolveHint(runtime *common.RuntimeContext, out map[string]interface{}) {
+func enrichBaseResolveHint(runtime *common.RuntimeContext, out map[string]interface{}, selection baseURLSelection) {
 	baseToken := strings.TrimSpace(common.GetString(out, "base_token"))
-	tableID := strings.TrimSpace(common.GetString(out, "table_id"))
-	if baseToken == "" || tableID == "" {
+	selectedBlockID := strings.TrimSpace(common.GetString(out, "block_id"))
+	if baseToken == "" || selectedBlockID == "" {
 		out["hint"] = resolveHint("", nil)
 		return
 	}
+
+	if block, found, err := resolveSelectedBaseBlock(runtime, baseToken, selectedBlockID); err == nil && found {
+		out["block_type"] = block.Type
+		if block.Name != "" {
+			out["block_name"] = block.Name
+		}
+		switch block.Type {
+		case "table":
+			applyResolvedTableSelection(out, selection)
+			enrichResolvedTable(runtime, out, baseToken, selectedBlockID)
+		case "dashboard":
+			out["dashboard_id"] = selectedBlockID
+			out["hint"] = map[string]interface{}{
+				"next_step": "this dashboard is only the block currently selected by the URL; if the user names a different dashboard than block_name, use +dashboard-list and match that name first, otherwise use +dashboard-get to inspect this dashboard",
+			}
+		case "workflow":
+			out["workflow_id"] = selectedBlockID
+			out["hint"] = map[string]interface{}{
+				"next_step": "use +workflow-get to inspect the resolved workflow",
+			}
+		case "folder":
+			out["hint"] = map[string]interface{}{
+				"next_step": fmt.Sprintf("use +base-block-list --base-token %s --parent-id %s to list this folder's direct children", baseToken, selectedBlockID),
+			}
+		case "docx":
+			if block.DocxToken != "" {
+				out["docx_token"] = block.DocxToken
+				out["hint"] = map[string]interface{}{
+					"next_step": fmt.Sprintf("use docs +fetch --doc %s to read this document", block.DocxToken),
+				}
+			} else {
+				out["hint"] = map[string]interface{}{
+					"next_step": "use +base-block-list --type docx and match block_id to retrieve this document's docx_token",
+				}
+			}
+		default:
+			out["hint"] = resolveUnknownBlockHint()
+		}
+		return
+	}
+
+	out["hint"] = resolveUnknownBlockHint()
+}
+
+type resolvedBaseBlock struct {
+	ID        string
+	Type      string
+	Name      string
+	DocxToken string
+}
+
+func resolveSelectedBaseBlock(runtime *common.RuntimeContext, baseToken, selectedBlockID string) (resolvedBaseBlock, bool, error) {
+	data, err := baseV3Call(runtime, "POST", baseV3Path("bases", baseToken, "blocks", "list"), nil, map[string]interface{}{})
+	if err != nil {
+		return resolvedBaseBlock{}, false, err
+	}
+	for _, item := range common.GetSlice(data, "blocks") {
+		row, ok := item.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		block := resolvedBaseBlock{
+			ID:        strings.TrimSpace(common.GetString(row, "id")),
+			Type:      strings.TrimSpace(common.GetString(row, "type")),
+			Name:      strings.TrimSpace(common.GetString(row, "name")),
+			DocxToken: strings.TrimSpace(common.GetString(row, "docx_token")),
+		}
+		if block.ID == selectedBlockID {
+			return block, true, nil
+		}
+	}
+	return resolvedBaseBlock{}, false, nil
+}
+
+func enrichResolvedTable(runtime *common.RuntimeContext, out map[string]interface{}, baseToken, tableID string) {
+	out["table_id"] = tableID
 	fields, total, err := listAllFields(runtime, baseToken, tableID, 0, 100)
 	if err != nil {
 		out["hint"] = resolveHint(tableID, nil)
@@ -383,6 +513,12 @@ func enrichBaseResolveHint(runtime *common.RuntimeContext, out map[string]interf
 	out["hint"] = resolveHint(tableID, map[string]interface{}{"fields": map[string]interface{}{"fields": fields, "total": total}})
 }
 
+func resolveUnknownBlockHint() map[string]interface{} {
+	return map[string]interface{}{
+		"next_step": "use +base-block-list and match block_id to determine whether this is a table, dashboard, workflow, folder, or docx block",
+	}
+}
+
 func enrichRecordShareResolveHint(runtime *common.RuntimeContext, out map[string]interface{}) {
 	baseToken := strings.TrimSpace(common.GetString(out, "base_token"))
 	tableID := strings.TrimSpace(common.GetString(out, "table_id"))

shortcuts/base/base_resolve_test.go

@@ -4,6 +4,7 @@
 package base
 
 import (
+	"net/http"
 	"strings"
 	"testing"
 
@@ -17,6 +18,9 @@ import (
 func TestBaseURLResolveBaseURL(t *testing.T) {
 	t.Run("with coordinates", func(t *testing.T) {
 		factory, stdout, reg := newExecuteFactory(t)
+		reg.Register(baseBlockListResolveStub("bas123",
+			map[string]interface{}{"id": "tbl123", "type": "table", "name": "Orders"},
+		))
 		reg.Register(fieldListStub("bas123", "tbl123"))
 		err := runShortcutWithAuthTypes(t, BaseURLResolve, authTypes(), []string{
 			"+url-resolve",
@@ -31,7 +35,7 @@ func TestBaseURLResolveBaseURL(t *testing.T) {
 		if data["input_type"] != "base_url" || data["base_token"] != "bas123" {
 			t.Fatalf("unexpected output: %#v", data)
 		}
-		if data["table_id"] != "tbl123" || data["view_id"] != "vew123" || data["record_id"] != "rec123" {
+		if data["block_id"] != "tbl123" || data["selection_source"] != "url_query" || data["block_type"] != "table" || data["table_id"] != "tbl123" || data["view_id"] != "vew123" || data["record_id"] != "rec123" {
 			t.Fatalf("missing Base coordinates: %#v", data)
 		}
 		hint, _ := data["hint"].(map[string]interface{})
@@ -62,45 +66,213 @@ func TestBaseURLResolveBaseURL(t *testing.T) {
 		}
 	})
 
-	t.Run("field list enrichment failure still returns coordinates", func(t *testing.T) {
+	t.Run("unconfirmed selected block stays neutral", func(t *testing.T) {
 		factory, stdout, _ := newExecuteFactory(t)
 		err := runShortcutWithAuthTypes(t, BaseURLResolve, authTypes(), []string{
-			"+url-resolve", "--url", "https://example.larkoffice.com/base/bas123?table=tbl123", "--as", "user",
+			"+url-resolve", "--url", "https://example.larkoffice.com/base/bas123?table=tbl123&view=vew_stale&record=rec_stale", "--as", "user",
 		}, factory, stdout)
 		if err != nil {
 			t.Fatalf("err=%v", err)
 		}
 		data := decodeBaseEnvelope(t, stdout)
-		if data["base_token"] != "bas123" || data["table_id"] != "tbl123" {
+		if data["base_token"] != "bas123" || data["block_id"] != "tbl123" {
 			t.Fatalf("unexpected output: %#v", data)
 		}
+		if _, ok := data["table_id"]; ok {
+			t.Fatalf("unconfirmed block must not be reported as a table: %#v", data)
+		}
+		if _, ok := data["view_id"]; ok {
+			t.Fatalf("unconfirmed block must not expose table-only view_id: %#v", data)
+		}
+		if _, ok := data["record_id"]; ok {
+			t.Fatalf("unconfirmed block must not expose table-only record_id: %#v", data)
+		}
 		hint, _ := data["hint"].(map[string]interface{})
-		if hint["next_step"] != nextStepRecordList {
+		if !strings.Contains(hint["next_step"].(string), "+base-block-list") {
 			t.Fatalf("unexpected hint: %#v", hint)
 		}
 		if _, ok := hint["fields"]; ok {
 			t.Fatalf("fields should be omitted when enrichment fails: %#v", hint)
 		}
 	})
+
+	t.Run("field endpoint does not confirm untyped block", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		reg.Register(baseBlockListResolveStub("bas123",
+			map[string]interface{}{"id": "tbl_other", "type": "table", "name": "Other"},
+		))
+		fieldStub := fieldListStub("bas123", "tbl123")
+		fieldStub.Optional = true
+		fieldStub.OnMatch = func(_ *http.Request) {
+			t.Fatalf("field endpoint must not be used to infer selected block type")
+		}
+		reg.Register(fieldStub)
+		err := runShortcutWithAuthTypes(t, BaseURLResolve, authTypes(), []string{
+			"+url-resolve", "--url", "https://example.larkoffice.com/base/bas123?table=tbl123&view=vew_stale", "--as", "user",
+		}, factory, stdout)
+		if err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		data := decodeBaseEnvelope(t, stdout)
+		if data["block_id"] != "tbl123" {
+			t.Fatalf("unexpected block coordinates: %#v", data)
+		}
+		if _, ok := data["block_type"]; ok {
+			t.Fatalf("field endpoint must not confirm block type without block directory: %#v", data)
+		}
+		if _, ok := data["table_id"]; ok {
+			t.Fatalf("field endpoint must not promote an untyped block to table_id: %#v", data)
+		}
+		if _, ok := data["view_id"]; ok {
+			t.Fatalf("untyped block must not expose table-only view_id: %#v", data)
+		}
+		hint, _ := data["hint"].(map[string]interface{})
+		if _, ok := hint["fields"]; ok {
+			t.Fatalf("fields should be omitted when block type is unconfirmed: %#v", hint)
+		}
+		if !strings.Contains(hint["next_step"].(string), "+base-block-list") {
+			t.Fatalf("unexpected hint: %#v", hint)
+		}
+	})
+
+	t.Run("dashboard selected through table query key", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		reg.Register(baseBlockListResolveStub("bas123",
+			map[string]interface{}{"id": "blk_dashboard", "type": "dashboard", "name": "Sales"},
+		))
+
+		err := runShortcutWithAuthTypes(t, BaseURLResolve, authTypes(), []string{
+			"+url-resolve", "--url", "https://example.larkoffice.com/base/bas123?table=blk_dashboard&view=vew_stale&record=rec_stale", "--as", "user",
+		}, factory, stdout)
+		if err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		data := decodeBaseEnvelope(t, stdout)
+		if data["block_id"] != "blk_dashboard" || data["selection_source"] != "url_query" || data["block_type"] != "dashboard" || data["dashboard_id"] != "blk_dashboard" || data["block_name"] != "Sales" {
+			t.Fatalf("unexpected dashboard coordinates: %#v", data)
+		}
+		if _, ok := data["table_id"]; ok {
+			t.Fatalf("dashboard must not be reported as table_id: %#v", data)
+		}
+		if _, ok := data["view_id"]; ok {
+			t.Fatalf("dashboard must not expose table-only view_id: %#v", data)
+		}
+		if _, ok := data["record_id"]; ok {
+			t.Fatalf("dashboard must not expose table-only record_id: %#v", data)
+		}
+		hint, _ := data["hint"].(map[string]interface{})
+		nextStep := hint["next_step"].(string)
+		if !strings.Contains(nextStep, "+dashboard-get") || !strings.Contains(nextStep, "+dashboard-list") || !strings.Contains(nextStep, "different dashboard than block_name") {
+			t.Fatalf("unexpected dashboard hint: %#v", hint)
+		}
+	})
+
+	t.Run("workflow selected through table query key", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		reg.Register(baseBlockListResolveStub("bas123",
+			map[string]interface{}{"id": "wkf_notify", "type": "workflow", "name": "Notify"},
+		))
+
+		err := runShortcutWithAuthTypes(t, BaseURLResolve, authTypes(), []string{
+			"+url-resolve", "--url", "https://example.larkoffice.com/base/bas123?table=wkf_notify&view=vew_stale&record=rec_stale", "--as", "user",
+		}, factory, stdout)
+		if err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		data := decodeBaseEnvelope(t, stdout)
+		if data["block_id"] != "wkf_notify" || data["block_type"] != "workflow" || data["workflow_id"] != "wkf_notify" {
+			t.Fatalf("unexpected workflow coordinates: %#v", data)
+		}
+		if _, ok := data["table_id"]; ok {
+			t.Fatalf("workflow must not be reported as table_id: %#v", data)
+		}
+		if _, ok := data["view_id"]; ok {
+			t.Fatalf("workflow must not expose table-only view_id: %#v", data)
+		}
+		if _, ok := data["record_id"]; ok {
+			t.Fatalf("workflow must not expose table-only record_id: %#v", data)
+		}
+		hint, _ := data["hint"].(map[string]interface{})
+		if !strings.Contains(hint["next_step"].(string), "+workflow-get") {
+			t.Fatalf("unexpected workflow hint: %#v", hint)
+		}
+	})
+
+	t.Run("folder selected through table query key", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		reg.Register(baseBlockListResolveStub("bas123",
+			map[string]interface{}{"id": "bfl_projects", "type": "folder", "name": "Projects"},
+		))
+
+		err := runShortcutWithAuthTypes(t, BaseURLResolve, authTypes(), []string{
+			"+url-resolve", "--url", "https://example.larkoffice.com/base/bas123?table=bfl_projects&view=vew_stale&record=rec_stale", "--as", "user",
+		}, factory, stdout)
+		if err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		data := decodeBaseEnvelope(t, stdout)
+		if data["block_id"] != "bfl_projects" || data["block_type"] != "folder" || data["block_name"] != "Projects" {
+			t.Fatalf("unexpected folder coordinates: %#v", data)
+		}
+		if _, ok := data["table_id"]; ok {
+			t.Fatalf("folder must not be reported as table_id: %#v", data)
+		}
+		hint, _ := data["hint"].(map[string]interface{})
+		nextStep := hint["next_step"].(string)
+		if !strings.Contains(nextStep, "+base-block-list --base-token bas123 --parent-id bfl_projects") || strings.Contains(nextStep, "determine whether") {
+			t.Fatalf("unexpected folder hint: %#v", hint)
+		}
+	})
+
+	t.Run("docx selected through table query key", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		reg.Register(baseBlockListResolveStub("bas123",
+			map[string]interface{}{"id": "blk_doc", "type": "docx", "name": "Spec", "docx_token": "docx123"},
+		))
+
+		err := runShortcutWithAuthTypes(t, BaseURLResolve, authTypes(), []string{
+			"+url-resolve", "--url", "https://example.larkoffice.com/base/bas123?table=blk_doc&view=vew_stale&record=rec_stale", "--as", "user",
+		}, factory, stdout)
+		if err != nil {
+			t.Fatalf("err=%v", err)
+		}
+		data := decodeBaseEnvelope(t, stdout)
+		if data["block_id"] != "blk_doc" || data["block_type"] != "docx" || data["block_name"] != "Spec" || data["docx_token"] != "docx123" {
+			t.Fatalf("unexpected docx coordinates: %#v", data)
+		}
+		if _, ok := data["table_id"]; ok {
+			t.Fatalf("docx must not be reported as table_id: %#v", data)
+		}
+		hint, _ := data["hint"].(map[string]interface{})
+		nextStep := hint["next_step"].(string)
+		if !strings.Contains(nextStep, "docs +fetch --doc docx123") || strings.Contains(nextStep, "determine whether") {
+			t.Fatalf("unexpected docx hint: %#v", hint)
+		}
+	})
+}
+
+func baseBlockListResolveStub(baseToken string, blocks ...map[string]interface{}) *httpmock.Stub {
+	items := make([]interface{}, 0, len(blocks))
+	for _, block := range blocks {
+		items = append(items, block)
+	}
+	return &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/base/v3/bases/" + baseToken + "/blocks/list",
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"blocks": items,
+				"total":  len(items),
+			},
+		},
+	}
 }
 
 func TestBaseURLResolveWikiURL(t *testing.T) {
 	t.Run("bitable", func(t *testing.T) {
 		factory, stdout, reg := newExecuteFactory(t)
-		reg.Register(&httpmock.Stub{
-			Method: "GET",
-			URL:    "/open-apis/wiki/v2/spaces/get_node?token=wik123",
-			Body: map[string]interface{}{
-				"code": 0,
-				"data": map[string]interface{}{
-					"node": map[string]interface{}{
-						"obj_type":  "bitable",
-						"obj_token": "bas123",
-						"title":     "Demo Base",
-					},
-				},
-			},
-		})
+		reg.Register(wikiBaseNodeStub("wik123", "bas123", "Demo Base"))
 
 		err := runShortcutWithAuthTypes(t, BaseURLResolve, authTypes(), []string{
 			"+url-resolve", "--url", "https://example.larkoffice.com/wiki/wik123", "--as", "user",
@@ -114,6 +286,57 @@ func TestBaseURLResolveWikiURL(t *testing.T) {
 		}
 	})
 
+	t.Run("bitable with table coordinates", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		reg.Register(wikiBaseNodeStub("wik123", "bas123", "Demo Base"))
+		reg.Register(baseBlockListResolveStub("bas123",
+			map[string]interface{}{"id": "tbl123", "type": "table", "name": "Orders"},
+		))
+		reg.Register(fieldListStub("bas123", "tbl123"))
+
+		err := runShortcutWithAuthTypes(t, BaseURLResolve, authTypes(), []string{
+			"+url-resolve",
+			"--url", "https://example.larkoffice.com/wiki/wik123?table=tbl123&view=vew123&record=rec123",
+			"--as", "user",
+		}, factory, stdout)
+		if err != nil {
+			t.Fatalf("err=%v", err)
+		}
+
+		data := decodeBaseEnvelope(t, stdout)
+		if data["input_type"] != "wiki_url" || data["base_token"] != "bas123" || data["block_id"] != "tbl123" || data["block_type"] != "table" || data["table_id"] != "tbl123" || data["view_id"] != "vew123" || data["record_id"] != "rec123" {
+			t.Fatalf("unexpected Wiki Base table coordinates: %#v", data)
+		}
+	})
+
+	t.Run("bitable with dashboard selection", func(t *testing.T) {
+		factory, stdout, reg := newExecuteFactory(t)
+		reg.Register(wikiBaseNodeStub("wik123", "bas123", "Demo Base"))
+		reg.Register(baseBlockListResolveStub("bas123",
+			map[string]interface{}{"id": "blk_dashboard", "type": "dashboard", "name": "Sales"},
+		))
+
+		err := runShortcutWithAuthTypes(t, BaseURLResolve, authTypes(), []string{
+			"+url-resolve",
+			"--url", "https://example.larkoffice.com/wiki/wik123?table=blk_dashboard&view=vew_stale&record=rec_stale",
+			"--as", "user",
+		}, factory, stdout)
+		if err != nil {
+			t.Fatalf("err=%v", err)
+		}
+
+		data := decodeBaseEnvelope(t, stdout)
+		if data["input_type"] != "wiki_url" || data["block_id"] != "blk_dashboard" || data["block_type"] != "dashboard" || data["dashboard_id"] != "blk_dashboard" {
+			t.Fatalf("unexpected Wiki Base dashboard coordinates: %#v", data)
+		}
+		if _, ok := data["view_id"]; ok {
+			t.Fatalf("dashboard must not expose table-only view_id: %#v", data)
+		}
+		if _, ok := data["record_id"]; ok {
+			t.Fatalf("dashboard must not expose table-only record_id: %#v", data)
+		}
+	})
+
 	t.Run("non bitable", func(t *testing.T) {
 		factory, stdout, reg := newExecuteFactory(t)
 		reg.Register(&httpmock.Stub{
@@ -136,6 +359,23 @@ func TestBaseURLResolveWikiURL(t *testing.T) {
 	})
 }
 
+func wikiBaseNodeStub(wikiToken, baseToken, title string) *httpmock.Stub {
+	return &httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/wiki/v2/spaces/get_node?token=" + wikiToken,
+		Body: map[string]interface{}{
+			"code": 0,
+			"data": map[string]interface{}{
+				"node": map[string]interface{}{
+					"obj_type":  "bitable",
+					"obj_token": baseToken,
+					"title":     title,
+				},
+			},
+		},
+	}
+}
+
 func TestBaseURLResolveRecordShareURL(t *testing.T) {
 	t.Run("enriched", func(t *testing.T) {
 		factory, stdout, reg := newExecuteFactory(t)

shortcuts/base/base_shortcuts_test.go

@@ -783,6 +783,20 @@ func TestBaseJSONExamplesLiveInFlagDescriptions(t *testing.T) {
 				`JSON array of question IDs to delete, max 10 items, e.g. '["q_001","q_002"]'`,
 			},
 		},
+		{
+			name:     "form question create visible_rule",
+			shortcut: BaseFormQuestionsCreate,
+			wantHelp: []string{
+				`"visible_rule"(display condition; same shape as view filter`,
+			},
+		},
+		{
+			name:     "form question update visible_rule",
+			shortcut: BaseFormQuestionsUpdate,
+			wantHelp: []string{
+				`"visible_rule"(display condition; same shape as view filter`,
+			},
+		},
 		{
 			name:     "record search json",
 			shortcut: BaseRecordSearch,
@@ -1028,6 +1042,39 @@ func TestBaseFieldUpdateHelpGuidesAgents(t *testing.T) {
 	}
 }
 
+func TestBaseFormQuestionsUpdateHelpGuidesFullOverwrite(t *testing.T) {
+	parent := &cobra.Command{Use: "base"}
+	BaseFormQuestionsUpdate.Mount(parent, &cmdutil.Factory{})
+	cmd := parent.Commands()[0]
+
+	help := cmd.Flags().FlagUsages()
+	wantHelp := []string{
+		"Update uses full question overwrite semantics",
+		"run +form-questions-list first",
+		"include existing values you want to keep",
+		"pass null or omit to clear",
+	}
+	for _, want := range wantHelp {
+		if !strings.Contains(help, want) {
+			t.Fatalf("flag help missing %q:\n%s", want, help)
+		}
+	}
+
+	tips := strings.Join(cmdutil.GetTips(cmd), "\n")
+	wantTips := []string{
+		"full question overwrite semantics, not a patch",
+		"Run +form-questions-list first",
+		"title/description/required/option_display_mode/visible_rule",
+		"Omitted fields reset to defaults",
+		"empty strings, null, and empty arrays are written as empty/clear",
+	}
+	for _, want := range wantTips {
+		if !strings.Contains(tips, want) {
+			t.Fatalf("tips missing %q:\n%s", want, tips)
+		}
+	}
+}
+
 func TestBaseAttachmentHelpGuidesAgents(t *testing.T) {
 	tests := []struct {
 		name     string

shortcuts/calendar/calendar_agenda.go

@@ -250,6 +250,8 @@ var CalendarAgenda = common.Shortcut{
 					}
 				}
 
+				collapseDescription(e)
+
 				filtered = append(filtered, e)
 			}
 		}

shortcuts/calendar/calendar_create.go

@@ -20,7 +20,6 @@ import (
 func buildEventData(runtime *common.RuntimeContext, startTs, endTs string) map[string]interface{} {
 	eventData := map[string]interface{}{
 		"summary":          runtime.Str("summary"),
-		"description":      runtime.Str("description"),
 		"start_time":       map[string]string{"timestamp": startTs},
 		"end_time":         map[string]string{"timestamp": endTs},
 		"attendee_ability": "can_modify_event",
@@ -33,6 +32,9 @@ func buildEventData(runtime *common.RuntimeContext, startTs, endTs string) map[s
 	if rrule := runtime.Str("rrule"); rrule != "" {
 		eventData["recurrence"] = rrule
 	}
+	if description := descriptionToSend(runtime); description != "" {
+		eventData["description_rich"] = description
+	}
 	return eventData
 }
 
@@ -118,7 +120,7 @@ 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 as Markdown (@file or - for stdin); the unified description field. Supports bold/italic/underline/strikethrough, links, headings (`#`..`###`), blockquotes (`>`), ordered/unordered lists, horizontal rules (`---`), GFM tables, and images (`![name](url)`; a remote URL is used as-is, and a local image path relative to and inside the current working directory is auto-uploaded to Lark drive and rendered inline — absolute/out-of-cwd paths are rejected). A Lark doc URL (bare or as a Markdown link) is auto-resolved to an inline doc-mention chip showing its title. Inside a GFM table cell, stack multiple lines with `<br>`; each line may itself be an ordered/unordered list item, image or styled text (e.g. `1. a<br>2. b`, `- x<br>- y`, `![p](url)<br>**bold**`).", 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)"},
@@ -231,6 +233,9 @@ var CalendarCreate = common.Shortcut{
 		if err != nil {
 			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--end: %v", err).WithParam("--end")
 		}
+		if err := resolveDescriptionImages(runtime, calendarId); err != nil {
+			return err
+		}
 
 		eventData := buildEventData(runtime, startTs, endTs)
 

shortcuts/calendar/calendar_get.go

@@ -81,6 +81,7 @@ type calendarEvent struct {
 	OrganizerCalendarID string                    `json:"organizer_calendar_id,omitempty"`
 	Summary             string                    `json:"summary,omitempty"`
 	Description         string                    `json:"description,omitempty"`
+	DescriptionRich     string                    `json:"description_rich,omitempty"`
 	StartTime           *calendarEventTime        `json:"start_time,omitempty"`
 	EndTime             *calendarEventTime        `json:"end_time,omitempty"`
 	VChat               *calendarEventVChat       `json:"vchat,omitempty"`
@@ -169,7 +170,7 @@ func buildCalendarEventOutput(event *calendarEvent) (map[string]interface{}, err
 	if status, _ := out["status"].(string); status != "cancelled" {
 		delete(out, "status")
 	}
-
+	collapseDescription(out)
 	return out, nil
 }
 

shortcuts/calendar/calendar_test.go

@@ -988,9 +988,15 @@ func TestUpdate_PatchEventOnly(t *testing.T) {
 	if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
 		t.Fatalf("unmarshal captured patch body: %v", err)
 	}
-	if body["summary"] != "Updated Meeting" || body["description"] != "Updated description" {
+	// --description is the unified field, treated as rich text and sent as
+	// description_rich; the CLI never sends the plain description field
+	// (mutually exclusive downstream).
+	if body["summary"] != "Updated Meeting" || body["description_rich"] != "Updated description" {
 		t.Fatalf("unexpected patch body: %#v", body)
 	}
+	if _, ok := body["description"]; ok {
+		t.Fatalf("plain description must not be sent, got: %#v", body)
+	}
 	if body["need_notification"] != false {
 		t.Fatalf("need_notification = %#v, want false", body["need_notification"])
 	}
@@ -1364,6 +1370,62 @@ func TestAgenda_Success(t *testing.T) {
 	}
 }
 
+func TestAgenda_UnifiesDescriptionRich(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/events/instance_view",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"items": []interface{}{
+					map[string]interface{}{
+						"event_id":         "evt_rich",
+						"summary":          "Rich",
+						"status":           "confirmed",
+						"description":      "[测试]\n友情提醒",
+						"description_rich": "友情提醒",
+						"start_time":       map[string]interface{}{"timestamp": "1742515200"},
+						"end_time":         map[string]interface{}{"timestamp": "1742518800"},
+					},
+					map[string]interface{}{
+						"event_id":    "evt_plain",
+						"summary":     "Plain",
+						"status":      "confirmed",
+						"description": "just text",
+						"start_time":  map[string]interface{}{"timestamp": "1742515200"},
+						"end_time":    map[string]interface{}{"timestamp": "1742518800"},
+					},
+				},
+			},
+		},
+	})
+
+	err := mountAndRun(t, CalendarAgenda, []string{
+		"+agenda",
+		"--start", "2025-03-21",
+		"--end", "2025-03-21",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	out := stdout.String()
+	// Read exposes a single unified description field: it carries the rich
+	// (Markdown) value when present, and the plain text otherwise. The internal
+	// description_rich key is never surfaced.
+	if !strings.Contains(out, "\"description\": \"友情提醒\"") {
+		t.Errorf("expected rich value surfaced under description, got: %s", out)
+	}
+	if !strings.Contains(out, "\"description\": \"just text\"") {
+		t.Errorf("expected plain description surfaced for plain-only event, got: %s", out)
+	}
+	if strings.Contains(out, "description_rich") {
+		t.Errorf("description_rich must not appear in output, got: %s", out)
+	}
+}
+
 func TestAgenda_EmptyResult(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
 
@@ -3375,6 +3437,72 @@ func TestGet_Success_FlattensAndConvertsTimes(t *testing.T) {
 	}
 }
 
+func TestGet_UnifiesDescriptionRich(t *testing.T) {
+	// Read exposes a single unified description field carrying the rich value
+	// when present, and the plain text otherwise; description_rich is dropped.
+	t.Run("rich present", func(t *testing.T) {
+		f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+		reg.Register(&httpmock.Stub{
+			Method: "GET",
+			URL:    "/open-apis/calendar/v4/calendars/cal_test123/events/evt_rich",
+			Body: map[string]interface{}{
+				"code": 0, "msg": "success",
+				"data": map[string]interface{}{
+					"event": map[string]interface{}{
+						"event_id":         "evt_rich",
+						"summary":          "Rich",
+						"description":      "[表格]",
+						"description_rich": "| a | b |\n| --- | --- |\n| c | d |",
+						"start_time":       map[string]interface{}{"timestamp": "1742515200", "timezone": "Asia/Shanghai"},
+						"end_time":         map[string]interface{}{"timestamp": "1742518800", "timezone": "Asia/Shanghai"},
+					},
+				},
+			},
+		})
+		if err := mountAndRun(t, CalendarGet, []string{"+get", "--calendar-id", "cal_test123", "--event-id", "evt_rich", "--as", "bot"}, f, stdout); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		out := stdout.String()
+		if !strings.Contains(out, "| a | b |") {
+			t.Errorf("expected rich value surfaced under description, got: %s", out)
+		}
+		if strings.Contains(out, "description_rich") {
+			t.Errorf("description_rich must not appear in output, got: %s", out)
+		}
+	})
+
+	// When only a plain description exists, it is surfaced under description.
+	t.Run("only plain surfaces under description", func(t *testing.T) {
+		f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+		reg.Register(&httpmock.Stub{
+			Method: "GET",
+			URL:    "/open-apis/calendar/v4/calendars/cal_test123/events/evt_plain",
+			Body: map[string]interface{}{
+				"code": 0, "msg": "success",
+				"data": map[string]interface{}{
+					"event": map[string]interface{}{
+						"event_id":    "evt_plain",
+						"summary":     "Plain",
+						"description": "just text",
+						"start_time":  map[string]interface{}{"timestamp": "1742515200", "timezone": "Asia/Shanghai"},
+						"end_time":    map[string]interface{}{"timestamp": "1742518800", "timezone": "Asia/Shanghai"},
+					},
+				},
+			},
+		})
+		if err := mountAndRun(t, CalendarGet, []string{"+get", "--calendar-id", "cal_test123", "--event-id", "evt_plain", "--as", "bot"}, f, stdout); err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		out := stdout.String()
+		if !strings.Contains(out, "\"description\": \"just text\"") {
+			t.Errorf("expected plain description surfaced, got: %s", out)
+		}
+		if strings.Contains(out, "description_rich") {
+			t.Errorf("description_rich must not appear in output, got: %s", out)
+		}
+	})
+}
+
 func TestGet_CancelledStatus_PreservesStatus(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
 

shortcuts/calendar/calendar_update.go

@@ -29,7 +29,7 @@ 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 as Markdown (@file or - for stdin); the unified description field. Supports bold/italic/underline/strikethrough, links, headings (`#`..`###`), blockquotes (`>`), ordered/unordered lists, horizontal rules (`---`), GFM tables, and images (`![name](url)`; a remote URL is used as-is, and a local image path relative to and inside the current working directory is auto-uploaded to Lark drive and rendered inline — absolute/out-of-cwd paths are rejected). A Lark doc URL (bare or as a Markdown link) is auto-resolved to an inline doc-mention chip showing its title. Inside a GFM table cell, stack multiple lines with `<br>`; each line may itself be an ordered/unordered list item, image or styled text (e.g. `1. a<br>2. b`, `- x<br>- y`, `![p](url)<br>**bold**`). Passing an empty string clears the description.", 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)"},
@@ -109,11 +109,13 @@ func buildCalendarUpdateEventData(runtime *common.RuntimeContext) (map[string]in
 	body := map[string]interface{}{}
 	hasFields := false
 
-	for _, field := range []string{"summary", "description"} {
-		if runtime.Cmd.Flags().Changed(field) {
-			body[field] = runtime.Str(field)
-			hasFields = true
-		}
+	if runtime.Cmd.Flags().Changed("summary") {
+		body["summary"] = runtime.Str("summary")
+		hasFields = true
+	}
+	if runtime.Cmd.Flags().Changed("description") {
+		body["description_rich"] = runtime.Str("description")
+		hasFields = true
 	}
 	if runtime.Cmd.Flags().Changed("rrule") {
 		rrule := strings.TrimSpace(runtime.Str("rrule"))
@@ -356,6 +358,12 @@ func executeCalendarUpdate(ctx context.Context, runtime *common.RuntimeContext)
 		return errs.NewValidationError(errs.SubtypeInvalidArgument, "specify --event-id").WithParam("--event-id")
 	}
 
+	if runtime.Cmd.Flags().Changed("description") {
+		if err := resolveDescriptionImages(runtime, calendarID); err != nil {
+			return err
+		}
+	}
+
 	body, hasEventFields, err := buildCalendarUpdateEventData(runtime)
 	if err != nil {
 		return err
@@ -428,8 +436,10 @@ func calendarUpdateResult(eventID string, event map[string]interface{}, addedCou
 	if summary, _ := event["summary"].(string); summary != "" {
 		result["summary"] = summary
 	}
-	if description, _ := event["description"].(string); description != "" {
-		result["description"] = description
+	if rich, _ := event["description_rich"].(string); rich != "" {
+		result["description"] = rich
+	} else if plain, _ := event["description"].(string); plain != "" {
+		result["description"] = plain
 	}
 	if start := formatCalendarEventTime(event["start_time"]); start != "" {
 		result["start"] = start

shortcuts/calendar/description_rich_images.go

@@ -0,0 +1,172 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package calendar
+
+import (
+	"fmt"
+	"image"
+
+	// Register the common image decoders so DecodeConfig can read intrinsic
+	// dimensions for PNG/JPEG/GIF sources.
+	_ "image/gif"
+	_ "image/jpeg"
+	_ "image/png"
+	"net/url"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const calendarMediaParentType = "calendar"
+
+var markdownImageRe = regexp.MustCompile(`!\[([^\]]*)\]\(([^)]*)\)`)
+
+func resolveDescriptionImages(runtime *common.RuntimeContext, calendarID string) error {
+	md := runtime.Str("description")
+	if md == "" || !strings.Contains(md, "![") {
+		return nil
+	}
+	rewritten, changed, err := uploadLocalDescriptionImages(runtime, calendarID, md)
+	if err != nil {
+		return err
+	}
+	if changed {
+		if err := runtime.Cmd.Flags().Set("description", rewritten); err != nil {
+			return errs.NewInternalError(errs.SubtypeUnknown, "failed to update --description after image upload: %v", err).WithCause(err)
+		}
+	}
+	return nil
+}
+
+func uploadLocalDescriptionImages(runtime *common.RuntimeContext, calendarID, md string) (string, bool, error) {
+	matches := markdownImageRe.FindAllStringSubmatchIndex(md, -1)
+	if len(matches) == 0 {
+		return md, false, nil
+	}
+	var out strings.Builder
+	last := 0
+	changed := false
+	cache := map[string]string{}
+	for _, m := range matches {
+		altStart, altEnd, srcStart, srcEnd := m[2], m[3], m[4], m[5]
+		src := strings.TrimSpace(md[srcStart:srcEnd])
+		if !isLocalImageSrc(src) {
+			continue
+		}
+		alt := md[altStart:altEnd]
+		uploadedURL, err := resolveLocalImage(runtime, calendarID, src, alt, cache)
+		if err != nil {
+			return "", false, err
+		}
+		out.WriteString(md[last:srcStart])
+		out.WriteString(uploadedURL)
+		last = srcEnd
+		changed = true
+	}
+	if !changed {
+		return md, false, nil
+	}
+	out.WriteString(md[last:])
+	return out.String(), true, nil
+}
+
+func resolveLocalImage(runtime *common.RuntimeContext, calendarID, src, alt string, cache map[string]string) (string, error) {
+	localPath := localImagePath(src)
+	if cached, ok := cache[localPath]; ok {
+		return cached, nil
+	}
+
+	safePath, err := validate.SafeInputPath(localPath)
+	if err != nil {
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument,
+			"--description image %q could not be read: %v", src, err).
+			WithParam("--description").
+			WithHint("reference local images by a path inside the current working directory (e.g. ./images/pic.png; cd there first), or use an already-uploaded Lark image URL").
+			WithCause(err)
+	}
+
+	info, err := runtime.FileIO().Stat(localPath)
+	if err != nil {
+		return "", common.WrapInputStatErrorTyped(err)
+	}
+
+	fileToken, err := common.UploadDriveMediaAllTyped(runtime, common.DriveMediaUploadAllConfig{
+		FilePath:   localPath,
+		FileName:   filepath.Base(safePath),
+		FileSize:   info.Size(),
+		ParentType: calendarMediaParentType,
+		ParentNode: &calendarID,
+	})
+	if err != nil {
+		return "", err
+	}
+
+	width, height := decodeImageDimensions(runtime, localPath)
+	uploadedURL := buildCalendarImagePreviewURL(runtime.Config.Brand, fileToken, width, height, info.Size())
+	cache[localPath] = uploadedURL
+	return uploadedURL, nil
+}
+
+func decodeImageDimensions(runtime *common.RuntimeContext, path string) (int, int) {
+	f, err := runtime.FileIO().Open(path)
+	if err != nil {
+		return 0, 0
+	}
+	defer f.Close()
+	cfg, _, err := image.DecodeConfig(f)
+	if err != nil {
+		return 0, 0
+	}
+	return cfg.Width, cfg.Height
+}
+
+func isLocalImageSrc(src string) bool {
+	if src == "" {
+		return false
+	}
+	lower := strings.ToLower(src)
+	switch {
+	case strings.HasPrefix(lower, "http://"), strings.HasPrefix(lower, "https://"), strings.HasPrefix(lower, "data:"):
+		return false
+	case strings.HasPrefix(lower, "file://"):
+		return true
+	}
+	if i := strings.Index(src, "://"); i > 0 {
+		return false
+	}
+	return true
+}
+
+func localImagePath(src string) string {
+	s := strings.TrimSpace(src)
+	if strings.HasPrefix(strings.ToLower(s), "file://") {
+		if u, err := url.Parse(s); err == nil && u.Path != "" {
+			s = u.Path
+		}
+	}
+	if decoded, err := url.PathUnescape(s); err == nil {
+		return decoded
+	}
+	return s
+}
+
+func buildCalendarImagePreviewURL(brand core.LarkBrand, fileToken string, width, height int, size int64) string {
+	host := "internal-api-drive-stream.feishu.cn"
+	if brand == core.BrandLark {
+		host = "internal-api-drive-stream.larksuite.com"
+	}
+	u := fmt.Sprintf("https://%s/space/api/box/stream/download/preview/%s?preview_type=16", host, fileToken)
+	if width > 0 && height > 0 {
+		u += fmt.Sprintf("&im_w=%d&im_h=%d", width, height)
+	}
+	if size > 0 {
+		u += fmt.Sprintf("&im_size=%d", size)
+	}
+	return u
+}

shortcuts/calendar/description_rich_images_test.go

@@ -0,0 +1,279 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package calendar
+
+import (
+	"bytes"
+	"encoding/json"
+	"errors"
+	"image"
+	"image/png"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/core"
+	"github.com/larksuite/cli/internal/httpmock"
+)
+
+func TestIsLocalImageSrc(t *testing.T) {
+	cases := []struct {
+		src  string
+		want bool
+	}{
+		{"./images/pic.png", true},
+		{"images/pic.png", true},
+		{"../assets/a.png", true},
+		{"/Users/me/Desktop/a.png", true},
+		{`C:\Users\me\a.png`, true},
+		{"file:///Users/me/a.png", true},
+		{"图片和附件/测试图片.png", true},
+		{"https://example.com/a.png", false},
+		{"http://example.com/a.png", false},
+		{"HTTPS://EXAMPLE.com/a.png", false},
+		{"data:image/png;base64,iVBOR", false},
+		{"ftp://host/a.png", false},
+		{"", false},
+	}
+	for _, c := range cases {
+		if got := isLocalImageSrc(c.src); got != c.want {
+			t.Errorf("isLocalImageSrc(%q) = %v, want %v", c.src, got, c.want)
+		}
+	}
+}
+
+func TestLocalImagePath(t *testing.T) {
+	cases := []struct{ in, want string }{
+		{"images/pic.png", "images/pic.png"},
+		{"images/my%20pic.png", "images/my pic.png"},
+		{"file:///Users/me/a.png", "/Users/me/a.png"},
+	}
+	for _, c := range cases {
+		if got := localImagePath(c.in); got != c.want {
+			t.Errorf("localImagePath(%q) = %q, want %q", c.in, got, c.want)
+		}
+	}
+}
+
+// TestBuildCalendarImagePreviewURL guards the contract the OpenAPI service
+// relies on: a Lark host (so token extraction triggers) whose final path
+// segment is exactly the uploaded file token.
+func TestBuildCalendarImagePreviewURL(t *testing.T) {
+	for _, tc := range []struct {
+		brand    core.LarkBrand
+		hostFrag string
+	}{
+		{core.BrandFeishu, "feishu.cn"},
+		{core.BrandLark, "larksuite"},
+	} {
+		raw := buildCalendarImagePreviewURL(tc.brand, "boxcnTOKEN123", 416, 306, 142568)
+		u, err := url.Parse(raw)
+		if err != nil {
+			t.Fatalf("built URL not parseable: %v", err)
+		}
+		if !strings.Contains(u.Host, tc.hostFrag) {
+			t.Errorf("brand %s host = %q, want fragment %q", tc.brand, u.Host, tc.hostFrag)
+		}
+		segs := strings.Split(strings.Trim(u.Path, "/"), "/")
+		if last := segs[len(segs)-1]; last != "boxcnTOKEN123" {
+			t.Errorf("last path segment = %q, want token", last)
+		}
+		q := u.Query()
+		if q.Get("im_w") != "416" || q.Get("im_h") != "306" || q.Get("im_size") != "142568" {
+			t.Errorf("dimension params missing: im_w=%q im_h=%q im_size=%q", q.Get("im_w"), q.Get("im_h"), q.Get("im_size"))
+		}
+	}
+
+	// With unknown dimensions the helper params are omitted entirely.
+	raw := buildCalendarImagePreviewURL(core.BrandFeishu, "boxcnTOKEN123", 0, 0, 0)
+	if strings.Contains(raw, "im_w") || strings.Contains(raw, "im_size") {
+		t.Errorf("expected no dimension params for unknown size, got %q", raw)
+	}
+}
+
+// TestUploadLocalDescriptionImages_RemoteUntouched verifies remote/data images
+// pass through unchanged and never trigger an upload (runtime unused → nil).
+func TestUploadLocalDescriptionImages_RemoteUntouched(t *testing.T) {
+	md := "text ![a](https://example.com/a.png) more ![b](data:image/png;base64,xx)"
+	got, changed, err := uploadLocalDescriptionImages(nil, "cal", md)
+	if err != nil {
+		t.Fatalf("unexpected err: %v", err)
+	}
+	if changed {
+		t.Errorf("changed = true, want false")
+	}
+	if got != md {
+		t.Errorf("markdown mutated: %q", got)
+	}
+}
+
+// TestCreate_UploadsLocalDescriptionImage runs +create with a local image path,
+// mocks the drive upload, and asserts the create body's description_rich carries
+// the uploaded token (not the local path).
+func TestCreate_UploadsLocalDescriptionImage(t *testing.T) {
+	dir := t.TempDir()
+	orig, err := os.Getwd()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Chdir(dir); err != nil {
+		t.Fatal(err)
+	}
+	defer os.Chdir(orig)
+	if err := os.WriteFile(filepath.Join(dir, "pic.png"), []byte("PNGDATA"), 0600); err != nil {
+		t.Fatal(err)
+	}
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+
+	uploadStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_all",
+		Body:   map[string]interface{}{"code": 0, "msg": "ok", "data": map[string]interface{}{"file_token": "boxcnTOKEN123"}},
+	}
+	reg.Register(uploadStub)
+
+	createStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/calendar/v4/calendars/cal_test123/events",
+		Body: map[string]interface{}{"code": 0, "msg": "ok", "data": map[string]interface{}{
+			"event": map[string]interface{}{
+				"event_id":   "evt_001",
+				"summary":    "Pic",
+				"start_time": map[string]interface{}{"timestamp": "1742515200"},
+				"end_time":   map[string]interface{}{"timestamp": "1742518800"},
+			},
+		}},
+	}
+	reg.Register(createStub)
+
+	runErr := mountAndRun(t, CalendarCreate, []string{
+		"+create",
+		"--summary", "Pic",
+		"--start", "2025-03-21T00:00:00+08:00",
+		"--end", "2025-03-21T01:00:00+08:00",
+		"--calendar-id", "cal_test123",
+		"--description", "![pic](./pic.png)",
+		"--as", "bot",
+	}, f, stdout)
+	if runErr != nil {
+		t.Fatalf("unexpected error: %v", runErr)
+	}
+
+	if uploadStub.CapturedBody == nil {
+		t.Fatalf("expected drive upload to be called")
+	}
+	if createStub.CapturedBody == nil {
+		t.Fatalf("expected create event to be called")
+	}
+	var body map[string]interface{}
+	if err := json.Unmarshal(createStub.CapturedBody, &body); err != nil {
+		t.Fatalf("create body unmarshal: %v", err)
+	}
+	dr, _ := body["description_rich"].(string)
+	if !strings.Contains(dr, "boxcnTOKEN123") {
+		t.Fatalf("description_rich should contain uploaded token, got %q", dr)
+	}
+	if strings.Contains(dr, "./pic.png") {
+		t.Fatalf("local path should be rewritten away, got %q", dr)
+	}
+}
+
+// TestCreate_LocalImageCarriesDimensions verifies a real decodable image's
+// intrinsic width/height and byte size are appended to the rewritten drive URL
+// (so the facade can populate originalWidth/originalHeight and the client can
+// render the image inline).
+func TestCreate_LocalImageCarriesDimensions(t *testing.T) {
+	dir := t.TempDir()
+	orig, err := os.Getwd()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Chdir(dir); err != nil {
+		t.Fatal(err)
+	}
+	defer os.Chdir(orig)
+
+	var buf bytes.Buffer
+	if err := png.Encode(&buf, image.NewRGBA(image.Rect(0, 0, 5, 7))); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dir, "pic.png"), buf.Bytes(), 0600); err != nil {
+		t.Fatal(err)
+	}
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/medias/upload_all",
+		Body:   map[string]interface{}{"code": 0, "msg": "ok", "data": map[string]interface{}{"file_token": "boxcnTOKEN123"}},
+	})
+	createStub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/calendar/v4/calendars/cal_test123/events",
+		Body: map[string]interface{}{"code": 0, "msg": "ok", "data": map[string]interface{}{
+			"event": map[string]interface{}{
+				"event_id":   "evt_001",
+				"summary":    "Pic",
+				"start_time": map[string]interface{}{"timestamp": "1742515200"},
+				"end_time":   map[string]interface{}{"timestamp": "1742518800"},
+			},
+		}},
+	}
+	reg.Register(createStub)
+
+	runErr := mountAndRun(t, CalendarCreate, []string{
+		"+create",
+		"--summary", "Pic",
+		"--start", "2025-03-21T00:00:00+08:00",
+		"--end", "2025-03-21T01:00:00+08:00",
+		"--calendar-id", "cal_test123",
+		"--description", "![pic](./pic.png)",
+		"--as", "bot",
+	}, f, stdout)
+	if runErr != nil {
+		t.Fatalf("unexpected error: %v", runErr)
+	}
+	var body map[string]interface{}
+	if err := json.Unmarshal(createStub.CapturedBody, &body); err != nil {
+		t.Fatalf("create body unmarshal: %v", err)
+	}
+	dr, _ := body["description_rich"].(string)
+	if !strings.Contains(dr, "im_w=5") || !strings.Contains(dr, "im_h=7") {
+		t.Fatalf("description_rich should carry image dimensions, got %q", dr)
+	}
+	if !strings.Contains(dr, "im_size=") {
+		t.Fatalf("description_rich should carry image byte size, got %q", dr)
+	}
+}
+
+// TestCreate_LocalImageAbsolutePathRejected verifies an out-of-cwd absolute path
+// yields a typed --description validation error before any API call.
+func TestCreate_LocalImageAbsolutePathRejected(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
+
+	runErr := mountAndRun(t, CalendarCreate, []string{
+		"+create",
+		"--summary", "Pic",
+		"--start", "2025-03-21T00:00:00+08:00",
+		"--end", "2025-03-21T01:00:00+08:00",
+		"--calendar-id", "cal_test123",
+		"--description", "![p](/etc/hosts)",
+		"--as", "bot",
+	}, f, stdout)
+	if runErr == nil {
+		t.Fatalf("expected error for absolute image path")
+	}
+	var ve *errs.ValidationError
+	if !errors.As(runErr, &ve) {
+		t.Fatalf("expected *errs.ValidationError, got %T: %v", runErr, runErr)
+	}
+	if ve.Param != "--description" {
+		t.Errorf("param = %q, want --description", ve.Param)
+	}
+}

shortcuts/calendar/helpers.go

@@ -30,6 +30,26 @@ func resolveStartEnd(runtime *common.RuntimeContext) (string, string) {
 	return startInput, endInput
 }
 
+func collapseDescription(event map[string]interface{}) {
+	if event == nil {
+		return
+	}
+	rich, _ := event["description_rich"].(string)
+	plain, _ := event["description"].(string)
+	delete(event, "description_rich")
+	switch {
+	case rich != "":
+		event["description"] = rich
+	case plain != "":
+		event["description"] = plain
+	default:
+		delete(event, "description")
+	}
+}
+func descriptionToSend(runtime *common.RuntimeContext) string {
+	return runtime.Str("description")
+}
+
 func hasExplicitBotFlag(cmd *cobra.Command) bool {
 	if cmd == nil {
 		return false

shortcuts/contact/contact_search_bot.go

@@ -0,0 +1,447 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package contact
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"html"
+	"io"
+	"net/http"
+	"strconv"
+	"strings"
+	"unicode/utf8"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+)
+
+const botSearchURL = "/open-apis/bot/v4/bot/search"
+
+const (
+	maxBotSearchQueryChars = 50
+	maxBotSearchChatIDs    = 100
+	maxBotSearchPageSize   = 30
+)
+
+type botSearchAPIRequest struct {
+	Query  string              `json:"query,omitempty"`
+	Filter *botSearchAPIFilter `json:"filter,omitempty"`
+}
+
+// HasChatter uses omitempty: validation rejects =false, so a set field is always
+// true and an unset field stays out of the request entirely.
+type botSearchAPIFilter struct {
+	ChatIDs    []string `json:"chat_ids,omitempty"`
+	HasChatter bool     `json:"has_chatter,omitempty"`
+}
+
+type botSearchAPIData struct {
+	Items     []botSearchAPIItem `json:"items"`
+	HasMore   bool               `json:"has_more"`
+	PageToken string             `json:"page_token"`
+	Notice    string             `json:"notice"`
+}
+
+type botSearchAPIItem struct {
+	ID          string           `json:"id"`
+	DisplayInfo string           `json:"display_info"`
+	MetaData    botSearchAPIMeta `json:"meta_data"`
+}
+
+type botSearchAPIMeta struct {
+	TenantID        string `json:"tenant_id"`
+	EnableJoinGroup bool   `json:"enable_join_group"`
+	ChatID          string `json:"chat_id"`
+	IsAgent         bool   `json:"is_agent"`
+}
+
+type searchBot struct {
+	OpenID      string `json:"open_id"`
+	Name        string `json:"name"`
+	Description string `json:"description,omitempty"`
+	// ChatID is the caller's P2P chat with the bot.
+	ChatID          string   `json:"chat_id"`
+	EnableJoinGroup bool     `json:"enable_join_group"`
+	IsAgent         bool     `json:"is_agent"`
+	TenantID        string   `json:"tenant_id,omitempty"`
+	MatchSegments   []string `json:"match_segments"`
+}
+
+// PageToken is decoded from the response but deliberately not surfaced, matching
+// searchUserResponse: neither search command paginates. Callers narrow the query
+// instead, so handing out a token that no flag accepts would only mislead.
+type searchBotResponse struct {
+	Bots    []searchBot `json:"bots"`
+	HasMore bool        `json:"has_more"`
+	Notice  string      `json:"notice,omitempty"`
+}
+
+var ContactSearchBot = common.Shortcut{
+	Service:     "contact",
+	Command:     "+search-bot",
+	Description: "Search bots (apps) by keyword — across the tenant, or inside specific chats (requires --as user)",
+	Risk:        "read",
+	Scopes:      []string{"search:bot"},
+	AuthTypes:   []string{"user"},
+	Flags: []common.Flag{
+		{Name: "query", Desc: "search keyword (≤ 50 characters); required unless --queries is given"},
+		{Name: "chat-ids", Desc: "search within specific chats (CSV of chat_id; ≤ 100)"},
+		{Name: "has-chatted", Type: "bool", Desc: "narrow a keyword search to bots you've chatted with (omit to disable; =false rejected)"},
+		{Name: "page-size", Type: "int", Default: "20", Desc: "rows per request, 1-30"},
+		{Name: "queries", Desc: "comma-separated keywords searched in parallel; output is a flat bots[] with matched_query plus a queries[] sidecar"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return validateBotSearch(runtime)
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		if raw := strings.TrimSpace(runtime.Str("queries")); raw != "" {
+			filter, err := buildBotSearchFilter(runtime)
+			if err != nil {
+				return common.NewDryRunAPI().Set("error", err.Error())
+			}
+			api := common.NewDryRunAPI()
+			for _, q := range parseAndDedupQueries(raw) {
+				body := &botSearchAPIRequest{Query: q, Filter: filter}
+				api.POST(botSearchURL).
+					Params(map[string]interface{}{"page_size": runtime.Int("page-size")}).
+					Body(body)
+			}
+			return api
+		}
+		body, err := buildBotSearchBody(runtime)
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		return common.NewDryRunAPI().
+			POST(botSearchURL).
+			Params(map[string]interface{}{"page_size": runtime.Int("page-size")}).
+			Body(body)
+	},
+	Execute: executeBotSearch,
+}
+
+// executeBotSearch dispatches to single-query or fanout mode.
+func executeBotSearch(ctx context.Context, runtime *common.RuntimeContext) error {
+	if strings.TrimSpace(runtime.Str("queries")) != "" {
+		return executeBotSearchFanout(ctx, runtime)
+	}
+	return executeBotSearchSingle(ctx, runtime)
+}
+
+// botSearchKeywordRequiredError names every flag that can satisfy the keyword
+// requirement. Naming only --query would tell an agent that --queries is not a
+// way out, which it is.
+func botSearchKeywordRequiredError() error {
+	return common.ValidationErrorf("specify --query or --queries: --chat-ids and --has-chatted shape a keyword search but cannot enumerate bots on their own (the API answers a filter-only request with an empty list)").
+		WithParams(
+			errs.InvalidParam{Name: "--query", Reason: "required unless --queries is given"},
+			errs.InvalidParam{Name: "--queries", Reason: "required unless --query is given"},
+		)
+}
+
+// botSearchHasChattedFalseError is raised from two places — with and without a
+// keyword — so the wording stays in one spot.
+//
+// Agents passing =false almost always mean "do not filter", but the API reads it
+// as "must NOT match". A hard error prevents silent wrong results.
+func botSearchHasChattedFalseError() error {
+	return common.ValidationErrorf("--has-chatted: pass the flag to enable the filter; omit it to disable filtering (=false is rejected to prevent silent wrong results)").
+		WithParam("--has-chatted")
+}
+
+func validateBotSearch(runtime *common.RuntimeContext) error {
+	queriesRaw := strings.TrimSpace(runtime.Str("queries"))
+	query := strings.TrimSpace(runtime.Str("query"))
+	explicitFalseHasChatted := runtime.Cmd.Flags().Changed("has-chatted") && !runtime.Bool("has-chatted")
+
+	if queriesRaw != "" {
+		if query != "" {
+			return common.ValidationErrorf("--query and --queries are mutually exclusive").
+				WithParams(
+					errs.InvalidParam{Name: "--query", Reason: "mutually exclusive with --queries"},
+					errs.InvalidParam{Name: "--queries", Reason: "mutually exclusive with --query"},
+				)
+		}
+		queries := parseAndDedupQueries(queriesRaw)
+		if len(queries) == 0 {
+			return common.ValidationErrorf("--queries: no valid query parsed from %q (separate entries with ',')", queriesRaw).
+				WithParam("--queries")
+		}
+		if len(queries) > maxFanoutQueries {
+			return common.ValidationErrorf("--queries: must be at most %d entries (got %d)", maxFanoutQueries, len(queries)).
+				WithParam("--queries")
+		}
+		for _, q := range queries {
+			if utf8.RuneCountInString(q) > maxBotSearchQueryChars {
+				return common.ValidationErrorf("--queries: entry %q exceeds %d characters", q, maxBotSearchQueryChars).
+					WithParam("--queries")
+			}
+		}
+	} else if query == "" {
+		// No keyword at all. An explicit =false is the more specific mistake, so
+		// report it instead of sending the caller off to add a keyword only to hit
+		// this on the next attempt. +search-user lands here too: a Changed bool
+		// counts as search input for its "at least one" gate, so the =false check
+		// is what it reaches next.
+		//
+		// Scoped to the no-keyword case on purpose. Hoisting it above the keyword
+		// checks would let it mask the mutual-exclusion and length errors, which
+		// +search-user reports first when a keyword is present.
+		if explicitFalseHasChatted {
+			return botSearchHasChattedFalseError()
+		}
+		return botSearchKeywordRequiredError()
+	} else if utf8.RuneCountInString(query) > maxBotSearchQueryChars {
+		return common.ValidationErrorf("--query: length must be between 1 and %d characters", maxBotSearchQueryChars).
+			WithParam("--query")
+	}
+
+	if _, err := parseBotSearchChatIDs(runtime); err != nil {
+		return err
+	}
+
+	if explicitFalseHasChatted {
+		return botSearchHasChattedFalseError()
+	}
+
+	if n := runtime.Int("page-size"); n < 1 || n > maxBotSearchPageSize {
+		return common.ValidationErrorf("--page-size: must be between 1 and %d", maxBotSearchPageSize).
+			WithParam("--page-size")
+	}
+	return nil
+}
+
+func parseBotSearchChatIDs(runtime *common.RuntimeContext) ([]string, error) {
+	raw := strings.TrimSpace(runtime.Str("chat-ids"))
+	if raw == "" {
+		return nil, nil
+	}
+	parts := common.SplitCSV(raw)
+	if len(parts) == 0 {
+		return nil, common.ValidationErrorf("--chat-ids: no valid chat_id parsed from %q (separate entries with ',')", raw).
+			WithParam("--chat-ids")
+	}
+
+	// Normalize before deduping, then check the cap against the deduped list —
+	// the same order common.resolveOpenIDs uses for --user-ids. Doing it the other
+	// way would spend the server's 100-entry budget on duplicates, and would let
+	// 101 copies of one chat be rejected here while the sibling command accepts
+	// them. Normalization matters too: a chat URL and a bare chat_id can name the
+	// same chat.
+	seen := make(map[string]struct{}, len(parts))
+	chatIDs := make([]string, 0, len(parts))
+	for _, part := range parts {
+		normalized, err := common.ValidateChatIDTyped("--chat-ids", part)
+		if err != nil {
+			return nil, err
+		}
+		if _, dup := seen[normalized]; dup {
+			continue
+		}
+		seen[normalized] = struct{}{}
+		chatIDs = append(chatIDs, normalized)
+	}
+	if len(chatIDs) > maxBotSearchChatIDs {
+		return nil, common.ValidationErrorf("--chat-ids: must be at most %d entries", maxBotSearchChatIDs).
+			WithParam("--chat-ids")
+	}
+	return chatIDs, nil
+}
+
+// buildBotSearchFilter reads the scope flags shared by single and fanout search.
+// A nil filter means "no scope": an empty filter object is not the same request.
+func buildBotSearchFilter(runtime *common.RuntimeContext) (*botSearchAPIFilter, error) {
+	filter := &botSearchAPIFilter{}
+	hasFilter := false
+
+	chatIDs, err := parseBotSearchChatIDs(runtime)
+	if err != nil {
+		return nil, err
+	}
+	if len(chatIDs) > 0 {
+		filter.ChatIDs = chatIDs
+		hasFilter = true
+	}
+	if runtime.Cmd.Flags().Changed("has-chatted") && runtime.Bool("has-chatted") {
+		filter.HasChatter = true
+		hasFilter = true
+	}
+
+	if !hasFilter {
+		return nil, nil
+	}
+	return filter, nil
+}
+
+func buildBotSearchBody(runtime *common.RuntimeContext) (*botSearchAPIRequest, error) {
+	filter, err := buildBotSearchFilter(runtime)
+	if err != nil {
+		return nil, err
+	}
+	return &botSearchAPIRequest{
+		Query:  strings.TrimSpace(runtime.Str("query")),
+		Filter: filter,
+	}, nil
+}
+
+// botSearchStdoutCarriesEnvelope reports whether the chosen format puts the
+// response envelope — notice, has_more, and in fanout mode queries[] — into
+// stdout. Only json does; pretty, table, csv and ndjson render rows only, so
+// every piece of "this result is not the whole answer" metadata would vanish and
+// the caller would read a truncated result as a complete one. For those formats
+// the metadata goes to stderr, which keeps stdout pipe-clean. A --jq expression
+// can still project it away, but that is the caller's explicit choice.
+func botSearchStdoutCarriesEnvelope(format string) bool {
+	return format == "json" || format == ""
+}
+
+func executeBotSearchSingle(ctx context.Context, runtime *common.RuntimeContext) error {
+	body, err := buildBotSearchBody(runtime)
+	if err != nil {
+		return err
+	}
+
+	apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
+		HttpMethod:  http.MethodPost,
+		ApiPath:     botSearchURL,
+		Body:        body,
+		QueryParams: larkcore.QueryParams{"page_size": []string{strconv.Itoa(runtime.Int("page-size"))}},
+	})
+	if err != nil {
+		return err
+	}
+
+	data, err := runtime.ClassifyAPIResponse(apiResp)
+	if err != nil {
+		return err
+	}
+	respData, err := decodeBotSearchAPIData(data)
+	if err != nil {
+		return err
+	}
+
+	bots := projectBots(respData)
+	out := searchBotResponse{
+		Bots:    bots,
+		HasMore: respData.HasMore,
+		Notice:  respData.Notice,
+	}
+	runtime.OutFormat(out, &output.Meta{Count: len(bots)}, func(w io.Writer) {
+		if len(bots) == 0 {
+			fmt.Fprintln(w, "No bots found.")
+			return
+		}
+		output.PrintTable(w, prettyBotRows(bots))
+	})
+	if respData.Notice != "" && !botSearchStdoutCarriesEnvelope(runtime.Format) {
+		fmt.Fprintf(runtime.IO().ErrOut, "\nnotice: %s\n", respData.Notice)
+	}
+	if respData.HasMore && !botSearchStdoutCarriesEnvelope(runtime.Format) {
+		fmt.Fprintln(runtime.IO().ErrOut,
+			"\nhint: more matches exist; narrow with --has-chatted or a more specific --query")
+	}
+	return nil
+}
+
+func decodeBotSearchAPIData(data map[string]interface{}) (*botSearchAPIData, error) {
+	raw, err := json.Marshal(data)
+	if err != nil {
+		return nil, contactInvalidResponseError("marshal bot search response data failed").WithCause(err)
+	}
+	var out botSearchAPIData
+	if err := json.Unmarshal(raw, &out); err != nil {
+		return nil, contactInvalidResponseError("decode bot search response data failed").WithCause(err)
+	}
+	return &out, nil
+}
+
+func projectBots(data *botSearchAPIData) []searchBot {
+	if data == nil {
+		return []searchBot{}
+	}
+	bots := make([]searchBot, 0, len(data.Items))
+	for i := range data.Items {
+		item := &data.Items[i]
+		name, description, segments := parseBotDisplayInfo(item.DisplayInfo)
+		bots = append(bots, searchBot{
+			OpenID:          item.ID,
+			Name:            name,
+			Description:     description,
+			ChatID:          item.MetaData.ChatID,
+			EnableJoinGroup: item.MetaData.EnableJoinGroup,
+			IsAgent:         item.MetaData.IsAgent,
+			TenantID:        item.MetaData.TenantID,
+			MatchSegments:   segments,
+		})
+	}
+	return bots
+}
+
+func stripHighlightTags(value string) string {
+	value = strings.ReplaceAll(value, "<h>", "")
+	return strings.ReplaceAll(value, "</h>", "")
+}
+
+func parseBotDisplayInfo(raw string) (name, description string, matchSegments []string) {
+	matchSegments = make([]string, 0)
+	for _, match := range displayInfoHighlightRE.FindAllStringSubmatch(raw, -1) {
+		// The capture can still carry a tag: the non-greedy pattern pairs a
+		// stray `<h>` with the next `</h>`. Strip it so a segment reads like the
+		// name and description it came from, and drop a highlight with no text.
+		segment := html.UnescapeString(stripHighlightTags(match[1]))
+		if strings.TrimSpace(segment) == "" {
+			continue
+		}
+		matchSegments = append(matchSegments, segment)
+	}
+
+	lines := strings.Split(raw, "\n")
+	stripTags := func(value string) string {
+		return strings.TrimSpace(html.UnescapeString(stripHighlightTags(value)))
+	}
+
+	// nameLine records which line the name came from, so the description is read
+	// from the line after it. Reading lines[1] unconditionally echoes the name
+	// back as its own description whenever line 0 is blank, and drops the real
+	// description with it.
+	nameLine := -1
+	if len(lines) > 0 {
+		if candidate := stripTags(lines[0]); candidate != "" {
+			name = candidate
+			nameLine = 0
+		}
+	}
+	if name == "" {
+		for i, line := range lines {
+			if candidate := stripTags(line); candidate != "" {
+				name = candidate
+				nameLine = i
+				break
+			}
+		}
+	}
+	if nameLine >= 0 && nameLine+1 < len(lines) {
+		description = stripTags(lines[nameLine+1])
+	}
+	return name, description, matchSegments
+}
+
+// map[] shape is required by output.PrintTable.
+func prettyBotRows(bots []searchBot) []map[string]interface{} {
+	rows := make([]map[string]interface{}, 0, len(bots))
+	for _, bot := range bots {
+		rows = append(rows, map[string]interface{}{
+			"name":              bot.Name,
+			"description":       common.TruncateStr(bot.Description, 50),
+			"is_agent":          bot.IsAgent,
+			"enable_join_group": bot.EnableJoinGroup,
+			"open_id":           bot.OpenID,
+		})
+	}
+	return rows
+}

shortcuts/contact/contact_search_bot_fanout.go

@@ -0,0 +1,289 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package contact
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"strconv"
+	"sync"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/shortcuts/common"
+	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
+)
+
+// Bot fanout reuses the user fanout's query parsing, concurrency limit and
+// response summary types.
+
+type botFanoutResult struct {
+	Index   int
+	Query   string
+	Bots    []searchBot
+	HasMore bool
+	Notice  string
+	ErrMsg  string // empty = success
+	Err     error  // original failure, kept for typed propagation
+}
+
+// runOneBotQuery converts one fanout request into either bots or an error summary.
+func runOneBotQuery(ctx context.Context, runtime *common.RuntimeContext, index int, query string,
+	filter *botSearchAPIFilter) botFanoutResult {
+	// Pre-check ctx so queued workers see cancellation before issuing a request;
+	// in-flight workers continue until DoAPI returns.
+	if err := ctx.Err(); err != nil {
+		return botFanoutErrorResult(index, query, err)
+	}
+
+	body := &botSearchAPIRequest{Query: query}
+	if filter != nil {
+		body.Filter = filter
+	}
+
+	apiResp, err := runtime.DoAPI(&larkcore.ApiReq{
+		HttpMethod:  http.MethodPost,
+		ApiPath:     botSearchURL,
+		Body:        body,
+		QueryParams: larkcore.QueryParams{"page_size": []string{strconv.Itoa(runtime.Int("page-size"))}},
+	})
+	if err != nil {
+		return botFanoutErrorResult(index, query, err)
+	}
+
+	data, err := runtime.ClassifyAPIResponse(apiResp)
+	if err != nil {
+		return botFanoutErrorResult(index, query, err)
+	}
+	respData, err := decodeBotSearchAPIData(data)
+	if err != nil {
+		return botFanoutErrorResult(index, query, err)
+	}
+
+	return botFanoutResult{
+		Index:   index,
+		Query:   query,
+		Bots:    projectBots(respData),
+		HasMore: respData.HasMore,
+		Notice:  respData.Notice,
+	}
+}
+
+// botFanoutErrorResult records a failed fanout query without stopping other workers.
+func botFanoutErrorResult(index int, query string, err error) botFanoutResult {
+	if err == nil {
+		return botFanoutResult{Index: index, Query: query}
+	}
+	return botFanoutResult{Index: index, Query: query, ErrMsg: contactFanoutErrorSummary(err), Err: err}
+}
+
+func botFanoutContextError(err error) error {
+	subtype := errs.SubtypeNetworkTransport
+	message := "bot search fanout cancelled"
+	if errors.Is(err, context.DeadlineExceeded) {
+		subtype = errs.SubtypeNetworkTimeout
+		message = "bot search fanout deadline exceeded"
+	}
+	return errs.NewNetworkError(subtype, "%s", message).WithCause(err)
+}
+
+func botFanoutPanicError(query string, recovered any) error {
+	err := errs.NewInternalError(errs.SubtypeUnknown,
+		"bot search query %q panicked: %v", query, recovered)
+	if cause, ok := recovered.(error); ok {
+		return err.WithCause(cause)
+	}
+	return err
+}
+
+// Terminal failures invalidate the batch; API and network failures remain
+// eligible for partial-success reporting.
+func botFanoutTerminalError(results []botFanoutResult) error {
+	for _, result := range results {
+		if result.Err == nil {
+			continue
+		}
+		if errors.Is(result.Err, context.Canceled) || errors.Is(result.Err, context.DeadlineExceeded) {
+			return botFanoutContextError(result.Err)
+		}
+		problem, ok := errs.ProblemOf(result.Err)
+		if !ok {
+			return errs.NewInternalError(errs.SubtypeUnknown,
+				"bot search query %q failed with an unclassified error: %v", result.Query, result.Err).
+				WithCause(result.Err)
+		}
+		if problem.Category != errs.CategoryAPI && problem.Category != errs.CategoryNetwork {
+			return result.Err
+		}
+	}
+	return nil
+}
+
+type fanoutBot struct {
+	searchBot
+	MatchedQuery string `json:"matched_query"`
+}
+
+type botFanoutResponse struct {
+	Bots    []fanoutBot    `json:"bots"`
+	Queries []querySummary `json:"queries"`
+	Notice  string         `json:"notice,omitempty"`
+}
+
+// buildBotFanoutResponse flattens recoverable results in query order. Terminal
+// errors fail the batch even when another query succeeded.
+func buildBotFanoutResponse(queries []string, results []botFanoutResult) (*botFanoutResponse, error) {
+	if err := botFanoutTerminalError(results); err != nil {
+		return nil, err
+	}
+
+	indexed := make([]botFanoutResult, len(queries))
+	for _, r := range results {
+		indexed[r.Index] = r
+	}
+
+	out := &botFanoutResponse{
+		Bots:    make([]fanoutBot, 0),
+		Queries: make([]querySummary, 0, len(queries)),
+	}
+	failed := 0
+	var firstErrMsg, firstErrQuery string
+	var firstErr error
+	for i, r := range indexed {
+		out.Queries = append(out.Queries, querySummary{
+			Query:   queries[i],
+			Error:   r.ErrMsg,
+			HasMore: r.HasMore,
+			Notice:  r.Notice,
+		})
+		if r.ErrMsg != "" {
+			failed++
+			if firstErrMsg == "" {
+				firstErrMsg = r.ErrMsg
+				firstErrQuery = queries[i]
+				firstErr = r.Err
+			}
+			continue
+		}
+		if out.Notice == "" {
+			out.Notice = r.Notice
+		}
+		for _, b := range r.Bots {
+			out.Bots = append(out.Bots, fanoutBot{searchBot: b, MatchedQuery: queries[i]})
+		}
+	}
+	if failed == len(queries) && len(queries) > 0 {
+		msg := fmt.Sprintf("all %d queries failed; first: %s (query=%q)",
+			len(queries), firstErrMsg, firstErrQuery)
+		return nil, contactFanoutAllFailedError(firstErr, msg)
+	}
+	return out, nil
+}
+
+func executeBotSearchFanout(ctx context.Context, runtime *common.RuntimeContext) error {
+	queries := parseAndDedupQueries(runtime.Str("queries"))
+
+	filter, err := buildBotSearchFilter(runtime)
+	if err != nil {
+		return err
+	}
+
+	results := make([]botFanoutResult, len(queries))
+	var wg sync.WaitGroup
+	sem := make(chan struct{}, fanoutConcurrency)
+
+schedule:
+	for i, q := range queries {
+		select {
+		case sem <- struct{}{}:
+		case <-ctx.Done():
+			for j := i; j < len(queries); j++ {
+				results[j] = botFanoutErrorResult(j, queries[j], ctx.Err())
+			}
+			break schedule
+		}
+		wg.Add(1)
+		go func(i int, q string) {
+			defer wg.Done()
+			defer func() { <-sem }()
+			defer func() {
+				if r := recover(); r != nil {
+					err := botFanoutPanicError(q, r)
+					results[i] = botFanoutResult{
+						Index:  i,
+						Query:  q,
+						ErrMsg: contactFanoutErrorSummary(err),
+						Err:    err,
+					}
+				}
+			}()
+			results[i] = runOneBotQuery(ctx, runtime, i, q, filter)
+		}(i, q)
+	}
+	wg.Wait()
+
+	resp, err := buildBotFanoutResponse(queries, results)
+	if err != nil {
+		return err
+	}
+
+	failed, hasMoreCount := 0, 0
+	for _, qs := range resp.Queries {
+		if qs.Error != "" {
+			failed++
+		}
+		if qs.HasMore {
+			hasMoreCount++
+		}
+	}
+
+	runtime.OutFormat(resp, &output.Meta{Count: len(resp.Bots)}, func(w io.Writer) {
+		if len(resp.Bots) == 0 {
+			fmt.Fprintln(w, "No bots found.")
+			return
+		}
+		output.PrintTable(w, prettyBotFanoutRows(resp.Bots))
+	})
+
+	if isFanoutSummaryFormat(runtime.Format) {
+		fmt.Fprintf(runtime.IO().ErrOut, "\n%d queries, %d total matches; %d failed, %d with has_more\n",
+			len(queries), len(resp.Bots), failed, hasMoreCount)
+	}
+	// The counts above say how many queries failed but not which, and only the
+	// json envelope carries queries[].error / queries[].notice. Without this an
+	// agent reading csv or a table sees "1 failed" with no way to learn the
+	// keyword or the reason, and a notice disappears entirely.
+	if !botSearchStdoutCarriesEnvelope(runtime.Format) {
+		for _, qs := range resp.Queries {
+			if qs.Error != "" {
+				fmt.Fprintf(runtime.IO().ErrOut, "failed: %q — %s\n", qs.Query, qs.Error)
+			}
+			if qs.Notice != "" {
+				fmt.Fprintf(runtime.IO().ErrOut, "notice: %q — %s\n", qs.Query, qs.Notice)
+			}
+			if qs.HasMore {
+				fmt.Fprintf(runtime.IO().ErrOut, "has_more: %q — more matches exist; narrow this keyword\n", qs.Query)
+			}
+		}
+	}
+	return nil
+}
+
+func prettyBotFanoutRows(bots []fanoutBot) []map[string]interface{} {
+	rows := make([]map[string]interface{}, 0, len(bots))
+	for _, bot := range bots {
+		rows = append(rows, map[string]interface{}{
+			"matched_query":     bot.MatchedQuery,
+			"name":              bot.Name,
+			"description":       common.TruncateStr(bot.Description, 50),
+			"is_agent":          bot.IsAgent,
+			"enable_join_group": bot.EnableJoinGroup,
+			"open_id":           bot.OpenID,
+		})
+	}
+	return rows
+}

shortcuts/contact/contact_search_bot_fanout_test.go

@@ -0,0 +1,684 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package contact
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func TestBotFanoutErrorResultNilErrorIsSuccess(t *testing.T) {
+	r := botFanoutErrorResult(3, "会议助手", nil)
+	if r.ErrMsg != "" || r.Err != nil {
+		t.Fatalf("nil error must stay a success result: %+v", r)
+	}
+	if r.Index != 3 || r.Query != "会议助手" {
+		t.Fatalf("index/query must survive: %+v", r)
+	}
+}
+
+func TestBotFanoutAssembleOrderAndShape(t *testing.T) {
+	results := []botFanoutResult{
+		{Index: 1, Query: "日报", Bots: []searchBot{{OpenID: "ou_b"}}, HasMore: true},
+		{Index: 0, Query: "会议", Bots: []searchBot{{OpenID: "ou_a1"}, {OpenID: "ou_a2"}}},
+		{Index: 2, Query: "审批", ErrMsg: "API 1: nope"},
+	}
+	resp, err := buildBotFanoutResponse([]string{"会议", "日报", "审批"}, results)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	// Results are emitted in query order even though the workers finished out of
+	// order, and a failed query contributes no rows.
+	wantRows := []struct {
+		openID, matched string
+	}{{"ou_a1", "会议"}, {"ou_a2", "会议"}, {"ou_b", "日报"}}
+	if len(resp.Bots) != len(wantRows) {
+		t.Fatalf("bots length: got %d, want %d", len(resp.Bots), len(wantRows))
+	}
+	for i, w := range wantRows {
+		if resp.Bots[i].OpenID != w.openID || resp.Bots[i].MatchedQuery != w.matched {
+			t.Errorf("bots[%d]: got %+v, want %s/%s", i, resp.Bots[i], w.openID, w.matched)
+		}
+	}
+
+	want := []querySummary{
+		{Query: "会议"},
+		{Query: "日报", HasMore: true},
+		{Query: "审批", Error: "API 1: nope"},
+	}
+	if len(resp.Queries) != len(want) {
+		t.Fatalf("queries length: got %d, want %d (every query is enumerated)", len(resp.Queries), len(want))
+	}
+	for i, w := range want {
+		if resp.Queries[i] != w {
+			t.Errorf("queries[%d]: got %+v, want %+v", i, resp.Queries[i], w)
+		}
+	}
+}
+
+func TestBotFanoutAssembleAllFailedReturnsTypedError(t *testing.T) {
+	results := []botFanoutResult{
+		{Index: 0, Query: "会议", ErrMsg: "API 99991663: rate limit", Err: errs.NewAPIError(errs.SubtypeRateLimit, "rate limit").WithCode(99991663)},
+		{Index: 1, Query: "日报", ErrMsg: "HTTP 500 Internal Server Error"},
+	}
+	_, err := buildBotFanoutResponse([]string{"会议", "日报"}, results)
+	if err == nil {
+		t.Fatal("expected an error when every query fails")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected a typed problem, got %T: %v", err, err)
+	}
+	// The first failure's classification must survive, so the caller can tell a
+	// rate limit apart from a transport fault.
+	if problem.Code != 99991663 || problem.Subtype != errs.SubtypeRateLimit {
+		t.Errorf("problem: got %d/%s, want 99991663/%s", problem.Code, problem.Subtype, errs.SubtypeRateLimit)
+	}
+	// Agents grep the count and the first failure out of this message.
+	for _, want := range []string{"all 2 queries failed", "rate limit"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("message must contain %q; got %v", want, err)
+		}
+	}
+}
+
+func TestBotFanoutAssemblePartialFailureSucceeds(t *testing.T) {
+	results := []botFanoutResult{
+		{Index: 0, Query: "会议", Bots: []searchBot{{OpenID: "ou_a"}}},
+		{Index: 1, Query: "日报", ErrMsg: "API 1: nope"},
+	}
+	resp, err := buildBotFanoutResponse([]string{"会议", "日报"}, results)
+	if err != nil {
+		t.Fatalf("one failure out of two must not fail the call: %v", err)
+	}
+	if len(resp.Bots) != 1 || resp.Queries[1].Error == "" {
+		t.Fatalf("partial failure shape: %+v", resp)
+	}
+}
+
+func TestBotFanoutTerminalContextOverridesPartialSuccess(t *testing.T) {
+	tests := []struct {
+		name        string
+		err         error
+		wantSubtype errs.Subtype
+	}{
+		{name: "cancelled", err: context.Canceled, wantSubtype: errs.SubtypeNetworkTransport},
+		{name: "deadline", err: context.DeadlineExceeded, wantSubtype: errs.SubtypeNetworkTimeout},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			results := []botFanoutResult{
+				{Index: 0, Query: "会议", Bots: []searchBot{{OpenID: "ou_a"}}},
+				botFanoutErrorResult(1, "日报", tt.err),
+			}
+			_, err := buildBotFanoutResponse([]string{"会议", "日报"}, results)
+			if err == nil {
+				t.Fatal("terminal context error must fail the batch after a partial success")
+			}
+			if !errors.Is(err, tt.err) {
+				t.Fatalf("error must preserve %v as its cause: %v", tt.err, err)
+			}
+			problem, ok := errs.ProblemOf(err)
+			if !ok || problem.Category != errs.CategoryNetwork || problem.Subtype != tt.wantSubtype {
+				t.Fatalf("problem: got %+v, want network/%s", problem, tt.wantSubtype)
+			}
+		})
+	}
+}
+
+func TestBotFanoutResponseHasNoTopLevelHasMore(t *testing.T) {
+	resp, err := buildBotFanoutResponse([]string{"会议"}, []botFanoutResult{{Index: 0, Query: "会议", HasMore: true}})
+	if err != nil {
+		t.Fatalf("build: %v", err)
+	}
+	raw, err := json.Marshal(resp)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	var envelope map[string]interface{}
+	if err := json.Unmarshal(raw, &envelope); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+	// has_more is per query in the sidecar; a single top-level flag would hide
+	// which keyword was truncated.
+	if _, ok := envelope["has_more"]; ok {
+		t.Fatalf("fanout must not surface a top-level has_more: %s", raw)
+	}
+	if !envelope["queries"].([]interface{})[0].(map[string]interface{})["has_more"].(bool) {
+		t.Fatalf("per-query has_more lost: %s", raw)
+	}
+}
+
+func TestBotFanoutEmptyBotsSerializesAsArray(t *testing.T) {
+	resp, err := buildBotFanoutResponse([]string{"会议"}, []botFanoutResult{{Index: 0, Query: "会议"}})
+	if err != nil {
+		t.Fatalf("build: %v", err)
+	}
+	raw, err := json.Marshal(resp)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	if !strings.Contains(string(raw), `"bots":[]`) {
+		t.Fatalf("empty bots must serialize as [], not null: %s", raw)
+	}
+}
+
+func TestPrettyBotFanoutRowsLeadWithMatchedQuery(t *testing.T) {
+	rows := prettyBotFanoutRows([]fanoutBot{{
+		searchBot:    searchBot{OpenID: "ou_a", Name: "会议助手", Description: strings.Repeat("长", 80)},
+		MatchedQuery: "会议",
+	}})
+	if len(rows) != 1 {
+		t.Fatalf("rows: %d", len(rows))
+	}
+	if rows[0]["matched_query"] != "会议" {
+		t.Errorf("matched_query missing: %+v", rows[0])
+	}
+	if got := rows[0]["description"].(string); len([]rune(got)) > 51 {
+		t.Errorf("description must be truncated like the single-search table: %d runes", len([]rune(got)))
+	}
+}
+
+func TestBotFanoutValidationRejectsQueryAndQueriesTogether(t *testing.T) {
+	cmd := newBotSearchTestCommand()
+	setBotSearchFlag(t, cmd, "query", "会议")
+	setBotSearchFlag(t, cmd, "queries", "会议,日报")
+	runtime := common.TestNewRuntimeContext(cmd, botSearchDefaultConfig())
+
+	err := validateBotSearch(runtime)
+	if err == nil {
+		t.Fatal("expected mutual-exclusion error")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("problem: %+v ok=%v", problem, ok)
+	}
+	if !strings.Contains(err.Error(), "mutually exclusive") {
+		t.Fatalf("message: %v", err)
+	}
+}
+
+func TestBotFanoutValidationLimits(t *testing.T) {
+	tests := []struct {
+		name      string
+		queries   string
+		wantParam string
+	}{
+		{name: "nothing parses", queries: " , , ", wantParam: "--queries"},
+		{name: "over the entry cap", queries: strings.TrimSuffix(strings.Repeat("q%d,", maxFanoutQueries+1), ","), wantParam: "--queries"},
+		{name: "entry too long", queries: strings.Repeat("会", maxBotSearchQueryChars+1), wantParam: "--queries"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			queries := tt.queries
+			if strings.Contains(queries, "%d") {
+				parts := make([]string, 0, maxFanoutQueries+1)
+				for i := 0; i <= maxFanoutQueries; i++ {
+					parts = append(parts, fmt.Sprintf("q%d", i))
+				}
+				queries = strings.Join(parts, ",")
+			}
+			cmd := newBotSearchTestCommand()
+			setBotSearchFlag(t, cmd, "queries", queries)
+			runtime := common.TestNewRuntimeContext(cmd, botSearchDefaultConfig())
+			assertBotSearchValidationProblem(t, validateBotSearch(runtime), tt.wantParam)
+		})
+	}
+}
+
+// --queries alone is enough: the single-search "--query is required" rule must not
+// leak into fanout mode.
+func TestBotFanoutValidationQueriesAloneIsValid(t *testing.T) {
+	cmd := newBotSearchTestCommand()
+	setBotSearchFlag(t, cmd, "queries", "会议助手,日报助手")
+	runtime := common.TestNewRuntimeContext(cmd, botSearchDefaultConfig())
+	if err := validateBotSearch(runtime); err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestBotFanoutFilterAppliedToEveryQuery(t *testing.T) {
+	factory, stdout, _, registry := cmdutil.TestFactory(t, botSearchDefaultConfig())
+	stub := botSearchStub(botSearchURL+"?page_size=20", "")
+	stub.Reusable = true
+	registry.Register(stub)
+
+	err := mountAndRun(t, ContactSearchBot, []string{
+		"+search-bot", "--queries", "会议,日报", "--has-chatted", "--format", "json", "--as", "user",
+	}, factory, stdout)
+	if err != nil {
+		t.Fatalf("execute: %v", err)
+	}
+	if len(stub.CapturedBodies) != 2 {
+		t.Fatalf("expected one request per query, got %d", len(stub.CapturedBodies))
+	}
+	seen := make(map[string]bool, len(stub.CapturedBodies))
+	for i, raw := range stub.CapturedBodies {
+		var body map[string]interface{}
+		if err := json.Unmarshal(raw, &body); err != nil {
+			t.Fatalf("unmarshal req %d: %v", i, err)
+		}
+		seen[fmt.Sprint(body["query"])] = true
+		filter, ok := body["filter"].(map[string]interface{})
+		if !ok || filter["has_chatter"] != true {
+			t.Fatalf("filter must ride along with every query: %#v", body)
+		}
+	}
+	for _, q := range []string{"会议", "日报"} {
+		if !seen[q] {
+			t.Fatalf("query %q never issued; saw %v", q, seen)
+		}
+	}
+}
+
+func TestBotFanoutMatchedQueryFidelityAndDedup(t *testing.T) {
+	factory, stdout, _, registry := cmdutil.TestFactory(t, botSearchDefaultConfig())
+	dedupStub := botSearchStub(botSearchURL+"?page_size=20", "")
+	dedupStub.Reusable = true
+	registry.Register(dedupStub)
+
+	// " 会议 " and "会议" collapse to one query; the duplicate must not double the
+	// requests or the rows.
+	err := mountAndRun(t, ContactSearchBot, []string{
+		"+search-bot", "--queries", " 会议 ,会议", "--format", "json", "--as", "user",
+	}, factory, stdout)
+	if err != nil {
+		t.Fatalf("execute: %v", err)
+	}
+
+	var envelope struct {
+		Data botFanoutResponse `json:"data"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("response JSON: %v\n%s", err, stdout.String())
+	}
+	if len(envelope.Data.Queries) != 1 || envelope.Data.Queries[0].Query != "会议" {
+		t.Fatalf("dedup failed: %+v", envelope.Data.Queries)
+	}
+	for _, bot := range envelope.Data.Bots {
+		if bot.MatchedQuery != "会议" {
+			t.Fatalf("matched_query fidelity: %+v", bot)
+		}
+	}
+}
+
+func TestBotFanoutConcurrencyCap(t *testing.T) {
+	factory, stdout, _, registry := cmdutil.TestFactory(t, botSearchDefaultConfig())
+
+	var inFlight, peak int32
+	stub := botSearchStub(botSearchURL+"?page_size=20", "")
+	stub.Reusable = true
+	stub.OnMatch = func(req *http.Request) {
+		cur := atomic.AddInt32(&inFlight, 1)
+		defer atomic.AddInt32(&inFlight, -1)
+		for {
+			p := atomic.LoadInt32(&peak)
+			if cur <= p || atomic.CompareAndSwapInt32(&peak, p, cur) {
+				break
+			}
+		}
+		time.Sleep(50 * time.Millisecond)
+	}
+	registry.Register(stub)
+
+	queries := []string{"a", "b", "c", "d", "e", "f", "g", "h", "i", "j"}
+	err := mountAndRun(t, ContactSearchBot, []string{
+		"+search-bot", "--queries", strings.Join(queries, ","), "--format", "json", "--as", "user",
+	}, factory, stdout)
+	if err != nil {
+		t.Fatalf("execute: %v", err)
+	}
+	if peak > fanoutConcurrency {
+		t.Errorf("concurrency peak = %d, want <= %d", peak, fanoutConcurrency)
+	}
+	if peak < 2 {
+		t.Errorf("concurrency peak = %d, want >= 2 so the test actually observes parallelism", peak)
+	}
+}
+
+func TestBotFanoutPanicFailsBatch(t *testing.T) {
+	factory, stdout, stderr, registry := cmdutil.TestFactory(t, botSearchDefaultConfig())
+	panicCause := errors.New("synthetic test panic")
+
+	boom := botSearchStub(botSearchURL, "")
+	boom.BodyFilter = func(b []byte) bool { return strings.Contains(string(b), `"boom"`) }
+	boom.OnMatch = func(req *http.Request) { panic(panicCause) }
+	registry.Register(boom)
+
+	okStub := botSearchStub(botSearchURL, "")
+	okStub.Reusable = true
+	registry.Register(okStub)
+
+	err := mountAndRun(t, ContactSearchBot, []string{
+		"+search-bot", "--queries", "ok,boom,fine", "--format", "json", "--as", "user",
+	}, factory, stdout)
+	if err == nil {
+		t.Fatal("a panicking query must fail the batch")
+	}
+	if !errors.Is(err, panicCause) {
+		t.Fatalf("panic cause must be preserved: %v", err)
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem.Category != errs.CategoryInternal || problem.Subtype != errs.SubtypeUnknown {
+		t.Fatalf("problem: got %+v, want internal/%s", problem, errs.SubtypeUnknown)
+	}
+	if stdout.Len() != 0 {
+		t.Fatalf("terminal failure must not write a success envelope: %s", stdout.String())
+	}
+	for _, marker := range []string{"goroutine ", ".go:", "runtime."} {
+		if strings.Contains(stderr.String(), marker) {
+			t.Errorf("stderr leaked stack-trace marker %q: %s", marker, stderr.String())
+		}
+	}
+}
+
+func TestBotFanoutAllQueriesFailingExitsNonZero(t *testing.T) {
+	factory, stdout, _, registry := cmdutil.TestFactory(t, botSearchDefaultConfig())
+	registry.Register(&httpmock.Stub{
+		Method:   "POST",
+		URL:      botSearchURL,
+		Reusable: true,
+		Status:   500,
+		Body:     map[string]interface{}{"reason": "boom"},
+	})
+
+	err := mountAndRun(t, ContactSearchBot, []string{
+		"+search-bot", "--queries", "会议,日报", "--format", "json", "--as", "user",
+	}, factory, stdout)
+	if err == nil {
+		t.Fatal("every query failing must surface as a command error")
+	}
+	if _, ok := errs.ProblemOf(err); !ok {
+		t.Fatalf("expected a typed problem, got %T: %v", err, err)
+	}
+	// The first failure's upstream status and the all-failed mode must both survive,
+	// so a caller can classify instead of seeing a generic internal error.
+	for _, want := range []string{"500", "all 2 queries failed"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Errorf("message must contain %q; got %v", want, err)
+		}
+	}
+}
+
+func TestBotFanoutPartialFailureKeepsNoticeAndSucceeds(t *testing.T) {
+	factory, stdout, _, registry := cmdutil.TestFactory(t, botSearchDefaultConfig())
+
+	broken := botSearchStub(botSearchURL, "")
+	broken.BodyFilter = func(b []byte) bool { return strings.Contains(string(b), `"日报"`) }
+	broken.Status = 500
+	broken.Body = map[string]interface{}{"reason": "boom"}
+	registry.Register(broken)
+
+	okStub := botSearchStub(botSearchURL, "")
+	okStub.Reusable = true
+	registry.Register(okStub)
+
+	err := mountAndRun(t, ContactSearchBot, []string{
+		"+search-bot", "--queries", "会议,日报", "--format", "json", "--as", "user",
+	}, factory, stdout)
+	if err != nil {
+		t.Fatalf("one failing query must not fail the batch: %v", err)
+	}
+
+	var envelope struct {
+		Data botFanoutResponse `json:"data"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("response JSON: %v\n%s", err, stdout.String())
+	}
+
+	const wantNotice = "The query is too long and has been truncated to the first 50 characters for search."
+	// Assert the notice itself, not just that some row survived: the surviving
+	// query's server remark has to reach the caller both at the top level and in
+	// its own sidecar entry.
+	if envelope.Data.Notice != wantNotice {
+		t.Errorf("top-level notice: got %q, want %q", envelope.Data.Notice, wantNotice)
+	}
+	if len(envelope.Data.Queries) != 2 {
+		t.Fatalf("both queries must be enumerated: %+v", envelope.Data.Queries)
+	}
+	if envelope.Data.Queries[0].Notice != wantNotice {
+		t.Errorf("surviving query notice: got %q, want %q", envelope.Data.Queries[0].Notice, wantNotice)
+	}
+	if envelope.Data.Queries[0].Error != "" {
+		t.Errorf("surviving query must carry no error: %q", envelope.Data.Queries[0].Error)
+	}
+	if !strings.Contains(envelope.Data.Queries[1].Error, "500") {
+		t.Errorf("failed query must carry the upstream status: %q", envelope.Data.Queries[1].Error)
+	}
+	// Only the surviving query contributes rows.
+	if len(envelope.Data.Bots) != 1 || envelope.Data.Bots[0].MatchedQuery != "会议" {
+		t.Fatalf("bots: %+v", envelope.Data.Bots)
+	}
+}
+
+func TestBotFanoutCSVCarriesMatchedQueryAndSummary(t *testing.T) {
+	factory, stdout, stderr, registry := cmdutil.TestFactory(t, botSearchDefaultConfig())
+	stub := botSearchStub(botSearchURL, "")
+	stub.Reusable = true
+	registry.Register(stub)
+
+	err := mountAndRun(t, ContactSearchBot, []string{
+		"+search-bot", "--queries", "会议,日报", "--format", "csv", "--as", "user",
+	}, factory, stdout)
+	if err != nil {
+		t.Fatalf("execute: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "matched_query") {
+		t.Errorf("csv must expose matched_query so rows can be traced to a keyword: %s", stdout.String())
+	}
+	// csv is in the summary format set, so the batch counters belong on stderr.
+	if !strings.Contains(stderr.String(), "2 queries, 2 total matches") || !strings.Contains(stderr.String(), "0 failed") {
+		t.Errorf("stderr summary must report the batch counters: %s", stderr.String())
+	}
+	if strings.Contains(stderr.String(), "total bots") {
+		t.Errorf("summary must count matches rather than imply unique bots: %s", stderr.String())
+	}
+}
+
+func TestBotFanoutNDJSONKeepsStdoutClean(t *testing.T) {
+	factory, stdout, stderr, registry := cmdutil.TestFactory(t, botSearchDefaultConfig())
+	stub := botSearchStub(botSearchURL, "")
+	stub.Reusable = true
+	registry.Register(stub)
+
+	err := mountAndRun(t, ContactSearchBot, []string{
+		"+search-bot", "--queries", "会议,日报", "--format", "ndjson", "--as", "user",
+	}, factory, stdout)
+	if err != nil {
+		t.Fatalf("execute: %v", err)
+	}
+	// ndjson is a machine format outside the summary set: every stdout line must
+	// parse, and the counters must not be mixed in.
+	for i, line := range strings.Split(strings.TrimSpace(stdout.String()), "\n") {
+		if line == "" {
+			continue
+		}
+		var row map[string]interface{}
+		if err := json.Unmarshal([]byte(line), &row); err != nil {
+			t.Fatalf("stdout line %d is not JSON: %q", i, line)
+		}
+	}
+	if strings.Contains(stderr.String(), "queries,") {
+		t.Errorf("ndjson must not emit the summary line: %s", stderr.String())
+	}
+}
+
+// TestBotFanoutCancelledSchedulingFailsQueuedQueries drives the real command so
+// the scheduler inside executeBotSearchFanout — not just runOneBotQuery — sees
+// the cancellation. Queueing more keywords than fanoutConcurrency while every
+// worker is parked keeps all semaphore slots held, so the queued keywords can
+// only leave the loop through its ctx.Done() branch.
+func TestBotFanoutCancelledSchedulingFailsQueuedQueries(t *testing.T) {
+	factory, stdout, _, registry := cmdutil.TestFactory(t, botSearchDefaultConfig())
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	started := make(chan struct{})
+	var once sync.Once
+	stub := botSearchStub(botSearchURL+"?page_size=20", "")
+	stub.Reusable = true
+	stub.OnMatch = func(*http.Request) {
+		once.Do(func() { close(started) })
+		<-ctx.Done() // hold the slot so later keywords must queue on the semaphore
+	}
+	registry.Register(stub)
+
+	go func() {
+		select {
+		case <-started:
+		case <-time.After(5 * time.Second): // never leave the workers parked
+		}
+		cancel()
+	}()
+
+	queries := make([]string, 0, fanoutConcurrency+3)
+	for i := 0; i < fanoutConcurrency+3; i++ {
+		queries = append(queries, fmt.Sprintf("q%d", i))
+	}
+
+	err := mountAndRunContext(t, ctx, ContactSearchBot, []string{
+		"+search-bot", "--queries", strings.Join(queries, ","), "--format", "json", "--as", "user",
+	}, factory, stdout)
+	if err == nil {
+		t.Fatal("a cancelled batch must surface as a command error")
+	}
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("cancellation cause must be preserved: %v", err)
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem.Category != errs.CategoryNetwork || problem.Subtype != errs.SubtypeNetworkTransport {
+		t.Fatalf("problem: got %+v, want network/%s", problem, errs.SubtypeNetworkTransport)
+	}
+}
+
+// TestBotFanoutCancelledContextShortCircuitsBeforeRequest pins the other half:
+// a queued worker must fail on the pre-check instead of issuing its request.
+func TestBotFanoutCancelledContextShortCircuitsBeforeRequest(t *testing.T) {
+	results := make([]botFanoutResult, 0, 2)
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+	for i, q := range []string{"会议", "日报"} {
+		results = append(results, runOneBotQuery(ctx, nil, i, q, nil))
+	}
+	for _, r := range results {
+		if r.ErrMsg == "" {
+			t.Fatalf("a cancelled context must short-circuit before the request: %+v", r)
+		}
+	}
+	_, err := buildBotFanoutResponse([]string{"会议", "日报"}, results)
+	if err == nil {
+		t.Fatal("all queries cancelled must surface as an error")
+	}
+	if !errors.Is(err, context.Canceled) {
+		t.Fatalf("cancellation cause must be preserved: %v", err)
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem.Category != errs.CategoryNetwork || problem.Subtype != errs.SubtypeNetworkTransport {
+		t.Fatalf("problem: got %+v, want network/%s", problem, errs.SubtypeNetworkTransport)
+	}
+}
+
+func TestBotFanoutDryRunPreviewsOneRequestPerKeyword(t *testing.T) {
+	cmd := newBotSearchTestCommand()
+	setBotSearchFlag(t, cmd, "queries", "会议, 日报 ,会议")
+	setBotSearchFlag(t, cmd, "chat-ids", "oc_a")
+	setBotSearchFlag(t, cmd, "has-chatted", "true")
+	runtime := common.TestNewRuntimeContext(cmd, botSearchDefaultConfig())
+
+	raw, err := json.Marshal(ContactSearchBot.DryRun(context.Background(), runtime))
+	if err != nil {
+		t.Fatalf("marshal dry-run: %v", err)
+	}
+	var preview struct {
+		API []struct {
+			Method string                 `json:"method"`
+			URL    string                 `json:"url"`
+			Params map[string]interface{} `json:"params"`
+			Body   struct {
+				Query  string `json:"query"`
+				Filter *struct {
+					ChatIDs    []string `json:"chat_ids"`
+					HasChatter bool     `json:"has_chatter"`
+				} `json:"filter"`
+			} `json:"body"`
+		} `json:"api"`
+	}
+	if err := json.Unmarshal(raw, &preview); err != nil {
+		t.Fatalf("decode dry-run: %v\n%s", err, raw)
+	}
+
+	// Deduped, so the repeated keyword previews once — the preview has to match
+	// the requests Execute would actually issue.
+	if len(preview.API) != 2 {
+		t.Fatalf("expected one previewed request per deduped keyword, got %d: %s", len(preview.API), raw)
+	}
+	seen := make([]string, 0, len(preview.API))
+	for i, call := range preview.API {
+		if call.Method != "POST" || call.URL != botSearchURL {
+			t.Errorf("api[%d]: got %s %s", i, call.Method, call.URL)
+		}
+		if call.Params["page_size"] != float64(20) {
+			t.Errorf("api[%d] page_size: %v", i, call.Params["page_size"])
+		}
+		if _, ok := call.Params["page_token"]; ok {
+			t.Errorf("api[%d] must not preview a page_token: %v", i, call.Params)
+		}
+		// The filter rides along with every keyword, not just the first.
+		if call.Body.Filter == nil || !call.Body.Filter.HasChatter ||
+			len(call.Body.Filter.ChatIDs) != 1 || call.Body.Filter.ChatIDs[0] != "oc_a" {
+			t.Errorf("api[%d] filter: %+v", i, call.Body.Filter)
+		}
+		seen = append(seen, call.Body.Query)
+	}
+	if fmt.Sprint(seen) != fmt.Sprint([]string{"会议", "日报"}) {
+		t.Errorf("previewed keywords: got %v, want [会议 日报]", seen)
+	}
+}
+
+// The summary counts how many queries failed but never says which or why, and
+// only json carries queries[].error. Without a per-query line on stderr an agent
+// reading csv sees "1 failed" and cannot recover the keyword or the reason.
+func TestBotFanoutFailedQueryIsNamedOnStderr(t *testing.T) {
+	for _, format := range []string{"csv", "table", "pretty", "ndjson"} {
+		t.Run(format, func(t *testing.T) {
+			factory, stdout, stderr, registry := cmdutil.TestFactory(t, botSearchDefaultConfig())
+			broken := botSearchStub(botSearchURL, "")
+			broken.BodyFilter = func(b []byte) bool { return strings.Contains(string(b), `"日报"`) }
+			broken.Status = 500
+			broken.Body = map[string]interface{}{"reason": "boom"}
+			registry.Register(broken)
+			okStub := botSearchStub(botSearchURL, "")
+			okStub.Reusable = true
+			registry.Register(okStub)
+
+			if err := mountAndRun(t, ContactSearchBot, []string{
+				"+search-bot", "--queries", "会议,日报", "--format", format, "--as", "user",
+			}, factory, stdout); err != nil {
+				t.Fatalf("one failing query must not fail the batch: %v", err)
+			}
+			for _, want := range []string{"日报", "500"} {
+				if !strings.Contains(stderr.String(), want) {
+					t.Fatalf("%s: stderr must name the failed query and its reason (missing %q)\nstderr:\n%s",
+						format, want, stderr.String())
+				}
+			}
+		})
+	}
+}

shortcuts/contact/contact_search_bot_test.go

@@ -0,0 +1,724 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package contact
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+	"testing"
+
+	"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"
+	"github.com/spf13/cobra"
+)
+
+func newBotSearchTestCommand() *cobra.Command {
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("query", "", "")
+	cmd.Flags().String("chat-ids", "", "")
+	cmd.Flags().Bool("has-chatted", false, "")
+	cmd.Flags().Int("page-size", 20, "")
+	cmd.Flags().String("queries", "", "")
+	return cmd
+}
+
+func botSearchDefaultConfig() *core.CliConfig {
+	return &core.CliConfig{
+		AppID: "test", AppSecret: "test", Brand: core.BrandFeishu,
+		UserOpenId: "ou_self",
+	}
+}
+
+func setBotSearchFlag(t *testing.T, cmd *cobra.Command, name, value string) {
+	t.Helper()
+	if err := cmd.Flags().Set(name, value); err != nil {
+		t.Fatalf("set --%s=%q: %v", name, value, err)
+	}
+}
+
+func assertBotSearchValidationProblem(t *testing.T, err error, wantParam string) {
+	t.Helper()
+	if err == nil {
+		t.Fatal("expected validation error")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed problem, got %T: %v", err, err)
+	}
+	if problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("problem: got %s/%s, want %s/%s", problem.Category, problem.Subtype, errs.CategoryValidation, errs.SubtypeInvalidArgument)
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected *errs.ValidationError, got %T", err)
+	}
+	if validationErr.Param != wantParam {
+		t.Fatalf("param: got %q, want %q", validationErr.Param, wantParam)
+	}
+}
+
+// assertBotSearchValidationParams covers the errors that name several flags via
+// WithParams; those leave the single Param empty on purpose, so an agent reading
+// the envelope sees every flag that could satisfy the requirement.
+func assertBotSearchValidationParams(t *testing.T, err error, wantParams []string) {
+	t.Helper()
+	if err == nil {
+		t.Fatal("expected validation error")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("problem: %+v ok=%v", problem, ok)
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected *errs.ValidationError, got %T", err)
+	}
+	got := make([]string, 0, len(validationErr.Params))
+	for _, p := range validationErr.Params {
+		if p.Reason == "" {
+			t.Errorf("param %q has no reason; agents read it to pick a recovery", p.Name)
+		}
+		got = append(got, p.Name)
+	}
+	if fmt.Sprint(got) != fmt.Sprint(wantParams) {
+		t.Fatalf("params: got %v, want %v", got, wantParams)
+	}
+}
+
+func TestValidateBotSearchErrors(t *testing.T) {
+	chatIDs := make([]string, 101)
+	for i := range chatIDs {
+		chatIDs[i] = fmt.Sprintf("oc_%03d", i)
+	}
+
+	tests := []struct {
+		name        string
+		flags       map[string]string
+		wantParam   string
+		wantParams  []string // set instead of wantParam when the error names several flags
+		wantMessage string
+	}{
+		{
+			name:        "keyword missing",
+			wantParams:  []string{"--query", "--queries"},
+			wantMessage: "specify --query or --queries: --chat-ids and --has-chatted shape a keyword search but cannot enumerate bots on their own (the API answers a filter-only request with an empty list)",
+		},
+		{
+			name:        "query over 50 characters",
+			flags:       map[string]string{"query": strings.Repeat("中", 51)},
+			wantParam:   "--query",
+			wantMessage: "--query: length must be between 1 and 50 characters",
+		},
+		{
+			name:        "chat ids parse empty",
+			flags:       map[string]string{"query": "x", "chat-ids": " , , "},
+			wantParam:   "--chat-ids",
+			wantMessage: "--chat-ids: no valid chat_id parsed from \", ,\" (separate entries with ',')",
+		},
+		{
+			name:        "over 100 chat ids",
+			flags:       map[string]string{"query": "x", "chat-ids": strings.Join(chatIDs, ",")},
+			wantParam:   "--chat-ids",
+			wantMessage: "--chat-ids: must be at most 100 entries",
+		},
+		{
+			name:        "invalid chat id",
+			flags:       map[string]string{"query": "x", "chat-ids": "bad"},
+			wantParam:   "--chat-ids",
+			wantMessage: "invalid chat ID format, should start with 'oc_' (e.g., oc_abc123)",
+		},
+		{
+			// With a keyword present the keyword errors win, exactly as +search-user
+			// orders them; the =false check must not be hoisted above these.
+			name:        "mutually exclusive keywords outrank has chatted false",
+			flags:       map[string]string{"query": "x", "queries": "y", "has-chatted": "false"},
+			wantParams:  []string{"--query", "--queries"},
+			wantMessage: "--query and --queries are mutually exclusive",
+		},
+		{
+			name:        "query length outranks has chatted false",
+			flags:       map[string]string{"query": strings.Repeat("中", 51), "has-chatted": "false"},
+			wantParam:   "--query",
+			wantMessage: "--query: length must be between 1 and 50 characters",
+		},
+		{
+			// With no keyword at all the explicit =false is the more specific mistake,
+			// so it wins over the missing-keyword error rather than costing a second
+			// round trip. Matches which error +search-user reports first.
+			name:        "has chatted false without a keyword",
+			flags:       map[string]string{"has-chatted": "false"},
+			wantParam:   "--has-chatted",
+			wantMessage: "--has-chatted: pass the flag to enable the filter; omit it to disable filtering (=false is rejected to prevent silent wrong results)",
+		},
+		{
+			name:        "has chatted false",
+			flags:       map[string]string{"query": "x", "has-chatted": "false"},
+			wantParam:   "--has-chatted",
+			wantMessage: "--has-chatted: pass the flag to enable the filter; omit it to disable filtering (=false is rejected to prevent silent wrong results)",
+		},
+		{
+			name:        "page size below one",
+			flags:       map[string]string{"query": "x", "page-size": "0"},
+			wantParam:   "--page-size",
+			wantMessage: "--page-size: must be between 1 and 30",
+		},
+		{
+			name:        "page size over 30",
+			flags:       map[string]string{"query": "x", "page-size": "31"},
+			wantParam:   "--page-size",
+			wantMessage: "--page-size: must be between 1 and 30",
+		},
+		{
+			name:        "chat ids without a keyword",
+			flags:       map[string]string{"chat-ids": "oc_a"},
+			wantParams:  []string{"--query", "--queries"},
+			wantMessage: "specify --query or --queries: --chat-ids and --has-chatted shape a keyword search but cannot enumerate bots on their own (the API answers a filter-only request with an empty list)",
+		},
+		{
+			name:        "has chatted without a keyword",
+			flags:       map[string]string{"has-chatted": "true"},
+			wantParams:  []string{"--query", "--queries"},
+			wantMessage: "specify --query or --queries: --chat-ids and --has-chatted shape a keyword search but cannot enumerate bots on their own (the API answers a filter-only request with an empty list)",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cmd := newBotSearchTestCommand()
+			for name, value := range tt.flags {
+				setBotSearchFlag(t, cmd, name, value)
+			}
+			runtime := common.TestNewRuntimeContext(cmd, botSearchDefaultConfig())
+			err := validateBotSearch(runtime)
+			if len(tt.wantParams) > 0 {
+				assertBotSearchValidationParams(t, err, tt.wantParams)
+			} else {
+				assertBotSearchValidationProblem(t, err, tt.wantParam)
+			}
+			if err.Error() != tt.wantMessage {
+				t.Fatalf("message: got %q, want %q", err.Error(), tt.wantMessage)
+			}
+		})
+	}
+}
+
+func TestValidateBotSearchPassingCases(t *testing.T) {
+	tests := []struct {
+		name  string
+		flags map[string]string
+	}{
+		{name: "query only", flags: map[string]string{"query": "x"}},
+		{name: "query and chat ids", flags: map[string]string{"query": "x", "chat-ids": "oc_a,oc_b"}},
+		{name: "query and has chatted", flags: map[string]string{"query": "x", "has-chatted": "true"}},
+		{name: "all filters", flags: map[string]string{"query": "x", "chat-ids": "oc_a,oc_b", "has-chatted": "true"}},
+		{name: "page size upper boundary", flags: map[string]string{"query": "x", "page-size": "30"}},
+		// An explicitly blank string flag reads as "no filter", matching how
+		// +search-user treats --user-ids / --queries. Only a non-blank value that
+		// parses to zero entries is an error.
+		{name: "blank chat ids ignored", flags: map[string]string{"query": "x", "chat-ids": ""}},
+		{name: "whitespace chat ids ignored", flags: map[string]string{"query": "x", "chat-ids": "   "}},
+		// Duplicates collapse before the cap is checked, so 101 copies of one chat
+		// is one entry — matching how --user-ids is resolved for +search-user.
+		{name: "duplicate chat ids collapse under the cap", flags: map[string]string{
+			"query": "x", "chat-ids": strings.TrimSuffix(strings.Repeat("oc_a,", 101), ","),
+		}},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cmd := newBotSearchTestCommand()
+			for name, value := range tt.flags {
+				setBotSearchFlag(t, cmd, name, value)
+			}
+			runtime := common.TestNewRuntimeContext(cmd, botSearchDefaultConfig())
+			if err := validateBotSearch(runtime); err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+		})
+	}
+}
+
+func TestValidateBotSearchQueryRuneBoundary(t *testing.T) {
+	for _, tt := range []struct {
+		name      string
+		query     string
+		wantError bool
+	}{
+		{name: "50 CJK characters", query: strings.Repeat("中", 50)},
+		{name: "51 CJK characters", query: strings.Repeat("中", 51), wantError: true},
+	} {
+		t.Run(tt.name, func(t *testing.T) {
+			cmd := newBotSearchTestCommand()
+			setBotSearchFlag(t, cmd, "query", tt.query)
+			runtime := common.TestNewRuntimeContext(cmd, botSearchDefaultConfig())
+			err := validateBotSearch(runtime)
+			if tt.wantError {
+				assertBotSearchValidationProblem(t, err, "--query")
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+		})
+	}
+}
+
+func TestBuildBotSearchBody(t *testing.T) {
+	tests := []struct {
+		name     string
+		flags    map[string]string
+		wantJSON string
+	}{
+		{name: "query only", flags: map[string]string{"query": "x"}, wantJSON: `{"query":"x"}`},
+		{name: "chat ids", flags: map[string]string{"query": "x", "chat-ids": "oc_a,oc_b"}, wantJSON: `{"query":"x","filter":{"chat_ids":["oc_a","oc_b"]}}`},
+		{name: "chat id URL normalized", flags: map[string]string{"query": "x", "chat-ids": "https://example.feishu.cn/foo/oc_a,oc_b"}, wantJSON: `{"query":"x","filter":{"chat_ids":["oc_a","oc_b"]}}`},
+		{name: "has chatted", flags: map[string]string{"query": "x", "has-chatted": "true"}, wantJSON: `{"query":"x","filter":{"has_chatter":true}}`},
+		{name: "all fields", flags: map[string]string{"query": "x", "chat-ids": "oc_a,oc_b", "has-chatted": "true"}, wantJSON: `{"query":"x","filter":{"chat_ids":["oc_a","oc_b"],"has_chatter":true}}`},
+		// A blank --chat-ids must not materialize an empty filter object.
+		{name: "blank chat ids omit filter", flags: map[string]string{"query": "x", "chat-ids": "   "}, wantJSON: `{"query":"x"}`},
+		// Deduped after normalization, so a repeated id and a URL naming the same
+		// chat both collapse into one entry instead of burning the server's quota.
+		{name: "duplicate chat ids deduped", flags: map[string]string{"query": "x", "chat-ids": "oc_a,oc_a,oc_b"}, wantJSON: `{"query":"x","filter":{"chat_ids":["oc_a","oc_b"]}}`},
+		{name: "URL and bare id dedupe to one", flags: map[string]string{"query": "x", "chat-ids": "https://example.feishu.cn/foo/oc_a,oc_a"}, wantJSON: `{"query":"x","filter":{"chat_ids":["oc_a"]}}`},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			cmd := newBotSearchTestCommand()
+			for name, value := range tt.flags {
+				setBotSearchFlag(t, cmd, name, value)
+			}
+			runtime := common.TestNewRuntimeContext(cmd, botSearchDefaultConfig())
+			body, err := buildBotSearchBody(runtime)
+			if err != nil {
+				t.Fatalf("build body: %v", err)
+			}
+			raw, err := json.Marshal(body)
+			if err != nil {
+				t.Fatalf("marshal body: %v", err)
+			}
+			if string(raw) != tt.wantJSON {
+				t.Fatalf("body: got %s, want %s", raw, tt.wantJSON)
+			}
+		})
+	}
+}
+
+func TestParseBotDisplayInfo(t *testing.T) {
+	tests := []struct {
+		name            string
+		raw             string
+		wantName        string
+		wantDescription string
+		wantSegments    []string
+	}{
+		// Whole name highlighted, description on line two.
+		{name: "whole name highlighted", raw: "<h>甲乙丙</h>\n一句话简介", wantName: "甲乙丙", wantDescription: "一句话简介", wantSegments: []string{"甲乙丙"}},
+		// Two highlighted runs split by a plain character: stripping tags has to
+		// rejoin them into one name.
+		{name: "two highlighted runs", raw: "<h>甲乙</h>丁<h>丙</h>\n另一句简介", wantName: "甲乙丁丙", wantDescription: "另一句简介", wantSegments: []string{"甲乙", "丙"}},
+		// Highlight at the end plus a trailing newline: line two exists but is empty.
+		{name: "trailing newline empty description", raw: "戊己的<h>庚辛</h>\n", wantName: "戊己的庚辛", wantSegments: []string{"庚辛"}},
+		// Single highlighted character in the middle of the name.
+		{name: "mid-name highlight", raw: "壬癸<h>子</h>丑\n第二行简介", wantName: "壬癸子丑", wantDescription: "第二行简介", wantSegments: []string{"子"}},
+		{name: "no newline", raw: "寅卯", wantName: "寅卯", wantSegments: []string{}},
+		{name: "html entities", raw: "<h>Lark</h>部门成员&amp;仓库\n来自飞书&#22810;维表格", wantName: "Lark部门成员&仓库", wantDescription: "来自飞书多维表格", wantSegments: []string{"Lark"}},
+		{name: "html entity in highlight", raw: "名称<h>&amp;</h>工具", wantName: "名称&工具", wantSegments: []string{"&"}},
+		{name: "empty", raw: "", wantSegments: []string{}},
+		{name: "first non-empty line", raw: "\n\n真名", wantName: "真名", wantSegments: []string{}},
+		// A blank first line must not make the description echo the name back and
+		// swallow the real description on the line after it.
+		{name: "blank first line keeps description", raw: "\n真名\n简介", wantName: "真名", wantDescription: "简介", wantSegments: []string{}},
+		{name: "blank first line without description", raw: "\n真名", wantName: "真名", wantSegments: []string{}},
+		// A highlight with no text carries nothing; an empty match segment is junk
+		// in the envelope. Which line the name comes from is left unchanged.
+		{name: "empty highlight yields no segment", raw: "<h></h>\n简介", wantName: "简介", wantSegments: []string{}},
+		// The non-greedy pattern pairs a stray `<h>` with the next `</h>`, so the
+		// capture can carry a tag the name and description already dropped.
+		{name: "nested highlight", raw: "<h>甲<h>乙</h></h>\n简介", wantName: "甲乙", wantDescription: "简介", wantSegments: []string{"甲乙"}},
+		{name: "dangling open tag", raw: "<h><h>甲</h>\n简介", wantName: "甲", wantDescription: "简介", wantSegments: []string{"甲"}},
+		{name: "unclosed highlight", raw: "<h>甲乙\n简介", wantName: "甲乙", wantDescription: "简介", wantSegments: []string{}},
+		// A literal `<h>` in a name arrives escaped, so it must survive: tags are
+		// stripped before unescaping. Swapping that order eats the name's own text.
+		{name: "escaped angle brackets are name text", raw: "名称&lt;h&gt;工具\n简介", wantName: "名称<h>工具", wantDescription: "简介", wantSegments: []string{}},
+		{name: "escaped angle brackets inside a highlight", raw: "<h>名称&lt;h&gt;</h>工具\n简介", wantName: "名称<h>工具", wantDescription: "简介", wantSegments: []string{"名称<h>"}},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			name, description, segments := parseBotDisplayInfo(tt.raw)
+			if name != tt.wantName || description != tt.wantDescription {
+				t.Fatalf("name/description: got %q/%q, want %q/%q", name, description, tt.wantName, tt.wantDescription)
+			}
+			if segments == nil {
+				t.Fatal("match segments must be an empty slice, not nil")
+			}
+			if fmt.Sprint(segments) != fmt.Sprint(tt.wantSegments) {
+				t.Fatalf("match segments: got %v, want %v", segments, tt.wantSegments)
+			}
+		})
+	}
+}
+
+func TestProjectBotsMapsEveryField(t *testing.T) {
+	data := &botSearchAPIData{Items: []botSearchAPIItem{
+		{
+			ID:          "ou_with_chat",
+			DisplayInfo: "<h>甲乙丙</h>\n一句话简介",
+			MetaData: botSearchAPIMeta{
+				TenantID: "1", EnableJoinGroup: true, ChatID: "oc_p2p", IsAgent: true,
+			},
+		},
+		{
+			ID:          "ou_without_chat",
+			DisplayInfo: "",
+			MetaData:    botSearchAPIMeta{TenantID: "1"},
+		},
+	}}
+
+	bots := projectBots(data)
+	if len(bots) != 2 {
+		t.Fatalf("bots: got %d, want 2", len(bots))
+	}
+	first := bots[0]
+	if first.OpenID != "ou_with_chat" || first.Name != "甲乙丙" || first.Description != "一句话简介" ||
+		first.ChatID != "oc_p2p" || !first.EnableJoinGroup || !first.IsAgent || first.TenantID != "1" ||
+		fmt.Sprint(first.MatchSegments) != "[甲乙丙]" {
+		t.Fatalf("first bot mapping: %+v", first)
+	}
+	second := bots[1]
+	if second.Name != "" || second.ChatID != "" {
+		t.Fatalf("empty source fields must stay empty: %+v", second)
+	}
+	raw, err := json.Marshal(searchBotResponse{Bots: bots})
+	if err != nil {
+		t.Fatalf("marshal response: %v", err)
+	}
+	if !strings.Contains(string(raw), `"chat_id":""`) {
+		t.Fatalf("empty chat_id must still be emitted: %s", raw)
+	}
+	if !strings.Contains(string(raw), `"name":""`) {
+		t.Fatalf("empty name must not fall back to open_id: %s", raw)
+	}
+	if strings.Contains(string(raw), `"has_chatted"`) {
+		t.Fatalf("chat_id presence must not be exposed as a has_chatted signal: %s", raw)
+	}
+}
+
+func TestProjectBotsEmptySerializesAsArray(t *testing.T) {
+	bots := projectBots(&botSearchAPIData{Items: []botSearchAPIItem{}})
+	if bots == nil {
+		t.Fatal("bots must be an empty slice, not nil")
+	}
+	raw, err := json.Marshal(searchBotResponse{Bots: bots})
+	if err != nil {
+		t.Fatalf("marshal response: %v", err)
+	}
+	if string(raw) != `{"bots":[],"has_more":false}` {
+		t.Fatalf("response: got %s", raw)
+	}
+}
+
+func botSearchStub(url string, pageToken string) *httpmock.Stub {
+	return &httpmock.Stub{
+		Method: "POST",
+		URL:    url,
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"notice":     "The query is too long and has been truncated to the first 50 characters for search.",
+				"has_more":   true,
+				"page_token": pageToken,
+				"items": []interface{}{
+					map[string]interface{}{
+						"id":           "ou_bot",
+						"display_info": "<h>甲乙丙</h>\n一句话简介",
+						"meta_data": map[string]interface{}{
+							"tenant_id": "1", "enable_join_group": true, "chat_id": "oc_p2p", "is_agent": false,
+						},
+					},
+				},
+			},
+		},
+	}
+}
+
+func TestBotSearchIntegrationRequestAndResponsePassThrough(t *testing.T) {
+	factory, stdout, _, registry := cmdutil.TestFactory(t, botSearchDefaultConfig())
+	stub := botSearchStub(botSearchURL+"?page_size=25", "cursor_out")
+	registry.Register(stub)
+
+	err := mountAndRun(t, ContactSearchBot, []string{
+		"+search-bot", "--query", "甲乙", "--chat-ids", "oc_a,oc_b", "--has-chatted",
+		"--page-size", "25", "--format", "json", "--as", "user",
+	}, factory, stdout)
+	if err != nil {
+		t.Fatalf("execute: %v", err)
+	}
+
+	var requestBody map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &requestBody); err != nil {
+		t.Fatalf("request body: %v", err)
+	}
+	if requestBody["query"] != "甲乙" {
+		t.Fatalf("request query: got %v", requestBody["query"])
+	}
+	filter, ok := requestBody["filter"].(map[string]interface{})
+	if !ok || filter["has_chatter"] != true || fmt.Sprint(filter["chat_ids"]) != "[oc_a oc_b]" {
+		t.Fatalf("request filter: %#v", requestBody["filter"])
+	}
+
+	var envelope struct {
+		Data searchBotResponse `json:"data"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("response JSON: %v\n%s", err, stdout.String())
+	}
+	if envelope.Data.Notice != "The query is too long and has been truncated to the first 50 characters for search." || !envelope.Data.HasMore {
+		t.Fatalf("response pass-through: %+v", envelope.Data)
+	}
+	if len(envelope.Data.Bots) != 1 || envelope.Data.Bots[0].OpenID != "ou_bot" || envelope.Data.Bots[0].ChatID != "oc_p2p" {
+		t.Fatalf("bots: %+v", envelope.Data.Bots)
+	}
+	registry.Verify(t)
+}
+
+func TestBotSearchIntegrationNeverSurfacesPageToken(t *testing.T) {
+	factory, stdout, _, registry := cmdutil.TestFactory(t, botSearchDefaultConfig())
+	// The stub returns a token; the envelope must still not carry one, matching
+	// +search-user, which decodes page_token and drops it.
+	registry.Register(botSearchStub(botSearchURL+"?page_size=20", "cursor_out"))
+
+	err := mountAndRun(t, ContactSearchBot, []string{"+search-bot", "--query", "甲乙", "--format", "json", "--as", "user"}, factory, stdout)
+	if err != nil {
+		t.Fatalf("execute: %v", err)
+	}
+	var envelope map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("response JSON: %v", err)
+	}
+	data := envelope["data"].(map[string]interface{})
+	if _, ok := data["page_token"]; ok {
+		t.Fatalf("page_token must never be surfaced: %v", data)
+	}
+}
+
+func TestBotSearchPrettyOutputAndPaginationHint(t *testing.T) {
+	factory, stdout, stderr, registry := cmdutil.TestFactory(t, botSearchDefaultConfig())
+	registry.Register(botSearchStub(botSearchURL+"?page_size=20", "cursor_out"))
+
+	err := mountAndRun(t, ContactSearchBot, []string{"+search-bot", "--query", "甲乙", "--format", "pretty", "--as", "user"}, factory, stdout)
+	if err != nil {
+		t.Fatalf("execute: %v", err)
+	}
+	for _, column := range []string{"name", "description", "is_agent", "enable_join_group", "open_id"} {
+		if !strings.Contains(stdout.String(), column) {
+			t.Errorf("pretty output missing %q: %s", column, stdout.String())
+		}
+	}
+	for _, genericField := range []string{"bots", "has_more", "notice", "tenant_id", "chat_id", "match_segments"} {
+		if strings.Contains(stdout.String(), genericField) {
+			t.Errorf("pretty output exposed %q: %s", genericField, stdout.String())
+		}
+	}
+	// pretty stdout carries rows only, so stderr has to carry both the server
+	// notice and the pagination hint.
+	for _, want := range []string{
+		"notice: The query is too long and has been truncated to the first 50 characters for search.",
+		"hint: more matches exist; narrow with --has-chatted or a more specific --query",
+	} {
+		if !strings.Contains(stderr.String(), want) {
+			t.Fatalf("pretty stderr missing %q: %q", want, stderr.String())
+		}
+	}
+}
+
+func TestBotSearchTableUsesGenericFormatterLikeSearchUser(t *testing.T) {
+	factory, stdout, stderr, registry := cmdutil.TestFactory(t, botSearchDefaultConfig())
+	registry.Register(botSearchStub(botSearchURL+"?page_size=20", "cursor_out"))
+
+	err := mountAndRun(t, ContactSearchBot, []string{"+search-bot", "--query", "甲乙", "--format", "table", "--as", "user"}, factory, stdout)
+	if err != nil {
+		t.Fatalf("execute: %v", err)
+	}
+	for _, field := range []string{"open_id", "tenant_id", "chat_id", "match_segments"} {
+		if !strings.Contains(stdout.String(), field) {
+			t.Errorf("table output missing %q: %s", field, stdout.String())
+		}
+	}
+	// table stdout carries rows only, so stderr has to carry both the server
+	// notice and the pagination hint.
+	for _, want := range []string{
+		"notice: The query is too long and has been truncated to the first 50 characters for search.",
+		"hint: more matches exist; narrow with --has-chatted or a more specific --query",
+	} {
+		if !strings.Contains(stderr.String(), want) {
+			t.Fatalf("table stderr missing %q: %q", want, stderr.String())
+		}
+	}
+}
+
+// The old name and assertion here pinned a bug: csv and ndjson were the two
+// formats that carried neither has_more in stdout nor a hint on stderr, so a
+// machine caller read a truncated result as the whole answer. stdout stays
+// data-only; the truncation signal belongs on stderr for every format whose
+// stdout has no envelope.
+func TestBotSearchCSVAndNDJSONCarryFullFieldsAndSignalTruncation(t *testing.T) {
+	for _, format := range []string{"csv", "ndjson"} {
+		t.Run(format, func(t *testing.T) {
+			factory, stdout, stderr, registry := cmdutil.TestFactory(t, botSearchDefaultConfig())
+			registry.Register(botSearchStub(botSearchURL+"?page_size=20", "cursor_out"))
+
+			err := mountAndRun(t, ContactSearchBot, []string{"+search-bot", "--query", "甲乙", "--format", format, "--as", "user"}, factory, stdout)
+			if err != nil {
+				t.Fatalf("execute: %v", err)
+			}
+			for _, field := range []string{"open_id", "tenant_id", "chat_id", "match_segments"} {
+				if !strings.Contains(stdout.String(), field) {
+					t.Errorf("%s output missing %q: %s", format, field, stdout.String())
+				}
+			}
+			// stdout must stay data-only, so both the notice and the truncation
+			// signal have to arrive on stderr.
+			for _, want := range []string{"notice: The query is too long", "hint: more matches exist"} {
+				if !strings.Contains(stderr.String(), want) {
+					t.Fatalf("%s dropped %q from stderr: %q", format, want, stderr.String())
+				}
+			}
+			if strings.Contains(stdout.String(), "more matches exist") {
+				t.Fatalf("%s stdout must stay data-only: %s", format, stdout.String())
+			}
+		})
+	}
+}
+
+func TestBotSearchPrettyEmptyResult(t *testing.T) {
+	factory, stdout, _, registry := cmdutil.TestFactory(t, botSearchDefaultConfig())
+	registry.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    botSearchURL + "?page_size=20",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{"items": []interface{}{}, "has_more": false},
+		},
+	})
+
+	err := mountAndRun(t, ContactSearchBot, []string{"+search-bot", "--query", "none", "--format", "pretty", "--as", "user"}, factory, stdout)
+	if err != nil {
+		t.Fatalf("execute: %v", err)
+	}
+	if !strings.Contains(stdout.String(), "No bots found.") {
+		t.Fatalf("pretty output: %q", stdout.String())
+	}
+}
+
+func TestBotSearchDryRunMirrorsRequest(t *testing.T) {
+	factory, stdout, _, _ := cmdutil.TestFactory(t, botSearchDefaultConfig())
+	err := mountAndRun(t, ContactSearchBot, []string{
+		"+search-bot", "--query", "甲乙", "--chat-ids", "oc_a", "--has-chatted",
+		"--page-size", "25", "--dry-run", "--as", "user",
+	}, factory, stdout)
+	if err != nil {
+		t.Fatalf("execute: %v", err)
+	}
+	var envelope struct {
+		Data struct {
+			API []struct {
+				Method string                 `json:"method"`
+				URL    string                 `json:"url"`
+				Params map[string]interface{} `json:"params"`
+				Body   botSearchAPIRequest    `json:"body"`
+			} `json:"api"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("dry-run JSON: %v", err)
+	}
+	if len(envelope.Data.API) != 1 {
+		t.Fatalf("api calls: got %d, want 1", len(envelope.Data.API))
+	}
+	call := envelope.Data.API[0]
+	if call.Method != "POST" || call.URL != botSearchURL || call.Params["page_size"] != float64(25) {
+		t.Fatalf("dry-run call: %+v", call)
+	}
+	if call.Body.Query != "甲乙" || call.Body.Filter == nil || fmt.Sprint(call.Body.Filter.ChatIDs) != "[oc_a]" || !call.Body.Filter.HasChatter {
+		t.Fatalf("dry-run body: %+v", call.Body)
+	}
+}
+
+func TestDecodeBotSearchAPIDataMarshalFailureTyped(t *testing.T) {
+	_, err := decodeBotSearchAPIData(map[string]interface{}{"bad": func() {}})
+	if err == nil {
+		t.Fatal("expected marshal failure")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok || problem.Category != errs.CategoryInternal || problem.Subtype != errs.SubtypeInvalidResponse {
+		t.Fatalf("problem: %+v, ok=%v", problem, ok)
+	}
+}
+
+// Only the json envelope carries data.notice. If the other formats dropped it
+// silently, a caller would read a truncated or incomplete result as a complete
+// one, so every non-json format has to surface it on stderr instead.
+func TestBotSearchNoticeReachesCallerInEveryFormat(t *testing.T) {
+	const notice = "The query is too long and has been truncated to the first 50 characters for search."
+	for _, format := range []string{"json", "ndjson", "csv", "table", "pretty"} {
+		t.Run(format, func(t *testing.T) {
+			factory, stdout, stderr, registry := cmdutil.TestFactory(t, botSearchDefaultConfig())
+			registry.Register(botSearchStub(botSearchURL+"?page_size=20", ""))
+			if err := mountAndRun(t, ContactSearchBot, []string{
+				"+search-bot", "--query", "甲乙", "--format", format, "--as", "user",
+			}, factory, stdout); err != nil {
+				t.Fatalf("execute: %v", err)
+			}
+			if strings.Contains(stdout.String(), notice) {
+				if format != "json" {
+					t.Fatalf("%s should not carry the notice in stdout: %s", format, stdout.String())
+				}
+				return
+			}
+			if !strings.Contains(stderr.String(), notice) {
+				t.Fatalf("%s dropped the notice entirely\nstdout:\n%s\nstderr:\n%s",
+					format, stdout.String(), stderr.String())
+			}
+			// stdout stays pipe-clean: the notice must not be mixed into the rows.
+			if format == "csv" && strings.Contains(stdout.String(), "notice") {
+				t.Fatalf("csv stdout must stay data-only: %s", stdout.String())
+			}
+		})
+	}
+}
+
+// has_more is the server saying "this is not the whole answer". Only the json
+// envelope carries it, so every other format has to say so on stderr or a machine
+// caller silently treats a truncated result as complete.
+func TestBotSearchTruncationReachesCallerInEveryFormat(t *testing.T) {
+	for _, format := range []string{"json", "ndjson", "csv", "table", "pretty"} {
+		t.Run(format, func(t *testing.T) {
+			factory, stdout, stderr, registry := cmdutil.TestFactory(t, botSearchDefaultConfig())
+			registry.Register(botSearchStub(botSearchURL+"?page_size=20", "cursor"))
+			if err := mountAndRun(t, ContactSearchBot, []string{
+				"+search-bot", "--query", "甲乙", "--format", format, "--as", "user",
+			}, factory, stdout); err != nil {
+				t.Fatalf("execute: %v", err)
+			}
+			if format == "json" {
+				if !strings.Contains(stdout.String(), `"has_more": true`) {
+					t.Fatalf("json must carry has_more in the envelope: %s", stdout.String())
+				}
+				return
+			}
+			if !strings.Contains(stderr.String(), "more matches exist") {
+				t.Fatalf("%s left the caller unable to learn the result was truncated\nstdout:\n%s\nstderr:\n%s",
+					format, stdout.String(), stderr.String())
+			}
+		})
+	}
+}

shortcuts/contact/contact_search_user_test.go

@@ -550,6 +550,13 @@ func TestDecodeSearchUserAPIData_MarshalFailureTyped(t *testing.T) {
 // mountAndRun mounts the shortcut under a parent cobra command and runs it
 // with the given args. Mirrors the pattern used in other shortcut packages.
 func mountAndRun(t *testing.T, s common.Shortcut, args []string, f *cmdutil.Factory, stdout *bytes.Buffer) error {
+	t.Helper()
+	return mountAndRunContext(t, context.Background(), s, args, f, stdout)
+}
+
+// mountAndRunContext is mountAndRun with a caller-supplied context, so a test
+// can cancel the run the shortcut actually sees (runShortcut reads cmd.Context).
+func mountAndRunContext(t *testing.T, ctx context.Context, s common.Shortcut, args []string, f *cmdutil.Factory, stdout *bytes.Buffer) error {
 	t.Helper()
 	parent := &cobra.Command{Use: "contact"}
 	s.Mount(parent, f)
@@ -559,7 +566,7 @@ func mountAndRun(t *testing.T, s common.Shortcut, args []string, f *cmdutil.Fact
 	if stdout != nil {
 		stdout.Reset()
 	}
-	return parent.Execute()
+	return parent.ExecuteContext(ctx)
 }
 
 // searchUserStub returns a representative user search response with a notice.

shortcuts/contact/shortcuts.go

@@ -9,6 +9,7 @@ import "github.com/larksuite/cli/shortcuts/common"
 func Shortcuts() []common.Shortcut {
 	return []common.Shortcut{
 		ContactSearchUser,
+		ContactSearchBot,
 		ContactGetUser,
 	}
 }

shortcuts/doc/docs_script.go

@@ -1,418 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package doc
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"io/fs"
-	"path/filepath"
-	"strings"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/extension/fileio"
-	"github.com/larksuite/cli/internal/charcheck"
-	"github.com/larksuite/cli/shortcuts/common"
-	"github.com/larksuite/cli/shortcuts/doc/internal/docxparse"
-)
-
-const (
-	docsScriptParse         = "parse"
-	docsScriptMarkdownToXML = "markdown-to-xml"
-	docsScriptCreateTempXML = "create-temp-xml"
-	docsScriptTempDirSuffix = "_*_folder"
-)
-
-var DocsScript = common.Shortcut{
-	Service:     "docs",
-	Command:     "+script",
-	Description: "Create a unique temporary XML file, parse and profile local or online documents, or convert Markdown to LarkOpenCLI XML",
-	Risk:        "read",
-	AuthTypes:   []string{"user", "bot"},
-	Scopes:      []string{},
-	ConditionalScopes: []string{
-		"docx:document:readonly",
-	},
-	Flags: []common.Flag{
-		{
-			Name:     "command",
-			Desc:     "local document operation",
-			Required: true,
-			Enum:     []string{docsScriptParse, docsScriptMarkdownToXML, docsScriptCreateTempXML},
-		},
-		{
-			Name:  "content",
-			Desc:  "local content for parse or markdown-to-xml; use @relative-file or - for stdin; mutually exclusive with --doc",
-			Input: []string{common.File, common.Stdin},
-		},
-		{
-			Name: "doc",
-			Desc: "online document URL or token for --command parse; mutually exclusive with --content",
-		},
-		{
-			Name: "output",
-			Desc: "local XML output path for markdown-to-xml; omit to return XML in data.xml",
-		},
-		{
-			Name: "file-name",
-			Desc: "portable base name without .xml; create-temp-xml writes <name>_<random>_folder/<name>.xml",
-		},
-		{
-			Name: "overwrite",
-			Type: "bool",
-			Desc: "overwrite an existing --output file",
-		},
-	},
-	Tips: []string{
-		"create-temp-xml atomically creates <file-name>_<random>_folder/<file-name>.xml in the current directory",
-		"parse accepts local --content or an online --doc URL/token and returns only the text and block profile",
-		"markdown-to-xml converts Markdown to LarkOpenCLI XML",
-		"use --output to save converted XML directly and keep stdout compact",
-	},
-	PostMount: installDocsScriptHelp,
-	Validate:  validateDocsScript,
-	DryRun:    dryRunDocsScript,
-	Execute:   executeDocsScript,
-}
-
-type docsScriptParseResult struct {
-	Profile docsScriptPublicProfile `json:"profile"`
-}
-
-// docsScriptPublicProfile is the stable shortcut response. The parser keeps
-// the more detailed breakdown internally so it can be exposed later without
-// changing the counting implementation.
-type docsScriptPublicProfile struct {
-	WordCount  int                    `json:"word_count"`
-	CharCount  int                    `json:"char_count"`
-	BlockCount int                    `json:"block_count"`
-	Blocks     []docxparse.BlockShare `json:"blocks"`
-}
-
-type docsScriptMarkdownResult struct {
-	XML string `json:"xml"`
-}
-
-type docsScriptMarkdownFileResult struct {
-	SavedPath string `json:"saved_path"`
-	SizeBytes int64  `json:"size_bytes"`
-}
-
-type docsScriptTempXMLResult struct {
-	Path string `json:"path"`
-}
-
-func installDocsScriptHelp(cmd *cobra.Command) {
-	installDocsShortcutHelp("+script")(cmd)
-	cmd.Example = `  lark-cli docs +script --command create-temp-xml --file-name "draft"
-  lark-cli docs +script --command parse --content "@draft.xml"
-  lark-cli docs +script --command parse --content "@draft.md"
-  lark-cli docs +script --command parse --doc "https://example.larksuite.com/docx/doxcn..."
-  lark-cli docs +script --command markdown-to-xml --content "@draft.md" --output "draft.xml"`
-}
-
-func validateDocsScript(_ context.Context, runtime *common.RuntimeContext) error {
-	content := strings.TrimSpace(runtime.Str("content"))
-	doc := strings.TrimSpace(runtime.Str("doc"))
-	outputPath := strings.TrimSpace(runtime.Str("output"))
-	fileName := strings.TrimSpace(runtime.Str("file-name"))
-	if runtime.Str("command") == docsScriptCreateTempXML {
-		switch {
-		case content != "":
-			return errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"--content is not supported with --command create-temp-xml").WithParam("--content")
-		case doc != "":
-			return errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"--doc is not supported with --command create-temp-xml").WithParam("--doc")
-		case outputPath != "":
-			return errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"--output is not supported with --command create-temp-xml").WithParam("--output")
-		case runtime.Bool("overwrite"):
-			return errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"--overwrite is not supported with --command create-temp-xml").WithParam("--overwrite")
-		case fileName == "":
-			return errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"--file-name is required with --command create-temp-xml").WithParam("--file-name")
-		case runtime.Str("file-name") != fileName:
-			return errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"--file-name must not start or end with whitespace").WithParam("--file-name")
-		default:
-			return validateDocsScriptTempXMLFileName(fileName)
-		}
-	}
-	if fileName != "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"--file-name is only supported with --command create-temp-xml").WithParam("--file-name")
-	}
-	if content == "" && doc == "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "one of --content or --doc is required").WithParams(
-			errs.InvalidParam{Name: "--content", Reason: "provide local document content"},
-			errs.InvalidParam{Name: "--doc", Reason: "provide an online document URL or token"},
-		)
-	}
-	if content != "" && doc != "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--content and --doc are mutually exclusive").WithParams(
-			errs.InvalidParam{Name: "--content", Reason: "mutually exclusive with --doc"},
-			errs.InvalidParam{Name: "--doc", Reason: "mutually exclusive with --content"},
-		)
-	}
-	if doc != "" {
-		if runtime.Str("command") != docsScriptParse {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"--doc is only supported with --command parse").WithParam("--doc")
-		}
-		if _, err := parseDocumentRef(doc); err != nil {
-			return err
-		}
-		if err := runtime.EnsureScopes([]string{"docx:document:readonly"}); err != nil {
-			return err
-		}
-	}
-	if outputPath == "" {
-		if runtime.Bool("overwrite") {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--overwrite requires --output").WithParam("--overwrite")
-		}
-		return nil
-	}
-	if runtime.Str("command") != docsScriptMarkdownToXML {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"--output is only supported with --command markdown-to-xml").WithParam("--output")
-	}
-	if _, err := runtime.ResolveSavePath(outputPath); err != nil {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe output path: %s", err).
-			WithParam("--output").
-			WithCause(err)
-	}
-	return nil
-}
-
-func dryRunDocsScript(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-	if runtime.Str("command") == docsScriptCreateTempXML {
-		fileName := strings.TrimSpace(runtime.Str("file-name"))
-		return common.NewDryRunAPI().
-			Desc("Create a random directory and an empty named XML file inside it; no API call is made").
-			Set("command", docsScriptCreateTempXML).
-			Set("directory_pattern", docsScriptTempDirectoryPattern(fileName)).
-			Set("file_name", fileName).
-			Set("xml_file_name", docsScriptXMLFileName(fileName)).
-			Set("creates_file", false).
-			Set("network", false)
-	}
-	if doc := strings.TrimSpace(runtime.Str("doc")); doc != "" {
-		ref, _ := parseDocumentRef(doc)
-		return common.NewDryRunAPI().
-			POST("/open-apis/docs_ai/v1/documents/:document_id/fetch").
-			Desc("OpenAPI: fetch document for parsing and profiling").
-			Body(docsScriptFetchBody(runtime)).
-			Set("command", runtime.Str("command")).
-			Set("document_id", ref.Token).
-			Set("network", true)
-	}
-	dry := common.NewDryRunAPI().
-		Desc("Local LarkOpenCLI document parsing or conversion; no API call is made").
-		Set("command", runtime.Str("command")).
-		Set("input_bytes", len(runtime.Str("content"))).
-		Set("network", false)
-	if outputPath := strings.TrimSpace(runtime.Str("output")); outputPath != "" {
-		dry.Set("output", outputPath).Set("overwrite", runtime.Bool("overwrite"))
-	}
-	return dry
-}
-
-func executeDocsScript(_ context.Context, runtime *common.RuntimeContext) error {
-	command := runtime.Str("command")
-	content := runtime.Str("content")
-	switch command {
-	case docsScriptCreateTempXML:
-		return createDocsScriptTempXML(runtime)
-	case docsScriptParse:
-		inputParam := "--content"
-		inputLabel := "--content"
-		if strings.TrimSpace(runtime.Str("doc")) != "" {
-			var err error
-			content, err = fetchDocsScriptContent(runtime)
-			if err != nil {
-				return err
-			}
-			inputParam = "--doc"
-			inputLabel = "fetched document content"
-		}
-		profile, err := docxparse.ParseAuto(content)
-		if err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"could not parse %s as LarkOpenCLI XML or Markdown: %s", inputLabel, err).
-				WithParam(inputParam).
-				WithCause(err)
-		}
-		runtime.OutFormatRaw(docsScriptParseResult{Profile: docsScriptPublicProfile{
-			WordCount:  profile.WordCount,
-			CharCount:  profile.CharCount,
-			BlockCount: profile.BlockCount,
-			Blocks:     profile.Blocks,
-		}}, nil, nil)
-		return nil
-	case docsScriptMarkdownToXML:
-		xml, err := docxparse.MarkdownToXML(content)
-		if err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"could not convert --content from Markdown to LarkOpenCLI XML: %s", err).
-				WithParam("--content").
-				WithCause(err)
-		}
-		if outputPath := strings.TrimSpace(runtime.Str("output")); outputPath != "" {
-			return saveDocsScriptXML(runtime, outputPath, xml)
-		}
-		runtime.OutFormatRaw(docsScriptMarkdownResult{XML: xml}, nil, nil)
-		return nil
-	default:
-		return errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"unsupported --command %q", command).
-			WithParam("--command")
-	}
-}
-
-func createDocsScriptTempXML(runtime *common.RuntimeContext) error {
-	creator, ok := runtime.FileIO().(fileio.TempDirFileCreator)
-	if !ok {
-		return errs.NewValidationError(errs.SubtypeFailedPrecondition,
-			"the active file I/O provider does not support temporary file creation").
-			WithHint("run this command with the local file I/O provider")
-	}
-	fileName := strings.TrimSpace(runtime.Str("file-name"))
-	path, err := creator.CreateTempDirFile(docsScriptTempDirectoryPattern(fileName), docsScriptXMLFileName(fileName))
-	if err != nil {
-		return common.WrapSaveErrorTyped(err)
-	}
-	if _, err := runtime.ResolveSavePath(path); err != nil {
-		return errs.NewInternalError(errs.SubtypeFileIO,
-			"resolve temporary XML path %s: %s", path, err).
-			WithCause(err)
-	}
-	runtime.Out(docsScriptTempXMLResult{
-		Path: path,
-	}, nil)
-	return nil
-}
-
-func validateDocsScriptTempXMLFileName(fileName string) error {
-	if fileName != filepath.Base(fileName) || strings.ContainsAny(fileName, "<>:\"/\\|?*\t\r\n") {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"--file-name must be a portable file name without path separators or reserved characters").WithParam("--file-name")
-	}
-	if err := charcheck.RejectControlChars(fileName, "--file-name"); err != nil {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).
-			WithParam("--file-name").
-			WithCause(err)
-	}
-	if strings.HasSuffix(fileName, ".") || strings.HasSuffix(fileName, " ") {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"--file-name must not end with a dot or space").WithParam("--file-name")
-	}
-	if strings.EqualFold(filepath.Ext(fileName), ".xml") {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"--file-name must omit the .xml extension").WithParam("--file-name")
-	}
-	base := strings.ToUpper(strings.SplitN(fileName, ".", 2)[0])
-	if isWindowsReservedFileName(base) {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"--file-name uses a Windows-reserved device name").WithParam("--file-name")
-	}
-	return nil
-}
-
-func docsScriptTempDirectoryPattern(fileName string) string {
-	return fileName + docsScriptTempDirSuffix
-}
-
-func docsScriptXMLFileName(fileName string) string {
-	return fileName + ".xml"
-}
-
-func isWindowsReservedFileName(base string) bool {
-	switch base {
-	case "CON", "PRN", "AUX", "NUL":
-		return true
-	}
-	if len(base) == 4 && (strings.HasPrefix(base, "COM") || strings.HasPrefix(base, "LPT")) {
-		return base[3] >= '1' && base[3] <= '9'
-	}
-	return false
-}
-
-func docsScriptFetchBody(runtime *common.RuntimeContext) map[string]interface{} {
-	body := map[string]interface{}{
-		"format":      "xml",
-		"extra_param": docsFetchExtraParam,
-		"export_option": map[string]interface{}{
-			"export_block_id":        false,
-			"export_style_attrs":     false,
-			"export_cite_extra_data": false,
-		},
-	}
-	if lang := resolveFetchLang(runtime); lang != "" {
-		body["lang"] = lang
-	}
-	return body
-}
-
-func fetchDocsScriptContent(runtime *common.RuntimeContext) (string, error) {
-	ref, _ := parseDocumentRef(runtime.Str("doc"))
-	apiPath := fmt.Sprintf("/open-apis/docs_ai/v1/documents/%s/fetch", ref.Token)
-	data, err := doDocAPI(runtime, "POST", apiPath, docsScriptFetchBody(runtime))
-	if err != nil {
-		return "", err
-	}
-	document, ok := data["document"].(map[string]interface{})
-	if !ok || document == nil {
-		return "", errs.NewInternalError(errs.SubtypeUnknown,
-			"document fetch response for --doc is missing document")
-	}
-	content, ok := document["content"].(string)
-	if !ok {
-		return "", errs.NewInternalError(errs.SubtypeUnknown,
-			"document fetch response for --doc is missing document.content")
-	}
-	return content, nil
-}
-
-func saveDocsScriptXML(runtime *common.RuntimeContext, outputPath, xml string) error {
-	if !runtime.Bool("overwrite") {
-		if _, err := runtime.FileIO().Stat(outputPath); err == nil {
-			return errs.NewValidationError(errs.SubtypeFailedPrecondition,
-				"output file already exists: %s (use --overwrite to replace)", outputPath).
-				WithParam("--output")
-		} else if !errors.Is(err, fs.ErrNotExist) {
-			if errors.Is(err, fileio.ErrPathValidation) {
-				return errs.NewValidationError(errs.SubtypeInvalidArgument, "unsafe output path: %s", err).
-					WithParam("--output").
-					WithCause(err)
-			}
-			return errs.NewInternalError(errs.SubtypeFileIO,
-				"cannot access output path %s: %s", outputPath, err).
-				WithCause(err)
-		}
-	}
-
-	result, err := runtime.FileIO().Save(outputPath, fileio.SaveOptions{
-		ContentType:   "application/xml",
-		ContentLength: int64(len(xml)),
-	}, strings.NewReader(xml))
-	if err != nil {
-		return common.WrapSaveErrorTyped(err)
-	}
-	savedPath, err := runtime.ResolveSavePath(outputPath)
-	if err != nil {
-		return errs.NewInternalError(errs.SubtypeFileIO,
-			"resolve saved XML path %s: %s", outputPath, err).
-			WithCause(err)
-	}
-	runtime.Out(docsScriptMarkdownFileResult{
-		SavedPath: savedPath,
-		SizeBytes: result.Size(),
-	}, nil)
-	return nil
-}

shortcuts/doc/docs_script_test.go

@@ -1,660 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package doc
-
-import (
-	"bytes"
-	"encoding/json"
-	"errors"
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/shortcuts/doc/internal/docxparse"
-)
-
-func TestDocsScriptParsesAndProfilesXML(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-script-test"))
-	source := `<title>标题</title><p>一个苹果是 an apple。</p>`
-
-	err := mountAndRunDocs(t, DocsScript, []string{
-		"+script",
-		"--command", docsScriptParse,
-		"--content", source,
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("execute docs +script: %v", err)
-	}
-
-	var envelope struct {
-		OK   bool                       `json:"ok"`
-		Data map[string]json.RawMessage `json:"data"`
-	}
-	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
-		t.Fatalf("decode stdout: %v\n%s", err, stdout)
-	}
-	if !envelope.OK {
-		t.Fatalf("ok = false: %s", stdout)
-	}
-	if len(envelope.Data) != 1 || envelope.Data["profile"] == nil {
-		t.Fatalf("data = %+v, want only profile", envelope.Data)
-	}
-	var profile docsScriptPublicProfile
-	if err := json.Unmarshal(envelope.Data["profile"], &profile); err != nil {
-		t.Fatalf("decode profile: %v", err)
-	}
-	var profileFields map[string]json.RawMessage
-	if err := json.Unmarshal(envelope.Data["profile"], &profileFields); err != nil {
-		t.Fatalf("decode profile fields: %v", err)
-	}
-	if len(profileFields) != 4 || profileFields["breakdown"] != nil {
-		t.Fatalf("profile fields = %+v, want breakdown hidden", profileFields)
-	}
-	if profile.WordCount != 10 || profile.CharCount != 15 || profile.BlockCount != 2 {
-		t.Fatalf("profile = %+v", profile)
-	}
-	if got := blockCount(profile.Blocks, "title"); got != 1 {
-		t.Fatalf("title count = %d, want 1", got)
-	}
-	if got := blockCount(profile.Blocks, "p"); got != 1 {
-		t.Fatalf("p count = %d, want 1", got)
-	}
-}
-
-func TestDocsScriptParseAutoDetectsMarkdown(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-script-auto-markdown"))
-
-	err := mountAndRunDocs(t, DocsScript, []string{
-		"+script",
-		"--command", docsScriptParse,
-		"--content", "# 标题\n\n- item",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("execute docs +script: %v", err)
-	}
-
-	var envelope struct {
-		Data docsScriptParseResult `json:"data"`
-	}
-	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
-		t.Fatalf("decode stdout: %v\n%s", err, stdout)
-	}
-	if envelope.Data.Profile.BlockCount != 3 {
-		t.Fatalf("profile = %+v, want 3 blocks", envelope.Data.Profile)
-	}
-}
-
-func TestDocsScriptParsesOnlineDocumentFromToken(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, stdout, _, reg := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-script-online-token"))
-	registerDocsAIStub(reg, "POST", "/open-apis/docs_ai/v1/documents/doxcnScriptToken/fetch", map[string]interface{}{
-		"document": map[string]interface{}{
-			"document_id": "doxcnScriptToken",
-			"content":     `<title>在线文档</title><p>Hello world</p>`,
-		},
-	})
-
-	err := mountAndRunDocs(t, DocsScript, []string{
-		"+script",
-		"--command", docsScriptParse,
-		"--doc", "doxcnScriptToken",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("execute docs +script with token: %v", err)
-	}
-
-	var envelope struct {
-		Data docsScriptParseResult `json:"data"`
-	}
-	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
-		t.Fatalf("decode stdout: %v\n%s", err, stdout)
-	}
-	if envelope.Data.Profile.BlockCount != 2 {
-		t.Fatalf("profile = %+v, want 2 blocks", envelope.Data.Profile)
-	}
-	if got := blockCount(envelope.Data.Profile.Blocks, "title"); got != 1 {
-		t.Fatalf("title count = %d, want 1", got)
-	}
-	if got := blockCount(envelope.Data.Profile.Blocks, "p"); got != 1 {
-		t.Fatalf("p count = %d, want 1", got)
-	}
-}
-
-func TestDocsScriptParsesOnlineDocumentFromURL(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, stdout, _, reg := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-script-online-url"))
-	stub := registerDocsAIStub(reg, "POST", "/open-apis/docs_ai/v1/documents/wikcnScriptURL/fetch", map[string]interface{}{
-		"document": map[string]interface{}{
-			"document_id": "doxcnResolvedScriptURL",
-			"content":     `<p>从 Wiki URL 读取</p>`,
-		},
-	})
-
-	err := mountAndRunDocs(t, DocsScript, []string{
-		"+script",
-		"--command", docsScriptParse,
-		"--doc", "https://example.larksuite.com/wiki/wikcnScriptURL",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("execute docs +script with URL: %v", err)
-	}
-	if stub.CapturedBody == nil {
-		t.Fatal("online parse did not call the document fetch API")
-	}
-
-	var envelope struct {
-		Data docsScriptParseResult `json:"data"`
-	}
-	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
-		t.Fatalf("decode stdout: %v\n%s", err, stdout)
-	}
-	if envelope.Data.Profile.BlockCount != 1 || blockCount(envelope.Data.Profile.Blocks, "p") != 1 {
-		t.Fatalf("profile = %+v, want one paragraph", envelope.Data.Profile)
-	}
-}
-
-func TestDocsScriptRejectsContentAndDocTogether(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-script-input-conflict"))
-	err := mountAndRunDocs(t, DocsScript, []string{
-		"+script",
-		"--command", docsScriptParse,
-		"--content", `<p>local</p>`,
-		"--doc", "doxcnScriptConflict",
-		"--as", "bot",
-	}, f, nil)
-	assertValidationContract(t, err, errs.SubtypeInvalidArgument, "", "--content", "--doc")
-}
-
-func TestDocsScriptRejectsDocForMarkdownConversion(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-script-doc-convert"))
-	err := mountAndRunDocs(t, DocsScript, []string{
-		"+script",
-		"--command", docsScriptMarkdownToXML,
-		"--doc", "doxcnScriptConvert",
-		"--as", "bot",
-	}, f, nil)
-	assertValidationContract(t, err, errs.SubtypeInvalidArgument, "--doc")
-}
-
-func TestDocsScriptConvertsMarkdownFromStdin(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-script-markdown"))
-	f.IOStreams.In = bytes.NewBufferString("# 标题\n\n- item")
-
-	err := mountAndRunDocs(t, DocsScript, []string{
-		"+script",
-		"--command", docsScriptMarkdownToXML,
-		"--content", "-",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("execute docs +script: %v", err)
-	}
-	if !strings.Contains(stdout.String(), `<h1>标题</h1><ul><li>item</li></ul>`) {
-		t.Fatalf("stdout missing converted XML: %s", stdout)
-	}
-	var envelope struct {
-		Data map[string]json.RawMessage `json:"data"`
-	}
-	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
-		t.Fatalf("decode stdout: %v\n%s", err, stdout)
-	}
-	if len(envelope.Data) != 1 || envelope.Data["xml"] == nil {
-		t.Fatalf("data = %+v, want only xml", envelope.Data)
-	}
-}
-
-func TestDocsScriptConvertsMarkdownToOutputFile(t *testing.T) {
-	workDir := t.TempDir()
-	withDocsWorkingDir(t, workDir)
-	f, stdout, _, _ := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-script-output"))
-	wantXML := `<h1>标题</h1><ul><li>item</li></ul>`
-
-	err := mountAndRunDocs(t, DocsScript, []string{
-		"+script",
-		"--command", docsScriptMarkdownToXML,
-		"--content", "# 标题\n\n- item",
-		"--output", "draft.xml",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("execute docs +script: %v", err)
-	}
-	gotXML, err := os.ReadFile("draft.xml")
-	if err != nil {
-		t.Fatalf("read output XML: %v", err)
-	}
-	if string(gotXML) != wantXML {
-		t.Fatalf("output XML = %q, want %q", gotXML, wantXML)
-	}
-
-	var envelope struct {
-		Data struct {
-			SavedPath string          `json:"saved_path"`
-			SizeBytes int64           `json:"size_bytes"`
-			XML       json.RawMessage `json:"xml"`
-		} `json:"data"`
-	}
-	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
-		t.Fatalf("decode stdout: %v\n%s", err, stdout)
-	}
-	if envelope.Data.SavedPath != filepath.Join(workDir, "draft.xml") {
-		t.Fatalf("saved_path = %q, want %q", envelope.Data.SavedPath, filepath.Join(workDir, "draft.xml"))
-	}
-	if envelope.Data.SizeBytes != int64(len(wantXML)) {
-		t.Fatalf("size_bytes = %d, want %d", envelope.Data.SizeBytes, len(wantXML))
-	}
-	if envelope.Data.XML != nil {
-		t.Fatalf("data.xml should be omitted when --output is used: %s", stdout)
-	}
-}
-
-func TestDocsScriptCreatesUniqueTempXMLFiles(t *testing.T) {
-	workDir := t.TempDir()
-	withDocsWorkingDir(t, workDir)
-	f, stdout, _, _ := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-script-temp-xml"))
-
-	create := func() docsScriptTempXMLResult {
-		t.Helper()
-		stdout.Reset()
-		err := mountAndRunDocs(t, DocsScript, []string{
-			"+script",
-			"--command", docsScriptCreateTempXML,
-			"--file-name", "川西",
-			"--as", "bot",
-		}, f, stdout)
-		if err != nil {
-			t.Fatalf("execute docs +script: %v", err)
-		}
-		var envelope struct {
-			Data docsScriptTempXMLResult `json:"data"`
-		}
-		if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
-			t.Fatalf("decode stdout: %v\n%s", err, stdout)
-		}
-		return envelope.Data
-	}
-
-	first := create()
-	second := create()
-	if first.Path == second.Path {
-		t.Fatalf("temporary paths are identical: %q", first.Path)
-	}
-	for _, got := range []docsScriptTempXMLResult{first, second} {
-		directory := filepath.Dir(got.Path)
-		if filepath.Base(got.Path) != "川西.xml" || filepath.Base(directory) != directory ||
-			!strings.HasPrefix(directory, "川西_") || !strings.HasSuffix(directory, "_folder") {
-			t.Fatalf("path = %q, want 川西_<random>_folder/川西.xml", got.Path)
-		}
-		info, err := os.Stat(got.Path)
-		if err != nil {
-			t.Fatalf("stat temporary XML %q: %v", got.Path, err)
-		}
-		if info.Size() != 0 {
-			t.Fatalf("temporary XML %q size = %d, want 0", got.Path, info.Size())
-		}
-	}
-}
-
-func TestDocsScriptCreateTempXMLRejectsOtherFlags(t *testing.T) {
-	tests := []struct {
-		name  string
-		args  []string
-		param string
-	}{
-		{name: "content", args: []string{"--content", "<p>text</p>"}, param: "--content"},
-		{name: "doc", args: []string{"--doc", "doxcnScriptTemp"}, param: "--doc"},
-		{name: "output", args: []string{"--output", "draft.xml"}, param: "--output"},
-		{name: "overwrite", args: []string{"--overwrite"}, param: "--overwrite"},
-	}
-	for _, test := range tests {
-		t.Run(test.name, func(t *testing.T) {
-			f, _, _, _ := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-script-temp-xml-flags"))
-			args := []string{"+script", "--command", docsScriptCreateTempXML, "--file-name", "川西", "--as", "bot"}
-			args = append(args, test.args...)
-			err := mountAndRunDocs(t, DocsScript, args, f, nil)
-			if err == nil {
-				t.Fatalf("expected %s validation error", test.param)
-			}
-			problem, ok := errs.ProblemOf(err)
-			var validationErr *errs.ValidationError
-			if !ok || problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument ||
-				!errors.As(err, &validationErr) || validationErr.Param != test.param {
-				t.Fatalf("problem = %+v, validation = %+v, ok=%v", problem, validationErr, ok)
-			}
-		})
-	}
-}
-
-func TestDocsScriptCreateTempXMLValidatesFileName(t *testing.T) {
-	tests := []struct {
-		name     string
-		fileName string
-	}{
-		{name: "missing"},
-		{name: "path", fileName: "folder/川西"},
-		{name: "windows path", fileName: `folder\川西`},
-		{name: "reserved character", fileName: "川西:一"},
-		{name: "xml extension included", fileName: "川西.xml"},
-		{name: "windows device", fileName: "CON"},
-		{name: "surrounding whitespace", fileName: " 川西"},
-		{name: "dangerous unicode", fileName: "川\u200b西"},
-	}
-	for _, test := range tests {
-		t.Run(test.name, func(t *testing.T) {
-			f, _, _, _ := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-script-temp-xml-file-name"))
-			args := []string{"+script", "--command", docsScriptCreateTempXML, "--as", "bot"}
-			if test.fileName != "" {
-				args = append(args, "--file-name", test.fileName)
-			}
-			err := mountAndRunDocs(t, DocsScript, args, f, nil)
-			if err == nil {
-				t.Fatalf("expected --file-name validation error for %q", test.fileName)
-			}
-			problem, ok := errs.ProblemOf(err)
-			var validationErr *errs.ValidationError
-			if !ok || problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument ||
-				!errors.As(err, &validationErr) || validationErr.Param != "--file-name" {
-				t.Fatalf("problem = %+v, validation = %+v, ok=%v", problem, validationErr, ok)
-			}
-		})
-	}
-}
-
-func TestDocsScriptOutputRequiresExplicitOverwrite(t *testing.T) {
-	withDocsWorkingDir(t, t.TempDir())
-	if err := os.WriteFile("draft.xml", []byte("old"), 0o600); err != nil {
-		t.Fatalf("write existing output: %v", err)
-	}
-	f, stdout, _, _ := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-script-overwrite"))
-
-	err := mountAndRunDocs(t, DocsScript, []string{
-		"+script",
-		"--command", docsScriptMarkdownToXML,
-		"--content", "# new",
-		"--output", "draft.xml",
-		"--as", "bot",
-	}, f, stdout)
-	if err == nil {
-		t.Fatal("expected existing output error")
-	}
-	problem, ok := errs.ProblemOf(err)
-	var validationErr *errs.ValidationError
-	if !ok || problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeFailedPrecondition ||
-		!errors.As(err, &validationErr) || validationErr.Param != "--output" {
-		t.Fatalf("problem = %+v, validation = %+v, ok=%v", problem, validationErr, ok)
-	}
-	got, readErr := os.ReadFile("draft.xml")
-	if readErr != nil || string(got) != "old" {
-		t.Fatalf("existing output changed: content=%q err=%v", got, readErr)
-	}
-
-	err = mountAndRunDocs(t, DocsScript, []string{
-		"+script",
-		"--command", docsScriptMarkdownToXML,
-		"--content", "# new",
-		"--output", "draft.xml",
-		"--overwrite",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("execute docs +script with --overwrite: %v", err)
-	}
-	got, readErr = os.ReadFile("draft.xml")
-	if readErr != nil || string(got) != "<h1>new</h1>" {
-		t.Fatalf("overwritten output = %q, err=%v", got, readErr)
-	}
-}
-
-func TestDocsScriptRejectsOutputForParse(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-script-output-parse"))
-	err := mountAndRunDocs(t, DocsScript, []string{
-		"+script",
-		"--command", docsScriptParse,
-		"--content", `<p>text</p>`,
-		"--output", "draft.xml",
-		"--as", "bot",
-	}, f, nil)
-	if err == nil {
-		t.Fatal("expected --output validation error")
-	}
-	problem, ok := errs.ProblemOf(err)
-	var validationErr *errs.ValidationError
-	if !ok || problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument ||
-		!errors.As(err, &validationErr) || validationErr.Param != "--output" {
-		t.Fatalf("problem = %+v, validation = %+v, ok=%v", problem, validationErr, ok)
-	}
-}
-
-func TestDocsScriptRejectsUnsafeOutputPath(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-script-output-path"))
-	err := mountAndRunDocs(t, DocsScript, []string{
-		"+script",
-		"--command", docsScriptMarkdownToXML,
-		"--content", "# title",
-		"--output", filepath.Join(t.TempDir(), "draft.xml"),
-		"--as", "bot",
-	}, f, nil)
-	if err == nil {
-		t.Fatal("expected unsafe output path error")
-	}
-	problem, ok := errs.ProblemOf(err)
-	var validationErr *errs.ValidationError
-	if !ok || problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument ||
-		!errors.As(err, &validationErr) || validationErr.Param != "--output" {
-		t.Fatalf("problem = %+v, validation = %+v, ok=%v", problem, validationErr, ok)
-	}
-}
-
-func TestDocsScriptDryRunHasNoAPICall(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-script-dry-run"))
-
-	err := mountAndRunDocs(t, DocsScript, []string{
-		"+script",
-		"--command", docsScriptParse,
-		"--content", `<p>text</p>`,
-		"--dry-run",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("execute docs +script dry-run: %v", err)
-	}
-	var got struct {
-		API     []any  `json:"api"`
-		Command string `json:"command"`
-		Network bool   `json:"network"`
-	}
-	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
-		t.Fatalf("decode dry-run stdout: %v\n%s", err, stdout)
-	}
-	if len(got.API) != 0 || got.Command != docsScriptParse || got.Network {
-		t.Fatalf("dry-run output = %+v", got)
-	}
-}
-
-func TestDocsScriptCreateTempXMLDryRunDoesNotWrite(t *testing.T) {
-	workDir := t.TempDir()
-	withDocsWorkingDir(t, workDir)
-	f, stdout, _, _ := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-script-temp-xml-dry-run"))
-
-	err := mountAndRunDocs(t, DocsScript, []string{
-		"+script",
-		"--command", docsScriptCreateTempXML,
-		"--file-name", "川西",
-		"--dry-run",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("execute docs +script dry-run: %v", err)
-	}
-	var got struct {
-		API              []any  `json:"api"`
-		Command          string `json:"command"`
-		DirectoryPattern string `json:"directory_pattern"`
-		FileName         string `json:"file_name"`
-		XMLFileName      string `json:"xml_file_name"`
-		CreatesFile      bool   `json:"creates_file"`
-		Network          bool   `json:"network"`
-	}
-	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
-		t.Fatalf("decode dry-run stdout: %v\n%s", err, stdout)
-	}
-	if len(got.API) != 0 || got.Command != docsScriptCreateTempXML ||
-		got.DirectoryPattern != "川西_*_folder" || got.FileName != "川西" || got.XMLFileName != "川西.xml" ||
-		got.CreatesFile || got.Network {
-		t.Fatalf("dry-run output = %+v", got)
-	}
-	entries, err := os.ReadDir(workDir)
-	if err != nil {
-		t.Fatalf("read work directory: %v", err)
-	}
-	if len(entries) != 0 {
-		t.Fatalf("dry-run created files: %+v", entries)
-	}
-}
-
-func TestDocsScriptOnlineDryRunShowsFetchAPICall(t *testing.T) {
-	f, stdout, _, _ := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-script-online-dry-run"))
-
-	err := mountAndRunDocs(t, DocsScript, []string{
-		"+script",
-		"--command", docsScriptParse,
-		"--doc", "https://example.larksuite.com/docx/doxcnScriptDryRun",
-		"--dry-run",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("execute online docs +script dry-run: %v", err)
-	}
-	var got struct {
-		API []struct {
-			Method string                 `json:"method"`
-			URL    string                 `json:"url"`
-			Body   map[string]interface{} `json:"body"`
-		} `json:"api"`
-		Command    string `json:"command"`
-		DocumentID string `json:"document_id"`
-		Network    bool   `json:"network"`
-	}
-	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
-		t.Fatalf("decode dry-run stdout: %v\n%s", err, stdout)
-	}
-	if len(got.API) != 1 || got.API[0].Method != "POST" ||
-		got.API[0].URL != "/open-apis/docs_ai/v1/documents/doxcnScriptDryRun/fetch" {
-		t.Fatalf("dry-run API = %+v", got.API)
-	}
-	if got.API[0].Body["format"] != "xml" {
-		t.Fatalf("dry-run body = %+v, want XML fetch", got.API[0].Body)
-	}
-	if got.Command != docsScriptParse || got.DocumentID != "doxcnScriptDryRun" || !got.Network {
-		t.Fatalf("dry-run output = %+v", got)
-	}
-}
-
-func TestDocsScriptOutputDryRunDoesNotWrite(t *testing.T) {
-	withDocsWorkingDir(t, t.TempDir())
-	f, stdout, _, _ := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-script-output-dry-run"))
-
-	err := mountAndRunDocs(t, DocsScript, []string{
-		"+script",
-		"--command", docsScriptMarkdownToXML,
-		"--content", "# title",
-		"--output", "draft.xml",
-		"--overwrite",
-		"--dry-run",
-		"--as", "bot",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("execute docs +script dry-run: %v", err)
-	}
-	var got struct {
-		API       []any  `json:"api"`
-		Command   string `json:"command"`
-		Network   bool   `json:"network"`
-		Output    string `json:"output"`
-		Overwrite bool   `json:"overwrite"`
-	}
-	if err := json.Unmarshal(stdout.Bytes(), &got); err != nil {
-		t.Fatalf("decode dry-run stdout: %v\n%s", err, stdout)
-	}
-	if len(got.API) != 0 || got.Command != docsScriptMarkdownToXML || got.Network || got.Output != "draft.xml" || !got.Overwrite {
-		t.Fatalf("dry-run output = %+v", got)
-	}
-	if _, err := os.Stat("draft.xml"); !errors.Is(err, os.ErrNotExist) {
-		t.Fatalf("dry-run created output file: %v", err)
-	}
-}
-
-func TestDocsScriptReturnsTypedParseError(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-script-error"))
-
-	err := mountAndRunDocs(t, DocsScript, []string{
-		"+script",
-		"--command", docsScriptParse,
-		"--content", `<!DOCTYPE document><p>text</p>`,
-		"--as", "bot",
-	}, f, nil)
-	if err == nil {
-		t.Fatal("expected parse error")
-	}
-	problem, ok := errs.ProblemOf(err)
-	if !ok || problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("problem = %+v, ok=%v", problem, ok)
-	}
-	var validationErr *errs.ValidationError
-	if !errors.As(err, &validationErr) || validationErr.Param != "--content" {
-		t.Fatalf("error = %#v, want --content metadata", err)
-	}
-}
-
-func TestDocsScriptRejectsMalformedXML(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-script-malformed"))
-
-	err := mountAndRunDocs(t, DocsScript, []string{
-		"+script",
-		"--command", docsScriptParse,
-		"--content", `<p>text`,
-		"--as", "bot",
-	}, f, nil)
-	if err == nil {
-		t.Fatal("expected malformed XML error")
-	}
-	problem, ok := errs.ProblemOf(err)
-	if !ok || problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("problem = %+v, ok=%v", problem, ok)
-	}
-}
-
-func TestDocsScriptHelpExamplesAreCrossShellSafe(t *testing.T) {
-	cmd := &cobra.Command{Short: "local document parser"}
-	installDocsScriptHelp(cmd)
-	if strings.Contains(cmd.Example, "cat ") {
-		t.Fatalf("help examples require a platform-specific command: %q", cmd.Example)
-	}
-	if strings.Contains(cmd.Example, "--content @") {
-		t.Fatalf("help examples contain an unquoted @file argument: %q", cmd.Example)
-	}
-	for _, want := range []string{`--command create-temp-xml --file-name "draft"`, `--content "@draft.xml"`, `--content "@draft.md"`, `--output "draft.xml"`} {
-		if !strings.Contains(cmd.Example, want) {
-			t.Errorf("help examples missing %q: %q", want, cmd.Example)
-		}
-	}
-}
-
-func blockCount(blocks []docxparse.BlockShare, typ string) int {
-	for _, block := range blocks {
-		if block.Type == typ {
-			return block.Count
-		}
-	}
-	return 0
-}

shortcuts/doc/internal/docxparse/markdown.go

@@ -1,743 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package docxparse
-
-// Markdown conversion is scoped to the docs +script business domain.
-
-import (
-	"fmt"
-	"strings"
-
-	"github.com/yuin/goldmark"
-	gast "github.com/yuin/goldmark/ast"
-	"github.com/yuin/goldmark/extension"
-	extast "github.com/yuin/goldmark/extension/ast"
-	"github.com/yuin/goldmark/parser"
-	"github.com/yuin/goldmark/text"
-	gmutil "github.com/yuin/goldmark/util"
-)
-
-var markdownParser parser.Parser
-
-func init() {
-	markdown := goldmark.New(
-		goldmark.WithExtensions(
-			extension.GFM,
-			extension.DefinitionList,
-			&mathExtension{},
-			&underscoreHTMLExtension{},
-		),
-		goldmark.WithParserOptions(
-			parser.WithBlockParsers(gmutil.Prioritized(&containerBlockParser{}, 90)),
-		),
-	)
-	markdownParser = markdown.Parser()
-}
-
-func parseMarkdown(source string) ([]*Node, error) {
-	if err := validateSource(source); err != nil {
-		return nil, err
-	}
-	source = strings.TrimPrefix(source, "\uFEFF")
-	source = normalizeListIndent(source)
-	source = preprocessCJKAdjacentMarkup(source)
-	data := []byte(source)
-	document := markdownParser.Parse(text.NewReader(data))
-	return renderBlockChildren(document, data)
-}
-
-func renderBlockChildren(parent gast.Node, source []byte) ([]*Node, error) {
-	var out []*Node
-	for child := parent.FirstChild(); child != nil; child = child.NextSibling() {
-		nodes, err := renderBlockNode(child, source)
-		if err != nil {
-			return nil, err
-		}
-		out = append(out, nodes...)
-	}
-	return out, nil
-}
-
-func renderBlockNode(node gast.Node, source []byte) ([]*Node, error) {
-	switch node.Kind() {
-	case gast.KindParagraph, gast.KindTextBlock:
-		children, err := renderInlineChildren(node, source)
-		if err != nil {
-			return nil, err
-		}
-		return wrapParagraphChildren(children), nil
-	case gast.KindHeading:
-		heading := newElement(headingTag(node.(*gast.Heading).Level), nil)
-		children, err := renderInlineChildren(node, source)
-		if err != nil {
-			return nil, err
-		}
-		for _, child := range children {
-			heading.addChild(child)
-		}
-		return []*Node{heading}, nil
-	case gast.KindBlockquote:
-		return renderContainer("blockquote", nil, node, source)
-	case gast.KindList:
-		return renderList(node.(*gast.List), source)
-	case gast.KindFencedCodeBlock:
-		block := node.(*gast.FencedCodeBlock)
-		language := string(block.Language(source))
-		content := trimOneTrailingNewline(string(node.Lines().Value(source)))
-		lowerLanguage := strings.ToLower(language)
-		if content != "" && (lowerLanguage == "mermaid" || lowerLanguage == "plantuml" || lowerLanguage == "svg") {
-			whiteboard := newElement("whiteboard", map[string]string{"type": lowerLanguage})
-			appendRawTextWithBreaks(whiteboard, content)
-			return []*Node{whiteboard}, nil
-		}
-		attrs := map[string]string(nil)
-		if language != "" {
-			attrs = map[string]string{"lang": language}
-		}
-		pre := newElement("pre", attrs)
-		code := newElement("code", nil)
-		appendRawTextWithBreaks(code, content)
-		pre.addChild(code)
-		return []*Node{pre}, nil
-	case gast.KindCodeBlock:
-		pre := newElement("pre", nil)
-		code := newElement("code", nil)
-		appendRawTextWithBreaks(code, trimOneTrailingNewline(string(node.Lines().Value(source))))
-		pre.addChild(code)
-		return []*Node{pre}, nil
-	case gast.KindThematicBreak:
-		return []*Node{newElement("hr", nil)}, nil
-	case gast.KindHTMLBlock:
-		nodes, err := parseMarkdownHTMLBlock(string(node.Lines().Value(source)))
-		if err != nil {
-			return nil, err
-		}
-		stripMarkdownEscapesInNodes(nodes, false, false)
-		return nodes, nil
-	case kindContainerBlock:
-		container := node.(*containerBlock)
-		return renderContainer(container.spec.tag, container.attrs, node, source)
-	}
-
-	switch node.Kind() {
-	case extast.KindTable:
-		return renderTable(node, source)
-	case extast.KindDefinitionList:
-		return renderDefinitionList(node, source)
-	}
-
-	value := strings.TrimSpace(extractMarkdownText(node, source))
-	if value == "" {
-		return nil, nil
-	}
-	paragraph := newElement("p", nil)
-	paragraph.addChild(newText(value))
-	return []*Node{paragraph}, nil
-}
-
-// parseMarkdownHTMLBlock handles the source-bearing LarkOpenCLI blocks whose
-// Markdown bodies are literal text, then delegates every other XML fragment to
-// the strict XML parser. Escaping literal code is part of Markdown conversion.
-func parseMarkdownHTMLBlock(fragment string) ([]*Node, error) {
-	trimmed := strings.TrimSpace(fragment)
-	for _, tag := range []string{"code", "whiteboard"} {
-		closing := "</" + tag + ">"
-		if !strings.HasPrefix(trimmed, "<"+tag) || !strings.HasSuffix(trimmed, closing) {
-			continue
-		}
-		token, contentStart, state := scanXMLToken(trimmed, 0)
-		if state != tokenOK || token.closing || token.selfClosing || token.name != tag {
-			return nil, fmt.Errorf("invalid Markdown <%s> block", tag)
-		}
-		contentEnd := len(trimmed) - len(closing)
-		if contentStart > contentEnd {
-			return nil, fmt.Errorf("invalid Markdown <%s> block", tag)
-		}
-		attrs := normalizeAttributes(tag, tag, token.attrs)
-		block := newElement(tag, attrs)
-		appendRawTextWithBreaks(block, strings.Trim(trimmed[contentStart:contentEnd], "\r\n"))
-		return []*Node{block}, nil
-	}
-	return parseXML(fragment)
-}
-
-func renderContainer(tag string, attrs map[string]string, node gast.Node, source []byte) ([]*Node, error) {
-	attrs = normalizeAttributes(tag, tag, attrs)
-	container := newElement(tag, attrs)
-	children, err := renderBlockChildren(node, source)
-	if err != nil {
-		return nil, err
-	}
-	for _, child := range children {
-		container.addChild(child)
-	}
-	return []*Node{container}, nil
-}
-
-func renderList(list *gast.List, source []byte) ([]*Node, error) {
-	if isTaskList(list) {
-		return renderTaskList(list, source)
-	}
-	tag := "ul"
-	if list.IsOrdered() {
-		tag = "ol"
-	}
-	listNode := newElement(tag, nil)
-	for child := list.FirstChild(); child != nil; child = child.NextSibling() {
-		if child.Kind() != gast.KindListItem {
-			continue
-		}
-		item, err := renderListItem(child.(*gast.ListItem), list.IsTight, source)
-		if err != nil {
-			return nil, err
-		}
-		listNode.addChild(item)
-	}
-	return []*Node{listNode}, nil
-}
-
-func isTaskList(list *gast.List) bool {
-	first := list.FirstChild()
-	if first == nil || first.Kind() != gast.KindListItem {
-		return false
-	}
-	return findTaskCheckbox(first.(*gast.ListItem)) != nil
-}
-
-func findTaskCheckbox(item *gast.ListItem) *extast.TaskCheckBox {
-	for child := item.FirstChild(); child != nil; child = child.NextSibling() {
-		if child.Kind() != gast.KindTextBlock && child.Kind() != gast.KindParagraph {
-			continue
-		}
-		if first := child.FirstChild(); first != nil && first.Kind() == extast.KindTaskCheckBox {
-			return first.(*extast.TaskCheckBox)
-		}
-	}
-	return nil
-}
-
-func renderTaskList(list *gast.List, source []byte) ([]*Node, error) {
-	var out []*Node
-	for child := list.FirstChild(); child != nil; child = child.NextSibling() {
-		if child.Kind() != gast.KindListItem {
-			continue
-		}
-		item := child.(*gast.ListItem)
-		checkboxAST := findTaskCheckbox(item)
-		if checkboxAST == nil {
-			li, err := renderListItem(item, list.IsTight, source)
-			if err != nil {
-				return nil, err
-			}
-			ul := newElement("ul", nil)
-			ul.addChild(li)
-			out = append(out, ul)
-			continue
-		}
-		done := "false"
-		if checkboxAST.IsChecked {
-			done = "true"
-		}
-		checkbox := newElement("checkbox", map[string]string{"done": done})
-		for block := item.FirstChild(); block != nil; block = block.NextSibling() {
-			if block.Kind() == gast.KindTextBlock || block.Kind() == gast.KindParagraph {
-				fragment, err := renderInlineFragment(block, source, true)
-				if err != nil {
-					return nil, err
-				}
-				nodes, err := parseMarkdownInlineFragment(fragment)
-				if err != nil {
-					return nil, err
-				}
-				for _, node := range nodes {
-					checkbox.addChild(node)
-				}
-				continue
-			}
-			nodes, err := renderBlockNode(block, source)
-			if err != nil {
-				return nil, err
-			}
-			for _, node := range nodes {
-				checkbox.addChild(node)
-			}
-		}
-		out = append(out, checkbox)
-	}
-	return out, nil
-}
-
-func renderListItem(item *gast.ListItem, tight bool, source []byte) (*Node, error) {
-	li := newElement("li", nil)
-	children, err := renderBlockChildren(item, source)
-	if err != nil {
-		return nil, err
-	}
-	for _, child := range children {
-		if child.tag == "p" && (tight || paragraphOnlyInline(child)) {
-			for _, grandchild := range child.children {
-				li.addChild(grandchild)
-			}
-			continue
-		}
-		li.addChild(child)
-	}
-	return li, nil
-}
-
-func renderInlineChildren(node gast.Node, source []byte) ([]*Node, error) {
-	fragment, err := renderInlineFragment(node, source, false)
-	if err != nil {
-		return nil, err
-	}
-	nodes, err := parseMarkdownInlineFragment(fragment)
-	if err != nil {
-		return nil, err
-	}
-	stripMarkdownEscapesInNodes(nodes, false, false)
-	return nodes, nil
-}
-
-// parseMarkdownInlineFragment wraps an inline fragment in a space-preserving
-// parent while parsing so XML normalization keeps semantic spaces between
-// adjacent inline elements. The wrapper is removed from the returned nodes.
-func parseMarkdownInlineFragment(fragment string) ([]*Node, error) {
-	nodes, err := parseXML("<p>" + fragment + "</p>")
-	if err != nil {
-		return nil, err
-	}
-	if len(nodes) != 1 || nodes[0].typ != nodeElement || nodes[0].tag != "p" {
-		return nil, fmt.Errorf("invalid Markdown inline fragment")
-	}
-	children := nodes[0].children
-	for _, child := range children {
-		child.parent = nil
-	}
-	return children, nil
-}
-
-func renderInlineFragment(parent gast.Node, source []byte, skipCheckbox bool) (string, error) {
-	var out strings.Builder
-	for child := parent.FirstChild(); child != nil; child = child.NextSibling() {
-		if skipCheckbox && child.Kind() == extast.KindTaskCheckBox {
-			continue
-		}
-		fragment, err := renderInlineNode(child, source)
-		if err != nil {
-			return "", err
-		}
-		out.WriteString(fragment)
-	}
-	return out.String(), nil
-}
-
-func renderInlineNode(node gast.Node, source []byte) (string, error) {
-	switch node.Kind() {
-	case gast.KindText:
-		textNode := node.(*gast.Text)
-		value := escapeXMLText(stripBackslashEscapes(string(textNode.Value(source))))
-		switch {
-		case textNode.HardLineBreak():
-			value += "<br/>"
-		case textNode.SoftLineBreak():
-			value += " "
-		}
-		return value, nil
-	case gast.KindString:
-		return escapeXMLText(string(node.(*gast.String).Value)), nil
-	case gast.KindEmphasis:
-		tag := "em"
-		if node.(*gast.Emphasis).Level >= 2 {
-			tag = "b"
-		}
-		return renderInlineContainer(node, tag, nil, source)
-	case gast.KindCodeSpan:
-		return elementXML("code", nil, escapeXMLText(collectMarkdownChildText(node, source))), nil
-	case gast.KindLink:
-		link := node.(*gast.Link)
-		attrs := map[string]string{"href": string(link.Destination)}
-		if len(link.Title) > 0 {
-			attrs["title"] = string(link.Title)
-		}
-		children, err := renderInlineFragment(node, source, false)
-		if err != nil {
-			return "", err
-		}
-		if children == "" {
-			children = escapeXMLText(string(link.Destination))
-		}
-		return elementXML("a", attrs, children), nil
-	case gast.KindImage:
-		image := node.(*gast.Image)
-		destination := string(image.Destination)
-		attrs := map[string]string{}
-		if strings.HasPrefix(destination, "http://") || strings.HasPrefix(destination, "https://") {
-			attrs["href"] = destination
-		} else {
-			attrs["src"] = destination
-		}
-		if len(image.Title) > 0 {
-			attrs["title"] = string(image.Title)
-		}
-		return elementXML("img", attrs, ""), nil
-	case gast.KindRawHTML:
-		return string(node.(*gast.RawHTML).Segments.Value(source)), nil
-	case gast.KindAutoLink:
-		link := node.(*gast.AutoLink)
-		return elementXML("a", map[string]string{"href": string(link.URL(source))}, escapeXMLText(string(link.Label(source)))), nil
-	}
-
-	switch node.Kind() {
-	case extast.KindStrikethrough:
-		return renderInlineContainer(node, "del", nil, source)
-	case kindMathInline:
-		return elementXML("latex", nil, escapeXMLText(stripLatexMarkdownEscapes(string(node.(*mathInline).content)))), nil
-	case kindMathBlock:
-		return elementXML("latex", nil, escapeXMLText(stripLatexMarkdownEscapes(string(node.(*mathBlock).content)))), nil
-	case extast.KindTaskCheckBox:
-		return "", nil
-	}
-
-	if node.Type() == gast.TypeBlock {
-		return escapeXMLText(strings.TrimSpace(extractMarkdownText(node, source))), nil
-	}
-	return escapeXMLText(extractMarkdownText(node, source)), nil
-}
-
-func renderInlineContainer(node gast.Node, tag string, attrs map[string]string, source []byte) (string, error) {
-	children, err := renderInlineFragment(node, source, false)
-	if err != nil {
-		return "", err
-	}
-	return elementXML(tag, attrs, children), nil
-}
-
-func elementXML(tag string, attrs map[string]string, inner string) string {
-	node := newElement(tag, attrs)
-	rendered := renderNodes([]*Node{node})
-	if inner == "" {
-		return rendered
-	}
-	close := "</" + tag + ">"
-	if strings.HasSuffix(rendered, close) {
-		return strings.TrimSuffix(rendered, close) + inner + close
-	}
-	return rendered
-}
-
-func wrapParagraphChildren(children []*Node) []*Node {
-	var out []*Node
-	var inline []*Node
-	flush := func() {
-		if len(inline) == 0 {
-			return
-		}
-		paragraph := newElement("p", nil)
-		for _, child := range inline {
-			paragraph.addChild(child)
-		}
-		out = append(out, paragraph)
-		inline = nil
-	}
-	for _, child := range children {
-		if child != nil && child.typ == nodeElement && layoutOf(child.tag) == layoutBlock {
-			flush()
-			out = append(out, child)
-			continue
-		}
-		inline = append(inline, child)
-	}
-	flush()
-	return out
-}
-
-func paragraphOnlyInline(node *Node) bool {
-	if node == nil || node.typ != nodeElement || node.tag != "p" {
-		return false
-	}
-	for _, child := range node.children {
-		if child.typ == nodeElement && layoutOf(child.tag) == layoutBlock {
-			return false
-		}
-	}
-	return true
-}
-
-func renderTable(node gast.Node, source []byte) ([]*Node, error) {
-	table := newElement("table", nil)
-	var body *Node
-	for child := node.FirstChild(); child != nil; child = child.NextSibling() {
-		switch child.Kind() {
-		case extast.KindTableHeader:
-			head := newElement("thead", nil)
-			row, err := renderTableRow(child, true, source)
-			if err != nil {
-				return nil, err
-			}
-			head.addChild(row)
-			table.addChild(head)
-		case extast.KindTableRow:
-			if body == nil {
-				body = newElement("tbody", nil)
-				table.addChild(body)
-			}
-			row, err := renderTableRow(child, false, source)
-			if err != nil {
-				return nil, err
-			}
-			body.addChild(row)
-		}
-	}
-	return []*Node{table}, nil
-}
-
-func renderTableRow(node gast.Node, header bool, source []byte) (*Node, error) {
-	row := newElement("tr", nil)
-	for child := node.FirstChild(); child != nil; child = child.NextSibling() {
-		if child.Kind() != extast.KindTableCell {
-			continue
-		}
-		cellAST := child.(*extast.TableCell)
-		tag := "td"
-		if header {
-			tag = "th"
-		}
-		attrs := map[string]string(nil)
-		switch cellAST.Alignment {
-		case extast.AlignCenter:
-			attrs = map[string]string{"align": "center"}
-		case extast.AlignRight:
-			attrs = map[string]string{"align": "right"}
-		}
-		cell := newElement(tag, attrs)
-		content, err := renderInlineChildren(cellAST, source)
-		if err != nil {
-			return nil, err
-		}
-		for _, inline := range content {
-			cell.addChild(inline)
-		}
-		row.addChild(cell)
-	}
-	return row, nil
-}
-
-func renderDefinitionList(node gast.Node, source []byte) ([]*Node, error) {
-	var out []*Node
-	for child := node.FirstChild(); child != nil; child = child.NextSibling() {
-		switch child.Kind() {
-		case extast.KindDefinitionTerm:
-			fragment, err := renderInlineFragment(child, source, false)
-			if err != nil {
-				return nil, err
-			}
-			nodes, err := parseXML(fragment)
-			if err != nil {
-				return nil, err
-			}
-			paragraph := newElement("p", nil)
-			bold := newElement("b", nil)
-			for _, node := range nodes {
-				bold.addChild(node)
-			}
-			paragraph.addChild(bold)
-			out = append(out, paragraph)
-		case extast.KindDefinitionDescription:
-			quote, err := renderContainer("blockquote", nil, child, source)
-			if err != nil {
-				return nil, err
-			}
-			out = append(out, quote...)
-		}
-	}
-	return out, nil
-}
-
-func appendRawTextWithBreaks(parent *Node, content string) {
-	if content == "" {
-		return
-	}
-	start := 0
-	for i := 0; i < len(content); i++ {
-		if content[i] != '\n' && content[i] != '\r' {
-			continue
-		}
-		if i > start {
-			parent.addChild(newText(content[start:i]))
-		}
-		if content[i] == '\r' && i+1 < len(content) && content[i+1] == '\n' {
-			i++
-		}
-		parent.addChild(newElement("br", nil))
-		start = i + 1
-	}
-	if start < len(content) {
-		parent.addChild(newText(content[start:]))
-	}
-}
-
-func stripMarkdownEscapesInNodes(nodes []*Node, inCode, inLatex bool) {
-	for _, node := range nodes {
-		if node == nil {
-			continue
-		}
-		if node.typ == nodeText {
-			switch {
-			case inCode:
-			case inLatex:
-				node.text = stripLatexMarkdownEscapes(node.text)
-			default:
-				node.text = stripBackslashEscapes(node.text)
-			}
-			continue
-		}
-		stripMarkdownEscapesInNodes(node.children, inCode || node.tag == "code" || node.tag == "pre", inLatex || node.tag == "latex")
-	}
-}
-
-func stripBackslashEscapes(value string) string {
-	if !strings.Contains(value, `\`) {
-		return value
-	}
-	var out strings.Builder
-	out.Grow(len(value))
-	for i := 0; i < len(value); i++ {
-		if value[i] == '\\' && i+1 < len(value) && isASCIIPunctuation(value[i+1]) {
-			out.WriteByte(value[i+1])
-			i++
-			continue
-		}
-		out.WriteByte(value[i])
-	}
-	return out.String()
-}
-
-func stripLatexMarkdownEscapes(value string) string {
-	if !strings.Contains(value, `\`) {
-		return value
-	}
-	var out strings.Builder
-	out.Grow(len(value))
-	for i := 0; i < len(value); i++ {
-		if value[i] == '\\' && i+1 < len(value) && strings.ContainsRune("_^&*[]$~<>`#+-=:", rune(value[i+1])) {
-			out.WriteByte(value[i+1])
-			i++
-			continue
-		}
-		out.WriteByte(value[i])
-	}
-	return out.String()
-}
-
-func isASCIIPunctuation(ch byte) bool {
-	return ch >= '!' && ch <= '/' || ch >= ':' && ch <= '@' || ch >= '[' && ch <= '`' || ch >= '{' && ch <= '~'
-}
-
-func trimOneTrailingNewline(value string) string {
-	if strings.HasSuffix(value, "\r\n") {
-		return value[:len(value)-2]
-	}
-	return strings.TrimSuffix(value, "\n")
-}
-
-func collectMarkdownChildText(node gast.Node, source []byte) string {
-	var out strings.Builder
-	for child := node.FirstChild(); child != nil; child = child.NextSibling() {
-		switch child.Kind() {
-		case gast.KindText:
-			out.Write(child.(*gast.Text).Value(source))
-		case gast.KindString:
-			out.Write(child.(*gast.String).Value)
-		default:
-			out.WriteString(collectMarkdownChildText(child, source))
-		}
-	}
-	return out.String()
-}
-
-func extractMarkdownText(node gast.Node, source []byte) string {
-	switch node.Kind() {
-	case gast.KindText:
-		return string(node.(*gast.Text).Value(source))
-	case gast.KindString:
-		return string(node.(*gast.String).Value)
-	case gast.KindCodeSpan:
-		return collectMarkdownChildText(node, source)
-	}
-	if node.Type() == gast.TypeBlock && node.Lines() != nil && node.Lines().Len() > 0 {
-		return string(node.Lines().Value(source))
-	}
-	var out strings.Builder
-	for child := node.FirstChild(); child != nil; child = child.NextSibling() {
-		out.WriteString(extractMarkdownText(child, source))
-	}
-	return out.String()
-}
-
-func headingTag(level int) string {
-	if level < 1 || level > 6 {
-		return "p"
-	}
-	return fmt.Sprintf("h%d", level)
-}
-
-func normalizeListIndent(markdown string) string {
-	lines := strings.Split(markdown, "\n")
-	type stackEntry struct{ indent int }
-	var stack []stackEntry
-	inFence := false
-	changed := false
-	lastOriginal, lastNormalized := 0, 0
-	for i, line := range lines {
-		trimmed := strings.TrimLeft(line, " ")
-		if strings.HasPrefix(trimmed, "```") || strings.HasPrefix(trimmed, "~~~") {
-			inFence = !inFence
-			continue
-		}
-		if inFence || trimmed == "" {
-			continue
-		}
-		indent := len(line) - len(trimmed)
-		if markdownListMarkerLength(trimmed) > 0 {
-			for len(stack) > 0 && indent <= stack[len(stack)-1].indent {
-				stack = stack[:len(stack)-1]
-			}
-			normalized := len(stack) * 4
-			stack = append(stack, stackEntry{indent: indent})
-			lastOriginal, lastNormalized = indent, normalized
-			if indent != normalized {
-				lines[i] = strings.Repeat(" ", normalized) + trimmed
-				changed = true
-			}
-		} else if len(stack) > 0 && indent > lastOriginal {
-			delta := lastNormalized - lastOriginal
-			if delta != 0 {
-				normalized := indent + delta
-				if normalized < 0 {
-					normalized = 0
-				}
-				lines[i] = strings.Repeat(" ", normalized) + trimmed
-				changed = true
-			}
-		}
-	}
-	if !changed {
-		return markdown
-	}
-	return strings.Join(lines, "\n")
-}
-
-func markdownListMarkerLength(value string) int {
-	if len(value) >= 2 && (value[0] == '-' || value[0] == '*' || value[0] == '+') && value[1] == ' ' {
-		return 2
-	}
-	i := 0
-	for i < len(value) && value[i] >= '0' && value[i] <= '9' {
-		i++
-	}
-	if i > 0 && i+1 < len(value) && (value[i] == '.' || value[i] == ')') && value[i+1] == ' ' {
-		return i + 2
-	}
-	return 0
-}

shortcuts/doc/internal/docxparse/markdown_cjk.go

@@ -1,284 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package docxparse
-
-import (
-	"strings"
-	"unicode"
-)
-
-// preprocessCJKAdjacentMarkup disambiguates a narrow CommonMark pattern common in
-// Chinese prose: emphasis that ends in punctuation and is immediately followed
-// by a letter (for example **结论。**下一步). Goldmark correctly follows
-// CommonMark's delimiter rules, while LarkOpenCLI accepts this authoring form.
-// Rewriting simple CJK delimiter spans to equivalent DocxXML
-// before parsing removes the ambiguity while leaving nested Markdown, links,
-// code, fenced blocks, and source-bearing XML untouched.
-func preprocessCJKAdjacentMarkup(markdown string) string {
-	if !strings.Contains(markdown, "**") && !strings.Contains(markdown, "~~") {
-		return markdown
-	}
-	lines := strings.SplitAfter(markdown, "\n")
-	var out strings.Builder
-	fenceMarker := rune(0)
-	fenceLength := 0
-	rawSourceTag := ""
-	for _, line := range lines {
-		trimmed := strings.TrimLeft(line, " \t>")
-		if marker, length, ok := markdownFence(trimmed); ok {
-			if fenceMarker == 0 {
-				fenceMarker, fenceLength = marker, length
-			} else if marker == fenceMarker && length >= fenceLength && strings.TrimSpace(runeTail(trimmed, length)) == "" {
-				fenceMarker, fenceLength = 0, 0
-			}
-			out.WriteString(line)
-			continue
-		}
-		if fenceMarker != 0 || leadingIndent(line) >= 4 {
-			out.WriteString(line)
-			continue
-		}
-		out.WriteString(rewriteCJKMarkupLine(line, &rawSourceTag))
-	}
-	return out.String()
-}
-
-func markdownFence(line string) (rune, int, bool) {
-	runes := []rune(line)
-	if len(runes) < 3 || runes[0] != '`' && runes[0] != '~' {
-		return 0, 0, false
-	}
-	marker := runes[0]
-	length := 0
-	for length < len(runes) && runes[length] == marker {
-		length++
-	}
-	return marker, length, length >= 3
-}
-
-func runeTail(value string, start int) string {
-	runes := []rune(value)
-	if start >= len(runes) {
-		return ""
-	}
-	return string(runes[start:])
-}
-
-func leadingIndent(line string) int {
-	count := 0
-	for _, r := range line {
-		switch r {
-		case ' ':
-			count++
-		case '\t':
-			count += 4
-		default:
-			return count
-		}
-	}
-	return count
-}
-
-type cjkMarkupRule struct {
-	delimiter []rune
-	openXML   string
-	closeXML  string
-}
-
-var cjkMarkupRules = []cjkMarkupRule{
-	{delimiter: []rune("***"), openXML: "<em><b>", closeXML: "</b></em>"},
-	{delimiter: []rune("~~"), openXML: "<del>", closeXML: "</del>"},
-	{delimiter: []rune("**"), openXML: "<b>", closeXML: "</b>"},
-}
-
-func rewriteCJKMarkupLine(line string, rawSourceTag *string) string {
-	if *rawSourceTag != "" {
-		runes := []rune(line)
-		closeTag := []rune("</" + *rawSourceTag + ">")
-		closeAt := indexRunesFold(runes, 0, closeTag)
-		if closeAt < 0 {
-			return line
-		}
-		closeEnd := closeAt + len(closeTag)
-		prefix := string(runes[:closeEnd])
-		*rawSourceTag = ""
-		return prefix + rewriteCJKMarkupLine(string(runes[closeEnd:]), rawSourceTag)
-	}
-
-	runes := []rune(line)
-	var out strings.Builder
-	for i := 0; i < len(runes); {
-		if runes[i] == '`' && !runeEscaped(runes, i) {
-			if end := codeSpanEnd(runes, i); end > i {
-				out.WriteString(string(runes[i:end]))
-				i = end
-				continue
-			}
-		}
-		if runes[i] == '<' {
-			if tag, end, selfClosing, ok := rawTagAt(runes, i); ok {
-				out.WriteString(string(runes[i:end]))
-				i = end
-				if !selfClosing && (tag == "code" || tag == "pre" || tag == "whiteboard") {
-					close := []rune("</" + tag + ">")
-					if closeAt := indexRunesFold(runes, i, close); closeAt >= 0 {
-						closeEnd := closeAt + len(close)
-						out.WriteString(string(runes[i:closeEnd]))
-						i = closeEnd
-					} else {
-						out.WriteString(string(runes[i:]))
-						*rawSourceTag = tag
-						return out.String()
-					}
-				}
-				continue
-			}
-		}
-
-		rewritten := false
-		for _, rule := range cjkMarkupRules {
-			if !exactDelimiterAt(runes, i, rule.delimiter) || runeEscaped(runes, i) {
-				continue
-			}
-			closeAt := delimiterCloser(runes, i+len(rule.delimiter), rule.delimiter)
-			if closeAt < 0 {
-				continue
-			}
-			content := runes[i+len(rule.delimiter) : closeAt]
-			if !shouldRewriteCJKMarkup(content) {
-				continue
-			}
-			out.WriteString(rule.openXML)
-			out.WriteString(escapeXMLText(stripBackslashEscapes(string(content))))
-			out.WriteString(rule.closeXML)
-			i = closeAt + len(rule.delimiter)
-			rewritten = true
-			break
-		}
-		if rewritten {
-			continue
-		}
-		out.WriteRune(runes[i])
-		i++
-	}
-	return out.String()
-}
-
-func rawTagAt(runes []rune, start int) (tag string, end int, selfClosing, ok bool) {
-	if start+1 >= len(runes) || !isASCIILetterRune(runes[start+1]) {
-		return "", 0, false, false
-	}
-	i := start + 1
-	for i < len(runes) && (isASCIILetterRune(runes[i]) || isASCIIDigitRune(runes[i]) || runes[i] == '-' || runes[i] == '_') {
-		i++
-	}
-	tag = strings.ToLower(string(runes[start+1 : i]))
-	quote := rune(0)
-	for ; i < len(runes); i++ {
-		if runes[i] == '\'' || runes[i] == '"' {
-			if quote == 0 {
-				quote = runes[i]
-			} else if quote == runes[i] {
-				quote = 0
-			}
-			continue
-		}
-		if runes[i] == '>' && quote == 0 {
-			trimmed := strings.TrimSpace(string(runes[start : i+1]))
-			return tag, i + 1, strings.HasSuffix(trimmed, "/>"), true
-		}
-	}
-	return "", 0, false, false
-}
-
-func indexRunesFold(haystack []rune, start int, needle []rune) int {
-	for i := start; i+len(needle) <= len(haystack); i++ {
-		if strings.EqualFold(string(haystack[i:i+len(needle)]), string(needle)) {
-			return i
-		}
-	}
-	return -1
-}
-
-func codeSpanEnd(runes []rune, open int) int {
-	length := 0
-	for open+length < len(runes) && runes[open+length] == '`' {
-		length++
-	}
-	for i := open + length; i < len(runes); i++ {
-		if runes[i] != '`' || runeEscaped(runes, i) {
-			continue
-		}
-		end := i
-		for end < len(runes) && runes[end] == '`' {
-			end++
-		}
-		if end-i == length {
-			return end
-		}
-		i = end - 1
-	}
-	return -1
-}
-
-func exactDelimiterAt(runes []rune, start int, delimiter []rune) bool {
-	if start+len(delimiter) > len(runes) {
-		return false
-	}
-	for i, want := range delimiter {
-		if runes[start+i] != want {
-			return false
-		}
-	}
-	marker := delimiter[0]
-	return (start == 0 || runes[start-1] != marker) && (start+len(delimiter) == len(runes) || runes[start+len(delimiter)] != marker)
-}
-
-func delimiterCloser(runes []rune, start int, delimiter []rune) int {
-	for i := start; i+len(delimiter) <= len(runes); i++ {
-		if runes[i] == '\n' {
-			return -1
-		}
-		if exactDelimiterAt(runes, i, delimiter) && !runeEscaped(runes, i) {
-			return i
-		}
-	}
-	return -1
-}
-
-func shouldRewriteCJKMarkup(content []rune) bool {
-	if len(content) == 0 || unicode.IsSpace(content[0]) || unicode.IsSpace(content[len(content)-1]) {
-		return false
-	}
-	for _, r := range content {
-		if r == '`' || r == '[' || r == ']' || r == '<' || r == '>' {
-			return false
-		}
-	}
-	if !containsCJK(content) {
-		return false
-	}
-	return true
-}
-
-func containsCJK(value []rune) bool {
-	for _, r := range value {
-		if isCJKRune(r) || r > unicode.MaxASCII && (unicode.IsPunct(r) || unicode.IsSymbol(r)) {
-			return true
-		}
-	}
-	return false
-}
-
-func isCJKRune(r rune) bool {
-	return unicode.In(r, unicode.Han, unicode.Hiragana, unicode.Katakana, unicode.Hangul)
-}
-
-func runeEscaped(runes []rune, index int) bool {
-	count := 0
-	for i := index - 1; i >= 0 && runes[i] == '\\'; i-- {
-		count++
-	}
-	return count%2 == 1
-}

shortcuts/doc/internal/docxparse/markdown_extensions.go

@@ -1,334 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package docxparse
-
-// This file contains the small Goldmark extensions needed to match the
-// LarkOpenCLI's Markdown surface: math, DocxXML tag names containing
-// underscores, and Markdown-aware callout/grid/column containers.
-
-import (
-	"bytes"
-	"regexp"
-	"strings"
-
-	"github.com/yuin/goldmark"
-	gast "github.com/yuin/goldmark/ast"
-	"github.com/yuin/goldmark/parser"
-	"github.com/yuin/goldmark/text"
-	gmutil "github.com/yuin/goldmark/util"
-)
-
-// ---------- Math ----------
-
-var kindMathInline = gast.NewNodeKind("DocxMathInline")
-var kindMathBlock = gast.NewNodeKind("DocxMathBlock")
-
-type mathInline struct {
-	gast.BaseInline
-	content []byte
-}
-
-func (n *mathInline) Kind() gast.NodeKind { return kindMathInline }
-func (n *mathInline) Dump(source []byte, level int) {
-	gast.DumpHelper(n, source, level, nil, nil)
-}
-
-type mathBlock struct {
-	gast.BaseInline
-	content []byte
-}
-
-func (n *mathBlock) Kind() gast.NodeKind { return kindMathBlock }
-func (n *mathBlock) Dump(source []byte, level int) {
-	gast.DumpHelper(n, source, level, nil, nil)
-}
-
-var (
-	mathBlockMultiLine  = regexp.MustCompile(`(?s)^\$\$(.+?)\$\$`)
-	mathInlineMultiLine = regexp.MustCompile(`(?s)^\$([^ \t$].*?)\$`)
-)
-
-type mathInlineParser struct{}
-
-func (p *mathInlineParser) Trigger() []byte { return []byte{'$'} }
-
-func (p *mathInlineParser) Parse(_ gast.Node, reader text.Reader, _ parser.Context) gast.Node {
-	line, _ := reader.PeekLine()
-	if len(line) == 0 || line[0] != '$' {
-		return nil
-	}
-	if len(line) >= 2 && line[1] == '$' {
-		if content, advance := scanMathClose(line[2:], "$$"); advance >= 0 && len(content) > 0 {
-			reader.Advance(2 + advance)
-			return &mathBlock{content: append([]byte(nil), content...)}
-		}
-		match := reader.FindSubMatch(mathBlockMultiLine)
-		if len(match) >= 2 && len(bytes.TrimSpace(match[1])) > 0 && !bytes.Contains(match[1], []byte("<latex")) {
-			return &mathBlock{content: append([]byte(nil), bytes.TrimSpace(match[1])...)}
-		}
-		return nil
-	}
-	if len(line) < 2 || line[1] == ' ' || line[1] == '\t' || line[1] == '$' {
-		return nil
-	}
-	if content, advance := scanMathClose(line[1:], "$"); advance >= 0 && len(content) > 0 {
-		if content[len(content)-1] == ' ' || content[len(content)-1] == '\t' {
-			return nil
-		}
-		reader.Advance(1 + advance)
-		return &mathInline{content: append([]byte(nil), content...)}
-	}
-	match := reader.FindSubMatch(mathInlineMultiLine)
-	if len(match) < 2 || bytes.Contains(match[1], []byte("<latex")) {
-		return nil
-	}
-	trimmed := bytes.TrimRight(match[1], "\n\r")
-	if len(trimmed) == 0 || trimmed[len(trimmed)-1] == ' ' || trimmed[len(trimmed)-1] == '\t' {
-		return nil
-	}
-	return &mathInline{content: append([]byte(nil), trimmed...)}
-}
-
-func scanMathClose(data []byte, delimiter string) ([]byte, int) {
-	delim := []byte(delimiter)
-	for offset := 0; offset < len(data); {
-		if data[offset] == '\\' && offset+1 < len(data) && data[offset+1] == '$' {
-			offset += 2
-			continue
-		}
-		rel := bytes.Index(data[offset:], delim)
-		if rel < 0 {
-			return nil, -1
-		}
-		end := offset + rel
-		if bytes.Contains(data[:end], []byte("<latex")) {
-			return nil, -1
-		}
-		return data[:end], end + len(delim)
-	}
-	return nil, -1
-}
-
-type mathExtension struct{}
-
-func (e *mathExtension) Extend(markdown goldmark.Markdown) {
-	markdown.Parser().AddOptions(parser.WithInlineParsers(
-		gmutil.Prioritized(&mathInlineParser{}, 100),
-	))
-}
-
-// ---------- Underscore-bearing raw XML tags ----------
-
-type underscoreHTMLExtension struct{}
-
-func (e *underscoreHTMLExtension) Extend(markdown goldmark.Markdown) {
-	markdown.Parser().AddOptions(
-		parser.WithInlineParsers(gmutil.Prioritized(&underscoreRawHTMLParser{}, 99)),
-		parser.WithBlockParsers(gmutil.Prioritized(&underscoreHTMLBlockParser{}, 99)),
-	)
-}
-
-var (
-	extendedTagNamePattern   = `([A-Za-z][A-Za-z0-9_-]*)`
-	extendedAttributePattern = `(?:\s+[a-zA-Z_:][a-zA-Z0-9:._-]*(?:\s*=\s*(?:[^"'=<>` + "`" + `\x00-\x20]+|'[^']*'|"[^"]*"))?)`
-	extendedOpenTag          = regexp.MustCompile("^<" + extendedTagNamePattern + extendedAttributePattern + `*\s*/?>`)
-	extendedCloseTag         = regexp.MustCompile("^</" + extendedTagNamePattern + `\s*>`)
-	peekExtendedOpenTag      = regexp.MustCompile(`^<([A-Za-z][A-Za-z0-9_-]*)`)
-	peekExtendedCloseTag     = regexp.MustCompile(`^</([A-Za-z][A-Za-z0-9_-]*)`)
-	extendedBlockTag         = regexp.MustCompile(`^[ ]{0,3}<(/)?\s*([a-zA-Z0-9_\-]+)(` + extendedAttributePattern + `*)\s*(?:>|/>)\s*\n?$`)
-)
-
-type underscoreRawHTMLParser struct{}
-
-func (p *underscoreRawHTMLParser) Trigger() []byte { return []byte{'<'} }
-
-func (p *underscoreRawHTMLParser) Parse(_ gast.Node, reader text.Reader, _ parser.Context) gast.Node {
-	line, _ := reader.PeekLine()
-	if len(line) > 1 && gmutil.IsAlphaNumeric(line[1]) {
-		if match := peekExtendedOpenTag.FindSubmatch(line); match != nil && bytes.IndexByte(match[1], '_') >= 0 {
-			return p.parseMultiLine(extendedOpenTag, reader)
-		}
-		return nil
-	}
-	if len(line) > 2 && line[1] == '/' && gmutil.IsAlphaNumeric(line[2]) {
-		if match := peekExtendedCloseTag.FindSubmatch(line); match != nil && bytes.IndexByte(match[1], '_') >= 0 {
-			return p.parseMultiLine(extendedCloseTag, reader)
-		}
-	}
-	return nil
-}
-
-func (p *underscoreRawHTMLParser) parseMultiLine(re *regexp.Regexp, reader text.Reader) gast.Node {
-	startLine, startSegment := reader.Position()
-	if !reader.Match(re) {
-		return nil
-	}
-	endLine, endSegment := reader.Position()
-	reader.SetPosition(startLine, startSegment)
-	node := gast.NewRawHTML()
-	for {
-		line, segment := reader.PeekLine()
-		if line == nil {
-			break
-		}
-		lineNo, _ := reader.Position()
-		start := segment.Start
-		if lineNo == startLine {
-			start = startSegment.Start
-		}
-		end := segment.Stop
-		if lineNo == endLine {
-			end = endSegment.Start
-		}
-		node.Segments.Append(text.NewSegment(start, end))
-		if lineNo == endLine {
-			reader.Advance(end - start)
-			break
-		}
-		reader.AdvanceLine()
-	}
-	return node
-}
-
-type underscoreHTMLBlockParser struct{}
-
-func (p *underscoreHTMLBlockParser) Trigger() []byte { return []byte{'<'} }
-
-func (p *underscoreHTMLBlockParser) Open(_ gast.Node, reader text.Reader, pc parser.Context) (gast.Node, parser.State) {
-	line, segment := reader.PeekLine()
-	pos := pc.BlockOffset()
-	if pos < 0 || pos >= len(line) || line[pos] != '<' {
-		return nil, parser.NoChildren
-	}
-	match := extendedBlockTag.FindSubmatchIndex(line)
-	if match == nil {
-		return nil, parser.NoChildren
-	}
-	tag := string(line[match[4]:match[5]])
-	if !strings.Contains(tag, "_") {
-		return nil, parser.NoChildren
-	}
-	isClose := match[2] > -1 && bytes.Equal(line[match[2]:match[3]], []byte("/"))
-	hasAttrs := match[6] != match[7]
-	if isClose && hasAttrs {
-		return nil, parser.NoChildren
-	}
-	node := gast.NewHTMLBlock(gast.HTMLBlockType7)
-	node.Lines().Append(segment)
-	reader.Advance(segment.Len() - 1)
-	return node, parser.NoChildren
-}
-
-func (p *underscoreHTMLBlockParser) Continue(node gast.Node, reader text.Reader, _ parser.Context) parser.State {
-	line, segment := reader.PeekLine()
-	if gmutil.IsBlank(line) {
-		return parser.Close
-	}
-	node.Lines().Append(segment)
-	reader.Advance(segment.Len() - 1)
-	return parser.Continue | parser.NoChildren
-}
-
-func (p *underscoreHTMLBlockParser) Close(gast.Node, text.Reader, parser.Context) {}
-func (p *underscoreHTMLBlockParser) CanInterruptParagraph() bool                  { return false }
-func (p *underscoreHTMLBlockParser) CanAcceptIndentedLine() bool                  { return false }
-
-// ---------- Markdown-aware DocxXML containers ----------
-
-type containerSpec struct {
-	tag string
-}
-
-var containerSpecs = map[string]*containerSpec{
-	"callout": {tag: "callout"},
-	"grid":    {tag: "grid"},
-	"column":  {tag: "column"},
-	"div":     {tag: "div"},
-}
-
-var kindContainerBlock = gast.NewNodeKind("DocxContainerBlock")
-
-type containerBlock struct {
-	gast.BaseBlock
-	spec  *containerSpec
-	attrs map[string]string
-}
-
-func (n *containerBlock) Kind() gast.NodeKind { return kindContainerBlock }
-func (n *containerBlock) Dump(source []byte, level int) {
-	gast.DumpHelper(n, source, level, nil, nil)
-}
-
-type containerBlockParser struct{}
-
-func (p *containerBlockParser) Trigger() []byte { return []byte{'<'} }
-
-var containerOpenTag = regexp.MustCompile(`^<([A-Za-z][A-Za-z0-9_-]*)`)
-
-func (p *containerBlockParser) Open(_ gast.Node, reader text.Reader, _ parser.Context) (gast.Node, parser.State) {
-	line, _ := reader.PeekLine()
-	trimmed := bytes.TrimLeft(line, " \t")
-	leading := len(line) - len(trimmed)
-	if len(trimmed) < 2 || trimmed[0] != '<' {
-		return nil, parser.NoChildren
-	}
-	match := containerOpenTag.FindSubmatch(trimmed)
-	if match == nil {
-		return nil, parser.NoChildren
-	}
-	spec := containerSpecs[strings.ToLower(string(match[1]))]
-	if spec == nil {
-		return nil, parser.NoChildren
-	}
-	openEnd := bytes.IndexByte(trimmed, '>')
-	if openEnd < 0 || openEnd >= 1 && trimmed[openEnd-1] == '/' {
-		return nil, parser.NoChildren
-	}
-	tagEnd := len(match[0])
-	node := &containerBlock{spec: spec, attrs: parseAttributes(string(trimmed[tagEnd:openEnd]))}
-	reader.Advance(leading + openEnd + 1)
-	return node, parser.HasChildren
-}
-
-func (p *containerBlockParser) Continue(node gast.Node, reader text.Reader, _ parser.Context) parser.State {
-	container := node.(*containerBlock)
-	line, segment := reader.PeekLine()
-	trimmed := bytes.TrimLeft(line, " \t")
-	if hasCloseTagPrefix(trimmed, container.spec.tag) {
-		reader.Advance(len(line) - len(trimmed) + closeTagLength(container.spec.tag))
-		return parser.Close
-	}
-	if isXMLTagLine(trimmed) {
-		indent := len(line) - len(trimmed)
-		if indent > 0 && segment.Start+indent <= segment.Stop {
-			reader.AdvanceAndSetPadding(indent, 0)
-		}
-	}
-	return parser.Continue | parser.HasChildren
-}
-
-func (p *containerBlockParser) Close(gast.Node, text.Reader, parser.Context) {}
-func (p *containerBlockParser) CanInterruptParagraph() bool                  { return true }
-func (p *containerBlockParser) CanAcceptIndentedLine() bool                  { return true }
-
-func closeTagLength(tag string) int { return len(tag) + len("</>") }
-
-func hasCloseTagPrefix(line []byte, tag string) bool {
-	want := []byte("</" + tag + ">")
-	return len(line) >= len(want) && bytes.EqualFold(line[:len(want)], want)
-}
-
-func isXMLTagLine(line []byte) bool {
-	if len(line) < 2 || line[0] != '<' {
-		return false
-	}
-	if line[1] == '/' {
-		return len(line) >= 3 && isASCIILetter(line[2])
-	}
-	return isASCIILetter(line[1])
-}
-
-func isASCIILetter(ch byte) bool {
-	return ch >= 'a' && ch <= 'z' || ch >= 'A' && ch <= 'Z'
-}

shortcuts/doc/internal/docxparse/model.go

@@ -1,172 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// Package docxparse parses LarkOpenCLI DocxXML and Markdown into a small,
-// offline DOM for the docs +script shortcut.
-package docxparse
-
-import (
-	"sort"
-	"strings"
-)
-
-// Format is an accepted source document format.
-type Format string
-
-const (
-	FormatXML      Format = "xml"
-	FormatMarkdown Format = "markdown"
-)
-
-// ParseResult is the complete result returned by Parse.
-type ParseResult struct {
-	Format  Format  `json:"format"`
-	XML     string  `json:"xml"`
-	Profile Profile `json:"profile"`
-}
-
-type nodeType uint8
-
-const (
-	nodeText nodeType = iota
-	nodeElement
-)
-
-// Node is the internal DocxXML DOM representation.
-type Node struct {
-	typ      nodeType
-	tag      string
-	attrs    map[string]string
-	children []*Node
-	text     string
-	parent   *Node
-}
-
-func newText(text string) *Node {
-	return &Node{typ: nodeText, text: text}
-}
-
-func newElement(tag string, attrs map[string]string) *Node {
-	return &Node{typ: nodeElement, tag: tag, attrs: attrs}
-}
-
-func (n *Node) addChild(child *Node) {
-	if n == nil || child == nil {
-		return
-	}
-	child.parent = n
-	n.children = append(n.children, child)
-}
-
-func (n *Node) writeXML(out *strings.Builder) {
-	if n == nil {
-		return
-	}
-	if n.typ == nodeText {
-		out.WriteString(escapeXMLText(n.text))
-		return
-	}
-
-	out.WriteByte('<')
-	out.WriteString(n.tag)
-	keys := make([]string, 0, len(n.attrs))
-	for key := range n.attrs {
-		keys = append(keys, key)
-	}
-	sort.Slice(keys, func(i, j int) bool {
-		wi, iWeighted := attributeWeight[keys[i]]
-		wj, jWeighted := attributeWeight[keys[j]]
-		switch {
-		case iWeighted && jWeighted && wi != wj:
-			return wi < wj
-		case iWeighted != jWeighted:
-			return iWeighted
-		default:
-			return keys[i] < keys[j]
-		}
-	})
-	for _, key := range keys {
-		out.WriteByte(' ')
-		out.WriteString(key)
-		out.WriteString(`="`)
-		out.WriteString(escapeXMLAttr(n.attrs[key]))
-		out.WriteByte('"')
-	}
-
-	if isVoidTag(n.tag) {
-		out.WriteString("/>")
-		return
-	}
-	out.WriteByte('>')
-	for _, child := range n.children {
-		child.writeXML(out)
-	}
-	out.WriteString("</")
-	out.WriteString(n.tag)
-	out.WriteByte('>')
-}
-
-func renderNodes(nodes []*Node) string {
-	var out strings.Builder
-	for _, node := range nodes {
-		node.writeXML(&out)
-	}
-	return out.String()
-}
-
-var attributeWeight = map[string]int{
-	"id":                0,
-	"name":              1,
-	"top-block-id":      2,
-	"parent-block-path": 3,
-	"mode":              4,
-	"start-block-id":    5,
-	"end-block-id":      6,
-	"hit-block-ids":     7,
-}
-
-func escapeXMLText(value string) string {
-	if !strings.ContainsAny(value, "&<>") {
-		return value
-	}
-	var out strings.Builder
-	out.Grow(len(value) + 8)
-	for _, r := range value {
-		switch r {
-		case '&':
-			out.WriteString("&amp;")
-		case '<':
-			out.WriteString("&lt;")
-		case '>':
-			out.WriteString("&gt;")
-		default:
-			out.WriteRune(r)
-		}
-	}
-	return out.String()
-}
-
-func escapeXMLAttr(value string) string {
-	if !strings.ContainsAny(value, "&<>\"'") {
-		return value
-	}
-	var out strings.Builder
-	out.Grow(len(value) + 8)
-	for _, r := range value {
-		switch r {
-		case '&':
-			out.WriteString("&amp;")
-		case '<':
-			out.WriteString("&lt;")
-		case '>':
-			out.WriteString("&gt;")
-		case '"':
-			out.WriteString("&#34;")
-		case '\'':
-			out.WriteString("&#39;")
-		default:
-			out.WriteRune(r)
-		}
-	}
-	return out.String()
-}

shortcuts/doc/internal/docxparse/parse_test.go

@@ -1,488 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package docxparse
-
-import (
-	"strings"
-	"testing"
-)
-
-func TestParseXMLBuildsBlockDistribution(t *testing.T) {
-	result, err := Parse(`<title>T</title><p>P</p><ul><li>A</li><li>B</li></ul>`, FormatXML)
-	if err != nil {
-		t.Fatalf("Parse() error = %v", err)
-	}
-	if result.XML != `<title>T</title><p>P</p><ul><li>A</li><li>B</li></ul>` {
-		t.Fatalf("XML = %q", result.XML)
-	}
-	if result.Profile.BlockCount != 5 {
-		t.Fatalf("block total = %d, want 5", result.Profile.BlockCount)
-	}
-	shares := map[string]BlockShare{}
-	for _, share := range result.Profile.Blocks {
-		shares[share.Type] = share
-	}
-	if got := shares["li"]; got.Count != 2 || got.Ratio != 0.4 {
-		t.Fatalf("li share = %+v, want count=2 ratio=0.4", got)
-	}
-	for _, typ := range []string{"title", "p", "ul"} {
-		if got := shares[typ]; got.Count != 1 || got.Ratio != 0.2 {
-			t.Errorf("%s share = %+v, want count=1 ratio=0.2", typ, got)
-		}
-	}
-}
-
-func TestParseXMLRejectsInvalidInput(t *testing.T) {
-	tests := []struct {
-		name   string
-		source string
-	}{
-		{name: "unsupported tag", source: `<unknown>x</unknown>`},
-		{name: "missing closing tag", source: `<p>one`},
-		{name: "invalid nesting", source: `<span>x<table><tr><td>y</td></tr></table></span>`},
-		{name: "malformed block id", source: `<block_id="8,9"/>`},
-		{name: "unterminated cdata", source: `<code><![CDATA[a < b</code>`},
-		{name: "tag spacing", source: `< p>text< / p>`},
-		{name: "self closing slash spacing", source: `<p/ >`},
-		{name: "unquoted attribute", source: `<p align=center>text</p>`},
-		{name: "invalid entity", source: `<p>one &unknown;</p>`},
-		{name: "invalid attribute entity", source: `<img href="https://example.com/&unknown;"/>`},
-		{name: "missing required ancestor", source: `<td>cell</td>`},
-		{name: "missing required attribute", source: `<img/>`},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			if _, err := Parse(tt.source, FormatXML); err == nil {
-				t.Fatalf("Parse(%q) succeeded, want validation error", tt.source)
-			}
-		})
-	}
-}
-
-func TestParseAutoDetectsXMLAndMarkdown(t *testing.T) {
-	tests := []struct {
-		name   string
-		source string
-		blocks int
-	}{
-		{name: "xml", source: `<title>T</title><p>P</p>`, blocks: 2},
-		{name: "markdown", source: "# T\n\nP", blocks: 2},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			profile, err := ParseAuto(tt.source)
-			if err != nil {
-				t.Fatalf("ParseAuto() error = %v", err)
-			}
-			if profile.BlockCount != tt.blocks {
-				t.Fatalf("profile = %+v, want %d blocks", profile, tt.blocks)
-			}
-		})
-	}
-}
-
-func TestParseAutoDoesNotTreatMalformedXMLAsMarkdown(t *testing.T) {
-	if _, err := ParseAuto(`<p>text`); err == nil {
-		t.Fatal("ParseAuto() succeeded, want malformed XML error")
-	}
-}
-
-func TestParseXMLAcceptsPublicTagAliasesWithoutChangingInput(t *testing.T) {
-	source := `<P>one<strong>two</strong><br></P><image href="https://example.com/image.png">`
-	result, err := Parse(source, FormatXML)
-	if err != nil {
-		t.Fatalf("Parse() error = %v", err)
-	}
-	if result.XML != source {
-		t.Fatalf("XML = %q, want original %q", result.XML, source)
-	}
-	if result.Profile.BlockCount != 2 {
-		t.Fatalf("profile = %+v, want p and img blocks", result.Profile)
-	}
-}
-
-func TestParseXMLAcceptsPublicAttributeAliasesWithoutChangingInput(t *testing.T) {
-	source := `<callout color="blue" icon="💡"><p>x</p></callout><at id="ou_legacy"></at><img url="https://example.com/image.png"/>`
-	result, err := Parse(source, FormatXML)
-	if err != nil {
-		t.Fatalf("Parse() error = %v", err)
-	}
-	if result.XML != source {
-		t.Fatalf("XML = %q, want original %q", result.XML, source)
-	}
-	if result.Profile.BlockCount != 3 {
-		t.Fatalf("profile = %+v, want callout, p, and img blocks", result.Profile)
-	}
-}
-
-func TestParseXMLAcceptsBareAmpersandsInAttributes(t *testing.T) {
-	source := `<block_insert><parameter><block_id>-1</block_id><content><img href="https://picsum.photos/320/200?seed=lark-cli&raw=1"/></content></parameter></block_insert>`
-	result, err := Parse(source, FormatXML)
-	if err != nil {
-		t.Fatalf("Parse() error = %v", err)
-	}
-	if result.XML != source {
-		t.Fatalf("XML = %q, want original %q", result.XML, source)
-	}
-}
-
-func TestNormalizeXMLAttributeAmpersandsPreservesEntityReferences(t *testing.T) {
-	source := `https://example.com?a=1&b=2&amp;c=3&#38;d=4&#x26;e=5&unknown;`
-	want := `https://example.com?a=1&amp;b=2&amp;c=3&#38;d=4&#x26;e=5&unknown;`
-	if got := normalizeXMLAttributeAmpersands(source); got != want {
-		t.Fatalf("normalizeXMLAttributeAmpersands() = %q, want %q", got, want)
-	}
-}
-
-func TestParseXMLPreservesValidCDATA(t *testing.T) {
-	source := `<code><![CDATA[a < b && c > d]]></code>`
-	result, err := Parse(source, FormatXML)
-	if err != nil {
-		t.Fatalf("Parse() error = %v", err)
-	}
-	if result.XML != source {
-		t.Fatalf("XML = %q, want original %q", result.XML, source)
-	}
-}
-
-func TestParseXMLPreservesUTF8BOM(t *testing.T) {
-	source := "\uFEFF<p>text</p>"
-	result, err := Parse(source, FormatXML)
-	if err != nil {
-		t.Fatalf("Parse() error = %v", err)
-	}
-	if result.XML != source {
-		t.Fatalf("XML = %q, want original input", result.XML)
-	}
-}
-
-func TestParseMarkdownConvertsLarkOpenCLIBlocks(t *testing.T) {
-	source := "# 标题\n\nHello **world**.\n\n- [x] Done\n- [ ] Todo\n\n" +
-		"| A | B |\n| --- | --- |\n| 1 | 2 |\n\n" +
-		"```go\nfmt.Println(\"x\")\n```\n\n$E=mc^2$\n"
-	result, err := Parse(source, FormatMarkdown)
-	if err != nil {
-		t.Fatalf("Parse() error = %v", err)
-	}
-	for _, fragment := range []string{
-		`<h1>标题</h1>`,
-		`<p>Hello <b>world</b>.</p>`,
-		`<checkbox done="true">Done</checkbox>`,
-		`<checkbox done="false">Todo</checkbox>`,
-		`<table><thead><tr><th>A</th><th>B</th></tr></thead><tbody><tr><td>1</td><td>2</td></tr></tbody></table>`,
-		`<pre lang="go"><code>fmt.Println("x")</code></pre>`,
-		`<p><latex>E=mc^2</latex></p>`,
-	} {
-		if !strings.Contains(result.XML, fragment) {
-			t.Errorf("XML missing %q:\n%s", fragment, result.XML)
-		}
-	}
-}
-
-func TestParseMarkdownPreservesLineBreakSemantics(t *testing.T) {
-	tests := []struct {
-		name   string
-		source string
-		want   string
-	}{
-		{
-			name:   "soft breaks become spaces",
-			source: "**文号：桂汛旱指〔2026〕17号**\n**签发人：XXX**\n**发布日期：2026年7月13日**",
-			want:   `<p><b>文号：桂汛旱指〔2026〕17号</b> <b>签发人：XXX</b> <b>发布日期：2026年7月13日</b></p>`,
-		},
-		{
-			name:   "hard breaks remain line breaks",
-			source: "**文号：A**  \n**签发人：B**",
-			want:   `<p><b>文号：A</b><br/><b>签发人：B</b></p>`,
-		},
-		{
-			name:   "blank lines remain paragraph breaks",
-			source: "**文号：A**\n\n**签发人：B**",
-			want:   `<p><b>文号：A</b></p><p><b>签发人：B</b></p>`,
-		},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			result, err := Parse(tt.source, FormatMarkdown)
-			if err != nil {
-				t.Fatalf("Parse() error = %v", err)
-			}
-			if result.XML != tt.want {
-				t.Fatalf("XML = %q, want %q", result.XML, tt.want)
-			}
-		})
-	}
-}
-
-func TestParseMarkdownContainerKeepsMarkdownChildren(t *testing.T) {
-	source := "<callout emoji=\"💡\">\n\n## Note\n\n- item\n\n</callout>\n"
-	result, err := Parse(source, FormatMarkdown)
-	if err != nil {
-		t.Fatalf("Parse() error = %v", err)
-	}
-	want := `<callout emoji="💡"><h2>Note</h2><ul><li>item</li></ul></callout>`
-	if result.XML != want {
-		t.Fatalf("XML = %q, want %q", result.XML, want)
-	}
-}
-
-func TestParseMarkdownMatchesLarkOpenCLIFixtures(t *testing.T) {
-	t.Run("deep nested list", func(t *testing.T) {
-		result, err := Parse("1. 第一层\n   - 第二层\n     - 第三层\n       - 第四层\n", FormatMarkdown)
-		if err != nil {
-			t.Fatalf("Parse() error = %v", err)
-		}
-		if strings.Contains(result.XML, "<pre>") || strings.Contains(result.XML, "<code>") || !strings.Contains(result.XML, "第四层") {
-			t.Fatalf("nested list converted incorrectly: %s", result.XML)
-		}
-	})
-
-	t.Run("fenced mermaid", func(t *testing.T) {
-		result, err := Parse("```mermaid\nflowchart LR\nA-->B\n```", FormatMarkdown)
-		if err != nil {
-			t.Fatalf("Parse() error = %v", err)
-		}
-		want := `<whiteboard type="mermaid">flowchart LR<br/>A--&gt;B</whiteboard>`
-		if result.XML != want {
-			t.Fatalf("XML = %q, want %q", result.XML, want)
-		}
-	})
-
-	t.Run("raw whiteboard source", func(t *testing.T) {
-		source := "<whiteboard type=\"mermaid\">\nflowchart LR\n  A --> B\n</whiteboard>"
-		result, err := Parse(source, FormatMarkdown)
-		if err != nil {
-			t.Fatalf("Parse() error = %v", err)
-		}
-		want := `<whiteboard type="mermaid">flowchart LR<br/>  A --&gt; B</whiteboard>`
-		if result.XML != want {
-			t.Fatalf("XML = %q, want %q", result.XML, want)
-		}
-	})
-
-	t.Run("raw code stays literal", func(t *testing.T) {
-		source := "<code lang=\"go\">\nif a < b && c > d {\n  fmt.Println(\"**raw**\")\n}\n</code>"
-		result, err := Parse(source, FormatMarkdown)
-		if err != nil {
-			t.Fatalf("Parse() error = %v", err)
-		}
-		want := `<code lang="go">if a &lt; b &amp;&amp; c &gt; d {<br/>  fmt.Println("**raw**")<br/>}</code>`
-		if result.XML != want {
-			t.Fatalf("XML = %q, want %q", result.XML, want)
-		}
-	})
-
-	t.Run("underscore tags", func(t *testing.T) {
-		result, err := Parse(`text <synced_reference src-block-id="abc" src-token="def"/> more`, FormatMarkdown)
-		if err != nil {
-			t.Fatalf("Parse() error = %v", err)
-		}
-		if !strings.Contains(result.XML, `<synced_reference`) || strings.Contains(result.XML, `&lt;synced_reference`) {
-			t.Fatalf("underscore tag was not preserved: %s", result.XML)
-		}
-	})
-
-	t.Run("canonical user cite", func(t *testing.T) {
-		result, err := Parse(`hello <cite type="user" user-id="ou_user"></cite>`, FormatMarkdown)
-		if err != nil {
-			t.Fatalf("Parse() error = %v", err)
-		}
-		for _, want := range []string{`<cite`, `type="user"`, `user-id="ou_user"`} {
-			if !strings.Contains(result.XML, want) {
-				t.Errorf("XML missing %q: %s", want, result.XML)
-			}
-		}
-	})
-
-	t.Run("public tag alias converts to canonical XML", func(t *testing.T) {
-		result, err := Parse(`hello <strong>world</strong>`, FormatMarkdown)
-		if err != nil {
-			t.Fatalf("Parse() error = %v", err)
-		}
-		if result.XML != `<p>hello <b>world</b></p>` {
-			t.Fatalf("XML = %q", result.XML)
-		}
-	})
-
-	t.Run("public cite alias converts attributes", func(t *testing.T) {
-		result, err := Parse(`hello <at id="ou_legacy"></at>`, FormatMarkdown)
-		if err != nil {
-			t.Fatalf("Parse() error = %v", err)
-		}
-		if result.XML != `<p>hello <cite type="user" user-id="ou_legacy"></cite></p>` {
-			t.Fatalf("XML = %q", result.XML)
-		}
-	})
-
-	t.Run("markdown backslash escapes", func(t *testing.T) {
-		result, err := Parse(`"source\_token": \[abc\] path\\to`, FormatMarkdown)
-		if err != nil {
-			t.Fatalf("Parse() error = %v", err)
-		}
-		for _, want := range []string{`source_token`, `[abc]`, `path\to`} {
-			if !strings.Contains(result.XML, want) {
-				t.Errorf("XML missing %q: %s", want, result.XML)
-			}
-		}
-	})
-
-	t.Run("adjacent CJK emphasis", func(t *testing.T) {
-		source := `***你好。***S 和 ~~再见。~~T。**agent team 做 brownfield 项目，带来的感知会强烈得多**——前提。**这个时刻，才是真正属于 agent team 的"闪光时刻"。**翟霖`
-		result, err := Parse(source, FormatMarkdown)
-		if err != nil {
-			t.Fatalf("Parse() error = %v", err)
-		}
-		for _, want := range []string{
-			`<em><b>你好。</b></em>S`,
-			`<del>再见。</del>T`,
-			`<b>agent team 做 brownfield 项目，带来的感知会强烈得多</b>`,
-			`<b>这个时刻，才是真正属于 agent team 的"闪光时刻"。</b>翟霖`,
-		} {
-			if !strings.Contains(result.XML, want) {
-				t.Errorf("XML missing %q: %s", want, result.XML)
-			}
-		}
-	})
-
-	t.Run("div parses markdown children", func(t *testing.T) {
-		result, err := Parse("<div>\n\n**bold**\n\n</div>", FormatMarkdown)
-		if err != nil {
-			t.Fatalf("Parse() error = %v", err)
-		}
-		if result.XML != `<div><p><b>bold</b></p></div>` {
-			t.Fatalf("XML = %q", result.XML)
-		}
-	})
-}
-
-func TestPreprocessCJKAdjacentMarkupUsesRuneOffsetsAfterRawBlock(t *testing.T) {
-	tests := []struct {
-		name       string
-		lineEnding string
-		final      string
-	}{
-		{name: "EOF", lineEnding: "\n"},
-		{name: "LF", lineEnding: "\n", final: "\n"},
-		{name: "CRLF", lineEnding: "\r\n", final: "\r\n"},
-	}
-
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			source := "<code>**raw**" + tt.lineEnding + "Ⱥ</code>**你好。**S" + tt.final
-			want := "<code>**raw**" + tt.lineEnding + "Ⱥ</code><b>你好。</b>S" + tt.final
-			if got := preprocessCJKAdjacentMarkup(source); got != want {
-				t.Fatalf("preprocessCJKAdjacentMarkup() = %q, want %q", got, want)
-			}
-		})
-	}
-}
-
-func TestTextProfileMatchesLarkOpenCLIContract(t *testing.T) {
-	result, err := Parse(`<title>标题</title><p>一个苹果是 an apple。</p>`, FormatXML)
-	if err != nil {
-		t.Fatalf("Parse() error = %v", err)
-	}
-	profile := result.Profile
-	if profile.WordCount != 10 || profile.CharCount != 15 {
-		t.Fatalf("profile = %+v, want word_count=10 char_count=15", profile)
-	}
-	if profile.Breakdown.HanChars != 7 || profile.Breakdown.EnglishWords != 2 || profile.Breakdown.ChinesePunctuations != 1 {
-		t.Fatalf("breakdown = %+v", profile.Breakdown)
-	}
-}
-
-func TestTextProfileMatchesAuthoringCounterCases(t *testing.T) {
-	tests := []struct {
-		name      string
-		source    string
-		words     int
-		chars     int
-		blocks    int
-		english   int
-		numbers   int
-		han       int
-		listItems int
-	}{
-		{
-			name:   "english number and punctuation",
-			source: `<p>Hello world 123.45。</p>`,
-			words:  4, chars: 17, blocks: 1, english: 2, numbers: 1,
-		},
-		{
-			name:   "list and checkbox markers",
-			source: `<ul><li>甲</li><li>two</li></ul><checkbox done="true">完成</checkbox>`,
-			words:  7, chars: 9, blocks: 4, english: 1, han: 3, listItems: 2,
-		},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			result, err := Parse(tt.source, FormatXML)
-			if err != nil {
-				t.Fatalf("Parse() error = %v", err)
-			}
-			profile := result.Profile
-			if profile.WordCount != tt.words || profile.CharCount != tt.chars || profile.BlockCount != tt.blocks {
-				t.Fatalf("profile = %+v, want words=%d chars=%d blocks=%d", profile, tt.words, tt.chars, tt.blocks)
-			}
-			if profile.Breakdown.EnglishWords != tt.english || profile.Breakdown.NumberWords != tt.numbers || profile.Breakdown.HanChars != tt.han {
-				t.Fatalf("breakdown = %+v", profile.Breakdown)
-			}
-			if got := blockCountForTest(profile.Blocks, "li"); got != tt.listItems {
-				t.Fatalf("li count = %d, want %d", got, tt.listItems)
-			}
-		})
-	}
-}
-
-func TestTextProfileUsesVisibleAttributeFallbacks(t *testing.T) {
-	result, err := Parse(`<p text="Hello"/><p><span title="world"/></p><img href="https://example.com/image.png" caption="图"/>`, FormatXML)
-	if err != nil {
-		t.Fatalf("Parse() error = %v", err)
-	}
-	profile := result.Profile
-	if profile.WordCount != 3 || profile.CharCount != 11 {
-		t.Fatalf("profile = %+v, want word_count=3 char_count=11", profile)
-	}
-	if profile.Breakdown.EnglishWords != 2 || profile.Breakdown.HanChars != 1 {
-		t.Fatalf("breakdown = %+v", profile.Breakdown)
-	}
-}
-
-func TestParseRejectsUnsafeXMLDeclarations(t *testing.T) {
-	_, err := Parse(`<!DOCTYPE foo [<!ENTITY x "value">]><p>&x;</p>`, FormatXML)
-	if err == nil || !strings.Contains(err.Error(), "DOCTYPE or ENTITY") {
-		t.Fatalf("Parse() error = %v, want unsafe declaration rejection", err)
-	}
-}
-
-func TestParseRejectsInvalidUTF8(t *testing.T) {
-	_, err := Parse(string([]byte{'<', 'p', '>', 0xff, '<', '/', 'p', '>'}), FormatXML)
-	if err == nil || !strings.Contains(err.Error(), "valid UTF-8") {
-		t.Fatalf("Parse() error = %v, want UTF-8 rejection", err)
-	}
-}
-
-func TestParseRejectsExcessiveNesting(t *testing.T) {
-	source := strings.Repeat("<span>", MaxNestingDepth+1)
-	_, err := Parse(source, FormatXML)
-	if err == nil || !strings.Contains(err.Error(), "nesting exceeds") {
-		t.Fatalf("Parse() error = %v, want nesting limit rejection", err)
-	}
-}
-
-func TestParseXMLRejectsNestedInvalidTagStarts(t *testing.T) {
-	if _, err := Parse(`<<<<p>text</p>`, FormatXML); err == nil {
-		t.Fatal("Parse() succeeded, want invalid XML token error")
-	}
-}
-
-func blockCountForTest(blocks []BlockShare, typ string) int {
-	for _, block := range blocks {
-		if block.Type == typ {
-			return block.Count
-		}
-	}
-	return 0
-}

shortcuts/doc/internal/docxparse/profile.go

@@ -1,397 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package docxparse
-
-import (
-	"fmt"
-	"math"
-	"sort"
-	"strings"
-)
-
-// Profile describes LarkOpenCLI document structure and visible text without
-// requiring callers to inspect the full XML.
-type Profile struct {
-	WordCount  int           `json:"word_count"`
-	CharCount  int           `json:"char_count"`
-	Breakdown  TextBreakdown `json:"breakdown"`
-	BlockCount int           `json:"block_count"`
-	Blocks     []BlockShare  `json:"blocks"`
-}
-
-// BlockShare reports one LarkOpenCLI block type's count and share. Structural
-// and inline-only tags are intentionally excluded.
-type BlockShare struct {
-	Type  string  `json:"type"`
-	Count int     `json:"count"`
-	Ratio float64 `json:"ratio"`
-}
-
-// TextProfile is the internal result of the LarkOpenCLI semantic counter.
-type TextProfile struct {
-	WordCount int           `json:"word_count"`
-	CharCount int           `json:"char_count"`
-	Breakdown TextBreakdown `json:"breakdown"`
-}
-
-type TextBreakdown struct {
-	HanChars            int `json:"han_chars"`
-	EnglishWords        int `json:"english_words"`
-	NumberWords         int `json:"number_words"`
-	ChinesePunctuations int `json:"chinese_punctuations"`
-	EnglishLetters      int `json:"english_letters"`
-	Digits              int `json:"digits"`
-	EnglishPunctuations int `json:"english_punctuations"`
-	SymbolWords         int `json:"symbol_words"`
-	SymbolChars         int `json:"symbol_chars"`
-}
-
-// Parse validates XML or converts Markdown to DocxXML, then builds its
-// structure and visible-text profile.
-func Parse(source string, format Format) (ParseResult, error) {
-	var (
-		nodes     []*Node
-		outputXML string
-		err       error
-	)
-	switch format {
-	case FormatXML:
-		nodes, err = parseXML(source)
-		outputXML = source
-	case FormatMarkdown:
-		nodes, err = parseMarkdown(source)
-	default:
-		return ParseResult{}, fmt.Errorf("unsupported input format %q", format)
-	}
-	if err != nil {
-		return ParseResult{}, err
-	}
-	if err := validateStructure(nodes); err != nil {
-		return ParseResult{}, err
-	}
-	if format == FormatMarkdown {
-		outputXML = renderNodes(nodes)
-	}
-
-	return ParseResult{
-		Format:  format,
-		XML:     outputXML,
-		Profile: buildProfile(nodes),
-	}, nil
-}
-
-// ParseAuto detects XML versus Markdown from the content and returns only the
-// document profile. XML-like input is parsed strictly; all other input is
-// interpreted as Markdown.
-func ParseAuto(source string) (Profile, error) {
-	result, err := Parse(source, detectFormat(source))
-	if err != nil {
-		return Profile{}, err
-	}
-	return result.Profile, nil
-}
-
-// MarkdownToXML converts Markdown to canonical LarkOpenCLI XML.
-func MarkdownToXML(source string) (string, error) {
-	result, err := Parse(source, FormatMarkdown)
-	if err != nil {
-		return "", err
-	}
-	return result.XML, nil
-}
-
-func detectFormat(source string) Format {
-	trimmed := strings.TrimSpace(strings.TrimPrefix(source, "\uFEFF"))
-	if strings.HasPrefix(trimmed, "<") {
-		return FormatXML
-	}
-	return FormatMarkdown
-}
-
-func validateStructure(nodes []*Node) error {
-	type frame struct {
-		node *Node
-		exit bool
-	}
-	frames := make([]frame, 0, len(nodes))
-	for i := len(nodes) - 1; i >= 0; i-- {
-		frames = append(frames, frame{node: nodes[i]})
-	}
-	ancestors := map[string]int{}
-	depth := 0
-	for len(frames) > 0 {
-		current := frames[len(frames)-1]
-		frames = frames[:len(frames)-1]
-		node := current.node
-		if node == nil || node.typ != nodeElement {
-			continue
-		}
-		if current.exit {
-			ancestors[node.tag]--
-			depth--
-			continue
-		}
-		if depth >= MaxNestingDepth {
-			return fmt.Errorf("document nesting exceeds limit %d at <%s>", MaxNestingDepth, node.tag)
-		}
-		if err := validateRequiredAttributes(node); err != nil {
-			return err
-		}
-		if required := requiredAncestorTags[node.tag]; len(required) > 0 {
-			matched := false
-			for tag := range required {
-				if ancestors[tag] > 0 {
-					matched = true
-					break
-				}
-			}
-			if !matched {
-				allowed := make([]string, 0, len(required))
-				for tag := range required {
-					allowed = append(allowed, tag)
-				}
-				sort.Strings(allowed)
-				return fmt.Errorf("LarkOpenCLI tag <%s> requires an ancestor in [%s]", node.tag, strings.Join(allowed, ", "))
-			}
-		}
-
-		ancestors[node.tag]++
-		depth++
-		frames = append(frames, frame{node: node, exit: true})
-		for i := len(node.children) - 1; i >= 0; i-- {
-			frames = append(frames, frame{node: node.children[i]})
-		}
-	}
-	return nil
-}
-
-func validateRequiredAttributes(node *Node) error {
-	for _, attr := range requiredAttributes[node.tag] {
-		if strings.TrimSpace(node.attrs[attr]) == "" {
-			return fmt.Errorf("LarkOpenCLI tag <%s> requires attribute %q", node.tag, attr)
-		}
-	}
-	for _, alternatives := range requiredAnyAttributes[node.tag] {
-		matched := false
-		for _, attr := range alternatives {
-			if strings.TrimSpace(node.attrs[attr]) != "" {
-				matched = true
-				break
-			}
-		}
-		if !matched {
-			return fmt.Errorf("LarkOpenCLI tag <%s> requires one of attributes [%s]", node.tag, strings.Join(alternatives, ", "))
-		}
-	}
-	return nil
-}
-
-func buildProfile(nodes []*Node) Profile {
-	counts := map[string]int{}
-	total := 0
-	var walk func(*Node)
-	walk = func(node *Node) {
-		if node == nil || node.typ != nodeElement {
-			return
-		}
-		layout := layoutOf(node.tag)
-		isBlock := layout == layoutBlock || layout == layoutDual && node.parent == nil
-		if isBlock {
-			counts[node.tag]++
-			total++
-		}
-		for _, child := range node.children {
-			walk(child)
-		}
-	}
-	for _, node := range nodes {
-		walk(node)
-	}
-
-	distribution := make([]BlockShare, 0, len(counts))
-	for typ, count := range counts {
-		ratio := 0.0
-		if total > 0 {
-			ratio = math.Round(float64(count)/float64(total)*1_000_000) / 1_000_000
-		}
-		distribution = append(distribution, BlockShare{Type: typ, Count: count, Ratio: ratio})
-	}
-	sort.Slice(distribution, func(i, j int) bool {
-		if distribution[i].Count != distribution[j].Count {
-			return distribution[i].Count > distribution[j].Count
-		}
-		return distribution[i].Type < distribution[j].Type
-	})
-	segments := extractSegments(nodes)
-	stats := newTextCounter().countSegments(segments)
-	return Profile{
-		WordCount:  stats.WordCount,
-		CharCount:  stats.CharCount,
-		Breakdown:  stats.Breakdown,
-		BlockCount: total,
-		Blocks:     distribution,
-	}
-}
-
-type segmentKind uint8
-
-const (
-	segmentText segmentKind = iota
-	segmentMarker
-	segmentCode
-)
-
-type textSegment struct {
-	text string
-	kind segmentKind
-}
-
-var ignoredResourceTags = map[string]bool{
-	"whiteboard": true, "sheet": true, "source": true, "chat_card": true,
-	"base_refer": true, "bitable": true, "synced_reference": true,
-	"poll": true, "isv": true, "mindnote": true, "sub-page-list": true,
-	"okr": true, "html5-block": true,
-}
-
-var ignoredInlineTags = map[string]bool{
-	"button": true, "cite": true, "latex": true, "bookmark": true,
-}
-
-func extractSegments(nodes []*Node) []textSegment {
-	var segments []textSegment
-	for _, node := range nodes {
-		extractNodeSegments(node, &segments)
-	}
-	return segments
-}
-
-func extractNodeSegments(node *Node, segments *[]textSegment) {
-	if node == nil {
-		return
-	}
-	if node.typ == nodeText {
-		if strings.TrimSpace(node.text) != "" {
-			*segments = append(*segments, textSegment{text: node.text})
-		}
-		return
-	}
-	if ignoredInlineTags[node.tag] || ignoredResourceTags[node.tag] {
-		return
-	}
-	if node.tag == "task" {
-		return
-	}
-	if node.tag == "synced-source" && len(node.children) == 0 {
-		return
-	}
-
-	switch node.tag {
-	case "ul", "ol":
-		sequence := 1
-		for _, child := range node.children {
-			if child.typ == nodeElement && child.tag == "li" {
-				if node.tag == "ul" {
-					*segments = append(*segments, textSegment{text: "•", kind: segmentMarker})
-				} else {
-					marker := sequence
-					if raw := child.attrs["seq"]; raw != "" {
-						if _, err := fmt.Sscanf(raw, "%d", &marker); err == nil {
-							sequence = marker
-						}
-					}
-					*segments = append(*segments, textSegment{text: fmt.Sprintf("%d.", marker)})
-					sequence++
-				}
-			}
-			extractNodeSegments(child, segments)
-		}
-		return
-	case "checkbox":
-		marker := "☐"
-		if node.attrs["done"] == "true" {
-			marker = "☑"
-		}
-		*segments = append(*segments, textSegment{text: marker, kind: segmentMarker})
-	}
-
-	kind := segmentText
-	if node.tag == "pre" || node.tag == "code" && (node.parent == nil || node.parent.tag != "p") {
-		kind = segmentCode
-	}
-	text := visibleInlineText(node)
-	if strings.TrimSpace(text) == "" && !hasBlockChildren(node) {
-		if node.tag == "img" {
-			text = node.attrs["caption"]
-		} else {
-			text = firstNonEmpty(node.attrs["text"], node.attrs["name"], node.attrs["title"], node.attrs["alt"], node.attrs["caption"])
-		}
-	}
-	if strings.TrimSpace(text) != "" {
-		*segments = append(*segments, textSegment{text: text, kind: kind})
-	}
-
-	for _, child := range node.children {
-		if child.typ != nodeElement || isInlineForExtraction(child.tag) {
-			continue
-		}
-		extractNodeSegments(child, segments)
-	}
-}
-
-func visibleInlineText(node *Node) string {
-	var out strings.Builder
-	var walk func(*Node)
-	walk = func(current *Node) {
-		if current.typ == nodeText {
-			out.WriteString(current.text)
-			return
-		}
-		if current != node && !isInlineForExtraction(current.tag) {
-			return
-		}
-		if ignoredInlineTags[current.tag] {
-			return
-		}
-		if current.tag == "br" {
-			out.WriteByte('\n')
-			return
-		}
-		if current != node {
-			if display := firstNonEmpty(current.attrs["text"], current.attrs["name"], current.attrs["title"], current.attrs["alt"]); display != "" {
-				out.WriteString(display)
-				return
-			}
-		}
-		for _, child := range current.children {
-			walk(child)
-		}
-	}
-	for _, child := range node.children {
-		walk(child)
-	}
-	return out.String()
-}
-
-func hasBlockChildren(node *Node) bool {
-	for _, child := range node.children {
-		if child.typ == nodeElement && !isInlineForExtraction(child.tag) {
-			return true
-		}
-	}
-	return false
-}
-
-func isInlineForExtraction(tag string) bool {
-	layout := layoutOf(tag)
-	return layout == layoutInline || layout == layoutDual
-}
-
-func firstNonEmpty(values ...string) string {
-	for _, value := range values {
-		if value != "" {
-			return value
-		}
-	}
-	return ""
-}

shortcuts/doc/internal/docxparse/schema.go

@@ -1,268 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package docxparse
-
-import (
-	"sort"
-	"strconv"
-	"strings"
-)
-
-type tagLayout string
-
-const (
-	layoutBlock      tagLayout = "block"
-	layoutInline     tagLayout = "inline"
-	layoutDual       tagLayout = "dual"
-	layoutStructural tagLayout = "structural"
-	layoutCommand    tagLayout = "command"
-)
-
-type tagSpec struct {
-	canonical string
-	layout    tagLayout
-}
-
-var tagSpecs = map[string]tagSpec{}
-
-// tagAliases mirrors the public compatibility aliases declared by the
-// LarkOpenCLI SDK. Parsing keeps the caller's XML unchanged; aliases are only
-// canonicalized in the in-memory tree used for profiling and Markdown output.
-var tagAliases = map[string]string{
-	"strong":           "b",
-	"text":             "span",
-	"equation":         "latex",
-	"lark-table":       "table",
-	"lark-tr":          "tr",
-	"lark-td":          "td",
-	"image":            "img",
-	"reference-synced": "synced_reference",
-	"source-synced":    "synced-source",
-	"at":               "cite",
-	"chat-card":        "chat_card",
-	"folder_manager":   "folder-manager",
-}
-
-type attributeAliasRule struct {
-	canonical string
-	transform func(string) (string, bool)
-}
-
-var commonAttributeAliases = map[string]attributeAliasRule{
-	"color":            {canonical: "text-color"},
-	"textcolor":        {canonical: "text-color"},
-	"text_color":       {canonical: "text-color"},
-	"bgcolor":          {canonical: "background-color"},
-	"background_color": {canonical: "background-color"},
-}
-
-var tagAttributeAliases = map[string]map[string]attributeAliasRule{
-	"img": {
-		"url":      {canonical: "href"},
-		"file_key": {canonical: "img_key"},
-	},
-	"callout": {
-		"color": {canonical: "background-color"},
-		"icon":  {canonical: "emoji"},
-	},
-	"column": {
-		"width": {canonical: "width-ratio", transform: normalizeWidthRatio},
-	},
-	"chat_card": {
-		"id": {canonical: "chat-id", transform: requireChatID},
-	},
-	"cite": {
-		"user_id": {canonical: "user-id"},
-	},
-}
-
-var rawTagAttributeAliases = map[string]map[string]attributeAliasRule{
-	"at": {
-		"id":      {canonical: "user-id"},
-		"user_id": {canonical: "user-id"},
-	},
-}
-
-var requiredAttributes = map[string][]string{
-	"task": {"task-id"},
-}
-
-var requiredAnyAttributes = map[string][][]string{
-	"img":        {{"src", "img_key", "href"}},
-	"whiteboard": {{"token", "type"}},
-	"chat_card":  {{"token", "chat-id"}},
-	"bookmark":   {{"href", "name"}},
-}
-
-func init() {
-	registerTags(layoutBlock,
-		"title", "h1", "h2", "h3", "h4", "h5", "h6", "h7", "h8", "h9", "p",
-		"div", "ul", "ol", "li", "blockquote", "grid", "column", "table", "thead",
-		"tbody", "tfoot", "tr", "hr", "pre", "img", "source", "bitable", "sheet",
-		"mindnote", "whiteboard", "base_refer", "synced_reference", "isv", "html5-block",
-		"view", "synced-source", "readonly-block", "figure", "callout", "checkbox",
-		"chat_card", "okr", "okr-objective", "okr-key-result", "okr-progress", "poll",
-		"agenda", "folder-manager", "sub-page-list", "wiki_catalog", "wiki_recent_update",
-		"chart-embedded", "chart-refer-host-perm", "chart_embedded", "chart_refer_host_perm",
-		"bookmark", "task", "vc-tabs", "vc-summary-tab", "vc-transcribe-tab", "append",
-	)
-	registerTags(layoutInline, "b", "em", "u", "del", "i", "span", "br", "inline-file", "mention-date", "cite", "button", "time", "a")
-	registerTags(layoutDual, "latex", "code")
-	registerTags(layoutStructural, "th", "td", "colgroup", "col", "sub-page")
-	registerTags(layoutCommand,
-		"comment", "block_delete", "str_delete", "str_replace", "block_replace", "block_insert",
-		"block_move", "block_copy_insert_after", "src_block_ids", "create", "answer", "response",
-		"identifier", "genre", "anchor", "type", "revision", "pattern", "replacement",
-		"replace_content", "action", "content", "parameter", "generation", "block_id",
-	)
-
-}
-
-func registerTags(layout tagLayout, tags ...string) {
-	for _, tag := range tags {
-		tagSpecs[tag] = tagSpec{canonical: tag, layout: layout}
-	}
-}
-
-func lookupTag(raw string) (tagSpec, bool) {
-	key := strings.ToLower(strings.TrimSpace(raw))
-	if canonical, ok := tagAliases[key]; ok {
-		key = canonical
-	}
-	spec, ok := tagSpecs[key]
-	if !ok {
-		return tagSpec{}, false
-	}
-	return spec, true
-}
-
-func layoutOf(tag string) tagLayout {
-	spec, ok := lookupTag(tag)
-	if !ok {
-		return ""
-	}
-	return spec.layout
-}
-
-var voidTags = map[string]bool{
-	"br":       true,
-	"col":      true,
-	"hr":       true,
-	"img":      true,
-	"source":   true,
-	"sub-page": true,
-}
-
-func isVoidTag(tag string) bool { return voidTags[tag] }
-
-var preserveSpaceTags = map[string]bool{
-	"title": true, "h1": true, "h2": true, "h3": true, "h4": true,
-	"h5": true, "h6": true, "h7": true, "h8": true, "h9": true,
-	"p": true, "i": true, "b": true, "em": true, "u": true, "del": true,
-	"code": true, "li": true, "a": true, "span": true,
-}
-
-var strictPhrasingTags = map[string]bool{
-	"title": true, "span": true, "b": true, "em": true,
-	"u": true, "del": true, "a": true,
-}
-
-var autoCloseTags = map[string]map[string]bool{
-	"li":     {"li": true},
-	"tr":     {"tr": true},
-	"td":     {"td": true, "th": true, "tr": true, "tbody": true, "tfoot": true},
-	"th":     {"th": true, "td": true, "tr": true, "tbody": true, "tfoot": true},
-	"tbody":  {"tbody": true, "tfoot": true},
-	"thead":  {"tbody": true, "tfoot": true},
-	"column": {"column": true},
-}
-
-var requiredAncestorTags = map[string]map[string]bool{
-	"column":         {"grid": true},
-	"thead":          {"table": true},
-	"tbody":          {"table": true},
-	"tfoot":          {"table": true},
-	"tr":             {"table": true, "thead": true, "tbody": true, "tfoot": true},
-	"th":             {"tr": true},
-	"td":             {"tr": true},
-	"colgroup":       {"table": true},
-	"col":            {"table": true, "colgroup": true},
-	"okr-objective":  {"okr": true},
-	"okr-key-result": {"okr": true, "okr-objective": true},
-	"okr-progress":   {"okr-objective": true, "okr-key-result": true},
-	"sub-page":       {"sub-page-list": true},
-}
-
-func shouldAutoClose(openTag, nextTag string) bool {
-	if strictPhrasingTags[openTag] && layoutOf(nextTag) == layoutBlock {
-		return true
-	}
-	return autoCloseTags[openTag] != nil && autoCloseTags[openTag][nextTag]
-}
-
-func normalizeAttributes(rawTag, canonical string, attrs map[string]string) map[string]string {
-	rules := make(map[string]attributeAliasRule, len(commonAttributeAliases)+4)
-	for alias, rule := range commonAttributeAliases {
-		rules[alias] = rule
-	}
-	for alias, rule := range tagAttributeAliases[canonical] {
-		rules[alias] = rule
-	}
-	rawKey := strings.ToLower(strings.TrimSpace(rawTag))
-	for alias, rule := range rawTagAttributeAliases[rawKey] {
-		rules[alias] = rule
-	}
-
-	aliases := make([]string, 0, len(rules))
-	for alias := range rules {
-		aliases = append(aliases, alias)
-	}
-	sort.Strings(aliases)
-	for _, alias := range aliases {
-		value, exists := attrs[alias]
-		if !exists {
-			continue
-		}
-		rule := rules[alias]
-		if rule.transform != nil {
-			var ok bool
-			value, ok = rule.transform(value)
-			if !ok {
-				continue
-			}
-		}
-		if canonicalValue, exists := attrs[rule.canonical]; !exists || strings.TrimSpace(canonicalValue) == "" {
-			if attrs == nil {
-				attrs = map[string]string{}
-			}
-			attrs[rule.canonical] = value
-		}
-		delete(attrs, alias)
-	}
-
-	if rawKey == "at" {
-		if attrs == nil {
-			attrs = map[string]string{}
-		}
-		attrs["type"] = "user"
-	}
-	return attrs
-}
-
-func normalizeWidthRatio(value string) (string, bool) {
-	trimmed := strings.TrimSuffix(strings.TrimSpace(value), "%")
-	if trimmed == "" {
-		return value, false
-	}
-	width, err := strconv.ParseFloat(trimmed, 64)
-	if err != nil {
-		return value, false
-	}
-	return strconv.FormatFloat(width/100, 'f', 6, 64), true
-}
-
-func requireChatID(value string) (string, bool) {
-	trimmed := strings.TrimSpace(value)
-	return trimmed, strings.HasPrefix(trimmed, "oc_")
-}

shortcuts/doc/internal/docxparse/wordcount.go

@@ -1,342 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package docxparse
-
-// This file implements the LarkOpenCLI document text-counting contract.
-
-import (
-	"regexp"
-	"strings"
-	"unicode"
-	"unicode/utf8"
-
-	"golang.org/x/text/width"
-)
-
-const chinesePunctuation = "，。！？；：、（）《》〈〉“”‘’【】「」『』〔〕…—～·￥"
-const englishPunctuation = `!"#$%&'()*+,-./:;<=>?@[\]^_` + "`" + `{|}~`
-
-var (
-	urlToken           = regexp.MustCompile(`^https?://[!-~]+`)
-	asciiCompoundToken = regexp.MustCompile(`^[A-Za-z0-9]+(?:[._/@:-][A-Za-z0-9]+)+`)
-)
-
-type lexemeKind uint8
-
-const (
-	lexemeNone lexemeKind = iota
-	lexemeEnglish
-	lexemeNumber
-)
-
-type textCounter struct {
-	stats           TextProfile
-	lexeme          lexemeKind
-	lexemeHasDigit  bool
-	symbolRunLength int
-	atBoundary      bool
-}
-
-func newTextCounter() *textCounter {
-	return &textCounter{atBoundary: true}
-}
-
-func (c *textCounter) countSegments(segments []textSegment) TextProfile {
-	for _, segment := range segments {
-		c.endUnit()
-		c.atBoundary = true
-		switch segment.kind {
-		case segmentMarker:
-			c.writeMarker(segment.text)
-		case segmentCode:
-			c.writeCode(segment.text)
-		default:
-			c.write(segment.text)
-		}
-		c.endUnit()
-		c.atBoundary = true
-	}
-	c.endUnit()
-	return c.stats
-}
-
-func (c *textCounter) write(value string) {
-	for offset := 0; offset < len(value); {
-		if token := matchASCIICompound(value[offset:]); token != "" {
-			c.writeASCIICompound(token)
-			offset += len(token)
-			continue
-		}
-		r, size := utf8.DecodeRuneInString(value[offset:])
-		if r == '/' && isVisibleHanSeparator(value, offset, size) {
-			c.endUnit()
-			c.stats.Breakdown.EnglishPunctuations++
-			c.stats.Breakdown.SymbolWords++
-			c.stats.WordCount++
-			c.stats.CharCount++
-			c.atBoundary = false
-			offset += size
-			continue
-		}
-		c.writeRune(r)
-		offset += size
-	}
-}
-
-func (c *textCounter) writeMarker(value string) {
-	for _, r := range value {
-		if unicode.IsSpace(r) {
-			continue
-		}
-		c.endUnit()
-		c.stats.WordCount++
-		c.stats.CharCount++
-		c.atBoundary = false
-	}
-}
-
-func (c *textCounter) writeCode(value string) {
-	for _, r := range value {
-		c.writeCodeRune(r)
-	}
-}
-
-func (c *textCounter) writeCodeRune(r rune) {
-	if unicode.IsSpace(r) {
-		c.endUnit()
-		c.atBoundary = true
-		return
-	}
-	if unicode.Is(unicode.Han, r) {
-		c.endLexeme()
-		c.endSymbolRun(false)
-		c.stats.Breakdown.HanChars++
-		c.stats.WordCount++
-		c.stats.CharCount++
-		c.atBoundary = false
-		return
-	}
-	if isASCIILetterRune(r) {
-		c.endSymbolRun(false)
-		c.stats.Breakdown.EnglishLetters++
-		c.stats.CharCount++
-		if c.lexeme == lexemeNone || c.lexeme == lexemeNumber {
-			c.lexeme = lexemeEnglish
-		}
-		c.atBoundary = false
-		return
-	}
-	if isASCIIDigitRune(r) {
-		c.endSymbolRun(false)
-		c.stats.Breakdown.Digits++
-		c.stats.CharCount++
-		c.atBoundary = false
-		return
-	}
-	if isChinesePunctuation(r) {
-		c.endLexeme()
-		c.endSymbolRun(false)
-		c.stats.Breakdown.ChinesePunctuations++
-		c.stats.WordCount++
-		c.stats.CharCount++
-		c.atBoundary = false
-		return
-	}
-	if isEnglishPunctuation(r) {
-		keepsLexeme := c.lexeme == lexemeEnglish && (r == '\'' || r == '-')
-		if !keepsLexeme {
-			hadLexeme := c.lexeme != lexemeNone
-			c.endLexeme()
-			if !hadLexeme && (c.symbolRunLength > 0 || c.atBoundary) {
-				c.symbolRunLength++
-			}
-		}
-		c.stats.Breakdown.EnglishPunctuations++
-		c.stats.CharCount++
-		if keepsLexeme {
-			c.atBoundary = false
-		}
-		return
-	}
-	if unicode.Is(unicode.Symbol, r) {
-		c.writeSymbol(r)
-		return
-	}
-	c.endLexeme()
-	c.endSymbolRun(false)
-	c.atBoundary = false
-}
-
-func (c *textCounter) writeRune(r rune) {
-	if unicode.IsSpace(r) {
-		c.endUnit()
-		c.atBoundary = true
-		return
-	}
-	if unicode.Is(unicode.Han, r) {
-		c.endLexeme()
-		c.endSymbolRun(false)
-		c.stats.Breakdown.HanChars++
-		c.stats.WordCount++
-		c.stats.CharCount++
-		c.atBoundary = false
-		return
-	}
-	if isASCIILetterRune(r) {
-		c.endSymbolRun(false)
-		c.stats.Breakdown.EnglishLetters++
-		c.stats.CharCount++
-		if c.lexeme == lexemeNone || c.lexeme == lexemeNumber {
-			c.lexeme = lexemeEnglish
-		}
-		c.atBoundary = false
-		return
-	}
-	if isASCIIDigitRune(r) {
-		c.endSymbolRun(false)
-		c.stats.Breakdown.Digits++
-		c.stats.CharCount++
-		c.lexemeHasDigit = true
-		if c.lexeme == lexemeNone {
-			c.lexeme = lexemeNumber
-		}
-		c.atBoundary = false
-		return
-	}
-	if isChinesePunctuation(r) {
-		c.endLexeme()
-		c.endSymbolRun(false)
-		c.stats.Breakdown.ChinesePunctuations++
-		c.stats.WordCount++
-		c.stats.CharCount++
-		c.atBoundary = false
-		return
-	}
-	if isEnglishPunctuation(r) {
-		keepsLexeme := c.lexeme == lexemeEnglish && (r == '\'' || r == '-' || c.lexemeHasDigit && r == '.') ||
-			c.lexeme == lexemeNumber && (r == '.' || r == ',' || r == '-')
-		if !keepsLexeme {
-			hadLexeme := c.lexeme != lexemeNone
-			c.endLexeme()
-			if !hadLexeme && (c.symbolRunLength > 0 || c.atBoundary) {
-				c.symbolRunLength++
-			}
-		}
-		c.stats.Breakdown.EnglishPunctuations++
-		c.stats.CharCount++
-		if keepsLexeme {
-			c.atBoundary = false
-		}
-		return
-	}
-	if unicode.Is(unicode.Symbol, r) {
-		c.writeSymbol(r)
-		return
-	}
-	c.endLexeme()
-	c.endSymbolRun(false)
-	c.atBoundary = false
-}
-
-func matchASCIICompound(value string) string {
-	if match := urlToken.FindString(value); match != "" {
-		return match
-	}
-	match := asciiCompoundToken.FindString(value)
-	if match == "" || !strings.ContainsAny(match, "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ") {
-		return ""
-	}
-	return match
-}
-
-func (c *textCounter) writeASCIICompound(token string) {
-	c.endUnit()
-	c.stats.Breakdown.EnglishWords++
-	c.stats.WordCount++
-	for _, r := range token {
-		switch {
-		case isASCIILetterRune(r):
-			c.stats.Breakdown.EnglishLetters++
-			c.stats.CharCount++
-		case isASCIIDigitRune(r):
-			c.stats.Breakdown.Digits++
-			c.stats.CharCount++
-		case isEnglishPunctuation(r):
-			c.stats.Breakdown.EnglishPunctuations++
-			c.stats.CharCount++
-		}
-	}
-	c.atBoundary = false
-}
-
-func (c *textCounter) writeSymbol(r rune) {
-	c.endLexeme()
-	c.endSymbolRun(false)
-	units := utf16Units(r)
-	c.stats.Breakdown.SymbolWords++
-	c.stats.Breakdown.SymbolChars += units
-	c.stats.WordCount++
-	c.stats.CharCount += units
-	c.atBoundary = false
-}
-
-func (c *textCounter) endUnit() {
-	c.endLexeme()
-	c.endSymbolRun(true)
-}
-
-func (c *textCounter) endLexeme() {
-	switch c.lexeme {
-	case lexemeEnglish:
-		c.stats.Breakdown.EnglishWords++
-		c.stats.WordCount++
-	case lexemeNumber:
-		c.stats.Breakdown.NumberWords++
-		c.stats.WordCount++
-	}
-	c.lexeme = lexemeNone
-	c.lexemeHasDigit = false
-}
-
-func (c *textCounter) endSymbolRun(countWord bool) {
-	if c.symbolRunLength > 0 && countWord {
-		c.stats.Breakdown.SymbolWords++
-		c.stats.WordCount++
-	}
-	if c.symbolRunLength > 0 {
-		c.atBoundary = false
-	}
-	c.symbolRunLength = 0
-}
-
-func isVisibleHanSeparator(value string, offset, size int) bool {
-	if offset == 0 || offset+size >= len(value) {
-		return false
-	}
-	previous, _ := utf8.DecodeLastRuneInString(value[:offset])
-	next, _ := utf8.DecodeRuneInString(value[offset+size:])
-	return unicode.Is(unicode.Han, previous) && unicode.Is(unicode.Han, next)
-}
-
-func isASCIILetterRune(r rune) bool { return r >= 'a' && r <= 'z' || r >= 'A' && r <= 'Z' }
-func isASCIIDigitRune(r rune) bool  { return r >= '0' && r <= '9' }
-
-func isChinesePunctuation(r rune) bool {
-	if strings.ContainsRune(chinesePunctuation, r) {
-		return true
-	}
-	kind := width.LookupRune(r).Kind()
-	return unicode.Is(unicode.Punct, r) && (kind == width.EastAsianWide || kind == width.EastAsianFullwidth)
-}
-
-func isEnglishPunctuation(r rune) bool {
-	return r < utf8.RuneSelf && strings.ContainsRune(englishPunctuation, r)
-}
-
-func utf16Units(r rune) int {
-	if r > 0xffff {
-		return 2
-	}
-	return 1
-}

shortcuts/doc/internal/docxparse/xml.go

@@ -1,572 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package docxparse
-
-import (
-	"fmt"
-	"html"
-	"regexp"
-	"strconv"
-	"strings"
-	"unicode"
-	"unicode/utf8"
-)
-
-const (
-	MaxInputBytes   = 20_000_000
-	MaxNestingDepth = 1024
-)
-
-var forbiddenXMLDeclaration = regexp.MustCompile(`(?i)<!\s*(?:DOCTYPE|ENTITY)\b`)
-
-func validateSource(source string) error {
-	if len(source) > MaxInputBytes {
-		return fmt.Errorf("input is too large (%d bytes, limit %d)", len(source), MaxInputBytes)
-	}
-	if forbiddenXMLDeclaration.MatchString(source) {
-		return fmt.Errorf("XML input must not contain DOCTYPE or ENTITY declarations")
-	}
-	if !utf8.ValidString(source) {
-		return fmt.Errorf("input must be valid UTF-8")
-	}
-	return nil
-}
-
-func parseXML(source string) ([]*Node, error) {
-	if err := validateSource(source); err != nil {
-		return nil, err
-	}
-	source = strings.TrimPrefix(source, "\uFEFF")
-
-	root := newElement("__fragment__", nil)
-	stack := []*Node{root}
-	for i := 0; i < len(source); {
-		lt := strings.IndexByte(source[i:], '<')
-		if lt < 0 {
-			if err := validateXMLText(source[i:], i); err != nil {
-				return nil, err
-			}
-			appendText(stack[len(stack)-1], source[i:])
-			break
-		}
-		lt += i
-		if err := validateXMLText(source[i:lt], i); err != nil {
-			return nil, err
-		}
-		appendText(stack[len(stack)-1], source[i:lt])
-
-		token, end, state := scanXMLToken(source, lt)
-		switch state {
-		case tokenComment, tokenProcessingInstruction:
-			i = end
-			continue
-		case tokenCDATA:
-			appendTextValue(stack[len(stack)-1], token.text)
-			i = end
-			continue
-		case tokenInvalid:
-			return nil, fmt.Errorf("invalid XML token at byte %d", lt)
-		case tokenIncomplete:
-			return nil, fmt.Errorf("unterminated XML tag at byte %d", lt)
-		}
-
-		spec, allowed := lookupTag(token.name)
-		if !allowed {
-			return nil, fmt.Errorf("unsupported LarkOpenCLI tag <%s> at byte %d", token.name, lt)
-		}
-		canonical := spec.canonical
-		if token.spacingNormalized {
-			return nil, fmt.Errorf("invalid whitespace in XML tag <%s> at byte %d", token.name, lt)
-		}
-
-		if token.closing {
-			if isVoidTag(canonical) {
-				return nil, fmt.Errorf("void tag <%s/> must not have a closing tag", canonical)
-			}
-			if len(stack) == 1 {
-				return nil, fmt.Errorf("unexpected closing tag </%s> at byte %d", canonical, lt)
-			}
-			open := stack[len(stack)-1].tag
-			if open != canonical {
-				return nil, fmt.Errorf("mismatched closing tag </%s> at byte %d; expected </%s>", canonical, lt, open)
-			}
-			stack = stack[:len(stack)-1]
-			i = end
-			continue
-		}
-
-		if len(stack) > 1 && shouldAutoClose(stack[len(stack)-1].tag, canonical) {
-			return nil, fmt.Errorf("invalid <%s> inside <%s> at byte %d", canonical, stack[len(stack)-1].tag, lt)
-		}
-		attrs := normalizeAttributes(token.name, canonical, token.attrs)
-		node := newElement(canonical, attrs)
-		stack[len(stack)-1].addChild(node)
-		if !token.selfClosing && !isVoidTag(canonical) {
-			if len(stack) > MaxNestingDepth {
-				return nil, fmt.Errorf("XML nesting exceeds limit %d at byte %d", MaxNestingDepth, lt)
-			}
-			stack = append(stack, node)
-		}
-		i = end
-	}
-
-	if len(stack) > 1 {
-		return nil, fmt.Errorf("missing closing tag </%s> at end of input", stack[len(stack)-1].tag)
-	}
-	normalizeParsedLineBreaks(root.children, false, false)
-	for _, child := range root.children {
-		child.parent = nil
-	}
-	return root.children, nil
-}
-
-// normalizeParsedLineBreaks removes formatting newlines from ordinary XML,
-// while source-bearing code/whiteboard blocks keep semantic
-// line breaks as explicit <br/> nodes. str_replace pattern/replacement payloads
-// retain raw newlines because their string matching semantics depend on them.
-func normalizeParsedLineBreaks(nodes []*Node, sourceBlock, stringMutation bool) {
-	for _, node := range nodes {
-		if node == nil || node.typ != nodeElement {
-			continue
-		}
-		nextSourceBlock := sourceBlock || node.tag == "code" || node.tag == "whiteboard"
-		nextStringMutation := stringMutation || node.tag == "str_replace"
-		preserveRaw := nextStringMutation && (node.tag == "pattern" || node.tag == "replacement")
-		if node.tag == "code" || node.tag == "whiteboard" {
-			trimSourceBlockBoundaryNewlines(node.children)
-		}
-		children := make([]*Node, 0, len(node.children))
-		for _, child := range node.children {
-			if child.typ != nodeText || !strings.ContainsAny(child.text, "\r\n") {
-				children = append(children, child)
-				continue
-			}
-			switch {
-			case preserveRaw:
-				children = append(children, child)
-			case nextSourceBlock:
-				for _, replacement := range rawTextWithBreakNodes(child.text) {
-					replacement.parent = node
-					children = append(children, replacement)
-				}
-			default:
-				child.text = strings.NewReplacer("\r", "", "\n", "").Replace(child.text)
-				if child.text != "" {
-					children = append(children, child)
-				}
-			}
-		}
-		node.children = children
-		normalizeParsedLineBreaks(node.children, nextSourceBlock, nextStringMutation)
-	}
-}
-
-func trimSourceBlockBoundaryNewlines(children []*Node) {
-	for _, child := range children {
-		if child.typ == nodeText {
-			child.text = strings.TrimLeft(child.text, "\r\n")
-			break
-		}
-		if child.typ == nodeElement {
-			break
-		}
-	}
-	for i := len(children) - 1; i >= 0; i-- {
-		child := children[i]
-		if child.typ == nodeText {
-			child.text = strings.TrimRight(child.text, "\r\n")
-			break
-		}
-		if child.typ == nodeElement {
-			break
-		}
-	}
-}
-
-func rawTextWithBreakNodes(content string) []*Node {
-	if content == "" {
-		return nil
-	}
-	var nodes []*Node
-	start := 0
-	for i := 0; i < len(content); i++ {
-		if content[i] != '\n' && content[i] != '\r' {
-			continue
-		}
-		if i > start {
-			nodes = append(nodes, newText(content[start:i]))
-		}
-		if content[i] == '\r' && i+1 < len(content) && content[i+1] == '\n' {
-			i++
-		}
-		nodes = append(nodes, newElement("br", nil))
-		start = i + 1
-	}
-	if start < len(content) {
-		nodes = append(nodes, newText(content[start:]))
-	}
-	return nodes
-}
-
-type tokenState uint8
-
-const (
-	tokenOK tokenState = iota
-	tokenInvalid
-	tokenIncomplete
-	tokenComment
-	tokenProcessingInstruction
-	tokenCDATA
-)
-
-type xmlToken struct {
-	name              string
-	attrs             map[string]string
-	text              string
-	closing           bool
-	selfClosing       bool
-	spacingNormalized bool
-}
-
-func scanXMLToken(source string, start int) (xmlToken, int, tokenState) {
-	if strings.HasPrefix(source[start:], "<![CDATA[") {
-		const marker = "<![CDATA["
-		contentStart := start + len(marker)
-		if closeAt := strings.Index(source[contentStart:], "]]>"); closeAt >= 0 {
-			contentEnd := contentStart + closeAt
-			return xmlToken{text: source[contentStart:contentEnd]}, contentEnd + len("]]>"), tokenCDATA
-		}
-		return xmlToken{}, len(source), tokenIncomplete
-	}
-	if strings.HasPrefix(source[start:], "<!--") {
-		if closeAt := strings.Index(source[start+4:], "-->"); closeAt >= 0 {
-			if strings.Contains(source[start+4:start+4+closeAt], "--") {
-				return xmlToken{}, start + 1, tokenInvalid
-			}
-			return xmlToken{}, start + 4 + closeAt + 3, tokenComment
-		}
-		return xmlToken{}, len(source), tokenIncomplete
-	}
-	if strings.HasPrefix(source[start:], "<?") {
-		if closeAt := strings.Index(source[start+2:], "?>"); closeAt >= 0 {
-			return xmlToken{}, start + 2 + closeAt + 2, tokenProcessingInstruction
-		}
-		return xmlToken{}, len(source), tokenIncomplete
-	}
-
-	quote := byte(0)
-	end := -1
-	for i := start + 1; i < len(source); i++ {
-		switch source[i] {
-		case '\'', '"':
-			if quote == 0 {
-				quote = source[i]
-			} else if quote == source[i] {
-				quote = 0
-			}
-		case '>':
-			if quote == 0 {
-				end = i + 1
-				i = len(source)
-			}
-		case '<':
-			// A second unquoted '<' cannot belong to the current XML tag.
-			// Stop here so a long sequence of invalid tag starts is scanned
-			// once instead of repeatedly searching to a distant '>'.
-			if quote == 0 {
-				return xmlToken{}, start + 1, tokenInvalid
-			}
-		}
-	}
-	if end < 0 {
-		candidate := strings.TrimSpace(source[start+1:])
-		if candidate == "" || !isTagNameStart(candidate[0]) && candidate[0] != '/' {
-			return xmlToken{}, start + 1, tokenInvalid
-		}
-		return xmlToken{}, len(source), tokenIncomplete
-	}
-
-	body := source[start+1 : end-1]
-	if body == "" {
-		return xmlToken{}, end, tokenInvalid
-	}
-	token := xmlToken{}
-	position := 0
-	for position < len(body) && isXMLSpace(body[position]) {
-		position++
-	}
-	if position > 0 {
-		token.spacingNormalized = true
-	}
-	if position >= len(body) || body[position] == '!' {
-		return xmlToken{}, end, tokenInvalid
-	}
-	if body[position] == '/' {
-		token.closing = true
-		position++
-		spaceStart := position
-		for position < len(body) && isXMLSpace(body[position]) {
-			position++
-		}
-		if position > spaceStart {
-			token.spacingNormalized = true
-		}
-	}
-	if position >= len(body) || !isTagNameStart(body[position]) {
-		return xmlToken{}, end, tokenInvalid
-	}
-	nameStart := position
-	position++
-	for position < len(body) && isTagNamePart(body[position]) {
-		position++
-	}
-	token.name = body[nameStart:position]
-	rawRemainder := body[position:]
-	remainder := strings.TrimRightFunc(rawRemainder, unicode.IsSpace)
-	if token.closing {
-		if strings.TrimSpace(remainder) != "" {
-			return xmlToken{}, end, tokenInvalid
-		}
-		return token, end, tokenOK
-	}
-	if strings.HasSuffix(remainder, "/") {
-		if len(remainder) != len(rawRemainder) {
-			return xmlToken{}, end, tokenInvalid
-		}
-		token.selfClosing = true
-		remainder = strings.TrimRightFunc(strings.TrimSuffix(remainder, "/"), unicode.IsSpace)
-	}
-	trimmedAttrs := strings.TrimLeftFunc(remainder, unicode.IsSpace)
-	if trimmedAttrs != "" && !isAttributeNameStart(trimmedAttrs[0]) {
-		return xmlToken{}, end, tokenInvalid
-	}
-	var ok bool
-	token.attrs, ok = parseStrictAttributes(remainder)
-	if !ok {
-		return xmlToken{}, end, tokenInvalid
-	}
-	return token, end, tokenOK
-}
-
-func isXMLSpace(ch byte) bool {
-	return ch == ' ' || ch == '\t' || ch == '\r' || ch == '\n'
-}
-
-func isTagNameStart(ch byte) bool {
-	return ch >= 'A' && ch <= 'Z' || ch >= 'a' && ch <= 'z'
-}
-
-func isTagNamePart(ch byte) bool {
-	return isTagNameStart(ch) || ch >= '0' && ch <= '9' || ch == '_' || ch == '-' || ch == '.' || ch == ':'
-}
-
-func isAttributeNameStart(ch byte) bool {
-	return isTagNameStart(ch) || ch == '_' || ch == ':'
-}
-
-func parseAttributes(source string) map[string]string {
-	attrs := map[string]string{}
-	for i := 0; i < len(source); {
-		for i < len(source) && unicode.IsSpace(rune(source[i])) {
-			i++
-		}
-		if i >= len(source) {
-			break
-		}
-		start := i
-		for i < len(source) && isAttributeNameByte(source[i]) {
-			i++
-		}
-		if start == i {
-			i++
-			continue
-		}
-		name := source[start:i]
-		for i < len(source) && unicode.IsSpace(rune(source[i])) {
-			i++
-		}
-		value := ""
-		if i < len(source) && source[i] == '=' {
-			i++
-			for i < len(source) && unicode.IsSpace(rune(source[i])) {
-				i++
-			}
-			if i < len(source) && (source[i] == '\'' || source[i] == '"') {
-				quote := source[i]
-				i++
-				start = i
-				for i < len(source) && source[i] != quote {
-					i++
-				}
-				value = source[start:i]
-				if i < len(source) {
-					i++
-				}
-			} else {
-				start = i
-				for i < len(source) && !unicode.IsSpace(rune(source[i])) {
-					i++
-				}
-				value = source[start:i]
-			}
-		}
-		attrs[name] = html.UnescapeString(value)
-	}
-	if len(attrs) == 0 {
-		return nil
-	}
-	return attrs
-}
-
-// parseStrictAttributes implements the quoted attribute grammar accepted by
-// XML. parseAttributes remains intentionally permissive for the Markdown
-// container extension, whose input is Markdown rather than an XML document.
-func parseStrictAttributes(source string) (map[string]string, bool) {
-	attrs := map[string]string{}
-	for i := 0; i < len(source); {
-		spaceStart := i
-		for i < len(source) && isXMLSpace(source[i]) {
-			i++
-		}
-		if i >= len(source) {
-			break
-		}
-		if i == spaceStart || !isAttributeNameStart(source[i]) {
-			return nil, false
-		}
-
-		nameStart := i
-		i++
-		for i < len(source) && isTagNamePart(source[i]) {
-			i++
-		}
-		name := source[nameStart:i]
-		if _, exists := attrs[name]; exists {
-			return nil, false
-		}
-
-		for i < len(source) && isXMLSpace(source[i]) {
-			i++
-		}
-		if i >= len(source) || source[i] != '=' {
-			return nil, false
-		}
-		i++
-		for i < len(source) && isXMLSpace(source[i]) {
-			i++
-		}
-		if i >= len(source) || (source[i] != '\'' && source[i] != '"') {
-			return nil, false
-		}
-
-		quote := source[i]
-		i++
-		valueStart := i
-		for i < len(source) && source[i] != quote {
-			if source[i] == '<' {
-				return nil, false
-			}
-			i++
-		}
-		if i >= len(source) {
-			return nil, false
-		}
-		rawValue := normalizeXMLAttributeAmpersands(source[valueStart:i])
-		if invalidXMLEntityAt(rawValue) >= 0 {
-			return nil, false
-		}
-		attrs[name] = html.UnescapeString(rawValue)
-		i++
-	}
-	if len(attrs) == 0 {
-		return nil, true
-	}
-	return attrs, true
-}
-
-func isAttributeNameByte(ch byte) bool {
-	return ch > ' ' && ch != '=' && ch != '/' && ch != '>'
-}
-
-func appendText(parent *Node, raw string) {
-	if parent == nil || raw == "" {
-		return
-	}
-	appendTextValue(parent, html.UnescapeString(raw))
-}
-
-func appendTextValue(parent *Node, text string) {
-	if parent == nil || text == "" {
-		return
-	}
-	if strings.TrimSpace(text) == "" && !preserveSpaceTags[parent.tag] && parent.tag != "whiteboard" {
-		return
-	}
-	if count := len(parent.children); count > 0 && parent.children[count-1].typ == nodeText {
-		parent.children[count-1].text += text
-		return
-	}
-	parent.addChild(newText(text))
-}
-
-func validateXMLText(value string, absoluteOffset int) error {
-	if offset := strings.Index(value, "]]>"); offset >= 0 {
-		return fmt.Errorf("invalid ]]> sequence in XML text at byte %d", absoluteOffset+offset)
-	}
-	if offset := invalidXMLEntityAt(value); offset >= 0 {
-		return fmt.Errorf("invalid XML entity at byte %d", absoluteOffset+offset)
-	}
-	return nil
-}
-
-func invalidXMLEntityAt(value string) int {
-	for cursor := 0; cursor < len(value); {
-		relative := strings.IndexByte(value[cursor:], '&')
-		if relative < 0 {
-			return -1
-		}
-		start := cursor + relative
-		endRelative := strings.IndexByte(value[start+1:], ';')
-		if endRelative < 0 {
-			return start
-		}
-		end := start + 1 + endRelative
-		if !isValidXMLEntity(value[start+1 : end]) {
-			return start
-		}
-		cursor = end + 1
-	}
-	return -1
-}
-
-func isValidXMLEntity(entity string) bool {
-	switch entity {
-	case "amp", "lt", "gt", "quot", "apos":
-		return true
-	}
-
-	base := 10
-	digits := ""
-	switch {
-	case strings.HasPrefix(entity, "#x"):
-		base = 16
-		digits = entity[2:]
-	case strings.HasPrefix(entity, "#"):
-		digits = entity[1:]
-	default:
-		return false
-	}
-	if digits == "" {
-		return false
-	}
-	value, err := strconv.ParseUint(digits, base, 32)
-	if err != nil {
-		return false
-	}
-	r := rune(value)
-	return r == '\t' || r == '\n' || r == '\r' ||
-		r >= 0x20 && r <= 0xD7FF ||
-		r >= 0xE000 && r <= 0xFFFD ||
-		r >= 0x10000 && r <= utf8.MaxRune
-}

shortcuts/doc/internal/docxparse/xml_compat.go

@@ -1,62 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package docxparse
-
-import "strings"
-
-// normalizeXMLAttributeAmpersands escapes bare ampersands in an XML attribute
-// value so local parsing matches the server SDK. Complete entity references
-// remain untouched for the strict parser to validate.
-func normalizeXMLAttributeAmpersands(value string) string {
-	firstBare := -1
-	for cursor := 0; cursor < len(value); {
-		relative := strings.IndexByte(value[cursor:], '&')
-		if relative < 0 {
-			break
-		}
-		ampersand := cursor + relative
-		if isBareXMLAttributeAmpersand(value, ampersand) {
-			firstBare = ampersand
-			break
-		}
-		cursor = ampersand + 1
-	}
-	if firstBare < 0 {
-		return value
-	}
-
-	var out strings.Builder
-	out.Grow(len(value))
-	out.WriteString(value[:firstBare])
-
-	for i := firstBare; i < len(value); i++ {
-		if value[i] == '&' && isBareXMLAttributeAmpersand(value, i) {
-			out.WriteString("&amp;")
-			continue
-		}
-		out.WriteByte(value[i])
-	}
-	return out.String()
-}
-
-func isBareXMLAttributeAmpersand(value string, start int) bool {
-	if start+1 >= len(value) {
-		return true
-	}
-	if value[start+1] == '#' {
-		return false
-	}
-	if !isTagNameStart(value[start+1]) && value[start+1] != '_' {
-		return true
-	}
-	for i := start + 2; i < len(value); i++ {
-		if value[i] == ';' {
-			return false
-		}
-		if !isTagNamePart(value[i]) {
-			return true
-		}
-	}
-	return true
-}

shortcuts/doc/shortcuts.go

@@ -33,8 +33,6 @@ func docsSkillReadCommandForShortcut(shortcut string) string {
 		return docsSkillReadCommand + " references/lark-doc-update.md"
 	case "history-list", "history-revert", "history-revert-status":
 		return docsSkillReadCommand + " references/lark-doc-history.md"
-	case "script":
-		return docsSkillReadCommand + " references/lark-doc-script.md"
 	default:
 		return docsSkillReadCommand
 	}
@@ -54,8 +52,6 @@ func docsHelpCommandForShortcut(shortcut string) string {
 		return "lark-cli docs +history-revert --help"
 	case "history-revert-status":
 		return "lark-cli docs +history-revert-status --help"
-	case "script":
-		return "lark-cli docs +script --help"
 	default:
 		return "lark-cli docs --help"
 	}
@@ -68,7 +64,6 @@ func Shortcuts() []common.Shortcut {
 		DocsCreate,
 		DocsFetch,
 		DocsUpdate,
-		DocsScript,
 		DocsHistoryList,
 		DocsHistoryRevert,
 		DocsHistoryRevertStatus,