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.
This commit is contained in:
@@ -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)
|
||||
Reference in New Issue
Block a user