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
+22 -13
View File
@@ -77,6 +77,13 @@ const (
// contexts so the user-visible exit follows Unix signal convention.
CodeOperationCancelled ErrorCode = "operation.cancelled"
// CodeInternalError is the catch-all for an error that reached the top
// without a typed code (a bug, or an unmapped dependency error). Maps to
// exit 1 via the fall-through bucket. Documented so the type is never a
// surprise on the wire; a recurring internal.error is a classification gap
// worth fixing at the source.
CodeInternalError ErrorCode = "internal.error"
// local.* - config / file / keychain on the user's machine
CodeLocalConfigCorrupt ErrorCode = "local.config_corrupt"
CodeLocalKeychainDenied ErrorCode = "local.keychain_denied"
@@ -117,8 +124,8 @@ type Error struct {
// own output (e.g. bulk operations reporting partial-success data on
// stdout) but still need to surface a non-zero exit code.
Silent bool
RetryCommand string // Directly-executable argv, distinct from prose Hint
RetryAfterSeconds int // HTTP Retry-After header semantics (transport-level retry hint)
RetryArgv []string // Directly-executable argv array, distinct from prose Hint
RetryAfterSeconds int // HTTP Retry-After header semantics (transport-level retry hint)
Detail any // Structured detail for envelope.error.detail (e.g. unknown-subcommand available[])
Risk *RiskInfo
}
@@ -148,11 +155,11 @@ func (e *Error) WithHint(hint string) *Error {
return e
}
// WithRetryCommand sets the directly-executable retry argv string so agents
// don't have to regex-extract argv from the prose Hint.
// Empty string for codes without a canonical retry command.
func (e *Error) WithRetryCommand(cmd string) *Error {
e.RetryCommand = cmd
// WithRetryArgv sets the directly-executable retry argv array so agents can
// exec it directly instead of regex-extracting argv from the prose Hint.
// Empty for codes without a canonical retry command.
func (e *Error) WithRetryArgv(argv []string) *Error {
e.RetryArgv = argv
return e
}
@@ -194,8 +201,8 @@ func AsError(err error) *Error {
// ErrorToDetail converts a typed cmdutil.Error (or fallback) into
// output.ErrDetail for embedding in success-envelope batch items or
// MCP CallToolResult StructuredContent. Hint / RetryCommand fall back
// to defaultHint / defaultRetryCommand when typed value is empty.
// MCP CallToolResult StructuredContent. Hint / RetryArgv fall back
// to defaultHint / defaultRetryArgv when typed value is empty.
// Returns nil when err is nil.
func ErrorToDetail(err error) *output.ErrDetail {
if err == nil {
@@ -206,9 +213,9 @@ func ErrorToDetail(err error) *output.ErrDetail {
if hint == "" {
hint = defaultHint(typed.Code)
}
retry := typed.RetryCommand
if retry == "" {
retry = defaultRetryCommand(typed.Code)
retry := typed.RetryArgv
if len(retry) == 0 {
retry = defaultRetryArgv(typed.Code)
}
// Build message without the code prefix — the envelope's separate
// "type" field already carries the code, so repeating it in "message"
@@ -222,7 +229,7 @@ func ErrorToDetail(err error) *output.ErrDetail {
Type: string(typed.Code),
Message: msg,
Hint: hint,
RetryCommand: retry,
RetryArgv: retry,
RetryAfterSeconds: typed.RetryAfterSeconds,
Detail: typed.Detail,
}
@@ -439,6 +446,8 @@ func AllCodes() []ErrorCode {
CodeSSEStreamAborted, CodeSessionCreateFailed,
// operation
CodeOperationTimeout, CodeOperationFailed, CodeOperationCancelled,
// internal catch-all
CodeInternalError,
}
}