feat(cli): agent-first WeKnora CLI

The `weknora` command-line client for the WeKnora RAG server. Full command
surface: kb / doc / chunk / session / message / agent / model / search / chat /
auth / profile / link / api / mcp / skills / config / doctor / schema /
exit-codes.

Agent-first wire contract: JSON envelope by default, typed error codes mapped to
stable exit codes, error.retry_argv / retryable / partial-failure status,
global --dry-run preview, the exit-10 confirmation protocol for writes, and
control/ANSI/Bidi input hygiene. Stateless env-credential auth
(WEKNORA_API_KEY / WEKNORA_TOKEN + WEKNORA_HOST) for headless/CI/agent use.
A curated read-only MCP tool surface (`mcp serve`) and embedded Agent Skills
(`skills install`). Extensive unit + contract-golden tests and CI.
This commit is contained in:
nullkey
2026-06-26 20:40:59 +08:00
committed by lyingbug
parent 445a4330fa
commit 6f8b825f5f
151 changed files with 7305 additions and 733 deletions
+1 -1
View File
@@ -74,7 +74,7 @@ func runList(fopts *cmdutil.FormatOptions, f *cmdutil.Factory) error {
sort.Slice(entries, func(i, j int) bool { return entries[i].Name < entries[j].Name })
if fopts.WantsJSON() {
meta := &output.Meta{Count: len(entries)}
meta := &output.Meta{Count: output.IntPtr(len(entries))}
return fopts.Emit(iostreams.IO.Out, entries, meta)
}
if len(entries) == 0 {
+8 -5
View File
@@ -20,7 +20,7 @@ import (
// keyring; agents who need to verify the credential should re-run
// `auth status`.
var authLoginFields = []string{
"profile", "host", "mode", "user", "tenant_id",
"profile", "host", "mode", "email", "tenant_id",
}
// LoginOptions is the configuration captured from flags + prompts. Host and
@@ -104,7 +104,7 @@ Credentials are persisted to the OS keyring when available; otherwise to a
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
UsedFor: "authenticate the active profile; --with-token reads an API key from stdin (non-interactive)",
Examples: []string{`echo "$WEKNORA_API_KEY" | weknora auth login --with-token`},
Output: "envelope.data is {profile, host, mode, user, tenant_id} on success",
Output: "envelope.data is {profile, host, mode, email, tenant_id} on success (email matches `auth status`)",
Warnings: []string{
"a profile must exist and be active first (`weknora profile add <n> --host <url> --use`)",
"password login is interactive-only (no flags) — agents must use --with-token with the key piped to stdin",
@@ -171,7 +171,7 @@ func runLogin(ctx context.Context, opts *LoginOptions, fopts *cmdutil.FormatOpti
}
// Reject shell-metacharacter / path-like names up-front so opts.Profile
// stays safe to interpolate into the keyring namespace, config.yaml
// keys, and (later) envelope.error.retry_command. Matches `profile add`.
// keys, and envelope.error.retry_argv. Matches `profile add`.
if err := cmdutil.ValidateProfileName(opts.Profile); err != nil {
return err
}
@@ -313,7 +313,10 @@ type loginResult struct {
Profile string `json:"profile"`
Host string `json:"host"`
Mode string `json:"mode"` // ModeBearer or ModeAPIKey
User string `json:"user,omitempty"`
// Email is the authenticated principal's email. Named "email" (not
// "user") so the identity field matches `auth status`, which also
// exposes it as `email` — one key for one concept across both commands.
Email string `json:"email,omitempty"`
TenantID uint64 `json:"tenant_id,omitempty"`
}
@@ -344,7 +347,7 @@ func saveProfileRef(opts *LoginOptions, fopts *cmdutil.FormatOptions, f *cmdutil
// user != nil would mislabel it as bearer.
result := loginResult{Profile: opts.Profile, Host: opts.Host, Mode: mode}
if user != nil {
result.User = user.Email
result.Email = user.Email
result.TenantID = user.TenantID
}
return fopts.Emit(iostreams.IO.Out, result, nil)
+3 -2
View File
@@ -92,6 +92,7 @@ accepted until it expires.`,
"weknora --profile staging auth logout",
"weknora auth logout --all",
},
Output: "envelope.data is {removed: [profile names cleared]}",
Warnings: []string{
"Requires explicit user approval (exit 10 / input.confirmation_required); never auto-add -y.",
"auth logout clears local credentials for this profile; server-side session continues until expiry.",
@@ -116,9 +117,9 @@ func runLogout(opts *LogoutOptions, fopts *cmdutil.FormatOptions, f *cmdutil.Fac
// Destructive-write protocol: confirm before clearing credentials.
scope := fmt.Sprintf("%d profile(s) [%s]", len(targets), strings.Join(targets, ", "))
retryCmd := "weknora auth logout -y"
retryCmd := []string{"weknora", "auth", "logout", "-y"}
if opts.All {
retryCmd = "weknora auth logout --all -y"
retryCmd = []string{"weknora", "auth", "logout", "--all", "-y"}
}
if err := cmdutil.ConfirmDestructive(f.Prompter(), opts.Yes, fopts.WantsJSON(), "delete", "auth credentials", scope, "auth.logout", retryCmd); err != nil {
return err
+26 -9
View File
@@ -3,6 +3,8 @@ package auth
import (
"context"
"fmt"
"os"
"strings"
"github.com/spf13/cobra"
@@ -14,7 +16,7 @@ import (
// authStatusFields enumerates the fields surfaced for `--format json` discovery
// on `auth status`. Single-resource shape: filter applies to data itself.
var authStatusFields = []string{
"profile", "user_id", "username", "email", "is_active",
"profile", "host", "auth_source", "user_id", "username", "email", "is_active",
"can_access_all_tenants", "tenant_id", "tenant_name",
}
@@ -29,6 +31,8 @@ type StatusService interface {
// account) without a second round-trip.
type statusResult struct {
Profile string `json:"profile"`
Host string `json:"host,omitempty"`
AuthSource string `json:"auth_source,omitempty"`
UserID string `json:"user_id,omitempty"`
Username string `json:"username,omitempty"`
Email string `json:"email,omitempty"`
@@ -68,7 +72,7 @@ usually only surfaces a hard auth failure.`,
cmdutil.SetAgentHelp(cmd, cmdutil.AgentHelp{
UsedFor: "show the active profile, the authenticated principal, and token state",
Examples: []string{"weknora auth status", "weknora auth status --jq .data.tenant_id"},
Output: "envelope.data is {profile, host, user, tenant, ...}; exit 3 if unauthenticated",
Output: "envelope.data is {profile, host, auth_source, user_id, username, email, tenant_id, tenant_name, ...}; auth_source is 'profile + keyring' or a stateless env credential; exit 3 if unauthenticated",
})
return cmd
}
@@ -89,8 +93,24 @@ func runStatus(ctx context.Context, fopts *cmdutil.FormatOptions, f *cmdutil.Fac
return err
}
// Effective host + auth source. Stateless env credentials
// (WEKNORA_TOKEN/WEKNORA_API_KEY) override the profile + keyring for the
// client, so report the host they authenticate against (WEKNORA_HOST) and
// that they are in effect — not the bypassed config profile's host.
host := ""
if c, ok := cfg.Profiles[cfg.CurrentProfile]; ok {
host = c.Host
}
authSource := "profile + keyring"
if active, kind := cmdutil.EnvCredential(); active {
authSource = kind + " env (stateless)"
if h := strings.TrimSpace(os.Getenv("WEKNORA_HOST")); h != "" {
host = h
}
}
if fopts.WantsJSON() {
result := statusResult{Profile: cfg.CurrentProfile}
result := statusResult{Profile: cfg.CurrentProfile, Host: host, AuthSource: authSource}
if user != nil {
result.UserID = user.ID
result.Username = user.Username
@@ -105,12 +125,9 @@ func runStatus(ctx context.Context, fopts *cmdutil.FormatOptions, f *cmdutil.Fac
return fopts.Emit(iostreams.IO.Out, result, nil)
}
host := ""
if c, ok := cfg.Profiles[cfg.CurrentProfile]; ok {
host = c.Host
}
fmt.Fprintf(iostreams.IO.Out, "profile: %s\n", cfg.CurrentProfile)
fmt.Fprintf(iostreams.IO.Out, "host: %s\n", host)
fmt.Fprintf(iostreams.IO.Out, "profile: %s\n", cfg.CurrentProfile)
fmt.Fprintf(iostreams.IO.Out, "auth_source: %s\n", authSource)
fmt.Fprintf(iostreams.IO.Out, "host: %s\n", host)
if user != nil {
fmt.Fprintf(iostreams.IO.Out, "user: %s (%s)\n", user.Email, user.ID)
fmt.Fprintf(iostreams.IO.Out, "tenant: %d", user.TenantID)
+3 -2
View File
@@ -54,8 +54,9 @@ func TestRunStatus_TextOutput(t *testing.T) {
}
require.NoError(t, runStatus(context.Background(), &cmdutil.FormatOptions{Mode: cmdutil.FormatText}, f, svc))
got := out.String()
assert.Contains(t, got, "profile: prod")
assert.Contains(t, got, "host: https://kb.example.com")
assert.Contains(t, got, "profile: prod")
assert.Contains(t, got, "auth_source: profile + keyring")
assert.Contains(t, got, "host: https://kb.example.com")
assert.Contains(t, got, "alice@example.com")
assert.Contains(t, got, "Acme")
}
+4 -4
View File
@@ -57,9 +57,9 @@ to see which mode each profile uses, and construct the matching HTTP header:
}
// `auth token` is a scalar scripting helper (WEKNORA_TOKEN=$(...)),
// so it defaults to the raw token — overriding the global json
// default (gh auth token does the same; cf. doc download streaming
// raw bytes). Explicit --format json / WEKNORA_FORMAT=json still
// emit the {token,mode,profile} envelope.
// default, the same way `doc download` streams raw bytes. Explicit
// --format json / WEKNORA_FORMAT=json still emit the
// {token,mode,profile} envelope.
fopts.FromEnv()
if fopts.Mode == "" {
// --jq implies JSON (it filters the envelope); without it,
@@ -83,7 +83,7 @@ to see which mode each profile uses, and construct the matching HTTP header:
},
Output: "raw token on stdout (no envelope, no trailing newline) by default; --format json emits {token, mode, profile}",
Warnings: []string{
"default output is the bare token, NOT the JSON envelope — it is a scripting helper (cf. `gh auth token`)",
"default output is the bare token, NOT the JSON envelope — it is a scripting helper for shell capture",
},
})
return cmd