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
+51 -22
View File
@@ -4,6 +4,7 @@ import (
"errors"
"fmt"
"io"
"strings"
"github.com/Tencent/WeKnora/cli/internal/output"
)
@@ -93,7 +94,7 @@ func ExitCode(err error) int {
// PrintError writes err to w (typically stderr) in dual mode:
// - text: code: msg\nhint: ...\nretry: ...
// - json/ndjson: {ok:false, error:{...}, _notice?:...}
// - json/ndjson: {ok:false, error:{...}}
//
// Mode is read from globalFormatMode (set by root PersistentPreRunE).
func PrintError(w io.Writer, err error) {
@@ -126,12 +127,12 @@ func printErrorProse(w io.Writer, err error) {
if hint != "" {
fmt.Fprintf(w, "hint: %s\n", hint)
}
retry := typed.RetryCommand
if retry == "" {
retry = defaultRetryCommand(typed.Code)
retry := typed.RetryArgv
if len(retry) == 0 {
retry = defaultRetryArgv(typed.Code)
}
if retry != "" {
fmt.Fprintf(w, "retry: %s\n", retry)
if len(retry) > 0 {
fmt.Fprintf(w, "retry: %s\n", strings.Join(retry, " "))
}
}
}
@@ -198,30 +199,58 @@ func defaultHint(code ErrorCode) string {
return ""
}
// defaultRetryCommand returns canonical retry argv for known codes.
// Empty string for codes without a stable canonical retry.
// defaultRetryArgv returns canonical retry argv for known codes.
// nil for codes without a stable canonical retry.
// Symmetric counterpart to defaultHint.
func defaultRetryCommand(code ErrorCode) string {
func defaultRetryArgv(code ErrorCode) []string {
switch code {
case CodeAuthUnauthenticated, CodeAuthBadCredential, CodeAuthTokenExpired:
return "weknora auth login"
return []string{"weknora", "auth", "login"}
case CodeKBIDRequired:
return "weknora link"
return []string{"weknora", "link"}
case CodeNetworkError, CodeServerTimeout:
return "weknora doctor"
return []string{"weknora", "doctor"}
case CodeProjectLinkCorrupt:
return "weknora link" // re-bind the project to a KB
return []string{"weknora", "link"} // re-bind the project to a KB
case CodeLocalConfigCorrupt:
// Recovery is two steps (delete config + re-login); the prose hint
// already spells it out, so the retry argv stays empty.
return ""
// already spells it out, so the retry argv stays nil.
return nil
}
return ""
return nil
}
// DefaultHint and DefaultRetryCommand are exported wrappers so that
// cross-package callers (MCP handlers, batch envelope helpers) can
// resolve hint/retry without duplicating the typed-code → string table.
// Avoids drift between cmdutil and copies elsewhere.
func DefaultHint(code ErrorCode) string { return defaultHint(code) }
func DefaultRetryCommand(code ErrorCode) string { return defaultRetryCommand(code) }
// boolPtr returns a pointer to b. Used by retryableForCode so the *bool can
// distinguish true / false / unknown(nil) on the wire.
func boolPtr(b bool) *bool { return &b }
// retryableForCode classifies whether re-running the SAME command may succeed.
// Pointer-to-true for transient failures, pointer-to-false for deterministic
// ones, nil (omitted) when genuinely unknown — notably CodeInternalError and
// any unlisted code (do NOT default to false).
func retryableForCode(code ErrorCode) *bool {
switch code {
// Transient — retrying the same command may succeed.
case CodeServerRateLimited, CodeServerTimeout, CodeNetworkError,
CodeOperationTimeout, CodeSSEStreamAborted:
return boolPtr(true)
// CodeServerError (generic 500) is deliberately NOT here: a 500 may be a
// transient server hiccup OR a deterministic server-side bug / mislabeled
// bad request, so blindly retrying risks a loop. Left unlisted → nil
// (unknown), so the agent decides rather than reading an optimistic true.
// Deterministic — same command will fail the same way.
case CodeAuthUnauthenticated, CodeAuthTokenExpired, CodeAuthBadCredential,
CodeAuthForbidden, CodeAuthCrossTenantBlocked, CodeAuthTenantMismatch,
CodeInputInvalidArgument, CodeInputMissingFlag,
CodeInputConfirmationRequired, CodeInputUnknownSubcommand,
CodeResourceNotFound, CodeResourceAlreadyExists, CodeResourceLocked,
CodeOperationFailed, CodeOperationCancelled, CodeUserAborted,
CodeUploadFileNotFound, CodeKBIDRequired, CodeKBNotFound,
CodeProjectLinkCorrupt, CodeLocalConfigCorrupt, CodeLocalKeychainDenied,
CodeLocalFileIO, CodeLocalProfileNotFound, CodeSessionCreateFailed,
CodeServerIncompatibleVersion:
return boolPtr(false)
}
// CodeInternalError and any unlisted code: genuinely unknown → omit.
return nil
}