feat(cli)!: v0.10 reliability, agent-UX, and command-surface hardening

A hardening + finalization pass over the agent-first CLI: correctness fixes, richer machine-readable signals, flag/naming consistency, and a symmetric config surface. Pre-1.0, so it includes breaking renames. Correctness: - agent update: resolve/validate --model/--rerank-model (was storing a bogus name verbatim, corrupting config.model_id). - doctor: honor WEKNORA_HOST / WEKNORA_API_KEY (headless path no longer reports "no host configured"). - session ask / MCP session_ask: text answer was empty on non-TTY — the agent stream sets Done=true on an intermediate agent_query frame before the answer, and AgentAccumulator treated the first Done as terminal. Terminate on the `complete` event (new sdk.AgentResponseTypeComplete), not a per-frame Done. - batch exit codes: any per-item failure collapses to operation.failed (exit 1), including `doc upload --recursive` partial failures — a permanent per-file failure (e.g. a duplicate) no longer surfaces as a retryable exit 7 an agent would loop on; per-item typed errors stay in the envelope. Agent-first signals & discovery: - error.exit_code in the envelope (type + exit_code disambiguate the input.invalid_argument exit-2-vs-5 split in one JSON read). - meta.hint on empty content search and on draft doc create; doc wait fails fast on a never-parsing draft instead of hanging to --timeout. - retrieval-readiness is visible in the natural flow: kb status / kb check emit retrieval_ready, and kb create hints the fix when no embedding model is bound — an unconfigured KB no longer looks silently healthy. - schema contract completeness: every leaf declares output + >=1 example (drift-guarded); output strings match the meta actually emitted; chunk list and search docs now emit meta.total_count (both previously dropped it). - schema tolerates a quoted multi-word command label; zero-state auth — and `link` with no profile — point at profile setup / the headless WEKNORA_KB_ID path instead of looping on `auth login`. - id-addressed reads tolerate a redundant --kb (doc view/wait, chunk list/view accept and ignore it, declared in schema) so a carried-over --kb doesn't exit 2; streaming commands warn that --jq does not apply to an NDJSON stream. - keep JSON-always as the default; --jq hints spell out the .data path. Consistency & gating: - doc create: drop the deprecated --name alias (--title only; pre-1.0 break). - chunk list --limit aligned to 1..10000; model list --limit/-L with has_more/total_count; api write-gates -X PUT/PATCH (exit 10); skills install expands a leading ~. - docs corrected: search docs / doc list --keyword help is case-insensitive (server does LOWER LIKE); AGENTS.md risk-action list (no phantom kb.init; add model.update / kb.config.set) and batch example (failed item carries `error`); session resume --message id comes from `message list`, not the stream. - auth/profile ergonomics: env credentials are now first-class — `auth token` prints the active WEKNORA_API_KEY / WEKNORA_TOKEN, and auth login/logout/refresh give an env-aware message instead of looping on "run auth login". `auth logout` clears credentials but keeps the profile registered (host preserved for re-login); deleting a profile is `profile remove`'s job (clean logout/remove separation, matching gh / lark). Config surface (symmetric read/write, in-place model edits): - kb config now returns a secret-free KBModelConfigView (was {}); `kb config` reads, new `kb config set` writes; `kb init` removed (misnomer). - kb create --chat-model: retrieval-ready in one step. - model update: edit a model in place (id preserved, references survive) — rotate --api-key-stdin, change base-url / display-name / etc. - session continue-stream renamed to session resume. Docs: AGENTS.md is the single wire-contract source; CHANGELOG slimmed; stale kb-init / continue-stream references removed; skill wire-vocab guard extended. AGENTS.md / weknora-shared SKILL document retrieval_ready (a KB needs an embedding model to be searchable), that --jq does not apply to NDJSON streams, and the env-credential-first auth path; the KB quickstart example now creates a retrieval-ready KB.
2026-07-02 15:53:51 +08:00
parent 040a734766
commit d3c03b2f34
95 changed files with 1711 additions and 436 deletions
@@ -85,7 +85,7 @@ func NewCmdCreate(f *cmdutil.Factory) *cobra.Command {
 		Use:   "create <name>",
 		Short: "Register a model (embedding / rerank / chat / VLLM / ASR)",
 		Long: `Register a model on the server so it can back a knowledge base's embedding /
-summary config (see 'weknora kb init') or an agent (--model).
+summary config (see 'weknora kb config set') or an agent (--model).

 <name> is the model name as the provider knows it (e.g. "nomic-embed-text",
 "gpt-4o", "qwen2"). --type and --source are required.
@@ -178,7 +178,7 @@ else goes through repeatable --param key=value.`,
 	cmdutil.AddFormatFlag(cmd, modelCreateFields...)
 	cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
 	cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
-		UsedFor:       "register a model (embedding/rerank/chat/VLLM/ASR) so a KB or agent can use it; capture .data.id to pass to `weknora kb init` / `agent create --model`.",
+		UsedFor:       "register a model (embedding/rerank/chat/VLLM/ASR) so a KB or agent can use it; capture .data.id to pass to `weknora kb config set` / `agent create --model`.",
 		RequiredFlags: []string{"<name> (positional)", "--type", "--source (local|remote)", "--provider (when --source remote)"},
 		Examples: []string{
 			`weknora model create nomic-embed-text --type Embedding --source local --dimension 768   # Ollama (server pulls it)`,
@@ -40,6 +40,10 @@ type ListOptions struct {
 	// …), matched case-insensitively. Empty shows everything.
 	Type   string
 	Source string
+	// Limit caps the returned slice client-side (applied after --type/--source
+	// filtering and sort). The ListModels SDK is unpaginated, so the CLI holds
+	// the true total and reports meta.total_count/has_more when --limit drops any.
+	Limit int
 }

 // ListService is the narrow SDK surface this command depends on.
@@ -62,6 +66,11 @@ func NewCmdList(f *cmdutil.Factory) *cobra.Command {
 				return err
 			}
 			fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
+			// Validate static input before building the client so a bad --limit
+			// returns input.invalid_argument (exit 5), not an auth error (exit 3).
+			if err := validateListOpts(opts); err != nil {
+				return err
+			}
 			cli, err := f.Client()
 			if err != nil {
 				return err
@@ -71,6 +80,7 @@ func NewCmdList(f *cmdutil.Factory) *cobra.Command {
 	}
 	cmd.Flags().StringVar(&opts.Type, "type", "", "Only show models of this type (Embedding, Rerank, KnowledgeQA, VLLM, ASR)")
 	cmd.Flags().StringVar(&opts.Source, "source", "", "Only show models from this provider (local, remote, openai, aliyun, …)")
+	cmd.Flags().IntVarP(&opts.Limit, "limit", "L", 30, "Maximum results to return — client-side cap; meta.has_more/total_count report the full size (1..10000)")
 	cmdutil.AddFormatFlag(cmd, modelListFields...)
 	cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
 		UsedFor: "discover model ids for `agent create --model` and a KB's embedding/summary model",
@@ -79,12 +89,28 @@ func NewCmdList(f *cmdutil.Factory) *cobra.Command {
 			"weknora model list --type KnowledgeQA --format json",
 			"weknora model list --source local",
 		},
-		Output: "envelope.data is an array of Model objects (id, name, display_name, type, source, is_default); narrow it with --type / --source",
+		Output: "envelope.data is an array of Model objects (id, name, display_name, type, source, is_default); narrow it with --type / --source; meta.count is the returned count, meta.total_count is the full set and meta.has_more=true means --limit truncated it",
 	})
 	return cmd
 }

+// validateListOpts checks --limit. Called from RunE before the client is built
+// (so a bad value surfaces as exit 5, not an auth error) and at runList's top
+// for direct callers; idempotent.
+func validateListOpts(opts *ListOptions) error {
+	if opts.Limit < 1 || opts.Limit > 10000 {
+		return &cmdutil.Error{
+			Code:    cmdutil.CodeInputInvalidArgument,
+			Message: fmt.Sprintf("--limit must be in 1..10000, got %d", opts.Limit),
+		}
+	}
+	return nil
+}
+
 func runList(ctx context.Context, opts *ListOptions, fopts *cmdutil.FormatOptions, svc ListService) error {
+	if err := validateListOpts(opts); err != nil {
+		return err
+	}
 	if _, err := cmdutil.ValidateEnum("type", opts.Type, modelTypeValues); err != nil {
 		return err
 	}
@@ -121,8 +147,19 @@ func runList(ctx context.Context, opts *ListOptions, fopts *cmdutil.FormatOption
 		return modelLabel(items[i]) < modelLabel(items[j])
 	})

+	// Client-side --limit cap. The ListModels SDK is unpaginated, so the CLI
+	// holds the true total and can tell the caller whether --limit dropped any:
+	// total_count is the full (post-filter) count, has_more flags truncation.
+	total := len(items)
+	truncated := false
+	if opts.Limit > 0 && len(items) > opts.Limit {
+		items = items[:opts.Limit]
+		truncated = true
+	}
+
 	if fopts.WantsJSON() {
-		return fopts.Emit(iostreams.IO.Out, items, &output.Meta{Count: output.IntPtr(len(items))})
+		meta := &output.Meta{Count: output.IntPtr(len(items)), HasMore: truncated, TotalCount: output.IntPtr(total)}
+		return fopts.Emit(iostreams.IO.Out, items, meta)
 	}

 	if len(items) == 0 {
@@ -27,7 +27,7 @@ func TestModelList_Text(t *testing.T) {
 		{ID: "m1", DisplayName: "GPT-X", Type: sdk.ModelTypeKnowledgeQA, Source: sdk.ModelSourceOpenAI, IsDefault: true},
 		{ID: "m2", Name: "bge", Type: sdk.ModelTypeEmbedding, Source: sdk.ModelSourceLocal},
 	}}
-	if err := runList(context.Background(), &ListOptions{}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc); err != nil {
+	if err := runList(context.Background(), &ListOptions{Limit: 30}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc); err != nil {
 		t.Fatalf("runList: %v", err)
 	}
 	got := out.String()
@@ -46,7 +46,7 @@ func TestModelList_TypeFilter(t *testing.T) {
 		{ID: "m1", Type: sdk.ModelTypeKnowledgeQA},
 		{ID: "m2", Type: sdk.ModelTypeEmbedding},
 	}}
-	if err := runList(context.Background(), &ListOptions{Type: "embedding"}, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc); err != nil {
+	if err := runList(context.Background(), &ListOptions{Type: "embedding", Limit: 30}, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc); err != nil {
 		t.Fatalf("runList: %v", err)
 	}
 	var env struct {
@@ -69,7 +69,7 @@ func TestModelList_TypeFilter(t *testing.T) {
 func TestModelList_Empty(t *testing.T) {
 	out, _ := iostreams.SetForTest(t)
 	svc := &fakeListSvc{models: nil}
-	if err := runList(context.Background(), &ListOptions{}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc); err != nil {
+	if err := runList(context.Background(), &ListOptions{Limit: 30}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc); err != nil {
 		t.Fatalf("runList: %v", err)
 	}
 	if !strings.Contains(out.String(), "(no models)") {
@@ -80,7 +80,7 @@ func TestModelList_Empty(t *testing.T) {
 func TestModelList_EmptyAfterFilter(t *testing.T) {
 	out, _ := iostreams.SetForTest(t)
 	svc := &fakeListSvc{models: []sdk.Model{{ID: "m1", Type: sdk.ModelTypeEmbedding}}}
-	if err := runList(context.Background(), &ListOptions{Type: "Rerank"}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc); err != nil {
+	if err := runList(context.Background(), &ListOptions{Type: "Rerank", Limit: 30}, &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, svc); err != nil {
 		t.Fatalf("runList: %v", err)
 	}
 	if !strings.Contains(out.String(), "(no models match the filter)") {
@@ -95,7 +95,7 @@ func TestModelList_SourceFilter(t *testing.T) {
 		{ID: "m1", Type: sdk.ModelTypeEmbedding, Source: sdk.ModelSourceLocal},
 		{ID: "m2", Type: sdk.ModelTypeKnowledgeQA, Source: sdk.ModelSourceOpenAI},
 	}}
-	if err := runList(context.Background(), &ListOptions{Source: "OpenAI"}, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc); err != nil {
+	if err := runList(context.Background(), &ListOptions{Source: "OpenAI", Limit: 30}, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc); err != nil {
 		t.Fatalf("runList: %v", err)
 	}
 	var env struct {
@@ -113,8 +113,8 @@ func TestModelList_SourceFilter(t *testing.T) {
 // (input.invalid_argument) instead of silently returning an empty set.
 func TestModelList_InvalidEnum(t *testing.T) {
 	for _, tc := range []struct{ name string; opts ListOptions }{
-		{"type", ListOptions{Type: "bogus"}},
-		{"source", ListOptions{Source: "bogus"}},
+		{"type", ListOptions{Type: "bogus", Limit: 30}},
+		{"source", ListOptions{Source: "bogus", Limit: 30}},
 	} {
 		t.Run(tc.name, func(t *testing.T) {
 			_, _ = iostreams.SetForTest(t)
@@ -127,3 +127,44 @@ func TestModelList_InvalidEnum(t *testing.T) {
 		})
 	}
 }
+
+// TestModelList_Limit_TruncatesAndSignals verifies --limit caps model list
+// output and reports meta.total_count/has_more like every other list command.
+// Regression: model list had no --limit, so an agent could not cap output or
+// tell whether it saw the full set.
+func TestModelList_Limit_TruncatesAndSignals(t *testing.T) {
+	out, _ := iostreams.SetForTest(t)
+	svc := &fakeListSvc{models: []sdk.Model{
+		{ID: "m1", Type: sdk.ModelTypeKnowledgeQA},
+		{ID: "m2", Type: sdk.ModelTypeKnowledgeQA},
+		{ID: "m3", Type: sdk.ModelTypeKnowledgeQA},
+	}}
+	fopts := &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}
+	if err := runList(context.Background(), &ListOptions{Limit: 2}, fopts, svc); err != nil {
+		t.Fatalf("runList: %v", err)
+	}
+	got := out.String()
+	if n := strings.Count(got, `"id":"m`); n != 2 {
+		t.Errorf("--limit 2 should slice to 2 models, got %d in:\n%s", n, got)
+	}
+	if !strings.Contains(got, `"has_more":true`) {
+		t.Errorf("truncated model list must set has_more:true; got:\n%s", got)
+	}
+	if !strings.Contains(got, `"total_count":3`) {
+		t.Errorf("truncated model list must report total_count:3; got:\n%s", got)
+	}
+}
+
+// TestModelList_BadLimit_Rejected verifies an out-of-range --limit is exit-5
+// typed validation, consistent with kb/session list.
+func TestModelList_BadLimit_Rejected(t *testing.T) {
+	_, _ = iostreams.SetForTest(t)
+	err := runList(context.Background(), &ListOptions{Limit: 99999}, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, &fakeListSvc{})
+	if err == nil {
+		t.Fatal("--limit 99999 must be rejected")
+	}
+	var e *cmdutil.Error
+	if !errors.As(err, &e) || e.Code != cmdutil.CodeInputInvalidArgument {
+		t.Errorf("want input.invalid_argument, got %v", err)
+	}
+}
@@ -21,7 +21,7 @@ import (
 func NewCmd(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "model",
-		Short: "Manage models (list / view / create / delete)",
+		Short: "Manage models (list / view / create / update / delete)",
 		Long: `List, inspect, register, and delete the models configured on the server. Use
 the model id to back a knowledge base's embedding / summary config ('weknora kb
 init') or an agent ('weknora agent create --model <id>').`,
@@ -29,6 +29,7 @@ init') or an agent ('weknora agent create --model <id>').`,
 	cmd.AddCommand(NewCmdList(f))
 	cmd.AddCommand(NewCmdView(f))
 	cmd.AddCommand(NewCmdCreate(f))
+	cmd.AddCommand(NewCmdUpdate(f))
 	cmd.AddCommand(NewCmdDelete(f))
 	return cmd
 }
@@ -0,0 +1,189 @@
+package modelcmd
+
+import (
+	"context"
+	"fmt"
+	"io"
+
+	"github.com/spf13/cobra"
+
+	"github.com/Tencent/WeKnora/cli/internal/cmdutil"
+	"github.com/Tencent/WeKnora/cli/internal/iostreams"
+	sdk "github.com/Tencent/WeKnora/client"
+)
+
+// UpdateOptions captures the surgical flag state for `model update`. Per-flag
+// *Set bits distinguish "" (clear) from unset, matching agent/doc update.
+type UpdateOptions struct {
+	DisplayName string
+	Description string
+	BaseURL     string
+	APIKeyStdin bool
+	Params      []string
+	Default     bool
+	DryRun      bool
+	StdinReader io.Reader
+	flags       modelUpdateFlags
+}
+
+type modelUpdateFlags struct{ displayName, description, baseURL, def bool }
+
+// UpdateService is the narrow SDK surface. UpdateModel is a full PUT, so the
+// fetch (GetModel) is mandatory — without the baseline, any field not touched
+// by a flag would clobber to its zero value.
+type UpdateService interface {
+	GetModel(ctx context.Context, id string) (*sdk.Model, error)
+	UpdateModel(ctx context.Context, id string, req *sdk.UpdateModelRequest) (*sdk.Model, error)
+}
+
+// NewCmdUpdate builds `weknora model update <model-id>` — update a registered
+// model in place (id preserved), so KBs / agents referencing it keep working.
+func NewCmdUpdate(f *cmdutil.Factory) *cobra.Command {
+	opts := &UpdateOptions{}
+	cmd := &cobra.Command{
+		Use:   "update <model-id>",
+		Short: "Update a model in place (rotate key, base URL, display name, default)",
+		Long: `Update a registered model WITHOUT changing its id, so KBs / agents that
+reference it keep working (unlike delete + re-create, which orphans references).
+Rotate the provider key with --api-key-stdin, or change --base-url,
+--display-name, --description, extra --param entries, or --default. A model's
+type and source are immutable — register a new model to change them.
+
+Reversible write: without -y/--yes in a non-TTY / JSON context it exits 10
+(input.confirmation_required) without applying the change.`,
+		Args: cobra.ExactArgs(1),
+		RunE: func(c *cobra.Command, args []string) error {
+			fopts, err := cmdutil.CheckFormatFlag(c)
+			if err != nil {
+				return err
+			}
+			fopts.ResolveDefault(iostreams.IO.IsStdoutTTY())
+			id := args[0]
+			opts.flags.displayName = c.Flags().Changed("display-name")
+			opts.flags.description = c.Flags().Changed("description")
+			opts.flags.baseURL = c.Flags().Changed("base-url")
+			opts.flags.def = c.Flags().Changed("default")
+			if !modelUpdateHasFlag(opts) {
+				return &cmdutil.Error{
+					Code:    cmdutil.CodeInputInvalidArgument,
+					Message: "model update requires at least one flag",
+					Hint:    "pass e.g. --display-name, --base-url, --api-key-stdin, --param, or --default",
+				}
+			}
+			params, err := parseParams(opts.Params)
+			if err != nil {
+				return err
+			}
+			if handled, err := cmdutil.HandleDryRun(c, opts.DryRun, cmdutil.DryRunPlan{
+				Action: "model.update",
+				Args:   map[string]any{"model": id, "display_name": opts.DisplayName, "base_url": opts.BaseURL, "default": opts.Default, "rotate_api_key": opts.APIKeyStdin, "param_count": len(params)},
+			}); handled {
+				return err
+			}
+			yes, _ := c.Flags().GetBool("yes")
+			// --api-key-stdin / --param excluded from retry_argv (stdin secret /
+			// repeatable), matching agent update's multi-value exclusions.
+			retry := cmdutil.BuildRetryArgv(c, []string{"weknora", "model", "update", id},
+				"display-name", "description", "base-url", "default", "format")
+			if err := cmdutil.ConfirmWrite(f.Prompter(), yes, fopts.WantsJSON(), "update", "model", id, "model.update", retry); err != nil {
+				return err
+			}
+			if opts.StdinReader == nil {
+				opts.StdinReader = iostreams.IO.In
+			}
+			cli, err := f.Client()
+			if err != nil {
+				return err
+			}
+			return runUpdate(c.Context(), opts, fopts, cli, id, params)
+		},
+	}
+	cmd.Flags().StringVar(&opts.DisplayName, "display-name", "", "New human-friendly name")
+	cmd.Flags().StringVar(&opts.Description, "description", "", "New description")
+	cmd.Flags().StringVar(&opts.BaseURL, "base-url", "", "New model API base URL")
+	cmd.Flags().BoolVar(&opts.APIKeyStdin, "api-key-stdin", false, "Rotate the provider API key, read from stdin (kept out of argv / history)")
+	cmd.Flags().StringArrayVar(&opts.Params, "param", nil, "Set an extra provider parameter as key=value, repeatable (value parsed as JSON)")
+	cmd.Flags().BoolVar(&opts.Default, "default", false, "Mark this the default model for its type (--default=false to unset)")
+	cmdutil.AddFormatFlag(cmd, modelListFields...)
+	cmdutil.AddDryRunFlag(cmd, &opts.DryRun)
+	cmdutil.SetWriteRisk(cmd, "model.update")
+	cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
+		UsedFor:       "update a registered model IN PLACE (id preserved, so KB/agent references keep working): rotate --api-key-stdin, change --base-url / --display-name / --description / --param, or set --default. Type and source are immutable.",
+		RequiredFlags: []string{"<model-id> (positional)", "at least one update flag"},
+		Examples: []string{
+			`printf '%s' "$NEW_KEY" | weknora model update mdl_abc --api-key-stdin -y`,
+			`weknora model update mdl_abc --base-url https://api.example.com/v1 -y`,
+			`weknora model update mdl_abc --default -y`,
+		},
+		Output: "envelope.data is the updated Model object (id preserved; provider api key never echoed)",
+		Warnings: []string{
+			"Reversible write: requires explicit approval (exit 10 / input.confirmation_required) unless -y; never auto-add -y.",
+			"Server-side this is an admin operation; a non-admin credential gets auth.forbidden (exit 3).",
+		},
+	})
+	return cmd
+}
+
+func modelUpdateHasFlag(o *UpdateOptions) bool {
+	return o.flags.displayName || o.flags.description || o.flags.baseURL || o.flags.def ||
+		o.APIKeyStdin || len(o.Params) > 0
+}
+
+func runUpdate(ctx context.Context, opts *UpdateOptions, fopts *cmdutil.FormatOptions, svc UpdateService, id string, params map[string]any) error {
+	// Fetch-then-update: UpdateModel is a full PUT, so start from the server's
+	// current state and overlay only what the user changed.
+	cur, err := svc.GetModel(ctx, id)
+	if err != nil {
+		return cmdutil.WrapHTTP(err, "fetch model %s", id)
+	}
+	merged := sdk.ModelParameters{}
+	for k, v := range cur.Parameters {
+		merged[k] = v
+	}
+	for k, v := range params {
+		merged[k] = v
+	}
+	if opts.flags.baseURL {
+		merged["base_url"] = opts.BaseURL
+	}
+	if opts.APIKeyStdin {
+		key, err := readStdinTrimmed(opts.StdinReader)
+		if err != nil {
+			return cmdutil.Wrapf(cmdutil.CodeLocalFileIO, err, "read API key from stdin")
+		}
+		if key == "" {
+			return cmdutil.NewError(cmdutil.CodeInputMissingFlag, "--api-key-stdin requires the key piped to stdin")
+		}
+		merged["api_key"] = key
+	}
+
+	req := &sdk.UpdateModelRequest{
+		Name:        cur.Name,
+		DisplayName: cur.DisplayName,
+		Description: cur.Description,
+		Parameters:  merged,
+		IsDefault:   cur.IsDefault,
+	}
+	if opts.flags.displayName {
+		req.DisplayName = opts.DisplayName
+	}
+	if opts.flags.description {
+		req.Description = opts.Description
+	}
+	if opts.flags.def {
+		req.IsDefault = opts.Default
+	}
+
+	updated, err := svc.UpdateModel(ctx, id, req)
+	if err != nil {
+		return cmdutil.WrapHTTP(err, "update model %s", id)
+	}
+	if fopts.WantsJSON() {
+		return fopts.Emit(iostreams.IO.Out, updated, nil)
+	}
+	fmt.Fprintf(iostreams.IO.Out, "✓ Updated model %q (id: %s)\n", updated.Name, updated.ID)
+	return nil
+}
+
+// compile-time check: the production SDK client implements UpdateService.
+var _ UpdateService = (*sdk.Client)(nil)
@@ -0,0 +1,81 @@
+package modelcmd
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/Tencent/WeKnora/cli/internal/cmdutil"
+	"github.com/Tencent/WeKnora/cli/internal/iostreams"
+	sdk "github.com/Tencent/WeKnora/client"
+)
+
+// fakeUpdateSvc scripts GetModel (fetch baseline) and captures the
+// UpdateModelRequest so tests can assert the surgical overlay.
+type fakeUpdateSvc struct {
+	cur    *sdk.Model
+	gotReq *sdk.UpdateModelRequest
+	gotID  string
+}
+
+func (f *fakeUpdateSvc) GetModel(_ context.Context, _ string) (*sdk.Model, error) {
+	return f.cur, nil
+}
+
+func (f *fakeUpdateSvc) UpdateModel(_ context.Context, id string, req *sdk.UpdateModelRequest) (*sdk.Model, error) {
+	f.gotID = id
+	f.gotReq = req
+	return &sdk.Model{ID: id, Name: req.Name, DisplayName: req.DisplayName, Parameters: req.Parameters, IsDefault: req.IsDefault}, nil
+}
+
+func baseModel() *sdk.Model {
+	return &sdk.Model{
+		ID: "mdl_x", Name: "keep-name", DisplayName: "old", Description: "olddesc",
+		Parameters: sdk.ModelParameters{"base_url": "http://old", "api_key": "SECRET-OLD", "provider": "generic"},
+		IsDefault:  false,
+	}
+}
+
+// TestModelUpdate_SurgicalOverlay: only touched fields change; the rest (name,
+// description, existing params) round-trip from the fetched baseline.
+func TestModelUpdate_SurgicalOverlay(t *testing.T) {
+	_, _ = iostreams.SetForTest(t)
+	svc := &fakeUpdateSvc{cur: baseModel()}
+	opts := &UpdateOptions{DisplayName: "new-display", flags: modelUpdateFlags{displayName: true}}
+	require.NoError(t, runUpdate(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc, "mdl_x", nil))
+
+	require.NotNil(t, svc.gotReq)
+	assert.Equal(t, "mdl_x", svc.gotID, "id preserved (in-place update)")
+	assert.Equal(t, "new-display", svc.gotReq.DisplayName, "display-name overlaid")
+	assert.Equal(t, "keep-name", svc.gotReq.Name, "untouched name round-trips")
+	assert.Equal(t, "olddesc", svc.gotReq.Description, "untouched description round-trips")
+	assert.Equal(t, "http://old", svc.gotReq.Parameters["base_url"], "untouched params round-trip")
+	assert.Equal(t, "SECRET-OLD", svc.gotReq.Parameters["api_key"], "existing key preserved when not rotating")
+}
+
+// TestModelUpdate_RotateKeyAndBaseURL: --api-key-stdin + --base-url overlay the
+// parameters map; the new key comes from stdin, never argv.
+func TestModelUpdate_RotateKeyAndBaseURL(t *testing.T) {
+	_, _ = iostreams.SetForTest(t)
+	svc := &fakeUpdateSvc{cur: baseModel()}
+	opts := &UpdateOptions{
+		BaseURL: "http://new", APIKeyStdin: true,
+		StdinReader: strings.NewReader("NEW-KEY\n"),
+		flags:       modelUpdateFlags{baseURL: true},
+	}
+	require.NoError(t, runUpdate(context.Background(), opts, &cmdutil.FormatOptions{Mode: cmdutil.FormatJSON}, svc, "mdl_x", nil))
+	assert.Equal(t, "http://new", svc.gotReq.Parameters["base_url"])
+	assert.Equal(t, "NEW-KEY", svc.gotReq.Parameters["api_key"], "rotated key read from stdin")
+}
+
+// TestModelUpdate_RequiresAtLeastOneFlag: a bare `model update <id>` is rejected
+// before any network call, matching agent update.
+func TestModelUpdate_RequiresAtLeastOneFlag(t *testing.T) {
+	assert.False(t, modelUpdateHasFlag(&UpdateOptions{}))
+	assert.True(t, modelUpdateHasFlag(&UpdateOptions{flags: modelUpdateFlags{displayName: true}}))
+	assert.True(t, modelUpdateHasFlag(&UpdateOptions{APIKeyStdin: true}))
+	assert.True(t, modelUpdateHasFlag(&UpdateOptions{Params: []string{"k=v"}}))
+}