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
+18 -4
View File
@@ -30,15 +30,29 @@ func WriteBatchEnvelope(w io.Writer, items []BatchItem, indent bool, profile str
}
}
env := Envelope{
OK: failures == 0,
Data: items,
OK: failures == 0,
Status: batchStatus(successes, failures),
Data: items,
Meta: &Meta{
Count: len(items),
Count: IntPtr(len(items)),
Successes: &successes,
Failures: &failures,
},
Notice: GetNotice(),
Profile: profile,
}
return writeJSON(w, env, indent)
}
// batchStatus maps the (successes, failures) counts to the tri-state envelope
// status: "success" when no failures, "error" when no successes, "partial"
// when both occur.
func batchStatus(successes, failures int) string {
switch {
case failures == 0:
return "success"
case successes == 0:
return "error"
default:
return "partial"
}
}
+47
View File
@@ -74,6 +74,53 @@ func TestWriteBatchEnvelope_EmptyItems_EmitsEmptyArray(t *testing.T) {
}
}
// TestWriteBatchEnvelope_StatusTriState verifies the additive tri-state
// envelope.status: "success" (all ok), "partial" (mixed), "error" (all fail).
func TestWriteBatchEnvelope_StatusTriState(t *testing.T) {
cases := []struct {
name string
items []output.BatchItem
status string
}{
{
name: "all_success",
items: []output.BatchItem{
{ID: "a", OK: true}, {ID: "b", OK: true},
},
status: "success",
},
{
name: "partial",
items: []output.BatchItem{
{ID: "a", OK: true},
{ID: "b", OK: false, Error: &output.ErrDetail{Type: "resource.not_found", Message: "missing"}},
},
status: "partial",
},
{
name: "all_fail",
items: []output.BatchItem{
{ID: "a", OK: false, Error: &output.ErrDetail{Type: "auth.forbidden", Message: "no perm"}},
{ID: "b", OK: false, Error: &output.ErrDetail{Type: "resource.not_found", Message: "missing"}},
},
status: "error",
},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
var buf bytes.Buffer
if err := output.WriteBatchEnvelope(&buf, tc.items, false, ""); err != nil {
t.Fatalf("unexpected error: %v", err)
}
got := buf.String()
want := `"status":"` + tc.status + `"`
if !strings.Contains(got, want) {
t.Errorf("expected %s; got %q", want, got)
}
})
}
}
func TestWriteBatchEnvelope_AllFail(t *testing.T) {
items := []output.BatchItem{
{ID: "id1", OK: false, Error: &output.ErrDetail{Type: "auth.forbidden", Message: "no perm"}},
+46 -42
View File
@@ -11,28 +11,35 @@ import (
// Envelope is the success-path stdout envelope. See AGENTS.md
// "Stdout (success path)" for the full wire contract.
type Envelope struct {
OK bool `json:"ok"`
Data any `json:"data,omitempty"`
Meta *Meta `json:"meta,omitempty"`
Notice map[string]any `json:"_notice,omitempty"`
Profile string `json:"profile,omitempty"`
OK bool `json:"ok"`
// Status is the batch tri-state outcome: "success" (all items ok),
// "partial" (some ok, some failed), or "error" (all failed). Set only by
// batch commands; omitted on ordinary single-result envelopes. `ok` stays
// authoritative — Status is an additive convenience for agents triaging
// multi-target results.
Status string `json:"status,omitempty"`
Data any `json:"data,omitempty"`
Meta *Meta `json:"meta,omitempty"`
Profile string `json:"profile,omitempty"`
}
// ErrorEnvelope is the error-path stderr envelope. See AGENTS.md
// "Stderr (error path)" for the full wire contract.
type ErrorEnvelope struct {
OK bool `json:"ok"`
Error *ErrDetail `json:"error"`
Notice map[string]any `json:"_notice,omitempty"`
OK bool `json:"ok"`
Error *ErrDetail `json:"error"`
}
// Meta carries optional metadata in success envelopes.
type Meta struct {
Count int `json:"count,omitempty"`
HasMore bool `json:"has_more,omitempty"`
NextCursor string `json:"next_cursor,omitempty"`
TotalCount int `json:"total_count,omitempty"`
RequestID string `json:"request_id,omitempty"`
// Count and TotalCount are *int so zero is serialized when explicitly set
// by list commands (omitempty on *int omits only nil, not zero). This keeps
// the agent contract stable: an empty list still emits count/total_count as 0
// instead of dropping the key. Non-list / dry-run metas leave them nil so they
// are omitted. Mirrors the Successes/Failures pointer pattern below.
Count *int `json:"count,omitempty"`
HasMore bool `json:"has_more,omitempty"`
TotalCount *int `json:"total_count,omitempty"`
// Successes and Failures are *int so zero is serialized when explicitly set
// by the batch path (omitempty on *int omits only nil, not zero).
// Non-batch commands leave these nil so they are omitted from the envelope.
@@ -47,13 +54,21 @@ type Meta struct {
// ErrDetail describes a structured error. Embedded in ErrorEnvelope.Error
// and also surfaced in batch envelope per-item failures.
type ErrDetail struct {
Type string `json:"type"`
Message string `json:"message"`
Hint string `json:"hint,omitempty"`
RetryCommand string `json:"retry_command,omitempty"`
RetryAfterSeconds int `json:"retry_after_seconds,omitempty"`
Risk *RiskDetail `json:"risk,omitempty"`
Detail any `json:"detail,omitempty"`
Type string `json:"type"`
Message string `json:"message"`
Hint string `json:"hint,omitempty"`
// RetryArgv is a directly-executable argv array (e.g.
// ["weknora","auth","login"]) so an agent can exec it without
// shell-splitting or quote-handling. Distinct from the prose Hint.
RetryArgv []string `json:"retry_argv,omitempty"`
RetryAfterSeconds int `json:"retry_after_seconds,omitempty"`
// Retryable indicates whether re-running the SAME command may succeed:
// true for transient failures (timeouts, rate limits, transport), false
// for deterministic ones (auth, bad input, not-found), omitted (nil) when
// genuinely unknown.
Retryable *bool `json:"retryable,omitempty"`
Risk *RiskDetail `json:"risk,omitempty"`
Detail any `json:"detail,omitempty"`
}
// RiskDetail tags high-risk writes for the agent protocol. Surfaces in
@@ -64,35 +79,20 @@ type RiskDetail struct {
Action string `json:"action"`
}
// PendingNotice, if set, returns system-level notices to inject as the
// "_notice" field on every envelope. Currently nil — Task 4.x deferred
// the registration. Tests may set this directly.
var PendingNotice func() map[string]any
// GetNotice returns the current pending notice. Nil when nothing to report.
func GetNotice() map[string]any {
if PendingNotice == nil {
return nil
}
return PendingNotice()
}
// NewEnvelope assembles a success Envelope with the given data + optional
// meta + profile, injecting the pending _notice automatically. Single source
// of construction so callers that need the envelope value (e.g. jq filtering)
// stay in sync with WriteEnvelope when fields are added.
// meta + profile. Single source of construction so callers that need the
// envelope value (e.g. jq filtering) stay in sync with WriteEnvelope when
// fields are added.
func NewEnvelope(data any, meta *Meta, profile string) Envelope {
return Envelope{
OK: true,
Data: data,
Meta: meta,
Notice: GetNotice(),
Profile: profile,
}
}
// WriteEnvelope writes a success envelope to w. Caller sets data + optional meta;
// notice is injected from GetNotice() automatically.
// WriteEnvelope writes a success envelope to w. Caller sets data + optional meta.
//
// When profile is non-empty, the envelope includes a "profile" field.
// indent: if true, output is multi-line (TTY mode); else compact (pipe mode).
@@ -103,13 +103,17 @@ func WriteEnvelope(w io.Writer, data any, meta *Meta, indent bool, profile strin
// WriteErrorEnvelope writes an error envelope to w (typically stderr).
func WriteErrorEnvelope(w io.Writer, err *ErrDetail, indent bool) error {
env := ErrorEnvelope{
OK: false,
Error: err,
Notice: GetNotice(),
OK: false,
Error: err,
}
return writeJSON(w, env, indent)
}
// IntPtr returns a pointer to i. Used by list commands to set Meta.Count /
// Meta.TotalCount so that a zero count still serializes (omitempty on *int
// omits only nil). Mirrors the Successes/Failures pointer pattern.
func IntPtr(i int) *int { return &i }
func writeJSON(w io.Writer, v any, indent bool) error {
enc := json.NewEncoder(w)
enc.SetEscapeHTML(false)
+30 -25
View File
@@ -40,7 +40,7 @@ func TestWriteEnvelope_OmitDataWhenNil(t *testing.T) {
func TestWriteEnvelope_WithMeta(t *testing.T) {
var buf bytes.Buffer
meta := &output.Meta{Count: 2, HasMore: false}
meta := &output.Meta{Count: output.IntPtr(2), HasMore: false}
if err := output.WriteEnvelope(&buf, []string{"a", "b"}, meta, false, ""); err != nil {
t.Fatalf("unexpected error: %v", err)
}
@@ -51,13 +51,36 @@ func TestWriteEnvelope_WithMeta(t *testing.T) {
}
}
// TestWriteEnvelope_ZeroCountSerializes pins the *int fix: a list command that
// sets Count to 0 (empty result) must still emit "count":0, while a meta that
// leaves Count nil (non-list / dry-run) must omit the key entirely. This is the
// agent-contract guarantee that omitempty on a plain int silently broke.
func TestWriteEnvelope_ZeroCountSerializes(t *testing.T) {
var bufZero bytes.Buffer
zero := &output.Meta{Count: output.IntPtr(0)}
if err := output.WriteEnvelope(&bufZero, []string{}, zero, false, ""); err != nil {
t.Fatalf("unexpected error: %v", err)
}
if gotZero := bufZero.String(); !strings.Contains(gotZero, `"count":0`) {
t.Errorf("explicit zero count must serialize; got %q", gotZero)
}
var bufNil bytes.Buffer
if err := output.WriteEnvelope(&bufNil, []string{}, &output.Meta{}, false, ""); err != nil {
t.Fatalf("unexpected error: %v", err)
}
if gotNil := bufNil.String(); strings.Contains(gotNil, "count") {
t.Errorf("nil count must be omitted; got %q", gotNil)
}
}
func TestWriteErrorEnvelope_FullShape(t *testing.T) {
var buf bytes.Buffer
errDetail := &output.ErrDetail{
Type: "input.confirmation_required",
Message: "kb delete kb_x requires confirmation",
Hint: "re-run with -y/--yes",
RetryCommand: "weknora kb delete kb_x -y",
Type: "input.confirmation_required",
Message: "kb delete kb_x requires confirmation",
Hint: "re-run with -y/--yes",
RetryArgv: []string{"weknora", "kb", "delete", "kb_x", "-y"},
Risk: &output.RiskDetail{
Level: "destructive",
Action: "kb.delete",
@@ -73,8 +96,8 @@ func TestWriteErrorEnvelope_FullShape(t *testing.T) {
if !strings.Contains(got, `"type":"input.confirmation_required"`) {
t.Errorf("missing typed code; got %q", got)
}
if !strings.Contains(got, `"retry_command":"weknora kb delete kb_x -y"`) {
t.Errorf("missing retry_command; got %q", got)
if !strings.Contains(got, `"retry_argv":["weknora","kb","delete","kb_x","-y"]`) {
t.Errorf("missing retry_argv; got %q", got)
}
if !strings.Contains(got, `"risk":{"level":"destructive","action":"kb.delete"}`) {
t.Errorf("missing risk; got %q", got)
@@ -91,21 +114,3 @@ func TestWriteEnvelope_IndentedTTYMode(t *testing.T) {
t.Errorf("expected indented multi-line output; got %q", got)
}
}
func TestGetNotice_NilSafe(t *testing.T) {
output.PendingNotice = nil
if got := output.GetNotice(); got != nil {
t.Errorf("GetNotice with nil PendingNotice should return nil; got %v", got)
}
}
func TestGetNotice_WithSetter(t *testing.T) {
output.PendingNotice = func() map[string]any {
return map[string]any{"deprecation": "foo is deprecated"}
}
defer func() { output.PendingNotice = nil }()
got := output.GetNotice()
if got["deprecation"] != "foo is deprecated" {
t.Errorf("notice not populated; got %v", got)
}
}